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:
- RECOVERED
- UNQUIESCED
- AVAILABLE
- RETRY
- UOWACTION
- RESETLOCKS
- UNAVAILABLE
- 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
>>-CEMT SET DSNAME--+-(value)-+--+------------+----------------->
'-ALL-----' +-REMOVE-----+
+-RECOVERED--+
+-RESETLOCKS-+
'-RETRY------'
>--+-------------+--+-------------+--+---------+---------------><
+-AVAILABLE---+ +-QUIESCED----+ +-BACKOUT-+
'-UNAVAILABLE-' +-UNQUIESCED--+ +-COMMIT--+
'-IMMQUIESCED-' '-FORCE---'
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:
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: - 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.
- 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.