Examples of MQCONN calls

In each of the following examples, the network is the same; there is a connection defined to two servers from the same WebSphere MQ client. (In these examples, the MQCONNX call could be used instead of the MQCONN call.)

There are two queue managers running on the server machines, one named SALE and the other named SALE_BACKUP.


The definitions for the channels in these examples are:

SALE definitions: 



DEFINE CHANNEL(ALPHA) CHLTYPE(SVRCONN) TRPTYPE(TCP) +
DESCR('Server connection to WebSphere MQ client')
 
DEFINE CHANNEL(APLHA) CHLTYPE(CLNTCONN) TRPTYPE(TCP) +
CONNAME(9.20.4.26) DESCR('WebSphere MQ client connection to server 1') +
QMNAME(SALE)
 
DEFINE CHANNEL(BETA) CHLTYPE(CLNTCONN) TRPTYPE(TCP) +
CONNAME(9.20.5.26) DESCR('WebSphere MQ client connection to server 2') +
QMNAME(SALE)

SALE_BACKUP definition: 



DEFINE CHANNEL(BETA) CHLTYPE(SVRCONN) TRPTYPE(TCP) +
DESCR('Server connection to WebSphere MQ client')

The client channel definitions can be summarized as follows:

Name CHLTYPE TRPTYPE CONNAME QMNAME
ALPHA CLNTCONN TCP 9.20.4.26 SALE
BETA CLNTCONN TCP 9.20.5.26 SALE

 

What the examples demonstrate

Suppose the communication link to Server 1 is temporarily broken. The use of multiple queue managers as a backup system is demonstrated.

Each example covers a different MQCONN call and gives an explanation of what happens in the specific example presented, by applying the following rules:

  1. WebSphere MQ searches the client channel definition table, in channel name order, looking in the queue manager name (QMNAME) field for an entry corresponding to the one given in the MQCONN call.

  2. If a match is found, the transmission protocol and the associated connection name are extracted.

  3. An attempt is made to start the channel to the machine identified by the connection name (CONNAME). If this is successful, the application continues. It requires:

    • A listener to be running on the server.

    • The listener to be connected to the same queue manager as the one the client wishes to connect to (if specified).

  4. If the attempt to start the channel fails and there is more than one entry in the client channel definition table (in this example there are two entries), the file is searched for a further match. If a match is found, processing continues at step 1.

  5. If no match is found, or there are no more entries in the client channel definition table and the channel has failed to start, the application is unable to connect. An appropriate reason code and completion code are returned in the MQCONN call. The application can take action based on the reason and completion codes returned.

 

Example 1. Queue manager name includes an asterisk (*)

In this example the application is not concerned about which queue manager it connects to. The application issues: 

MQCONN (*SALE)

Following the rules, this is what happens in this instance:

  1. The client channel definition table is scanned (in channel name order) for the queue manager name SALE, matching with the application MQCONN call.

  2. The first channel definition found to match is ALPHA.

  3. An attempt to start the channel is made - this is NOT successful because the communication link is broken.

  4. The client channel definition table is again scanned for the queue manager name SALE and the channel name BETA is found.

  5. An attempt to start the channel is made - this is successful.

  6. A check to see that a listener is running shows that there is one running. It is not connected to the SALE queue manager, but because the MQI call parameter has an asterisk (*) included in it, no check is made. The application is connected to the SALE_BACKUP queue manager and continues processing.

 

Example 2. Queue manager name specified

The application requires a connection to a specific queue manager, named SALE, as seen in the MQI call: 

MQCONN (SALE)

Following the rules, this is what happens in this instance:

  1. The client channel definition table is scanned (in channel name order) for the queue manager name SALE, matching with the application MQCONN call.

  2. The first channel definition found to match is ALPHA.

  3. An attempt to start the channel is made - this is not successful because the communication link is broken.

  4. The client channel definition table is again scanned for the queue manager name SALE and the channel name BETA is found.

  5. An attempt to start the channel is made - this is successful.

  6. A check to see that a listener is running shows that there is one running, but it is not connected to the SALE queue manager.

  7. There are no further entries in the client channel definition table. The application cannot continue and receives return code MQRC_Q_MGR_NOT_AVAILABLE.

 

Example 3. Queue manager name is blank or an asterisk (*)

In this example the application is not concerned about which queue manager it connects to. This is treated in the same way as Example 1. Queue manager name includes an asterisk (*).

Note:
If this application were running in an environment other than a WebSphere MQ client, and the name was blank, it would be attempting to connect to the default queue manager. This is not the case when it is run from a client environment, as there can be more than one default queue manager.

The application issues: 

MQCONN ("")

or 

MQCONN (*)

Following the rules, this is what happens in this instance:

  1. The client channel definition table is scanned (in channel name order) for a queue manager name that is blank, matching with the application MQCONN call.

  2. The entry for the channel name ALPHA has a queue manager name in the definition of SALE. This does not match the MQCONN call parameter, which requires the queue manager name to be blank.

  3. The next entry is for the channel name BETA.

  4. The queue manager name in the definition is SALE. Once again, this does not match the MQCONN call parameter, which requires the queue manager name to be blank.

  5. There are no further entries in the client channel definition table. The application cannot continue and receives return code MQRC_Q_MGR_NOT_AVAILABLE.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.