The CICS adapter

Note to users

If you are using the CICS(R) adapter from a WebSphere MQ for z/OS system, ensure that CICS can obtain sufficient storage to accommodate messages up to 100 MB long.

A CICS system can have only one connection to a WebSphere MQ for z/OS queue manager, and this connection is managed by the WebSphere MQ for z/OS CICS adapter. The CICS adapter provides access to WebSphere MQ for z/OS resources for CICS programs.

In addition to providing access to the MQI calls, the adapter provides:

CICS adapter performance considerations

This section describes how the CICS adapter optimizes the performance of a CICS to WebSphere MQ connection.

There are a number of factors to consider when performance is critical:

First MQI call
In general, the first MQI call of a task takes longer to perform than subsequent calls. This is because the environment must be set up. For example, the adapter must acquire storage and security information, and control blocks must be allocated and formatted.
MQGET and the SIGNAL option
Using the SIGNAL option with an MQGET call imposes an additional overhead. This is because the SIGNAL option can produce a CICS GETMAIN in the adapter, which is used to record the address of the ECB so that it can be posted if the queue manager abends.
API-crossing exit
Using the API-crossing exit also imposes a host processor overhead on each MQI call. The overhead in handling the exit parameter block and the invocations are minimal, but the exit can be invoked twice for each MQI call through EXEC CICS LINK.
CICS tracing
CICS tracing in the adapter also increases the pathlength of an MQI call. A large number of trace entries can be generated depending on how busy the system is. There is no control over the granularity of the trace entries produced in the adapter. Therefore, tracing should only be switched on if necessary.
MQGET and the WAIT option
Using MQGET with the WAIT option is less efficient if the task has been put into a wait until a message arrives. The adapter implements the wait as a form of CICS wait. When a message arrives, the adapter effectively reissues the MQGET call for the application.

Therefore, use the WAIT option with care.

MQCLOSE
Issuing an MQCLOSE call is not always necessary because WebSphere MQ automatically closes any unclosed handles when the task ends.
MQPUT1
If there is only one message to be put, MQPUT1 is more efficient than an MQOPEN-MQPUT-MQCLOSE sequence because only one flow is generated between the WebSphere MQ and the adapter, instead of three.

To put multiple messages, use MQOPEN-MQPUT...MQPUT-MQCLOSE.

EXEC CICS RETURN
Implicit syncpointing generated by EXEC CICS RETURN is more efficient than issuing the explicit syncpoint call EXEC CICS SYNCPOINT followed by EXEC CICS RETURN.

The EXEC CICS RETURN call accommodates all the work needed for syncpointing and task termination into one flow to WebSphere MQ instead of the two separate flows used when explicit syncpointing is used.

Two-phase commit
A two-phase commit consumes more resources than a single-phase commit, both in host processor cost and response time. This is because a two-phase commit involves one more flow to WebSphere MQ and more physical logging. If an application is restricted to recoverable updates in WebSphere MQ and no other resource managers, CICS invokes the adapter for a single-phase commit.
Syncpoint bypassing
The adapter does not use the read-only commit feature in CICS. When a transaction is restricted to non-recoverable or non-destructive work in WebSphere MQ, syncpointing is bypassed because it is not necessary. The clean-up process is performed when the task ends.
Statistics collection
Statistics collection by connection and by task is done for each MQI call and cannot be switched off. This overhead is negligible.

You can use the CKQC transaction to display statistics for the current connection.

The adapter supports a two-phase commit protocol for changes made to resources owned by WebSphere MQ for z/OS, with CICS acting as the syncpoint coordinator.

The CICS adapter also supplies facilities (for use by system programmers and administrators) for managing the CICS-WebSphere MQ for z/OS connection, and for collecting task and connection statistics. These facilities are described in the WebSphere MQ for z/OS System Administration Guide.

Adapter trace points

Application programmers can use trace points related to the MQI calls (for example, CSQCGMGD (get message data)) for debugging CICS application programs. System programmers can use trace points related to system events, such as recovery and task switching, for diagnosing system-related problems. For full details of trace points in the CICS adapter, see the WebSphere MQ for z/OS Problem Determination Guide.

Some trace data addresses are passed by applications. If the address of the trace data is in the private storage area of the CICS region, the contents of the area are traced when necessary. For example, this would be done for the trace entries CSQCGMGD (get message data) or CSQCPMGD (put message data). If the address is not in the private storage area, message CSQC416I is written to the CICS trace; this contains the address in error.

Abends

This section describes some of the things to consider with regard to CICS AEY9 and QLOP abends. For information about all other abends, see the WebSphere MQ for z/OS Messages and Codes.

CICS AEY9 abends

A transaction does not abend with a CICS AEY9 code if it issues an MQI call before the adapter is enabled. Instead, it receives return code MQCC_FAILED and reason code MQRC_ADAPTER_NOT_AVAILABLE.

For more information about CICS AEY9 abends, see the CICS Messages and Codes.

QLOP abends

Tasks abend with the abend code QLOP if a second MQI call is made after a call has been returned with completion code MQCC_FAILED and one of these reason codes:

This runaway mechanism can be activated only after the adapter has been enabled once. Before the adapter has been enabled, such a task loops with reason code set to MQRC_ADAPTER_NOT_AVAILABLE. To avoid this, ensure that your applications respond to the above reason codes either by terminating abnormally or by issuing an EXEC CICS SYNCPOINT ROLLBACK and terminating normally.

If the application does not terminate at this point, it might not issue any further WebSphere MQ calls even if the connection between WebSphere MQ and CICS is reestablished. Once WebSphere MQ is reconnected to CICS, new transactions can use MQI calls as before.

Using the CICS Execution Diagnostic Facility

You can use the CICS execution diagnostic facility (CEDF) to monitor applications that use the CICS adapter. For details of how to use CEDF, see the CICS Application Programming Guide.

CEDF uses standard formatting to display MQI calls.

See WebSphere MQ for z/OS Problem Determination Guide for examples of the output produced by this facility.