SET FILE
Change attributes of a VSAM or BDAM file, including files that refer to CICS® shared data tables and coupling facility data tables.
Conditions: FILENOTFOUND, INVREQ, IOERR, NOTAUTH
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
Any combination of the options can be set on one command. For all changes, other than to close and disable the file, the file must be in a CLOSED state, with an ENABLESTATUS of either DISABLED or UNENABLED. Changes do not take effect until the file is next opened. If the file is not closed immediately, then attributes that require the file to be in a CLOSED state, with an ENABLESTATUS of either DISABLED or UNENABLED, will be ignored.
You can use the SET FILE command to set combinations of attributes that are relevant to more than one file type, to simplify switching between different types of file. Attributes that are not relevant to the current type of file are ignored. So you can set up dual-purpose file definitions, for example, by defining both local and remote attributes, or set attributes that make it easy to switch the file from accessing a user-maintained data table in a single MVS™ image to accessing a coupling facility data table in a parallel sysplex.
If a coupling facility data table exists, and the table attributes specified on the SET FILE command do not match those with which it was created, an attempt to open the file fails with an error message.
If you use the SET FILE command to switch the file from referencing a coupling facility data table to a different object (for example from CFTABLE to NOTTABLE), the CFDT is not deleted and remains in its pool (the coupling facility list structure).
The requested changes are applied in the following order: NOEMPTYREQ, CLOSED, DISABLED, miscellaneous, OPEN, ENABLED.
Description
Use the SET FILE command to change some of the attributes of a named VSAM or BDAM file. A security check is made and an unauthorized command attempt is given a NOTAUTH response. If any retained locks are associated with the file, the only attributes that you can change are the ENABLESTATUS and the OPENSTATUS. If you try to specify any other attribute when there are retained locks, an INVREQ condition is issued.
- CICS bundles that were deployed on their own or with a platform can be updated individually.
- If the CICS bundle was deployed as part of an application or with an application binding, update the whole application.
To change the status of a FILE resource that was defined and installed in a CICS bundle, change the status of the CICS bundle or the application with which it is deployed. When you perform the disable action on a CICS bundle that defines a FILE resource, the action completes when the file is no longer in use and any retained locks have been resolved.
If you are experiencing a problem with disabling a CICS bundle that defines a FILE resource, you may issue the EXEC CICS SET FILE DISABLED or EXEC CICS SET FILE CLOSED command with the FORCE option against the dynamically generated resource, if this action is required. Follow the troubleshooting procedure in Diagnosing application errors to diagnose the problem and take suitable action.
Options
- ADD(cvda)
- Specifies whether new records can be added to the file. CVDA values
are as follows:
- ADDABLE
- New records can be added to the file.
- NOTADDABLE
- New records cannot be added to the file.
- BROWSE(cvda)
- Specifies whether the file can be browsed. CVDA values are as
follows:
- BROWSABLE
- The file can be browsed.
- NOTBROWSABLE
- The file cannot be browsed.
- BUSY(cvda)
- Specifies the CICS action
if the file is in use when you issue the SET command. The BUSY option
is valid only for requests to set the file to DISABLED or CLOSED,
and is ignored for any other request. CVDA values are as follows:
- FORCE
- All tasks using the file abend, the file is immediately set to DISABLED or CLOSED, and control returns to the issuing application.
- NOWAIT
- The same as WAIT, except that CICS returns control to the issuing application as soon as the SET request has been queued.
- WAIT
- CICS waits until all activity on the file has quiesced before setting the file to DISABLED or CLOSED. CICS then returns control to the application that is issuing this command. WAIT is the default.
Closing a file using the FORCE option causes tasks of any current users of the file to be stopped immediately by the CICS task FORCEPURGE mechanism. Data integrity is not guaranteed with this mechanism. In some extreme cases (for example, if an error occurs during backout processing), CICS might end abnormally. For this reason, close files using the FORCE option only in exceptional circumstances.
- CFDTPOOL(data-value) (CFDT only)
- Specifies the name of the pool that contains the coupling facility data table. You can specify the CFDT pool name for a file that does not currently refer to a coupling facility data table, but which might be switched to use a coupling facility data table at a later date.
- DELETE(cvda) (VSAM only)
- Specifies whether records can be deleted from the file. CVDA values
are as follows:
- DELETABLE
- Records can be deleted from the file.
- NOTDELETABLE
- Records cannot be deleted from the file.
- DISPOSITION(cvda)
- Specifies the disposition for this file. When you issue a SET
FILE DISPOSITION command, you override the current DISPOSITION value,
which can have been taken from the installed file definition, or from
any JCL statement for this file, if the file has been opened. CVDA
values are as follows:
- OLD
- The disposition value is OLD.
- SHARE
- The disposition value is SHARE.
- DSNAME(data-value)
Specifies the data set name of the data set associated with this file, as defined to the access method and the operating system. The name can be up to 44 characters long. If you set a value of blanks, CICS does not change the value of this option.
- EMPTY
- Is equivalent to EXEC CICS SET FILE EMPTYSTATUS(EMPTYREQ). It is supported for compatibility reasons only, but not for files operating in RLS mode.
- EMPTYSTATUS(cvda) (VSAM only)
- Specifies whether the data set is to be emptied when a file that
refers to it is next opened. This option is valid only for data sets
that are defined as reusable, and that are accessed in either LSR
or NSR mode. CVDA values are:
- EMPTYREQ
- If the data set is defined as reusable, it is set to empty the
next time a file that references it is opened in non-RLS mode. Notes:
- If you specify EMPTYREQ for a nonreusable data set, CICS accepts it, but a subsequent attempt to open the file fails.
- If you specify EMPTYREQ for a file defined with RLSACESS(YES), CICS accepts it, but the option does not have any effect unless the file is subsequently opened in non-RLS mode.
- If you specify EMPTYREQ for a file that refers to a coupling facility data table that requires preloading from a data set and is specified with RLSACCESS(NO), and opening the file triggers the table load, the data set is set to empty.
- If you specify EMPTYREQ for a file that refers to a coupling facility data table that does not require loading from a source data set, the option is ignored.
- If you specify EMPTYREQ for a file that refers to a coupling facility data table that is already loaded from a source data set, the option is ignored.
- NOEMPTYREQ
- The data set has been defined as reusable but is not set empty the next time a file that references it is opened. Specify NOEMPTYREQ for a coupling facility data table.
- ENABLESTATUS(cvda)
- Specifies whether application programs can access the file. CVDA
values are as follows:
- DISABLED
- The file is unavailable for access by application programs.
- ENABLED
- The file is available for access by application programs.
- EXCLUSIVE(cvda) (BDAM only)
- Specifies whether records on this file are placed under exclusive
control when a read for update is issued. CVDA values are as follows:
- EXCTL
- Records on this file are under exclusive control.
- NOEXCTL
- Records on this file are not under exclusive control.
- FILE(data-value)
- Specifies the 8-character file name as defined to CICS.
- KEYLENGTH(data-value) (CFDT only)
- Specifies, as a fullword binary value, the key length of records
in a coupling facility data table. To set a key length, specify a
value in the range 1 - 16. To clear a key length (set it to null values),
specify KEYLENGTH(0).
You can specify the key length for a file that does not currently refer to a coupling facility data table, but which could be switched to use a coupling facility data table at a later date.
- LOADTYPE(data-value) (CFDT only)
- Specifies whether the coupling facility data table associated
with the file requires pre loading from a source data set. CVDA values
are as follows:
- LOAD
- The coupling facility data table requires loading from a source data set before it is fully usable; the transactions that use this coupling facility data table rely on it containing the records from the specified source data set.
- NOLOAD
- The coupling facility data table does not require loading from a source data set; it is fully usable as soon as it is created, and is populated by the transactions that use it.
You can specify the load type for a file that does not currently refer to a coupling facility data table, but which might be switched to use a coupling facility data table later.
- LSRPOOLID(data-value) (VSAM only)
- This attribute is obsolete, but is supported to provide compatibility
with earlier releases of CICS.
A value specified for LSRPOOLID is transferred to the new option LSRPOOLNUM.
- LSRPOOLNUM(data-value) (VSAM only)
- Specifies, as a fullword binary value, the number of the LSR pool
associated with this file. LSR pool IDs are in the range 1 through
255.
If the file cannot share buffers, set this value to 0.
For a CICS-maintained or user-maintained data table, the value must be 1 or greater. Both these types of CICS shared data tables must use LSR access mode (unless the file is defined to be opened in RLS access mode).
For a coupling facility data table, you can set this value to 0.
- MAXNUMRECS(data-value)
- Specifies, as a fullword binary value, the maximum number of records
that the data table for this file can hold. Use this parameter to
control the use of storage.
For any type of table, if you want to set a limit, specify a value in the range 1 - 99999999. If you do not want any limit to apply, specify MAXNUMRECS(0), which CICS interprets as no limit, and sets internally to the maximum positive fullword value (+2147483647 or X'7FFFFFFF').
To specify MAXNUMRECS for a recoverable coupling facility data table, use a value that is 5 - 10% more than the maximum number of records that the table is expected to contain. This value allows for additional records that might be created internally for processing recoverable requests. The margin to be left for this internal processing depends on the level of use of the coupling facility data table, and the nature of that use. An effect of this is that the NOSPACE condition (with a RESP2 value of 102) can be raised on a WRITE or REWRITE request to a recoverable coupling facility data table that has fewer records than the MAXNUMRECS limit specifies.
- OPENSTATUS(cvda)
- Specifies whether the file is open or closed. CVDA values are
as follows:
- CLOSED
- The file is to be closed.
The close request is deferred until all units of work that hold repeatable read locks reach their sync points.
If the file is not closed immediately, then other attributes that require the file to be in a CLOSED state, with an ENABLESTATUS of either DISABLED or UNENABLED, will be ignored.
A coupling facility data table remains in existence (in the coupling facility) after the file is closed, unlike a user-maintained data table, which ceases to exist when the file in the file-owning region is closed. Closing a file for a coupling facility data table does not prevent it being accessed through another file or by other CICS regions.
You can use the MVS MODIFY command to issue CFDT server commands:- To set the table unavailable (MODIFY server-name,SET TABLE=tablename,AVAILABLE=NO) so that no other files can issue opens against it
- To delete the table from the coupling facility (MODIFY server-name,DELETE TABLE=table-name) if you do not want it to exist after the last file using it has been closed.
- OPEN
- The file is opened.
For a coupling facility data table, open processing causes the coupling facility data table server to create the table if it does not exist when CICS processes the open request. If the installed file definition specifies the name of a source data set, the coupling facility data table is created by loading the data from the source data set.
If a SET FILE(filename) OPEN command refers to a file that specifies LOAD(YES), but which does not name the source data set, the CFDT can be created and loaded only by opening a file that defines the source data set name.
If a recoverable data set is closed, the task issuing the close must commit any prior changes to that data set; otherwise, the request is rejected by file control.
- READ(cvda)
- Specifies whether records can be read from the file. CVDA values
are as follows:
- NOTREADABLE
- Records are not readable from the file.
- READABLE
- Records are readable from the file.
- READINTEG(cvda)
- Specifies the default level of read integrity for the file. CVDA
values are as follows:
- CONSISTENT
- Consistent read integrity is required for this file.
- REPEATABLE
- Repeatable read integrity is required for this file.
- UNCOMMITTED
- No read integrity is required for this file.
These default read integrity values are used only when the file read request does not specify read integrity options explicitly on the EXEC CICS command.
CICS ignores a READINTEG option specified for a coupling facility data table.
- RECORDSIZE(data-area) (CFDT only)
- Specifies, as a fullword binary value, the maximum record size
for a coupling facility data table in the range 1 - 32767.
You can specify the record size for a file that does not currently refer to a coupling facility data table, but which might be switched to use a coupling facility data table later. Specify a record size of zero to remove a previously defined value.
- RLSACCESS(cvda)
- Specifies whether the file is to be accessed in RLS mode. The
file must be closed, and either disabled or unenabled, to change the
access mode to RLS access or to non-RLS access.
The non-RLS mode becomes either LSR or NSR, depending on the value specified for LSRPOOLNUM in the file resource definition.
CVDA values are as follows:- NOTRLS
- The file is opened in LSR or NSR mode when it is next opened.
- RLS
- The file is opened in RLS access mode when it is next opened.
See Switching from RLS to non-RLS access mode for information about switching between RLS and non-RLS modes.
- STRINGS(data-value) (VSAM only)
- Specifies, as a fullword binary value, the maximum number of concurrent operations to allow on this file, in the range 1 - 255.
- TABLE(cvda) (VSAM and CFDT only)
- Specifies whether the file name specified on the FILE parameter
represents a data table. CVDA values are as follows:
- CFTABLE
- The file name refers to a coupling facility data table.
- CICSTABLE
- The file name represents a CICS-maintained data table.
- NOTTABLE
- The file name does not represent a data table.
- USERTABLE
- The file name represents a user-maintained data table.
- TABLENAME(data-area) (CFDT only)
- Specifies the 1- to 8-character name of the coupling facility
data table to which this file refers. If TABLENAME is not specified,
the table name defaults to the name of the file.
You can specify the table name for a file that does not currently refer to a coupling facility data table, but which might be switched to use a coupling facility data table later.
- UPDATE(cvda)
- Specifies whether the file is read-only or read/write. CVDA values
are as follows:
- NOTUPDATABLE
- You can only read the records.
- UPDATABLE
- You can read, write, or delete the records.
- UPDATEMODEL(cvda) (CFDT only)
- Specifies the type of update coupling facility data table used
for a coupling facility data table. CVDA values are as follows:
- CONTENTION
- The CFDT is to use the contention model, in which records are not locked when they are read for update, but an error is returned on a subsequent REWRITE or DELETE if the record has changed or been deleted since it was read for update.
- LOCKING
- The CFDT is to use the locking coupling facility data table, in which records are locked when they are read for update.
You can specify the update model for a file that does not currently refer to a coupling facility data table, but which might be switched to use a coupling facility data table later.
Conditions
- FILENOTFOUND
- RESP2 values:
- 18
- The named file cannot be found.
- INVREQ
- RESP2 values:
- 1
- The named file is REMOTE.
- 2
- The named file is not CLOSED.
- 3
- The named file is not DISABLED or UNENABLED.
- 4
- ADD has an invalid CVDA value.
- 5
- BROWSE has an invalid CVDA value.
- 6
- BUSY has an invalid CVDA value.
- 7
- DELETE has an invalid CVDA value.
- 8
- DISPOSITION has an invalid CVDA value.
- 9
- EMPTYSTATUS has an invalid CVDA value.
- 10
- LSRPOOLNUM is specified for a non-VSAM data set.
- 11
- LSRPOOLNUM is not in the range 1 - 255, or the corresponding buffer is not defined.
- 12
- READ has an invalid CVDA value.
- 13
- STRINGS value is not in the range 1 - 255, or this is not a VSAM file.
- 14
- UPDATE has an invalid CVDA value.
- 16
- OPENSTATUS has an invalid CVDA value.
- 17
- ENABLESTATUS has an invalid CVDA value.
- 19
- DELETE has been specified for a non-VSAM file.
- 20
- EMPTYSTATUS has been specified for a non-VSAM file.
- 21
- CLOSED or DISABLED has been specified by a task that has issued one or more recoverable requests within the current unit of work.
- 22
- ENABLED was specified for a file that is currently DISABLING or UNENABLING.
- 23
- EXCLUSIVE has an invalid CVDA value.
- 24
- EXCLUSIVE has been specified for a non-BDAM file.
- 28
- OPEN, CLOSE, ENABLE, or DISABLE has been specified but an exit program running at exit point XFCSREQ instructed CICS not to carry out the command.
- 29
- TABLE has an invalid CVDA value.
- 30
- MAXNUMRECS value is out of range.
- 31
- The TABLE option is invalid for a BDAM file (must be VSAM for a data table).
- 32
- The TABLE option is invalid for a file defined with the REUSE option.
- 33
- The TABLE option is invalid for a file defined as UNBLOCKED.
- 34
- The MAXNUMRECS option is invalid for a BDAM file (must be VSAM for a data table).
- 35
- The MAXNUMRECS option is invalid for a file defined with the REUSE option.
- 36
- The MAXNUMRECS option is invalid for a file defined as UNBLOCKED.
- 37
- The TABLE option is invalid when LSRPOOL=0 is specified.
- 39
- The USERTABLE option is invalid when record format is not variable.
- 40
- CONSISTENT or REPEATABLE is specified for a file that is not accessed in RLS mode.
- 41
- The DSNB cannot be disconnected, and a new DSNB cannot be connected, for this file because the file has deferred work outstanding, for which there are retained or repeatable read locks. In this case, at least one shunted UOW is awaiting completion, that has made changes to this file.
- 42
- The SET FILE request cannot be satisfied because the file has deferred work outstanding, for which there are retained or repeatable read locks. In this case, at least one shunted UOW is awaiting completion, that has made changes to this file. The only valid options when a file has deferred work pending are those that change the file state. File state changes are permitted because they might be required to enable the deferred work to be completed.
- 43
- The file cannot be discarded because it has deferred work outstanding, for which there are retained or repeatable read locks. In this case, at least one shunted UOW, awaiting completion, has made changes to this file.
- 44
- A file open request cannot be satisfied because the file refers to a data set that is marked as unavailable by a SET DSNAME UNAVAILABLE command.
- 45
- A file open request cannot be satisfied because the file references an RLS-mode data set that was quiesced by a SET DSNAME QUIESCED command.
- 46
- A file open request cannot be satisfied because the file refers to an RLS-mode data set that is being copied by a DFSMSdss-initiated non-BWO backup.
- 47
- A file open request cannot be satisfied because the file references an RLS-mode data set that is in the process of quiescing by a SET DSNAME QUIESCED command.
- 48
- A file open request cannot be satisfied because the file refers to a data set for which its ICF Catalog entry indicates that a recovery is pending or is in progress; for example, a CICS VSAM Recovery job is running.
- 49
- An invalid CVDA is specified for the READINTEG option.
- 50
- An attempt has been made to open an RLS file but RLS is not supported, either because the level of VSAM does not support RLS or because RLS=NO has been specified during system initialization.
- 51
- An invalid CVDA is specified for the RLSACCESS option.
- 52
- An attempt has been made to specify RLS access for a BDAM data set.
- 53
- An attempt has been made to specify a CICS-maintained data table for a file defined with RLS access.
- 54
- A file open request cannot be satisfied because of one of the
following reasons:
- The file is being opened in RLS mode and this region has other files open in non-RLS mode against the data set that it references.
- The file is being opened in non-RLS mode and this region has other files open in RLS mode against the data set that it references.
- The file is being opened in non-RLS mode and this region has unresolved RLS recovery work against the data set that it references.
- 55
- LOADTYPE has an invalid CVDA value.
- 56
- UPDATEMODEL has an invalid CVDA value.
- 57
- EMPTYSTATUS has a CVDA value that is not allowed for a coupling facility data table. EMPTYSTATUS must be NOEMPTYREQ for a coupling facility data table.
- 58
- CFDTPOOL is not specified for a file that refers to a coupling facility data table.
- 59
- KEYLENGTH is not specified for a file that refers to a coupling facility data table, and which specifies LOAD=NO.
- 60
- An invalid KEYLENGTH is specified. The KEYLENGTH must be in the range 1 - 16 for a coupling facility data table.
- 61
- RECORDSIZE is not specified for a file that refers to a coupling facility data table that specifies LOAD=NO.
- 62
- An invalid RECORDSIZE is specified. RECORDSIZE must be in the range 0 - 32 767 bytes.
- 63
- OPEN is specified for a file that refers to a coupling facility
data table, but OPEN processing has failed because of one of these
reasons:
- The file attributes do not match those specified when the coupling facility data table was created.
- A keylength or recordsize has been specified that exceeds the maximum supported.
- 64
- OPEN is specified for a file that refers to a coupling facility data table, but OPEN processing has failed because the server is unavailable.
- 65
- An invalid CFDTPOOL name is specified.
- 66
- An invalid TABLE name is specified.
- 67
- An UPDATEMODEL of CONTENTION is specified for a recoverable coupling facility data table. The update model must be LOCKING for a coupling facility data table that is recoverable.
- 69
- The DSNAME is invalid.
- 70
- LSRPOOLNUM(0) specified for a CICS or USER maintained data table.
- 300
- You specified an operation that is invalid for a resource that is installed by a BUNDLE resource.
- IOERR
- RESP2 values:
- 0
- The command failed before the request was passed to the resource management system.
- *
- OPEN has failed outside file control. The RESP2 field contains the response that was returned to file control by the external resource management system.
- *
- CLOSE has failed outside file control. The RESP2 field contains the response that was returned to file control by the external resource management system.
In all cases of IOERR, examine the CICS console for messages that provide more information about the error. Resource management system refers to any of the catalog management systems such as VSAM, BDAM, or DFSMS, or to an external resource management system such as CFDT or SDT (Coupling facility data tables, or Shared data tables).
Depending on how you are viewing the RESP2 value, note that it might contain the decimal equivalent of the response returned to file control.
- NOTAUTH
- RESP2 values:
- 100
- The user associated with the issuing task is not authorized to use this command.
- 101
- The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.
Examples
EXEC CICS SET FILE ('FILE12')
WAIT
CLOSED
DISABLED
DELETABLE
LSRPOOLNUM(7)
STRINGS(50)
EXEC CICS SET FILE ('FILE12')
OPEN
ENABLED
On the first command, the WAIT option tells CICS to allow all activity on FILE12 to quiesce before closing the file, and to return control to the issuing application only when this request has been started. When the file is CLOSED, it is DISABLED. Delete commands are allowed, LSRPOOL number 7 is associated with the file, and up to 50 concurrent operations are allowed.
The second of the two commands opens and then enables the file. Setting a file CLOSED and DISABLED makes the file eligible for deletion (DISCARD) or reinstallation by another task. Thus, another task can delete the file after the first SET command but before the second SET command.