FILE attributes

This attribute is ignored for coupling facility data tables and, if there are any recovery attributes defined in the ICF catalog for a source data set associated with the table, these also are ignored. A CFDT is not eligible for backup-while-open (BWO).

A-Z 0-9 $ @ #

Coupling facility data tables can be separated (for purposes of accounting, security, administration, and so on) into groups (pools) of CFDTs. The names of all coupling facility data table pools must be unique within the sysplex, but can be the same as the names of other types of pools, such as TS data-sharing pools.

Opening a file that references a coupling facility data table requires that a coupling facility data table server for the named pool is running in the MVS™ in which the open request is issued. If the required server has not been started, the file open request fails.

OLD

Equivalent to the DISP=OLD parameter in JCL.

SHARE

Equivalent to the DISP=SHR parameter in JCL.

A-Z 0-9 $ @ # . -

At file open time, if no JCL statement exists for this file, the open is preceded by a dynamic allocation of the file using this DSNAME. If the file definition refers to a data table (CICS, USER, or CF) the DSNAME must be that of a VSAM base KSDS. It cannot be a path or alternate index data set.

ALLREQS

Data set name sharing is set in the ACB when the file is opened and is therefore used for all file requests.

MODIFYREQS

Data set name sharing is set in the ACB when the file is opened only if an operation of DELETE, ADD, or UPDATE is set for the file.

If you define the recovery attributes for a file in the ICF catalog entry for the corresponding data set, CICS always uses the ICF catalog recovery attributes and ignores those in the FILE resource. To force CICS to use the FILE resource attributes instead of the recovery options in the catalog, set the NONRLSRECOV system initialization parameter to FILEDEF. You can alter the recovery attributes defined in the ICF catalog by using the IDCAMS ALTER command. This is not prevented while there are ACBs open for a data set. However, if you change the recovery attributes, be aware of the possible effect on data integrity.

CICS takes a copy of the recovery attributes for a data set from the ICF catalog on the first open-for-update in a sequence of open requests for a data set. This means that a single CICS region is not affected by an update to recovery attributes. However, if a data set is opened in RLS mode and the attributes on the ICF catalog are modified, a second CICS region could open the same data set for update and copy a different set of attributes, with a risk to data integrity.

If you must alter recovery attributes defined in the ICF catalog (for example, to change the forward recovery log stream name), quiesce the data set before making any changes. This ensures that the data set cannot be used in RLS mode until you have made the change and unquiesced the data set.

A-Z 0-9 $ @ #

The GROUP name can be up to 8 characters in length. Lowercase characters are treated as uppercase characters.

AFTER

Add the file control write operation to the journal after the VSAM I/O operation.

ALL

Add the file control write operation to the journal both before and after the VSAM I/O operation has completed.

BEFORE

Add the file control write operation to the journal before the VSAM I/O operation.

NONE

Do not add write operations to the journal.

ALL

Add all read operations to the journal.

NONE

Do not add read operations to the journal.

READONLY

Add only READ ONLY operations (not READ UPDATE operations) to the journal.

UPDATEONLY

Add only READ UPDATE operations (not READ ONLY operations) to the journal.

The data to be journaled is identified by the JNLADD, JNLREAD, JNLSYNCREAD, JNLSYNCWRITE, and JNLUPDATE attributes.

For a CICS-maintained data table, journaling is performed only for requests that result in VSAM I/O requests.

For a user-maintained data table or a coupling facility data table journaling is not performed for any file control operations. However, although automatic journaling for these tables is not supported, if you specify a journal number, CICS tries to open the log stream for the specified journal when opening the file.

NO

No automatic journaling is to take place for this file.

number

The number that identifies the journal that CICS is to use for the autojournal. CICS journal names are of the form DFHJnn, where nn is in the range 01 through 99.

Note: In CICS Transaction Server for z/OS, DFHJ01 is not the system log.

If KEYLENGTH is not defined here, the KEYLENGTH option must be specified on file control commands in the application programs that refer to this file. If KEYLENGTH is not defined here and is not specified in the application program, and the key is longer than 4 characters, the default value is 4.

NO

Means that the coupling facility data table does not require loading from a source data set; it is fully usable by application programs as soon as it is open. The table is loaded by the application programs that use it, which is the default method for a coupling facility data table.

YES

Means that the coupling facility data table has to be loaded from a source data set before it is fully usable; the application programs that use this coupling facility data table rely on it containing the records from a source data set. Loading does not have to be completed before data can be accessed.

This attribute is meaningful only for files defined with the TABLE(CF) attribute. You can specify the LOAD attribute for a file that is not defined as TABLE(CF), but CICS ignores it. (CICS-maintained and user-maintained tables are loaded automatically always from a source data set.) If you then alter the file definition to reference a coupling facility data table, the LOAD attribute comes into effect.

