WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

Properties of Message

An overview of the properties of the Message object, with links to more detailed reference information.

Table 1. Properties of Message
Name of property Description
JMS_IBM_ArmCorrelator The Open Group Application Response Measurement Correlator property, set on a message. This IBM-defined property associates a unique Id with the application data in the message. Use JMS_TOG_ARM_Correlator in preference to this property.
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 will be 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 will be 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 of 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 that 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 that 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.
JMS_TOG_ARM_Correlator The Open Group Application Response Measurement Correlator property, set on a message. Associates a unique Id with the application data in the message.
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 C/C++ 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 above 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 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 WMQ_MQMD_MESSAGE_CONTEXT to an appropriate value, the property value is ignored. If you set 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 WMQ_MQMD_MESSAGE_CONTEXT are as follows.

The following properties require WMQ_MQMD_MESSAGE_CONTEXT to be set to WMQ_MDCTX_SET_IDENTITY_CONTEXT or WMQ_MDCTX_SET_ALL_CONTEXT:
  • JMS_IBM_MQMD_UserIdentifier
  • JMS_IBM_MQMD_AccountingToken
  • JMS_IBM_MQMD_ApplIdentityData
The following properties require WMQ_MQMD_MESSAGE_CONTEXT to be set to WMQ_MDCTX_SET_ALL_CONTEXT:
  • JMS_IBM_MQMD_PutApplType
  • JMS_IBM_MQMD_PutApplName
  • JMS_IBM_MQMD_PutDate
  • JMS_IBM_MQMD_PutTime
  • JMS_IBM_MQMD_ApplOriginData

Receiving messages

All these properties are available on a received message if WMQ_MQMD_READ_ENABLED property is set to true, irrespective of the actual properties the producing application has set. An application cannot modify the properties of a received message unless all properties are cleared first, according to the JMS specification. The received message can be forwarded without modifying the properties.
Note: If your application receives a message from a destination with WMQ_MQMD_READ_ENABLED property set to true, and forwards it to a destination with WMQ_MQMD_WRITE_ENABLED set to true, this results in all the MQMD field values of the received message being copied into the forwarded message. Table of properties
Table 2. Properties of the Message object representing the MQMD fields
Property Description Type
JMS_IBM_MQMD_REPORT Options for report messages xmsINT
JMS_IBM_MQMD_MSGTYPE Message type xmsINT
JMS_IBM_MQMD_EXPIRY message lifetime xmsINT
JMS_IBM_MQMD_FEEDBACK Feedback or reason code xmsINT
JMS_IBM_MQMD_ENCODING Numeric encoding of message data xmsINT
JMS_IBM_MQMD_CODEDCHARSETID Character set identifier of message data xmsINT
JMS_IBM_MQMD_FORMAT Format name of message data 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 violates the JMS specification.
Message priority xmsINT
JMS_IBM_MQMD_PERSISTENCE Message persistence xmsINT
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 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 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 xmsINT
JMS_IBM_MQMD_REPLYTOQ Name of reply queue String
JMS_IBM_MQMD_REPLYTOQMGR Name of reply queue manager String
JMS_IBM_MQMD_USERIDENTIFIER User identifier 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 String
JMS_IBM_MQMD_PUTAPPLTYPE Type of application that put the message xmsINT
JMS_IBM_MQMD_PUTAPPLNAME Name of the application that put the message String
JMS_IBM_MQMD_PUTDATE Date when message was put String
JMS_IBM_MQMD_PUTTIME Time when message was put String
JMS_IBM_MQMD_APPLORIGINDATA Application data relating to origin 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 xmsINT
JMS_IBM_MQMD_OFFSET Offset of data in physical message from start of logical message xmsINT
JMS_IBM_MQMD_MSGFLAGS Message flags xmsINT
JMS_IBM_MQMD_ORIGINALLENGTH Length of original message xmsINT

For further details on MQMD please refer WebSphere MQ v7.0 Application Programming Reference.

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
  String value = rcvMsg.getStringProperty(JMS_IBM_MQMD_APPLIDENTITYDATA);

Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.