Home

 

NameValueData (MQCHARn)

This is a variable-length character string containing data encoded using an XML-like syntax. The length in bytes of this string is given by the NameValueLength field that precedes the NameValueData field; this length must be a multiple of four.

The NameValueLength and NameValueData fields are optional, but if present they must occur as a pair and be adjacent. The pair of fields can be repeated as many times as required, for example:

length1 data1 length2 data2 length3 data3
Notes:

  1. Because these fields are optional, they are omitted from the declarations of the structure that are provided for the various programming languages supported.

  2. For further information on the method of terminating the following NameValue fields, see topic NameValueString

NameValueData is not converted to the character set specified on the MQGET call when 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.

Syntax of name/value data: The string consists of a single folder that contains zero or more properties. The folder is delimited by XML start and end tags whose name is the name of the folder:

<folder> property1 property2 ... </folder>

Characters following the folder end tag, up to the length defined by NameValueLength, must be blank. Within the folder, each property is composed of a name and a value, and optionally a data type:

<name dt="datatype">value</name>

In these examples:

  • Specify the delimiter characters (<, =, ", /, and >) exactly as shown.

  • name is the user-specified name of the property; see below for more information about names.

  • datatype is an optional user-specified data type of the property; see below for valid data types.

  • value is the user-specified value of the property; see below for more information about values.

  • Blanks are significant between the

    > character that precedes a value, and the

    < character that follows the value, and at least one blank must precede

    dt=. Elsewhere we can code blanks freely between tags, or preceding or following tags (for example, in order to improve readability); these blanks are not significant.

If properties are related to each other, we can group them together by enclosing them within XML start and end tags whose name is the name of the group:

<folder> <group> property1 property2 ... </group> </folder>

Groups can be nested within other groups, without limit, and a given group can occur more than once within a folder. A folder can also contain some properties in groups and other properties not in groups.

Names of properties, groups, and folders: The names of properties, groups, and folders must be valid XML tag names, with the exception of the colon character, which is not permitted in a property, group, or folder name. In particular:

  • Names must start with a letter or an underscore. Valid letters are defined in the W3C XML specification, and consist essentially of Unicode categories Ll, Lu, Lo, Lt, and Nl.

  • The remaining characters in a name can be letters, decimal digits, underscores, hyphens, or dots. These correspond to Unicode categories Ll, Lu, Lo, Lt, Nl, Mc, Mn, Lm, and Nd.

  • The Unicode compatibility characters (X'F900' and above) are not permitted in any part of a name.

  • Names must not start with the string

    XML in any mixture of upper or lowercase.

In addition:

  • Names are case-sensitive. For example,

    ABC, abc, and

    Abc are three different names.

  • Each folder has a separate name space. As a result, a group or property in one folder does not conflict with a group or property of the same name in another folder.

  • Groups and properties occupy the same name space within a folder. As a result, a property cannot have the same name as a group within the folder containing that property.

Generally, programs that analyze the NameValueData field must ignore properties or groups that have names that the program does not recognize, provided that those properties or groups are correctly formed.

Data types of properties: Each property can have an optional data type. If specified, the data type must be one of the following values, in upper, lower, or mixed case:

Data type Used for

string

Any sequence of characters. Certain characters must be specified using escape sequences (see below).

boolean

The character 0 or 1 (1 denotes

TRUE).

bin.hex

Hexadecimal digits representing octets.

i1

Integer number in the range -128 through +127, expressed using only decimal digits and optional sign.

i2

Integer number in the range -32 768 through +32 767, expressed using only decimal digits and optional sign.

i4

Integer number in the range -2 147 483 648 through +2 147 483 647, expressed using only decimal digits and optional sign.

i8

Integer number in the range -9 223 372 036 854 775 808 through +9 223 372 036 854 775 807, expressed using only decimal digits and optional sign.

int

Integer number in the range -9 223 372 036 854 775 808 through +9 223 372 036 854 775 807, expressed using only decimal digits and optional sign. This can be used in place of

i1, i2, i4, or i8 if the sender does not wish to imply a particular precision.

r4

Floating-point number with magnitude in the range 1.175E-37 through 3.402 823 47E+38, expressed using decimal digits, optional sign, optional fractional digits, and optional exponent.

r8

Floating-point number with magnitude in the range 2.225E-307 through 1.797 693 134 862 3E+308 expressed using decimal digits, optional sign, optional fractional digits, and optional exponent.

Values of properties: The value of a property can consist of any characters, except as detailed below. Each occurrence in the value of a character marked as mandatory must be replaced by the corresponding escape sequence. Each occurrence in the value of a character marked as optional can be replaced by the corresponding escape sequence, but this is not required.

Character Escape sequence Usage

&

&amp;

Mandatory

<

&lt;

Mandatory

>

&gt;

Optional

"

&quot;

Optional

'

&apos;

Optional
Note:
The

& character at the start of an escape sequence must not be replaced by

&amp;.

In the following example, the blanks in the value are significant; however, no escape sequences are needed:

<Famous_Words>The program displayed "Hello World"</Famous_Words>


 

Home