The main reason why you might need to switch a data set from RLS access mode to non-RLS access mode is to run a batch update program that cannot be changed to run as a CICS® transaction.
Non-RLS access mode is a generic term embracing NSR, LSR, and GSR access modes. It is likely that your existing batch programs open VSAM data sets in NSR access mode, although it is also possible for batch programs to use LSR or GSR.
As a general rule, you are recommended not to switch between RLS and non-RLS within CICS. After a data set is accessed in RLS mode by CICS, it should always be accessed in RLS mode by CICS. The following topic describes an exception to this general rule for read-only operations.
There is an exception to the general rule about not switching between RLS and non-RLS within CICS. You can switch to non-RLS access on a data set that is normally opened in RLS mode provided access is restricted to read-only operations. You might want to do this, for example, to allow continued access for read-only transactions while the data set is being updated by a batch job. CICS and VSAM permit quiesced data sets to be opened in non-RLS mode, but you must ensure that CICS transactions do not update a data set that is being updated concurrently by a batch program.
The recommended procedure for providing CICS read access to a recoverable data set while it is being updated by a batch job is:
You should also take data set copies for recovery purposes before and after a batch run as you would normally, regardless of whether you are switching from RLS to non-RLS access mode.
You cannot open a data set in non-RLS access mode if there are any ACBs open against it in RLS access mode. To switch from RLS to non-RLS access mode, first ensure that all files that are open against the data set are closed. You can use the quiesce function for this purpose. As discussed in Quiescing RLS data sets, the VSAM RLS quiesce mechanism causes each CICS region in the sysplex to close any RLS ACBs that are open against a specified data set. Once closed under the quiesce mechanism, data sets can only be opened in non-RLS mode. To re-enable quiesced data sets to be reopened in RLS mode, all open non-RLS ACBs must be closed and then the data sets must be unquiesced.
The quiesce mechanism cannot inform batch programs that have the data set open in RLS access mode about the quiesce request. If you have such programs, use the access method services SHCDS LIST subcommand to check whether any non-CICS jobs have ACBs open in RLS mode against the data set. For information about the SHCDS LIST subcommand, see DFSMS/MVS Access Method Services for ICF.
Quiescing a data set sets the quiesce flag in the ICF catalog so that the data set can be opened in non-RLS mode only. This way of making data sets available for batch programs without having to shut down all the CICS regions is particularly suited to the Parallel Sysplex® environment. Note that if you do shut CICS regions down, it is best to avoid immediate shutdowns when you have not specified a shutdown transaction, because this could cause large numbers of locks to be retained. A shutdown transaction can enable you to perform a quick but controlled shutdown.
Even if a data set has been quiesced, you still cannot open it for update in non-RLS access mode if SMSVSAM is holding retained locks against the data set. This is because the locks are needed to preserve data integrity: they protect changes that are waiting to be either committed or backed out. It is possible to open a data set for input (read-only) in non-RLS mode even when there are retained locks, because a reader cannot corrupt the data integrity that such locks are preserving. Note that, when you are opening a data set in a batch job, there cannot be any active locks because, when an ACB is closed, any active locks are converted automatically into retained locks.
The remainder of this topic on switching to non-RLS access mode describes the options that are available if you need to switch to non-RLS mode and are prevented from doing so by retained locks.
VSAM sets an ‘RLS-in-use’ indicator in the ICF catalog cluster entry when a data set is successfully opened in RLS mode. This indicator remains set, even when a data set opened in RLS mode is closed by all CICS regions, to show that the data set was last accessed in RLS mode. The indicator is cleared only when a data set is successfully opened in non-RLS mode. However, if SMSVSAM also holds retained locks against a data set, a non-RLS open fails and the RLS-in-use indicator remains set. In this event, try to resolve retained locks before attempting to use a data set in non-RLS mode for batch processing.
The procedure described here lists the steps you can take to switch from RLS to non-RLS mode in readiness for batch processing. The procedure is for a single data set, and should be repeated for each data set that is to be accessed from batch in non-RLS mode. CICS provides a suite of sample programs designed to help you to automate most of this procedure, which you can tailor to suit your own requirements (see The batch-enabling sample programs):
CICS does not know exactly which locks are held by VSAM RLS. However, it does know about the uncommitted changes that are protected by such locks, and why the changes have not yet been committed successfully. CICS uses this information to help you resolve any retained locks that are preventing you from switching to non-RLS access mode.
You can use the INQUIRE DSNAME command to find out whether the data set has any retained locks or if it is waiting for lost locks recovery by any CICS region (see A special case: lost locks).
INQUIRE DSNAME(...) RETLOCKS returns a value of RETAINED if the CICS region has any shunted UOWs that have made uncommitted changes to the named data set, and NORETAINED if it does not. (RETLOCKS may return the value NORETAINED whilst changes are being made or units of work are being retried.) You can use this command to find out whether or not there are any retained locks that you need to resolve before running batch.
The INQUIRE DSNAME(...) LOSTLOCKS command returns:
CEMT INQUIRE UOWDSNFAIL DSN(datasetname) can return information about shunted UOWs that have failed to commit changes to the named data set. The information includes the resource that caused the failure and, where there can be more than one reason, the reason for the failure. The EXEC CICS INQUIRE UOWDSNFAIL command provides a browse interface, allowing an application program to browse through all the shunted UOWs for a data set or a group of data sets.
There are three main categories of failure:
Backout failures can be retried after the cause of the failure has been corrected. In some cases, the retry occurs automatically.
Commit failures can be retried after the cause of the failure has been corrected. The retry usually occurs automatically.
Note that INQUIRE UOWDSNFAIL displays information about UOWs that are currently failed with respect to one or more data sets. The command does not display information for a unit of work that was in backout-failed or commit-failed state and is being retried, or for a unit of work that was in-doubt and is being completed. The retry, or the completion of the in-doubt unit of work, could fail, in which case a subsequent INQUIRE UOWDSNFAIL displays the relevant information.
A CICS region that has been accessing a data set may not be running at the time you want to inquire on unit of work failures in readiness for a batch job. Instead of bringing up such a CICS region just to issue INQUIRE UOWDSNFAIL commands, you can use the SHCDS LISTDS, LISTSUBSYS, or LISTSUBSYSDS commands. These commands enable you to find out which CICS regions (if any) hold retained locks, and to obtain other information about the status of your data sets with regard to each CICS region. You then know which regions you need to start in order to resolve the locks. These commands are described in DFSMS/MVS Access Method Services for ICF.
The SHCDS LIST commands could also be useful in the unlikely event of a mismatch between the information that CICS holds about uncommitted changes, and the information that the VSAM RLS share control data set holds about retained locks.
Unless prevented by time constraints, you are recommended to resolve retained locks by using the INQUIRE UOWDSNFAIL command and retrying shunted UOWs. (See the INQUIRE UOWDSNFAIL for information about the actions that should be taken to allow each shunted unit of work to complete.) For example, for a unit of work that has been shunted with a CAUSE of DATASET and a REASON of DELEXITERROR, enable a suitable global user exit program at the XFCLDEL (logical delete) global user exit point and then issue a SET DSNAME ACTION(RETRY) command to retry the backout and drive the global user exit. For a unit of work that has been shunted with a CAUSE of CONNECTION, use the SYSID and NETNAME returned by INQUIRE UOWDSNFAIL to find out what has caused the in-doubt condition and correct the failure, after which automatic resynchronization should allow the unit of work to complete, either by being backed out or by committing the changes.
There may be times when you cannot resolve all the retained locks correctly, either because you cannot easily remedy the situations preventing the changes from being committed, or because of insufficient time. In such a situation, you can still release the locks, using the SET DSNAME command, although in most cases you will lose some data integrity.
SET DSNAME UOWACTION(COMMIT, BACKOUT, or FORCE) operates on shunted in-doubt UOWs. It causes any in-doubt UOWs that have made changes to the data set (these will appear on an INQUIRE UOWDSNFAIL command with a CAUSE of CONNECTION) to complete in one of the following ways:
When the unit of work completes, the locks are released. If the action chosen is backout (either by explicitly specifying BACKOUT or as a result of the FORCE option), diagnostic information is written to the CSFL transient data queue. Therefore BACKOUT is normally the best option, because you can use the diagnostic information to correct the data if backout was the wrong decision. Diagnostic messages DFHFC3004 and DFHFC3010 are issued for each backed-out update. Choose COMMIT for the UOWs only if you know this is the decision that would be communicated by the coordinator when resynchronization takes place following reconnection.
The SET DSNAME(datasetname) ACTION(RESETLOCKS) command operates on UOWs that are shunted for reasons other than in-doubt failure. CICS resets the locks for the named data set; that is, it:
Diagnostic messages DFHFC3003 and DFHFC3010 are issued for each log record.
If a data set has both indoubt-failed and other (backout- or commit-) failed UOWs, deal with the indoubt UOWs first, using SET DSNAME UOWACTION, because this might result in other failures which can then be cleared by the SET DSNAME RESETLOCKS command.
CICS provides a suite of sample programs to help you automate batch preparation procedures. The three coordinating programs, which use CICS distributed program link (DPL) commands to run programs on a set of nominated CICS regions, are:
The DFH0BAT3 sample program is also useful for resolving pending backouts after a failure to forward recover a data set. See Procedure for failed RLS mode forward recovery operation.
For more information about these batch-enabling sample programs see the CICS Operations and Utilities Guide, which describes how to install the programs and how to prepare the required input for them. See also the comments contained in the source code supplied in the CICSTS31.CICS.SDFHSAMP library.
The following is a series of CEMT command examples showing how you can use CEMT to resolve unit of work failures in preparation for batch processing.
CEMT INQUIRE UOWDSNFAIL DSN('RLS.ACCOUNTS.ESDS.DBASE1')
STATUS: RESULTS
Dsn(RLS.ACCOUNTS.ESDS.DBASE1 ) Dat Del
Uow(AA6DB080C40CEE01) Rls
Dsn(RLS.ACCOUNTS.ESDS.DBASE1 ) Dat Ind
Uow(AA6DB08AC66B4000) Rls
The display shows a REASON code of DELEXITERROR (Del) for one unit of work, and INDEXRECFULL (Ind) for the other.
SET DSNAME('RLS.ACCOUNTS.ESDS.DBASE1') RETRY
STATUS: RESULTS - OVERTYPE TO MODIFY
Dsn(RLS.ACCOUNTS.ESDS.DBASE1 ) Vsa NORMAL
Fil(0001) Val Bas Rec Sta Ava Ret
INQUIRE UOWDSNFAIL
STATUS: RESULTS
Dsn(RLS.ACCOUNTS.ESDS.DBASE1 ) Dat Ind
Uow(AA6DB08AC66B4000) Dat Ind Rls
This type of error can occur when adding a value to a non-unique alternate index while trying to back out a change to a record; after the original update was made, other UOWs have added values to the alternate index, filling all the available space. Such an error should be extremely rare. The solution is to define a larger alternate index record size for the data set.
Dsname(RLS.ACCOUNTS.ESDS.DBASE1)
Accessmethod(Vsam)
Action( )
Filecount(0001)
Validity(Valid)
Object(Base)
Recovstatus(Recoverable)
Backuptype(Static)
Frlog()
Availability( Available )
Lostlocks()
Retlocks(Noretained)
Quiescestate()
Uowaction( )
Basedsname(RLS.ACCOUNTS.ESDS.DBASE1)
Fwdrecovlsn(RLS.ACCOUNTS.FWDRECOV.LOG)
DFHFC3003 01/04/95 12:08:03 CICSHDA1 Record not backed out because locks for
a backout-failed data set have been reset.
Diagnostic information follows in message DFHFC3010. The record was
updated by unit of work X'AA6DB08AC66B4000' for file ACCNT1 , base
data set RLS.ACCOUNTS.ESDS.DBASE1
DFHFC3010 01/04/95 12:08:03 CICSHDA1 Diagnostic information for unit of work
X'AA6DB08AC66B4000' and file ACCNT1 .
Update was a write-add made by transaction WKLY at terminal T583
under task number 00027. Key length 4, data length 7, base ESDS
RBA X'00000DDF', record key X'00000DDF'
If a lost locks condition occurs (see Lost locks recovery), any affected data set remains in a lost locks state until all CICS regions have completed lost locks recovery for the data set.
Lost locks recovery is complete when all uncommitted changes, which were protected by the locks that were lost, have been committed. Therefore, after a lost locks condition occurs, you may need to follow the same procedures as those for preparing for batch jobs (described in The batch-enabling sample programs), to ensure that the data set is made available again as soon as possible. Preserving data integrity should be the priority, but you may decide to force in-doubt UOWs and to reset locks in order to make the data set available sooner.
There may be situations in which it is difficult or inconvenient to use CICS commands to remove all the retained locks held against a data set. For these situations, DFSMS access method services provides a SHCDS subcommand that allows you to run a non-RLS batch program despite the fact that there are retained locks.
The SHCDS PERMITNONRLSUPDATE subcommand allows you to run a non-RLS batch job where it is not possible to resolve all the retained locks that are held against the data set. This subcommand overrides the DFSMS controls that prevent non-RLS opens-for-update when a data set still has retained locks. Use this option only as a last resort.
The effect of the PERMITNONRLSUPDATE command is canceled as soon as the data set is re-opened in RLS mode after the batch work is complete. Re-issue the command when you next want to override retained locks.
The SHCDS DENYNONRLSUPDATE subcommand allows you to reset the permit status of a data set to prevent non-RLS updates. This subcommand is provided for the situation where you issue the PERMITNONRLSUPDATE subcommand in error, and wish to turn the permit status off again without running any non-RLS work:
After a non-RLS program has been permitted to override retained locks, the uncommitted changes that were protected by those locks must not normally be allowed to back out. This is because the non-RLS program may have changed the protected records. To ensure this, all CICS regions that held retained locks are notified by VSAM that a non-RLS update may have occurred because of the PERMITNONRLSUPDATE override. The CICS regions receive this notification when they open the affected data set in RLS mode.
CICS stores information about any uncommitted changes that are currently outstanding, and then informs VSAM RLS that the PERMITNONRLSUPDATE state can be cleared with respect to this CICS region. CICS uses the stored information to prevent automatic backouts during retries, because this could cause unpredictable results if backouts were applied to data modified by a batch program. Whenever a change made by one of these UOWs is about to be backed out, CICS detects its special status and invokes the XFCBOVER global user exit program. This allows you to determine what action to take over the uncommitted changes. The default action for these UOWs is not to retry the backouts.
Diagnostic information is provided to help you to correct the data if necessary. Diagnostic messages DFHFC3001 and DFHFC3010 are issued for each affected update. CICS uses an internal form of the SET DSNAME RETRY command to drive any pending backout failures immediately. In the case of in-doubt failures, CICS has to wait for the indoubt to be resolved following resynchronization before knowing whether the changes were to have been backed out.
Note that neither CICS nor VSAM knows whether the non-RLS program did change any of the locked records, only that it had the potential to do so. With your knowledge of the batch application, you may know that the records, or certain of the records, could not have been changed by batch and could therefore be safely backed out. For example, the batch application might only ever add records to the data set. CICS provides a global user exit point, XFCBOVER, which allows you to request that records are backed out, and which you can also use to perform other actions. If you choose to back out an update, CICS issues diagnostic message DFHFC3002 instead of DFHFC3001.
The SHCDS LISTDS subcommand shows whether the non-RLS batch update PERMITNONRLSUPDATE state is currently set. It also shows the status of a PERMIT first-time switch, which is a switch that is cleared as soon as a data set for which non-RLS update has been allowed is next opened for RLS access. The non-RLS permitted state is used to inform each contributing CICS region that a non-RLS program has potentially overridden its retained locks. The first-time switch is used to ensure that a subsequent non-RLS open for update requires a new PERMITNONRLSUPDATE to be issued even if some permitted states have not yet been cleared.
[[ Contents Previous Page | Next Page Index ]]