MQMHBUF - Convert message handle into buffer
The MQMHBUF call converts a message handle into a buffer and is the inverse of the MQBUFMH call.
Syntax
MQMHBUF (Hconn, Hmsg, MsgHBufOpts, Name, MsgDesc, BufferLength, Buffer, 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, a valid connection must be established on the thread deleting the message handle. If a valid connection is not established, the call fails with MQRC_CONNECTION_BROKEN.
- Hmsg
- Type: MQHMSG - input
This is the message handle for which a buffer is required. The value was returned by a previous MQCRTMH call.
- MsgHBufOpts
- Type: MQMHBO - input
The MQMHBO structure allows applications to specify options that control how buffers are produced from message handles.
See MQMHBO - Message handle to buffer options for details.
- Name
- Type: MQCHARV - input
The name of the property or properties to put into the buffer.
If no property matching the name can be found, the call fails with MQRC_PROPERTY_NOT_AVAILABLE.
We can use a wildcard to put more than one property into the buffer. To do this, use the wildcard character '%' at the end of the property name. This wildcard matches zero or more characters, including the '.' character.
In the C programming language, the following macro variables are defined for inquiring on all properties and all properties that begin 'usr':- MQPROP_INQUIRE_ALL
- Put all properties of the message into the buffer
- MQPROP_INQUIRE_ALL_USR
- Put all properties of the message that start with the characters 'usr.' into the buffer.
See Property names and Property name restrictions for further information about the use of property names.
- MsgDesc
- Type: MQMD - input/output
The MsgDesc structure describes the contents of the buffer area.
On output, the Encoding, CodedCharSetId and Format fields are set to correctly describe the encoding, character set identifier, and format of the data in the buffer area as written by the call.
Data in this structure is in the character set and encoding of the application.
- BufferLength
- Type: MQLONG - input
BufferLength is the length of the Buffer area, in bytes.
- Buffer
- Type: MQBYTExBufferLength - output
Buffer defines the area to contain the message properties. You must align the buffer on a 4-byte boundary.
If BufferLength is less than the length required to store the properties in Buffer, MQMHBUF fails with MQRC_PROPERTY_VALUE_TOO_BIG.
The contents of the buffer can change even if the call fails.
- DataLength
- Type: MQLONG - output
DataLength is the length, in bytes, of the returned properties in the buffer. If the value is zero, no properties matched the value given in Name and the call fails with reason code MQRC_PROPERTY_NOT_AVAILABLE.
If BufferLength is less than the length required to store the properties in the buffer, the MQMHBUF call fails with MQRC_PROPERTY_VALUE_TOO_BIG, but a value is still entered into DataLength. This allows the application to determine the size of the buffer required to accommodate the properties, and then reissue the call with the required BufferLength.
- CompCode
- Type: MQLONG - output
The completion code; it is one of the following:
- MQCC_OK
- Successful completion.
- MQCC_FAILED
- Call failed.
- Reason
- Type: MQLONG - output
The reason code qualifying CompCode.
If CompCode is MQCC_OK:- MQRC_NONE
- (0, X'000') No reason to report.
If CompCode is MQCC_FAILED:
- MQRC_ADAPTER_NOT_AVAILABLE
- (2204, X'089C') Adapter not available.
- MQRC_ADAPTER_SERV_LOAD_ERROR
- (2130, X'852') Unable to load adapter service module.
- MQRC_ASID_MISMATCH
- (2157, X'86D') Primary and home ASIDs differ.
- MQRC_MHBO_ERROR
- (2501, X'095C') Message handle to buffer options structure not valid.
- MQRC_BUFFER_ERROR
- (2004, X'07D4') Buffer parameter not valid.
- MQRC_BUFFER_LENGTH_ERROR
- (2005, X'07D5') Buffer 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_HMSG_ERROR
- (2460, X'099C') Message handle not valid.
- MQRC_MD_ERROR
- (2026, X'07EA') Message descriptor not valid.
- MQRC_MSG_HANDLE_IN_USE
- (2499, X'09C3') Message handle already in use.
- MQRC_OPTIONS_ERROR
- (2046, X'07FE') Options not valid or not consistent.
- MQRC_PROPERTY_NAME_ERROR
- (2442, X'098A') Property name is not valid.
- MQRC_PROPERTY_NOT_AVAILABLE
- (2471, X'09A7') Property not available.
- MQRC_PROPERTY_VALUE_TOO_BIG
- (2469, X'09A5') BufferLength value is too small to contain specified properties.
- MQRC_UNEXPECTED_ERROR
- (2195, X'893') Unexpected error occurred.
For detailed information about these codes, see Reason codes.
C invocation
MQMHBUF (Hconn, Hmsg, &MsgHBufOpts, &Name, &MsgDesc, BufferLength, Buffer,
&DataLength, &CompCode, &Reason);
Declare the parameters as follows:
MQHCONN Hconn; /* Connection handle */ MQHMSG Hmsg; /* Message handle */ MQMHBO MsgHBufOpts; /* Options that control the action of MQMHBUF */ MQCHARV Name; /* Property name */ MQMD MsgDesc; /* Message descriptor */ MQLONG BufferLength; /* Length in bytes of the Buffer area */ MQBYTE Buffer[n]; /* Area to contain the properties */ MQLONG DataLength; /* Length of the properties */ MQLONG CompCode; /* Completion code */ MQLONG Reason; /* Reason code qualifying CompCode */
Usage notes
MQMHBUF converts a message handle into a buffer.
We can use it with an MQGET API exit to access certain properties, using the message property APIs, and then pass these in a buffer back to an application designed to use MQRFH2 headers rather than message handles.
This call is the inverse of the MQBUFMH call, which we can use to parse message properties from a buffer into a message handle.
COBOL invocation
CALL 'MQMHBUF' USING HCONN, HMSG, MSGHBUFOPTS, NAME, MSGDESC,
BUFFERLENGTH, BUFFER, 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 MQMHBUF
01 MSGHBUFOPTS.
COPY CMQMHBOV.
** Property name
01 NAME
COPY CMQCHRVV.
** Message descriptor
01 MSGDESC
COPY CMQMDV.
** Length in bytes of the Buffer area */
01 BUFFERLENGTH PIC S9(9) BINARY.
** Area to contain the properties
01 BUFFER PIC X(n).
** Length of the properties
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 MQMHBUF (Hconn, Hmsg, MsgHBufOpts, Name, MsgDesc, BufferLength, Buffer, DataLength, CompCode, Reason);Declare the parameters as follows:
dcl Hconn fixed bin(31); /* Connection handle */ dcl Hmsg fixed bin(63); /* Message handle */ dcl MsgHBufOpts like MQMHBO; /* Options that control the action of MQMHBUF */ dcl Name like MQCHARV; /* Property name */ dcl MsgDesc like MQMD; /* Message descriptor */ dcl BufferLength fixed bin(31); /* Length in bytes of the Buffer area */ dcl Buffer char(n); /* Area to contain the properties */ dcl DataLength fixed bin(31); /* Length of the properties */ dcl CompCode fixed bin(31); /* Completion code */ dcl Reason fixed bin(31); /* Reason code qualifying CompCode */
High Level Assembler invocation
CALL MQMHBUF,(HCONN,HMSG,MSGHBUFOPTS,NAME,MSGDESC,BUFFERLENGTH,
BUFFER,DATALENGTH,COMPCODE,REASON)
Declare the parameters as follows:
HCONN DS F Connection handle HMSG DS D Message handle MSGHBUFOPTS CMQMHBOA , Options that control the action of MQMHBUF NAME CMQCHRVA , Property name MSGDESC CMQMDA , Message descriptor BUFFERLENGTH DS F Length in bytes of the BUFFER area BUFFER DS CL(n) Area to contain the properties DATALENGTH DS F Length of the properties COMPCODE DS F Completion code REASON DS F Reason code qualifying COMPCODE