Resource recovery

Resource recovery consists of the protocols and program interfaces that allow an application program to make consistent changes to multiple protected resources. The external CICS® interface supports resource recovery.

A CICS server program that is invoked by an external CICS interface request can update recoverable resources; the changes are committed when the mirror transaction in the CICS server region takes a syncpoint. The client program can determine when syncpointing should occur. There are two options:

These options are controlled as follows:

If you specify SYNCONRETURN, a syncpoint is taken on completion of each DPL request. If SYNCONRETURN is omitted, a syncpoint is taken when the client program requests it using the interfaces described in Taking a syncpoint in the client program.

Using RRMS with the external CICS interface

To use RRMS to coordinate DPL requests, ensure that:

For an illustration of the concept of the external CICS interface and CICS using RRMS, see Figure 20.

Figure 20. Conceptual view of EXCI client and CICS server region using RRMS. The main (numbered) steps within a unit-of-recovery are described in the list following the diagram
 Diagram showing an MVS batch region with the External CICS Interface and an EXCI lient program and a CICS Server Region with the CICS mirror and a CICS application program. The flow between them is described in the following 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 from RRMS:
  3. The URID and the tokens obtained by EXCI on behalf of the client program are included on the DPL request passed to the CICS server region. If the DPL request is the first one within 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 within the unit-of-recovery. 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) and 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 either: 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 unit-of-recovery 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 syncpoint takes place, the mirror task ends, and the next non-SYNCONRETURN request attaches a new mirror. To see the effect of mixing DPL requests with and without the SYNCONRETURN option, see Figure 21.

Figure 21. Effect of mixing DPL requests with and without SYNCONRETURN
 An MVS client application issuing DPL requests with and without SYNCONRETURN with results described in the following text
  1. Client issues DPL request omitting SYNCONRETURN.

    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 omitting SYNCONRETURN. 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.

Taking a syncpoint in the client program

To commit changes instigated by the client program, use one of the following MVS callable services:

Application_Commit_UR (SRRCMIT)
For a description of Application_Commit_UR, see OS/390 MVS Programming: Callable Services for High-Level Languages.
Commit_UR (ATRCMIT)
For a description of Commit_UR, see OS/390 MVS Programming: Resource Recovery.

To backout changes in the client program, use one of the following services:

Application_Backout_UR (SRRBACK)
For a description of Application_Backout_UR, see OS/390 MVS Programming: Callable Services for High-Level Languages.
Backout_UR (ATRBACK)
For a description of Backout_UR, seeOS/390 MVS Programming: Resource Recovery.

If none of these interfaces is used, changes are committed or backed out explicitly when the client program either ends normally or abends. The use of implicit commit or backout is not recommended:

Related concepts
The EXCI programming interfaces
Introduction to the external CICS interface
EXCI concepts
Requirements for the external CICS interface
Related tasks
The EXCI CALL interface
The EXCI EXEC CICS interface

1.
RRMS comprises three OS/390 components: registration services, context services, and resource recovery services (RRS)
2.
A unit of recovery is analogous to a CICS unit of work

[[ Contents Previous Page | Next Page Index ]]