CallType (MQLONG)

Field containing information about why this function has been called; the following values are defined.

Message delivery call types: These call types contain information about a message. The DataLength and BufferLength parameters are valid for these call types.

    MQCBCT_MSG_REMOVED
    The message consumer function has been invoked with a message that has been destructively removed from the object handle.

    If the value of CompCode is MQCC_WARNING, the value of the Reason field is MQRC_TRUNCATED_MSG_ACCEPTED or one of the codes indicating a data conversion problem.

    MQCBCT_MSG_NOT_REMOVED
    The message consumer function has been invoked with a message that has not yet been destructively removed from the object handle. The message can be destructively removed from the object handle using the MsgToken. The message might not have been removed because:

    • The MQGMO options requested a browse operation, MQGMO_BROWSE_*
    • The message is larger than the available buffer and the MQGMO options do not specify MQGMO_ACCEPT_TRUNCATED_MSG

    If the value of CompCode is MQCC_WARNING, the value of the Reason field is MQRC_TRUNCATED_MSG_FAILED or one of the codes indicating a data conversion problem.

Callback control call types: These call types contain information about the control of the callback and do not contain details about a message. These call types are requested using Options in the MQCBD structure.

The DataLength and BufferLength parameters are not valid for these call types.

    MQCBCT_REGISTER_CALL
    The purpose of this call type is to allow the callback function to perform some initial setup.

    The callback function is invoked is immediately after the callback is registered, that is, upon return from an MQCB call using a value for the Operation field of MQOP_REGISTER.

    This call type is used both for message consumers and event handlers.

    If requested, this is the first invocation of the callback function.

    The value of the Reason field is MQRC_NONE.

    MQCBCT_START_CALL
    The purpose of this call type is to allow the callback function to perform some setup when it is started, for example, reinstating resources that were cleaned up when it was previously stopped.

    The callback function is invoked when the connection is started using either MQOP_START or MQOP_START_WAIT.

    If a callback function is registered within another callback function, this call type is invoked when the callback returns.

    This call type is used for message consumers only.

    The value of the Reason field is MQRC_NONE.

    MQCBCT_STOP_CALL
    The purpose of this call type is to allow the callback function to perform some cleanup when it is stopped for a while, for example, cleaning up additional resources that have been acquired during the consuming of messages.

    The callback function is invoked when an MQCTL call is issued using a value for the Operation field of MQOP_STOP.

    This call type is used for message consumers only.

    The value of the Reason field is set to indicate the reason for stopping.

    MQCBCT_DEREGISTER_CALL
    The purpose of this call type is to allow the callback function to perform final cleanup at the end of the consume process. The callback function is invoked when the:

    • Callback function is deregistered using an MQCB call with MQOP_DEREGISTER.
    • Queue is closed, causing an implicit deregister. In this instance the callback function is passed MQHO_UNUSABLE_HOBJ as the object handle.
    • MQDISC call completes - causing an implicit close and, therefore, a deregister. In this case the connection is not disconnected immediately, and any ongoing transaction is not yet committed.

    If any of these actions are taken inside the callback function itself, the action is invoked once the callback returns.

    This call type is used both for message consumers and event handlers.

    If requested, this is the last invocation of the callback function.

    The value of the Reason field is set to indicate the reason for stopping.

    MQCBCT_EVENT_CALL
    Event handler function

    The event handler function has been invoked without a message when the queue manager or connection stops or quiesces.

    This call can be used to take appropriate action for all callback functions.

    Message consumer function

    The message consumer function has been invoked without a message when an error (CompCode = MQCC_FAILED) has been detected that is specific to the object handle; for example Reason code = MQRC_GET_INHIBITED.

    The value of the Reason field is set to indicate the reason for the call.

    MQCBCT_MC_EVENT_CALL

    The event handler function has been invoked for multicast events; The event handler is sent IBM MQ Multicast events instead of 'normal' IBM MQ events.

    For more information about MQCBCT_MC_EVENT_CALL, see Multicast exception reporting.

Parent topic: Fields for MQCBC