MQBUFMH (Convert buffer into message handle) on IBM i

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
• Usage notes
• Parameters
• RPG Declaration

Syntax

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

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.

Parameters

The MQBUFMH call has the following parameters:

HCONN (10-digit signed integer) - 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 by using HCUNAS, 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 RC2009.

HMSG (20-digit signed integer) - input

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

BMHOPT (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) on IBM i for details.

MSGDSC (MQMD) - input/output

The MSGDSC 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.

BUFLEN (10-digit signed integer) - input

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

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

BUFFER (1-byte bit string x BUFLEN) - input/output

BUFFER defines the area containing the message buffer. For most data, we must align the buffer on a 4-byte boundary.

If BUFFER contains character or numeric data, set the CodedCharSetId and Encoding fields in the MSGDSC 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 BUFLEN 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.

DATLEN (10-digit signed integer) - output

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

CMPCOD (10-digit signed integer) - output

CCOK

Successful completion.

CCFAIL

Call failed.

REASON (10-digit signed integer) - output

The reason code qualifying CMPCOD.

If CMPCOD is CCOK:

RCNONE

(0, X'000') No reason to report.

If CMPCOD is CCFAIL:

RC2204

(2204, X'089C') Adapter not available.

RC2130

(2130, X'852') Unable to load adapter service module.

RC2157

(2157, X'86D') Primary and home ASIDs differ.

RC2489

(2489, X'09B9') Buffer to message handle options structure not valid.

RC2004

(2004, X'07D4') Buffer parameter not valid.

RC2005

(2005, X'07D5') Buffer length parameter not valid.

RC2219

(2219, X'08AB') MQI call entered before previous call completed.

RC2009

(2009, X'07D9') Connection to queue manager lost.

RC2460

(2460, X'099C') Message handle not valid.

RC2026

(2026, X'07EA') Message descriptor not valid.

RC2499

(2499, X'09C3') Message handle already in use.

RC2046

(2046, X'07FE') Options not valid or not consistent.

RC2334

(2334, X'091E') MQRFH2 structure not valid.

RC2421

(2421, X'0975') An MQRFH2 folder containing properties could not be parsed.

RC2195

(2195, X'893') Unexpected error occurred.

RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQBUFMH(HCONN : HMSG : BMHOPT :
                                             MSGDSC : BUFLEN : BUFFER :
                                             DATLEN : CMPCOD : REASON)

     DMQBUFMH          PR                  EXTPROC('MQBUFMH')
     D* Connection handle 
     D HCONN                         10I 0 
     D* Message handle 
     D HMSG                          10I 0 
     D* Options that control the action of MQBUFMH 
     D BMHOPT                        12A   VALUE
     D* Message descriptor 
     D MSGDSC                       364A   
     D* Length in bytes of the Buffer area 
     D BUFLEN                        10I 0 
     D* Area to contain the message buffer 
     D BUFFER                          *   VALUE
     D* Length of the output buffer 
     D DATLEN                        10I 0 
     D* Completion code 
     D CMPCOD                        10I 0 
     D* Reason code qualifying CompCode 
     D REASON                        10I 0