Optional Parameters

LISTDS(base-cluster)

Lists the following information:

The assigned coupling facility cache structure name
The subsystem type and status:
- Active for batch
- Active or failed for online
Whether the VSAM sphere is recoverable or nonrecoverable
The state of the data set:
- Forward recovery required
- Retained locks
- Lost locks
- Locks unbound
- Non-RLS update permitted
- Permit-first-time switch
- Optionally, a list of the jobs accessing the data set using DFSMStvs.

Abbreviation: LDS

JOBS

When this keyword is specified, LISTDS returns a list of the jobs currently accessing the data set in DFSMStvs mode.

LISTSHUNTED {SPHERE(base-cluster) | URID}(urid|ALL) }}

Lists information about work that was shunted due to an inability to complete a syncpoint (commit or backout) for a given data set or unit of recovery, or for all shunted units of recovery when the ALL keyword is specified. The output includes the following information:

The unit of recovery identifier
The data set name
The job with which the unit of recovery was associated
The step within the job with which the unit of recovery was associated
Whether the unit of recovery will be committed or backed out if it is retried

Shunting is caused by errors such as the following:

C-FAILED: A commit failed.
B-FAILED: A backout failed.
IO-ERROR: An I/O error occurred on the data set.
DS-FULL: The data set was full; no space on DASD to add records.
IX-FULL: A larger alternate index is required.
LOCK: A failure occurred during an attempt to obtain a lock during backout.
LOG: A log stream became or was made unavailable.
CACHE: A cache structure or connection to it failed.

This parameter requires that you have UPDATE authority to the data set specified.

Abbreviation: LSH

LISTSUBSYS(subsystem|ALL)

Lists information about a specific subsystem or all subsystems known to the SMSVSAM server:

Subsystem status
- Active for batch
- Active or failed for online
A summary showing whether the subsystem's shared data sets have:
- Lost locks
- Retained locks
- Non-RLS update permitted

For an active subsystem, LISTSUBSYS gives the number of held locks, waiting lock requests, and retained locks. For a failed subsystem, LISTSUBSYS shows the number of retained locks.

Abbreviation: LSS

LISTSUBSYSDS(subsystem|ALL)

Lists information about a specific subsystem or all subsystems known to the SMSVSAM server, including data sets that it is sharing. For each subsystem, this parameter lists the following information:

Sharing protocol (online or batch)
The status (active or failed)
Recovery information for each shared data set:
- Whether it has retained locks owned by this subsystem
- Whether it has lost locks owned by this subsystem
- Whether there are locks not bound to the data set
- If forward recovery is required
- If non-RLS update is permitted
- The permit-first-time switch setting

Abbreviation: LSSDSL

LISTRECOVERY(base-cluster)

lists data sets requiring recovery and the subsystems that share those data sets. Recovery indicators listed are:

Lost locks
Retained locks
Non-RLS update permitted
Forward recovery required

Abbreviation: LRCVY

LISTALL

Lists all information related to recovery for subsystems and VSAM spheres accessed in RLS mode. The output from this parameter can be quite large.

Abbreviation: LALL

FRSETRR(base-cluster)

This parameter sets the forward-recovery-required indicator. Until reset with the FRRESETRR parameter, access is prevented until forward recovery is complete.

If you use a forward recovery utility such as CICSVR that supports RLS, DFSMStvs, or both, do not use this parameter.

Abbreviation: SETRR

FRUNBIND(base-cluster)

This parameter unbinds the retained locks prior to restoring or moving the data set. These locks protect uncommitted changes and are needed for eventual backout. They must be rebound by using the FRBIND parameter.

If you use a forward recovery utility such as CICSVR that supports RLS, DFSMStvs, or both, do not use this parameter.

Abbreviation: UNB

FRBIND(base-cluster)

Use this parameter after BLDINDEX to rebind the associated locks to the restored data set.

Attention: Between the unbind and the bind, do not delete any clusters in the sphere or change their names.

If you use a forward recovery utility such as CICSVR that supports RLS, DFSMStvs, or both, do not use this parameter.

