MQMHBUF (Convert message handle into buffer) on IBM i

The MQMHBUF 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)


Usage notes

MQMHBUF converts a message handle into a buffer.

We can use it with an MQGET API exit to access certain properties, by using the message property APIs, and then pass these properties 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.


Parameters

The MQMHBUF 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 deleting the 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.

    MHBOPT (MQMHBO) - input

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

    See MQBMHO (Buffer to message handle options) on IBM i for details.

    PRNAME (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 RC2471.

    Wildcards

    We can use a wildcard to put more than one property into the buffer. To do so, use the percent sign (%) at the end of the property name. This wildcard matches zero or more characters, including the period (.) character.

    See Property names and Property name restrictions for further information about the use of property names.

    MSGDSC (MQMD) - input/output

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

    BUFLEN (10-digit signed integer) - input

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

    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 returned properties in the buffer. If the value is zero, no properties matched the value given in PRNAME and the call fails with reason code RC2471.

    If BUFLEN is less than the length required to store the properties in the buffer, the MQMHBUF call fails with RC2469, but a value is still entered into DATLEN. This allows the application to determine the size of the buffer required to accommodate the properties, and then reissue the call with the required BUFLEN.

    CMPCOD (10-digit signed integer) - output
    The completion code; it is one of the following:

      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.

      RC2501
      (2501, X'095C') Message handle to buffer 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.

      RC2010
      (2010, X'07DA') Data length parameter not valid.

      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.

      RC2442
      (2442, X'098A') Property name is not valid.

      RC2471
      (2471, X'09A7') Property not available.

      RC2469
      (2469, X'09A5') BufferLength value is too small to contain specified properties.

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


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQMHBUF(HCONN : HMSG : MHBOPT :
                                             PRNAME : MSGDSC : BUFLEN :
                                             BUFFER : DATLEN : 
                                             CMPCOD : REASON)
The prototype definition for the call is: 
     DMQMHBUF          PR                  EXTPROC('MQMHBUF')
     D* Connection handle 
     D HCONN                         10I 0 VALUE
     D* Message handle 
     D HMSG                          20I 0 VALUE
     D* Options that control the action of MQMHBUF 
     D MHBOPT                        12A
     D* Property name 
     D PRNAME                        32A
     D* Message descriptor 
     D MSGDSC                       364A   
     D* Length in bytes of the Buffer area 
     D BUFLEN                        10I 0 VALUE
     D* Area to contain the properties 
     D BUFFER                          *   VALUE
     D* Length of the properties 
     D DATLEN                        10I 0 
     D* Completion code 
     D CMPCOD                        10I 0 
     D* Reason code qualifying CompCode 
     D REASON                        10I 0
Parent topic: Function calls on IBM i