SET MQCONN
Change information about the attributes of the connection between CICS® and IBM® MQ, and start or stop the connection.
Syntax
Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).
Conditions: NORMAL, NOTAUTH, NOTFND, INVREQ
NOHANDLE, RESP, and
RESP2 are common options that can be added to all EXEC CICS
commands to process error conditions. They are not explicitly included in the command syntax diagram
and option descriptions. For information about these common options and EXEC CICS
command syntax, see EXEC CICS command format and programming considerations. For more information
about the use of CVDAs, see CICS-value data areas (CVDAs).
This command is threadsafe.
Description
Use the SET MQCONN command to change attributes of the currently installed MQCONN resource definition, which defines the connection to IBM 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 QNAME attribute of the MQMONITOR resource definition DFHMQINI, which was dynamically installed with the MQCONN resource definition and represents the default initiation queue, you must change the INITQNAME attribute of the MQCONN resource definition and then reinstall the MQCONN resource definition.
Options
- BUSY
- This option is valid only with CONNECTST when setting the CICS-MQ connection NOTCONNECTED. If you
specify CONNECTED, BUSY is ignored. The CVDA values are as follows:
- FORCE
- Any CICS transactions currently by using IBM MQ are abnormally ended, and the connection to IBM 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 IBM 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 IBM 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 IBM MQ. The CVDA values are as follows:
- CONNECTED
- Starts the CICS-MQ connection. This action has the same effect as issuing a CKQC START command to start the CICS-MQ adapter. If the requested queue manager is active, control returns when CICS and IBM MQ are connected. If the requested queue manager is not active, CICS returns a NORMAL response with RESP2=8, indicating that the CICS-MQ adapter is in connecting state and reconnects to IBM MQ as soon as the requested queue manager becomes active.
- NOTCONNECTED
- Stops the CICS-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 an IBM 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 IBM 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-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 IBM 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 IBM 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 IBM MQ that supports group unit of recovery
for CICS and when the GROUPUR attribute has been enabled in
the IBM MQ queue managers.
When an attempt is made to connect CICS to IBM MQ by using an EXEC CICS SET MQCONN CONNECTED command and RESYNCMEMBER(GROUPRESYNC) is set but IBM MQ does not support group unit of recovery, or group unit of recovery is not enabled, then IBM 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 IBM 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 IBM 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-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.