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.

The input parameters are:

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

Returned in the FCFS parameter list:

DFHFCN return code
Register 15 return code
VSAM return code

Operation

Before any processing to change the state of a file is carried out, its FCT entry is locked by means of a DFHKC ENQ call. At the conclusion of file state change processing, the FCT entry is unlocked before returning to the caller.
  • 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.



dfhs3fc.html | Timestamp icon Last updated: Monday, 5 June 2017