Data sets opened by CICS® in RLS mode can also be accessed by batch programs,
provided the batch programs open them in RLS mode for read-only processing.
Batch programs cannot update recoverable data sets in RLS mode, because SMSVSAM
prevents it. Thus, to update a recoverable data set from a batch program,
first ensure that the data set is closed to all CICS regions. This allows the batch program
to open the data set in non-RLS mode for update. (See Switching from RLS to non-RLS access mode.)
To enable batch programs to access data sets opened in RLS mode, CICS supports the
VSAM RLS data set quiesce and unquiesce functions.
The quiesce function enables you, with a single command, to close in an
orderly manner throughout the sysplex any data sets that are open in RLS mode,
and prevent the data sets being opened in RLS mode while they are in the quiesced
state. This function is required in the data sharing environment because many CICS regions can have the same data set open for update at the same time.
You can use the quiesce function to take a data set offline throughout the
sysplex when:
- You want to switch between RLS and non-RLS VSAM access modes.
- You want to prevent data set access during forward recovery.
CICS supports the VSAM RLS quiesce interface by providing an RLS quiesce exit program that is driven for the quiesce and
unquiesce functions. CICS regions initiating quiesce and unquiesce requests
propagate these to other CICS regions, through the SMSVSAM control ACB and the CICS RLS quiesce exit program.
Other products such as DFSMSdss and CICSVR also communicate with CICS through their SMSVSAM control ACBs and the RLS quiesce exit.
The RLS quiesce and unquiesce functions are initiated by a CICS command in
one region, and propagated by the VSAM RLS quiesce interface to other CICS regions in the sysplex.
When these functions are complete, the ICF catalog shows the quiesce state
of the target data set. The state of the quiesce flag in the ICF catalog controls
whether a data set can be opened in RLS mode:
- When a quiesce operation has been completed throughout the sysplex, SMSVSAM
sets the quiesced flag to prevent applications (either CICS or batch) from
opening the data set in RLS mode.
You can open a quiesced data set in non-RLS
mode only.
- When an unquiesce operation has been completed, SMSVSAM clears the quiesced
flag to permit the data set to be opened in RLS mode.
You can open an unquiesced
data set in either RLS or non-RLS mode, the mode for the entire sysplex being
determined by the first ACB opened.
Normally, a data set cannot be opened for update in non-RLS access mode
if SMSVSAM is holding retained locks against the data set. Thus, to enable
a non-RLS batch program to update a recoverable data set that CICS regions have
open in RLS mode, take the following steps:
- Resolve shunted UOWs that are holding retained locks
- Quiesce the data set
- Run the batch update job
- Unquiesce the data set
CICS transactions that try to access a quiesced data in RLS-mode fail
with a NOTOPEN condition. Non-RLS accesses are permitted subject to the data
set’s VSAM SHAREOPTIONS.
For more information, see Switching from RLS to non-RLS access mode.
To support the quiesce and unquiesce functions provided by the VSAM RLS
quiesce interface, CICS provides a VSAM RLS quiesce exit program. The following general
information gives an overview of the CICS support for the quiesce and unquiesce
functions, and of the CICS RLS quiesce exit program:
- Enabling the quiesce exit
- CICS passes the address of its RLS quiesce exit program when it registers with the
SMSVSAM control ACB during CICS initialization. This ensures that the
CICS-supplied RLS quiesce exit program is enabled for use from the start of CICS until CICS shutdown.
CICS can pass the address of a private copy of the exit program if it is
loaded in the CICS address space, or the address of a shared copy if
its RLS quiesce exit program is LPA-resident. Note that the RLS quiesce exit program
is supplied and enabled by CICS, and is not one that requires any action
from you.
- Communicating requests
- Communication between CICS and SMSVSAM takes place either directly
through the SMSVSAM control ACB or through the quiesce exit.
For example,
a CICS region passes quiesce and unquiesce requests over the VSAM control
ACB interface using the VSAM IDAQUIES macro. A CICS region receives notification of quiesce
and unquiesce requests in which it is required to participate through the RLS quiesce exit (see Figure 16).
- Starting the CICS quiesce long-running tasks
- There are 2 new CICS-supplied transactions, CFQS and CFQR, which are
started during CICS initialization as long-running tasks. These are the "send" and "receive" transactions for handling quiesce and unquiesce
requests.
- Scheduling quiesce and unquiesce processing
- When a CICS region receives notification of a quiesce or unquiesce request,
the CICS RLS quiesce exit program schedules a CICS region task (CFQR) to perform asynchronously
any work associated with the quiesce or unquiesce function.
- Issuing a quiesce request
- This is initiated in a CICS region (by CFQS) in response to a CEMT,
or EXEC CICS, SET DSNAME(...) command to quiesce the specified data set.
SMSVSAM propagates the request across the sysplex to all CICS regions that
have open RLS ACBs by invoking each CICS region’s RLS quiesce exit program, which uses
CFQR to schedule any necessary work. All regions receiving the request are
required to close and all files open against the specified data set, and set
them to the UNENABLED state.
For a normal quiesce, UOWs accessing
the data set are allowed to complete normally (or be shunted), whereupon all
files open against the specified data set are closed and set to the UNENABLED
state.
For an immediate quiesce, UOWs accessing
the data set are force-purged and all files open against the specified data
set are closed and set UNENABLED.
See the description of the QUIESCESTATE
option on the CEMT, or EXEC CICS, SET DSNAME command for information about
the effect of a quiesce request on in-flight tasks.
When SMSVSAM receives
replies (see "Completion notification") from all the CICS regions to
which the quiesce request was sent, it sets the ICF catalog quiesced indicator.
This prevents any RLS opens against the data set until the data set is unquiesced.
Note:
If enabled, the CICS XFCVSDS exit is invoked for this function,
with the UEPVSACT parameter set to a value of UEQUIES.
If enabled, the CICS XFCQUIS exit is also invoked for this function, with the UEPQSTAT parameter
set to a value of UEQSD or UEIMQSD, for a normal or an immediate quiesce respectively.
- Issuing an unquiesce request
- This is initiated in a CICS region (by CFQS) in response to a CEMT,
or EXEC CICS, SET DSNAME(...) command to unquiesce the specified data set.
SMSVSAM updates the ICF catalog to indicate that the data set is unquiesced,
and then propagates the request, through the CICS RLS quiesce exit program, to all CICS regions that are registered with an SMSVSAM control ACB. As soon
as they receive the notification, CICS regions re-enable the data set, making
it eligible to be reopened in RLS mode, and re-try any backout-failed shunted UOWs for
that data set. (See also "Completion notification".)
Note:
If enabled, the CICS XFCVSDS exit is invoked for this function, with the
UEPVSACT parameter set to a value of UEUNQUIS.
If enabled, the CICS XFCQUIS exit
is also invoked for this function, with the UEPQSTAT parameter set to a value
of UEUNQSD.
- Notifying completion
- The required completion notification for the quiesce function and the
unquiesce function is as follows:
- Quiesce: SMSVSAM does not change the ICF catalog state
until it receives notification from all CICS regions with open RLS ACBs that they
have completed their quiesce processing. For this purpose, CICS issues a quiesce completed code (using an IDAQUIES macro QUICMP function)
when it has finished its required processing for a data set quiesce operation.
SMSVSAM then issues a normal response to the initiating CICS region to signify
that the operation is complete.
- Unquiesce: SMSVSAM changes the ICF catalog state immediately
on receipt of an unquiesce request from a CICS region. SMSVSAM then notifies all CICS regions that are registered with an SMSVSAM control ACB, through the CICS RLS quiesce exit program, that the data set is unquiesced. In this case, the CICS RLS quiesce exit issues a quiesce completed code to SMSVSAM immediately, with any
associated unquiesce processing taking place asynchronously.
SMSVSAM then
issues a normal response to the initiating CICS region to signify that the operation
is complete.
- Canceling a quiesce request
- If SMSVSAM receives an unquiesce request before an in-progress quiesce
request completes, it has the effect of canceling the quiesce request.
- Timing out a quiesce
- If the CICS region initiating a quiesce request does not receive a normal response
from SMSVSAM within the specified quiesce time-out limit, CICS issues an unquiesce
request to cancel the quiesce operation. You specify the quiesce time-out
limit on the QUIESTIM system initialization parameter, for which the default value is 240 seconds.
Illustration of the quiesce flow across two CICS regions
Figure 16 illustrates the operation of the CICS RLS quiesce
operation. The notes that follow explain the numbered points.
Notes:
- A suitably-authorized user application program (AOR1 in the diagram) issues
an EXEC CICS SET DSNAME(...) QUIESCED command (or a terminal operator issues
the equivalent CEMT command).
If the command specifies the BUSY(NOWAIT)
option, all phases of the quiesce operation are asynchronous, and the user
application program continues processing.
If the command specifies BUSY(WAIT),
control is not returned to the user application program until SMSVSAM replies
to CFQS that the quiesce function has completed (or failed).
- CICS file control (AOR1 in the diagram) invokes CFQS to send the quiesce
request to SMSVSAM.
- The long-running CICS (AOR1) CFQS task passes the quiesce request to SMSVSAM
across the control ACB interface using the IDAQUIES macro QUICLOSE function.
- SMSVSAM drives the CICS RLS quiesce exit program of each CICS region that has an open RLS ACB for the
specified data set (as shown in both AOR1 and AOR2 in the diagram).
Note:
This also applies to the CICS region in which a quiesce request is
initiated if it has open RLS ACBs for the data set. Thus an initiator can
also be a recipient of a quiesce request.
(4a) SMSVSAM
uses the coupling facility to propagate the request to the other SMSVSAM servers
in the sysplex.
- The CICS RLS quiesce exit program schedules a CICS region task (CFQR) to perform asynchronously
the required quiesce actions in that CICS region.
- When CICS has closed all open RLS ACBs for the data set, CICS issues the "quiesce completed" notification (the IDAQUIES macro QUICMP function) direct
to SMSVSAM through the control ACB interface.
- When all CICS regions have replied with the IDAQUIES macro QUICMP function, the
SMSVSAM server that handled the original request (from AOR1 in the diagram)
sets the quiesced flag in the ICF catalog. This prevents any files being opened
in RLS mode for the data set, but allows non-RLS open requests that are initiated,
either implicitly or explicitly, by user transactions.
- SMSVSAM returns to the CICS region that initiated the quiesce request.
If the BUSY(WAIT) option was specified on the request, CFQS resumes the waiting
application program.
The flow of an unquiesce request is virtually the same as that illustrated
in Figure 16, with the following differences in operation:
- As soon as SMSVSAM receives the unquiesce request from the initiating CICS region, it immediately sets the quiesce flag in the ICF catalog to the
unquiesce state.
- SMSVSAM invokes the RLS quiesce exit program of each CICS region registered with a control ACB
to notify it of the change in the quiesce state.
- The CICS RLS quiesce exit program returns a "quiesce completed" code to SMSVSAM
immediately, and then passes the request to CFQR for processing.
Other quiesce interface functions
In addition to quiesce and unquiesce, there are some other data-set-related
functions using the RLS quiesce interface that are not connected with quiescing
or unquiescing activity on a data set. These are functions initiated by DFSMSdss, CICSVR, or VSAM RLS, and may require some processing in those CICS regions that are registered with SMSVSAM. These functions do not cause
any change in the ICF catalog quiesced flag.
The other functions provided on the RLS quiesce interface for data-set-related
activities are as follows:
- Non-BWO data set backup start
- A quiesce interface function initiated by DFSMSdss in readiness for non-BWO backup processing
for a data set that is open in RLS mode. This function prevents CICS file control
issuing RLS update requests against a sphere so that the VSAM sphere can be
backed up.
SMSVSAM invokes the CICS RLS quiesce exit program in each region that has
an open RLS ACB for the data set.
If any in-flight UOWs are using
the data set when a QUICOPY notification is received, CICS allows them
to complete (or be shunted). CICS then flags its data set name block (DSNB)
for the data set to disable further updates. Any UOW that attempts to update
the data set thereafter is abended with an AFCK abend, and SMSVSAM prevents
any new file opens for update.
Note:
If enabled, the CICS XFCVSDS exit
is invoked for this function, with the UEPVSACT parameter set to a value of
UENBWST.
With the new RLS quiesce mechanism, you do not
have to close a data set to take a non-BWO backup. However, because this causes
new transactions to be abended, you may prefer to quiesce your data sets before
taking a non-BWO backup.
- Non-BWO data set backup end
- A quiesce interface function initiated by DFSMSdss at the end of non-BWO backup processing
(or to cancel a non-BWO backup request). This function enables CICS file control
to permit RLS update requests against the data set now that backup processing
is complete.
SMSVSAM invokes the CICS RLS quiesce exit program in each region that is
registered with an SMSVSAM control ACB.
In addition to permitting updates, CICS writes tie-up log records to the forward recovery log and the log of
logs, and retries any shunted UOWs for the data set.
Note:
If enabled, the CICS XFCVSDS exit is invoked for this function, with the
UEPVSACT parameter set to a value of UENBWCMP.
- BWO backup start
- A quiesce interface function initiated by DFSMSdss in readiness for BWO backup processing
for a data set that is open in RLS mode. This function enables CICS to ensure the
data set is in a suitable state for a BWO backup to be taken.
SMSVSAM invokes
the CICS RLS quiesce exit program in each region that has an open RLS ACB for the data
set.
In response to this form of request, CICS writes tie-up records to the forward
recovery log and log of logs, and waits for any in-flight UOWs to complete
(or be shunted). New units of work can then update the data set.
Note:
If enabled, the CICS XFCVSDS exit is invoked for this function, with the
UEPVSACT parameter set to a value of UEBWOST.
- BWO backup end
- A quiesce interface function initiated by DFSMSdss at the end of BWO backup processing
(or to cancel a BWO backup request). It notifies CICS that a BWO backup of a data set is complete.
SMSVSAM invokes the CICS RLS quiesce exit program in each region that is registered with
an SMSVSAM control ACB.
CICS does not perform any processing for this
form of request.
Note:
If enabled, the CICS XFCVSDS exit
is invoked for this function, with the UEPVSACT parameter set to a value of
UEBWOCMP.
- Forward recovery complete
- A quiesce interface function initiated by VSAM in response to a request
from CICSVR. VSAM takes action associated with a sphere having completed forward
recovery, which includes notifying CICS.
SMSVSAM invokes the CICS RLS quiesce exit program
in each region that is registered with an SMSVSAM control ACB.
CICS retries any backout-failed shunted UOWs for the data set.
- Lost locks recovery complete
- A quiesce interface function initiated by VSAM. VSAM takes action associated
with a sphere having completed lost locks recovery on all CICS regions that
were sharing the data set.
SMSVSAM invokes the CICS RLS quiesce exit program in each region that is
registered with an SMSVSAM control ACB.
Until lost locks recovery is
complete, CICS disallows any new requests to the data set (that is, only requests
issued as part of the recovery processing are possible). When lost locks recovery
is complete, CICS allows all requests to the data set.
- Quiesce coupling facility cache available
- A quiesce interface function initiated by VSAM. VSAM takes action associated
with an MVS™ coupling facility cache structure being restored.
SMSVSAM invokes
the CICS RLS quiesce exit program in each region that is registered with an SMSVSAM
control ACB.
CICS retries any backout-failed shunted UOWs for all
data sets.
[[ Contents Previous Page | Next Page Index ]]