Quiescing RLS data sets

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:

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

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:

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:

  1. Resolve shunted UOWs that are holding retained locks
  2. Quiesce the data set
  3. Run the batch update job
  4. 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.

The CICS RLS quiesce support

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:
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.

Figure 16. The CICS RLS quiesce operation with the CICS quiesce exit program
 This diagram illustrates the process described in the notes that follow. It shows 2 MVS images connected through one coupling facility, and using the same VSAM integrated catalog facility (ICF) catalog. CICS AOR1 is shown running in MVS1, and CICS AOR2 is running in MVS2, and each AOR is connected to the SMSVSAM server in its MVS image.In the note list that follows, steps 1, 2, and 3 are executed in AOR1; steps 4, 5, and 6 are executed in both AORs; steps 4a by both SMSVSAM servers; steps 7 and 8 are performed by the SMSVSAM server in MVS1 only.

Notes:
  1. 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).

  2. CICS file control (AOR1 in the diagram) invokes CFQS to send the quiesce request to SMSVSAM.
  3. The long-running CICS (AOR1) CFQS task passes the quiesce request to SMSVSAM across the control ACB interface using the IDAQUIES macro QUICLOSE function.
  4. 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.

  5. The CICS RLS quiesce exit program schedules a CICS region task (CFQR) to perform asynchronously the required quiesce actions in that CICS region.
  6. 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.
  7. 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.
  8. 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:

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 ]]