MQCBD (Callback descriptor) on IBM i

Structure specifying the callback function.

Overview

Purpose: The MQCBD 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.

Version: The current version of MQCBD is CBDV1.

Character set and encoding: Data in MQCBD must be in the character set and encoding of the local queue manager; these are given by the CodedCharSetId queue manager attribute and ENNAT. However, if the application is running as an IBM MQ MQI client, the structure must be in the character set and encoding of the client.

• Fields
• Initial values
• RPG declaration

Fields

The MQCBD structure contains the following fields; the fields are described in alphabetical order:

CBDCALLBA (10-digit signed integer)

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 CBCCALLBA field in the MQCBD structure, which is a parameter on the callback function declaration.

The value is used only on an Operation having a value CBREG, 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.

CBDCALLBF (10-digit signed integer)

The callback function is invoked as a function call.

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

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

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

This option is not supported in the following environments:

• CICS on z/OS
• Programming languages and compilers that do not support function-pointer references

In such situations, the call fails with the reason code RC2486.

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

CBDCALLBN (10-digit signed integer)

The callback function is invoked as a dynamically linked program.

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

If either CallbackName or CallbackFunction is not true, the call fails with the reason code RC2486.

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-aligned 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:

IBMi

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.

UNIX

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 CBCHOBJ 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:

• RC2495
• RC2496
• RC2497

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.

CBDCALLBT (10-digit signed integer)

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

CBTMC

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.

CBTEH

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, RC2016.

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 RC2483

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

CBDMML (10-digit signed integer)

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:

• RC2080 or
• RC2079 if you specified GMATM.

The actual message length is supplied in the CBCLEN (10 digit signed integer) field of the MQCBC structure. The following special value is defined:

CBDFM

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 RC2071 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 CBDFM.

CBDOPT (10-digit signed integer)

Callback descriptor structure - Options field.

Any one, or all, of the following can be specified. 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). Combinations that are not valid are noted; any other combinations are valid.

CBDFQ

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 GMFIQ, 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:

CBDRC

The callback function is invoked with call type CBCTRC

.

CBDSC

The callback function is invoked with call type CBCTSC.

CBDTC

The callback function is invoked with call type CBCTTC.

CBDDC

The callback function is invoked with call type CBCTDC.

See CBCCALLT (10 digit signed integer) for further details about these call types. Default option: If we do not need any of the options described, use the following option:

CBDNO

Use this value to indicate that no other options have been specified; all options assume their default values.

CBDNO is defined to aid program documentation; it is not intended that this option is 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 CBDNO.

CBDSID (10-digit signed integer)

Callback descriptor structure - StrucId field.

This is the structure identifier; the value must be:

CBDSI

Identifier for callback descriptor structure.

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

CBDVER (10-digit signed integer)

Callback descriptor structure - Version field.

This is the structure version number; the value must be:

CBDV1

Version-1 callback descriptor structure.

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

CBDCV

Current version of callback descriptor structure.

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

Initial values

1. The symbol ¬ represents a single blank character.

RPG declaration

     D* MQCBD Structure
     D*
     D*
     D* Structure identifier 
     D  CBDSID                 1      4    INZ('CBD ')  
     D*
     D* Structure version number 
     D  CBDVER                 5      8I 0 INZ(1)
     D*
     D* Callback function type 
     D  CBDCALLBT              9     12I 0 INZ(1)
     D*
     ** Options controlling message
     D* consumption 
     D  CBDOPT                13     16I 0 INZ(0)
     D*
     D* User data passed to the function 
     D  CBDCALLBA             17     32*
     D*
     D* FP: Callback function pointer 
     D  CBDCALLBF             33     48*
     D*
     D* Callback name 
     D  CBDCALLBN             49    176    INZ('\0') 
     D*
     D* Maximum message length 
     D  CBDMML               177    180I 0 INZ(-1)