MQINQMP - Inquire message property

The MQINQMP call returns the value of a property of a message.


Syntax

MQINQMP (Hconn, Hmsg, InqPropOpts, Name, PropDesc, Type, ValueLength, Value, DataLength, CompCode, Reason)


Parameters

    Hconn
    Type: MQHCONN - input

    This handle represents the connection to the queue manager. The value of Hconn must match the connection handle that was used to create the message handle specified in the Hmsg parameter.

    If the message handle was created using MQHC_UNASSOCIATED_HCONN then a valid connection must be established on the thread inquiring a property of the message handle otherwise the call fails with MQRC_CONNECTION_BROKEN.

    Hmsg
    Type: MQHMSG - input

    This is the message handle to be inquired. The value was returned by a previous MQCRTMH call.

    InqPropOpts
    Type: MQIMPO - input/output

    See the MQIMPO data type for details.

    Name
    Type: MQCHARV - input/output

    The name of the property to inquire.

    If no property with this name can be found, the call fails with reason MQRC_PROPERTY_NOT_AVAILABLE.

    We can use the wildcard character percent sign (%) at the end of the property name. The wildcard matches zero or more characters, including the period (.) character. This allows an application to inquire the value of many properties. Call MQINQMP with option MQIMPO_INQ_FIRST to get the first matching property and again with the option MQIMPO_INQ_NEXT to get the next matching property. When no more matching properties are available, the call fails with MQRC_PROPERTY_NOT_AVAILABLE. If the ReturnedName field of the InqPropOpts structure is initialized with an address or offset for the returned name of the property, this is completed on return from MQINQMP with the name of the property that has been matched. If the VSBufSize field of the ReturnedName in the InqPropOpts structure is less than the length of the returned property name the completion code is set MQCC_FAILED with reason MQRC_PROPERTY_NAME_TOO_BIG.

    Properties that have known synonyms are returned as follows:
    1. Properties with the prefix "mqps." are returned as the IBM MQ property name. For example, "MQTopicString" is the returned name rather than "mqps.Top"
    2. Properties with the prefix "jms." or "mcd." are returned as the JMS header field name, for example, "JMSExpiration" is the returned name rather than "jms.Exp".
    3. Properties with the prefix "usr." are returned without that prefix, for example, "Color" is returned rather than "usr.Color".
    Properties with synonyms are only returned once.

    In the C programming language, the following macro variables are defined for inquiring on all properties and then all properties that begin "usr.":

      MQPROP_INQUIRE_ALL
      Inquire on all properties of the message. MQPROP_INQUIRE_ALL can be used in the following way: 
      MQCHARV Name = {MQPROP_INQUIRE_ALL};

      MQPROP_INQUIRE_ALL_USR
      Inquire on all properties of the message that start "usr.". The returned name is returned without the "usr." prefix.

    If MQIMP_INQ_NEXT is specified but Name has changed since the previous call or this is the first call, then MQIMPO_INQ_FIRST is implied.

    See Property names and Property name restrictions for further information about the use of property names.

    PropDesc
    Type: MQPD - output

    This structure is used to define the attributes of a property, including what happens if the property is not supported, what message context the property belongs to, and what messages the property should be copied into. See MQPD for details of this structure.

    Type
    Type: MQLONG - input/output

    On return from the MQINQMP call this parameter is set to the data type of Value. The data type can be any of the following:

      MQTYPE_BOOLEAN
      A boolean.

      MQTYPE_BYTE_STRING
      a byte string.

      MQTYPE_INT8
      An 8-bit signed integer.

      MQTYPE_INT16
      A 16-bit signed integer.

      MQTYPE_INT32
      A 32-bit signed integer.

      MQTYPE_INT64
      A 64-bit signed integer.

      MQTYPE_FLOAT32
      A 32-bit floating-point number.

      MQTYPE_FLOAT64
      A 64-bit floating-point number.

      MQTYPE_STRING
      A character string.

      MQTYPE_NULL
      The property exists but has a null value.

    If the data type of the property value is not recognized then MQTYPE_STRING is returned and a string representation of the value is placed into the Value area. A string representation of the data type can be found in the TypeString field of the InqPropOpts parameter. A warning completion code is returned with reason MQRC_PROP_TYPE_NOT_SUPPORTED.

    Additionally, if the option MQIMPO_CONVERT_TYPE is specified, conversion of the property value is requested. Use Type as an input to specify the data type that you want the property to be returned as. See the description of the MQIMPO_CONVERT_TYPE option of the MQIMPO structure for details of data type conversion.

    If we do not request type conversion, we can use the following value on input:

      MQTYPE_AS_SET
      The value of the property is returned without converting its data type.

    ValueLength
    Type: MQLONG - input

    The length in bytes of the Value area. Specify zero for properties that we do not require the value returned for. These could be properties which are designed by an application to have a null value or an empty string. Also specify zero if the MQIMPO_QUERY_LENGTH option has been specified; in this case no value is returned.

    Value
    Type: MQBYTEx ValueLength - output

    This is the area to contain the inquired property value. The buffer should be aligned on a boundary appropriate for the value being returned. Failure to do so can result in an error when the value is later accessed.

    If ValueLength is less than the length of the property value, as much of the property value as possible is moved into Value and the call fails with completion code MQCC_FAILED and reason MQRC_PROPERTY_VALUE_TOO_BIG.

    The character set of the data in Value is given by the ReturnedCCSID field in the InqPropOpts parameter. The encoding of the data in Value is given by the ReturnedEncoding field in the InqPropOpts parameter.

    In the C programming language, the parameter is declared as a pointer-to-void; the address of any type of data can be specified as the parameter.

    If the ValueLength parameter is zero, Value is not referred to and its value passed by programs written in C or System/390 assembler can be null.

    DataLength
    Type: MQLONG - output

    This is the length in bytes of the actual property value as returned in the Value area.

    If DataLength is less than the property value length, DataLength is still filled in on return from the MQINQMP call. This allows the application to determine the size of the buffer required to accommodate the property value, and then reissue the call with a buffer of the appropriate size.

    The following values can also be returned.

    If the Type parameter is set to MQTYPE_STRING or MQTYPE_BYTE_STRING:

      MQVL_EMPTY_STRING
      The property exists but contains no characters or bytes.

    CompCode
    Type: MQLONG - output The completion code; it is one of the following:

      MQCC_OK
      Successful completion.

      MQCC_WARNING
      Warning (partial completion).

      MQCC_FAILED
      Call failed.

    Reason
    Type: MQLONG - output If CompCode is MQCC_OK:

      MQRC_NONE
      (0, X'000') No reason to report.

    If CompCode is MQCC_WARNING:

      MQRC_PROP_NAME_NOT_CONVERTED
      (2492, X'09BC') Returned property name not converted.

      MQRC_PROP_VALUE_NOT_CONVERTED
      (2466, X'09A2') Property value not converted.

      MQRC_PROP_TYPE_NOT_SUPPORTED
      (2467, X'09A3') Property data type is not supported.

      MQRC_RFH_FORMAT_ERROR
      (2421, X'0975') An MQRFH2 folder containing properties could not be parsed.

    If CompCode is MQCC_FAILED:

      MQRC_ADAPTER_NOT_AVAILABLE
      (2204, X'089C') Adapter not available.

      MQRC_ADAPTER_SERV_LOAD_ERROR
      (2130, X'0852') Unable to load adapter service module.

      MQRC_ASID_MISMATCH
      (2157, X'086D') Primary and home ASIDs differ.

      MQRC_BUFFER_ERROR
      (2004, X'07D4') Value parameter not valid.

      MQRC_BUFFER_LENGTH_ERROR
      (2005, X'07D5') Value length parameter not valid.

      MQRC_CALL_IN_PROGRESS
      (2219, X'08AB') MQI call entered before previous call completed.

      MQRC_CONNECTION_BROKEN
      (2009, X'07D9') Connection to queue manager lost.

      MQRC_DATA_LENGTH_ERROR
      (2010, X'07DA') Data length parameter not valid.

      MQRC_IMPO_ERROR
      (2464, X'09A0') Inquire message property options structure not valid.

      MQRC_HMSG_ERROR
      (2460, X'099C') Message handle not valid.

      MQRC_MSG_HANDLE_IN_USE
      (2499, X'09C3') Message handle already in use.

      MQRC_OPTIONS_ERROR
      (2046, X'07F8') Options not valid or not consistent.

      MQRC_PD_ERROR
      (2482, X'09B2') Property descriptor structure not valid.

      MQRC_PROP_CONV_NOT_SUPPORTED
      (2470, X'09A6') Conversion from the actual to requested data type not supported.

      MQRC_PROPERTY_NAME_ERROR
      (2442, X'098A') Invalid property name.

      MQRC_PROPERTY_NAME_TOO_BIG
      (2465, X'09A1') Property name too large for returned name buffer.

      MQRC_PROPERTY_NOT_AVAILABLE
      (2471, X'09A7) Property not available.

      MQRC_PROPERTY_VALUE_TOO_BIG
      (2469, X'09A5') Property value too large for the Value area.

      MQRC_PROP_NUMBER_FORMAT_ERROR
      (2472, X'09A8') Number format error encountered in value data.

      MQRC_PROPERTY_TYPE_ERROR
      (2473, X'09A9') Invalid requested property type.

      MQRC_SOURCE_CCSID_ERROR
      (2111, X'083F') Property name coded character set identifier not valid.

      MQRC_STORAGE_NOT_AVAILABLE
      (2071, X'0871') Insufficient storage available.

      MQRC_UNEXPECTED_ERROR
      (2195, X'0893') Unexpected error occurred.

    For detailed information about these codes, see Reason codes.


C invocation

MQINQMP (Hconn, Hmsg, &InqPropOpts, &Name, &PropDesc, &Type,
ValueLength, Value, &DataLength, &CompCode, &Reason);
Declare the parameters as follows: 
MQHCONN Hconn;       /* Connection handle */
MQHMSG  Hmsg;        /* Message handle */
MQIMPO  InqPropOpts; /* Options that control the action of MQINQMP */
MQCHARV Name;        /* Property name */
MQPD    PropDesc;    /* Property descriptor */
MQLONG  Type;        /* Property data type */
MQLONG  ValueLength; /* Length in bytes of the Value area */
MQBYTE  Value[n];    /* Area to contain the property value */
MQLONG  DataLength;  /* Length of the property value */
MQLONG  CompCode;    /* Completion code */
MQLONG  Reason;      /* Reason code qualifying CompCode */


COBOL invocation

CALL 'MQINQMP' USING HCONN, HMSG, INQMSGOPTS, NAME, PROPDESC, TYPE,
VALUELENGTH, VALUE, DATALENGTH, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN       PIC S9(9) BINARY.
**   Message handle
 01  HMSG		    PIC S9(18) BINARY.
**   Options that control the action of MQINQMP
 01  INQMSGOPTS.
     COPY CMQIMPOV.
**   Property name
 01  NAME.
     COPY CMQCHRVV.
**   Property descriptor
 01  PROPDESC.
     COPY CMQPDV.
**   Property data type
 01  TYPE        PIC S9(9) BINARY.
**   Length in bytes of the VALUE area
 01  VALUELENGTH PIC S9(9) BINARY.
**   Area to contain the property value
 01  VALUE       PIC X(n).
**   Length of the property value
 01  DATALENGTH  PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE    PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON      PIC S9(9) BINARY.


PL/I invocation

call MQINQMP (Hconn, Hmsg, InqPropOpts, Name, PropDesc, Type,
ValueLength, Value, DataLength, CompCode, Reason);
Declare the parameters as follows: 
dcl Hconn       fixed bin(31);  /* Connection handle */
dcl Hmsg        fixed bin(63);  /* Message handle */
dcl InqPropOpts like MQIMPO;    /* Options that control the action of MQINQMP */
dcl Name        like MQCHARV;   /* Property name */
dcl PropDesc    like MQPD;      /* Property descriptor */
dcl Type        fixed bin (31); /* Property data type */
dcl ValueLength fixed bin (31); /* Length in bytes of the Value area */
dcl Value       char (n);       /* Area to contain the property value */
dcl DataLength  fixed bin (31); /* Length of the property value */
dcl CompCode    fixed bin (31); /* Completion code */
dcl Reason      fixed bin (31); /* Reason code qualifying CompCode */


High Level Assembler invocation

CALL MQINQMP,(HCONN,HMSG,INQMSGOPTS,NAME,PROPDESC,TYPE,
VALUELENGTH,VALUE,DATALENGTH,COMPCODE,REASON)
Declare the parameters as follows: 
HCONN        DS         F     Connection handle
HMSG         DS         D     Message handle
INQMSGOPTS   CMQIMPOA   ,     Options that control the action of MQINQMP
NAME         CMQCHRVA   ,     Property name
PROPDESC     CMQPDA     ,     Property descriptor
TYPE         DS         F     Property data type
VALUELENGTH  DS         F     Length in bytes of the VALUE area
VALUE        DS         CL(n) Area to contain the property value
DATALENGTH   DS         F     Length of the property value
COMPCODE     DS         F     Completion code
REASON       DS         F     Reason code qualifying COMPCODE