MQCTL (Control callback) on IBM i

The MQCTL call performs controlling actions on the object handles opened for a connection.


Syntax

MQCTL (Hconn, Operation, ControlOpts, CompCode, Reason)


Usage notes

  1. Callback routines must check the responses from all services they invoke, and if the routine detects a condition that cannot be resolved, it must issue an MQCB(CBREG) command to prevent repeated calls to the callback routine.


Parameters

The MQCTL call has the following parameters:

    HCONN (10-digit signed integer) - input

    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
    The operation being processed on the callback defined for the specified object handle. We must specify one, and one only, of the following options:

      CTLSR
      Start the consuming of messages for all defined message consumer functions for the specified connection handle.

      Callbacks run on a thread started by the system, which is different from any of the application threads.

      This operation gives control of the provided connection handle to system. The only MQI calls which can be issued by a thread other than the consumer thread are:

      • MQCTL with Operation CTLSP
      • MQCTL with Operation CTLSU
      • MQDISC - This performs MQCTL with Operation CTLSP before disconnection the HConn.

      RC2500 is returned if an IBM MQ API call is issued while the connection handle is started, and the call does not originate from a message consumer function.

      If a connection fails, this stops the conversation as soon as possible. It is possible, therefore, for an IBM MQ API call being issued on the main thread to receive the return code RC2500 for a while, followed by the return code RC2009 when the connection reverts to the stopped state.

      This can be issued in a consumer function. For the same connection as the callback routine, its only purpose is to cancel a previously issued CTLSP operation.

      This option is not supported if the application is bound with a nonthreaded IBM MQ library.

      CTLSW
      Start the consuming of messages for all defined message consumer functions for the specified connection handle. Message consumers run on the same thread and control is not returned to the caller of MQCTL until:

      • Released by the use of the MQCTL CTLSP or CTLSU operations, or
      • All consumer routines have been deregistered or suspended.

      If all consumers are deregistered or suspended, an implicit CTLSP operation is issued.

      This option cannot be used from within a callback routine, either for the current connection handle or any other connection handle. If the call is attempted it returns with RC2012.

      If, at any time during a CTLSW operation there are no registered, non-suspended consumers the call fails with a reason code of RC2446.

      If, during a CTLSW operation, the connection is suspended, the MQCTL call returns a warning reason code of RC2521; the connection remains 'started'.

      The application can choose to issue CTLSP or CTLRE. In this instance, the CTLRE operation blocks.

      This option is not supported in a single threaded client.

      CTLSP
      Stop the consuming of messages, and wait for all consumers to complete their operations before this option completes. This operation releases the connection handle.

      If issued from within a callback routine, this option does not take effect until the routine exits. No more message consumer routines are called after the consumer routines for messages already read have completed, and after stop calls (if requested) to callback routines have been made.

      If issued outside a callback routine, control does not return to the caller until the consumer routines for messages already read have completed, and after stop calls (if requested) to callbacks have been made. The callbacks themselves, however, remain registered.

      This function has no effect on read ahead messages. We must ensure that consumers run MQCLOSE(COQSC), from within the callback function, to determine whether there are any further messages available to be delivered.

      CTLSU
      Pause the consuming of messages. This operation releases the connection handle.

      This does not affect the reading ahead of messages for the application. If you intend to stop consuming messages for a long period, consider closing the queue and reopening it when consumption must continue.

      If issued from within a callback routine, it does not take effect until the routine exits. No more message consumer routines will be called after the current routine exits.

      If issued outside a callback, control does not return to the caller until the current consumer routine has completed and no more are called.

      CTLRE
      Resume the consuming of messages.

      This option is normally issued from the main application thread, but it can also be used from within a callback routine to cancel an earlier suspension request issued in the same routine.

      If CTLRE is used to resume a CTLSW, then the operation blocks.

    PCTLOP (MQCTLO) - input

    Options that control the action of MQCTL

    See MQCTLO for details of the structure.

    CMPCOD (10-digit signed integer) - output
    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

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

    If CMPCOD is CCOK:

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

    If CMPCOD is CCFAIL:

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

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

      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.

      RC2487
      (2487, X'9B7') Unable to call the callback routine

      RC2448
      (2448, X'990') Unable to Deregister, Suspend, or Resume because there is no registered callback

      RC2486
      (2486, X'9B6') Either, both CallbackFunction and CallbackName have been specified on a CBREG call, or either one of CallbackFunction or CallbackName has been specified but does not match the currently registered callback function.

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

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

      RC2444
      (2444, X'98C') Option block is incorrect.

      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.

      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'9B5') Incorrect MaxMsgLength field

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

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

      RC2496
      (2496, X'9C0') Module is found but is of the wrong type (32-bit or 64-bit) or is not a valid dll.

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

      RC2206
      (2206, X'89E') Message-identifier error.

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

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

      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.

      RC2488
      (2488, X'9B8') 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.

      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     MQCTL(HCONN : OPERATN : PCTLOP :
                                           CMPCOD : REASON)
The prototype definition for the call is: 
     DMQCTL            PR                  EXTPROC('MQCTL')
     D* Connection handle 
     D HCONN                         10I 0 VALUE
     D* Operation 
     D OPERATN                       10I 0 VALUE
     D* Control options 
     D PCTLOP                        32A  
     D* Completion code 
     D CMPCOD                        10I 0 
     D* Reason code qualifying CompCode 
     D REASON                        10I 0
Parent topic: Function calls on IBM i