MQCBC (Callback context) on IBM i

Structure describing the callback routine.

Overview

Purpose

The MQCBC structure is used to specify context information that is passed to a callback function.

The structure is an input/output parameter on the call to a message consumer routine.

Version

The current version of MQCBC is CBCV2.

Character set and encoding

Data in MQCBC is in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT. However, if the application is running as an IBM MQ client, the structure is in the character set and encoding of the client.

• Fields
• Initial values
• RPG declaration

Fields

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

CBCBUFFLEN (10 digit signed integer)

The buffer can be larger than both the MaxMsgLength value defined for the consumer and the ReturnedLength value in the MQGMO.

Callback context structure - BufferLength field.

This is the length in bytes of the message buffer that has been passed to this function.

The actual message length is supplied in DataLength field.

The application can use the entire buffer for its own purposes for the duration of the callback function.

This is an input field to the message consumer function; it is not relevant to an exception handler function.

CBCCALLBA (10 digit signed integer)

Callback context 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 CBDCALLBA field in the MQCBD structure, which is a parameter on the MQCB call used to define the callback function.

Changes to the CBCCALLBA are preserved across the invocations of the callback function for an CBCHOBJ. This field is not shared with callback functions for other handles.

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

CBCCALLT (10 digit signed integer)

Callback Context structure - CallType field.

Field containing information about why this function has been called. The following call types are defined.

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

CBCTMR

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

If the value of CBCCC is CCWARN, the value of the Reason field is RC2079 or one of the codes indicating a data conversion problem.

CBCTMN

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, GMBR*
• The message is larger than the available buffer and the MQGMO options do not specify gmatm

If the value of CBCCC is CCWARN, the value of the Reason field is RC2080 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 CBDOPT in the MQCBD structure.

The CBCLEN and CBCBUFFLEN parameters are not valid for these call types.

CBCTRC

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

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 CBCREA field is RCNONE.

CBCTSC

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 CTLSR or CTLSW.

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 CBCREA field is RCNONE.

CBCTTC

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

This call type is used for message consumers only.

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

CBCTDC

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 BCUNR.
• Queue is closed, causing an implicit deregister. In this instance the callback function is passed HOUNUH 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 CBCREA field is set to indicate the reason for stopping.

CBCTEC

Event handler function The event handler function has been invoked without a message when:

• An MQCTL call is issued with a value for the Operation field of CTLSP, or
• 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 (CBCCC = CCFAIL) has been detected that is specific to the object handle; for example CBCREA code = RC2016 .

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

This is an input field. CBCTMR and CMCTMN are applicable only to message consumer functions.

CBCCC (10 digit signed integer)

Callback context structure - CompCode field.

This is the completion code. It indicates whether there were any problems consuming the message; it is one of the following:

CCOK

Successful completion

CCWARN

Warning (partial completion)

CCFAIL

Call failed

This is an input field. The initial value of this field is CCOK.

CBCCONNAREA (10 digit signed integer)

Callback context structure - ConnectionArea 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 ConnectionArea field in the MQCTLO structure, which is a parameter on the MQCTL call used to control the callback function.

Any changes made to this field by the callback functions are preserved across the invocations of the callback function. This area can be used to pass information that is to be shared by all callback functions. Unlike CallbackArea, this area is common across all callbacks for a connection handle.

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

CBCLEN (10 digit signed integer)

This is the length in bytes of the application data in the message. If the value is zero, it means that the message contains no application data.

The CBCLEN field contains the length of the message but not necessarily the length of the message data passed to the consumer. It could be that the message was truncated. Use the GMRL field in the MQGMO to determine how much data has been passed to the consumer.

If the reason code indicates the message has been truncated, we can use the CBCLEN field to determine how large the actual message is. This allows you to determine the size of the buffer required to accommodate the message data, and then issue an MQCB call to update the CBDMML in the MQCBD with an appropriate value.

If the GMCONV option is specified, the converted message could be larger than the value returned for DataLength. In such cases, the application probably needs to issue an MQCB call to update the CBDMML in the MQCBD to be greater than the value returned by the queue manager for DataLength.

To avoid message truncation problems, specify MaxMsgLength as CBDFM. This causes the queue manager to allocate a buffer for the full message length after data conversion. Be aware, however, that even if this option is specified, it is still possible that sufficient storage is not available to correctly process the request. Applications should always check the returned reason code. For example, if it is not possible to allocate sufficient storage to convert the message, the messages is returned to the application unconverted.

This is an input field to the message consumer function; it is not relevant to an event handler function.

CBCFLG (10 digit signed integer)

Flags containing information about this consumer.

The following option is defined:

CBCFBE

This flag can be returned if a previous MQCLOSE call using the COQSC option failed with a reason code of RC2458.

This code indicated that the last read ahead message is being returned and that the buffer is now empty. If the application issues another MQCLOSE call using the COQSC option, it succeeds.

Note, that an application is not guaranteed to be given a message with this flag set, as there might still be messages in the read-ahead buffer that do not match the current selection criteria. In this instance, the consumer function is invoked with the reason code RC2019 .

