NameValueData ( MQCHARn)

length1 data1 length2 data2 length3 data3

NameValueData is not converted to the character set specified on the MQGET call. Even if the message is retrieved with the MQGMO_CONVERT option in effect NameValueData remains in its original character set. However, NameValueData is converted to the encoding specified on the MQGET call.

• Because these fields are optional, they are omitted from the declarations of the structure that are provided for the various programming languages supported.
• The terms defined and reserved are used in the syntax diagram. Defined means that the name is used by IBM MQ . Reserved means that the name is reserved for future use by IBM MQ.

NameValueData syntax

• ¹ Double quotation marks or single quotation marks are valid.
• ² Do not use an invalid property name; see Invalid property name. Use a reserved property name only for its defined purpose; see Defined property names.
• ³ Do not use an invalid or reserved folder name; see Invalid path name and Reserved folder or property folder name. Use a defined folder name only for its defined purpose; see Defined folder name.
• ⁴ The name must be in lowercase.
• ⁵ Only one psc and pscr folder is supported.
• ⁶ WebSphere Application Server Service Integration Bus ignores sib, sib_context, and sib_usr folders in subsequent MQRFH2 headers, and only properties in the first MQRFH2 header are significant.
• ⁷ Not more than one usr folder must be present in an MQRFH2. Properties in the usr folder must occur no more than once.
• ⁸ Only properties in the first mq folder are significant. If the folder is UTF-8, only single byte UTF-8 characters are supported. The only white space character is Unicode U+0020.
• ⁹ Valid characters are defined in the W3C XML specification, and consist essentially of Unicode categories Ll, Lu, Lo, Lt, Nl, Mc, Mn, Lm, and Nd ; see Unicode character categories.
• ¹⁰ All characters are significant. Leading and trailing blanks are part of the element value.
• ¹¹ Do not use an invalid character; see Invalid characters. Use an escape sequence, rather than these invalid characters.
• ¹² The support property attribute is only valid on the mq folder

Folder name

NameValueData contains a single folder. To create multiple folders, create multiple NameValueData fields. We can create multiple NameValueData fields in a single MQRFH2 header within a message. Alternatively we can create multiple chained MQRFH2 headers, each containing multiple NameValueData fields.

The order of MQRFH2 headers, and the order of NameValueData fields makes no difference to the logical contents of a folder. If the same folder is present more than once in a message the folder is parsed as a whole. If the same property occurs in muliple instances of the same folder, it is parsed as a list.

A correct parse of an MQRFH2 is not affected by the alternative ways a folder can be physically stored in a message.

Four folders do not follow this rule. Only the first instance of the mq, sib, sib_context, and sib_usr folder are parsed.

If the same property occurs more than once in the combined contents of the chained MQRFH2 headers, only the first instance of the property is parsed. If a property is set using an API call, such as MQSETMP, and added to an MQRFH2 directly by an application, the API call takes precedence.

A folder name is the name of a folder containing name-value pairs or groups. Groups and name-value pairs can be mixed at the same level in the folder tree; see Figure 1. Do not combine a group name and an element name; see Figure 2

<group1><nvp1>value</nvp1></group1><group2><nvp2>value</nvp2></group2>
<group3><nvp1>value</nvp1></group3><nvp3>value</nvp3>

<group1><nvp1> value </nvp1> value </group1>

Do not use an invalid or reserved folder name; see #q099320___d592e2894 and #q099320___d592e2821. Use a defined folder name only for its defined purpose; see #q099320___d592e1056.

If you add the attribute 'content=properties' to the folder name tag, the folder becomes a property folder; see Figure 3.

<myFolder></myfolder>
<myPropertyFolder contents='properties'></myPropertyFolder>

Folder names are case-sensitive. Folder names and property folder names share the same namespace. They must have different names. Folder1 in Figure 4 must be a different name to Folder2 in Figure 5.

< Folder1 ><NVP1> value </NVP1></ Folder1 >

