JMS and MQ Message Properties

Document ID : KB000048531
Last Modified Date : 14/02/2018
Show Technical Document Details

JMS Message Properties

Figure 1

The following properties can be set directly by the client:

  • JMSCorrelationID: Any string value.
  • JMSType: Any string value.
  • JMSDeliveryMode: 1 for persistent, or 2 for non-persistent. Note that this is both a JMS message property and an argument to the MessageProducer.send() method. LISA will set it in both places.
  • JMSPriority: Any integer value between 0 and 9. Note that this is both a JMS message property and an argument to the MessageProducer.send() method. LISA will set it in both places.
  • JMSTimeToLive: The time in milliseconds that the JMS provider will wait to deliver the message before discarding it. This is not actually a JMS message property. It is an argument used by the MessageProducer.send() method to set JMSExpiration.

The following properties are not set directly by the client. They are provided mainly for completeness, or if the client is using a non-compliant JMS provider that allows the setting of these values.

  • JMSMessageID: The identifier for the message. The JMS specification dictates that the JMS provider set this value when the message is published
  • JMSRedelivered: A flag describing whether the message has been delivered more than once due to a retry policy. The JMS specification dictates that the JMS provider sets this value when the message is redelivered.
  • JMSTimestamp: The timestamp, in milliseconds since Epoch, at which the message was published. The JMS specification dictates that the JMS provider set this when the message is published.
  • JMSExpiration: The timestamp, in milliseconds since Epoch, after which the message will be discarded if it is not delivered. This property is set indirectly by adding JMSTimeToLive to JMSTimestamp.

For more information see the Javadocs for the JMS API:

  • javax.jms.Message
  • javax.jms.MessageProducer

MQ Message Properties

As of LISA 5.0.23 all MQ message properties can be set using the Message Properties dialog of the MQ step. However, some of these properties have special requirements before they can be set without the MQ platform overriding them with defaults.

Properties that can always be set

The following properties can be set at any time, and they will always take effect. Note that many of these are integer properties with a finite set of valid values. Most of them will simply be reset to their default if you try and send an invalid value.

messageId

A string of up to 24 characters or a {{...}} property containing a byte array of no more than 24 bytes.

correlationId

A string of up to 24 characters or a {{...}} property containing a byte array of no more than 24 bytes.

format

A string of up to 8 characters. This can be any string, but there are a few standard ones defined by MQ. The most common is "MQSTR" (MQC.MQFMT_STRING).

messageType

A free integer field. This can be any 32-bit integer, but there are a few standard ones defined by MQ.

Code

Name

1

MCQ.MQMT_REQUEST

2

MCQ.MQMT_REPLY

4

MCQ.MQMT_REPORT

8

MCQ.MQMT_DATAGRAM

User-defined message types start at 65536.

expiry

An integer field giving the number of milliseconds the message should sit on the queue without being picked up before it is discarded. If left at the default then the message does not expire.

messageFlags

This is an integer field that mostly relates to message grouping and segmentation. It's a bitmask field, meaning any number of these MQ defined values can be added together into one message.

Code

Name

1

MCQ.MQMF_SEGMENTATION_ALLOWED

2

MCQ.MQMF_SEGMENT

4

MCQ.MQMF_LAST_SEGMENT

8

MCQ.MQMF_MSG_IN_GROUP

16

MCQ.MQMF_LAST_MSG_IN_GROUP

The default is 0, which disables grouping and segmentation. See the sections below on Grouping properties and Segmentation properties for more information.

characterSet

This defines the character set used to encode a text payload to bytes. Some of the most common values are:

Code

Meaning

819

UTF-8 (default)

39

EBCDIC

500

EBCDIC (alternate)

1047

EBCDIC (alternate)

There are many other possible values. The number itself refers to an IBM or Windows Code Page number.

encoding

This defines the encoding used for numeric data. It is a bitmask, meaning that it's produced by adding several of these values together:

