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 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 Messages and 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.

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.

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