Mapping AMQP fields onto IBM MQ fields (incoming messages)

When the AMQP channel receives a message and puts it to IBM MQ, it propagates some of the attributes of the AMQP message into equivalent IBM MQ message attributes.

The following restrictions apply when mapping an incoming AMQP message:

  • If the message-id or correlation-id field in the properties part is a uuid or a ulong, then the message is rejected.
  • Any message-annotations cause the message to be rejected.
  • delivery-annotations and footer sections are allowed, but are not propagated into the IBM MQ message.

The following sub-sections show the IBM MQ expression of an AMQP message.


Message descriptor

Field Value
StrucId MQMD_STRUC_ID
Version MQMD_VERSION_1
Report MQRO_NONE
MsgType MQMT_DATAGRAM
Expiry Value taken from the ttl field in the AMQP message header
Feedback MQFB_NONE
Encoding MQENC_NORMAL
CodedCharSetId 1208 (UTF-8)
Format See Payload
Priority Value taken from the priority field in the AMQP message header. If set, limited to a maximum of 9. If not set, takes the default value of 4.
Persistence If the durable field in the AMQP message header is set true, set to MQPER_PERSISTENT. Otherwise, set to MQPER_NOT_PERSISTENT.
MagId The queue manager allocates a unique 24-byte MsgId.
Correlld Value taken from the correlation-id field in the AMQP properties, if set. Set to a 24-byte binary value. Otherwise, set to MQCI_NONE/.
BackoutCount 0
ReplyToQ ""
ReplyToQMgr ""
UserIdentifier Set to the identifier of the authenticated user that connected to the AMQP channel
AccountingToken MQACT_NONE
ApplIdentityData Hexadecimal string. Set to the last 8 bytes of the MQ connection identifier of the AMQP channel.
PutApplType MQAT_AMQP
PutApplName  
PutDate Value taken from the creation-time field of the AMQP properties, if set. Otherwise set to the current date.
PutTime Value taken from the creation-time field of the AMQP properties, if set. Otherwise set to the current time.
ApplOriginData ""


Message properties

There are two reasons for setting message properties:

  • To allow parts of the AMQP message to flow through the queue manager without affecting the payload of the message.
  • To allow selection of the application-properties.

The following table shows the properties that are set from the AMQP message:

Property name MQRFH2 name Type Description
AMQPListener mq_amqp.Lis MQTYPE_STRING An identifying string for the AMQP channel. It is used to generate the message, so that interested parties can tell which version put the message (for example, the service team when diagnosing problems). The value is not validated by the queue manager, and must not be documented externally.
AMQPVersion mq_amqp.Ver MQTYPE_STRING The version of the AMQP message. If not present, "1.0" is assumed. The value is not validated by the queue manager.
AMQPClient mq_amqp.Cli MQTYPE_STRING An identifying string for the API. It is used to send the AMQP message to the channel, so that interested parties can tell which version put the message (for example, the service team when diagnosing problems). The value is not validated by the queue manager and must not be documented externally.
AMQPDurable mq_amqp.Hdr.Dur MQTYPE_BOOLEAN The value of the durable field in the AMQP message header, if set.
AMQPPriority mq_amqp.Hdr.Pri MQTYPE_INT32 The value of the priority field in the AMQP message header, if set.
AMQPTtl mq_amqp.Hdr.Ttl MQTYPE_INT64 The value of the ttl field in the AMQP message header, if set.
AMQPFirstAcquirer mq_amqp.Hdr.Fac MQTYPE_BOOLEAN The value of the first-acquirer field in the AMQP message header, if set.
AMQPDeliveryCount mq_amqp.Hdr.Dct MQTYPE_INT64 The value of the delivery-count field in the AMQP message header, if set.
AMQPMsgId mq_amqp.Prp.Mid MQTYPE_STRING The value of the message-id field in the AMQP properties, if set as a string.
    MQTYPE_BYTE_STRING The value of the message-id field in the AMQP properties, if set as a byte string.
AMQPUserId mq_amqp.Prp.Uid MQTYPE_BYTE_STRING The value of the user-id field in the AMQP properties, if set.
AMQPTo mq_amqp.Prp.To MQTYPE_STRING The value of the to field in the AMQP properties, if set.
AMQPSubject mq_amqp.Prp.Sub MQTYPE_STRING The value of the subject field in the AMQP properties, if set.
AMQPReplyTo mq_amqp.Prp.Rto MQTYPE_STRING The value of the reply-to field in the AMQP properties, if set.
AMQPCorrelationId mq_amqp.Prp.Cid MQTYPE_STRING The value of the correlation-id field in the AMQP properties, if set as a string..
    MQTYPE_BYTE_STRING The value of the correlation-id field in the AMQP properties, if set as a byte string.
AMQPContentType mq_amqp.Prp.Cnt MQTYPE_STRING The value of the content-type field in the AMQP properties, if set.
AMQPContentEncoding mq_amqp.Prp.Cne MQTYPE_STRING The value of the content-encoding field in the AMQP properties, if set.
AMQPAbsoluteExpiryTime mq_amqp.Prp.Aet MQTYPE_STRING The value of the absolute-expiry-time field in the AMQP properties, if set.
AMQPCreationTime mq_amqp.Prp.Crt MQTYPE_STRING The value of the creation-time field in the AMQP properties, if set.
AMQPGroupId mq_amqp.Prp.Gid MQTYPE_STRING The value of the group-id field in the AMQP properties, if set.
AMQPGroupSequence mq_amqp.Prp.Gsq MQTYPE_INT64 The value of the group-sequence field in the AMQP properties, if set.
AMQPReplyToGroupId mq_amqp.Prp.Rtg MQTYPE_STRING The value of the reply-to-group-id field in the AMQP properties, if set.

Each of the application-properties from the AMQP message is set as an IBM MQ message property. The application-properties section must be reconstituted identically byte-for-byte, and so the following restrictions apply:

  • If an application property is rejected by the MQSETMP validation code, the message to be rejected. For example:

    • The property name is limited in length to MQ_MAX_PROPERTY_NAME_LENGTH.
    • The property name must follow the rules defined by the Java Language Specification for Java Identifiers.
    • The property name must not begin JMS or usr.JMS except for the documented JMS properties that can be set.
    • The property name must not be a SQL keyword.

  • An application property containing Unicode character U+002E (".") causes the message to be rejected. The property must be expressible in the "usr" group of properties used by JMS.
  • Only null, boolean, byte, short, int, long, float, double, binary and string properties are supported. An application property with any other type will cause the message to be rejected.


payload

  • For an AMQP body with a single binary data section, the binary data (excluding the AMQP bits) is put as the IBM MQ payload, with a Format of MQFMT_NONE.
  • For an AMQP body with a single string data section, the string data (excluding the AMQP bits) is put as the IBM MQ payload, with a Format of MQFMT_STRING.
  • Otherwise, the AMQP body forms the payload as-is, with a Format of MQFMT_AMQP.

Parent topic: Mapping AMQP and IBM MQ message fields


Related information