MQRFH2 (Rules and formatting header 2) on IBM i

The MQRFH2 structure defines the format of the version-2 rules and formatting header.

Overview

Purpose: This header can be used to send data that has been encoded using an XML-like syntax A message can contain two or more MQRFH2 structures in series, with user data optionally following the last MQRFH2 structure in the series.

Format name: FMRFH2.

• Fields other than RF2NVD are in the character set and encoding that are given by the MDCSI and MDENC fields in the header structure that precedes MQRFH2, or by those fields in the MQMD structure if the MQRFH2 is at the start of the application message data.

  The character set must be one that has single-byte characters for the characters that are valid in queue names.

  When GMCONV is specified on the MQGET call, the queue manager converts these fields to the requested character set and encoding.

• RF2NVD is in the character set given by the RF2NVC field. Only certain Unicode character sets are valid for RF2NVC (see the description of RF2NVC for details).

  Some character sets have a representation that is dependent on the encoding. If RF2NVC is one of these character sets, RF2NVD must be in the same encoding as the other fields in the MQRFH2.

  When GMCONV is specified on the MQGET call, the queue manager converts RF2NVD to the requested encoding, but does not change its character set.

• Fields
• Initial values
• RPG declaration

Fields

The MQRFH2 structure contains the following fields; the fields are described in alphabetical order:

RF2CSI (10-digit signed integer)

Character set identifier of data that follows last RF2NVD field.

This specifies the character set identifier of the data that follows the last RF2NVD field. It does not apply to character data in the MQRFH2 structure itself

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The following special value can be used:

CSINHT

Inherit character-set identifier of this structure.

Character data in the data following this structure is in the same character set as this structure.

The queue manager changes this value in the structure sent in the message to the actual character-set identifier of the structure. Provided no error occurs, the value CSINHT is not returned by the MQGET call.

CSINHT cannot be used if the value of the MDPAT field in MQMD is ATBRKR.

The initial value of this field is CSINHT.

RF2ENC (10-digit signed integer)

Numeric encoding of data that follows last RF2NVD field.

This specifies the numeric encoding of the data that follows the last RF2NVD field; it does not apply to numeric data in the MQRFH2 structure itself.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data.

The initial value of this field is ENNAT.

RF2FLG (10-digit signed integer)

Flags.

The following value must be specified:

RFNONE

No flags.

The initial value of this field is RFNONE.

RF2FMT (8-byte character string)

Format name of data that follows last RF2NVD field.

This specifies the format name of the data that follows the last RF2NVD field.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The rules for coding this field are the same as those for the MDFMT field in MQMD.

The initial value of this field is FMNONE.

RF2LEN (10-digit signed integer)

Total length of MQRFH2 including all RF2NVL and RF2NVD fields.

This is the length in bytes of the MQRFH2 structure, including the RF2NVL and RF2NVD fields at the end of the structure. It is valid for there to be multiple pairs of RF2NVL and RF2NVD fields at the end of the structure, in the sequence:

length1, data1, length2, data2, ...

RF2LEN does not include any user data that may follow the last RF2NVD field at the end of the structure.

To avoid problems with data conversion of the user data in some environments, consider using RF2LEN as a multiple of four.

The following constant gives the length of the fixed part of the structure, that is, the length excluding the RF2NVL and RF2NVD fields:

RFLEN2

Length of fixed part of MQRFH2 structure.

The initial value of this field is RFLEN2.

RF2NVC (10-digit signed integer)

Character set identifier of RF2NVD.

This specifies the coded character set identifier of the data in the RF2NVD field. This is different from the character set of the other strings in the MQRFH2 structure, and can be different from the character set of the data (if any) that follows the last RF2NVD field at the end of the structure.

RF2NVC must have one of the following values, shown in Table 1:

CCSID	Meaning
1200	UTF-16, most recent Unicode version supported
13488	UTF-16, Unicode version 2.0 subset
17584	UTF-16, Unicode version 3.0 subset (includes the Euro symbol)
1208	UTF-8, most recent Unicode version supported

For the UTF-16 character sets, the encoding (byte order) of the RF2NVD must be the same as the encoding of the other fields in the MQRFH2 structure. Surrogate characters (X'D800' through X'DFFF') are not supported.

Note: If RF2NVC does not have one of the values listed previously, and the MQRFH2 structure requires conversion on the MQGET call, the call completes with reason code RC2111 and the message is returned unconverted.

The initial value of this field is 1208.

RF2NVD (n-byte character string)

Name/value data.

This is a variable-length character string containing data encoded using an XML-like syntax. The length in bytes of this string is provided by the RF2NVL field that precedes the RF2NVD field; this length should be a multiple of four.

The RF2NVL and RF2NVD 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

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

RF2NVD is unusual because it is not converted to the character set specified on the MQGET call when the message is retrieved with the GMCONV option in effect; RF2NVD remains in its original character set. However, RF2NVD 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 with the same name as the the folder:

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

Characters following the folder end tag, up to the length defined by RF2NVL, 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:

• The delimiter characters (<, =, ", /, and >) must be specified exactly as shown.
• name is the user-specified name of the property; see the following example for more information about names.
• datatype is an optional user-specified data type of the property; see the following example for valid data types.
• value is the user-specified value of the property; see the following paragraphs for more information about values.
• Blanks are significant between the > character which precedes a value, and the < character which follows the value, and at least one blank must precede dt=. Elsewhere blanks can be coded 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, they can be grouped together by enclosing them within XML start and end tags with the same name as the group:

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

Groups can be nested within other groups, without limit, and a group can occur more than once within a folder. It is also valid for a folder to contain some properties in groups and other properties not in groups. Names of properties, groups, and folders: 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 namespace. 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 namespace 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 RF2NVD field should 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.
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 want 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 in the following table. 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 < < 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>

RF2NVL (10-digit signed integer)

Length of RF2NVD.

This specifies the length in bytes of the data in the RF2NVD field. To avoid problems with data conversion of the data (if any) that follows the RF2NVD field, RF2NVL should be a multiple of four.

Note: The RF2NVL and RF2NVD 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

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

RF2SID (4-byte character string)

Structure identifier.

The value must be:

RFSIDV

Identifier for rules and formatting header structure.

The initial value of this field is RFSIDV.

RF2VER (10-digit signed integer)

Structure version number.

The value must be:

RFVER2

Version-2 rules and formatting header structure.

The initial value of this field is RFVER2.

Initial values

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D*
     D* MQRFH2 Structure
     D*
     D* Structure identifier
     D  RF2SID                 1      4    INZ('RFH ')
     D* Structure version number
     D  RF2VER                 5      8I 0 INZ(2)
     D* Total length of MQRFH2 including allNameValueLength and
     D* NameValueDatafields
     D  RF2LEN                 9     12I 0 INZ(36)
     D* Numeric encoding of data that followslast NameValueData field
     D  RF2ENC                13     16I 0 INZ(273)
     D* Character set identifier of data thatfollows last NameValueData field
     D  RF2CSI                17     20I 0 INZ(-2)
     D* Format name of data that follows lastNameValueData field
     D  RF2FMT                21     28    INZ('        ')
     D* Flags
     D  RF2FLG                29     32I 0 INZ(0)
     D* Character set identifier ofNameValueData
     D  RF2NVC                33     36I 0 INZ(1208)