MQINQMP (Inquire message property) on IBM i

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

The MQINQMP call has the following parameters:

    HCONN (10-digit signed integer) - 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 HCUNAS then a valid connection must be established on the thread inquiring a property of the message handle, otherwise the call fails with RC2009.

    HMSG (20-digit signed integer) - input

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

    INQOPT (MQIMPO) - input

    See the MQIMPO data type for details.

    PRNAME (MQCHARV) - input

    This describes the name of the property to inquire.

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

    We can use the percent sign (%) character 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 IPINQF to get the first matching property and again with the option IPINQN to get the next matching property. When no more matching properties are available, the call fails with RC2471. 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 CCFAIL with reason RC2465.

    Properties that have known synonyms are returned as follows:
    1. Properties with the prefix "mqps." are returned with 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 RPG programming language, the following macro variables are defined for inquiring on all properties and all properties that begin "usr.":

      INQALL
      Inquire on all properties of the message.

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

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

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

    PRPDSC (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 (10-digit signed integer) - 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:

      TYPBOL
      A boolean.

      TYPBST
      a byte string.

      TYPI8
      An 8-bit signed integer.

      TYPI16
      A 16-bit signed integer.

      TYPI32
      A 32-bit signed integer.

      TYPI64
      A 64-bit signed integer.

      TYPF32
      A 32-bit floating-point number.

      TYPF64
      A 64-bit floating-point number.

      TYPSTR
      A character string.

      TYPNUL
      The property exists but has a null value.

    If the data type of the property value is not recognized then TYPSTR 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 IPTYP field of the IPOPT parameter. A warning completion code is returned with reason RC2467.

    Additionally, if the option IPCTYP is specified, conversion of the property value is requested. Use Type as an input to specify the data type that we want the property to be returned as. See the description of the IPCTYP option of the MQIMPO (Inquire message property options) on IBM i for details of data type conversion.

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

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

    VALLEN (10-digit signed integer) - 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 IPQLEN option has been specified; in this case no value is returned.

    VALUE (1-byte bit stringxVALLEN) - 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 might result in an error when the value is later accessed.

    If VALLEN 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 CCFAIL and reason RC2469.

    The character set of the data in VALUE is given by the IPRETCSI field in the INQOPT parameter. The encoding of the data in VALUE is given by the IPRETENC field in the INQOPT parameter.

    If the VALLEN parameter is zero, VALUE is not referred to.

    DATLEN (10-digit signed integer) - 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 entered 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 may also be returned.

    If the Type parameter is set to TYPSTR or TYPBST:

      VLEMP
      The property exists but contains no characters or bytes.

    CMPCOD (10-digit signed integer) - output
    The completion code; it is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    The reason code qualifying CompCode.

    If CMPCOD is CCOK:

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

    If CompCode is CCWARN:

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

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

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

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

    If CMPCOD is CCFAIL:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    For detailed information about these codes, see:


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQINQMP(HCONN : HMSG : INQOPT :
                                             PRNAME : PRPDSC : TYPE :
                                             VALLEN : VALUE : DATLEN :
                                             CMPCOD : REASON)
The prototype definition for the call is: 
     DMQINQMP          PR                  EXTPROC('MQINQMP')
     D* Connection handle 
     D HCONN                         10I 0 VALUE
     D* Message handle 
     D HMSG                          20I 0 VALUE
     D* Options that control the action of MQINQMP 
     D INQOPT                        72A
     D* Property name 
     D PRNAME                        32A
     D* Property descriptor 
     D PRPDSC                        24A   
     D* Property data type 
     D TYPE                          10I 0 
     D* Length in bytes of the Value area 
     D VALLEN                        10I 0 VALUE
     D* Property value 
     D VALUE                           *   VALUE
     D* Length of the property value 
     D DATLEN                        10I 0 
     D* Completion code 
     D CMPCOD                        10I 0 
     D* Reason code qualifying CompCode 
     D REASON                        10I 0
Parent topic: Function calls on IBM i