Abbreviation: BIND

FRRESETRR(base-cluster)

Use this parameter after forward recovery is complete and after locks have been bound to the new location of the data set using FRBIND. This allows access to the newly recovered data set by applications other than the forward recovery application.

If you use a forward recovery utility such as CICSVR that supports RLS, DFSMStvs, or both, do not use this parameter.

Abbreviation: RESET

FRDELETEUNBOUNDLOCKS(base-cluster)

The FRDELETEUNBOUNDLOCKS parameter lets you delete locks in the rare case when a successful forward recovery is not possible. Every attempt should be made to complete forward recovery, whether using a product such as CICSVR that supports VSAM RLS or using another forward recovery procedure.

If forward recovery does not successfully complete, locks cannot be reassociated (bound) to the new version of the data set, because these locks do not provide the protection that online backout requires.

Before using this parameter, check the documentation for your online application.

Abbreviation: DUNBL

PERMITNONRLSUPDATE(base-cluster)

Allows a data set with pending RLS recovery to be opened for output in non-RLS mode. This command is used when it is necessary to run critical batch updates and RLS recovery cannot first be completed. This is reset the next time the data set is accessed for RLS. If after using PERMITNONRLSUPDATE, you do not run a non-RLS batch job, you must use DENYNONRLSUPDATE to prevent non-RLS updates.

Abbreviation: PERMT

DENYNONRLSUPDATE(base-cluster)

If you inadvertently issue PERMITNONRLSUPDATE, use this parameter to reset the effect of PERMITNONRLSUPDATE.

If recovery was pending, but you did not run a non-RLS batch job, you must use this parameter. If not reset, CICS® takes action assuming the data set has been opened for update in non-RLS mode.

Do not use DENYNONRLSUPDATE if you do indeed run non-RLS work after specifying PERMITNONRLSUPDATE. The permit status is reset the next time the data set is opened in RLS mode.

Abbreviation: DENY

REMOVESUBSYS(subsystem)

Use this parameter to remove any knowledge of recovery owed to SMSVSAM by the named subsystem, including locks protecting uncommitted updates.

Normally, a failed online application would be restarted so that it can do the required backouts and release locks protecting uncommitted updates. However, sometimes it might be necessary to cold start the online application.

Use of this parameter is equivalent to cold starting the named subsystem with respect to the SMSVSAM server. Use REMOVESUBSYS for the rare cases where either there is no intention of ever running the subsystem again or the application's cold start procedures cannot be used. An example of an appropriate use of REMOVESUBSYS would be removing a test system that is no longer needed.

If the removed subsystem is ever run again, every effort should be made to cold start the subsystem.

Attention: Use of REMOVESUBSYS can result in loss of data integrity.

Abbreviation: RSS

