Options (MQLONG)

Inquire message property options structure - Options field

The following options control the action of MQINQMP. You 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.
MQIMPO_CONVERT_VALUE
This option requests that the value of the property be converted to conform to the RequestedCCSID and RequestedEncoding values specified before the MQINQMP call returns the property value in the Value area.
  • If conversion is successful, the ReturnedCCSID and ReturnedEncoding fields are set to the same as RequestedCCSID and RequestedEncoding 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 ReturnedCCSID and ReturnedEncoding fields are set to the character set and encoding of the unconverted string.

    The completion code is MQCC_WARNING in this case, with reason code MQRC_PROP_VALUE_NOT_CONVERTED. 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 MQCC_FAILED; the reason code is set to MQRC_PROPERTY_VALUE_TOO_BIG.

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 ReturnedName field is initialized with an address or offset for the returned name,
then the returned name is converted to conform to the RequestedCCSID and RequestedEncoding values.
  • If conversion is successful, the VSCCSID field of ReturnedName and the encoding of the returned name are set to the input value of RequestedCCSID and RequestedEncoding.
  • If conversion fails, but the MQINQMP call otherwise completes without error or warning, the returned name is unconverted. The completion code is MQCC_WARNING in this case, with reason code MQRC_PROP_NAME_NOT_CONVERTED.

    The property cursor is advanced to the returned property. MQRC_PROP_VALUE_NOT_CONVERTED 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 MQCC_FAILED and the reason code is set to MQRC_PROPERTY_NAME_TOO_BIG.

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.

MQIMPO_CONVERT_TYPE
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 MQRC_PROP_CONV_NOT_SUPPORTED. 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 MQCC_FAILED and the reason code is set to MQRC_PROPERTY_VALUE_TOO_BIG.

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 MQRC_PROPERTY_TYPE_ERROR.

If the requested data type conversion is not supported, the call fails with reason MQRC_PROP_CONV_NOT_SUPPORTED. The following data type conversions are supported:
Table 1. Supported data type conversions
Property data type Supported target data types
MQTYPE_BOOLEAN MQTYPE_STRING, MQTYPE_INT8, MQTYPE_INT16, MQTYPE_INT32, MQTYPE_INT64
MQTYPE_BYTE_STRING MQTYPE_STRING
MQTYPE_INT8 MQTYPE_STRING, MQTYPE_INT16, MQTYPE_INT32, MQTYPE_INT64
MQTYPE_INT16 MQTYPE_STRING, MQTYPE_INT32, MQTYPE_INT64
MQTYPE_INT32 MQTYPE_STRING, MQTYPE_INT64
MQTYPE_INT64 MQTYPE_STRING
MQTYPE_FLOAT32 MQTYPE_STRING, MQTYPE_FLOAT64
MQTYPE_FLOAT64 MQTYPE_STRING
MQTYPE_STRING MQTYPE_BOOLEAN, MQTYPE_INT8, MQTYPE_INT16, MQTYPE_INT32, MQTYPE_INT64, MQTYPE_FLOAT32, MQTYPE_FLOAT64
MQTYPE_NULL 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 MQTYPE_INT32 can be converted into a value with data type MQTYPE_INT64, but cannot be converted into a value with data type MQTYPE_INT16.

  • 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 MQRC_PROP_NUMBER_FORMAT_ERROR.
  • If an application attempts a conversion that is not supported, IBM MQ returns reason code MQRC_PROP_CONV_NOT_SUPPORTED.
The specific rules for converting a property value from one data type to another are as follows:
  • When converting an MQTYPE_BOOLEAN 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 an MQTYPE_BOOLEAN 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 an MQTYPE_BOOLEAN 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 MQRC_PROP_NUMBER_FORMAT_ERROR.

  • When converting a string property value to a value with data type MQTYPE_INT8, MQTYPE_INT16, MQTYPE_INT32 or MQTYPE_INT64, 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 MQRC_PROP_NUMBER_FORMAT_ERROR if the string is not formatted correctly.

  • When converting a string property value to a value with data type MQTYPE_FLOAT32 or MQTYPE_FLOAT64, 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 MQRC_PROP_NUMBER_FORMAT_ERROR 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".
MQIMPO_QUERY_LENGTH
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
MQIMPO_INQ_FIRST
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 MQIMPO_INQ_PROP_UNDER_CURSOR 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:
  • MQIMPO_INQ_NEXT
  • MQIMPO_INQ_PROP_UNDER_CURSOR
MQIMPO_INQ_NEXT
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 MQIMPO_INQ_PROP_UNDER_CURSOR 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 MQIMPO_INQ_FIRST.

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:
  • MQIMPO_INQ_FIRST
  • MQIMPO_INQ_PROP_UNDER_CURSOR
MQIMPO_INQ_PROP_UNDER_CURSOR
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 MQIMPO_INQ_FIRST or the MQIMPO_INQ_NEXT 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 MQCC_FAILED and reason MQRC_PROPERTY_NOT_AVAILABLE.

This option is not valid with either of the following options:
  • MQIMPO_INQ_FIRST
  • MQIMPO_INQ_NEXT
If none of the options previously described is required, the following option can be used:
MQIMPO_NONE
Use this value to indicate that no other options have been specified; all options assume their default values.

MQIMPO_NONE 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 MQIMPO_INQ_FIRST.