MQCONN - Connect queue manager

Syntax

MQCONN (QMgrName, Hconn, CompCode, Reason)

Parameters

QMgrName

Type: MQCHAR48 - input

This is the name of the queue manager to which the application wants to connect. The name can contain the following characters:

• Uppercase alphabetic characters (A through Z)
• Lowercase alphabetic characters (a through z)
• Numeric digits (0 through 9)
• Period (.), forward slash (/), underscore (_), percent (%)

The name must not contain leading or embedded blanks, but can contain trailing blanks. A null character can be used to indicate the end of significant data in the name; the null and any characters following it are treated as blanks. The following restrictions apply in the environments indicated:

• On systems that use EBCDIC Katakana, lowercase characters cannot be used.
• On z/OS, names that begin or end with an underscore cannot be processed by the operations and control panels. For this reason, avoid such names.
• On IBM i, enclose names containing lowercase characters, forward slash, or percent in quotation marks when specified on commands. Do not specify these quotation marks in the QMgrName parameter.

If the name consists entirely of blanks, the name of the default queue manager is used. However, note the use of blank queue manager names described in the section on IBM MQ MQI client applications.

The name specified for QMgrName must be the name of a connectable queue manager or, if queue manager groups are being used, the name of the queue manager group..

On z/OS, the queue managers to which it is possible to connect are determined by the environment:

• For CICS, you can use only the queue manager to which the CICS system is connected. The QMgrName parameter must still be specified, but its value is ignored; blank characters are a suitable option.
• For IMS, only queue managers that are listed in the subsystem definition table (CSQQDEFV), and listed in the SSM table in IMS, are connectable (see usage note 6 ).
• For z/OS batch and TSO, only queue managers that reside on the same system as the application are connectable (see usage note 6 ).

Queue sharing groups: On systems where several queue managers exist and are configured to form a queue sharing group, the name of the queue sharing group can be specified for QMgrName in place of the name of a queue manager. This allows the application to connect to any queue manager that is available in the queue sharing group and that is on the same z/OS image as the application. The system can also be configured so that using a blank QMgrName connects to the queue sharing group instead of to the default queue manager.

If QMgrName specifies the name of the queue sharing group, but there is also a queue manager with that name on the system, connection is made to the latter in preference to the former. Only if that connection fails is connection to one of the queue managers in the queue sharing group attempted.

If the connection is successful, you can use the handle returned by the MQCONN or MQCONNX call to access all the resources (both shared and nonshared) that belong to the queue manager to which connection has been made. Access to these resources is subject to the typical authorization controls.

If the application issues two MQCONN or MQCONNX calls to establish concurrent connections, and one or both calls specifies the name of the queue sharing group, the second call returns completion code MQCC_WARNING and reason code MQRC_ALREADY_CONNECTED when it connects to the same queue manager as the first call.

Queue sharing groups are supported only on z/OS. Connection to a queue sharing group is supported only in the batch, RRS batch, CICS, and TSO environments. For CICS, you can use only the queue sharing group to which the CICS system is connected. You must still specify the QMgrName parameter, but its value is ignored; blank characters are a suitable option.

Attention: IMS is unable to connect to a queue sharing group.

IBM MQ MQI client applications: For IBM MQ MQI client applications, a connection is attempted for each client-connection channel definition with the specified queue manager name, until one is successful. The queue manager, however, must have the same name as the specified name. If an all-blank name is specified, each client-connection channel with an all-blank queue manager name is tried until one is successful; in this case there is no check against the actual name of the queue manager.

IBM MQ client applications are not supported in z/OS, but z/OS can act as an IBM MQ server, to which IBM MQ client applications can connect.

IBM MQ MQI client queue manager groups: If the specified name starts with an asterisk (*), the queue manager to which connection is made might have a different name from that specified by the application. The specified name (without the asterisk) defines a group of queue managers that are eligible for connection. The implementation selects one from the group by trying each one in turn until one is found to which a connection can be made. The order in which connections are attempted is influenced by the client channel weight and connection affinity values of the candidate channels. If none of the queue managers in the group is available for connection, the call fails. Each queue manager is tried once only. If an asterisk alone is specified for the name, an implementation-defined default queue manager group is used.

Queue manager groups are supported only for applications running in an MQ-client environment; the call fails if a non-client application specifies a queue manager name beginning with an asterisk. A group is defined by providing several client connection channel definitions with the same queue manager name (the specified name without the asterisk), to communicate with each of the queue managers in the group. The default group is defined by providing one or more client connection channel definitions, each with a blank queue manager name (specifying an all-blank name therefore has the same effect as specifying a single asterisk for the name for a client application).

After connecting to one queue manager of a group, an application can specify blanks in the typical way in the queue manager name fields in the message and object descriptors to mean the name of the queue manager to which the application has connected (the local queue manager ). If the application needs to know this name, use the MQINQ call to inquire the QMgrName queue manager attribute.