< Folder2 content='properties'>< Property1 > value </ Property1 ></ Folder2 >

Groups, properties, and name-value pairs in different folders have different namespaces. Property1 in Figure 5 is a different property to Property1 in Figure 6.

<Folder3 content='properties'>< Property1 > value </ Property1 ></Folder3>

Property folders are different to non-property folders in two important respects:

1. Property folders contain properties, and non-property folders contain name-value pairs. The folders differ slightly, syntactically.
2. Use the defined interfaces, such as the properties MQI, or JMS message properties, to access message properties. The interfaces ensure the property folders in the MQRFH2 are well-formed. A well-formed property folder is interoperable between queue managers on different platforms and different releases.

The message property MQI is a robust way to read and write an MQRFH2, and avoids the difficulties of parsing an MQRFH2 correctly.

Defined folder name

A defined folder name is the name of a folder that is reserved for use by IBM MQ, or another product. Do not create a folder of the same name, and do not add your own name-value pairs to the folders. The defined folders are psc and pscr.

psc and pscr are used by queued publish/subscribe.

A segmented message put with either MQMF_SEGMENT or MQMF_SEGMENTATION_ALLOWED cannot contain an MQRFH2 with a defined folder name. The MQPUT fails with reason code 2443, MQRC_SEGMENTATION_NOT_ALLOWED.

Defined property folder name

A defined property folder name is the name of a property folder that is used by IBM MQ, or another product. For the names of the folders and their contents, see Property folders. Defined property folder names are a subset of all the folder names reserved by IBM MQ; see Reserved folder or property folder name.

Any element stored in a defined property folder is a property. An element stored in a defined property folder must not have a content='properties' attribute.

We can add properties only to the defined property folders usr, mq_usr, and sib_usr. In other property folders, such as mq and sib, IBM MQ ignores or throws away properties it does not recognize.

The description of each defined property folder lists the properties that IBM MQ has defined that can be used by application programs. Some of the properties are accessed indirectly by setting or getting a JMS property, and some are accessed directly using the MQSETMP and MQINQMP MQI calls.

The defined property folders also contain other properties that IBM MQ has reserved, but which applications do not have access to. The names of the reserved properties are not listed. No reserved properties are present in the usr, mq_usr, and sib_usr property folders. But do not create properties with invalid property names; see Invalid property name.

Property folders

jms

jms contains JMS header fields, and JMSX properties that cannot be fully expressed in the MQMD. The jms folder is always present in a JMS MQRFH2.

Property synonym	Property name	Data type	Folder
JMSDestination	jms.Dst	string	<jms><Dst> destination </Dst></jms>
JMSExpiration	jms.Exp	i8	<jms><Exp> expiration </Exp></jms>
JMSCorrelation	jms.Cid	string	<jms><Cid> correlationId </Cid></jms>
JMSDelivery	jms.Dlv	i4	<jms><Dlv> delivery </Dlv></jms>
JMSPriority	jms.Pri	i4	<jms><Pri> priority </Pri></jms>
JMSReplyTo	jms.Rto	string	<jms><Rto> replyToURI </Rto></jms>
JMSTimeStamp	jms.Tms	i8	<jms><Tms> timestamp </Tms></jms>
JMSXGroupID	jms.Gid	string	<jms><Gid> groupId </Gid></jms>
JMSXGroupSeq	jms.Seq	i4	<jms><Seq> messageSequenceNo </Seq></jms>

Do not add your own properties in the jms folder.

mcd

mcd contains properties that describe the format of the message. For example, the message service domain Msd property identifies a JMS message as being JMSTextMessage, JMSBytesMessage, JMSStreamMessage, JMSMapMessage, JMSObjectMessage, or null.

The mcd folder is always present in a JMS message containing an MQRFH2.

It is always present in a message containing an MQRFH2 sent from IBM Integration Bus. It describes the domain, format, type, and message set of a message.

