Use of RRMS with the external CICS interface

You can use z/OS recoverable resource management services (RRMS) to coordinate distributed program link (DPL) requests.

To use RRMS to coordinate DPL requests, ensure that the following conditions are met:
  • The EXCI client and the CICS® region to which it sends DPL requests run in the same MVS™ image. This is an RRMS restriction, and does not apply to DPL requests that specify SYNCONRETURN.
  • The CICS region that receives the DPL requests is started with RRMS=YES specified as a system initialization parameter (the default is RRMS=NO).
  • Resource recovery services (RRS) run in the MVS image where CICS and the client program execute. See z/OS MVS Programming: Resource Recovery.

The following figure shows how the external CICS interface and CICS use RRMS. It shows the flow between the MVS batch region that contains the external CICS interface and the EXCI client program, and the CICS server region that contains the CICS mirror and a CICS application program. The numbers on the diagram refer to the principal steps in a unit of recovery (UR), as listed after the figure.

Figure 1. Conceptual view of EXCI client and CICS server region using RRMS
Figure is described in surrounding text
  1. If the CICS system initialization parameter RRMS=YES is specified, CICS registers with RRMS as a resource manager. This registration occurs during CICS initialization.
  2. When the EXCI client program issues a DPL_Request call in 2-phase commit mode (a call that omits the SYNCONRETURN option), it receives the following from RRMS:
    • A unit-of-recovery identifier (URID)
    • A context token
    • A pass token
  3. The URID and the tokens obtained by EXCI on behalf of the client program are included on the DPL request that is passed to the CICS server region. If the DPL request is the first one in the UR, CICS calls RRS to express an interest in the UR, attaches a new mirror transaction, and validates the tokens. If the request is valid, the mirror program links to the specified server application program. The server program completes its work, which is all performed in the UR. This work can include updating recoverable resources in the local server region, or daisy chaining to other CICS regions.
  4. When the server program completes, it returns the communications area (COMMAREA) or channels and containers , with return codes, to the client program.
    Note: Steps 3 and 4 can repeated many times for the same UR.
  5. When the EXCI client program is ready to commit or back out its changes, the program invokes RRS to begin the 2-phase commit protocol.
  6. RRS acts as coordinator and completes one of the following actions:
    • RRS asks the resource managers to prepare to commit all updates in the UR. Resource managers other than the CICS server region might also express an interest in the UR. If all vote yes, RRS tells them to go ahead and commit the changes. If any vote no, RRS tells all the resource managers to back out all the changes made in the UR.
    • RRS tells all the resource managers that express an interest in the UR to back out all the changes made in the UR.
    The UR is now complete and CICS detaches the mirror task. If the EXCI client sends any new DPL requests after this point, EXCI starts a new UR and CICS attaches a new mirror transaction.

Each DPL request that specifies the SYNCONRETURN option attaches a new mirror task in the target CICS region. The first DPL request that does not specify SYNCONRETURN also attaches a new mirror task, but subsequent requests are directed to the same mirror task. When a sync point takes place, the mirror task ends, and the next non-SYNCONRETURN request attaches a new mirror. See Figure 2 . In this figure, an MVS client application issues DPL requests with and without SYNCONRETURN. The numbers on the figure refer to the principal flow, as listed after the figure.

Figure 2. Effect of mixing DPL requests with and without the SYNCONRETURN option
Figure is described in surrounding text
  1. Client issues a DPL request without the SYNCONRETURN option.

    Because no mirror transaction is running, a new mirror (Mirror 1) is attached.

  2. The DPL request completes, and because it was issued without the SYNCONRETURN option, the mirror transaction waits for another request.
  3. Client issues DPL request with the SYNCONRETURN option.

    A new mirror transaction (Mirror 2) is attached.

  4. On completion of the DPL request, resources updated by the mirror transaction are committed, and the mirror transaction ends.
  5. Client issues another DPL request without the SYNCONRETURN option. Mirror 1 receives and executes the DPL request.
  6. The DPL request completes, and once again, the mirror transaction waits for another request.
  7. Client issues DPL request with the SYNCONRETURN option.

    A new mirror transaction (Mirror 3) is attached.

  8. On completion of the DPL request, resources updated by the mirror transaction are committed, and the mirror transaction ends.
  9. The client program requests a syncpoint. Resources updated by mirror 1 are committed, and the transaction ends.