SET MQCONN

Change information about the attributes of the connection between CICS® and WebSphere® MQ, and start or stop the connection.

SET MQCONN

Conditions: NORMAL, NOTAUTH, NOTFND, INVREQ

This command is threadsafe.

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

Use the SET MQCONN command to change attributes of the currently installed MQCONN resource definition, which defines the connection to WebSphere MQ, and to start and stop the connection.

Because only one MQCONN resource definition can be installed at a time, the name of the MQCONN resource definition is not required on input.

This command does not set the INITQNAME attribute of the MQCONN resource definition, which specifies the name of the default initiation queue. If you want to change the MQINI resource definition, you must reinstall the MQCONN resource definition with an appropriate MQINI attribute.

Restriction: This command cannot be used in a remote program that is linked by a distributed program link command.

Options

BUSY

This option is valid only with CONNECTST when setting the CICS-WebSphere MQ connection NOTCONNECTED. If you specify CONNECTED, BUSY is ignored. The CVDA values are as follows:

FORCE: Any CICS transactions currently by using WebSphere MQ are abnormally ended, and the connection to WebSphere MQ is stopped. The request is synchronous in nature; that is, control is not returned to the application until the connection is stopped.
NOWAIT: The connection to WebSphere MQ is quiesced. Existing transactions are allowed to finish before the connection is stopped. The request is asynchronous in nature; that is, control is returned to the application before the connection is stopped.
WAIT: The connection to WebSphere MQ is quiesced. Existing transactions are allowed to finish before the connection is stopped. The request is synchronous in nature; that is, control is not returned to the application until the connection is stopped. WAIT is the default.

CONNECTST

Starts or stops the connection between CICS and WebSphere MQ. The CVDA values are as follows:

CONNECTED: Starts the CICS-WebSphere MQ connection. This action has the same effect as issuing a CKQC START command to start the CICS-WebSphere MQ adapter. If the requested queue manager is active, control returns when CICS and WebSphere MQ are connected. If the requested queue manager is not active, CICS returns a NORMAL response with RESP2=8, indicating that the CICS-WebSphere MQ adapter is in connecting state and reconnects to WebSphere MQ as soon as the requested queue manager becomes active.
NOTCONNECTED: Stops the CICS-WebSphere MQ connection. The value that you specify for the BUSY option determines whether existing transactions are stopped or allowed to complete, and at what stage control is returned to the application. The default is BUSY(WAIT), allowing existing transactions to finish before the connection is stopped, and not returning control to the application until the connection is stopped.

MQNAME

Specifies the 1 - 4 character name of a WebSphere MQ queue manager or queue-sharing group to which CICS is to connect. CICS attempts to connect to the queue manager or to any active member of the queue-sharing group. You can change MQNAME only when CICS is not connected to WebSphere MQ.

When you specify MQNAME, the queue manager name or queue-sharing group that you specified in the MQNAME attribute of the installed MQCONN resource definition is replaced with the name that you specified on this command. If you want to revert to the original queue manager or queue-sharing group, set MQNAME again.

RESYNCMEMBER

This option applies only if you have specified a queue-sharing group for the CICS-WebSphere MQ connection. RESYNCMEMBER specifies the strategy that CICS adopts if outstanding units of work are being held for the last queue manager to which CICS was connected from the queue-sharing group.

Changing the setting for RESYNCMEMBER must be done only when all resources are in a consistent state; that is, there are no indoubt units of work outstanding otherwise CICS is not able to resynchronize the WebSphere MQ units of work. It is important to ensure that all resources are in a consistent state before changing RESYNCMEMBER to or from GROUPRESYNC.

Units of work that are shunted indoubt are not included in this process, because CICS itself cannot resolve those units of work at this time. Resynchronization for those UOWs occurs when CICS has resynchronized with its remote coordinator.

The CVDA values are as follows:

RESYNC

CICS connects to the same queue manager.

NORESYNC

CICS makes one attempt to connect to the same queue manager. If that attempt fails, CICS connects to any member of the queue-sharing group and issues a warning message about the outstanding units of work.

GROUPRESYNC

CICS connects to any member of the queue-sharing group. The queue manager is chosen by WebSphere MQ and it asks CICS to resolve indoubt units of work on behalf of all eligible queue managers in the queue-sharing group. This function is called group unit of recovery. The GROUPRESYNC option can be used only when you are running a release of WebSphere MQ that supports group unit of recovery for CICS and when the GROUPUR attribute has been enabled in the WebSphere MQ queue managers.

When an attempt is made to connect CICS to WebSphere MQ by using an EXEC CICS SET MQCONN CONNECTED command and RESYNCMEMBER(GROUPRESYNC) is set but WebSphere MQ does not support group unit of recovery, or group unit of recovery is not enabled, then WebSphere MQ rejects the connection attempt. The connection attempt results in the SET command failing with INVREQ and RESP2=9 (connection error).

Do not change the setting for RESYNCMEMBER when units of work are outstanding in WebSphere MQ because this means that units of work cannot be resolved. A unit of work held in CICS is identified with a resource manager qualifier. When RESYNCMEMBER(GROUPRESYNC) is used the qualifier is the name of the queue-sharing group, otherwise the qualifier used is the name of the individual queue manager.

Conditions

NORMAL

RESP2 values:

8: Waiting for WebSphere MQ. This situation can occur following a CONNECTST with a CVDA of CONNECT.

NOTAUTH

The user associated with the issuing task is not authorized to use this command, or is not authorized to access this resource.

RESP2 values:

100: Command authorization failure.

NOTFND

RESP2 values:

1: No MQCONN resource definition is currently installed.

INVREQ

RESP2 values:

2: SET NOTCONNECTED with the FORCE or WAIT option has been specified, but this transaction is itself using the CICS-WebSphere MQ interface.
3: MQNAME cannot be set because the connection is active.
4: BUSY value is not valid.
5: MQNAME contains characters that are not valid.
6: CONNECTST value is not valid.
7: RESYNCMEMBER value is not valid.
9: Connection error.
10: MQNAME value is not a valid queue manager or queue-sharing group.