MQCONNX - Connect queue manager (extended)

The MQCONNX call connects an application program to a queue manager. It provides a queue manager connection handle, which is used by the application on subsequent IBM MQ calls.

The MQCONNX call is like the MQCONN call, except that MQCONNX allows options to be specified to control the way that the call works.

  • This call is supported on all IBM MQ systems, and IBM MQ clients connected to these systems.
A client connection cannot be made on a server only installation, and a local connection cannot be made on a client only installation.


Syntax

MQCONNX (QMgrName, ConnectOpts, Hconn, CompCode, Reason)


Parameters

    QMgrName
    Type: MQCHAR48 - input

    See the QMgrName parameter described in MQCONN - Connect queue manager for details.

    ConnectOpts
    Type: MQCNO - input/output

    See MQCNO - Connect options for details.

    Hconn
    Type: MQHCONN - output

    This handle represents the connection to the queue manager. Specify it on all subsequent message queuing calls issued by the application. It ceases to be valid when the MQDISC call is issued, or when the unit of processing that defines the scope of the handle terminates.

    IBM MQ now supplies the mqm library with client packages as well as server packages. This means that when an MQI call that is found in the mqm library is made, the connection type is checked to see if it is a client or server connection, and then the correct underlying call is made. Therefore an exit which is passed an Hconn can now be linked against the mqm library, but used on a client installation.

    Handle scope: The scope of the handle returned depends on the call used to connect to the queue manager (MQCONN or MQCONNX). If the call used is MQCONNX, the scope of the handle also depends on the MQCNO_HANDLE_SHARE_* option specified in the Options field of the MQCNO structure.

    • If the call is MQCONN, or the MQCNO_HANDLE_SHARE_NONE option is specified, the handle returned is a nonshared handle.

      The scope of a nonshared handle is the smallest unit of parallel processing supported by the platform on which the application is running (see Table 1 for details); the handle is not valid outside the unit of parallel processing from which the call was issued.

    • If you specify the MQCNO_HANDLE_SHARE_BLOCK or MQCNO_HANDLE_SHARE_NO_BLOCK option, the handle returned is a shared handle.

      The scope of a shared handle is the process that owns the thread from which the call was issued; the handle can be used from any thread that belongs to that process. Not all platforms support threads.

    • If the MQCONN or MQCONNX call fails with completion code equal to MQCC_FAILED, then the Hconn value is undefined.
    Table 1. Scope of nonshared handles on various platforms
    Platform Scope of nonshared handle
    z/OS®

    • CICS®: the CICS task
    • IMS: the task, up to the next sync point (excluding subtasks of the task)
    • z/OS batch and TSO: the task (excluding subtasks of the task)
    IBM i Job
    UNIX Thread
    16 bit Windows applications Process
    32 bit Windows applications Thread
    On z/OS for CICS applications the value returned is:

      MQHC_DEF_HCONN
      Default connection handle.

    CompCode
    Type: MQLONG - output

    See the CompCode parameter described in MQCONN - Connect queue manager for details.

    Reason
    Type: MQLONG - output

    The following codes can be returned by the MQCONN and MQCONNX calls. For a list of additional codes that can be returned by the MQCONNX call, see the following codes.

    If CompCode is MQCC_OK:

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

    If CompCode is MQCC_WARNING:

      MQRC_ALREADY_CONNECTED
      (2002, X'7D2') Application already connected.

      MQRC_CLUSTER_EXIT_LOAD_ERROR
      (2267, X'8DB') Unable to load cluster workload exit.

      MQRC_SSL_ALREADY_INITIALIZED
      (2391, X'957') SSL already initialized.

    If CompCode is MQCC_FAILED:

      MQRC_ADAPTER_CONN_LOAD_ERROR
      (2129, X'851') Unable to load adapter connection module.

      MQRC_ADAPTER_DEFS_ERROR
      (2131, X'853') Adapter subsystem definition module not valid.

      MQRC_ADAPTER_DEFS_LOAD_ERROR
      (2132, X'854') Unable to load adapter subsystem definition module.

      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_ADAPTER_STORAGE_SHORTAGE
      (2127, X'84F') Insufficient storage for adapter.

      MQRC_ANOTHER_Q_MGR_CONNECTED
      (2103, X'837') Another queue manager already connected.

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

      MQRC_API_EXIT_INIT_ERROR
      (2375, X'947') API exit initialization failed.

      MQRC_API_EXIT_TERM_ERROR
      (2376, X'948') API exit termination failed.

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

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

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

      MQRC_CONN_ID_IN_USE
      (2160, X'870') Connection identifier already in use.

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

      MQRC_CONNECTION_ERROR
      (2273, X'8E1') Error processing MQCONN call.

      MQRC_CONNECTION_NOT_AVAILABLE
      (2568, X'A08') Occurs on an MQCONN or MQCONNX call when the queue manager is unable to provide a connection of the requested connection type on the current installation. A client connection cannot be made on a server only installation. A local connection cannot be made on a client only installation.

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

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

      MQRC_CRYPTO_HARDWARE_ERROR
      (2382, X'94E') Cryptographic hardware configuration error.

      MQRC_DUPLICATE_RECOV_COORD
      (2163, X'873') Recovery coordinator exists.

      MQRC_ENVIRONMENT_ERROR
      (2012, X'7DC') Call not valid in environment.

      Additionally, on the MQCONNX call, passing the MQCSP - Security parameters control block from a CICS or IMS application.

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

      MQRC_HOST_NOT_AVAILABLE
      (2538, X'9EA') An MQCONN call was issued from a client to connect to a queue manager but the attempt to allocate a conversation to the remote system failed.

      MQRC_INSTALLATION_MISMATCH
      (2583, X'A17') Mismatch between queue manager installation and selected library.

      MQRC_KEY_REPOSITORY_ERROR
      (2381, X'94D') Key repository not valid.

      MQRC_MAX_CONNS_LIMIT_REACHED
      (2025, X'7E9') Maximum number of connections reached.

      MQRC_NOT_AUTHORIZED
      (2035, X'7F3') Not authorized for access.

      MQRC_OPEN_FAILED
      (2137, X'859') Object not opened successfully.

      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_SECURITY_ERROR
      (2063, X'80F') Security error occurred.

      MQRC_SSL_INITIALIZATION_ERROR
      (2393, X'959') SSL initialization error.

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

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

    The following additional reason codes can be returned by the MQCONNX call:

    If CompCode is MQCC_FAILED:

      MQRC_AIR_ERROR
      (2385, X'951') Authentication information record not valid.

      MQRC_AUTH_INFO_CONN_NAME_ERROR
      (2387, X'953') Authentication information connection name not valid.

      MQRC_AUTH_INFO_REC_COUNT_ERROR
      (2383, X'94F') Authentication information record count not valid.

      MQRC_AUTH_INFO_REC_ERROR
      (2384, X'950') Authentication information record fields not valid.

      MQRC_AUTH_INFO_TYPE_ERROR
      (2386, X'952') Authentication information type not valid.

      MQRC_CD_ERROR
      (2277, X'8E5') Channel definition not valid.

      MQRC_CLIENT_CONN_ERROR
      (2278, X'8E6') Client connection fields not valid.

      MQRC_CNO_ERROR
      (2139, X'85B') Connect-options structure not valid.

      MQRC_CONN_TAG_IN_USE
      (2271, X'8DF') Connection tag in use.

      MQRC_CONN_TAG_NOT_USABLE
      (2350, X'92E') Connection tag not usable.

      MQRC_LDAP_PASSWORD_ERROR
      (2390, X'956') LDAP password not valid.

      MQRC_LDAP_USER_NAME_ERROR
      (2388, X'954') LDAP user name fields not valid.

      MQRC_LDAP_USER_NAME_LENGTH_ERR
      (2389, X'955') LDAP user name length not valid.

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

      MQRC_SCO_ERROR
      (2380, X'94C') SSL configuration options structure not valid.

      MQRC_SSL_CONFIG_ERROR
      (2392, X'958') SSL configuration error.

    For detailed information about these codes, see Reason codes.


