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, we 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 we 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: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 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, CRTMSGOPTS, 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 COMPCODEParent topic: Function calls