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.
You 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
andFormat
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 inBuffer
, 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 inName
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 intoDataLength
. This allows the application to determine the size of the buffer required to accommodate the properties, and then reissue the call with the requiredBufferLength
. - 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
.IfCompCode
is MQCC_OK:- MQRC_NONE
- (0, X'000') No reason to report.
IfCompCode
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 Messages and reason codes.
C invocation
MQMHBUF (Hconn, Hmsg, &MsgHBufOpts, &Name, &MsgDesc, BufferLength, Buffer,
&DataLength, &CompCode, &Reason);
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.
You 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 you 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.
** 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);
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)
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