CEMT SET DSNAME

Change the status of an external data set.

Description

You can use the SET DSNAME command to change the status of a VSAM base data set. You can use the command to perform the following actions on a data set:
  • Mark a VSAM data set as quiesced, or unquiesced, throughout the sysplex.
  • Make a VSAM data set available or unavailable to a CICS® region. (The availability function does not operate across the sysplex—a SET DSNAME(…) AVAILABILITY command is effective only within the CICS region in which it is issued.)
  • Retry all unit of work (UOW) log records that are shunted because of the failures of this data set (other than indoubt failures).
  • Force any UOWs that are shunted because of indoubt failures, and which have updated this data set, to complete.
  • Purge shunted UOW log records that hold retained locks (other than those because of indoubt failures) for any records in the data set, and release the retained locks.
  • Cancel any attempt to recover lost RLS locks for the data set using the UOWACTION and ACTION(RESETLOCKS) options.

The SET DSNAME command does not distinguish between data sets accessed in RLS and non-RLS mode.

The new options for the SET DSNAME command are subject to the following rules relating to the order of processing and the combinations of keywords and multiple keywords on the same command:
  • If REMOVE is specified, no other attribute is allowed.
  • Options are processed in the following order:
    1. RECOVERED
    2. UNQUIESCED
    3. AVAILABLE
    4. RETRY
    5. UOWACTION
    6. RESETLOCKS
    7. UNAVAILABLE
    8. QUIESCED

If you specify RETRY, do not also specify UNAVAILABLE or QUIESCED, because this would cause backout retries to fail. UNQUIESCE should not be specified with other attributes, because the other options might fail.

Some attributes of a data set cannot be set until the first file that references the data set is opened. Where an attribute is not valid until a file is opened, an error is returned. QUIESCESTATE is an attribute that can be set before any files are opened against the specified data set.

Syntax

Press the Clear key to clear the screen. You can start this transaction in two ways:
  • Type CEMT SET DSNAME (or suitable abbreviations for the keywords), followed by either a value that corresponds to a data set name, or ALL. The resulting display lists the current status, similar to that obtained by using the CEMT INQUIRE DSNAME command. You can tab to the highlighted or blank fields and overtype them with the required values.
  • Type CEMT SET DSNAME (or suitable abbreviations for the keywords), followed by a value that corresponds to a data set name or ALL, then followed by one or more attributes that you want to change. For example, cemt s dsn(applb.*) q quiesces all data sets with a high-level qualifier of APPLB in all CICS regions within the sysplex.
Resetting the values takes effect immediately.

CEMT SET DSNAME

Read syntax diagramSkip visual syntax diagramCEMT SET DSNAME( value)ALLREMOVERECOVEREDRESETLOCKSRETRYAVAILABLEUNAVAILABLEQUIESCEDUNQUIESCEDIMMQUIESCEDBACKOUTCOMMITFORCE

Options

(value)
Specifies one or more names (1 - 44 characters) of an external data set.
ALL
Any change you request is made to all resources of the specified type that you are authorized to access.
AVAILABLE
Specifies whether the data set is marked in this CICS region as available for use. This command sets the availability indicator, which is a local flag that a CICS region maintains in a data set name block (DSNB) for each data set. CICS can issue either RLS or non-RLS open requests for this data set.
BACKOUT
Specifies that all shunted indoubt UOWs that hold locks on this data set are backed out.
COMMIT
Specifies that all shunted indoubt UOWs that hold locks on this data set are committed.
FORCE
Specifies that all shunted indoubt UOWs that hold locks on this data set are forced to back out or commit, as specified by the ACTION attribute on the transaction resource definition.
IMMQUIESCED
Causes all existing CICS open RLS-mode files throughout the sysplex to close and the data set to be marked as quiesced in the ICF catalog. Each CICS in the sysplex abends all in-flight UOWs that are accessing the data set before closing files, causing in-flight UOWs to back out. Any UOWs that fail backout are shunted. No RLS-mode files can open against this data set, but non-RLS-mode open requests are permitted.

IMMQUIESCED also sets the file state to UNENABLED if it was ENABLED. A subsequent SET DSNAME UNQUIESCED command restores the file state to ENABLED, if it was set UNENABLED by a QUIESCED or IMMQUIESCED action, but not if the UNENABLED state is because of another event. This state change is recorded in the CICS global catalog.

Note: Using the IMMQUIESCED option causes any tasks currently using the data set to be terminated immediately, using the CICS task FORCEPURGE mechanism. In some extreme cases CICS might terminate abnormally. For this reason, setting a data set as quiesced using the IMMQUIESCED option should be restricted to exceptional circumstances.
QUIESCED
Causes all existing CICS files open in RLS mode throughout the sysplex to close and the data set to be marked as quiesced in the ICF catalog. Each CICS in the sysplex waits until all in-flight UOWs that are accessing the data set have reached syncpoint before closing the files. That is, the UOWs are in one of the following states:
  • Successfully committed
  • Successfully backed out
  • Shunted because they failed indoubt
  • Shunted because they failed commit
  • Shunted because they failed backout