Ensure that the value for this attribute is the same throughout the sysplex in all file definitions that reference the same coupling facility data table.

For more information about using this attribute, see Coupling facility data tables.

The value specified for LSRPOOLID in existing definitions is transferred to the new option LSRPOOLNUM.

NONE

Specifies that the data set associated with this file uses VSAM nonshared resources (NSR).

You cannot specify NONE for a CICS shared data table (CICS or user-maintained), because these types of data tables must use an LSR pool. However, this restriction does not apply to a coupling facility data table, for which you can specify NONE.

VSAM nonshared resources (NSR) are not supported for transactions that use transaction isolation. Specify ISOLATE(NO) when you define transactions that access VSAM files that use NSR. You can also function ship the file request to a remote region. The DFHMIRS program that carries out the request is defined with an EXECKEY of CICS. A CICS-key program has read and write access to CICS-key and user-key storage of its own task and all other tasks, whether or not transaction isolation is active.

number

Identifies the number of the VSAM shared resource pool that is used by the VSAM data set associated with this file. The value must be in the range 1 through 255. The data set is defined as using VSAM local shared resources (LSR). Define the buffers, strings, and other resources explicitly in an LSRPOOL resource definition that corresponds to the assigned LRPOOLNUM value.

By default, if the file definition specifies RLSACCESS(YES), the LSRPOOLNUM value is ignored when CICS opens the file. However, if you change a file definition that specifies an LSR pool from RLSACCESS(NO) to RLSACCESS(YES), you are advised to keep the LSRPOOLNUM value. LSRPOOLNUM ensures that, if the file is switched at any time from RLS to LSR mode, the file correctly references an LSR pool.

• All the storage in the server's pool if the table is a coupling facility data table
• All the storage in the MVS data space if the table is a CICS- or user-maintained table.

The NSRGROUP attribute takes effect only for files referencing data sets that use VSAM nonshared resources. The NSRGROUP attribute must not be coded for a data table. It is associated with the VSAM concept of data set name sharing which causes VSAM to create a single control block structure for the strings and buffers required by all the files that relate to the same base data set.

When the first member of such a group of files is opened, the total number of strings to be allocated for all file entries in the group must be specified to VSAM (with the BSTRNO value in the Access Control Block). The VSAM control block structure is built this time regardless of whether the first file to be opened is associated with a path or base data set. The value of BSTRNO is calculated at this time by adding the STRINGS values in all the file definitions with the same NSRGROUP attribute. After the first file in the group is opened, any new files added to the group do not affect the VSAM control block structure already built. This would change only if all the files open against the base cluster were closed and then reopened.

Data set name sharing is forced by CICS as the default for all VSAM files. Data set name sharing is not in effect if a file is opened for read-only processing with DSNSHARING=MODIFYREQS. A file with DSNSHARING=MODIFYREQS still, however, contributes to the BSTRNO calculation.

If a file is using VSAM nonshared resources, and you do not provide an NSRGROUP attribute, the VSAM control block structure might be built with insufficient strings for later processing. When this happens, VSAM invokes the dynamic string addition feature to provide the extra control blocks for the strings as they are required. This mechanism is, however, inefficient and the extra storage is not released until the end of the CICS run.

For files specifying that VSAM local shared resources are to be used (LSRPOOLNUM=n, where n is in the range 1 - 255), NSRGROUP has no effect.

CEDA DEFINE FILE(VSAM10B)  GROUP(xxxxxx)
            DSNAME(DTGCAT.VSAM10B)
            DISPOSITION(SHARE)  ADD(YES)
            BROWSE(YES)  DELETE(YES)  READ(YES)
            UPDATE(NO)  RECORDFORMAT(F)
            STRINGS(8)  LSRPOOLNUM(NONE)
            RECOVERY(NONE)  NSRGROUP(GROUP1)
            INDEXBUFFERS(8)  DATABUFFERS(9)
CEDA DEFINE FILE(VSAM10P)  GROUP(xxxxxx)
            DSNAME(DTGCAT.VSAM10P)
            LSRPOOLNUM(NONE)  DISPOSITION(SHARE)
            STRINGS(5)  NSRGROUP(GROUP1)
            BROWSE(YES)  DELETE(NO)  READ(YES)
            ADD(NO)  UPDATE(NO)  RECORDFORMAT(F)
            RECOVERY(NONE)  INDEXBUFFERS(5)
            DATABUFFERS(6)

FIRSTREF

The file remains closed until a request is made to open it by using one of the following methods:

• A master terminal command
• An EXEC CICS SET FILE OPEN command in an application program
• An implicit open

STARTUP

The file is opened immediately after CICS initialization by an automatically initiated CICS transaction (CSFU), unless the status of the file is UNENABLED when the file remains closed.

