Field details for MQCBD

The MQCBD Callback descriptor structure is used to specify a callback function and the options controlling its use by the queue manager. The structure is an input parameter on the MQCB call.

StrucID (MQCHAR4)

This is the structure identifier of the callback descriptor structure. It is always an input field. Its value is MQCBD_STRUC_ID.

The value must be:

MQCBD_STRUC_ID: Identifier for callback descriptor structure.
For the C programming language, the constant MQCBD_STRUC_ID_ARRAY is also defined. This has the same value as MQCBD_STRUC_ID, but is an array of characters instead of a string.

Version (MQLONG)

This is the version number of the callback descriptor structure. It is always an input field.

The value must be:

MQCBD_VERSION_1: Version 1 callback descriptor structure.

The following constant specifies the version number of the current version:

MQCBD_CURRENT_VERSION: Current version of callback descriptor structure.

CallbackType (MQLONG)

Callback descriptor structure - CallbackType field.

This is the type of the callback function. The value must be one of:

MQCBT_MESSAGE_CONSUMER

Defines this callback as a message consumer function.

A message consumer callback function is called when a message, meeting the selection criteria specified, is available on an object handle and the connection is started.

MQCBT_EVENT_HANDLER

Defines this callback as the asynchronous event routine; it is not driven to consume messages for a handle.

Hobj is not required on the MQCB call defining the event handler and is ignored if specified.

The event handler is called for conditions that affect the whole message consumer environment. The consumer function is invoked without a message when an event, for example, a queue manager or connection stopping, or quiescing, occurs. It is not called for conditions that are specific to a single message consumer, for example, MQRC_GET_INHIBITED.

Events are delivered to the application, regardless of whether the connection is started or stopped, except in the following environments:

CICS® on z/OS® environment
nonthreaded applications

If the caller does not pass one of these values, the call fails with a Reason code of MQRC_CALLBACK_TYPE_ERROR

This is always an input field. The initial value of this field is MQCBT_MESSAGE_CONSUMER.

Options (MQLONG)

Callback descriptor structure - Options field

You can specify one or more of these options. To specify more than one option, either add the values together (do not add the same constant more than once), or combine the values using the bitwise OR operation (if the programming language supports bit operations).

MQCBDO_FAIL_IF_QUIESCING

The MQCB call fails if the queue manager is in the quiescing state.

On z/OS, this option also forces the MQCB call to fail if the connection (for a CICS or IMS application) is in the quiescing state.

Specify MQGMO_FAIL_IF_QUIESCING, in the MQGMO options passed on the MQCB call, to cause notification to message consumers when they are quiescing.

Control options: The following options control whether the callback function is called, without a message, when the state of the consumer changes:

MQCBDO_REGISTER_CALL: The callback function is invoked with call type MQCBCT_REGISTER_CALL.
MQCBDO_START_CALL: The callback function is invoked with call type MQCBCT_START_CALL.
MQCBDO_STOP_CALL: The callback function is invoked with call type MQCBCT_STOP_CALL.
MQCBDO_DEREGISTER_CALL: The callback function is invoked with call type MQCBCT_DEREGISTER_CALL.
MQCBDO_EVENT_CALL: The callback function is invoked with call type MQCBCT_EVENT_CALL.
MQCBDO_MC_EVENT_CALL: The callback function is invoked with call type MQCBCT_MC_EVENT_CALL.

See CallType for further details about these call types.

Default option: If you do not need any of the options described, use the following option:

MQCBDO_NONE: Use this value to indicate that no other options have been specified; all options assume their default values.
MQCBDO_NONE is defined to aid program documentation; it is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.

This is an input field. The initial value of the Options field is MQCBDO_NONE.

CallbackArea (MQPTR)

Callback descriptor structure - CallbackArea field

This is a field that is available for the callback function to use.

The queue manager makes no decisions based on the contents of this field and it is passed unchanged from the CallbackArea field in the MQCBC structure, which is a parameter on the callback function declaration.

The value is used only on an Operation having a value MQOP_REGISTER, with no currently defined callback, it does not replace a previous definition.

This is an input and output field to the callback function. The initial value of this field is a null pointer or null bytes.

CallbackFunction (MQPTR)

Callback descriptor structure - CallbackFunction field

The callback function is invoked as a function call.