Property synonym	Property name	Data type	Folder
	mcd.Msd	string	<mcd><Msd>messageDomain</Msd></mcd>
	mcd.Set	string	<mcd><Set>messageDomain</Set></mcd>
	mcd.Type	string	<mcd><Type>messageDomain</Type></mcd>
	mcd.Fmt	string	<mcd><Fmt>messageDomain</Fmt></mcd>

Do not add your own properties in the mcd folder.

mq_usr

mq_usr contains application-defined properties that are not exposed as JMS user-defined properties. Properties that do not meet JMS requirements can be placed in this folder.

We can create properties in the mq_usr folder. Properties you create in the mq_usr are like properties you create in new folders with the content='properties' attribute.

sib

sib contains WebSphere Application Server service integration bus (WAS/SIB) system message properties. sib properties are not exposed as JMS properties to IBM MQ JMS applications because they are not of the supported types. For example, some sib properties cannot be exposed as JMS properties because they are byte arrays. Some sib properties are exposed to WAS/SIB applications as JMS_IBM_* properties; these include forward and reverse routing paths properties.

Do not add your own properties in the sib folder.

sib_context

sib_context contains WAS/SIB system message properties that are not exposed to WAS/SIB user applications or as JMS properties. sib_context contains security and transactional properties that are used for web services.

Do not add your own properties in the sib_context folder.

sib_usr

sib_usr contains WAS/SIB user message properties that are not exposed as JMS user properties because they are not of supported types. sib_usr is exposed to WAS/SIB applications in the SIMessage interface; see Developing Service Integration.

The type of a sib_usr property must be bin.hex, and the value must be in the correct format. If an IBM MQ application writes a bin.hex typed element to the folder in the wrong format, the application receives an IOException. If the data type of the property is not bin.hex the application receives a ClassCastException.

Do not attempt to make JMS user properties available to WAS/SIB by using this folder; instead use the usr folder.

We can create properties in the sib_usr folder.

usr

usr contains application-defined JMS properties associated with the message. The usr folder is present only if an application has set an application-defined property.

usr is the default property folder. If a property is set without a folder name, it is placed in the usr folder.

Property synonym	Property name	Data type	Folder
	usr.contentType	string	<usr><contentType>text/xml; charset=utf-8</contentType></usr>
	usr.endPointURL	string	<usr><endPointURL> URI </endPointURL></usr>
	usr.targetService	string	<usr><targetService> serviceName </targetService></usr>
	usr.soapAction	string	<usr><soapAction> name </soapAction></usr>
	usr.transportVersion	string	<usr><transportVersion> version </transportVersion></usr>

We can create properties in the usr folder.

A segmented message put with either MQMF_SEGMENT or MQMF_SEGMENTATION_ALLOWED cannot contain an MQRFH2 with a defined property folder name. The MQPUT fails with reason code 2443, MQRC_SEGMENTATION_NOT_ALLOWED.

Ungrouped property folder name

ibm

ibm contains properties that are used only by IBM MQ.

Property synonym	Property name	Data type	Folder
	ibm.rfp	string	<ibm><rfp>fingerprint</rfp></ibm>

Do not add your own properties in the ibm folder.

mq

mq contains properties that are used only by IBM MQ.

The following restrictions apply to properties in the mq folder:

• Only properties in the first significant mq folder in the message are acted upon by MQ; properties in any other mq folder in the message are ignored.
• Only single-byte UTF-8 characters are allowed in the folder. A multi-byte character in the folder, can cause parsing to fail, and the message to be rejected.
• Do not use escape strings in the folder. An escape string is treated as the actual value of the element.
• Only Unicode character U+0020 is treated as white space within the folder. All other characters are treated as significant and can cause parsing of the folder to fail, and the message to be rejected.

If parsing of the mq folder fails, or if the folder does not observe these restrictions, the message is rejected with reason code 2527, MQRC_RFH_RESTRICTED_FORMAT_ERR.

Do not add your own properties in the mq folder.

mqema

mqema contains properties that are used only by WebSphere Application Server. The folder has been replaced by mqext.

