SET FILE

Change attributes of a VSAM or BDAM file, including files that refer to CICS® shared data tables and coupling facility data tables.

SET FILE

Conditions: FILENOTFOUND, INVREQ, IOERR, NOTAUTH

Options

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

Note: This command replaces the SET DATASET command. The DATASET keyword is supported by the translator as a synonym for FILE, but use FILE for all new applications. Similarly, OBJECTNAME is supported as a synonym for DSNAME.

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.

SET FILE ENABLED

Conditions: FILENOTFOUND, INVREQ, NOTAUTH

SET FILE DISABLED

Conditions: FILENOTFOUND, INVREQ, NOTAUTH

SET FILE OPEN

Conditions: FILENOTFOUND, IOERR, NOTAUTH

SET FILE CLOSED

Conditions: FILENOTFOUND, INVREQ, IOERR, NOTAUTH

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.

To modify the attributes of a FILE resource that was defined and installed in a CICS bundle, use the resource editor in the CICS Explorer® to modify the definition in the CICS bundle, and install a new version of the CICS bundle or of the application with which it was deployed. To update the definition, replace the old version of the CICS bundle with the new one, following the instructions in Working with bundles in the CICS Explorer product documentation.

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.

You can use the SET FILE command to change the attributes of the dynamically generated resource, but these changes are not cataloged and are not recovered across a warm restart of CICS.

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.

If no JCL statement exists for this file when it is opened, the open is preceded by a dynamic allocation of the file using this data set name. If there is a JCL statement, it takes precedence over the data set name that is specified in this option.

If the file is associated with a coupling facility data table, DSNAME specifies the name of the source data set from which the table is loaded when the file definition specifies LOAD(YES).

When you add a data set name to a file definition for a coupling facility data table, LSR pool size calculations might be involved when the file is opened. This calculation occurs when the file refers to an LSRPOOL that CICS builds using default values, and the first data set that uses the LSR pool is opened to load the table. CICS issues message DFHFC0208, which indicates that a delay might occur while the LSR pool size is being calculated. If you specify a data set name on a file that refers to an LSR pool that is already built using default values, the data set has not been included in the LSR pool calculation, indicating that the existing LSR pool might not be adequate for the new data set. To resolve any problems associated with an LSR pool used in this way, you can close all files that refer to the pool, which causes CICS to discard the pool and rebuild it using new calculations the next time a file is opened that refers to the pool. Alternatively, define the LSR pool explicitly specifying the appropriate values. See LSRPOOL resources for information about defining LSR pools.

With the SET FILE command, you can dissociate the file from any DSNAME by supplying a DSNAME value that begins with a null character (hexadecimal zeros).

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.