If the read ahead buffer is empty, the consumer is invoked with the CBCFBE flag and the reason code RC2518.

This is an input field to the message consumer function; it is not relevant to an event handler function.

CBCHOBJ (10 digit signed integer)

Callback context structure - CBCHOBJ field.

For a call to a message consumer, this is the handle for the object relating to the message consumer.

For an event handler, this value is HONONE

The application can use this handle and the message token in the Get Message Options block to get the message if a message has not been removed from the queue.

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

CBCRCD (10 digit signed integer)

CBCRCD indicates how long the queue manager waits before trying to reconnect. The field can be modified by an event handler to change the delay or stop reconnection altogether.

Use the CBCRCD field only if the value of the Reason field in the Callback Context is RC2545.

On entry to the event handler the value of CBCRCD is the number of milliseconds the queue manager is going to wait before making a reconnection attempt. Table 1 lists the values that we can set to modify the behavior of the queue manager on return from the event handler.

Table 1. CBCRCD values

Value	Description
-1	Make no more reconnection attempts. An error is returned to the application.
0	Try to reconnect immediately.
>0	Wait for this many milliseconds before trying the connection again.

CBCREA (10 digit signed integer)

Callback context structure - Reason field.

This is the reason code qualifying the CBCCC

This is an input field. The initial value of this field is RCNONE.

CBCSTATE (10 digit signed integer)

An indication of the state of the current consumer. This field is of most value to an application when a nonzero reason code is passed to the consumer function.

We can use this field to simplify application programming because we do not need to code behavior for each reason code.

This is an input field. The initial value of this field is CSNONE

State	Queue manager action	Value of constant
CSNONE This reason code represents a normal call with no additional reason information	None; this is the normal operation.	0
CSSUST These reason codes represent temporary conditions.	The callback routine is called to report the condition and then suspended. After a period the system might attempt the operation again, which can lead to the same condition being raised again.	1
CSSUSU These reason codes represent conditions where the callback needs to act to resolve the condition.	The consumer is suspended and the callback routine is called to report the condition. The callback routine should resolve the condition if possible and either RESUME or close down the connection.	2
CSSUS These reason codes represent failures that prevent further message callbacks.	The queue manager automatically suspends the callback function. If the callback function is resumed it is likely to receive the same reason code again.	3
CSSTOP These reason codes represent the end of message consumption.	Delivered to the exception handler and to callbacks that specified CBDTC. No further messages can be consumed.	4

CBCSID (10 digit signed integer)

Callback context structure - StrucId field.

This is the structure identifier; the value must be:

CBCSI

Identifier for callback context structure.

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

CBCVER (10 digit signed integer)

Callback context structure - Version field.

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

CBCV1

Version-1 callback context structure.

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

CBCCV

Current version of the callback context structure.

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

Initial values

Table 2. Initial values of fields in MQCBC

Field name	Name of constant	Value of constant
CBCSID	CBCSI	'CBC¬'
CBCVER	CBCV1	1
CBCCALLT	None	0
CBCHOBJ	HOUNUH	-1
CBCCALLBA	None	Null pointer or null bytes
CBCCONNAREA	None	Null pointer or null bytes
CBCCC	CCOK	0
CBCREA	RCNONE	0
CBCSTATE	CSNONE	0
CBCLEN	None	0
CBCBUFFLEN	None	0
CBCFLG	None	0
CBCRCD	none	0

Note:

1. The symbol ¬ represents a single blank character.

RPG declaration

     D* MQCBC Structure
     D*
     D*
     D* Structure identifier
     D  CBCSID                 1      4    INZ('CBC ')
     D*
     D* Structure version number
     D  CBCVER                 5      8I 0 INZ(1)
     D*
     D* Why Function was called
     D  CBCCALLT               9     12I 0 INZ(0)
     D*
     D* Object Handle
     D  CBCHOBJ               13     16I 0 INZ(-1)
     D*
     D* Callback data passed to the function
     D  CBCCALLBA             17     32*   INZ(*NULL)
     D*
     D* MQCTL Data area passed to the function
     D  CBCCONNAREA           33     48*   INZ(*NULL)
     D*
     D* Completion Code
     D  CBCCC                 49     52I 0 INZ(0)
     D*
     D* Reason Code
     D  CBCREA                53     56I 0 INZ(0)
     D*
     D* Consumer State
     D  CBCSTATE              57     60I 0 INZ(0)
     D*
     D* Message Data Length
     D  CBCLEN                61     64I 0 INZ(0)
     D*
     D* Buffer Length
     D  CBCBUFFLEN            65     68I 0 INZ(0)
     D*
     ** Flags containing information about
     D* this consumer
     D  CBCFLG                69     72I 0 INZ(0)
     D* Ver:1 **
     D* Number of milliseconds before reconnect attempt
     D  CBCRCD                73     76I 0 INZ(0)
     D* Ver:2 **
     D*