The DFHFCT TYPE=FILE macro describes to CICS® file control the physical and operational
characteristics of a BDAM file. This macro includes operands that provide
information about the access method, record characteristics, and types of
service allowed for the file. This information is used to generate control
information used by CICS as well as a DCB
.

>>-DFHFCT--TYPE=FILE--,ACCMETH=BDAM--,FILE=name----------------->
>--+-----------------+--+--------------+------------------------>
'-,DISP=--+-OLD-+-' '-,DSNAME=name-'
'-SHR-'
>--+---------------------------------------+-------------------->
| .-ENABLED---. .-,CLOSED-. |
'-,FILSTAT=--+-----------+--+---------+-'
+-DISABLED--+ '-,OPENED-'
'-UNENABLED-'
>--+-------------------+---------------------------------------->
| .-NO-----. |
'-,JID=--+--------+-'
'-number-'
>--+---------------------------------------------+-------------->
| .-,LOG=NO--. |
'-,JREQ=--+-ALL---------------+--+----------+-'
| .-,-------. | '-,LOG=YES-'
| V | |
'-(----request-+--)-'
>--+-----------------------------------------------------------+-->
'-,RECFORM=--+-----------+--+------------+--+-------------+-'
+-UNDEFINED-+ +-,BLOCKED---+ '-,DCB-format-'
+-VARIABLE--+ '-,UNBLOCKED-'
'-FIXED-----'
>--+------------------------------+--+-----------------+-------->
| .-,-------. | '-,BLKKEYL=length-'
| V | |
'-,SERVREQ=--(----request-+--)-'
>--+--------------------------------+--+----------------+------->
'-,BLKSIZE=(length--+----------+-' '-,KEYLEN=length-'
'-,length)-'
>--+---------------+--+--------------------+--+-------------+--->
'-,LRECL=length-' '-,RELTYPE=--+-BLK-+-' '-,RKP=number-'
+-DEC-+
'-HEX-'
>--+---------------+--+-------------+--------------------------><
'-,SRCHM=number-' '-,VERIFY=YES-'
- TYPE=FILE
- Indicates that this macro describes the characteristics of a file.
- ACCMETH=BDAM
- specifies the basic direct access method of the data set is allocated
to the file.
- BLKKEYL=length
- Code this with a decimal value from 1 through 255, which represents
the length in bytes of the physical key in the BDAM physical record. You must
code this operand only for files that reference data sets with physical keys
(that is, those with SERVREQ=KEY specified). If a data set contains blocked
records, and deblocking is to be performed by using a logical key (that is,
a key embedded within each logical record), the logical key length must be
specified by using the KEYLEN operand.
If necessary, CICS can place a record
under exclusive control by building an ENQ argument by concatenating the data
set name, the block reference, and the physical key. An ENQ is issued using
a maximum of 255 bytes of this argument. If the argument exceeds 255 bytes
in length, the ENQ places a range of keys under exclusive control.
- BLKSIZE=(length[,length])
- Code this with the length of the block, in bytes. The way you calculate
the BLKSIZE depends on the RECFORM. For UNDEFINED or VARIABLE blocks, the
length must be the maximum block length. For FIXED length blocks, you calculate
the BLKSIZE as follows:
BLKSIZE = LRECL for unblocked records.
BLKSIZE = (LRECL x blocking factor) for blocked records.
If you wish to have a BLKSIZE value generated in the DCB, you must
specify that value in the second parameter of the operand; for example, BLKSIZE=(250,250),
where the first 250 relates to the FCT and the second 250 relates to the DCB.
If the second parameter is not coded, the DCB is generated without a BLKSIZE
value.
Note: - CICS assumes that the block size of the BDAM data set is the size you
have specified on the first BLKSIZE parameter. If the value specified is smaller
than the actual block size of the data set, you will probably get storage
violations or other unpredictable results when using the file.
- If you specify the second parameter (the DCB value) the value that you
code must always be the actual block size. We recommend that you either omit
the second parameter, or make it equal to the first parameter.
- DISP={OLD∨SHR}
- Code this to specify the disposition of the data set which will be allocated
to this file. 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 disposition.
If a JCL statement does exist, it will take precedence over this disposition.
- OLD
- The disposition of the data set is set to OLD if dynamic allocation
is performed.
- SHR
- The disposition of the data set is set to SHR if dynamic allocation
is performed.
Note: You must specify the disposition of the data set, either
with the DISP operand, or:
- In a JCL statement
- With CEMT SET
- With EXEC CICS SET
If you specify the disposition in a JCL statement, specify the data
set name in the JCL statement as well.
- DSNAME=name
- Code from 1 to 44 characters to specify the JCL data set name (DSNAME)
to be used for this file. If no JCL statement exists for this file when it
is opened, the open will be preceded by a dynamic allocation of the file using
this DSNAME. If a JCL statement does exist, it will take precedence over this
DSNAME.
You must specify the data set name, either with the DSNAME operand,
or:
- In a JCL statement
- With CEMT SET
- With EXEC CICS SET
If you specify the data set in a JCL statement, you must specify the disposition in the JCL statement as well.
Note: You define the CICS system definition (CSD) file by system initialization parameters, not
in the FCT.
- FILE=name
- Code this with a 1-to 8-character symbolic name by which this FCT entry
is to be identified. This name is known as the file name and is used by CICS or by CICS application programs to refer to the
data set with which this FCT entry has been associated.
As well as identifying the FCT entry, this name is also used as the DDNAME
when the associated data set is allocated to CICS. The allocation is achieved
either by using JCL statements in the start-up job stream, or dynamically,
by using the DSNAME and DISP values in the FCT.
Do not use file names
that start with the character string DFH for your own files, because CICS
reserves the right to use any file name beginning with DFH. In addition, using
the character string FCT for a file name prefix can cause assembly errors.
- FILSTAT=({ENABLED∨DISABLED∨UNENABLED},{OPENED∨CLOSED})
- Code this to specify the initial status of the file.
The first operand
determines the initial enablement state of the file. It is used only during
an initial or a cold start. (On a warm or emergency start, the file state
is determined by the state at the time of the previous shutdown.)
The
second operand specifies whether an attempt is made to open the file at the
end of CICS initialization. It applies to initial, cold, warm, and emergency
starts.
- ENABLED
- Normal processing is to be allowed against this file.
- DISABLED
- Any request against this file from an application program causes the
DISABLED condition to be passed to the program.
- UNENABLED
- This option is valid only with the CLOSED option. It may be used to
prevent the file being opened on first reference. An attempt to access the
file in this state raises the NOTOPEN condition.
- OPENED
- The file is opened by an automatically initiated CICS transaction (CSFU)
after CICS initialization. (On
a warm or emergency start, a file remains UNENABLED, if that was its state
at the time of the previous shutdown. CSFU ignores an OPENED option on an
UNENABLED file, and leaves the file closed.)
- CLOSED
- The file is to remain closed until a request is made to open it by the
master terminal function, by an EXEC CICS SET command, or by an implicit open.
For each combination of initial states, files are opened as follows:
- (ENABLED,CLOSED)
- The file is opened on first reference. This is the default.
- (ENABLED,OPENED)
- The file is opened by the automatically-initiated transaction CSFU after
CICS initialization, unless a user application or master terminal function
has opened it first.
- (DISABLED,CLOSED)
- The file is opened only by an explicit OPEN request (for example, from
the master terminal transaction).
- (DISABLED,OPENED)
- The file is opened by the automatically-initiated transaction CSFU after
CICS initialization, unless a user application or master terminal function
has explicitly opened it first.
- (UNENABLED,CLOSED)
- The file is opened only by an explicit OPEN request. The file state
after it has been opened is (ENABLED,OPENED).
Note: For performance reasons, the default CSD file entry
for transaction CSFU is defined with DTIMOUT=10 (seconds). This can cause
a transaction timeout abend if there is a delay in opening a file during CICS
startup. See
TRANSACTION definition attributes for an explanation of the DTIMOUT value
on TRANSACTION definitions.
- JID={NO∨number}
- Code this if automatic journal activity is to take place for this FCT
entry, and to identify the journal to be used to record the journaled data.
The operations that cause data records to be journaled are specified in the
JREQ parameter.
- NO
- No automatic journaling activity for this file is to take place.
- number
- The journal identifier to be used for automatic journaling. This may
be any number in the range 01 through 99. The number is appended to the letters
DFHJ to give a journal name of the form DFHJnn, which maps to an MVS™ system
logger general log stream.
Note: Automatic journaling can be specified if you wish
to record file activity for subsequent processing by yourself (for example,
user-written data set I/O recovery). It must not be confused with automatic
logging (specified with LOG=YES), which is required if CICS is to perform
data set backout to remove in-flight task activity during emergency restart
or dynamic transaction backout.
- JREQ={ALL∨(request[,request,...])}
- Code this with the file operations that are to be automatically journaled,
and whether the journaling operation is to be synchronous or asynchronous with file activity.
When a
synchronous journal operation is executed for a READ request, control is not
returned to the program that issued the file control request until the data
read is written in the journal data set. When a synchronous journal operation
is executed for a WRITE request, the output operation to the data set is not
initiated until the data is written in the journal data set.
When an
asynchronous journal operation is executed for a READ request, control can
be returned as soon as the data read is moved to the journal I/O buffer. When
an asynchronous journal operation is executed for a WRITE request, the output
operation to the data set can be initiated as soon as the data is moved to
the journal I/O buffer.
Synchronization defaults provide asynchronous
operation for READs and synchronous operation for WRITEs.
If you have
requested automatic journaling, the contents of the journal may not accurately
reflect the actual changes to a data set, because the request is journaled
before the response from the I/O operation is tested.
If this operand
is omitted and JID is coded, JREQ defaults to JREQ=(WU,WN).
Here are
the possible values for
request:
- ALL
- Journal all file activity with READ asynchronous and WRITE synchronous.
- ASY
- Asynchronous journal operation for WRITE operations.
- RO
- Journal READ ONLY operations.
- RU
- Journal READ UPDATE operations.
- SYN
- Synchronous journal operation for READ operations.
- WN
- Journal WRITE NEW operations.
- WU
- Journal WRITE UPDATE operations.
- KEYLEN=length
- Code this with the length of the logical key for the deblocking of the
BDAM data set to which this file refers.
The logical key for BDAM data
sets is embedded and located through the use of the RKP operand. The length
of the physical key is coded in the BLKKEYL operand, and can be different
from the value specified for KEYLEN.
This operand must always be coded
when logical keys are used in blocked BDAM data sets.
- LOG={NO∨YES}
- This operand specifies the recovery attributes of the file. Specify
LOG=YES if you want automatic logging. This enables backout (recovery) of
incomplete changes to the data set referenced by this file, in the event of
an emergency restart or transaction abend. Whenever a change—update,
deletion, or addition—is made to the data set, the “before” image
is automatically recorded in the CICS system log. (Automatic logging should
not be confused with automatic journaling.)
- NO
- Automatic logging is not to be performed.
- YES
- Automatic logging is to be performed.
When a request is made to change
the contents of the data set referenced by the file, the record being updated,
added, or deleted is enqueued upon, using the record identification together
with the address of the CICS control block representing the base data set.
This enqueue is maintained until the task terminates or the application issues
a syncpoint request to signal the end of a logical unit of work. This ensures
the integrity of the altered data.
Because the enqueues are thus maintained
for a longer period of time, an enqueue lockout can occur if an application
program that accesses this data set performs what is effectively more than
one logical unit of work against it, without defining each separate logical
unit of work to CICS by issuing a syncpoint request. Also, long-running tasks
could tie up storage resources.
- LRECL=length
- Code this with the maximum length (in bytes) of the logical record.
The value specified is also the length of records in a fixed length remote
file. See the DFHFCT TYPE=REMOTE macro for further information on remote files.
- RECFORM=([{UNDEFINED∨VARIABLE∨FIXED}], [{BLOCKED∨UNBLOCKED}],[DCB
format])
- Code this to describe the format of physical records in the data set.
For BDAM data sets, blocking refers to CICS blocking,
and has no meaning for BDAM. You must specify BLOCKED or UNBLOCKED for all
data sets of FIXED or VARIABLE format.
- BLOCKED
- Specify this option when each physical record is to be viewed by CICS
as a block consisting of more than one logical record.
- DCB
- Code this with the record format to be inserted in the DCB; for example,
RECFORM=(FIXED,BLOCKED,FBS).
The DCB format sub-parameter of the RECFORM
operand is the only way you can put record format information into the DCB when
the FCT is assembled. The first two sub-parameters of the RECFORM operand
do not generate information in the DCB.
- FIXED
- Records are fixed length.
- UNBLOCKED
- Specify this option when no CICS block structure is to be used. That
is, when there is one CICS logical record for each BDAM physical record.
- UNDEFINED
- Records are of undefined length. (If you specify a data set as UNDEFINED,
allow for an additional 8 bytes for the count field, when calculating the
BLKSIZE.)
- VARIABLE
- Records are variable length.
- RELTYPE={BLK∨DEC∨HEX}
- Code this if relative addressing is being used in the block reference
portion of the record identification field of the BDAM data set referenced
by this file. If the RELTYPE operand is omitted, absolute addressing is assumed
(that is, MBBCCHHR).
- BLK
- Relative block addressing is being used.
- DEC
- The zoned decimal format is being used.
- HEX
- The hexadecimal relative track and record format is being used.
- RKP=number
- Code this with the starting position of the key field in the record
relative to the beginning of the
record. With variable-length records, this operand must include space for
the 4-byte LLbb field at the beginning of each logical record. This operand
must always be coded for data sets that have keys within each logical record,
or when browsing.
- SERVREQ=(request[,request],...)
- Code this to define the types of service request that can be processed
against the file. The parameters that can be included are as follows:
- ADD
- Records can be added to the file.
- BROWSE
- Records may be sequentially retrieved from the file.
- KEY
- Records can be retrieved from or added to the file. This parameter is
mandatory if the data set referenced by the file is a keyed BDAM data set.
It must not be coded for other files.
- NOEXCTL
- Records are not to be placed under exclusive control when a read for
update is requested.
If you do not specify NOEXCTL, BDAM exclusive control
is provided by default. This provides integrity in the system. For BDAM, you
may specify LOG=YES with SERVREQ=NOEXCTL. This requests only a CICS enqueue
and suppress the BDAM exclusive control, thus providing CICS integrity for
the update only until a syncpoint.
Note: The CICS enqueue is
at the record level within the CICS region, and lasts until a syncpoint, whereas
the BDAM exclusive control operates on a physical block, is system-wide, and
lasts only until the update is complete.
- READ
- Records in this file can be read. READ is assumed, if you specify BROWSE
or UPDATE.
- UPDATE
- Records in this file can be changed.
- SRCHM=number
- Code this if multiple track search for keyed records is to be provided.
This operand is applicable only to BDAM keyed data sets.
- number
- The number of tracks or blocks to be searched. The default is 0.
- VERIFY=YES
- Code this if you want to check the parity of disk records after they
are written. If this operand is omitted, records are not verified after a
write request.