- ADD({NO|YES})
- specifies whether records can be added to the file.
- BACKUPTYPE({STATIC|DYNAMIC})
- CICS® VSAM
files can be defined as eligible for backup while open for update. This attribute
is not used for files defined with RLSACCESS(YES), or if the recovery options
are defined in the ICF catalog. For files that are accessed in RLS mode,
you must specify the backup type on the data set definition in the ICF catalog.
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).
Possible values are:
- DYNAMIC
- Specify this along with the RECOVERY attribute of ALL to make the file
eligible for backup while open for update.
- STATIC
- The file is not eligible for backup while open for update.
- BROWSE({NO|YES})
- specifies whether records can be retrieved sequentially from the file.
- CFDTPOOL(cfdtpool)
- specifies the name of the coupling facility data table pool containing
the table defined by this file definition. This attribute is required if you specify
TABLE(CF).
Acceptable characters:A-Z 0-9 $ @ #
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
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.
Note: The
CFDTPOOL attribute is meaningful only for CFDTs. You can specify a pool name
for a file that is not defined as TABLE(CF), but CICS ignores it. If you subsequently
alter the file definition to reference a coupling facility data table, the
CFDTPOOL name comes into effect.
- DATABUFFERS({2|value})
- specifies the number of buffers to be used for data. Use a value in the
range 2 (the default) through 32767. The minimum value you can specify is
one more than the number of strings defined in the STRINGS attribute.
- DELETE({NO|YES})
- specifies whether records can be deleted from the file.
- DESCRIPTION(text)
- You can provide a description of the resource you are defining in this
field. The description text can be up to 58 characters in length. There are
no restrictions on the characters that you can use. However,
if you use parentheses, ensure that for each left parenthesis there is a matching
right one. If you use the CREATE command, for each single apostrophe in the
text, code two apostrophes.
- DISPOSITION({SHARE|OLD})
- specifies the disposition
of this file.
- OLD
- Equivalent to the DISP=OLD parameter in JCL.
- SHARE
- Equivalent to the DISP=SHR parameter in JCL.
- DSNAME(dsname)
- specifies the data set name (as known to the operating system) to be used
for this file. DSNAME can be 1 through 44 characters, conforming to the rules
for MVS data set names (see the DSNAME parameter in the z/OS MVS JCL Reference).
Acceptable characters:A-Z 0-9 $ @ # . -
Any
lowercase characters you enter are converted to uppercase. |
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.
The DSNAME
specified on a DD statement for this file in the CICS start-up JCL takes precedence
over the DSNAME specified in this file definition.
- Coupling facility data tables
- If the file definition specifies LOAD(YES) and it is not already opened,
DSNAME specifies the name of the source data set from which the table is to
be loaded. Alternatively, you can specify the source data set on a DD statement
in the CICS startup JCL. The data set specified must be a VSAM base KSDS.
If there is a path or alternate index associated with the source data
set, then any updates made via the file will not be reflected in either the
source data set or its associated alternate indexes. A coupling facility data
table is entirely independent of its source data set after loading has completed.
If
you want table loading to be initiated by the opening of another file specified
by a different file definition, omit this attribute. In this case, also ensure
that the file name is not specified on a DD statement in the CICS JCL. Attempts
to open the file fail until CFDT loading has been initiated. For more information
about loading a coupling facility data table from a data set, see Coupling facility data tables.
If LOAD(NO) is specified, this attribute is
not required and is ignored.
- DSNSHARING({ALLREQS|MODIFYREQS})
- specifies whether VSAM data set name sharing is used for the VSAM file.
The possible values are:
- 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.
- FILE(name)
- specifies the name of the file. The name can be up to eight characters
in length.
Acceptable characters:A-Z 0-9 $ @ #
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
The name must not start with a numeric
character.
- FWDRECOVLOG({NO|journal})
- specifies the journal that corresponds to the MVS system logger log stream
that is to be used for forward recovery.
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 forward recoverable.
- NO
- Forward recovery logging is not required for this file.
- journal
- The number that identifies the journal that CICS is to use for the forward
recovery log. CICS journal names are of the form DFHJnn where nn is
in the range 1 through 99. The after images for forward recovery are written
to the MVS log stream that corresponds to journal name DFHJnn.
Note: In CICS Transaction Server for z/OS®,
DFHJ01 is not the system log.
This attribute is used by CICS only
if:
- RECOVERY(ALL) is specified
- RLSACCESS(NO) is specified
- No recovery attributes are defined in the ICF catalog
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 definition.
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 need to 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.
- GROUP(groupname)
- Every resource definition must have a GROUP name. The resource definition
becomes a member of the group and is installed in the CICS system when the
group is installed.
Acceptable characters:A-Z 0-9 $ @ #
Any
lower case characters you enter are converted to upper case. |
The GROUP name can be up to eight characters in length. Lowercase
characters are treated as uppercase characters. Do not use group names beginning
with DFH, because these characters are reserved for use by CICS.
- INDEXBUFFERS({1|number})
- specifies the number of buffers to be used for the index. Use a value
in the range 1 through 32767. The minimum value you can specify is the number
of strings defined in the STRINGS attribute.
- JNLADD({NONE|BEFORE|AFTER|ALL})
- specifies the add operations you want recorded on the journal nominated
by the JOURNAL attribute. Possible values are:
- AFTER
- Journal the file control write operation after the VSAM I/O operation.
- ALL
- Journal the file control write operation both before and after the VSAM
I/O operation has completed.
- BEFORE
- Journal the file control write operation before the VSAM I/O operation.
- NONE
- Do not journal add operations.
- JNLREAD({NONE|UPDATEONLY|READONLY|ALL})
- specifies the read operations you want recorded on the journal nominated
by the JOURNAL attribute. Possible values are:
- ALL
- Journal all read operations.
- NONE
- Do not journal read operations.
- READONLY
- Journal only READ ONLY operations (not READ UPDATE operations).
- UPDATEONLY
- Journal only READ UPDATE operations (not READ ONLY operations).
- JNLSYNCREAD({NO|YES})
- specifies whether you want the automatic journaling records, written for
READ operations to the journal specified by JOURNAL, to be written synchronously
or asynchronously.
- JNLSYNCWRITE({YES|NO})
- specifies whether you want the automatic journaling records, written for
WRITE operations to the journal specified by JOURNAL, to be written synchronously
or asynchronously.
- JNLUPDATE({NO|YES})
- specifies whether you want REWRITE and DELETE operations recorded on the
journal nominated by the JOURNAL attribute.
- JOURNAL({NO|journal})
- specifies whether you want automatic journaling for this file. The journaled
data is in the format of the VSAM record and is used for user controlled journaling.
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.
Note: Automatic journaling is independent of logging to the system
and forward recovery logs, as specified by the RECOVERY and FWDRECOVLOG attributes.
Possible
values are: - 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 1 through 99.
Note: In CICS Transaction Server for z/OS,
DFHJ01 is not the system log.
- KEYLENGTH(value)
- specifies the length in bytes of the logical key of records in remote
files, and in coupling facility data tables that are specified with LOAD(NO).
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 not specified in the application program,
and the key is longer than 4 characters, the default value is 4.
- Remote files
- The range for key length is 1 through 255.
- Coupling facility data tables
- The range for key length is 1 through 16. Key length is required only
if LOAD(NO) is specified.
You can, optionally, specify a key length for
coupling facility data tables specified with LOAD(YES), in which case you
should be aware of the following:
- The key length is obtained from the ICF catalog entry for the data set
from which the table is loaded. If you specify a key length, the key length
must match that specified for the source data set, otherwise attempts to open
the file fail with an error message.
- If, when opening the file, CICS finds that the CFDT has already been created,
and the key length is different from that used when loading the data set,
the open fails.
If you specify a key length 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 CFDT. Note, however, that if you
specify a key length, 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.
The value for this attribute must be the same throughout the
sysplex in all file definitions that reference the same coupling facility
data table.
- LOAD({NO|YES})
- specifies whether the coupling facility data table is to be loaded from
a source data set when first opened.
- NO
- Means 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 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 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 subsequently
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.
- LSRPOOLID({1|2|3|4|5|6|7|8|NONE})
- specifies the identity of the local shared resource pool. The default
value for LSRPOOLID is 1, unless a value has been specified for the NSRGROUP
attribute, in which case the default value for LSRPOOLID is NONE.
- NONE
- Specifies that the data set associated with this file uses VSAM nonshared
resources (NSR).
Note: - You cannot specify NONE for a CICS shared data table (CICS- or user-maintained):
both these types of data table 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. You should specify ISOLATE(NO) when you define
transactions that access VSAM files using NSR.
- 1|2|3|4|5|6|7|8
- The value, in the range 1 through 8, identifies the number of the VSAM
shared resource pool that is used by the VSAM data set associated with this
file. The data set is defined as using VSAM local shared resources (LSR).
You are recommended to define the buffers, strings, and other resources explicitly
in an LSRPOOL resource definition that corresponds to this LSRPOOLID.
By default, if the file definition specifies RLSACCESS(YES),
the LSRPOOLID 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 recommended to keep the LSRPOOLID. This ensures that, if the file
is switched at any time from RLS to LSR mode, the file correctly references
an LSR pool.
- MAXNUMRECS({NOLIMIT|number})
- specifies the maximum number of records (entries) to be accommodated in
the data table. You can use this attribute to prevent a runaway transaction
from using:
- 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.
This attribute is meaningful only for files defined with 'CICS',
'USER', or 'CF' for the TABLE attribute. You can specify MAXNUMRECS for a
file that is defined with TABLE(NO), but it has no effect. If you subsequently
alter the file definition to reference a data table, the MAXNUMRECS value
comes into effect.
- NOLIMIT
- There is no user-specified limit placed on the number of records that
can be stored in the table. CICS imposes a limit of 2 147 483 647, the maximum
fullword value.
- number
- Specifies the maximum number of records allowed in the table, in the range
1 through 99 999 999.
If you are setting a limit for a recoverable coupling
facility data table, specify a value that is about 5 to 10% greater than the
maximum number of records the table is expected to contain. This is to allow
for additional records that may be created internally for processing recoverable
requests. The margin you allow 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 internal processing is that the NOSPACE condition with a
RESP2 of 102 can be raised on a WRITE or REWRITE request to a recoverable
coupling facility data table that apparently has fewer records than the MAXNUMRECS
limit that has been specified for it.
- NSRGROUP(group)
- specifies a symbolic name (up to eight characters) to group together file
definitions that refer to the same VSAM base data set. The value is purely
symbolic and need not refer to any particular file definition. It is merely
necessary that all file definitions that need to be grouped together have
the same name. You do not have to specify this attribute to ensure correct
processing, but if you do not provide it, performance of your system may be
degraded.
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
(by means of 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 together 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 were closed and then re-opened.
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
may 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 (LSRPOOLID=n,
where n is in the range 1 to 8), NSRGROUP has no effect.
Figure 1 shows an example of how to specify the required file control
definition for a VSAM base data set and alternate index path.
Figure 1. VSAM base data set and alternate index path
definition.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) LSRPOOLID(NONE)
RECOVERY(NONE) NSRGROUP(GROUP1)
INDEXBUFFERS(8) DATABUFFERS(9)
CEDA DEFINE FILE(VSAM10P) GROUP(xxxxxx)
DSNAME(DTGCAT.VSAM10P)
LSRPOOLID(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)
- OPENTIME({FIRSTREF|STARTUP})
- specifies when the file is opened. Possible values are:
- FIRSTREF
- The file remains closed until a request is made to open it by:
- 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 is left closed.
- PASSWORD(password)
- specifies the 1-to 8-character password that is used to verify user access
to the file.
CICS masks the
password you supply to avoid unauthorized access. You should therefore find
a safe way of recording the password.
- READ({YES|NO})
- specifies whether records on this file can be read.
- READINTEG({UNCOMMITTED|CONSISTENT|REPEATABLE})
- specifies the level of read integrity required for files defined with
RLSACCESS(YES). Read integrity does not apply to non-RLS access mode files,
CICS shared data tables, or coupling facility data tables.
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.
Note: You can specify read
integrity options only on CICS file control API commands or in CICS file resource
definitions. You cannot use the equivalent parameter on the DD statement for
files opened by CICS.
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 may also
encounter the LOCKED condition.
- CONSISTENT
- The record is read with consistent read integrity. If the record is being
modified by another transaction, the READ request waits until the update is
complete, the timing of which depends on whether the data set is recoverable
or nonrecoverable:
- For a recoverable data set, the READ request completes when the updating
transaction completes its next syncpoint or rollback.
- For a nonrecoverable data set, the READ completes as soon as the VSAM
request performing the update completes.
CONSISTENT is valid only if you also specify RLSACCESS(YES)—the resource
definition is rejected with an error if you specify CONSISTENT for a non-RLS
file.
- REPEATABLE
- The record is read with repeatable read integrity. If the record is being
modified by another transaction, the READ request waits until the update is
complete, the timing of which depends on whether the data set is recoverable
or nonrecoverable:
- For a recoverable data set, the READ request completes when the updating
transaction completes its next syncpoint or rollback.
- For a nonrecoverable data set, the READ completes as soon as the VSAM
request performing the update completes.
After the read completes, a shared lock remains held until syncpoint.
This guarantees that any record read within a unit-of-work cannot be modified
while the task makes further read requests. Error responses such as NOTFND
may not be repeatable.
REPEATABLE is valid only if you also specify
RLSACCESS(YES)—the resource definition is rejected with an error if you specify
REPEATABLE for a non-RLS file.
- UNCOMMITTED
- The record is read without read integrity. CICS obtains the current value
of the record as known to VSAM. No attempt is made to serialize this read
request with any concurrent update activity for the same record. The record
returned may be a version updated by another transaction, but not yet committed,
and this record may change if the update is subsequently backed out.
Note: - UNCOMMITTED is the same level of integrity that is provided by those releases
of CICS that do not support the READINTEG attribute.
- Specify UNCOMMITTED for any kind of data table. Any value other than UNCOMMITTED
is allowed if RLSACCESS(YES) but is ignored if TABLE(CF), TABLE(CICS), or
TABLE(USER) is also specified for the file.
- RECORDFORMAT({V|F})
- specifies the format of the records on the file.
- 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.
- RECORDSIZE(number)
- specifies the maximum length in bytes of records in a remote file or a
coupling facility data table. The size specified can be in the range 1 through
32767.
- 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):
- 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.
- 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.
- 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 the above errors, ensure 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 signficant gain in performance as a result
of the way records are held in the coupling facility.
- RECOVERY({NONE|BACKOUTONLY|ALL})
- specifies the type of recovery required for the file.
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.
For
files that are accessed in RLS mode, you must specify the recovery parameters
with the data set definition in the ICF catalog. See the CICS Recovery and Restart Guide 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.
- ALL
Except for coupling facility data tables, which
manage their own recovery and do not use the services of log manager or recovery
manager,
before images are recorded in the system log, and after images
in the journal specified in the FWDRECOVLOG attribute. Records written
to the FWDRECOVLOG are independent of any automatic journaling options that
may be set.
RECOVERY=ALL together with FWDRECOVLOG provide a means
of separating the needs of a forward recovery utility from those of automatic
journaling. Additional information, not available via automatic journaling,
is recorded on the FWDRECOVLOG. RECOVERY=ALL plus FWDRECOVLOG is the recommended
way to provide forward recovery support.
Existing forward recovery
utilities that used the JREQ=(WU,WN) and JID=FCT macro settings can still
be used with these settings. The RDO equivalents of these automatic journaling
settings are JNLADD=BEFORE, JNLUPDATE=YES, and the JOURNAL attribute.
For
CICS-maintained data tables, the data table and its source data set are
logged, journaled, and recovered together.
For user-maintained tables,
specifying ALL has the same effect as specifying BACKOUTONLY: only dynamic
backout is provided. There is no forward recovery support for user-maintained
tables.
For coupling facility data tables you cannot specify
ALL.
Note: When ALL is specified for VSAM ESDS files, CICS is unable to
perform backout of ADDs. To cope with this situation, code user exit XFCLDEL
to avoid the file being closed because of the error.
- BACKOUTONLY
Except for coupling facility data tables, which
manage their own recovery and do not use the services of log manager or recovery
manager,
before images are recorded in the system log. For CICS-maintained
data tables, BACKOUTONLY specifies that the data table and its source
data set are recoverable. They are both updated in step and, if required,
recovered in step.
For user-maintained tables, this specifies
only dynamic backout. No log records are written and, therefore, there is
no recovery at emergency restart.
For coupling facility data tables,
BACKOUTONLY is permitted only if the coupling facility data table is defined
with UPDATEMODEL(LOCKING). You cannot specify this attribute for UPDATEMODEL(CONTENTION).
Specifying BACKOUTONLY implies that a coupling facility data table is UOW-recoverable.
This means 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.
Note: When BACKOUTONLY is specified
for VSAM ESDS files, CICS is unable to perform backout of ADDs. To cope with
this situation, code user exit XFCLDEL to avoid the file being closed because
of the error.
- NONE
- There is no recovery logging for this file.
- REMOTENAME(file)
- specifies, if the file resides on a remote system, the name by which
this file is known in the system or region in which it is resident. The name
can be up to eight characters in length. If REMOTENAME is not specified, the name
given in the FILE attribute is used.
Acceptable characters:A-Z 0-9 $ @ #
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
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.
- REMOTESYSTEM(connection)
- If you are operating
in an ISC or MRO environment, and the file is held by a remote system, this
specifies the name of the system or region in which the file is resident.
The name can be up to four characters in length. If you specify REMOTESYSTEM,
you may also supply a REMOTENAME, to specify the name of the file in the remote
system.
Acceptable characters:A-Z 0-9 $ @ #
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
Note: If you modify a resource definition from RLSACCESS(NO)
to RLSACCESS(YES), you must remove the remote system name. Otherwise CICS
will continue to function ship file requests.
- RESSECNUM
- This attribute is obsolete, but is supported to provide compatibility
with earlier releases of CICS. For more information, see Obsolete attributes.
- RLSACCESS({NO|YES})
- specifies whether CICS is to open the file in RLS mode.
- 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 LSRPOOLID attribute. If you also specify LSRPOOLID(NONE), the access
mode is NSR; if LSRPOOLID(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 LSRPOOLID 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.
Table 1. Effects of RLSACCESS(YES) on other FILE attributesAttribute |
Effect of RLSACCESS(YES) |
PASSWORD |
Ignored. |
LSRPOOLID |
Ignored. |
DSNSHARING |
Ignored. |
STRINGS |
Ignored; RLS access-mode files always have 1024 strings. |
REMOTESYSTEM
REMOTENAME
RECORDSIZE
KEYLENGTH
|
The meanings of these attributes are unchanged. However,
dual FILE definitions of local and remote is of less value for RLS access-mode
files. With RLS, there may be many file-owning regions (FORs) instead of
one, and a local CICS region may have the choice of several FORs. |
DATABUFFERS
INDEXBUFFERS
|
Ignored. |
TABLE |
TABLE(CICS) is not allowed; an error message is issued
if specified. TABLE(USER) or TABLE(CF) is allowed. The source data set (if
there is one) is accessed in RLS mode to load the data table, after which
requests access the data table directly using data table services. |
RECOVERY |
Ignored. The recovery attribute is obtained from the
ICF catalog for an RLS file. |
FWDRCOVLOG |
Ignored. The forward recovery log stream name is obtained
from the ICF catalog for an RLS file. |
BACKUPTYPE |
Ignored. The type of backup is determined by the DFSMSdss backup
utility for RLS. |
Note: - As long as a file is opened in RLS mode, any values specified for PASSWORD,
LSRPOOLID, DSNSHARING, STRINGS, DATABUFFERS, and INDEXBUFFERS are ignored,
as described in Table 1. However,
if you use a CEMT, or EXEC CICS, SET FILE command to change the value of RLSACCESS
from YES to NO, these values are no longer ignored, and CICS uses them when
the file is closed and re-opened in non-RLS mode.
- CICS always takes the RLS access mode from the file resource definition
and you cannot override this using the RLS=NRI or RLS=CR parameter on a DD
statement.
- STATUS({ENABLED|DISABLED|UNENABLED})
- specifies the initial status of the file following a CICS initialization
with START=COLD or START=INITIAL. You can change the status of a closed file
with the master terminal transaction CEMT. The status of a file (enabled,
disabled, or unenabled) following a CICS restart is recovered to its status
at the previous shutdown.
- 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.
- STRINGS({1|value})
- specifies the number, in the range 1 through 255, of concurrent requests
that can be processed against the file. When the number of requests reaches
this value, CICS queues any additional requests until one of the active requests
terminates. This applies both to files using shared resources, and to those
not using shared resources. Note that if the file definition specifies RLSACCESS(YES),
the strings is ignored; you always get 1024 strings with RLS mode access.
For files using
local shared resources, this number is not used by VSAM. It is used by CICS,
not only as described above, but also to calculate the default value in the
buffer pool definition.
Notes: - When choosing a STRINGS value, be aware that a proportion (20%) of the
specified number of strings is reserved by CICS for use in read-only requests
- When choosing a STRINGS value for an ESDS, consider the following:
- If an ESDS is used as an 'add-only' file (that is, it is used only in
write mode), a string number of 1 is strongly recommended. Any string number
greater than 1 can significantly affect performance, because of exclusive
control conflicts that occur when more than one task attempts to write to
the ESDS at the same time.
- If an ESDS is used for both writing and reading, with writing being 80%
of the activity, it is better to define two file definitions—using one file
for writing and the other for reading.
- For user-maintained data tables and coupling facility data tables, the
STRINGS value does not limit the number of concurrent requests against
the table. However, the value does limit the number of concurrent requests
during the loading of a user-maintained table.
For CICS-maintained data tables, the STRINGS value limits the
number of concurrent requests to update the table. It does not limit the number
of concurrent read-only requests.
- TABLE({NO|CICS|USER|CF})
- specifies the type of data table that you require.
- 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 or not 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 on how to start a coupling facility data table
server, see CICS System
Definition Guide.
- 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:
- LSRPOOLID with a value of 1 through 8
- 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:
- LSRPOOLID with a value of 1 through 8
- RECORDFORMAT as VARIABLE (or let this default to VARIABLE)
- MAXNUMRECS with the value you require.
- TABLENAME(cfdt)
- specifies the name of the coupling facility data table that is accessed
through this file definition. The name can be up to 8 characters in length.
Acceptable characters:A-Z 0-9 $ @ #
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
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 subsequently alter
the file definition to reference a coupling facility data table, the TABLENAME
attribute comes into effect.
- UPDATE({NO|YES})
- specifies whether records on this file can be updated.
- UPDATEMODEL({LOCKING|CONTENTION})
- specifies the type of update model to be used for a coupling facility
data table.
- 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
(at syncpoint, or by a REWRITE, DELETE, or UNLOCK command for non-recoverable
tables) LOCKING is the default for a file that specifies TABLE(CF). With the
LOCKING model, the CFDT can be defined as:
- Non-recoverable, 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 very similar to
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 non-recoverable
(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 subsequently alter
the file definition to reference a coupling facility data table, the UPDATEMODEL
attribute comes into effect.