Use this field to specify a pointer to the callback function.

You must specify either CallbackFunction or CallbackName. If you specify both, the reason code MQRC_CALLBACK_ROUTINE_ERROR is returned.

If neither CallbackName nor CallbackFunction is set, the call fails with the reason code MQRC_CALLBACK_ROUTINE_ERROR.

This option is not supported in the following environment: Programming languages and compilers that do not support function-pointer references. In such situations, the call fails with the reason code MQRC_CALLBACK_ROUTINE_ERROR.

On z/OS, the function must expect to be called with OS linkage conventions. For example, in the C programming language, specify:

#pragma linkage(MQCB_FUNCTION,OS)

This is an input field. The initial value of this field is a null pointer or null bytes.

CallbackName (MQCHAR128)

Callback descriptor structure - CallbackName field

The callback function is invoked as a dynamically linked program.

You must specify either CallbackFunction or CallbackName. If you specify both, the reason code MQRC_CALLBACK_ROUTINE_ERROR is returned.

If neither CallbackName nor CallbackFunction is not set, the call fails with the reason code MQRC_CALLBACK_ROUTINE_ERROR.

The module is loaded when the first callback routine to use is registered, and unloaded when the last callback routine to use it deregisters.

Except where noted in the following text, the name is left-justified within the field, with no embedded blanks; the name itself is padded with blanks to the length of the field. In the descriptions that follow, square brackets ([ ]) denote optional information:

IBM® i

The callback name can be one of the following formats:

Library "/" Program
Library "/" ServiceProgram "("FunctionName")"

For example, MyLibrary/MyProgram(MyFunction).

The library name can be *LIBL. Both the library and program names are limited to a maximum of 10 characters.

AIX® and Linux®

The callback name is the name of a dynamically-loadable module or library, suffixed with the name of a function residing in that library. The function name must be enclosed in parentheses. The library name can optionally be prefixed with a directory path:

[path]library(function)

If the path is not specified the system search path is used.

The name is limited to a maximum of 128 characters.

Windows

The callback name is the name of a dynamic-link library, suffixed with the name of a function residing in that library. The function name must be enclosed in parentheses .The library name can optionally be prefixed with a directory path and drive:

[d:][path]library(function)

If the drive and path are not specified the system search path is used.

The name is limited to a maximum of 128 characters.

z/OS

The callback name is the name of a load module that is valid for specification on the EP parameter of the LINK or LOAD macro.

The name is limited to a maximum of 8 characters.

z/OS CICS

The callback name is the name of a load module that is valid for specification on the PROGRAM parameter of the EXEC CICS LINK command macro.

The name is limited to a maximum of 8 characters.

The program can be defined as remote using the REMOTESYTEM option of the installed PROGRAM definition or by the dynamic routing program.

The remote CICS region must be connected to IBM MQ if the program is to use IBM MQ API calls. Note, however, that the Hobj field in the MQCBC structure is not valid in a remote system.

If a failure occurs trying to load CallbackName, one of the following error codes is returned to the application:

MQRC_MODULE_NOT_FOUND
MQRC_MODULE_INVALID
MQRC_MODULE_ENTRY_NOT_FOUND

A message is also written to the error log containing the name of the module for which the load was attempted, and the failing reason code from the operating system.

This is an input field. The initial value of this field is a null string or blanks.

MaxMsgLength (MQLONG)

This is the length in bytes of the longest message that can be read from the handle and given to the callback routine.

If a message has a longer length, the callback routine receives MaxMsgLength bytes of the message, and reason code:

MQRC_TRUNCATED_MSG_FAILED or
MQRC_TRUNCATED_MSG_ACCEPTED if you specified MQGMO_ACCEPT_TRUNCATED_MSG.

The actual message length is supplied in the DataLength field of the MQCBC structure.

The following special value is defined:

MQCBD_FULL_MSG_LENGTH

The buffer length is adjusted by the system to return messages without truncation.

If insufficient memory is available to allocate a buffer to receive the message, the system calls the callback function with an MQRC_STORAGE_NOT_AVAILABLE reason code.

If, for example, you request data conversion, and there is insufficient memory available to convert the message data, the unconverted message is passed to the callback function.

This is an input field. The initial value of the MaxMsgLength field is MQCBD_FULL_MSG_LENGTH.