The WebSphere MQ for z/OS interface with the application environment

To allow applications running in different environments to send and receive messages through a message queuing network, WebSphere MQ for z/OS provides an adapter for each of the environments it supports. These adapters are the interface between application programs and WebSphere MQ for z/OS subsystems. They allow the programs to use the MQI.

The batch adapter

The batch adapter provides access to WebSphere MQ for z/OS resources for programs running in:

• Task (TCB) mode
• Problem or Supervisor state
• Primary address space control mode

The programs must not be in cross-memory mode.

Connections between application programs and WebSphere MQ for z/OS are at the task level. The adapter provides a single connection thread from an application task control block (TCB) to WebSphere MQ for z/OS.

The adapter supports a single-phase commit protocol for changes made to resources owned by WebSphere MQ for z/OS; it does not support multiphase-commit protocols.

RRS batch adapter

The transaction management and recoverable resource manager services (RRS) adapter:

• Uses z/OS RRS for commit control.
• Supports simultaneous connections to multiple WebSphere MQ subsystems running on a single z/OS instance from a single task.
• Provides z/OS-wide coordinated commitment control (via z/OS RRS) for recoverable resources accessed via z/OS RRS compliant recoverable managers for:
  • Applications that connect to WebSphere MQ using the RRS batch adapter.
  • DB2 stored procedures executing in a DB2 stored procedures address space that is managed by a workload manager (WLM) on z/OS.
• Supports the ability to switch a WebSphere MQ batch thread between TCBs.

WebSphere MQ for z/OS provides two RRS batch adapters:

CSQBRSTB

This adapter requires you to change any MQCMIT and MQBACK statements in your WebSphere MQ application to SRRCMIT and SRRBACK respectively. (If you code MQCMIT or MQBACK in an application linked with CSQBRSTB, you will receive MQRC_ENVIRONMENT_ERROR.)

CSQBRRSI

This adapter allows your WebSphere MQ application to use either MQCMIT and MQBACK or SRRCMIT and SRRBACK.

Note:

CSQBRSTB and CSQBRRSI are shipped with linkage attributes AMODE(31) RMODE(ANY). If your application loads either stub below the 16 MB line, you must first relink the stub with RMODE(24).

Migration

It is possible to migrate existing Batch/TSO WebSphere MQ applications to exploit RRS coordination with few or no changes. If you link-edit your WebSphere MQ application with the CSQBRRSI adapter, MQCMIT and MQBACK syncpoint your unit of work across WebSphere MQ and all other RRS-enabled resource managers. If you link-edit your WebSphere MQ application with the CSQBRSTB adapter you must change MQCMIT and MQBACK to SRRCMIT and SRRBACK respectively. The latter approach may be preferable as it clearly indicates that the syncpoint is not restricted to WebSphere MQ resources only.

The CICS adapter

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:

• A trigger monitor (or task initiator) program that can start programs automatically when certain trigger conditions on a queue are met. For more information, see Chapter 14, Starting WebSphere MQ applications using triggers.
• An API-crossing exit that can be invoked before and after each MQI call. For more information, see The API-crossing exit for z/OS.
• A trace facility to help you when debugging programs.
• Facilities that allow the MQI calls to be executed under multiple z/OS TCBs. For more information, see the WebSphere MQ for z/OS Concepts and Planning Guide.

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 be taken into consideration 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 re-issues 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.

If there are multiple messages to be put, MQOPEN-MQPUT...MQPUT-MQCLOSE should be used.

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 on a per MQI call basis 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 you must 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:

MQRC_CONNECTION_BROKEN

MQRC_Q_MGR_NAME_ERROR

MQRC_Q_MGR_NOT_AVAILABLE

MQRC_Q_MGR_STOPPING

MQRC_CONNECTION_STOPPING

MQRC_CONNECTION_NOT_AUTHORIZED

This runaway mechanism can be activated only after the adapter has been enabled once. Before the adapter has been enabled, such a task will loop 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 re-established. 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.

• Before the MQI call is executed:
  • CEDF displays the addresses of the call parameters
  • You can use the Working Storage key to verify or modify their contents
  • You can skip the call by overtyping the command with NOOP
• After the call has completed:
  • The results are returned in the program's storage
  • The return code and reason code are displayed in the call parameter list
  • You can modify them before returning to the application program

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

The IMS adapter

The IMS adapter provides access to WebSphere MQ for z/OS resources for

• On-line message processing programs (MPPs)
• Interactive Fast Path programs (IFPs)
• Batch message processing programs (BMPs)

To use these resources, the programs must be running in task (TCB) mode and problem state; they must not be in cross-memory mode or access-register mode.

The adapter provides a connection thread from an application task control block (TCB) to WebSphere MQ. The adapter supports a two-phase commit protocol for changes made to resources owned by WebSphere MQ for z/OS, with IMS acting as the syncpoint coordinator.

The adapter also provides a trigger monitor program that can start programs automatically when certain trigger conditions on a queue are met. For more information, see Chapter 14, Starting WebSphere MQ applications using triggers.

If you are writing batch DL/I programs, follow the guidance given in this book for z/OS batch programs.