+

Search Tips | Advanced Search

MQCONN - Connect queue manager

The MQCONN call connects an application program to a queue manager.

It provides a queue manager connection handle, which the application uses on subsequent message queuing calls.

A client connection cannot be made on a server only installation, and a local connection cannot be made on a client only installation.


Syntax

MQCONN (QMgrName, Hconn, CompCode, Reason)


Parameters


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);
Declare the parameters as follows: 
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.
Declare the parameters as follows: 
**   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);
Declare the parameters as follows: 
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)
Declare the parameters as follows: 
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
Declare the parameters as follows: 
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'