Properties of Message

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

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.

Send 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, we 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 we 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 we 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

The following properties require XMSC_WMQ_MQMD_MESSAGE_CONTEXT to be set to XMSC_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

Receive messages

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, we 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 required MQMD field value using a property
  System.String value = rcvMsg.getStringProperty(JMS_IBM_MQMD_APPLIDENTITYDATA);