DFHFCN (file control open/close program)
Call mechanism
BALR, obtaining LIFO storage on entry.
Entry address
DFHFCNNA. DFHFCN is link-edited with DFHFCFS. All calls to DFHFCN are made from DFHFCFS; the entry point address is known to DFHFCFS from the link-edit.
Purpose
The file control open/close program is part of the file control component.
This program performs the physical opening and closing of files by making the corresponding requests to VSAM or BDAM. Associated with these operations are a number of further activities that must be completed before control is returned to DFHFCFS.
- Dynamic allocation of the file
- Empty file checking
- Dynamically setting up ACB fields in advance of the VSAM open
- Copying into file-control control blocks VSAM information about the file that is available after the open
- Inquiring on, and updating, the VSAM data set's backup while open (BWO) attributes in the ICF catalog for a file that is defined as eligible for BWO support if the appropriate prerequisite software levels have been installed
- On close, deallocating the file if necessary and clearing the file control information related to the file
- Resetting a VSAM data set's BWO attributes in the ICF catalog during close processing.
Called by
DFHFCFS, exclusively.
Inputs
The FCSPARMS parameter list, created in DFHFCFS’s automatic storage and addressed by register 1 on the call.
FCTE address
Request identifier
Outputs
DFHFCN return code
Register 15 return code
VSAM return code
Base data set name
Recovery attributes of base
Operation
Execution of the DFHFCN code is serialized. This is done by DFHFCFS issuing a DFHKC ENQ before calling DFHFCN, and a DFHKC DEQ after calling DFHFCN. As a consequence, only a single open or close request to any file can be in progress at any time, and multiple concurrent requests are single-threaded.
- The main actions when processing an open request are as follows:
- If the file is being opened for update and any type of autojournalling is specified on the file definition, then the autojournal log stream is opened, via a call to DFHLGGL.
- The file is tested to determine if it is allocated to the job
by means of a JCL statement or is to be allocated dynamically.
If the file is already allocated, any existing DSN block to which it may be connected is disconnected and a new block with the actual DSNAME is connected. Connecting and disconnecting of DSNAME blocks is always performed by calling DFHFCDN.
If the file is not already allocated, it is at this point dynamically allocated to the DSNAME in the DSNAME block to which it is connected.
In the case of a VSAM file, the file's data set name is used to issue appropriate SHOWCAT and LOCATE instructions to determine relevant information from the VSAM catalog about the data set that the file represents. In particular, the following are obtained:Base/path indicator
Base data set name
Attributes of the data set
Key length of the base
Relative key position of base key
Maximum record length
Control interval size
Share options
High RBA - The data set is checked to determine if it is empty (high RBA
is zero) or is to be emptied.
The ‘load' mode indicator is set on.
- DFHFCDN is now called to connect the FCT entry to a DSNAME block
for the base cluster (which may be the existing allocation DSNAME
block, or may need to be newly created, or may already exist and need
only be pointed to from the FCT). The base cluster's attributes,
as obtained from the VSAM catalog, are stored in the base cluster
block.
The file's recovery characteristics are checked against any that may already have been stored in the base cluster block and, if they have not yet been set up, are saved there. Any conflict with the stored values is handled. In some cases the new value overrides the old one, in others an error is returned.
During this processing, if this is the first open for update for a file associated with this particular data set:- a call is made to the VSAM callable interface IGWARLS, in order to get any recovery attributes that may be defined in the VSAM catalog. If they are present, then they override any values in the FCT entry.
- if forward recovery logging is specified, the forward recovery log stream is opened, using either the log stream name from the VSAM catalog, or a log stream name derived from the id specified in the file definition.
In the case of an entry sequenced data set or a path to an ESDS, the next available RBA in the data set is determined and stored in the base cluster block.
- If the file uses a shared resources (LSR) pool, and if the pool is not currently in existence, DFHFCL is called to determine the pool's characteristics and to build it.
- Before opening a VSAM file, any STRNO, BUFND, or BUFNI parameters that may have been specified in the JCL DD statement are copied to the FCT entry (for LSR opens, these are ignored). The ACB is now created and its various options and parameters filled in from information in the FCT entry. The OPEN is finally completed by a call to VSAM.
- If the file refers to a BDAM data set, the assembled DCB is used for the open request and no dynamic setting of DCB options is carried out.
- After the VSAM file has been successfully opened, certain file
attributes are obtained from VSAM and are stored in the FCT entry.
These include:
Key length
Relative key position
Base/path/AIX indicator
KSDS/ESDS/RRDS/VRRDS indicator
Number of strings required for an update operation. - For a file opened for update against a VSAM base data set when
the update use count in the DSNB for this data set is zero, the BWO
attributes in the ICF catalog are validated to find their current
state. This is done by making an INQ_DATASET_STATE call to DFHFCAT,
regardless of whether the file is defined to CICS as eligible for
BWO support. The file open request is rejected if one of the following is true:
- The BWO attributes in the ICF catalog show either that the data set is “back level”, that is, a backup copy has been restored but not forward recovered, or that either the catalog or the data set has been corrupted.
- The BWO attributes in the FCT entry conflict with those defined in the DSNB, that is, the file has already been opened with different attributes since the DSNB was created.
If the file is defined to CICS as eligible for BWO support, the BWO attributes in the ICF catalog are updated by making a SET_BWO_BITS_ENABLED call to DFHFCAT.
However, if the file is not defined to CICS as eligible for BWO support, but the BWO attributes in the ICF catalog currently show that the VSAM base data set is eligible for BWO support, the BWO attributes in the ICF catalog are disabled by making a SET_BWO_BITS_DISABLED call to DFHFCAT, and CICS issues a warning message.
Note: The ICF BWO attributes are a property of a VSAM sphere; therefore, the VSAM base data set and alternate index path definitions should be consistent. For a general description of the CICS backup while open (BWO) facility, see Troubleshooting for recovery processing. - The base DSNB, and path DSNB if this is a path, are marked as validated and catalogued.
- The main actions when processing a close request are as follows:
- If the close request is for the last file that was opened for update against a VSAM base data set and the file is defined to CICS as eligible for BWO support, the BWO attributes in the ICF catalog are reset so that BWO support is no longer enabled. This is done by making a SET_BWO_BITS_DISABLED call to DFHFCAT.
- Before performing the access method close for a VSAM file, the number of accumulated EXCPs is obtained by making a call to VSAM and is saved in the FCT entry ready to be sent to the statistics domain as part of the file statistics.
- A CLOSE request is then made by issuing the appropriate (VSAM or BDAM) macro.
- The ACB storage is freed, and certain fields in the FCT entry which are no longer valid are cleared.
- File statistics and data table statistics, if any, are sent to the statistics domain as unsolicited data.
- If the file being closed uses shared resources, and if it is the last to have been closed in its LSR pool, DFHFCL is called to delete the pool.
- If the file was dynamically allocated at open time, it is deallocated, leaving a pointer to the DSNAME block in the FCT entry.
- If the file had an autojournal, then the autojournal log stream is closed.
- If the base data set was forward recoverable, and its use count is non-zero, then the forward recovery log stream is closed.
How loaded
As a constituent part of DFHFCFS, which is loaded by DFHFCRP as part of file control initialization.