MQBUFMH - Convert buffer into message handle

The MQBUFMH function call converts a buffer into a message handle and is the inverse of the MQMHBUF call.

This call takes a message descriptor and MQRFH2 properties in the buffer and makes them available through a message handle. The MQRFH2 properties in the message data are, optionally, removed. The Encoding, CodedCharSetId, and Format fields of the message descriptor are updated, if necessary, to correctly describe the contents of the buffer after the properties have been removed.

Syntax

MQBUFMH (Hconn, Hmsg, BufMsgHOpts, 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 converting a buffer into a message handle. If a valid connection is not established, the call fails with MQRC_CONNECTION_BROKEN.

Hmsg

Type: MQHMQSG - input

This is the message handle for which a buffer is required. The value was returned by a previous MQCRTMH call.

BufMsgHOpts

Type: MQBMHO - input

The MQBMHO structure allows applications to specify options that control how message handles are produced from buffers.

See MQBMHO - Buffer to message handle options for details.

MsgDesc

Type: MQMD - input/output

The MsgDesc structure contains the message descriptor properties and describes the contents of the buffer area.

On output from the call, the properties are optionally removed from the buffer area and, in this case, the message descriptor is updated to correctly describe the buffer area.

Data in this structure must be in the character set and encoding of the application.

BufferLength

Type: MQLONG - input

BufferLength is the length of the Buffer area, in bytes.

A BufferLength of zero bytes is valid, and indicates that the buffer area contains no data.

Buffer

Type: MQBYTExBufferLength - input/output

These are options that control the action of MQBEGIN, as described in MQBEGIN - Begin unit of work.

Buffer defines the area containing the message buffer. For most data, you should align the buffer on a 4-byte boundary.

If Buffer contains character or numeric data, set the CodedCharSetId and Encoding fields in the MsgDesc parameter to the values appropriate to the data; this enables the data to be converted, if necessary.

If properties are found in the message buffer they are optionally removed; they later become available from the message handle on return from the call.

In the C programming language, the parameter is declared as a pointer-to-void, which means the address of any type of data can be specified as the parameter.

If the BufferLength parameter is zero, Buffer is not referred to; in this case, the parameter address passed by programs written in C or System/390 assembler can be null.

DataLength

Type: MQLONG - output

The length, in bytes, of the buffer which might have the properties removed.

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

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_BMHO_ERROR: (2489, X'09B9') Buffer to message handle 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_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_RFH_ERROR: (2334, X'091E') MQRFH2 structure not valid.
MQRC_RFH_FORMAT_ERROR: (2421, X'0975') An MQRFH2 folder containing properties could not be parsed.
MQRC_UNEXPECTED_ERROR: (2195, X'893') Unexpected error occurred.

For detailed information about these codes, see Messages and reason codes.

Usage notes

MQBUFMH calls cannot be intercepted by API exits - a buffer is converted into a message handle in the application space; the call does not reach the queue manager.

C invocation


MQBUFMH (Hconn, Hmsg, &BufMsgHOpts, &MsgDesc, BufferLength, Buffer,
         &DataLength, &CompCode, &Reason);

Declare the parameters as follows:


MQHCONN Hconn;        /* Connection handle */
MQHMSG  Hmsg;         /* Message handle */
MQBMHO  BufMsgHOpts;  /* Options that control the action of MQBUFMH */
MQMD    MsgDesc;      /* Message descriptor */
MQLONG  BufferLength; /* Length in bytes of the Buffer area */
MQBYTE  Buffer[n];    /* Area to contain the message buffer */
MQLONG  DataLength;   /* Length of the output buffer */
MQLONG  CompCode;     /* Completion code */
MQLONG  Reason;       /* Reason code qualifying CompCode */

COBOL invocation


CALL 'MQBUFMH' USING HCONN, HMSG, BUFMSGHOPTS, 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 MQBUFMH
 01  BUFMSGHOPTS.
     COPY CMQBMHOV.
**   Message descriptor
 01  MSGDESC.
     COPY CMQMD.
**   Length in bytes of the Buffer area
 01  BUFFERLENGTH  PIC S9(9) BINARY.
**   Area to contain the message buffer
 01  BUFFER        PIC X(n).
**   Length of the output buffer
 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 MQBUFMH (Hconn, Hmsg, BufMsgHOpts, 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 BufMsgHOpts  like MQBMHO;   /* Options that control the action of
                                   MQBUFMH */
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 message buffer */
dcl DataLength   fixed bin(31); /* Length of the output buffer */
dcl CompCode     fixed bin(31); /* Completion code */
dcl Reason       fixed bin(31); /* Reason code qualifying CompCode */

High Level Assembler invocation


CALL MQBUFMH,(HCONN,HMSG,BUFMSGHOPTS,MSGDESC,BUFFERLENGTH,BUFFER,
                DATALENGTH,COMPCODE,REASON)

Declare the parameters as follows:


HCONN        DS       F      Connection handle
HMSG         DS       D      Message handle
BUFMSGHOPTS  CMQBMHOA ,      Options that control the action of MQBUFMH
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 output buffer
COMPCODE     DS       F      Completion code
REASON       DS       F      Reason code qualifying COMPCODE