Home

 

QMgrName (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 i5/OS, 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.

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

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

• For CICS, we 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; blanks are recommended.

• 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, we 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 usual 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, and TSO environments.

MQ client applications: For MQ 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.

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

MQ 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 (in no defined 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 usual 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 those 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.

Queue-manager groups are not supported on z/OS.

The length of this parameter is given by MQ_Q_MGR_NAME_LENGTH.

 

Home