MQCRTMH - Create message handle

The MQCRTMH call returns a message handle.

An application can use the MQCRTMH call on subsequent message queuing calls:

  • Use the MQSETMP call to set a property of the message handle.
  • Use the MQINQMP call to inquire on the value of a property of the message handle.
  • Use the MQDLTMP call to delete a property of the message handle.

The message handle can be used on the MQPUT and MQPUT1 calls to associate the properties of the message handle with those of the message being put. Similarly by specifying a message handle on the MQGET call, the properties of the message being retrieved can be accessed using the message handle when the MQGET call completes.

Use MQDLTMH to delete the message handle.

Syntax

MQCRTMH (Hconn, CrtMsgHOpts, Hmsg, CompCode, Reason)

Parameters

Hconn
Type: MQHCONN - input

This handle represents the connection to the queue manager. The value of Hconn was returned by a previous MQCONN or MQCONNX call. If the connection to the queue manager ceases to be valid and no IBM® MQ call is operating on the message handle, MQDLTMH is implicitly called to delete the message.

Alternatively, you can specify the following value:
MQHC_UNASSOCIATED_HCONN
The connection handle does not represent a connection to any particular queue manager.

When this value is used, the message handle must be deleted with an explicit call to MQDLTMH in order to release any storage allocated to it; IBM MQ never implicitly deletes the message handle.

There must be at least one valid connection to a queue manager established on the thread creating the message handle, otherwise the call fails with MQRC_HCONN_ERROR.

In an environment with multiple installations on a single system, the MQHC_UNASSOCIATED_HCONN value is limited to use with the first installation loaded into the process. The reason code MQRC_HMSG_NOT_AVAILABLE is returned if the message handle is supplied to a different installation.

On z/OS® for CICS® applications the MQCONN call can be omitted, and you can specify the following value for Hconn :
MQHC_DEF_CONN
Default connection handle
CrtMsgHOpts
Type: MQCMHO - input

The options that control the action of MQCRTMH. See MQCMHO for details.

Hmsg
Type: MQHMSG - output

On output a message handle is returned that can be used to set, inquire, and delete properties of the message handle. Initially the message handle contains no properties.

A message handle also has an associated message descriptor. Initially this contains the default values. The values of the associated message descriptor fields can be set and inquired using the MQSETMP and MQINQMP calls. The MQDLTMP call resets a field of the message descriptor back to its default value.

If the Hconn parameter is specified as the value MQHC_UNASSOCIATED_HCONN then the returned message handle can be used on MQGET, MQPUT, or MQPUT1 calls with any connection within the unit of processing, but can only be in use by one IBM MQ call at a time. If the handle is in use when a second IBM MQ call attempts to use the same message handle, the second IBM MQ call fails with reason code MQRC_MSG_HANDLE_IN_USE.

If the Hconn parameter is not MQHC_UNASSOCIATED_HCONN then the returned message handle can only be used on the specified connection.

The same Hconn parameter value must be used on the subsequent MQI calls where this message handle is used:
  • MQDLTMH
  • MQSETMP
  • MQINQMP
  • MQDLTMP
  • MQMHBUF
  • MQBUFMH

The returned message handle ceases to be valid when the MQDLTMH call is issued for the message handle, or when the unit of processing that defines the scope of the handle terminates. MQDLTMH is called implicitly if a specific connection is supplied when the message handle is created and the connection to the queue manager ceases to be valid, for example, if MQDBC is called.

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_CALL_IN_PROGRESS
(2219, X'08AB') MQI call entered before previous call completed.
MQRC_CMHO_ERROR
(2461, X'099D') Create message handle options structure not valid.
MQRC_CONNECTION_BROKEN
(2273, X'7D9') Connection to queue manager lost.
MQRC_HANDLE_NOT_AVAILABLE
(2017, X'07E1') No more handles available.
MQRC_HCONN_ERROR
(2018, X'7E2') Connection handle not valid.
MQRC_HMSG_ERROR
(2460, X'099C') Message handle pointer not valid.
MQRC_OPTIONS_ERROR
(2046, X'07FE') Options not valid or not consistent.
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') Insufficient storage available.
MQRC_UNEXPECTED_ERROR
(2195, X'893') Unexpected error occurred.

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

C


MQCRTMH (Hconn, &CrtMsgHOpts, &Hmsg, &CompCode, &Reason);
Declare the parameters as follows: 

MQHCONN  Hconn;       /* Connection handle */
MQCMHO   CrtMsgHOpts; /* Options that control the action of MQCRTMH */
MQHMSG   Hmsg;        /* Message handle */
MQLONG   CompCode;    /* Completion code */
MQLONG   Reason;      /* Reason code qualifying CompCode */

COBOL


CALL 'MQCRTMH' USING HCONN, CRTMSGHOPTS, HMSG, COMPCODE, REASON.
Declare the parameters as follows: 

**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Options that control the action of MQCRTMH
 01  CRTMSGHOPTS.
     COPY CMQCMHOV.
**   Message handle
 01  HMSG    PIC S9(18) BINARY.
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.

PL/I


call MQCRTMH (Hconn, CrtMsgHOpts, Hmsg, CompCode, Reason);
Declare the parameters as follows: 

dcl Hconn       fixed bin(31);  /* Connection handle */
dcl CrtMsgHOpts like MQCMHO;    /* Options that control the action of MQCRTMH */
dcl Hmsg        fixed bin(63);  /* Message handle */
dcl CompCode    fixed bin(31);  /* Completion code */
dcl Reason      fixed bin(31);  /* Reason code qualifying CompCode */

High Level Assembler


CALL MQCRTMH,(HCONN,CRTMSGHOPTS,HMSG,COMPCODE,REASON)
Declare the parameters as follows: 

HCONN          DS        F  Connection handle
CRTMSGHOPTS    CMQCMHOA  ,  Options that control the action of MQCRTMH
HMSG           DS        D  Message handle
COMPCODE       DS        F  Completion code
REASON         DS        F  Reason code qualifying COMPCODE