Property name restrictions

When you name a property, we must observe certain rules.

The following restrictions apply to property names:

  1. A property must not begin with the following strings:

    • "JMS" - reserved for use by IBM MQ classes for JMS.
    • "usr.JMS" - not valid.

    The only exceptions are the following properties providing synonyms for JMS properties:

    Property Synonym for
    JMSCorrelationID Root .MQMD.CorrelId or jms.Cid
    JMSDeliveryMode Root .MQMD.Persistence or jms.Dlv
    JMSDestination jms.Dst
    JMSExpiration Root .MQMD.Expiry or jms.Exp
    JMSMessageID Root .MQMD.MsgId
    JMSPriority Root .MQMD.Priority or jms.Pri
    JMSRedelivered Root .MQMD.BackoutCount
    JMSReplyTo (a string encoded as a URI) Root .MQMD.ReplyToQ or Root .MQMD.ReplyToQMgr or jms.Rto
    JMSTimestamp Root .MQMD.PutDate or Root .MQMD.PutTime or jms.Tms
    JMSType mcd.Type or mcd.Set or mcd.Fmt
    JMSXAppID Root .MQMD.PutApplName
    JMSXDeliveryCount Root .MQMD.BackoutCount
    JMSXGroupID Root .MQMD.GroupId or jms.Gid
    JMSXGroupSeq Root .MQMD.MsgSeqNumber or jms.Seq
    JMSXUserID Root .MQMD.UserIdentifier
    These synonyms allow an MQI application to access JMS properties in a similar fashion to IBM MQ classes for JMS client application. Of these properties, only JMSCorrelationID, JMSReplyTo, JMSType, JMSXGroupID, and JMSXGroupSeq can be set using the MQI.

    Note that the JMS_IBM_* properties available from within IBM MQ classes for JMS are not available using the MQI. The fields that the JMS_IBM_* properties reference can be accessed in other ways by MQI applications.

  2. A property must not be called, in any mixture of lower or uppercase, "NULL", "TRUE", "FALSE", "NOT", "AND", "OR", "BETWEEN", "LIKE", "IN", "IS" and "ESCAPE". These are the names of SQL keywords used in selection strings.
  3. A property name beginning " mq " in any mixture of lowercase or uppercase and not beginning "mq_usr" can contain only one "." character (U+002E). Multiple "." characters are not allowed in properties with those prefixes.
  4. Two "." characters must contain other characters in between; we cannot have an empty point in the hierarchy. Similarly a property name cannot end in a "." character.
  5. If an application sets the property "a.b" and then the property "a.b.c", it is unclear whether in the hierarchy "b" contains a value or another logical grouping . Such a hierarchy is "mixed content" and this is not supported. Setting a property that causes mixed content is not allowed.

These restrictions are enforced by the validation mechanism as follows:

  • Property names are validated when setting a property using the MQSETMP - Set message property call, if validation was requested when the message handle was created . If an attempt to validate a property is undertaken and fails due to an error in the specification of the property name, the completion code is MQCC_FAILED with reason:

    • MQRC_PROPERTY_NAME_ERROR for reasons 1-4.
    • MQRC_MIXED_CONTENT_NOT_ALLOWED for reason 5.

  • The names of properties specified directly as MQRFH2 elements are not guaranteed to be validated by the MQPUT call.

Parent topic: Property names