No files can open in RLS mode against this data set, but non-RLS open requests are permitted.

QUIESCED also sets the file state to UNENABLED if it was ENABLED. A subsequent SET DSNAME UNQUIESCED command restores the file state to ENABLED, if it was set UNENABLED by a QUIESCED or IMMQUIESCED action, but not if the UNENABLED state is because of another event. This state change is recorded in the CICS global catalog.

RECOVERED
The data set has been restored from a backup version and forward recovery has run and completed successfully. CICS normally updates the backup-while-open (BWO) attributes for the base cluster data set BASEDSNAME, using MVS/DFP 3.2 Callable Services.

If the BWO attributes are not updated after the restore of a backup copy of a data set that was taken using BWO, CICS fails a subsequent file open because the data set is marked as down-level.

REMOVE
This option is used when a data set is no longer required on the local system. It deletes the data set name block for the named data set. The REMOVE option can be used only when there are no file control resource definition entries that refer to the specified data set. If any file definitions refer to the data set name when you enter SET DSNAME REMOVE, you receive an error message indicating that the use count of the data set name block is not zero. To ensure that no file definitions refer to the data set name:
  • Close all files that refer to the data set. These files can be found using the command: 
      CEMT INQUIRE FILE(*) DSNAME(dsname)
  • Either remove the data set name from each file entry (by over-typing the data set name with blanks on the CEMT display), or discard the file definition entirely.
If you have a base data set with one or more alternate indexes, you cannot remove the data set name block for the base until you have removed all references to the base data set and all references to paths.
RESETLOCKS (VSAM only)
Purges shunted UOW log records for backout-failed and commit-failed UOWs that hold locks on this data set, and releases the retained locks:
  • Backout-failed UOWs are those that failed during backout processing.
  • Commit-failed UOWs are those that have updated RLS data sets, and have failed to release locks during the second phase of 2-phase commit syncpoint processing.

If you specify this option, you are accepting backout failure and some loss of data integrity rather than retaining locks and delaying transactions, and therefore use it only as a last resort.

For backout-failed and commit-failed UOWs that hold locks on the data set, all records relating to this data set are removed from the system log and all retained record locks held by this CICS for the data set are released. Diagnostic messages are written to the CSFL transient data queue for each backout-failed log record that is removed as a result of the RESETLOCKS operation.

RESETLOCKS applies only to shunted UOW log records that are classed as backout-failed and commit-failed. Therefore it cannot be issued for a BDAM data set. Backout-failed and commit-failed log records are not shunted for BDAM data sets.

You might use RESETLOCKS if backout-failed or commit-failed log records are holding up lost locks recovery for the data set, and there is no other way of resolving them.
Note:
  1. This option does not apply to shunted indoubt UOWs. Try to resolve the shunted indoubt UOWs that hold locks on the data set in other ways before issuing RESETLOCKS; for example, by using COMMIT, BACKOUT, or FORCEUOW.
  2. RESETLOCKS can fail during the commit phase (for example, if an error occurs while CICS is trying to release the RLS locks), in which case the UOWs revert to being shunted as commit-failed UOWs.
RETRY
Specifies that shunted UOW log records, caused by failed backout and commit processing as a result of the failure of this data set, are retried. This is similar in operation to the EXEC CICS RESYNC command, but applies to backout-failed and commit-failed UOWs only, and not to indoubt UOWs.

Use RETRY when the data set has shunted backout- or commit-failed UOWs associated with it, and you believe that some or all of the data set problems are either transient or have been resolved.

Messages that are issued at the time of a data set failure that causes UOWs to be shunted recommend the actions that are required to recover from the failure.

RETRY does not affect data integrity, and can be used safely at any time to enable some failed recovery work to complete.

UNAVAILABLE
Marks the data set as unavailable, and prevents the data set being opened in either RLS or non-RLS modes. This command sets or unsets the availability indicator, which is a local flag that a CICS region maintains in a data set name block (DSNB) for each data set.
UNQUIESCED
Causes the data set to be marked as unquiesced in the ICF catalog. RLS or non-RLS mode files can be opened against this data set, the access mode (RLS or non-RLS) being established by the first open.

If a file has been set UNENABLED by a SET DSNAME IMMQUIESCED or QUIESCED command, UNQUIESCED sets it back to ENABLED, provided that there have been no other explicit changes to the enablement state in the meantime. This state change is recorded in the CICS global catalog.