DFHFCFS (file control file state program)
Call mechanism
Kernel subroutine call. Automatic stack storage acquired as part of the call.
Entry address
DFHFCFS. The entry point address is held in FC static storage in a field named FC_FCFS_ADDRESS, which is set by DFHFCRP when it loads DFHFCFS.
Purpose
The file control file state program is part of the file control component.
The program processes requests to enable, disable, open, and close files. Such requests can originate from explicit requests (either CEMT or EXEC CICS SET), from implicit requests (such as implicit open), or from requests made from CICS internal processing.
Close and disable requests are processed in different ways, depending on whether the request has been issued with the WAIT or the NOWAIT option. A request with the WAIT option is treated as a synchronous request, that is, control returns to the requesting program only after all users of the file have completed their use.
A request with the NOWAIT option is treated as an asynchronous request. In this case, the file is marked with the intended state and control is returned immediately.
Called by
- DFHAMFC
- Enable a newly installed file
- DFHDMPCA
- Change the state of the CSD
- DFHDMRM
- Close CSD after an error
- DFHDTLX
- Close the data set associated with a shared data table
- DFHEIQDS
- Implement CEMT and EXEC CICS requests
- DFHFCDL
- Close the data set associated with a coupling facility data table
- DFHFCDTS
- Close shared data table if remote connection disabled or invalidated
- DFHFCFR
- Implicit open
- DFHFCQU
- Close files for quiesce, cancel close for unquiesce, enable files
- DFHFCRC
- Open files which need backout, and close files at syncpoint
- DFHFCRD
- Immediate close of RLS files
- DFHFCRV
- Close files for pending immediate close requests
- DFHFCSD
- Close files on a normal CICS shutdown
- DFHFCU
- Open all files with FILSTAT=OPEN coded
- DFHFCVS
- Open the base, and during empty file or I/O error processing.
Inputs
The FCFS parameter list, as defined by the DFHFCFSA DSECT, is created as part of the subroutine call.
Request identifier (open, close, enable, disable, cancel close)
FCTE address
FCTE token
Open options (open base, open for backout)
Close qualifier (close pending, shutdown, immediate close,
quiesce, and so on)
Action (wait, do not wait, force)
Outputs
DFHFCN return code
Register 15 return code
VSAM return code
Operation
- Enable file.
DFHFCFS marks the FCT entry as ‘enabled’, and catalogs the change.
- Disable file.
If the WAIT option is specified, DFHFCFS tests whether the transaction issuing the request is a current user of the file. If it is, DFHFCFS returns an exception response.
DFHFCFS next marks the FCT entry entry as ‘disabled’ and catalogs the change. If the disable request stems from a close request (see later), DFHFCFS also sets the implicit indicator, thereby marking the state as ‘unenabled’. However, if this close request originated from DFHFCSD as part of CICS shutdown processing, DFHFCFS does not mark the state as ‘unenabled’.
Finally, if the WAIT option is specified, the FCT entry is unlocked before waiting for the ‘disabled’ ECB in the FCT entry to be posted by the transaction that reduces the use count to zero.
- Open file.
If the file is unenabled (due to a previous close), DFHFCFS enables it and catalogs the new state, unless the open option is open for backout.
If the file refers to a BDAM data set, DFHFCFS tests whether DFHFCBD is already loaded; if not, it calls loader domain to do so.
If the file is a data table, DFHFCFS loads and initializes data table services, if this has not been done already on a previous open request.
DFHFCFS next calls DFHFCN (for non-RLS) or DFHFCRO (for RLS) to perform the physical open. After the file has been successfully opened, its FCT entry is marked accordingly.
For a data table, DFHFCFS issues OPEN and LOAD requests to data table services.
- Close file.
If there is no close qualifier, the file is first implicitly disabled (as described earlier), taking into account the WAIT or NOWAIT option. The new state is cataloged.
If the file use count is zero, DFHFCFS calls DFHFCN or DFHFCRO to perform the physical close. After the file has been successfully closed, its FCT entry is marked accordingly.
An immediate close is issued if the SMSVSAM RLS server fails. The close must wait until there are no requests active in the RLS record management processor. The enablement state of the file is not changed. A close with close qualifier of quiesce is issued to process an RLS quiesce request. The file is unenabled, and the state catalogued.
For a data table, DFHFCFS issues a CLOSE request to data table services, except in the case of a special type of CLOSE request issued by DFHFCVS for a user-maintained data table, when loading is complete and the source data set is to be closed, but not the table itself.
For a remote data table, DFHFCFS issues a DISCONNECT request to data table services.
If the file use count is nonzero, DFHFCFS sets the ‘close requested’ indicator in the FCT and returns to the caller. Any subsequent transaction that reduces the use count to zero tests the ‘close requested’ indicator and, if set, performs the actual close.
When called by DFHFCSD during CICS shutdown, DFHFCFS ensures that files are closed, marks the file as ‘closed unenabled’ in the FCT, but does not record this change in the global catalog. This allows implicit file opens on a subsequent restart.
- Cancel close.
An in-progress close is cancelled if a data set is unquiesced. The close_in_progress flag is reset, any tasks waiting for the file to close are resumed, and the file is re-enabled.
How loaded
By DFHFCRP as part of file control initialization.