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