Modules

This Topic describes the following modules. Unless otherwise stated, addressing mode and residency mode are AMODE 31 and RMODE ANY respectively.

Module Function See topic
DFHEIFC File control EXEC interface module DFHEIFC (file control EXEC interface module)
DFHEIQCF Exec INQUIRE CFDTPOOL module -
DFHFCAT File control catalog manager DFHFCAT (file control catalog manager)
DFHFCBD File control BDAM request processor DFHFCBD (file control BDAM request processor)
DFHFCCA File control RLS control ACB manager DFHFCCA (file control RLS control ACB manager)
DFHFCDL File control coupling facility data table load program DFHFCDL (file control CFDT load program)
DFHFCDN File control DSNAME block manager DFHFCDN (file control DSN block manager)
DFHFCDO File control coupling facility data table open/close program DFHFCDO (file control CFDT open/close program)
DFHFCDR File control coupling facility data table request processor DFHFCDR (file control CFDT request processor)
DFHFCDTS File control shared data table request processor DFHFCDTS (file control shared data table request program)
DFHFCDTX File control shared data table function ship program DFHFCDTX (file control shared data table function ship program)
DFHFCDU File control coupling facility data table UOW calls program DFHFCDU (file control CFDT UOW calls program)
DFHFCDW File control coupling facility data table RMC program DFHFCDW (file control CFDT RMC program)
DFHFCDY File control coupling facility data table resynchronization program DFHFCDY (file control CFDT resynchronization program)
DFHFCES File control ENF servicer DFHFCES (file control ENF servicer)
DFHFCFL File control FRAB and FLAB processor DFHFCFL (file control FRAB and FLAB processor)
DFHFCFR File control file request handler DFHFCFR (file control file request handler)
DFHFCFS File control file state program DFHFCFS (file control file state program)
DFHFCIN1 File control initialization program 1 DFHFCIN1 (file control initialization program 1)
DFHFCIN2 File control initialization program 2 DFHFCIN2 (file control initialization program 2)
DFHFCIR File control initialize recovery DFHFCIR (file control initialize recovery)
DFHFCL File control shared resources pool processor DFHFCL (file control shared resources pool processor)
DFHFCLF File control log failure handler DFHFCLF (file control log failures handler)
DFHFCLJ File control logging and journaling program DFHFCLJ (file control logging and journaling program
DFHFCMT File control table manager DFHFCMT (file control table manager)
DFHFCN File control open/close program DFHFCN (file control open/close program)
DFHFCNQ File control non-RLS lock handler DFHFCNQ (file control non-RLS lock handler)
DFHFCOR File control offsite recovery completion DFHFCOR (file control offsite recovery completion)
DFHFCQI File control RLS quiesce initiation DFHFCQI (file control RLS quiesce initiation)
DFHFCQR File control RLS quiesce receive transaction DFHFCQR (file control quiesce receive transaction)
DFHFCQS File control RLS quiesce send transaction DFHFCQS (file control RLS quiesce send transaction)
DFHFCQT File control RLS quiesce common system transaction DFHFCQT (file control RLS quiesce common system transaction)
DFHFCQU File control RLS quiesce processor DFHFCQU (file control RLS quiesce processor)
DFHFCQX File control RLS quiesce exit DFHFCQX (file control RLS quiesce exit)
DFHFCRC File control recovery control program DFHFCRC (file control recovery control program)
DFHFCRD File control RLS cleanup transaction DFHFCRD (file control RLS cleanup transaction)
DFHFCRF File control function shipping interface module DFHFCRF (file control function shipping interface module)
DFHFCRL File control share control block manager DFHFCRL (file control share control block manager)
DFHFCRO File control RLS open/close program DFHFCRO (file control RLS open/close program)
DFHFCRP File control restart program DFHFCRP (file control restart program)
DFHFCRR File control RLS restart DFHFCRR (file control RLS restart)
DFHFCRS File control RLS record management processor DFHFCRS (file control RLS record management processor)
DFHFCRV File control RLS VSAM interface processor DFHFCRV (file control RLS VSAM interface processor)
DFHFCSD File control shutdown program DFHFCSD (file control shutdown program)
DFHFCST File control statistics program DFHFCST (file control statistics program)
DFHFCVR File control VSAM interface program DFHFCVR (file control VSAM interface program)
DFHFCVS File control VSAM request processor DFHFCVS (file control VSAM request processor)

There are also a number of modules which make up the coupling facility data tables server. These all have names of the form DFHCFxx.

Figure 50 shows the main file control modules and their interfaces.

Figure 50. Main file control modules and their interfaces
 This is a diagram showing the main file control modules and their interfaces.

DFHEIFC (file control EXEC interface module)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHEIFC. Stored in the CSA in a field named CSAEIFC.

Purpose

DFHEIFC is DFHEIP’s file control interface. It routes requests to the file control file request handler, DFHFCFR.

Called by

DFHEIP exclusively.

Inputs

The EIEI parameter list, as defined by the DFHEIEIA DSECT.

Outputs

Updated EIEI parameter list, with completed EIB.

Operation

How loaded

At CICS® startup, as part of the building of the CICS nucleus. The nucleus is built by DFHSIB1, which uses its nucleus build list to determine the content and characteristics of the CICS nucleus.

DFHFCAT (file control catalog manager)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCAT. The entry point address is held in FC static storage in a field named FC_FCAT_ADDRESS, which is set by DFHFCRP when it loads DFHFCAT.

Purpose

The file control catalog manager is part of the file control component. This program processes inquire and update requests on the state of the backup while open (BWO) attributes in the ICF catalog for VSAM data sets and inquire on the quiesce state in the ICF catalog. The DFSMS Callable Services interface is used for these operations.

Called by

DFHFCDN
Get the base data set name for a DSNB that has not yet been validated, update the recovery point, or to set the BWO attributes to a ‘forward recovered’ state
DFHFCN
Inquire on the current state of, and to update, BWO attributes during file open processing; and to reset these attributes during file close processing.
DFHFCQI
Inquire on the quiesce state of a data set.

Inputs

The FCAT parameter list, as defined by the DFHFCATA DSECT, is created as part of the subroutine call.

The input parameters are:

Outputs

Returned in the FCAT parameter list:

Operation

DFHFCAT provides the following functions:

INQ_BASEDSNAME
Gets the base data set name for a specified data set name from the ICF catalog. This function is used when there is not a validated DSN block for the data set.
INQ_CATALOG_QUIESCESTATE
If the level of DFSMS is 1.3 or higher, issues an IGWARLS call to determine the quiesce state of the data set (quiesced or unquiesced).
INQ_DATASET_STATE
Determines the current state of a VSAM data set’s BWO attributes in the ICF catalog. If the BWO attributes indicate that the data set is "back level", that is, a backup copy has been restored but not forward recovered, an exception response is returned; otherwise, a state of ‘fuzzy’ or ‘sharp’ is returned, indicating whether or not the data set is defined in the ICF catalog as eligible for BWO.
SET_CATALOG_RECOVERED
Updates a VSAM data set’s BWO attributes in the ICF catalog to a ‘forward recovered’ state to indicate that the data set has been forward recovered.
SET_CATALOG_RECOV_POINT
Updates a VSAM data set’s BWO attributes in the ICF catalog with the new recovery point.
SET_BWO_BITS_DISABLED
Updates a VSAM data set’s BWO attributes in the ICF catalog to show that the data set is no longer eligible for BWO support, and updates the recovery point.
SET_BWO_BITS_ENABLED
Updates a VSAM data set’s BWO attributes in the ICF catalog to show that the data set is eligible for BWO support, and updates the recovery point.

How loaded

By DFHFCRP as part of file control initialization.

DFHFCBD (file control BDAM request processor)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCBD. The entry point address is held in FC static storage in a field named FC_BDAM_ENTRY_ADDRESS.

Addressing mode

AMODE 31.

Residency mode

RMODE 24.

Purpose

The BDAM request processor is part of the file control component. It processes access requests to BDAM files.

Called by

DFHFCFR, after having determined that the request is for a BDAM file.

Inputs

The FCFR parameter list, as defined by the DFHFCFRA DSECT. Also, the file control environment, including FC static storage and the FCT.

Outputs

Updated FCFR parameter list.

Operation

Acquires and releases FIOA storage as necessary. Implements BDAM exclusive control requests. Performs record-length and key-length checking. Calls BDAM to perform the I/O request.

Acquires storage, in the correct key subpool, for requests that specify SET.

How loaded

By DFHFCFS, by means of a loader domain call. DFHFCBD is not loaded unless DFHFCFS is called to open a BDAM file and, in doing so, it discovers that DFHFCBD is not yet in storage.

DFHFCCA (file control RLS control ACB manager)

DFHFCCA is the file control RLS control ACB manager. The RLS control ACB is a special ACB required when a commit protocol application such as CICS uses VSAM RLS. FCCA processes requests to register and unregister the control ACB, and all other file control requests to SMSVSAM that have to be made via the control ACB. These requests are:

DFHFCCA also includes the code for the RLSWAIT exit used by control ACB requests. Whenever CICS issues such a request, VSAM drives the RLSWAIT exit as soon as it is about to transfer control to the SMSVSAM address space. CICS is then able to drive the dispatcher and schedule other CICS tasks whilst the SMSVSAM address space is busy processing the request.

DFHFCDL (file control CFDT load program)

DFHFCDL is attached by DFHFCDO to load a load-capable coupling facility data tavle with records from a source data set.

DFHFCDN (file control DSN block manager)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCDN. The entry point address is held in FC static storage in a field named FC_FCDN_ADDRESS, which is set by DFHFCRP when it loads DFHFCDN.

Purpose

The DSNAME block manager is part of the file control component. This program is called to perform various operations on data set name blocks. These operations include connecting and disconnecting DSN blocks and FCT entries, setting their attributes, and deleting them when no longer required. The program also allows the caller to inspect a particular DSN block or browse a set of blocks. It can also be called to update the backup while open (BWO) attributes in the ICF catalog for VSAM data sets, and to set the quiesce state to normal in all DSN blocks. Finally it can be called to catalog the information in a DSN block to the CICS global catalog.

Called by

DFHAMFC
Connect a DSN block to a newly created FCT entry
DFHAMPFI
Connect the DSN block for the CSD to the associated FCT entry
DFHEIQDN
Connect, disconnect, delete, set attributes, browse, and inquire against DSN blocks in response to external requests; and to update the BWO attributes in the ICF catalog for a VSAM data set to a ‘forward recovered’ state
DFHEIQDS
Connect or disconnect DSN blocks and FCT entries in response to external requests
DFHFCLF
Set the availability attribute to unavailable after a forward recovery log stream failure
DFHFCMT
Disconnect the DSN block when deleting an FCT entry
DFHFCN
Connect or disconnect and to catalog a DSN block
DFHFCRC
Update the recovery point in the ICF catalog for all VSAM data sets that are open for update in non-RLS mode and defined as eligible for BWO support at keypoint time
DFHFCRD
To reset all quiesce states to normal after an SMSVSAM server failure
DFHFCRO
Connect or disconnect and to catalog a DSN block
DFHFCRP
Connect or reconnect DSN blocks during file control initialization or restart.

Inputs

The FCDN parameter list, as defined by the DFHFCDNA DSECT, is created as part of the subroutine call.

The input parameters include:

Outputs

Output parameters, as part of the FCDN parameter list. Apart from the response, all these are returned on the inquire or browse requests. The parameters include:

Access method
Base data set name
Availability status
DSNB type
File count
DSNB valid status
Lost locks status
Forward-recovery log stream name
Forward-recovery log ID
Recovery status
Response
Reason

Operation

How loaded

By DFHFCRP as part of file control initialization.

DFHFCDO (file control CFDT open/close program)

When called using the FCFS parameter list, DFHFCDO performs an equivalent function for coupling facility data table opens and closes as is performed by DFHFCN for non-RLS VSAM files.

When called using the FCDS parameter list, DFHFCDO performs statistics collection for coupling facility data tables, and disconnects from CFDT pools at shutdown.

DFHFCDR (file control CFDT request processor)

DFHFCDR performs an equivalent function for coupling facility data tables as is performed by DFHFCVS for non-RLS VSAM files, and uses the same interface.

DFHFCDTS (file control shared data table request program)

DFHFCDTS performs an equivalent function for CICS-maintained and user-maintained data tables as is performed by DFHFCVS for non-RLS VSAM files and uses the same interface.

DFHFCDTX (file control shared data table function ship program)

DFHFCDTX receives file requests from DFHFCDTS in FCFRR format, converts them into command level interface form and then calls ISP to function ship the request.

The response returned by ISP in the EIB is translated back into an FCFRR response and reason code.

DFHFCDU (file control CFDT UOW calls program)

DFHFCDU encapsulates the processing required to call the coupling facility data tables server for unit of work related operations, such as commit, backout, inquire. It is called via the FCDU parameter list by DFHFCDW and DFHFCDY.

DFHFCDW (file control CFDT RMC program)

DFHFCDW provides a recovery manager connector (RMC) between file control and the coupling facility data tables server, to support 2-phase commit and recovery for recoverable coupling facility data tables. It is called by the CICS Recovery Manager using the RMLK parameter list.

DFHFCDY (file control CFDT resynchronization program)

DFHFCDY performs resynchronization of coupling facility data table pools and links. It is called using the FCDY parameter list by DFHFCDO, DFHFCDR and DFHFCDU.

DFHFCES (file control ENF servicer)

DFHFCES is the file control ENF servicer. It is used to prompt dynamic restart of RLS file control when the SMSVSAM Server becomes available again after an earlier failure. DFHFCES is invoked whenever the MVS™ Event Notification Facility notifies CICS (via the CICS domain manager ENF support) that SMSVSAM is available.

DFHFCES establishes a transaction environment, and calls DFHFCRR to dynamically restart RLS.

DFHFCFL (file control FRAB and FLAB processor)

DFHFCFL is the File Control FRAB/FLAB processor. It contains a number of functions to process FLAB control blocks belonging to a particular base data set. It processes the functions of the FCFL interface.

The DSNB of the data set is not locked during the processing of the commands. As a FLAB exists, and hence an FCTE, the DSNB cannot be deleted, therefore there is no need to lock the DSNB.

DFHFCFR (file control file request handler)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCFR. Stored in the CSA in a field named CSAFCEP.

Purpose

The central module in the file control component.

Processes file control requests issued by DFHEIFC (requests from application programs), or from other CICS modules (internal CICS file control requests).

Receives and routes file control access-method dependent requests to one of the following:

Implements TEST_FILE_USER requests.

Routes RESTART_FILE_CONTROL requests to DFHFCVS and DFHFCRS during the file control initialization.

Frees buffers at the request of DFHAPSM when ‘short on storage’ has been detected.

Performs a CLEAR_ENVIRONMENT when requested by DFHERM, DFHAPLI or DFHUEH. This cleans up file control storage at the completion of a task-related user exit, a user-replaceable program, or a global user exit:

Called by

DFHAPLI
AP language interface program
DFHAPSM
AP domain storage notify gate
DFHDMPCA
CSD manager adapter
DFHDTLX
Shared data tables load program
DFHEIFC
File control EXEC interface module
DFHERM
Resource manager interface (RMI) module
DFHFCDL
Coupling facility data tables load program
DFHFCDTS
File control shared data table request processor
DFHFCFR
File control file request handler (a recursive call)
DFHFCRC
File control recovery control program
DFHFCRP
File control restart program
DFHUEH
AP user exit handler.

Inputs

The FCFR parameter list, as defined by the DFHFCFRA DSECT. Also the file control environment, including FC static storage and the FCT.

Outputs

Updated FCFR parameter list.

Operation

Selects on the request type, and passes control to the routine specific to that request.

Performs monitoring.

Obtains a FLAB and FRTE to represent this request, or scans the FLAB and FRTE chains to associate this request with a previous FRTE if required. Some checking for error situations is performed during the scan.

Performs file state checking to determine whether or not a (VSAM or BDAM) request to a file is able to proceed. If file is enabled but closed and is not a request to a remote file, opens it before carrying out the request.

Checks for "privileged" requests.

If the request is not remote, checks the "service request" attributes for the file to determine whether the request can proceed.

Checks the file’s access method (VSAM or BDAM as defined in the FCT). If BDAM, calls DFHFCBD to process the request. If VSAM and non-RLS, calls DFHFCVS to process the request. If VSAM and RLS, calls DFHFCRS to process the request. If a data table, calls DFHFCDTS for read requests against a CICS-maintained data table or any request against a user-maintained table, and calls DFHFCVS otherwise (that is, for update and browse requests against a CICS-maintained data table). If the file is remote, calls DFHFCRF to process the request.

On return, performs cleanup if required.

How loaded

By DFHSIB1 as part of the CICS nucleus.

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.

How loaded

By DFHFCRP as part of file control initialization.

DFHFCIN1 (file control initialization program 1)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCIN1. Stored in the CSA in a field named CSAFCXAD.

Purpose

The file control initialization program is part of the file control component. This program initializes file control and starts the file control restart task. It also waits for the restart task to complete, and returns the status of the completion to the caller.

Called by

DFHSII1, as part of CICS initialization.

Inputs

The FCIN parameter list, as defined by the DFHFCINA DSECT.

Outputs

Updated FCIN parameter list.

Operation

Initialize:

WAITINIT:

How loaded

Link-edited with DFHFCIN2 to form the DFHFCIN module, which is loaded by DFHSIB1 as part of the CICS nucleus.

DFHFCIN2 (file control initialization program 2)

Call mechanism

Attached by DFHFCIN1 as a separate CICS task. Given control by means of the DFHKC TYPE=ATTACH mechanism.

Entry address

DFHFCIN2. Because DFHFCIN2 is link-edited with DFHFCIN1, the entry address is known to DFHFCIN1 at the time the DFHKC TYPE=ATTACH is issued.

Purpose

The file control initialization program is part of the file control component. This program loads and calls the file control restart program (DFHFCRP), to perform file control restart as a separate task.

Called by

CICS task control, after being attached by DFHFCIN1.

Inputs

None.

Outputs

The initialized file control component. Addresses and indicators completed in file control static storage.

Operation

Calls loader domain to acquire (that is, to load) the DFHFCRP program. Stores the entry point address of the loaded module (which is also the load point) in DFHFCIN2’s automatic storage in a field named FCRP_ENTRY_ADDRESS.

If the ACQUIRE request failed, calls loader domain to define program and then retries the ACQUIRE request.

Calls DFHFCRP by means of a subroutine call via the kernel.

On successful completion, calls loader domain to release DFHFCRP. On both successful and unsuccessful completion, posts the ECBs FC_NON_RECOV_ALLOWED_ECB and FC_RECOV_ALLOWED_ECB. The success or otherwise of File Control restart is indicated by the flag FCSCMPLT in file control static storage.

On unsuccessful completion, posts the Restart Task ECB complete and returns.

How loaded

By DFHSIB1 as part of the CICS nucleus.

DFHFCIR (file control initialize recovery)

DFHFCIR is the File Control Initialize Recovery Module. It initializes the File Control environment in which recovery after a CICS failure is carried out.

DFHFCIR handles the delivery of recovery data by the CICS Recovery Manager during its scan of the system log at warm or emergency restart, and rebuilds the file control structures that represent units of work that were in-flight or shunted when CICS terminated.

During its log scan, Recovery Manager calls File Control's recovery gate, which invokes the module DFHFCRC. DFHFCRC passes the calls through to DFHFCIR via a kernel subroutine call. The calls are the RMDE functions START_DELIVERY, DELIVER_RECOVERY, DELIVER_FORGET and END_DELIVERY.

DFHFCL (file control shared resources pool processor)

Call mechanism

BALR, obtaining LIFO storage on entry.

Entry address

DFHFCLNA. DFHFCL is, together with DFHFCN and DFHFCM, link-edited with DFHFCFS. All calls to DFHFCL are made from DFHFCN; the entry point address is known to DFHFCN from the link edit.

Purpose

The shared resources pool processor is part of the file control component.

This program is called at file open time to create a specific local shared resources pool if it does not exist. It is also called to delete a specific pool when the last file to use the pool is being closed.

The size and characteristics of the pool being built are obtained either from information in the SHRCTL definition in the FCT or, if that information has not been provided, from the best information available to DFHFCL at the time of the open.

Called by

DFHFCL is called exclusively by DFHFCN.

Inputs

The FCLPARAM parameter list, created in DFHFCN’s automatic storage and addressed by register 1 on the call.

The input parameters are:

Request identifier (build, delete)
LSR pool number

Outputs

Returned in the FCLPARAM parameter list:

DFHFCL return code
BLDVRP/DLVRP return code
VSAM return code

Operation

If the request is for LSR pool creation, DFHFCL first checks whether the SHRCTL block includes specifications for the number of strings, maximum key length, and the number of virtual and hyperspace buffers of each of the eleven sizes in the pool. If these values are known, DFHFCL sets up the BLDVRP parameter list and creates the pool by issuing the BLDVRP macro.

If some or all of the pool characteristics are not specified in the SHRCTL definition, DFHFCL calculates the pool requirements from the information in the FCT and the VSAM catalog.

Each FCT entry is inspected to find whether it is to be included in the pool being built. If so, its DSNAME is determined and this is used to obtain data set characteristics from the VSAM catalog. The information required for the BLDVRP macro is accumulated in the SHRCTL block and the pool is built from these values.

If the request is for LSR pool deletion, DFHFCL first obtains the VSAM statistics for the pool and saves them in the SHRCTL block. These statistics are unobtainable after the pool has been deleted.

DFHFCL next deletes the specified pool by issuing a DLVRP macro.

Finally, DFHFCL sends pool statistics to the statistics domain as unsolicited data.

How loaded

As a constituent part of DFHFCFS, which is loaded by DFHFCRP as part of file control initialization.

DFHFCLF (file control log failures handler)

DFHFCLF provides control of long term logger failures for File Control. It is called in the event of a failure of a general log stream, which will be either the forward recovery log for a data set or the autojournal for a file.

The CICS Log Manager invokes DFHFCLF when an MVS log stream being used for forward recovery or file autojournalling suffers a long term failure. The call is made using the LGGL ERROR function.

When file control opens a forward recovery log stream or an autojournal, it will register this call back gate to the Log Manager by specifying FCLF as the file control error gate.

When called, DFHFCLF takes action to ensure that the log stream failure causes minimum damage. For a forward recovery log failure it closes all files open against the data set using that forward recovery log (across the sysplex for a data set accessed in RLS mode) and issues a message advising that a new backup copy should be taken. For an autojournal it closes the file using that autojournal and issues a warning message.

DFHFCLJ (file control logging and journaling program

DFHFCLJ is the file control logging and journaling program. It is called to perform logging for transaction backout and forward recovery, to write to journals for autojournal requests and to write to the log of logs.

Records are written to the system log using the RMRE APPEND function, and optionally forced using the RMRE FORCE function. Records are written to forward recovery logs and autojournals using the LGGL WRITE function, and to the log of logs using the LGGL WRITE_JNL function.

DFHFCMT (file control table manager)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCMT. The entry point address is held in FC static storage in a field named FC_FCMT_ADDRESS, which is set by DFHFCRP when it loads DFHFCMT.

Purpose

The file control table manager is part of the file control component. This program is called to add, delete, and set FCT entries, and to return attributes of an FCT entry (inquire).

Called by

DFHAMFC
Inquire on, add, or delete a newly created FCT entry to the system
DFHAMPFI
Add the entry in the FCT for the CSD to the system
DFHDMPCA
Inquire on and set the attributes of the FCT entry for the CSD
DFHEDFX
Inquire on the attributes of an FCT entry
DFHEIQDS
Inquire on or set the attributes of FCT entries, or delete an FCT entry.

Inputs

The FCMT parameter list, as defined by the DFHFCMTA assembler DSECT, is created as part of the subroutine call.

The input parameters are:

Common parameters:
    File name
    String number
    Journal ID
    Recovery characteristics
    Journaling characteristics
    Enablement status
    Open time
    Data set disposition
    Service request attributes
    Record format
    Number of data buffers
    Number of index buffers
    Whether to catalog the FCT entry

VSAM-specific parameters:
    VSAM password
    Empty status
    Data set name sharing
    LSR pool ID
    Base name
    Forward recovery log ID
    BWO eligibility
    RLS access mode
    Read integrity

BDAM-specific parameters:
    Exclusive control

Outputs

Output parameters, as part of the FCMT parameter list. Apart from the response, all these are returned on the inquire or browse requests. The output parameters are:

Common parameters:
    File type
    String number
    Record size
    Key length
    Key position
    Recovery characteristics
    Journaling characteristics
    Enablement status
    Open status
    Open time
    Data set type
    Data set disposition
    Data set name
    Base data set name
    Service request attributes
    Record format
    Block format
    Access method
    Remote name
    Remote system

VSAM-specific parameters:
    VSAM password
    Empty status
    Object type
    Data set name sharing
    Number of data buffers
    Number of index buffers
    Number of active strings
    LSR pool ID
    Whether using shared resources
    Forward-recovery log ID
    RLS access mode
    Read integrity

BDAM-specific parameters:
    Block size
    Block key length
    Relative address form
    Exclusive control
    Response
    Reason

Data Table specific parameters:
    Table type
    Table size

Operation

How loaded

By DFHFCRP as part of file control initialization.

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.

These activities include:

Called by

DFHFCFS, exclusively.

Inputs

The FCSPARMS parameter list, created in DFHFCFS’s automatic storage and addressed by register 1 on the call.

The input parameters are:

FCTE address
Request identifier

Outputs

Returned in the FCSPARMS parameter list:

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
  1. 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.
  2. 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
  3. 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.

  4. 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:

    1. 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.
    2. 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.

  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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 in the FCT as eligible for BWO support.

    The file open request is rejected if one of the following is true:

    1. 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.
    2. 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 in the FCT 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 in the FCT 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 the CICS Recovery and Restart Guide.
  10. 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
  1. 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 in the FCT 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.
  2. 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.
  3. A CLOSE request is then made by issuing the appropriate (VSAM or BDAM) macro.
  4. The ACB storage is freed, and certain fields in the FCT entry which are no longer valid are cleared.
  5. File statistics and data table statistics, if any, are sent to the statistics domain as unsolicited data.
  6. 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.
  7. If the file was dynamically allocated at open time, it is deallocated, leaving a pointer to the DSNAME block in the FCT entry.
  8. If the file had an autojournal, then the autojournal log stream is closed.
  9. 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.

DFHFCNQ (file control non-RLS lock handler)

DFHFCNQ is the file control non-RLS lock handler. It is called using the FCCA RETAIN_DATASET_LOCKS interface to retain locks in cases of backout failure. It is called using the NQNQ INTERPRET_ENQUEUE interface to interpret File Control locks for presentation purposes.

Lock retention

When DFHFCRC encounters a failure during an attempt to backout a unit of work it must retain all record locks held by that UOW for the failing data set. It issues an FCCA RETAIN_DATASET_LOCKS request to DFHFCCA for RLS access data sets and to this DFHFCNQ for non-RLS access data sets.

Lock name interpretation

Non-RLS locks include record locks for all file types, and for VSAM files, mass-insert range locks, load mode locks and ESDS WRITE locks. Each lock belongs to one of some half dozen or so pools created by DFHFCRP during CICS initialization. DFHFCNQ is called using the NQNQ INTERPRET_ENQUEUE interface and is passed the enqueue pool name and the lock identifier. The name of pool to which a lock belongs is sufficient information to allow the identifier to be parsed and its constituents returned to the caller.

The pool names and lock constituents are:

DFHFCOR (file control offsite recovery completion)

DFHFCOR is the file control RLS offsite recovery completion transaction.

Transaction CFOR is attached when CICS detects that is has completed its RLS offsite recovery processing. RLS offsite recovery is only performed when OFFSITE=YES is specified as a system initialization override. CFOR may be attached either during RLS warm or emergency restart (if there is no RLS offsite recovery work to be performed) or during file control commit processing (if the commit was for the last remaining item of RLS offsite recovery work).

DFHFCOR issues message DFHFC0575 and awaits an operator reply. When the reply is received, it enables RLS access for new transactions.

DFHFCQI (file control RLS quiesce initiation)

DFHFCQI is the RLS Quiesce Initiation module. It provides code to initiate a quiesce request against a base data set. It also provides code to inquire on the quiesce state of a base data set, and to complete a quiesce request against a base data set. Quiesce initiations are issued by the CICS API, or by CICS internally, or by CICS internally cancelling certain in-progress quiesce operations. Quiesce inquiries are issued via the CICS API. Quiesce completions are issued by CICS internally.

DFHFCQR (file control quiesce receive transaction)

DFHFCQR is the VSAM RLS Quiesce Receive module, running under a dedicated CFQR system transaction. It provides code to take quiesce requests from the CICS VSAM RLS quiesce exit and pass them to DFHFCQU for processing. As DFHFCQR runs under a system transaction, it has full transaction environment which enables it to invoke API-capable global user exits, or to call parts of file control that reference the TCA.

DFHFCQS (file control RLS quiesce send transaction)

DFHFCQS is the VSAM RLS Quiesce Send module, running under a dedicated CFQS system transaction. It provides code to take quiesce requests from another task and pass them to SMSVSAM. As DFHFCQS runs under a system transaction, it has full transaction environment which enables it to invoke API-capable global user exits, or to call parts of file control that reference the TCA. DFHFCQS is called from DFHFCQT, the quiesce system transaction module, if the transaction id under which DFHFCQT was started is ’CFQS’.

DFHFCQT (file control RLS quiesce common system transaction)

DFHFCQT is the file control RLS quiesce common system transaction.

There are two file control system transactions dedicated to RLS quiesce processing: CFQS and CFQR. CFQS sends quiesce requests to SMSVSAM in order to initiate the quiesce or unquiesce of a data set throughout the sysplex. CFQR receives quiesce requests from VSAM RLS and performs the quiesce processing required for the CICS region concerned. These transactions share a common top-level program, DFHFCQT.

There is no DFHFCQT parameter list. The action DFHFCQT takes depends on the transid of the transaction it is running under. If it is CFQS then DFHFCQS SEND_QUIESCES is called. If it is CFQR then DFHFCQR RECEIVE_QUIESCES is called. If DFHFCQS or DFHFCQR subsequently fail with a disastrous error, control is returned to DFHFCQT and a transaction abend is issued, having first re-attached the transaction concerned to ensure that RLS Quiesce support is not lost for ever.

DFHFCQU (file control RLS quiesce processor)

DFHFCQU is the RLS Quiesce Process module. It processes quiesce requests received from SMSVSAM via the quiesce exit mechanism.

DFHFCQX (file control RLS quiesce exit)

DFHFCQX is the RLS Quiesce Exit module. It is called by SMSVSAM whenever the CICS region concerned is required to perform processing for a quiesce request.

The quiesce exit is specified on the RLS control ACB EXLST. The exit simply initiates processing and returns to VSAM. It must not issue any VSAM requests. It is scheduled as an IRB on the TCB that registered the RLS control ACB. Because of the environment DFHFCQX cannot issue CICS requests. GTF tracing is used to trace entry, exit and any errors.Start of changeIn addition, timestamps are made on entry to and exit from DFHFCQX, and are stored in fields FC_DFHFCQX_ENTRY_STCK and FC_DFHFCQX_EXIT_STCK respectively of the File Control Static area.End of change

On entry to DFHFCQX, register 1 contains the address of a VSAM structure mapped by IFGQUIES which defines the quiesce request. The processing of the quiesce request is performed by the CFQR long-running system transaction (DFHFCQR). To communicate the quiesce to CFQR, DFHFCQX creates an FC Quiesce Receive Element (FCQRE) to describe the request, and adds it to a chain in file control static storage, posting an ECB associated with the chain also in FC static.

DFHFCRC (file control recovery control program)

DFHFCRC provides recovery control for file control. All calls from the Recovery Manager domain to file control come through DFHFCRC.

DFHFCRC is called by the Recovery Manager domain to participate in syncpoint and in warm and emergency restart.

Early on during startup File Control registers as a client of the CICS Recovery Manager. During File Control initialization, File Control will add its recovery gate to the kernel, specifying DFHFCRC as the entry point, and then declares the recovery gate to the CICS Recovery Manager via an RMCD SET_GATE call.

At syncpoint, a resource owner such as File Control may be called either

  1. to prepare, optionally followed by shunt-unshunt pairs, followed either by calls to backout (as in 2 below) or a call to commit.
  2. to backout, which involves start_backout, optional delivery of backout data, and end_backout, followed by prepare and commit, optionally followed by backout retries (which consist of shunt-unshunt pairs followed by the start_backout - delivery of backout data - end_backout - prepare - commit sequence).

At warm or emergency restart, a resource owner such as File Control will be called with start_delivery, optional deliver_recovery and deliver_forget calls, followed by end_deliver.

The Recovery Manager functions processed by DFHFCRC are:

DFHFCRC performs different processing depending on the function with which it has been called:

PERFORM_PREPARE

Any active VSAM requests are terminated, and a vote of READ_ONLY is returned if the unit of work did not make any recoverable file control updates, a vote of YES if the prepare was successful, or a vote of NO otherwise.

PERFORM_COMMIT

For a forwards syncpoint, any changes made by the unit of work to recoverable user-maintained data tables are committed. For a backwards syncpoint, locks for any backout-failed data sets are retained. All other locks are released.

On transaction termination, the FLABs and FRAB are freed unless there are FLABs marked for retention. On an intermediate syncpoint, various flags in the FLABs and FRAB are reset to indicate that a commit has been performed.

START_BACKOUT

Any active VSAM requests are terminated, and any changes made by the unit of work to recoverable user-maintained data tables are backed out.

DELIVER_BACKOUT_DATA

The recoverable file control change represented by the log record delivered to DFHFCRC is backed out via calls to DFHFCFR which reverse the update. The change is not backed out if the unit of work has already suffered a backout failure for the data set, or if the data set is in a ’non-RLS update permitted’ state, or if this call is being made as part of a CEMT or EXEC CICS SET DSNAME RESETLOCKS request.

If a failure occurs during the backout, then backout failure processing is carried out.

END_BACKOUT

Under normal conditions there should be no processing required at END_BACKOUT, but it is conceivable that there might be outstanding active VSAM requests to be terminated.

PERFORM_SHUNT

The failed parts of the unit of work's file control structures are put into a condition to survive without an executable transaction environment. This involves retaining any FLABs that are marked for retention, which will allow files to be closed, but not to be reallocated to a different data set.

If this is an intermediate syncpoint, and the shunt is due to a failure in phase 2 of syncpoint, the transactional parts of the unit of work are copied into a new control structure to be passed to the follow-on unit of work. A new FRAB is acquired to anchor this control structure. If this is transaction termination, or the shunt is due to a failure in phase 1 of syncpoint, the transactional parts are cleaned up.

PERFORM_UNSHUNT

The file control structures are converted back into a condition suitable for a unit of work that is in an executable state. Retained FLABs for the unit of work are restored.

TAKE_KEYPOINT

DFHFCRC is called when CICS takes a keypoint, to perform processing required by BWO backup on non-RLS data sets. This involves the writing of a set of ’tie up records’ and the calculation of a new BWO recovery time.

START_DELIVERY

DFHFCIR is called to process the call.

DELIVER_RECOVERY

DFHFCIR is called to process the call.

DELIVER_FORGET

DFHFCIR is called to process the call.

END_DELIVERY

DFHFCIR is called to process the call.

DFHFCRD (file control RLS cleanup transaction)

As soon as CICS detects an SMSVSAM server failure, it runs program DFHFCRD under transaction CSFR to perform cleanup.

Following the server failure all current RLS ACBs become unusable. DFHFCRD scans a chain of files open in RLS mode, which is anchored from file control static storage and call DFHFCFS to perform an IMMEDIATE_CLOSE for each open file.

DFHFCRD then waits:

  1. for the last file to close,
  2. once the last file has closed, for SMSVSAM to complete any residual requests against the RLS control ACB.

When both these events have occurred, DFHFCRD calls DFHFCCA to perform UNREGISTER_CONTROL_ACB processing in order to clean up the CICS and VSAM state with respect to the control ACB.

DFHFCRD finally posts an ECB which allows dynamic RLS restart to go ahead. Dynamic RLS restart cannot start until DFHFCRD has completed clean up and posted this ECB.

DFHFCRF (file control function shipping interface module)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

FC_FCRF_ADDRESS stored in FC Static Storage.

Purpose

DFHFCRF is the function shipping interface module. It is called by the access method independent module DFHFCFR for record management requests (e.g. reads, writes, rewrites, etc.) that are to be directed to files that are defined as remote.

DFHFCRF is called with the FCFR parameter list. From this it constructs an FCRF parameter list, which is subsequently passed to DFHISP and, in turn, either to DFHXFX (the MRO transformer) or to DFHXFFP (the ISC transformer).

DFHFCRF executes the following requests from the DFHFCFRR parameter list:

Called by

DFHFCFR, the File Control file request handler.

Inputs

The FCFR parameter list, as defined by the DFHFCFRA DSECT.

Outputs

The FCRF parameter list, as defined by the DFHFCRFA DSECT.

Operation

Traces module entry.

Checks for an explicit SYSID specified on the request and sets the remote system and remote file name in the DFHFCRF parameter list ready for function shipping.

Increments statistics for the type of request.

Checks request specific parameters

Ships the request.

Handles return codes.

Finally, traces the module exit.

How loaded

By FCRP at file control initialization.

DFHFCRL (file control share control block manager)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCRL. The entry point address is held in FC static storage in a field named FC_FCRL_ADDRESS, which is set by DFHFCRP when it loads DFHFCRL.

Purpose

The file control share control block manager is part of the file control component.

This program modifies the CICS specification of a shared resources pool. The changes are allowed to be made only when the actual pool is deleted.

Called by

DFHAMFC, when installing an LSR pool defined by RDO.

Inputs

The FCRL parameter list, as defined by the DFHFCRLA DSECT, is created as part of the subroutine call.

The input parameters are:

Request identifier
Pool identifier
Number of strings
Maximum key length
Share limit
Buffer characteristics

Outputs

The response and reason codes only. These are returned in the FCRL parameter list.

Operation

The SHRCTL block for the specified pool is addressed. A test is made to determine whether or not the pool is currently built; if it is built, the request is rejected with an error response.

The pool characteristics specified in the input parameter list are included in the SHRCTL block.

Finally the information in the SHRCTL block is written to the CICS global catalog.

How loaded

By DFHFCRP as part of file control initialization.

DFHFCRO (file control RLS open/close program)

DFHFCRO performs an equivalent function for RLS opens and closes as is performed by DFHFCN for non-RLS access mode.

DFHFCRP (file control restart program)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCRP. This address is needed only by DFHFCIN2 during initialization; it is therefore not saved in FC static storage.

Purpose

The file control restart program is part of the file control component. This program creates a file control component on a cold or initial start of CICS, or re-creates it after a warm or emergency start. For a warm or emergency start, the intention is to reconstruct the identical file control environment which was in effect at the time of the previous CICS termination.

Called by

DFHFCIN2, during file control initialization.

Inputs

None.

Outputs

The restarted file control component. File control static addresses and indicators are set up. DFHFCRP’s response and reason codes are set in the parameter list defined by DFHFCRPA DSECT.

Operation

Calls loader domain to define (if necessary) and acquire (load) the following file control programs: DFHDTINS, DFHFCAT, DFHFCCA, DFHFCDN, DFHFCD2, DFHFCES, DFHFCFL, DFHFCFS, DFHFCIR, DFHFCLF, DFHFCLJ, DFHFCMT, DFHFCNQ, DFHFCQI, DFHFCQU, DFHFCQX, DFHFCRC, DFHFCRL, DFHFCRO, DFHFCRR, DFHFCRS, DFHFCRV, DFHFCSD, DFHFCST, and DFHFCVS.

Adds gates to the kernel for recovery control, ENF services, and log stream failure notification.

Calls storage manager domain to add (create) the following storage subpools: file control general below 16MB, VSAM FCTE, BDAM FCTE, ACB, DCB, SHRCTL, DSN, FFLE, FRAB, FRTE, FLLB, FLAB, RPL, IFGLUWID, file control fixed-length buffer storage. Calls the NQ domain to add (create) enqueue subpools for: dataset record NQs, file record NQs, range NQs, load mode NQs, ESDS write NQs, and UMT loading NQs.

Calls DFHTMP to create TMP primary indexes for the FCT, AFCT, and DSN tables, and a TMP secondary index for the DSN table.

If RLS is supported (correct level of DFSMS, and RLS=YES SIT parameter) initializes the CSFR, CFQS, CFQR and CFOR tasks, registers file control's interest in the SMSVSAM ENF signal by a LISTEN call to DFHDMEN, and calls DFHFCRR to restart RLS.

On a warm or emergency start:

On a cold start:

Indicates file control restart complete for non-recoverable business by setting FC_NON_REV_ALLOWED_ECB on.

Sends message to inform that file control restart is complete.

If all was successful, turns on the FCSCMPLT flag in FC static.

Finally, posts the FC_RECOV_ALLOWED_ECB in FC static.

How loaded

By the file control initialization module 2, DFHFCIN2, and deleted after it has completed.

DFHFCRR (file control RLS restart)

DFHFCRR is used to restart the RLS component of File Control. It is called whenever CICS is restarted and after any total RLS failure. DFHFCRR is also called whenever a resource can be made available again after earlier failures have been rectified, and after recovery from Lost Locks.

DFHFCRR is invoked whenever CICS is restarted (COLD, WARM or EMERGENCY) by DFHFCRP, and following any total RLS failure (DYNAMIC restart) by DFHFCES.

DFHFCRR is also called to retry work which has been shunted because a resource (a data set, and RLS cache, or the VSAM RLS server) was not available. For this purpose, it is called by DFHFCQU when CICS is notified that a data set has been unquiesced, has completed a non-BWO copy or has completed forward recovery, and when CICS is notified that a previously failed cache is now available; by DFHFCFL when the API interface is used to retry all shunted work for a given data set; and by DFHFCRO when an override condition is detected, in order to drive any shunted work. DFHFCRR is also called by DFHFCQU when CICS is notified that all systems have completed lost locks recovery for a data set.

DFHFCRS (file control RLS record management processor)

DFHFCRS performs an equivalent function for RLS access mode record management requests as is performed by DFHFCVS for non-RLS access mode requests.

DFHFCRV (file control RLS VSAM interface processor)

DFHFCRV performs an equivalent function for RLS access mode record management requests as is performed by DFHFCVR for non-RLS access mode requests.

DFHFCSD (file control shutdown program)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCSD. The entry point address is held in FC static storage in a field named FC_FCSD_ADDRESS, which is set by DFHFCRP when it loads DFHFCSD.

Purpose

The file control shutdown program is part of the file control component. Its purpose is to close all CICS files that are still open during phase 2 of a normal controlled CICS termination. This processing is bypassed for immediate termination.

Called by

DFHSTP, to close all open files managed by CICS file control.

Inputs

The FCSD parameter list, as defined by the DFHFCSDA DSECT, is created as part of the subroutine call.

The input parameters are:

Type of shutdown (immediate, warm)

Outputs

The response and reason codes only, which are returned in the FCSD parameter list.

Operation

DFHFCSD has only one function: TERMINATE.

On a ‘warm’ shutdown (that is, a not-immediate shutdown), DFHFCSD calls DFHTMP to scan all FCT entries. For each file, it calls DFHFCFS to close the file. A special CLOSE qualifier (shutdown) is specified on the call to DFHFCFS so as not to catalog the FCT entry as in an ‘unenabled’ state. DFHFCSD also calls DFHFCDO to disconnect coupling facility data table pools.

If RLS is supported, the quiesce system tasks CFQS and CFQR are terminated.

How loaded

By DFHFCRP as part of file control initialization.

DFHFCST (file control statistics program)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCST. The entry point address is held in FC static storage in a field named FC_FCST_ADDRESS, which is set by DFHFCRP when it loads DFHFCST.

Purpose

The file control statistics program is part of the file control component.

This program is called to collect statistics for a single file, together with any data table statistics, or to collect statistics for the activity in a shared resources pool.

It is also called to return file statistics associated with a file’s use of a shared resources pool.

Called by

DFHSTFC
Collect file statistics
DFHSTLS
Collect pool statistics and also file-in-pool statistics.

Inputs

The FCST parameter list, as defined by the DFHFCSTA DSECT, is created as part of the subroutine call.

The input parameters are:

Request identifier
File name
FCTE token
Statistics record
Pool identifier
Browse token
Reset indicator

Outputs

Returned in the FCST parameter list:

Browse token
Response
Reason

Operation

How loaded

By DFHFCRP as part of file control initialization.

DFHFCVR (file control VSAM interface program)

Call mechanism

BALR, obtaining LIFO storage on entry.

Entry address

DFHFCVR. DFHFCVR is link-edited with DFHFCVS. For calls to DFHFCVR from DFHFCVS, the entry point address is known to DFHFCVS from the link-edit. This address is also stored in FC static storage in a field named FC_FCVR_ENTRY. In addition, there is a further "entry address", UPADEXIT, which is the entry code for the UPAD exit code.

Purpose

The VSAM request interface program is part of the file control component.

This module contains code that issues the VSAM requests, and performs UPAD exit processing in the case of synchronous requests to LSR files, or performs the IOEVENT wait (‘FCIOWAIT’) in the case of asynchronous requests to NSR files.

The module also contains a number of further routines that implement functions required by DFHFCVS.

Called by

DFHFCBD
To issue a message
DFHFCFR
To wait on a CICS ECB
DFHFCVR
Recursively, in order to issue an ENDREQ request to free a deadlock
DFHFCVS
When issuing VSAM requests
DFHFCVS
To execute one of the constituent functions
VSAM
To invoke the UPAD exit.

Inputs

The FCWSV parameter list, as defined by the DFHFCWS macro, is created in the caller’s automatic storage and addressed by register 1 on the call. The input parameters are:

Request identifier
FCTE address
VSWA address
ECB address
Wait resource type
Message number
Dump code

In addition, DFHFCVR requires access to the TCA for certain of its operations.

Outputs

FCVR_RESPONSE parameter (only), defined as part of the FCWSV parameter list.

Operation

Initialize: Copies the VSAM exit list to FC static storage. This action is performed as part of file control initialization.

VSAM_Request: Issues the request to VSAM. Performs the IOEVENT wait. Handles LSR ‘no buffers’ logical error. Issues change mode request to perform the request under the concurrent TCB if possible.

Get_Strings and Free_Strings: Acquires and frees the required number of shared strings from the LSR pool.

Get_TRANID and Free_TRANID: Allocates and releases a VSAM tranid required during sequential update operations to an LSR file.

Wait_CICSECB: Issues a function request to wait for a CICS ECB to be posted.

Wait_String: Issues a function request to wait for a private string to become available.

Send_Message: Issues a function request to send a message.

How loaded

Link-edited with DFHFCVS to form the DFHFCVS load module, which is loaded by DFHFCRP as part of file control initialization.

DFHFCVS (file control VSAM request processor)

Call mechanism

Kernel subroutine call. Automatic stack storage acquired as part of the call.

Entry address

DFHFCVS. The entry point address is held in FC static storage in a field named FC_FCVS_ADDRESS, which is set by DFHFCRP when it loads DFHFCVS.

Purpose

Processes file control requests to VSAM files.

Also initializes certain FC static storage fields during file control initialization.

Called by

DFHFCDTS
To access the VSAM source data set to satisfy requests that cannot be satisfied by the table itself
DFHFCFR
After having determined that the request is for a VSAM file.

Inputs

The FCFR parameter list, as defined by the DFHFCFRA DSECT. Also the file control environment, including FC static storage and the FCT.

Outputs

Updated FCFR parameter list.

Operation

Selects on the request type, and passes control to the routine specific to that request.

Acquires and releases the VSWA as necessary.

Logs and journals the request if required.

Performs record-length and key-length checking.

Acquires storage, in the correct key subpool, for requests that specify SET.

Calls DFHFCVR to perform the VSAM request.

Resolves conflicts of exclusive control.

Performs record locking and resolves locking conflicts, including the detection of deadlocks caused either by single tasks that deadlock themselves or by multiple tasks that deadlock each other.

Performs initialization of FC static storage during file control initialization.

For CICS-maintained data tables, calls data table services to update the table to keep it in step with the VSAM source data set.

How loaded

By DFHFCRP as part of file control initialization.

[[ Contents Previous Page | Next Page Index ]]