MQCONN (Connect queue manager) on IBM i

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

  • Applications must use the MQCONN or MQCONNX call to connect to the queue manager, and the MQDISC call to disconnect from the queue manager.

On IBM MQ for Windows, UNIX, and IBM i, each thread in an application can connect to different queue managers. On other systems, all concurrent connections within a process must be to the same queue manager.


Syntax

MQCONN (QMNAME, HCONN, CMPCOD, REASON)


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 possible 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 in order 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 in order 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 CCWARN and reason code RC2002.

  4. When the application has finished using IBM MQ calls, the application should use the MQDISC call to disconnect from the queue manager.
  5. On IBM i, programs that end abnormally are not automatically disconnected from the queue manager. Therefore applications should be written to allow for the possibility of the MQCONN or MQCONNX call returning completion code CCWARN and reason code RC2002. The connection handle returned in this situation can be used as normal.


Parameters

The MQCONN call has the following parameters:

    QMNAME (48-byte character string) - input

    Name of queue manager.

    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 might 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 IBM i, names containing lowercase characters, forward slash, or percent must be enclosed in quotation marks when specified on commands. These quotation marks must not be specified in the QMNAME parameter.

    If the name consists entirely of blanks, the name of the default queue manager is used.

    The name specified for QMNAME must be the name of a connectable queue manager.

    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 QMNAME 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. The system can also be configured so that a blank QMNAME causes connection to the queue sharing group instead of to the default queue manager.

    If QMNAME 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, the handle returned by the MQCONN or MQCONNX call can be used to access all of the resources (both shared and nonshared) that belong to the particular 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 in order to establish concurrent connections, and one or both calls specifies the name of the queue sharing group, the second call may return completion code CCWARN and reason code RC2002. This occurs when the second call 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, and TSO environments.

    IBM MQ 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 queue manager groups: If the specified name starts with an asterisk (*), the actual queue manager to which connection is made may have a name that is different 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, in alphabetic order, until one is found to which a connection can be made. 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 actually connected (the local queue manager ). If the application needs to know this name, the MQINQ call can be issued to inquire the QMgrName queue manager attribute.

    Prefixing an asterisk to the connection name implies that the application is not dependent on connecting to a particular queue manager in the group. Suitable applications would be:

    • 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 would be those that need to get messages from a particular queue at a particular queue manager; such applications should not prefix the name with an asterisk.

    Note that if an asterisk is specified, the maximum length of the remainder of the name is 47 characters.

    The length of this parameter is given by LNQMN.

    HCONN (10-digit signed integer) - output

    Connection handle.

    This handle represents the connection to the queue manager. It must be specified 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.

    The scope of the handle is restricted to the smallest unit of parallel processing supported by the platform on which the application is running; the handle is not valid outside the unit of parallel processing from which the MQCONN call was issued.

    • On IBM i, the scope of the handle is the job issuing the call.

    CMPCOD (10-digit signed integer) - output

    Completion code.

    It is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

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

    If CMPCOD is CCWARN:

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

    If CMPCOD is CCFAIL:

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

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

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

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

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

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

      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.

      RC2063
      (2063, X'80F') Security error occurred.

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

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


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQCONN(QMNAME : HCONN : CMPCOD :
     C                                      REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQCONN           PR                  EXTPROC('MQCONN')
     D* Name of queue manager
     D QMNAME                        48A
     D* Connection handle
     D HCONN                         10I 0
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0
Parent topic: Function calls on IBM i