Local files—DFHFCT TYPE=FILE

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 .
Read syntax diagramSkip visual syntax diagram
>>-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:
  1. 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.
  2. 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.