CICS masks the password you supply to avoid unauthorized access. You should therefore find a safe way of recording the password.

This attribute is not supported for FILE resources that are dynamically generated by a CICS bundle.

You can use READINTEG to set a default level of read integrity for a file. The default level of read integrity is used by programs that do not specify one of the API read integrity options UNCOMMITTED, CONSISTENT, or REPEATABLE on the READ, READNEXT, or READPREV commands. However, if an application program uses one of these explicitly to specify read integrity, the API option overrides any value specified on this READINTEG attribute.

You can specify CONSISTENT or REPEATABLE in a file resource definition, to make read integrity available to programs written before these options were available on the API, and without having to modify those programs. However, if you do this, be aware that enforcing consistent or repeatable reads can introduce unexpected deadlocks. Programs might also encounter the LOCKED condition.

F

The records are fixed length. For VSAM files, specify this only if the VSAM access method services definition specifies fixed size records (that is, the average size is equal to the maximum size), and all the records in the file are of that size.

F is invalid for user-maintained data tables and coupling facility data tables

V

The records are variable length. All user-maintained data tables and coupling facility data tables must be specified as variable length. Otherwise, CICS returns an error message stating that RECORDFORMAT(F) conflicts with TABLE(CF) or TABLE(USER) options and is ignored.

For coupling facility data tables only

This value is required if the file definition for the table specifies LOAD(NO).

You can also specify this attribute if LOAD(YES) is specified (for example, to make it easier for switching the file definition between LOAD(NO) and LOAD(YES)). However, if you specify LOAD(YES), the record size value must match that for the source data set, otherwise CICS fails to open the table. There are three conditions in which CICS can detect an error because of an incorrect record size with LOAD(YES):

1. Before opening the table, CICS verifies that the VSAM-defined record size for the data set from which the coupling facility data table is to be loaded is the same as the size, if any, in the file definition. If the record size is different, CICS returns error message DFHFC7081.
2. The record size (if specified) on the file definition is the same as that defined to VSAM for the data set, but on opening the table, CICS finds the table is already loaded with data of a different record size. This is probably because the data was loaded from a different data set from the one specified by this file definition. In this case CICS returns error message DFHFC7082.
3. The file definition for the table being opened specifies a record size, but not a data set name because the table is to be loaded by the opening of a different file. If the table has already been created, the open of a file specifying a different record size fails with message DFHFC7083.

To avoid these errors, ensure that the value for this attribute is the same throughout the sysplex in all file definitions that reference the same coupling facility data table, or omit it altogether for files that specify LOAD(YES).

If you specify a record size for a file that is not a remote file, or does not refer to a CFDT, it has no effect unless the file is redefined, either as a remote file or to reference a coupling facility data table. Note, however, that if you specify a record size, the value returned by an INQUIRE FILE command is as follows:

• If the file is open, CICS returns the value obtained from VSAM, which can be different from that specified on the file definition.
• If the file is closed, CICS returns the value specified on the file definition.

Note: For coupling facility data tables, if you can keep the record size to 63 bytes or less, there is a significant gain in performance as a result of the way records are held in the coupling facility.

This attribute is not used for files defined with RLSACCESS(YES), or if the recovery options are defined in the ICF catalog. If LOG is defined in the ICF catalog, CICS ignores the RECOVERY option and takes the LOG value from the ICF catalog, even for files defined with RLSACCESS(NO). If LOG(ALL) is specified in the ICF catalog, CICS also takes the LOGSTREAMID and BWO values from the ICF catalog. To force CICS to use this attribute instead of the recovery options in the catalog, set the NONRLSRECOV system initialization parameter to FILEDEF.

For files that are accessed in RLS mode, you must specify the recovery parameters with the data set definition in the ICF catalog. See Defining files as recoverable resources for more information.)

For coupling facility data tables and user-maintained tables that are defined with a source data set, any recovery attributes in the ICF catalog are ignored. The recovery attributes are a property of the file not the associated data set.

For coupling facility data tables, the recovery attribute must be the same throughout the sysplex in all file definitions that reference the same coupling facility data table.

A-Z 0-9 $ @ #

If you specify a remote name, CICSPlex® SM uses that name when assigning the file to a related system. If you specify a remote system but not a remote name, the local name (that is, the name of this file definition) is used in both the target and related systems.

For IPIC connections, REMOTESYSTEM specifies the first 4 characters of the IPCONN name on the IPCONN definition that is in service and acquired.

For MRO and APPC connections, REMOTESYSTEM specifies the CONNECTION name on the CONNECTION definition.

A-Z 0-9 $ @ #

NO

The file is not to be opened in RLS mode. If you specify RLSACCESS(NO) or allow it to default, CICS opens the file in LSR or NSR access mode, depending on the LSRPOOLNUM attribute. If you also specify LSRPOOLNUM(NONE), the access mode is NSR; if you specify LSRPOOLNUM(number), the access mode is LSR.

