+

Search Tips | Advanced Search

MQCB (Manage callback) on IBM i

The MQCB call reregisters a callback for the specified object handle and controls activation and changes to the callback.

A callback is a piece of code (specified as either the name of a function that can be dynamically linked or as a function pointer) that is called by IBM MQ when certain events occur.

To use MQCB and MQCTL on a V7 client we must be connected to a V7 server and the SHARECNV parameter of the channel must have a non-zero value.

For information about Global units of work see: Global units of work.

The types of callback that can be defined are:

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

    Only one callback function can be registered against each object handle. If a single queue is to be read with multiple selection criteria then the queue must be opened multiple times and a consumer function registered on each handle.

    Event handler
    The event handler is called for conditions that affect the whole callback environment.

    The function is called when an event condition occurs, for example, a queue manager or connection stopping or quiescing.

    The function is not called for conditions that are specific to a single message consumer, for example RC2016; it is called however if a callback function does not end normally.


Syntax

MQCB (HCONN, OPERATN, HOBJ, CBDSC, MSGDSC, GMO, CMPCOD, REASON)


Usage notes for MQCB

  1. MQCB is used to define the action to be invoked for each message, matching the specified criteria, available on the queue. When the action is processed, either the message is removed from the queue and passed to the defined message consumer, or a message token is provided, which is used to retrieve the message.
  2. MQCB can be used to define callback routines before starting consumption with MQCTL or it can be used from within a callback routine.
  3. To use MQCB from outside of a callback routine, we must first suspend message consumption by using MQCTL and resume consumption afterward.

    Message consumer callback sequence
    We can configure a consumer to invoke callback at key points during the lifecycle of the consumer. For example:

    • when the consumer is first registered,
    • when the connection is started,
    • when the connection is stopped and
    • when the consumer is deregistered, either explicitly, or implicitly by an MQCLOSE.

    Verb Meaning
    MQCTL(START) MQCTL call by using the CTLSR Operation
    MQCTL(STOP) MQCTL call by using the CTLSP Operation
    MQCTL(WAIT) MQCTL call by using the CTLSW Operation
    Allows the consumer to maintain state associated with the consumer. When a callback is requested by an application, the rules for consumer invocation are as follows:

      REGISTER
      Is always the first type of invocation of the callback.
      Is always called on the same thread as the MQCB(CBREG) call.

      START
      Is always called synchronously with the MQCTL(START) verb.

      • All START callbacks are completed before the MQCTL(START) verb returns.

      Is on the same thread as the message delivery if CTLTHR is requested.
      The call with start is not guaranteed if, for example, a previous callback issues MQCTL(STOP) during the MQCTL(START).

      STOP
      No further messages or events are delivered after this call until the connection is restarted.
      A STOP is guaranteed if the application was previously called for START, or a message, or an event.

      DEREGISTER
      Is always the last type of invocation of the callback.

    Ensure that the application performs thread-based initialization and cleanup in the START and STOP callbacks. We can do non thread-based initialization and cleanup with REGISTER and DEREGISTER callbacks.

    Do not make any assumptions about the life and availability of the thread other than what is stated. For example, do not rely on a thread staying alive beyond the last call to DEREGISTER. Similarly, when you have chosen not to use CTLTHR, do not assume that the thread exists whenever the connection is started.

    If the application has particular requirements for thread characteristics, it can always create a thread accordingly, then use MQCTL(WAIT). This step donates the thread to IBM MQ for asynchronous message delivery.

    Message consumer connection usage

    Normally, when an application issues another MQI call while one is outstanding, the call fails with reason code RC2219.

    There are special cases, however, when the application must issue a further MQI call before the previous call has completed. For example, the consumer can be invoked during an MQCB call with CBRE.

    In such an instance, when as a result of the application issuing either an MQCB or MQCTL verb, the application is called back, the application is allowed to issue a further MQI call. This instance means we can issue, for example, an MQOPEN call, in the consumer function when called with a CBCCALLT type of CBCTRC. Any MQI call, except for MQDISC, is allowed.


Parameters for MQCB