Do not add your own properties in the mqema folder.

mqext

mqext contains the following types of property:

• Properties that are used only by WebSphere Application Server.
• Properties relating to delayed delivery of messages.

The folder is present if the application has either set at least one of the IBM defined properties or used delivery delay.

Property synonym	Property name	Data type	Folder
JMSArmCorrelator	mqext.Arm	string	<mqext><Arm>armCorrelator</Arm></mqext>
JMSRMCorrelator	mqext.Wrm	string	<mqext><Wrm>wrmCorrelator</Wrm></mqext>
JMSDeliveryTime	mqext.Dlt	i8	<mqext><Dlt>DeliveryTime</Dlt></mqext>
JMSDeliveryDelay	mqext.Dly	i8	<mqext><Dly>DeliveryTime</Dly></mqext>

Do not add your own properties in the mqext folder.

mqps

mqps contains properties that are used only by IBM MQ publish/subscribe. The folder is present only if the application has set at least one of the integrated publish/subscribe properties.

Property synonym	Property name	Data type	Folder
MQTopicString	mqps.Top	string	<mqps><Top>topicString</Top></mqps>
MQSubUserData	mqps.Sud	string	<mqps><Sud>subscriberUserData...</Sud></mqps>
MQIsRetained	mqps.Ret	boolean	<mqps><Ret>isRetained</Ret></mqps>
MQPubOptions	mqps.Pub	i8	<mqps><Pub>publicationOptions</Pub></mqps>
MQPubLevel	mqps.Pbl	i8	<mqps><Pbl>publicationLevel</Pbl></mqps>
MQPubTime	mqpse.Pts	string	<mqps><Pts>publicationTime</Pts></mqps>
MQPubSeqNum	mqpse.Seq	i8	<mqps><Seq>publicationSequenceNumber</Seq></mqps>
MQPubStrIntData	mqpse.Sid	string	<mqps><Sid>publicationData</Sid></mqps>
MQPubFormat	mqpse.Pfmt	i8	<mqps><Pfmt>messageFormat</Pfmt></mqps>

Do not add your own properties in the mqps folder.

mq_svc

mq_svc contains properties used by SupportPac MA93.

Do not add your own properties in the mq_svc folder.

mqtt

mqtt contains properties use by MQ Telemetry

Property synonym	Property name	Data type	Folder
	mqtt.clientId	string	<mqtt><clientId> topicString </clientId></mqtt>
	mqtt.qos	i4	<mqtt><qos> qualityOfService </qos></mqtt>
	mqtt.msgid	string	<mqtt><msgid> messageIdentifier </msgid></mqtt>

Do not add your own properties in the mqtt folder.

A segmented message put with either MQMF_SEGMENT or MQMF_SEGMENTATION_ALLOWED cannot contain an MQRFH2 with an ungrouped property folder name. The MQPUT fails with reason code 2443, MQRC_SEGMENTATION_NOT_ALLOWED.

Name-value pairs

In the syntax diagram, Name-value pairs describes the content of an ordinary folder. An ordinary folder contains groups, and elements. An element is a name-value pair. A group contains elements and other groups.

In terms of trees, elements are leaf nodes, and groups are internal nodes. An internal node, and the folder, which is the root node, can contain a mixture of internal nodes and leaf nodes. A node cannot be both an internal node and a leaf node at the same time; see Figure 2.

Properties

In the syntax diagram, Properties describes the content of a property folder. A property folder contains groups, and properties. A property is a name-value pair with an optional data type attribute. A group contains properties and other groups.

In terms of trees, properties are leaf nodes, and groups are internal nodes. An internal node, and the property folder, which is the root node, can contain a mixture of internal nodes and leaf nodes. A node cannot be both an internal node and a leaf node at the same time; see Figure 2.

Property

A message property is a name-value pair in a property folder. It can optionally include a data type attribute and a property attribute; for an example, see Figure 7. If the data type attribute is omitted, the property type is string.