Prefixing an asterisk to the connection name implies that the application does not depend on connecting to a particular queue manager in the group. Suitable applications are:

• Applications that put messages but do not get messages.
• Applications that put request messages and then get the reply messages from a temporary dynamic queue.

Unsuitable applications are ones that need to get messages from a particular queue at a particular queue manager; such applications must not prefix the name with an asterisk.

If you specify an asterisk, the maximum length of the remainder of the name is 47 characters.

The length of this parameter is given by MQ_Q_MGR_NAME_LENGTH.

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
32 bit Windows applications	Thread
64 bit Windows applications	Thread

On z/OS for CICS applications the value returned is:

MQHC_DEF_HCONN

Default connection handle.

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

For detailed information about these codes, see Messages and reason codes.

Usage notes

1. The queue manager to which connection is made using the MQCONN call is called the local queue manager.
2. Queues that are owned by the local queue manager appear to the application as local queues. It is possible to put messages on and get messages from these queues.

   Shared queues that are owned by the queue sharing group to which the local queue manager belongs appear to the application as local queues. It is possible to put messages on and get messages from these queues.

   Queues that are owned by remote queue managers appear as remote queues. It is possible to put messages on these queues, but not to get messages from these queues.

3. If the queue manager fails while an application is running, the application must issue the MQCONN call again to obtain a new connection handle to use on subsequent IBM MQ calls. The application can issue the MQCONN call periodically until the call succeeds.

   If an application is not sure whether it is connected to the queue manager, the application can safely issue an MQCONN call to obtain a connection handle. If the application is already connected, the handle returned is the same as that returned by the previous MQCONN call, but with completion code MQCC_WARNING and reason code MQRC_ALREADY_CONNECTED.

4. When the application has finished using IBM MQ calls, the application must use the MQDISC call to disconnect from the queue manager.
5. If the MQCONN call fails with completion code equal to MQCC_FAILED, then the Hconn value is undefined.
6. On z/OS:
   • Batch, TSO, and IMS applications must issue the MQCONN call to use the other IBM MQ calls. These applications can connect to more than one queue manager concurrently.

     If the queue manager fails, the application must issue the call again after the queue manager has restarted to obtain a new connection handle.

     Although IMS applications can issue the MQCONN call repeatedly, even when already connected, this is not recommended for online message processing programs (MPPs).

   • CICS applications do not have to issue the MQCONN call to use the other IBM MQ calls, but can do so if they want; both the MQCONN call and the MQDISC call are accepted. However, it is not possible to connect to more than one queue manager concurrently.

     If the queue manager fails, these applications are automatically reconnected when the queue manager restarts, and so do not need to issue the MQCONN call.

7. On z/OS, to define the available queue managers:
   • For batch applications, system programmers can use the CSQBDEF macro to create a module (CSQBDEFV) that defines the default queue manager name, or queue sharing group name.
   • For IMS applications, system programmers can use the CSQQDEFX macro to create a module (CSQQDEFV) that defines the names of the available queue managers and specifies the default queue manager.

     In addition, each queue manager must be defined to the IMS control region and to each dependent region accessing that queue manager. To do this, you must create a subsystem member in the IMS.PROCLIB library and identify the subsystem member to the applicable IMS regions. If an application attempts to connect to a queue manager that is not defined in the subsystem member for its IMS region, the application abends.

   For more information about using these macros, see Macros intended for customer use.

8. On IBM i, programs that end abnormally are not automatically disconnected from the queue manager. Write applications to allow for the possibility of the MQCONN or MQCONNX call returning completion code MQCC_WARNING and reason code MQRC_ALREADY_CONNECTED. Use the connection handle returned in this situation as normal.

C invocation

MQCONN (QMgrName, &Hconn, &CompCode, &Reason);

MQCHAR48  QMgrName;  /* Name of queue manager */
MQHCONN   Hconn;     /* Connection handle */
MQLONG    CompCode;  /* Completion code */
MQLONG    Reason;    /* Reason code qualifying CompCode */

COBOL invocation

CALL 'MQCONN' USING QMGRNAME, HCONN, COMPCODE, REASON.

**   Name of queue manager
 01  QMGRNAME  PIC X(48).
**   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 MQCONN (QMgrName, Hconn, CompCode, Reason);

dcl QMgrName  char(48);       /* Name of queue manager */
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 MQCONN,(QMGRNAME,HCONN,COMPCODE,REASON)

QMGRNAME  DS  CL48  Name of queue manager
HCONN     DS  F     Connection handle
COMPCODE  DS  F     Completion code
REASON    DS  F     Reason code qualifying COMPCODE

Visual Basic invocation

MQCONN QMgrName, Hconn, CompCode, Reason

Dim QMgrName As String*48 'Name of queue manager'
Dim Hconn    As Long      'Connection handle'
Dim CompCode As Long      'Completion code'
Dim Reason   As Long      'Reason code qualifying CompCode'