Change information relating to an external data set, including actions that apply to all UOWs that access this dataset.
SET DSNAME >>-SET DSNAME(data-value)--+--------------+---------------------> +-ACTION(cvda)-+ +-REMOVE-------+ +-RECOVERED----+ +-RESETLOCKS---+ '-RETRY--------' >--+--------------------+--+-------------------+----------------> +-AVAILABILITY(cvda)-+ +-QUESCESTATE(cvda)-+ +-AVAILABLE----------+ +-QUIESCED----------+ '-UNAVAILABLE--------' +-IMMQUIESCED-------+ '-UNQUIESCED--------' .-WAIT-------. >--+------------+--+-----------------+------------------------->< +-BUSY(cvda)-+ +-UOWACTION(cvda)-+ '-NOWAIT-----' +-BACKOUT---------+ +-COMMIT----------+ '-FORCE-----------'
Conditions: DSNNOTFOUND, INVREQ, IOERR, NOTAUTH, SUPPRESSED
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
With the SET DSNAME command, you can:
For information about shunted UOW log records, see the CICS® Recovery and Restart Guide.
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 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, you should 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. Note that QUIESCESTATE is an attribute that can be used before any files have been opened against the specified data set.
For information about DFSMS callable services see z/OS V1R4.0 Security Server RACF Security Administrator’s Guide.
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.
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.
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.
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.
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.
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.
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.
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:
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.