MQRFH (Rules and formatting header) on IBM i

The MQRFH structure defines the layout of the rules and formatting header.


Overview

Purpose: This header can be used to send string data in the form of name-value pairs.

Format name: FMRFH.

Character set and encoding: The fields in the MQRFH structure (including RFNVS) are in the character set and encoding given by the MDCSI and MDENC fields in the header structure that precedes the MQRFH, or by those fields in the MQMD structure if the MQRFH 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.


Fields

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

    RFCSI (10-digit signed integer)

    Character set identifier of data that follows RFNVS.

    This specifies the character set identifier of the data that follows RFNVS ; it does not apply to character data in the MQRFH 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 CSUNDF.

    Numeric encoding of data that follows RFNVS.

    This specifies the numeric encoding of the data that follows RFNVS ; it does not apply to numeric data in the MQRFH 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.

    RFFLG (10-digit signed integer)

    Flags.

    The following can be specified:

      RFNONE
      No flags.

    The initial value of this field is RFNONE.

    RFFMT (8-byte character string)

    Format name of data that follows RFNVS.

    This specifies the format name of the data that follows RFNVS.

    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.

    RFLEN (10-digit signed integer)

    Total length of MQRFH including RFNVS.

    This is the length in bytes of the MQRFH structure, including the RFNVS field at the end of the structure. The length does not include any user data that follows the RFNVS field.

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

    The following constant gives the length of the fixed part of the structure, that is, the length excluding the RFNVS field:

      RFLENV
      Length of fixed part of MQRFH structure.

    The initial value of this field is RFLENV.

    RFNVS (n-byte character string)

    String containing name-value pairs.

    This is a variable-length character string containing name-value pairs in the form: 
    name1 value1 name2 value2 name3 value3 ...
    Each name or value must be separated from the adjacent name or value by one or more blank characters; these blanks are not significant. A name or value can contain significant blanks by prefixing and suffixing the name or value with the quotation mark character; all characters between the opening quotation mark and the matching closing quotation mark are treated as significant. In the following example, the name is FAMOUS_WORDS, and the value is Hello World: 
    FAMOUS_WORDS "Hello World"
    A name or value can contain any characters other than the null character (which acts as a delimiter for RFNVS). However, to assist interoperability an application might prefer to restrict names to the following characters:

    • First character: uppercase or lowercase alphabetic (A through Z, or a through z), or underscore.
    • Subsequent characters: upper or lowercase alphabetic, decimal digit (0 through 9), underscore, hyphen, or dot.
    If a name or value contains one or more quotation marks, the name or value must be enclosed in quotation marks, and each quotation mark within the string must be doubled: 
    Famous_Words "The program displayed ""Hello World"""
    Names and values are case sensitive, that is, lowercase letters are not considered to be the same as uppercase letters. For example, FAMOUS_WORDS and Famous_Words are two different names.

    The length in bytes of RFNVS is equal to RFLEN minus RFLENV. To avoid problems with data conversion of the user data in some environments, it is recommended that this length should be a multiple of four. RFNVS must be padded with blanks to this length, or terminated earlier by placing a null character following the last significant character in the string. The null character and the bytes following it, up to the specified length of RFNVS, are ignored.

    Note: Because the length of this field is not fixed, the field is omitted from the declarations of the structure that are provided for the supported programming languages.

    RFSID (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.

    RFVER (10-digit signed integer)

    Structure version number.

    The value must be:

      RFVER1
      Version-1 rules and formatting header structure.

    The initial value of this field is RFVER1.


Initial values

Table 1. Initial values of fields in MQRFH
Field name Name of constant Value of constant
RFSID RFSIDV 'RFH¬'
RFVER RFVER1 1
RFLEN RFLENV 32
RFENC ENNAT Depends on environment
RFCSI CSUNDF 0
RFFMT FMNONE Blanks
RFFLG RFNONE 0
Notes:
  1. The symbol ¬ represents a single blank character.


RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQRFH Structure
     D*
     D* Structure identifier
     D  RFSID                  1      4    INZ('RFH ')
     D* Structure version number
     D  RFVER                  5      8I 0 INZ(1)
     D* Total length of MQRFH includingNameValueString
     D  RFLEN                  9     12I 0 INZ(32)
     D* Numeric encoding of data that followsNameValueString
     D  RFENC                 13     16I 0 INZ(273)
     D* Character set identifier of data thatfollows NameValueString
     D  RFCSI                 17     20I 0 INZ(0)
     D* Format name of data that followsNameValueString
     D  RFFMT                 21     28    INZ('        ')
     D* Flags
     D  RFFLG                 29     32I 0 INZ(0)