Usage notes

For the Visual Basic programming language, the following point applies:

  • The ConnectOpts parameter is declared as being of type MQCNO. If the application is running as an IBM MQ MQI client, and you want to specify the parameters of the client-connection channel, declare the ConnectOpts parameter as being of type Any, so that the application can specify an MQCNOCD structure on the call in place of an MQCNO structure. However, this means that the ConnectOpts parameter cannot be checked to ensure that it is the correct data type.


C invocation

MQCONNX (QMgrName, &ConnectOpts, &Hconn, &CompCode, &Reason);
Declare the parameters as follows: 
MQCHAR48  QMgrName;     /* Name of queue manager */
MQCNO     ConnectOpts;  /* Options that control the action of MQCONNX */
MQHCONN   Hconn;        /* Connection handle */
MQLONG    CompCode;     /* Completion code */
MQLONG    Reason;       /* Reason code qualifying CompCode */


COBOL invocation

CALL 'MQCONNX' USING QMGRNAME, CONNECTOPTS, HCONN, COMPCODE,
REASON.
Declare the parameters as follows: 
**   Name of queue manager
 01  QMGRNAME     PIC X(48).
**   Options that control the action of MQCONNX
 01  CONNECTOPTS.
     COPY CMQCNOV.
**   Connection handle
 01  HCONN        PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE     PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON       PIC S9(9) BINARY.


PL/I invocation

call MQCONNX (QMgrName, ConnectOpts, Hconn, CompCode, Reason);
Declare the parameters as follows: 
dcl QMgrName     char(48);       /* Name of queue manager */
dcl ConnectOpts  like MQCNO;     /* Options that control the action of
                                    MQCONNX */
dcl Hconn        fixed bin(31);  /* Connection handle */
dcl CompCode     fixed bin(31);  /* Completion code */
dcl Reason       fixed bin(31);  /* Reason code qualifying CompCode */


High Level Assembler invocation

CALL MQCONNX,(QMGRNAME,CONNECTOPTS,HCONN,COMPCODE,REASON)
Declare the parameters as follows: 
QMGRNAME     DS       CL48  Name of queue manager
CONNECTOPTS  CMQCNOA  ,     Options that control the action of MQCONNX
HCONN        DS       F     Connection handle
COMPCODE     DS       F     Completion code
REASON       DS       F     Reason code qualifying COMPCODE


Visual Basic invocation

MQCONNX QMgrName, ConnectOpts, Hconn, CompCode, Reason
Declare the parameters as follows: 
Dim QMgrName    As String*48 'Name of queue manager'
Dim ConnectOpts As MQCNO     'Options that control the action of'
                             'MQCONNX'
Dim Hconn       As Long      'Connection handle'
Dim CompCode    As Long      'Completion code'
Dim Reason      As Long      'Reason code qualifying CompCode'