CFREPAIR({INFILE(ddname)|INDATASET(dsname)}

Use this command to reconstruct the RLS indicators for all applicable data sets in a restored catalog. The catalog must be import-connected on all systems to the master catalog before the CFREPAIR parameter can be used.

INFILE(ddname): Indicates which DD statement defines the catalog to be processed.
INDATASET(dsname): Use this to specify the name of the catalog to be processed.

({LIST|NOLIST})

Optional subparameters, which control the information returned by the CFREPAIR parameter.

LIST: Requests a list of data sets for which CFREPAIR successfully restored the RLS information. If you do not specify this subparameter, CFREPAIR lists only those data sets whose RLS information could not be restored.
NOLIST: Only data sets whose information could not be restored are listed. Using this subparameter is the same as not specifying LIST or NOLIST.

Abbreviation: CFREP

CFREPAIRDS({base_cluster_name|partially_qualified_cluster_name})

Use this command to reconstruct the RLS indicators for all applicable data sets requested after restoring a catalog.

Note: Be sure to identify all data sets used as RLS data sets. Otherwise, data may be lost.

base_cluster_name: Specifies the name of the data set to be processed.
partially_qualified_cluster_name: A list of data sets will be generated using the partially qualified data set name. A partially qualified data set name is specified by appending an asterisk to a partial data set name. CFREPAIRDS lists all data sets processed, not just those with errors.

Abbreviation: None.

CFRESET({INFILE(ddname)|INDATASET(dsname)}

Use this parameter if you've decided to fall back from using VSAM RLS. The CFRESET parameter clears VSAM RLS indicators in the catalog for all applicable data sets. A detailed fallback procedure is included in the z/OS DFSMSdfp Storage Administration. See the z/OS DFSMSdfp Storage Administration for information specific to CICS.

If the catalog is later restored, use CFREPAIR to reconstruct critical information required by the SMSVSAM server.

INFILE(ddname): Specifies the data definition (DD) name of the catalog to be processed.
INDATASET(dsname): Specifies the data set name of the catalog to be processed.

({LIST|NOLIST})

Optional subparameters, which control the information returned by the CFRESET parameter.

LIST: Requests a list of data sets for which CFRESET successfully processed the RLS indicators. If you do not specify this subparameter, CFRESET lists only those data sets whose indicators were not cleared.
NOLIST: Only data sets that were not successfully processed are listed. Using this subparameter is the same as not specifying LIST or NOLIST.

Abbreviation: CFRES

CFRESETDS({base_cluster_name|partially_qualified_cluster_name})

Use this parameter if you've decided to fall back from using VSAM RLS. It clears VSAM RLS indicators in the catalog for all applicable data sets. CFRESETDS This parameter differs from CFRESET in that it lets you select one or more data sets for fallback.

base_cluster_name: Specifies the name of the data set to be processed.
partially_qualified_cluster_name: A list of data sets will be generated using the partially qualified data set name. A partially qualified data set name is specified by appending an asterisk to a partial data set name. CFRESETDS lists all data sets processed, not just those with errors.

A detailed fallback procedure is included in the z/OS DFSMSdfp Storage Administration.

Abbreviation: CFRDS

CFQUIRSDS({base_cluster_name | partially_qualified_cluster_name})

Use this parameter to turn off the RLS Quiesced indicator in the catalog for all applicable data sets.

After a data set is quiesced in RLS, the Quiesced indicator in the catalog will be set to indicate the data set is in a quiesced state. RLS access is prevented from the data set until this indicator is reset. This command provides the capability to directly turn off this indicator in the catalog without going through the unquiesce process.

base_cluster_name: Specifies the name of the data set to be processed.
partially_qualified_cluster_name: A list of data sets will be generated using the partially qualified data set name. A partially qualified data set name is specified by appending an asterisk to a partial data set name. CFRESETDS lists all data sets processed, not just those with errors.

Note that RACF® ALTER access is required for any data sets accessed by this command. Access to STGADMIN FACILITY CLASS STGADMIN.IGWSHCDS.REPAIR is not required.

Abbreviation:. CFQDS

OUTFILE(ddname)

Specifies a data set, other than the SYSPRINT data set, to receive the output produced by the SHCDS command.

ddname identifies the DD statement of the alternate target data set.

Abbreviation: OUTDD

PURGE {SPHERE(base-cluster)|URID(urid)}

Discards the log entries and releases the associated locks. Use this command when the data set is damaged and cannot be restored to a state where it is consistent with the log entries. For example, it might have been necessary to restore the data set from a backup copy that predates the updates that were made to the data set prior to the failure.

Recommendation: If any data sets are in a lost locks status, do not issue this command while a DFSMStvs restart is in progress. If any lost locks recovery was not completed for a data set that is being processed by this command, the command does not complete until the DFSMStvs restart completes.

This parameter requires that you have update authority for the specified data set.

Abbreviation: none

RETRY {SPHERE(base-cluster)|URID(urid)}

Retries the syncpoint. Use this command when the data set can be restored to a state where it is consistent with the log entries. By consistent, we mean that the data set reflects the state that existed before the time of the particular unit of recovery for which DFSMStvs was unable to complete processing. This is possible for data sets that are forward recoverable or for failures that do not damage the data set (such as a dropped path). When the command completes successfully, locks associated with the log entries are released.

This parameter requires that you have update authority for the specified data set.

Abbreviation: none