<pf><p1 dt='i8' > value </p1></pf>

<myPropertyFolder1>
    <myGroup1>
        <myGroup2>
            <myProperty1>value</myProperty1>
        </myGroup2>
    </myGroup1>
</myPropertyFolder1>

A property folder can contain multiple properties. For example the properties in Figure 9 are mapped to the property folder in Figure 10

 myPropertyFolder1.myProperty4
myPropertyFolder1.myGroup1.myGroup2.myProperty1
myPropertyFolder1.myGroup1.myGroup2.myProperty2
myPropertyFolder1.myGroup1.myProperty3

<myPropertyFolder1>
    <myProperty4>value</myProperty4>
    <myGroup1>
        <myGroup2>
            <myProperty1>value</myProperty1>
            <myProperty2>value</myProperty2>
        </myGroup2>
        <myProperty3>value</myProperty3>
    </myGroup1>
</myPropertyFolder1>

Name

A name must begin with a Letter or an Underscore. It must not contain a Colon, not end in a Period and contain only Letters, Numerals, Underscores, Hyphens, and Dots. Valid characters are defined in the W3C XML specification, and consist essentially of Unicode categories Ll, Lu, Lo, Lt, Nl, Mc, Mn, Lm, and Nd ; see Unicode character categories.

The complete path of a property or name-value pair must not break the rule described in Invalid path name. Paths are restricted to 4095 bytes, must not contain Unicode compatibility characters, and must not start with the string XML.

Group name

A group name has the same syntax as a name. Group names are optional. Properties and name-value pairs can be placed in the root of a folder. Use groups if it helps to organize properties and name-value pairs.

Element name

An element name has the same syntax as a name.

Element value

An element value includes all the white space between the < Element name > tag and the < /Element name >. Do not use the two characters < and & in a value. Replace then with < and &amp;.

Property attributes

Support

sa

MQPD_SUPPORT_OPTIONAL

sr

MQPD_SUPPORT_REQUIRED

sx

MQPD_SUPPORT_REQUIRED_IF_LOCAL

Context

none

MQPD_NO_CONTEXT

user

MQPD_USER _CONTEXT

CopyOptions

forward

MQPD_COPY_FORWARD

reply

MQPD_COPY_REPLY

report

MQPD_COPY_REPORT

publish

MQPD_COPY_PUBLISH

all

MQPD_COPY_ALL

Do not use all in combination with other options.

default

MQPD_COPY_DEFAULT

Do not use default in combination with other options. default is the same as forward + report + publish.

none

MQPD_COPY_NONE

Do not use none in combination with other options.

The Support property attributes are only applicable to properties in the mq folder.

The Context and CopyOptions property attributes are applicable to all property folders.

Data types

MQRFH2 data types map to message property types as follows:

Any element without a data type is assumed to be of type string.

<NullProperty
xsi:nil='true'></NullProperty>

<EmptyProperty></EmptyProperty>

Reserved folder or property folder name

Restrict the name of a folder or property folder not to start with any of the following strings. The prefixes are reserved for folder or property names created by IBM.

• ¹ A reserved folder or property name contains any mixture of lower and uppercase letters.

Invalid path name

Restrict the complete path of a name-value pair or a property not to include any of the following strings.

Invalid characters

Always use the escape sequences &amp; and < instead of the literals & and <.

Defined property names

Defined property names are the names of properties that are defined by IBM MQ, or other products, and used by IBM MQ and user applications. Defined properties exist only in defined property folders. Defined property names are described in the description of property folders; see Property folders.

Invalid property name

Do not construct property names that match the following rule. The rule applies to the full property path that names a property, and not only to the property element name.

• ¹ An invalid property name can contain any combination of upper and lowercase.

Invalid attributes

Property folders and properties can include only supported Property attributes and Data types.

Any non-supported XML-like attributes, for example, names with quoted string values, that are included in property folders or properties might be removed.

XML-like attributes included in non-property folders or non-property elements that remain in MQRFH2 headers.