SET DSNAME

Change information relating to an external data set, including actions that apply to all UOWs that access this data set.

SET DSNAME

Conditions: DSNNOTFOUND, INVREQ, IOERR, NOTAUTH, SUPPRESSED

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

With the SET DSNAME command, you can:

Tell CICS that a data set is no longer required on the local system.
Set the “backup while open” (BWO) attributes of the data set to the ‘forward recovered' state by updating the ICF catalog. This indicates that a forward recovery has taken place.
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 UOW log records that are shunted due to the failures of this data set (other than indoubt failures).
Force any UOWs that are shunted due to indoubt failures, and which have updated this data set, to complete.
Purge shunted UOW log records that hold retained locks (other than those due to 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.

For information about shunted UOW log records, see Units of work.

The options and CVDAs 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, you should not also specify UNAVAILABLE or QUIESCED, because this could cause backout retries to fail.

If you combine UNQUIESCED with any other attributes, also specify BUSY(WAIT), so that later options do not cause the command to fail because the data set is not unquiesced.

Some of the options of a data set cannot be specified until the first file that references the data set has been opened. Where an attribute is not valid until a file has been opened, the INVREQ condition is returned. QUIESCESTATE is an attribute that can be used before any files have been opened against the specified data set.

Options

ACTION(cvda)

specifies the action to be taken on the data set. CVDA values are:

RECOVERED

This data set has been restored from a backup version and forward recovery has been run and completed successfully. CICS attempts to update the BWO attributes of the data set in the ICF catalog using DFSMS™ callable services. The command is used by the database administrator to update the BWO attributes in the ICF catalog if the forward recovery log apply utility does not do so, or if the database administrator finds that there has been no update since the backup copy was made. This would mean that no forward recovery is needed. If the BWO attributes of the data set are not updated after restoring a backup copy, a subsequent file open fails because the data set is still marked as down-level in the ICF catalog.

For information about DFSMS callable services see the RACF Security Administrator's Guide.

REMOVE

A data set is no longer required on the local system. Before you can issue a SET DSNAME REMOVE command, the data set must have a FILECOUNT of zero. If you specify REMOVE, you must not specify any other option.

Removing temporary data sets: If you have an application that creates temporary data sets, it is most important that you remove the associated data set name blocks when the data sets are no longer needed. Data set name blocks are not removed when a data set is closed, or when CICS is shut down (they are removed automatically only during a cold or initial start). If not removed, unwanted data set name blocks can use up excessive amounts of dynamic storage, leading to a short-on-storage condition. See Examples for an illustration of how you can identify and remove unwanted data set name blocks.

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 it should be used 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.

You might choose to 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.

Notes:

This option does not apply to shunted indoubt UOWs. You should 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 FORCE (see the UOWACTION option).
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

Shunted UOW log records, caused by failed backout and commit processing for this data set, should be retried. This is similar in concept to the SET CONNECTION RESYNC command, but applies to backout-failed and commit-failed UOWs only, and not to indoubt UOWs.

You should use RETRY when the data set has shunted backout-failed 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. If the data set was damaged in some way, it must have been repaired (recreated) and made available for RETRY to work successfully.

Messages issued at the time of a data set failure, and which cause UOWs to be shunted, recommend the actions required to recover from the failure.

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

AVAILABILITY(cvda) (VSAM only)

specifies whether the data set is to be marked, in this CICS region, as available or unavailable for use. 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. CVDA values are:

AVAILABLE: The data set is available. CICS can issue both RLS and non-RLS open requests for this data set.
UNAVAILABLE: The data set is unavailable. The data set cannot be opened in either RLS or non-RLS modes.

BUSY(cvda) (RLS only)

specifies whether CICS should wait when requested to quiesce or unquiesce the data set, provided QUIESCESTATE has also been specified. It is ignored if QUIESCESTATE is not specified. CVDA values are:

NOWAIT: CICS returns control to the application immediately, having started the quiesce or unquiesce operation asynchronously. You can use INQUIRE DSNAME QUIESCESTATE to check whether the quiesce or unquiesce has completed.
WAIT: CICS returns control to the application only when the data set has been quiesced or unquiesced throughout the sysplex, or when it has failed to do so. If a quiesce is not completed within the time specified in the QUIESTIM system initialization parameter, the quiesce times out. See QUIESTIM system initialization parameter. If you specify WAIT, or allow it to default, you should ensure that your program handles an AEXY abend in case the DTIMOUT value is not high enough to allow your task to wait for completion.

DSNAME(data-value)

specifies the name of the data set. It can be up to 44 characters long, and is defined to CICS in the DSNAME operand of the CEDA DEFINE FILE command.

QUIESCESTATE(cvda) (RLS only)

specifies the RLS quiesce state of the data set. The state is set in the ICF catalog entry for the data set when the operation has completed. CVDA values are:

IMMQUIESCED: All existing CICS files open in RLS mode throughout the sysplex are closed and the data set is 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 files can open in RLS mode against this data set, but non-RLS open requests are permitted (although opens for update are not possible in non-RLS mode if the data set has retained RLS locks).
In addition to closing open files, IMMQUIESCED sets the file state to UNENABLED if it was ENABLED. A subsequent SET DSNAME UNQUIESCED command restores the file state to ENABLED, provided it was set UNENABLED by a QUIESCED or IMMQUIESCED action, but not if the UNENABLE state is because of some other 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 may terminate abnormally. For this reason, setting a data set as quiesced using the IMMQUIESCED option should be restricted to exceptional circumstances.

QUIESCED

All existing CICS files open in RLS mode throughout the sysplex are closed and the data set is 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:

successfully committed
or successfully backed out
or shunted because of an indoubt failure
or shunted because of a failed backout
or shunted because of a failed commit.

Note: If you specify QUIESCED with WAIT (the default), all tasks in all CICS regions in the sysplex must have reached syncpoint before the files are closed, allowing your command to complete. You must ensure that the DTIMOUT value for the transaction issuing the QUIESCED command is sufficient to allow for this, otherwise the transaction abends with an AEXY abend. The QUIESCE operation is allowed to run until completed or until the timeout value set by the QUIESTIM system initialization parameter, (for which the default is 4 minutes), is reached.

No files can open in RLS mode against this data set, but non-RLS open requests are permitted (although opens for update are not possible in non-RLS mode if the data set has retained RLS locks).

In addition to closing open files, QUIESCED sets the file state to UNENABLED if it was ENABLED. A subsequent SET DSNAME UNQUIESCED command restores the file state to ENABLED, provided it was set UNENABLED by a QUIESCED or IMMQUIESCED action, but not if the UNENABLE state is because of some other event. This state change is recorded in the CICS global catalog.

UNQUIESCED

The data set is marked as unquiesced in the ICF catalog. RLS or non-RLS opens can be issued against this data set, the access mode (RLS or non-RLS) being established by the first open. After the first successful open request, subsequent open requests in the same mode as the first open only are permitted.

If a file has been set UNENABLED by an earlier SET DSNAME IMMQUIESCED or QUIESCED command, UNQUIESCED restores the file state to ENABLED. This state change is recorded in the CICS global catalog.

UOWACTION(cvda)

specifies the action to be taken for shunted indoubt UOWs. CVDA values are:

BACKOUT: All shunted indoubt UOWs that hold locks on this data set should be backed out.
COMMIT: All shunted indoubt UOWs that hold locks on this data set should be committed.
FORCE: All shunted indoubt UOWs that hold locks on this data set should be FORCED to back out or commit, as specified by the ACTION attribute defined on the transaction resource definition.

Conditions

DSNNOTFOUND

RESP2 values:

1: The named data set cannot be found.
15: RECOVERED was specified, but the data set was not found.

INVREQ

RESP2 values:

3

ACTION has an invalid CVDA value.

10

REMOVE was specified, but the data set is associated with a file definition.

12

REMOVE was specified with another option. If you specify REMOVE, it must be the only option present on the command.

13

REMOVE was specified but a lock was held on the data set by another INQUIRE or SET DSNAME command, or by CICS file control processing.

14

RECOVERED was specified but CICS is not configured to support “backup while open” (BWO). Check that you have a version of MVS/DFP™, DFHSM, and DFDSS that supports BWO.

16

RECOVERED was specified but the data set has not been opened during this CICS session, so the BWO attributes in the ICF catalog cannot be set.

17

RECOVERED was specified for a BDAM data set, or a VSAM path. This is not supported.

18

RECOVERED was specified for a VSAM base data set that has FCTs open. This is not allowed.

19

RECOVERED was specified for an unknown data set, or the data set was not in the ‘forward recovered' state.

29

QUIESCESTATE is specified, but the operation is not supported because RLS=NO is specified as a system initialization parameter, or because DFSMS 1.3 or later is not installed.

30

QUIESCESTATE has an invalid CVDA value.

31

BUSY has an invalid CVDA value.

33

AVAILABILITY has an invalid CVDA value.

34

A QUIESCESTATE value of QUIESCED or IMMQUIESCED is specified, but is rejected by SMSVSAM either because a quiesce or unquiesce is already taking place, or because DFSMSdss is currently taking a backup copy of the data set.

36

A QUIESCESTATE value of UNQUIESCED is specified, but is rejected by SMSVSAM either because an unquiesce is already taking place, or because DFSMSdss™ is currently taking a backup copy of the data set.

39

AVAILABILITY, QUIESCESTATE, RESETLOCKS, or RETRY is specified for a data set that is a BDAM data set.

40

The CICS control block (DSNB) describing the data set has been deleted (by the REMOVE option) by another task before CICS could process this SET command.

41

QUIESCESTATE is specified for a data set that is not known to DFSMS as a VSAM data set.

42

An invalid CVDA is specified for UOWACTION.

43

A QUIESCESTATE value of QUIESCED or IMMQUIESCED is specified without NOWAIT, and the issuing task has updated the data set, or is browsing the data set, in the same unit of work. This is not allowed because:

For QUIESCED, this would result in a deadlock.
For IMMQUIESCED, this would result in the issuing task being purged.

44

A SET DSNAME REMOVE command has been issued by another task. This has been detected after this SET DSNAME command was issued, but before the AVAILABILITY option is processed.

46

BKOUTSTATUS is specified with a value other than NORMALBKOUT (BKOUTSTATUS is obsolete).

47

No file has been opened against the data set since the last cold start of this CICS region, or since the first file definition was installed for the data set.

IOERR

RESP2 values:

20: RECOVERED was specified but an error was raised on accessing the ICF catalog. Ensure that the specified data set is on an SMS-managed DASD and is known to the SMS subsystem.
21: RECOVERED was specified but an error was raised by the CICS table manager program.
35: QUIESCESTATE is specified but the SMSVSAM server is not available.
40: QUIESCESTATE is specified, and an unexpected error occurred in DFSMS.
48: The specified operation cannot be completed because the data set is migrated. Recall the data set and reissue the command.
49: An error was raised by DFSMS when reading the ICF Catalog to establish the base data set name.

NOTAUTH

RESP2 values:

100: The user associated with the issuing task is not authorized to use this command.

SUPPRESSED

RESP2 values:

37

A QUIESCESTATE value of QUIESCED or IMMQUIESCED is specified, but the quiesce of the data set is canceled by another participating CICS region. This could be for one of the following reasons:

A user issued a SET DSNAME UNQUIESCED command.
An XFCVSDS global user exit program suppressed the quiesce.
An XFCSREQ global user exit program suppressed the close of a file that is open against the data set.

38

A QUIESCESTATE value of QUIESCED or IMMQUIESCED is specified, but the quiesce of the data set is canceled by this CICS region because the quiesce operation timed out. This is probably because of a long-running transaction on another participating CICS region preventing the close of a file that is open against the data set.

Another reason for the timeout could be that one or more regions are very busy. If this occurs too frequently, you can modify the timeout period (from the default of 240 seconds) by specifying a longer period using the QUIESTIM system initialization parameter.

Examples

It is possible in CICS to create VSAM data sets online for temporary use, and which are dynamically allocated by CICS file control. Typically, this involves reusing the same file control entry and setting the new temporary data set name each time you need to use a new data set. This practice can lead to a large number of data set name blocks occupying CICS dynamic storage. These can only be removed by a SET DSNAME(…) REMOVE command, or by a cold or initial start of CICS.

Ideally, an application that creates and uses a temporary data set should explicitly delete the DSN block when it no longer needs the data set. This involves two actions:

Breaking the association between the CICS file and the data set by issuing an EXEC CICS SET FILE(…) CLOSED DISABLED command, followed by an EXEC CICS SET FILE command to set the DSNAME operand to a null value.
Removing the data set name block by issuing an EXEC CICS SET DSNAME(…) REMOVE command.

To set the DSNAME to null you must code the CICS commands as shown in the following examples to ensure they translate and compile correctly.

Assembler example

*        Remove DSN block from CICS storage
*
*ASM XOPTS(SP)
DFHEISTG DSECT
TEMPDSN  DS    CL44
REMOVE   CSECT
         PRINT GEN
*          Find name of temporary data set if not known
         EXEC CICS INQUIRE FILE('TEMPFILE') DSNAME(TEMPDSN)
*          Close file temporary file and set DSN to null
         EXEC CICS SET FILE('TEMPFILE') CLOSED DISABLED
         EXEC CICS SET FILE('TEMPFILE') DSNAME(=X'00')
*          Remove DSN block from storage
         EXEC CICS SET DSNAME(TEMPDSN) REMOVE
*
*         Return and end
*
RETURN   DS    0H
         EXEC CICS RETURN
         END

PL/I example

*PROCESS XOPTS(SP);
 REMOVE:PROC OPTIONS(MAIN);
 DCL PLIXOPT STATIC EXTERNAL CHAR(10) VAR INIT('NOSTAE');
 DCL TEMPDSN CHAR(44);
/*                                                       */
/*         Find name of temporary data set if not known  */
         EXEC CICS INQUIRE FILE('TEMPFILE') DSNAME(TEMPDSN);
*/         Close file temporary file and set DSN to null */
         EXEC CICS SET FILE('TEMPFILE') CLOSED DISABLED;
         EXEC CICS SET FILE('TEMPFILE') DSNAME('00'X);
/*         Remove DSN block from storage                 */
         EXEC CICS SET DSNAME(TEMPDSN) REMOVE
/*
/*           Return and end                              */
/*
         EXEC CICS RETURN;
         END;

COBOL example

 CBL XOPTS(SP)
       IDENTIFICATION DIVISION.
       PROGRAM-ID. REMOVE.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       77  TEMPDSN             PIC X(44).
       PROCEDURE DIVISION.
      *   Find name of temporary data set if not known
           EXEC CICS INQUIRE FILE('TEMPFILE') DSNAME(TEMPDSN)
                END-EXEC.
      *   Close file temporary file and set DSN to null
           EXEC CICS SET FILE('TEMPFILE') CLOSED DISABLED
                END-EXEC.
           EXEC CICS SET FILE('TEMPFILE') DSNAME(LOW-VALUES)
                END-EXEC.
      *   Remove DSN block from storage
           EXEC CICS SET DSNAME(TEMPDSN) REMOVE END-EXEC.
      *
      *   Return and end
           EXEC CICS RETURN END-EXEC.
           GOBACK.