MQIMPO (Inquire message property options) on IBM i

The MQIMPO structure allows applications to specify options that control how properties of messages are inquired.


Overview

Purpose: The structure is an input parameter on the MQINQMP call.

Character set and encoding: Data in MQIMPO must be in the character set of the application and encoding of the application (ENNAT).


Fields

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

    IPOPT (10-digit signed integer)

    The following options control the action of MQINQMP. We can specify one or more of these options. To specify more than one option, either add the values together (do not add the same constant more than once), or combine the values using the bitwise OR operation (if the programming language supports bit operations). Combinations of options that are not valid are noted; all other combinations are valid.

    Value data options: The following options relate to the processing of the value data when the property is retrieved from the message.

      IPCVAL
      This option requests that the value of the property be converted to conform to the IPREQCSI and IPREQENC values specified before the MQINQMP call returns the property value in the Value area.

      • If conversion is successful, the IPRETCSI and IPRETENC fields are set to the same as IPREQCSI and IPREQENC on return from the MQINQMP call.
      • If conversion fails, but the MQINQMP call otherwise completes without error, the property value is returned unconverted.

        If the property is a string, the IPRETCSI and IPRETENC fields are set to the character set and encoding of the unconverted string.

        The completion code is CCWARN in this case, with reason code RC2466. The property cursor is advanced to the returned property.

      If the property value expands during conversion, and exceeds the size of the Value parameter, the value is returned unconverted, with completion code CCFAIL; the reason code is set to RC2469.

      The DataLength parameter of the MQINQMP call returns the length that the property value would have converted to, in order to allow the application to determine the size of the buffer required to accommodate the converted property value. The property cursor is unchanged.

      This option also requests that:

      • If the property name contains a wildcard, and
      • The IPRETNAMECHRP field is initialized with an address or offset for the returned name,

      then the returned name is converted to conform to the IPREQCSI and IPREQENC values.

      • If conversion is successful, the VSCCSID field of IPRETNAMECHRP and the encoding of the returned name are set to the input value of IPREQCSI and IPREQENC.
      • If conversion fails, but the MQINQMP call otherwise completes without error or warning, the returned name is unconverted. The completion code is CCWARN in this case, with reason code RC2492.

        The property cursor is advanced to the returned property. RC2466 is returned if both the value and the name are not converted.

      If the returned name expands during conversion, and exceeds the size of the VSBufsize field of the RequestedName, the returned string is left unconverted, with completion code CCFAIL and the reason code is set to RC2465.

      The VSLength field of the MQCHARV structure returns the length that the property value would have converted to, in order to allow the application to determine the size of the buffer required to accommodate the converted property value. The property cursor is unchanged.

      IPCTYP
      This option requests that the value of the property be converted from its current data type, into the data type specified on the Type parameter of the MQINQMP call.

      • If conversion is successful, the Type parameter is unchanged on return of the MQINQMP call.
      • If conversion fails, but the MQINQMP call otherwise completes without error, the call fails with reason RC2470. The property cursor is unchanged.

      If the conversion of the data type causes the value to expand during conversion, and the converted value exceeds the size of the Value parameter, the value is returned unconverted, with completion code CCFAIL and the reason code is set to RC2469.

      The DataLength parameter of the MQINQMP call returns the length that the property value would have converted to, in order to allow the application to determine the size of the buffer required to accommodate the converted property value. The property cursor is unchanged.

      If the value of the Type parameter of the MQINQMP call is not valid, the call fails with reason RC2473.

      If the requested data type conversion is not supported, the call fails with reason RC2470. The following data type conversions are supported:

      Property data type Supported target data types
      TYPBOL TYPSTR, TYPI8, TYPI16, TYPI32, TYPI64
      TYPBST TYPSTR
      TYPI8 TYPSTR, TYPI16, TYPI32, TYPI64
      TYPI16 TYPSTR, TYPI32, TYPI64
      TYPI32 TYPSTR, TYPI64
      TYPI64 TYPSTR
      TYPF32 TYPSTR, TYPF64
      TYPF64 TYPSTR
      TYPSTR TYPBOL, TYPI8, TYPI16, TYPI32, TYPI64, TYPF32, TYPF64
      TYPNUL None
      The general rules governing the supported conversions are as follows:

      • Numeric property values can be converted from one data type to another, provided that no data is lost during the conversion.

        For example, the value of a property with data type TYPI32 can be converted into a value with data type TYPI64, but cannot be converted into a value with data type TYPI16.

      • A property value of any data type can be converted into a string.
      • A string property value can be converted to any other data type provided the string is formatted correctly for the conversion. If an application attempts to convert a string property value that is not formatted correctly, IBM MQ returns reason code RC2472.
      • If an application attempts a conversion that is not supported, IBM MQ returns reason code RC2470.

      The specific rules for converting a property value from one data type to another are as follows:

      • When converting a TYPBOL property value to a string, the value TRUE is converted to the string "TRUE", and the value false is converted to the string "FALSE".
      • When converting a TYPBOL property value to a numeric data type, the value TRUE is converted to one, and the value FALSE is converted to zero.
      • When converting a string property value to a TYPBOL value, the string "TRUE", or "1", is converted to TRUE, and the string "FALSE", or "0", is converted to FALSE.

        Note that the terms "TRUE" and "FALSE" are not case sensitive.

        Any other string cannot be converted; IBM MQ returns reason code RC2472.

      • When converting a string property value to a value with data type TYPI8, TYPI16, TYPI32 or TYPI64, the string must have the following format: 
        [blanks][sign]digits
        The meanings of the components of the string are as follows:

          blanks
          Optional leading blank characters

          sign
          An optional plus sign (+) or minus sign (-) character.

          digits
          A contiguous sequence of digit characters (0-9). At least one digit character must be present.

        After the sequence of digit characters, the string can contain other characters that are not digit characters, but the conversion stops as soon as the first of these characters is reached. The string is assumed to represent a decimal integer.

        IBM MQ returns reason code RC2472 if the string is not formatted correctly.

      • When converting a string property value to a value with data type TYPF32 or TYPF64, the string must have the following format: 
        [blanks][sign]digits[.digits][e_char[e_sign]e_digits]
        The meanings of the components of the string are as follows:

          blanks
          Optional leading blank characters

          sign
          An optional plus sign (+) or minus sign (-) character.

          digits
          A contiguous sequence of digit characters (0-9). At least one digit character must be present.

          e_char
          An exponent character, which is either "E" or "e".

          e_sign
          An optional plus sign (+) or minus sign (-) character for the exponent.

          e_digits
          A contiguous sequence of digit characters (0-9) for the exponent. At least one digit character must be present if the string contains an exponent character.

        After the sequence of digit characters, or the optional characters representing an exponent, the string can contain other characters that are not digit characters, but the conversion stops as soon as the first of these characters is reached. The string is assumed to represent a decimal floating point number with an exponent that is a power of 10.

        IBM MQ returns reason code RC2472 if the string is not formatted correctly.

      • When converting a numeric property value to a string, the value is converted to the string representation of the value as a decimal number, not the string containing the ASCII character for that value. For example, the integer 65 is converted to the string "65", not the string "A".
      • When converting a byte string property value to a string, each byte is converted to the two hexadecimal characters that represent the byte. For example, the byte array {0xF1, 0x12, 0x00, 0xFF} is converted to the string "F11200FF".

      IPQLEN
      Query the type and length of the property value. The length is returned in the DataLength parameter of the MQINQMP call. The property value is not returned.

      If a ReturnedName buffer is specified, the VSLength field of the MQCHARV structure is filled in with the length of the property name. The property name is not returned.

    Iteration options: The following options relate to iterating over properties, using a name with a wildcard character

      IPINQF
      Inquire on the first property that matches the specified name. After this call, a cursor is established on the property that is returned.

      This is the default value.

      The IPINQC option can subsequently be used with an MQINQMP call, if required, to inquire on the same property again.

      Note that there is only one property cursor; therefore, if the property name, specified in the MQINQMP call, changes the cursor is reset.

      This option is not valid with either of the following options:

      • IPINQN
      • IPINQC

      IPINQN
      Inquires on the next property that matches the specified name, continuing the search from the property cursor. The cursor is advanced to the property that is returned.

      If this is the first MQINQMP call for the specified name, then the first property that matches the specified name is returned.

      The IPINQC option can subsequently be used with an MQINQMP call if required, to inquire on the same property again.

      If the property under the cursor has been deleted, MQINQMP returns the next matching property following the one that has been deleted.

      If a property is added that matches the wildcard, while an iteration is in progress, the property might or might not be returned during the completion of the iteration. The property is returned once the iteration restarts using IPINQF.

      A property matching the wildcard that was deleted, while the iteration was in progress, is not returned subsequent to its deletion.

      This option is not valid with either of the following options:

      • IPINQF
      • IPINQC

      IPINQC
      Retrieve the value of the property pointed to by the property cursor. The property pointed to by the property cursor is the one that was last inquired, using either the IPINQF or the IPINQN option.

      The property cursor is reset when the message handle is reused, when the message handle is specified in the MsgHandle field of the MQGMO on an MQGET call, or when the message handle is specified in OriginalMsgHandle or NewMsgHandle fields of the MQPMO structure on an MQPUT call.

      If this option is used when the property cursor has not yet been established, or if the property pointed to by the property cursor has been deleted, the call fails with completion code CCFAIL and reason RC2471.

      This option is not valid with either of the following options:

      • IPINQF
      • IPINQN

    If none of the options previously described is required, the following option can be used:

      IPNONE
      Use this value to indicate that no other options have been specified; all options assume their default values.

      IPNONE aids program documentation; it is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.

    This is always an input field. The initial value of this field is IPINQF.

    IPREQCSI (10-digit signed integer)

    The character set that the inquired property value is to be converted into if the value is a character string. This is also the character set into which the ReturnedName is to be converted when IPCVAL or IPCTYP is specified.

    The initial value of this field is CSAPL.

    IPREQENC (10-digit signed integer)

    This is the encoding into which the inquired property value is to be converted when IPCVAL or IPCTYP is specified.

    The initial value of this field is ENNAT.

    IPRE1 (10-digit signed integer)

    This is a reserved field. The initial value of this field is a blank character.

    IPRETCSI (10-digit signed integer)

    On output, this is the character set of the value returned if the Type parameter of the MQINQMP call is TYPSTR.

    If the IPCVAL option is specified and conversion was successful, the ReturnedCCSID field, on return, is the same value as the value passed in.

    The initial value of this field is zero.

    IPRETENC (10-digit signed integer)

    On output, this is the encoding of the value returned.

    If the IPCVAL option is specified and conversion was successful, the ReturnedEncoding field, on return, is the same value as the value passed in.

    The initial value of this field is ENNAT.

    IPRETNAMCHRP (10-digit signed integer)

    The actual name of the inquired property.

    On input a string buffer can be passed in using the VSPtr or VSOffset field of the MQCHARV structure. The length of the string buffer is specified using the VSBufsize field of the MQCHARV structure.

    On return from the MQINQMP call, the string buffer is completed with the name of the property that was inquired, provided the string buffer was long enough to fully contain the name. The VSLength field of the MQCHARV structure is filled in with the length of the property name. The VSCCSID field of the MQCHARV structure is filled in to indicate the character set of the returned name, whether or not conversion of the name failed.

    This is an input/output field. The initial value of this field is MQCHARV_DEFAULT.

    IPSID (10-digit signed integer)
    This is the structure identifier. The value must be:

      IPSIDV
      Identifier for inquire message property options structure.

    This is always an input field. The initial value of this field is IPSIDV.

    IPTYP (10-digit signed integer)

    A string representation of the data type of the property.

    If the property was specified in an MQRFH2 header and the MQRFH2 dt attribute is not recognized, this field can be used to determine the data type of the property. TypeString is returned in coded character set 1208 (UTF-8), and is the first eight bytes of the value of the dt attribute of the property that failed to be recognized

    This is always an output field. The initial value of this field is the null string in the C programming language, and 8 blank characters in other programming languages.

    IPVER (10-digit signed integer)
    This is the structure version number. The value must be:

      IPVER1
      Version number for inquire message property options structure.

    The following constant specifies the version number of the current version:

      IPVERC
      Current version of inquire message property options structure.

    This is always an input field. The initial value of this field is IPVER1.


