Properties of Message
An overview of the properties of the Message object, with links to more detailed reference information.
Name of property | Description |
---|---|
JMS_IBM_CHARACTER_SET | The identifier (CCSID) of the coded character set, or code page, that the strings of character data in the body of the message is in when the XMS client forwards the message to its intended destination. In XMS this property has a numeric value and maps to CCSID. However, this property is based on a JMS property so has a string type value and maps to the Java character set that represents this numeric CCSID. |
JMS_IBM_ENCODING | How numerical data in the body of the message is represented when the XMS client forwards the message to its intended destination. |
JMS_IBM_EXCEPTIONMESSAGE | Text that describes why the message was sent to the exception destination. This property is read-only. |
JMS_IBM_EXCEPTIONPROBLEMDESTINATION | The name of the destination that the message was at before the message was sent to the exception destination. |
JMS_IBM_EXCEPTIONREASON | A reason code indicating the reason why the message was sent to the exception destination. |
JMS_IBM_EXCEPTIONTIMESTAMP | The time when the message was sent to the exception destination. |
JMS_IBM_FEEDBACK | A code that indicates the nature of a report message. |
JMS_IBM_FORMAT | The nature the application data in the message. |
JMS_IBM_LAST_MSG_IN_GROUP | Indicate whether the message is the last message in a message group. |
JMS_IBM_MSGTYPE | The type of the message. |
JMS_IBM_PUTAPPLTYPE | The type of application that sent the message. |
JMS_IBM_PUTDATE | The date when the message was sent. |
JMS_IBM_PUTTIME | The time when the message was sent. |
JMS_IBM_REPORT_COA | Request 'confirm on arrival' report messages, specifying how much application data from the original message must be included in a report message. |
JMS_IBM_REPORT_COD | Request 'confirm on delivery' report messages, specifying how much application data from the original message must be included in a report message. |
JMS_IBM_REPORT_DISCARD_MSG | Request that the message is discarded if it cannot be delivered to its intended destination. |
JMS_IBM_REPORT_EXCEPTION | Request exception report messages, specifying how much application data from the original message must be included in a report message. |
JMS_IBM_REPORT_EXPIRATION | Request expiration report messages, specifying how much application data from the original message must be included in a report message. |
JMS_IBM_REPORT_NAN | Request negative action notification report messages. |
JMS_IBM_REPORT_PAN | Request positive action notification report messages. |
JMS_IBM_REPORT_PASS_CORREL_ID | Request that the correlation identifier of any report or reply message is the same as the correlation identifier of the original message. |
JMS_IBM_REPORT_PASS_MSG_ID | Request that the message identifier of any report or reply message is the same as the message identifier of the original message. |
JMS_IBM_RETAIN | Setting this property indicates to the queue manager to treat a message as Retained Publication. |
JMS_IBM_SYSTEM_MESSAGEID | An identifier that identifies the message uniquely within the service integration bus. This property is read-only. |
JMSX_APPID | The name of the application that sent the message. |
JMSX_DELIVERY_COUNT | The number of attempts to deliver the message. |
JMSX_GROUPID | The identifier of the message group to which the message belongs. |
JMSX_GROUPSEQ | The sequence number of the message within a message group. |
JMSX_USERID | The user identifier associated with the application that sent the message. |
JMS_IBM_MQMD* properties
IBM® Message Service Client for .NET enables client applications to read/write MQMD fields using APIs. It also allows access to MQ message data. By default access to MQMD is disabled and must be enabled explicitly by the application using Destination properties XMSC_WMQ_MQMD_WRITE_ENABLED and XMSC_WMQ_MQMD_READ_ENABLED. These two properties are independent of each other.
All MQMD fields except StrucId and Version are exposed as additional Message object properties and are prefixed JMS_IBM_MQMD.
JMS_IBM_MQMD* properties take higher precedence over other properties like JMS_IBM* described in the previous table.
Sending messages
All MQMD fields except StrucId and Version are represented. These properties refer only to the MQMD fields; where a property occurs both in the MQMD and in the MQRFH2 header, the version in the MQRFH2 is not set or extracted. Any of these properties can be set, except JMS_IBM_MQMD_BackoutCount. Any value set for JMS_IBM_MQMD_BackoutCount is ignored.
If a property has a maximum length and you supply a value that is too long, the value is truncated.
For certain properties, you must also set the XMSC_WMQ_MQMD_MESSAGE_CONTEXT property on the Destination object. The application must be running with appropriate context authority for this property to take effect. If you do not set XMSC_WMQ_MQMD_MESSAGE_CONTEXT to an appropriate value, the property value is ignored. If you set XMSC_WMQ_MQMD_MESSAGE_CONTEXT to an appropriate value but you do not have sufficient context authority for the queue manager, an exception is issued. Properties requiring specific values of XMSC_WMQ_MQMD_MESSAGE_CONTEXT are as follows.
- JMS_IBM_MQMD_UserIdentifier
- JMS_IBM_MQMD_AccountingToken
- JMS_IBM_MQMD_ApplIdentityData
- JMS_IBM_MQMD_PutApplType
- JMS_IBM_MQMD_PutApplName
- JMS_IBM_MQMD_PutDate
- JMS_IBM_MQMD_PutTime
- JMS_IBM_MQMD_ApplOriginData
Receiving messages
Property | Description | Type |
---|---|---|
JMS_IBM_MQMD_REPORT | Options for report messages | System.Int32 |
JMS_IBM_MQMD_MSGTYPE | Message type | System.Int32 |
JMS_IBM_MQMD_EXPIRY | message lifetime | System.Int32 |
JMS_IBM_MQMD_FEEDBACK | Feedback or reason code | System.Int32 |
JMS_IBM_MQMD_ENCODING | Numeric encoding of message data | System.Int32 |
JMS_IBM_MQMD_CODEDCHARSETID | Character set identifier of message data | System.Int32 |
JMS_IBM_MQMD_FORMAT | Format name of message data | System.String |
JMS_IBM_MQMD_PRIORITY Note: If you assign a value
to JMS_IBM_MQMD_PRIORITY that is not within the range 0-9, this value
violates the JMS specification.
|
Message priority | System.Int32 |
JMS_IBM_MQMD_PERSISTENCE | Message persistence | System.Int32 |
JMS_IBM_MQMD_MSGID Note: The JMS specification
states that the message ID must be set by the JMS provider and that
it must either be unique or null. If you assign a value to JMS_IBM_MQMD_MSGID,
this value is copied to the JMSMessageID. Thus it is not set by the
JMS provider and might not be unique: this value violates the JMS
specification.
|
Message identifier | Byte Array Note: The use of byte array properties
on a message violates the JMS specification.
|
JMS_IBM_MQMD_CORRELID Note: If you assign a value
to JMS_IBM_MQMD_CORRELID that starts with the string 'ID:', this value
violates the JMS specification.
|
Correlation identifier | Byte Array Note: The use of byte array properties
on a message violates the JMS specification.
|
JMS_IBM_MQMD_BACKOUTCOUNT | Backout counter | System.Int32 |
JMS_IBM_MQMD_REPLYTOQ | Name of reply queue | System.String |
JMS_IBM_MQMD_REPLYTOQMGR | Name of reply queue manager | System.String |
JMS_IBM_MQMD_USERIDENTIFIER | User identifier | System.String |
JMS_IBM_MQMD_ACCOUNTINGTOKEN | Accounting token | Byte Array Note: The use of byte array properties
on a message violates the JMS specification.
|
JMS_IBM_MQMD_APPLIDENTITYDATA | Application data relating to identity | System.String |
JMS_IBM_MQMD_PUTAPPLTYPE | Type of application that put the message | System.Int32 |
JMS_IBM_MQMD_PUTAPPLNAME | Name of the application that put the message | System.String |
JMS_IBM_MQMD_PUTDATE | Date when message was put | System.String |
JMS_IBM_MQMD_PUTTIME | Time when message was put | System.String |
JMS_IBM_MQMD_APPLORIGINDATA | Application data relating to origin | System.String |
JMS_IBM_MQMD_GROUPID | Group identifier | Byte Array Note: The use of byte array properties
on a message violates the JMS specification.
|
JMS_IBM_MQMD_MSGSEQNUMBER | Sequence number of local message within group | System.Int32 |
JMS_IBM_MQMD_OFFSET | Offset of data in physical message from start of logical message | System.Int32 |
JMS_IBM_MQMD_MSGFLAGS | Message flags | System.Int32 |
JMS_IBM_MQMD_ORIGINALLENGTH | Length of original message | System.Int32 |
See MQMD for further details.
Examples
This example results in a message being put to a queue or topic with MQMD.UserIdentifier set to "JoeBloggs".
// Create a ConnectionFactory, connection, session, producer, message
// ...
// Create a destination
// ...
// Enable MQMD write
dest.setBooleanProperty(XMSC_WMQ_MQMD_WRITE_ENABLED,
XMSC_WMQ_MQMD_WRITE_ENABLED_YES);
// Optionally, set a message context if applicable for this MD field
dest.setIntProperty(XMSC_WMQ_MQMD_MESSAGE_CONTEXT,
XMSC_WMQ_MDCTX_SET_IDENTITY_CONTEXT);
// On the message, set property to provide custom UserId
msg.setStringProperty(JMS_IBM_MQMD_USERIDENTIFIER, "JoeBloggs");
// Send the message
// ...
It is necessary to set XMSC_WMQ_MQMD_MESSAGE_CONTEXT before setting JMS_IBM_MQMD_USERIDENTIFIER. For more information about the use of XMSC_WMQ_MQMD_MESSAGE_CONTEXT, see Message object properties.
Similarly, you can extract the contents of the MQMD fields by setting XMSC_WMQ_MQMD_READ_ENABLED to true before receiving a message and then using the get methods of the message, such as getStringProperty. Any properties received are read-only.
This example results in the value field holding the value of the MQMD.ApplIdentityData field of a message got from a queue or a topic.
// Create a ConnectionFactory, connection, session, consumer
// ...
// Create a destination
// ...
// Enable MQMD read
dest.setBooleanProperty(XMSC_WMQ_MQMD_READ_ENABLED, XMSC_WMQ_MQMD_READ_ENABLED_YES);
// Receive a message
// ...
// Get desired MQMD field value using a property
System.String value = rcvMsg.getStringProperty(JMS_IBM_MQMD_APPLIDENTITYDATA);