MQCTL - Control callbacks

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


Syntax

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


Parameters

    Hconn
    Type: MQHCONN - input

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

    On z/OS for CICS applications the MQCONN call can be omitted, and we can specify the following special value for Hconn :

      MQHC_DEF_HCONN
      Default connection handle.

    Operation
    Type: MQLONG - 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:

      MQOP_START

      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 MQOP_STOP
      • MQCTL with Operation MQOP_SUSPEND
      • MQDISC - Performs MQCTL with Operation MQOP_STOP before disconnection the HConn.

      MQRC_HCONN_ASYNC_ACTIVE 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 message consumer stops the connection during the MQCBCT_START_CALL then the MQCTL call returns with a failure reason code of MQRC_CONNECTION_STOPPED.

      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 MQOP_STOP operation.

      This option is not supported in the following environments: CICS on z/OS or if the application is bound with a nonthreaded IBM MQ library.

      MQOP_START_WAIT
      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 MQOP_STOP or MQOP_SUSPEND operations, or
      • All consumer routines have been deregistered or suspended.

      If all consumers are deregistered or suspended, an implicit MQOP_STOP 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 MQRC_ENVIRONMENT_ERROR.

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

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

      The application can choose to issue MQOP_STOP or MQOP_RESUME. In this instance, the MQOP_RESUME operation blocks.

      This option is not supported in a single threaded client.

      MQOP_STOP
      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(MQCO_QUIESCE), from within the callback function, to determine whether there are any further messages available to be delivered.

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

      This does not have any effect on the reading ahead of messages for the application. If you intend to stop consuming messages for a long time, consider closing the queue and reopening it when consumption continues.

      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.

      MQOP_RESUME
      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 the MQOP_RESUME is used to resume an MQOP_START_WAIT then the operation blocks.

    ControlOpts
    Type: MQCTLO - input

    Options that control the action of MQCTL

    See MQCTLO for details of the structure.

    CompCode
    Type: MQLONG - output The completion code; it is one of the following:

      MQCC_OK
      Successful completion.

      MQCC_WARNING
      Warning (partial completion).

      MQCC_FAILED
      Call failed.

    Reason
    Type: MQLONG - output If CompCode is MQCC_OK:

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

    If CompCode is MQCC_FAILED:

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

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

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

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

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

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

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

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

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

      MQRC_CALLBACK_ROUTINE_ERROR
      (2486, X'9B6') Either, both CallbackFunction and CallbackName have been specified on an MQOP_REGISTER call.
      Or either CallbackFunction or CallbackName have been specified but does not match the currently registered callback function.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      MQRC_MAX_MSG_LENGTH_ERROR
      (2485, X'9B5') Incorrect MaxMsgLength field

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

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

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

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

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

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

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

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

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

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

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

      MQRC_OPERATION_ERROR
      (2488, X'9B8') Incorrect Operation code on API Call

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    For detailed information about these codes, see Reason codes.


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 MQOP_DEREGISTER command to prevent repeated calls to the callback routine.
  2. If we are using asynchronous consume in an application where an XA Transaction Manager is managing global transactions, including updates to IBM MQ, we need to consider the following additional points:
    1. It is not valid to call MQCTL(MQOP_START) for an HConn, after it has been created, after calling xa_open.

      The reason is, that the HConn has become attached to an XA context, and so cannot then be accessed on the separate thread, or threads, in use by the asynchronous consume mechanism.

    2. If you call MQCTL(MQOP_START) in that scenario the call fails with reason code MQRC_ASYNC_XA_CONFLICT (2350).
    3. It is valid to call MQCTL(MQOP_START_WAIT) for an HConn, after it has been created, after calling xa_open.

      The reason is, that this method of starting the asynchronous consume mechanism causes all further callbacks for the HConn to run on the thread where the MQCTL call is made. Therefore, the link between the HConn and the thread is not lost.

  3. On z/OS, when Operation is MQOP_START:

    • Programs which use asynchronous callback routines must be authorized to use z/OS UNIX System Services (USS).
    • Language Environment (LE) programs which use asynchronous callback routines must use the LE runtime option POSIX(ON).
    • Non-LE programs which use asynchronous callback routines must not use the USS pthread_create interface (callable service BPX1PTC).

  4. MQCTL is not supported within the IMS adapter.

Note: In CICS, MQOP_START is not supported. Instead, use the MQOP_START_WAIT function call.


C invocation

MQCTL (Hconn, Operation, &ControlOpts, &CompCode, &Reason)
Declare the parameters as follows: 
MQHCONN  Hconn;         /* Connection handle */
MQLONG   Operation;     /* Operation being processed */
MQCTLO   ControlOpts    /* Options that control the action of MQCTL */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */


COBOL invocation

CALL 'MQCTL' USING HCONN, OPERATION, CTLOPTS, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN    PIC S9(9) BINARY.
**   Operation
 01  OPERATION PIC S9(9) BINARY.
**   Control Options
 01  CTLOPTS.
     COPY CMQCTLOV.
**   Completion code
 01  COMPCODE PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON   PIC S9(9) BINARY.


PL/I invocation

call MQCTL(Hconn, Operation, CtlOpts, CompCode, Reason)
Declare the parameters as follows: 
dcl Hconn        fixed bin(31); /* Connection handle */
dcl Operation    fixed bin(31); /* Operation */
dcl CtlOpts like MQCTLO;        /* Options that control the action of MQCTL */
dcl CompCode     fixed bin(31); /* Completion code */
dcl Reason       fixed bin(31); /* Reason code qualifying CompCode */
Parent topic: Function calls