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.
You 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 theVSBufSize
field of theReturnedName
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:- Properties with the prefix "mqps." are returned as the IBM® MQ property name. For example, "MQTopicString" is the returned name rather than "mqps.Top"
- 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".
- Properties with the prefix "usr." are returned without that prefix, for example, "Color" is returned rather than "usr.Color".
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 you do not request type conversion, you 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 you 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.
IfCompCode
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.
IfCompCode
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 Messages and reason codes.
C invocation
MQINQMP (Hconn, Hmsg, &InqPropOpts, &Name, &PropDesc, &Type,
ValueLength, Value, &DataLength, &CompCode, &Reason);
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.
** 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);
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)
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