MQCB_FUNCTION - Callback function
The MQCB_FUNCTION function call is the callback function for event handling and asynchronous message consumption.
The MQCB_FUNCTION call definition is provided solely to describe the parameters that are passed to the callback function. No entry point called MQCB_FUNCTION is provided by the queue manager.The specification of the actual function to be called is an input to the MQCB call and is passed in through the MQCBD structure.
Syntax
MQCB_FUNCTION (Hconn, MsgDesc, GetMsgOpts, Buffer, Context)
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. On z/OS® for CICS® applications the MQCONN call can be omitted, and the following value specified for Hconn:
MQHC_DEF_CONN
Default connection handle.
- MsgDesc
- Type: MQMD - input
This structure describes the attributes of the message retrieved.
See MQMD - Message descriptor for details.
The version of MQMD passed is the same version as passed on the MQCB call that defined the consumer function.
The address of the MQMD is passed as null characters if a version 4 MQGMO was used to request that a Message Handle be returned instead of an MQMD.
This is an input field to the message consumer function; it is not relevant to an event handler function.
- GetMsgOpts
- Type: MQGMO - input
Options used to control the actions of the message consumer. This parameter also contains additional information about the message returned.
See MQGMO for details.
The version of MQGMO passed is the latest version supported.
This is an input field to the message consumer function; it is not relevant to an event handler function.
- Buffer
- Type: MQBYTExBufferLength - input
This is the area containing the message data.
If no message is available for this call, or if the message contains no message data, the address of the Buffer is passed as nulls.
This is an input field to the message consumer function; it is not relevant to an event handler function.
- Context
- Type: MQCBC - input/output
This structure provides context information to the callback functions. See MQCBC - Callback context for details.
Usage notes
- Be aware that if your callback routines use services that could delay or block the thread, for example, MQGET with wait, could delay the dispatch of other callbacks.
- A separate unit of work is not automatically established for each invocation of a callback routine, so routines can either issue a commit call, or defer committing, until a logical batch of work has been processed. When the batch of work is committed, it commits the messages for all callback functions that have been invoked since the last sync point.
- Programs invoked by CICS LINK or CICS START retrieve parameters using CICS services through named objects known as channel containers. The container names are the same as the parameter names. For more information, see your CICS documentation.
- Callback routines can issue an MQDISC call, but not for their own connection. For example, if a callback routine has created a connection, then it can also disconnect the connection.
- A callback routine should not, in general, rely on being invoked from the same thread each time. If required, use the MQCTLO_THREAD_AFFINITY when the connection is started.
- When a callback routine receives a nonzero reason code, it must take appropriate action.
- MQCB_FUNCTION is not supported within the IMS adapter.