Code

Meaning

1

MQC.MQENC_INTEGER_NORMAL

2

MQC.MQENC_INTEGER_REVERSED

16

MQC.MQENC_DECIMAL_NORMAL

32

MQC.MQENC_DECIMAL_REVERSED

256

MQC.MQENC_FLOAT_IEEE_NORMAL

512

MQC.MQENC_FLOAT_IEEE_REVERSED

1024

MQC.MQENC_FLOAT_TNS

The default value is 273 (MQENC_INTEGER_NORMAL + MQENC_DECIMAL_NORMAL + MQENC_FLOAT_IEEE_NORMAL).

feedback

This property is used when the message is a Report message, with message type 4 (MQC.MQMT_REPORT). It gives the nature of the report. There are several dozen possible values in MQC.MQFB_* and MQC.MQRC_*.

report

This property is used on a normal message to request that a report message be sent in response. There are several dozen possible values in MQC.MQRO_*. If this property is given then the message must also have a Reply To or Temp Queue defined with which to receive the report response.

priority

This defines the priority of the message. Generally, higher priority messages are delivered before lower priority messages. The maximum value for priority is defined by the Queue Manager.

persistence

This defines whether the message is persisted when the MQ server is restarted.

Code

Meaning

0

MQC.MQPER_NOT_PERSISTENT

1

MQC.MQPER_PERSISTENT

2

MQC.MQPER_PERSISTENCE_AS_Q_DEF

Grouping properties

The following properties can only be set if messageFlags contains 8 (MQC.MQMF_MSG_IN_GROUP) or 16 (MQC.MQMF_LAST_MSG_IN_GROUP). If messageFlags does not contain one of those flags then the value of these properties will be automatically reset by MQ.

groupId

A string of up to 24 characters or a {{...}} property containing a byte array of no more than 24 bytes.

messageSequenceNumber

The sequence number of the message in the group.

Segmentation properties

The following properties can only be set if messageFlags contains 2 (MQC.MQMF_SEGMENT) or 4 (MQC.MQMF_LAST_SEGMENT). If messageFlags does not contain one of those flags then the value of these properties will be automatically reset by MQ.

originalLength

The original size of the unsegmented message body.

offset

The offset of the data in the current message related to the start of the unsegmented message body.

Identity Context properties

The following properties can only be set by opening the queue with the open option MQC.MQOO_SET_IDENTITY_CONTEXT and sending the message with the put option MQC.MQPMO_SET_IDENTITY_CONTEXT. LISA will automatically add those options when you specify one of these properties.

Note: If you specify one of these properties without specifying the other two then their values in the resulting message will be blank.

accountingToken

A string of up to 32 characters or a {{...}} property containing a byte array of no more than 32 bytes.

applicationIdData

A free text field.

userId

A free text field.

Origin Context properties

The following properties can only be set by opening the queue with the open option MQC.MQOO_SET_ALL_CONTEXT and sending the message with the put option MQC.MQPMO_SET_ALL_CONTEXT. LISA will now automatically add those options when you specify one of these properties. Note that this includes the above three properties in the Identity Context group as well as the following four properties.

Note: If you specify one of these properties without specifying the other three, plus the three Identity Context properties above, then theirvalues in the resulting message will be blank.

applicationOriginData

A free text field.

putApplicationName

A free text field.

putApplicationType

This defined the application platform. Some common values are:

Code

Meaning

6

MQC.MQAT_UNIX

9

MQC.MQAT_WINDOWS

28

MQC.MQAT_JAVA

putDateTime

This must contain a {{...}} reference to a property containing either a java.util.Date object or a java.util.GregorianCalendar object.

Unsettable properties

The following property can not be set when sending a message, ever. It is exclusively set by the MQ platform when resending messages, and is always ignored when sending a message. It appears on the list for completeness sake. However, LISA will emit a warning log message if the user tries to set this.

backoutCount