The MQCB call has the following parameters:

    HCONN (10-digit signed integer) - input

    Manage callback function - HCONN parameter.

    This handle represents the connection to the queue manager. The value of HCONN was returned by a previous MQCONN or MQCONNX call.

    OPERATN (10-digit signed integer) - input

    Manage callback function - OPERATN parameter.

    The operation being processed on the callback defined for the specified object handle. We must specify one of the following options; if more than one option is required, the values can be added (do not add the same constant more than once) or combined by using the bitwise OR operation (if the programming language supports bit operations).

    Combinations that are not valid are noted; all other combinations are valid.

      CBREG
      Define the callback function for the specified object handle. This operation defines the function to be called and the selection criteria to be used.

      If a callback function is already defined for the object handle the definition is replaced. If an error is detected while replacing the callback, the function is deregistered.

      If a callback is registered in the same callback function in which it was previously deregistered, this is treated as a replace operation; any initial or final calls are not invoked.

      We can use CBREG with CTLSU or CTLRE.

      CBUNR
      Stop the consuming of messages for the object handle and removes the handle from those eligible for a callback.

      A callback is automatically deregistered if the associated handle is closed.

      If CBUNR is called from within a consumer, and the callback has a stop call defined, it is invoked upon return from the consumer.

      If this operation is issued against an Hobj with no registered consumer, the call returns with RC2448.

      CTLSU
      Suspends the consuming of messages for the object handle.

      If this operation is applied to an event handler, the event handler does not get events while suspended, and any events missed while in the suspended state are not provided to the operation when it is resumed.

      While suspended, the consumer function continues to get the control type callbacks.

      CTLRE
      Resume the consuming of messages for the object handle.

      If this operation is applied to an event handler, the event handler does not get events while suspended, and any events missed while in the suspended state are not provided to the operation when it is resumed.

    CBDSC (MQCBD) - input

    Manage callback function - CBDSC parameter.

    This is a structure that identifies the callback function that is being registered by the application and the options used when registering it.

    See MQCBD - Callback descriptor for details of the structure.

    Callback descriptor is required only for the CBREG option; if the descriptor is not required, the parameter address passed can be null.

    HOBJ (10-digit signed integer) - input

    Manage callback function - HOBJ parameter.

    This handle represents the access that has been established to the object from which a message is to be consumed. This is a handle that has been returned from a previous MQOPEN or MQSUB call (in the HOBJ parameter).

    HOBJ is not required when defining an event handler routine (CBTEH) and must be specified as HONONE.

    If this Hobj has been returned from an MQOPEN call, the queue must have been opened with one or more of the following options:

    • OOINPS
    • OOINPX
    • OOINPQ
    • OOBRW

    MSGDSC (MQMD) - input

    Manage callback function -MSGDSC parameter.

    This structure describes the attributes of the message required, and the attributes of the message retrieved.

    The MsgDesc parameter defines the attributes of the messages required by the consumer, and the version of the MQMD to be passed to the message consumer.

    The MsgId, CorrelId, GroupId, MsgSeqNumber, and Offset in the MQMD are used for message selection, depending on the options specified in the GetMsgOpts parameter.

    The Encoding and CodedCharSetId are used for message conversion if we specify the GMCONV option.

    See MQMD for details.

    MsgDesc is used only for CBREG and, if you require values other than the default for any fields. MsgDesc is not used for an event handler.

    If the descriptor is not required the parameter address passed can be null.

    Note, that if multiple consumers are registered against the same queue with overlapping selectors, the chosen consumer for each message is undefined.

    GMO (MQGMO) - input

    Manage callback function - GMO parameter.

    Options that control how the message consumer gets messages.

    All options have the meaning as described in MQGMO (Get-message options) on IBM i, when used on an MQGET call, except:

      GMSSIG
      This option is not permitted.

      GMBRWF, GMBRWN, GMMBH, GMMBC
      The order of messages delivered to a browsing consumer is dictated by the combinations of these options. Significant combinations are:

        GMBRWF
        The first message on the queue is delivered repeatedly to the consumer. This is useful when the consumer destructively consumes the message in the callback. Use this option with care.

        GMBRWN
        The consumer is given each message on the queue, from the current cursor position until the end of the queue is reached.

        GMBRWF + GMBRWN
        The cursor is reset to the start of the queue. The consumer is then given each message until the cursor reaches the end of the queue.

        GMBRWF + GMMBH or GMMBC
        Starting at the beginning of the queue, the consumer is given the first nonmarked message on the queue, which is then marked for this consumer. This combination ensures that the consumer can receive new messages added behind the current cursor point.

        GMBRWN + GMMBH or GMMBC
        Starting at the cursor position the consumer is given the next nonmarked message on the queue, which is then marked for this consumer. Use this combination with care because messages can be added to the queue behind the current cursor position.

        GMBRWF + GMBRWN + GMMBH or GMMBC
        This combination is not permitted, if used the call returns RC2046.

      GMNWT, GMWT and GMWI
      These options control how the consumer is invoked.

        GMNWT
        The consumer is never called with RC2033. The consumer is only invoked for messages and events

        GMWT with a zero GMWI
        The RC2033 code is only passed to the consumer when there are no messages and

        • the consumer has been started
        • the consumer has been delivered at least one message since the last no messages reason code.

        This prevents the consumer from polling in a busy loop when a zero wait interval is specified.

        GMWT and a positive GMWI
        The user is invoked after the specified wait interval with reason code RC2033. This call is made regardless of whether any messages have been delivered to the consumer. This allows the user to perform heartbeat or batch type processing.

        GMWT and GMWI of WIULIM
        This specifies an infinite wait before returning RC2033. The consumer is never called with RC2033.

    GMO is used only for CBREG and, if you require values other than the default for any fields. GMO is not used for an event handler.

    If the options are not required the parameter address passed can be null.

    If a message properties handle is provided in the MQGMO structure, a copy is provided in the MQGMO structure that is passed into the consumer callback. On return from the MQCB call, the application can delete the message properties handle.

    CMPCOD (10-digit signed integer) - output

    Manage callback function - CMPCOD parameter.

    The completion code; it is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Manage callback function - REASON parameter.

    The following reason codes are the codes that the queue manager can return for the REASON parameter.

    If CMPCOD is CCOK:

      RCNONE
      (0, X'000') No reason to report.

    If CompCode is CCFAIL:

      RC2204
      (2204, X'89C') Adapter not available.

      RC2133
      (2133, X'855') Unable to load data conversion services modules.

      RC2130
      (2130, X'852') Unable to load adapter service module.

      RC2374
      (2374, X'946') API exit failed.

      RC2183
      (2183, X'887') Unable to load API exit.

      RC2157
      (2157, X'86D') Primary and home ASIDs differ.

      RC2005
      (2005, X'7D5') Buffer length parameter not valid.

      RC2219
      (2219, X'8AB') MQI call entered before previous call complete.

      RC2487
      (2487, X'9B7') Incorrect callback type field.

      RC2448
      (2448, X'990') Unable to deregister, suspend, or resume because there is no registered callback.

      RC2486
      (2486, X'9B6') Either CallbackFunction or CallbackName must be specified but not both.

      RC2483
      (2483, X'9B3') Incorrect callback type field.

      RC2484
      (2484, X'9B4') Incorrect MQCBD options field.

      RC2140
      (2140, X'85C') Wait request rejected by CICS .

      RC2009
      (2009, X'7D9') Connection to queue manager lost.

      RC2217
      (2217, X'8A9') Not authorized for connection.

      RC2202
      (2202, X'89A') Connection quiescing.

      RC2203
      (2203, X'89B') Connection shutting down.

      RC2207
      (2207, X'89F') Correlation-identifier error.

      RC2010
      (2010, X'7DA') Data length parameter not valid.

      RC2016
      (2016, X'7E0') Gets inhibited for the queue.

      RC2351
      (2351, X'92F') Global units of work conflict.

      RC2186
      (2186, X'88A') Get-message options structure not valid.

      RC2353
      (2353, X'931') Handle in use for global unit of work.

      RC2018
      (2018, X'7E2') Connection handle not valid.

      RC2019
      (2019, X'7E3') Object handle not valid.

      RC2259
      (2259, X'8D3') Inconsistent browse specification.

      RC2245
      (2245, X'8C5') Inconsistent unit-of-work specification.

      RC2246
      (2246, X'8C6') Message under cursor not valid for retrieval.

      RC2352
      (2352, X'930') Global unit of work conflicts with local unit of work.

      RC2247
      (2247, X'8C7') Match options not valid.

      RC2485
      (2485, X'9B4') Incorrect MaxMsgLength field.

      RC2026
      (2026, X'7EA') Message descriptor not valid.

      RC2497
      (2497, X'9C1') The specified function entry point could not be found in the module.

      RC2496
      (2496, X'9C0') Module found, however it is of the wrong type; not 32 bit, 64 bit, or a valid dynamic link library.

      RC2495
      (2495, X'9BF') Module not found in the search path or not authorized to load.

      RC2250
      (2250, X'8CA') Message sequence number not valid.

      RC2331
      (2331, X'91B') Use of message token not valid.

      RC2033
      (2033, X'7F1') No message available.

      RC2034
      (2034, X'7F2') Browse cursor not positioned on message.

      RC2036
      (2036, X'7F4') Queue not open for browse.

      RC2037
      (2037, X'7F5') Queue not open for input.

      RC2041
      (2041, X'7F9') Object definition changed since opened.

      RC2101
      (2101, X'835') Object damaged.

      RC2206
      (2206, X'89E') Incorrect operation code on API Call.

      RC2046
      (2046, X'7FE') Options not valid or not consistent.

      RC2193
      (2193, X'891') Error accessing page-set data set.

      RC2052
      (2052, X'804') Queue has been deleted.

      RC2394
      (2394, X'95A') Queue has wrong index type.

      RC2058
      (2058, X'80A') Queue manager name not valid or not known.

      RC2059
      (2059, X'80B') Queue manager not available for connection.

      RC2161
      (2161, X'871') Queue manager quiescing.

      RC2162
      (2162, X'872') Queue manager shutting down.

      RC2102
      (2102, X'836') Insufficient system resources available.

      RC2069
      (2069, X'815') Signal outstanding for this handle.

      RC2071
      (2071, X'817') Insufficient storage available.

      RC2109
      (2109, X'83D') Call suppressed by exit program.

      RC2024
      (2024, X'7E8') No more messages can be handled within current unit of work.

      RC2072
      (2072, X'818') Syncpoint support not available.

      RC2195
      (2195, X'893') Unexpected error occurred.

      RC2354
      (2354, X'932') Enlistment in global unit of work failed.

      RC2355
      (2355, X'933') Mixture of unit-of-work calls not supported.

      RC2255
      (2255, X'8CF') Unit of work not available for the queue manager to use.

      RC2090
      (2090, X'82A') Wait interval in MQGMO not valid.

      RC2256
      (2256, X'8D0') Wrong version of MQGMO supplied.

      RC2257
      (2257, X'8D1') Wrong version of MQMD supplied.

      RC2298
      (2298, X'8FA') The function requested is not available in the current environment.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQCB(HCONN : OPERATN : CBDSC :
                                     HOBJ : MSGDSC : GMO :
                                     DATLEN : CMPCOD : REASON)
The prototype definition for the call is: 
     DMQCB             PR                  EXTPROC('MQCB')
     D* Connection handle 
     D HCONN                         10I 0 VALUE
     D* Operation 
     D OPERATN                       10I 0 VALUE
     D* Callback descriptor 
     D CBDSC                        180A  
     D* Object handle 
     D HOBJ                          10I 0 VALUE
     D* Message Descriptor 
     D MSGDSC                       364A   
     D* Get options 
     D GMO                          112A   
     D* Completion code 
     D CMPCOD                        10I 0 
     * Reason code qualifying CompCode
     D REASON                        10I 0
Parent topic: Function calls on IBM i

Last updated: 2020-10-04