YES

The file is to be opened in RLS mode. If you specify RLSACCESS(YES), it takes precedence over the LSRPOOLNUM attribute, which is ignored when the FILE is opened.

Specifying RLSACCESS(YES) alters the effect of some other attributes defined in the FILE definition, as shown in Table 1.

DISABLED

Any request against this file from a command-level application program causes the DISABLED condition to be passed to the program.

ENABLED

Normal processing is allowed against this file.

UNENABLED

This prevents the file being opened by an implicit open from an application program. Any such attempt to access the file raises the NOTOPEN condition. By contrast, an explicit request to open the file (for example, a CEMT or EXEC CICS SET FILE OPEN command) changes the status to ENABLED before attempting to open the file.

This attribute is ignored for FILE resources that are dynamically generated by a CICS bundle. The initial status of a FILE resource is derived from the initial status of the bundle that defines the resource.

CF

A coupling facility data table (CFDT). This remains independent of its source data set, and changes to the table are not reflected in the corresponding source data set, if there is one. A source data set is optional for a CFDT, and is specified by LOAD(YES) on the file definition.

If you specify CF, also specify:

• CFDTPOOL, to give the name of the coupling facility pool in which the table resides
• LOAD, to specify whether the table is to be loaded from a source data set (or let this default to NO)
• UPDATEMODEL to specify whether the table is to use the CONTENTION or the LOCKING update model (or let this default to LOCKING)
• RECORDFORMAT as V (or let this default to V)
• MAXNUMRECS with the value you require.

A coupling facility data table requires a coupling facility data table server. For information about how to start a coupling facility data table server, see Setting up and running a coupling facility data table server.

CICS

A CICS-maintained data table. This automatically reflects all modifications made to the table in its source data set. If you specify CICS, also specify:

• LSRPOOLNUM with a value of 1 through 255
• MAXNUMRECS with the value you require.

NO

Data table not required.

USER

A user-maintained table. This remains independent of its source data set, and changes to the user-maintained table are not reflected in corresponding source data set. If you specify USER, also specify:

• LSRPOOLNUM with a value of 1 through 255
• RECORDFORMAT as VARIABLE (or let this default to VARIABLE)
• MAXNUMRECS with the value you require.

A-Z 0-9 $ @ #

If you omit this attribute when TABLE(CF) is specified, it defaults to the name specified for the FILE. To enable CICS regions to share a coupling facility data table, the file definitions installed in each region must specify the same CFDTPOOL name and TABLENAME (or FILE name when TABLENAME is not used). The TABLENAME need only be unique within its pool.

Note that the table name is not only an identifier for the table, but is also used as the resource name in security checks.

This attribute is meaningful only for files defined with the TABLE(CF) attribute. You can specify a table name for a file that is not defined as TABLE(CF), but CICS ignores it. If you then alter the file definition to reference a coupling facility data table, the TABLENAME attribute comes into effect.

LOCKING

Specifies that the CFDT is updated using the locking model. This means that records are locked when they are read for update, so that they cannot be changed by any other units of work until the update request has been completed. For recoverable tables, the update request is completed at sync point. For unrecoverable tables, the update request is completed when a REWRITE, DELETE, or UNLOCK command is completed. LOCKING is the default for a file that specifies TABLE(CF). With the LOCKING model, the CFDT can be defined as:

• Unrecoverable, meaning that CFDT updates are not backed out if a unit of work fails, and the locks are only held for the duration of a request. You specify that a CFDT is not recoverable by specifying RECOVERY(NONE).
• Recoverable, or UOW-recoverable, meaning that updates made to the CFDT within a unit of work are backed out if the unit of work fails, or if CICS or the CFDT server fails while the unit of work is in-flight, or if MVS fails. You specify that a CFDT is recoverable by specifying RECOVERY(BACKOUTONLY).

A recoverable CFDT that uses the locking model is like a recoverable file or data set, except that it does not survive a failure of the coupling facility in which it resides. There is no forward recovery for a coupling facility data table.

CONTENTION

Specifies that the CFDT is updated using the contention model. This means that records are not locked when they are read for update. An error is returned on a subsequent REWRITE or DELETE if the record was changed or deleted by another task after it was read for update. The CFDT must be unrecoverable (RECOVERY(NONE)), meaning that updates are not backed out if a unit of work fails.

The value for this attribute must be the same throughout the sysplex in all file definitions that reference the same coupling facility data table.

This attribute is meaningful only for files defined with the TABLE(CF) attribute. You can specify the update model for a file that is not defined as TABLE(CF), but CICS ignores it. If you then alter the file definition to reference a coupling facility data table, the UPDATEMODEL attribute comes into effect.