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:
- Resource recovery controlled by the CICS server regions. In this case, changes
to recoverable resources are committed at the completion of each DPL request,
independently of the client program. Also, in addition to the syncpoint taken
when the server program returns control to CICS (the SYNCONRETURN option), the server
program can take explicit syncpoints during execution.
- Resource recovery controlled by the EXCI client program with the support
of recoverable resource management services (RRMS). When the client program
requests it, updates made by the server program in successive DPL requests
are committed together.
To support this option, CICS and the external CICS interface both
make use of resource recovery services (RRS), the OS/390® syncpoint manager1,which is an MVS™ component of recoverable resource management
services (RRMS). In the context of RRMS, CICS is a resource manager; the client program may issue requests to other resource managers, and
have resources owned by those resource managers committed in the same unit-of-recovery (UR).2
These options are controlled as follows:
- By the DPL_opts parameter of the DPL_request.
- By the SYNCONRETURN option, either specified or omitted, on the EXEC CICS LINK PROGRAM command.
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.
To use RRMS to coordinate DPL requests, ensure that:
- The EXCI client and the CICS region to which it sends DPL requests
are running 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).
- RRS is running in the MVS image where CICS and the client program execute. See OS/390 MVS Programming: Resource Recovery.
For an illustration of the concept of the external CICS interface and CICS using RRMS, see Figure 20.
- If the CICS system initialization parameter RRMS=YES is specified, CICS registers with RRMS as a resource manager.
This registration occurs during CICS initialization.
- 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:
- A unit-of-recovery identifier (URID)
- A context token
- A pass token
- 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.
- 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.
- 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.
- RRS acts as coordinator and either:
- Asks the resource managers to prepare to commit all updates within the
UR. (Note that resource managers other than the CICS server region may also have expressed
an interest in the UR.) If all vote yes, RRS tells them to go ahead and commit
the changes. If any vote no, all resource managers are told to perform backout.
- Tells all the resource managers that expressed an interest in the UR to
perform backout of all the changes made with 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 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.
- Client issues DPL request omitting SYNCONRETURN.
Because no mirror transaction
is running, a new mirror (mirror 1) is attached.
- The DPL request completes, and because it was issued without the SYNCONRETURN
option, the mirror transaction waits for another request.
- Client issues DPL request with the SYNCONRETURN option.
A new mirror
transaction (mirror 2) is attached.
- On completion of the DPL request, resources updated by the mirror transaction
are committed, and the mirror transaction ends.
- Client issues another DPL request omitting SYNCONRETURN. Mirror 1 receives
and executes the DPL request.
- The DPL request completes, and once again the mirror transaction waits
for another request.
- Client issues DPL request with the SYNCONRETURN option.
A new mirror
transaction (mirror 3) is attached.
- On completion of the DPL request, resources updated by the mirror transaction
are committed, and the mirror transaction ends.
- The client program requests a syncpoint. Resources updated by mirror 1
are committed, and the transaction ends.
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:
- The client program has no way of knowing if updates were committed or
backed out; even if the program ends normally, a resource manager may choose
to backout any changes.
- The run time environment for high level languages may intercept errors
that would otherwise result in an operating system abend. If an error is intercepted
in this way, and the client program does not take any explicit action, the
program may terminate normally and updates committed. Your client program
should be coded to ensure that resources are committed or backed out correctly
in these situations. For example, a PL/I program might include an ON unit
that issues SRRBACK when errors are encountered. A COBOL program might use
the ON phrase on statements that could encounter errors to achieve the same
result.
RRMS comprises
three OS/390 components: registration services, context services, and resource
recovery services (RRS)
A unit of recovery is analogous
to a CICS unit of work
[[ Contents Previous Page | Next Page Index ]]