Initial values

Field name Name of constant Value of constant
IPSID IPSIDV 'IMPO'
IPVER IPVER1 1
IPOPT IPINQF  
IPREQENC ENNAT  
IPREQCSI CSAPL  
IPRETENC ENNAT  
IPRETCSI 0  
IPRE1 0  
IPRETNAMCHRP    
IPTYP   blanks


RPG declaration

D* MQIMPO Structure
D*
D*
D* Structure identifier
D IPSID         1   4  INZ('IMPO')
D*
D* Structure version number
D IPVER         5   8I 0 INZ(1)
D*
** Options that control the action of
D* MQINQMP
D IPOPT         9   12I 0 INZ(0)
D*
D* Requested encoding of Value
D IPREQENC       13   16I 0 INZ(273)
D*
** Requested character set identifier
D* of Value
D IPREQCSI       17   20I 0 INZ(-3)
D*
D* Returned encoding of Value
D IPRETENC       21   24I 0 INZ(273)
D*
** Returned character set identifier of
D* Value
D IPRETCSI       25   28I 0 INZ(0)
D*
D* Reserved
D IPRE1         29   32I 0 INZ(0)
D*
D* Returned property name
D* Address of variable length string
D IPRETNAMCHRP     33   48*  INZ(*NULL)
D* Offset of variable length string
D IPRETNAMCHRO     49   52I 0 INZ(0)
D* Size of buffer
D IPRETNAMVSBS     53   56I 0 INZ(-1)
D* Length of variable length string
D IPRETNAMCHRL     57   60I 0 INZ(0)
D* CCSID of variable length string
D IPRETNAMCHRC     61   64I 0 INZ(-3)
D*
D* Property data type as a string
D IPTYP         65   72  INZ
Parent topic: Data type descriptions on IBM i