MQCRTMH (Create message handle) on IBM i

The MQCRTMH call returns a message handle.

• 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 the properties 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 by using the message handle when the MQGET call completes.

Use MQDLTMH to delete the message handle.

• Syntax
• Parameters
• RPG Declaration

Syntax

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

Parameters

The MQCRTMH call has the following parameters:

HCONN (10-digit signed integer) - 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:

HCUNAS

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 RC2018.

CRTOPT (MQCMHO) - input

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

HMSG (20-digit signed integer) - 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 message descriptor contains the default values. The values of the associated message descriptor fields can be set and inquired by 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 HCUNAS then the returned message handle can be used on MQGET, MQPUT, or MQPUT1 calls with any connection within the unit of processing, but can be in use by only 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 RC2499.

If the HCONN parameter is not HCUNAS then the returned message handle can be used only 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.

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.

RC2219

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

RC2461

(2461, X'099D') Create message handle options structure not valid.

RC2273

(2273, X'7D9') Connection to queue manager lost.

RC2017

(2017, X'07E1') No more handles available.

RC2018

(2018, X'7E2') Connection handle not valid.

RC2460

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

RC2046

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

RC2071

(2071, X'817') Insufficient storage available.

RC2195

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

See Return codes for IBM i (ILE RPG) for more details.

RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQCRTMH(HCONN : CRTOPT : HMSG :
                                             CMPCOD : REASON)

     DMQCRTMH          PR                  EXTPROC('MQCRTMH')
     D* Connection handle 
     D HCONN                         10I 0 VALUE
     D* Options that control the action of MQCRTMH 
     D CRTOPT                        12A   
     D* Message handle 
     D HMSG                          20I 0 
     D* Completion code 
     D CMPCOD                        10I 0 
     D* Reason code qualifying CompCode 
     D REASON                        10I 0