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.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
DFHEIFC. Stored in the CSA in a field named CSAEIFC.
DFHEIFC is DFHEIP’s file control interface. It routes requests to the file control file request handler, DFHFCFR.
DFHEIP exclusively.
The EIEI parameter list, as defined by the DFHEIEIA DSECT.
Updated EIEI parameter list, with completed EIB.
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.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
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.
The FCAT parameter list, as defined by the DFHFCATA DSECT, is created as part of the subroutine call.
The input parameters are:
Returned in the FCAT parameter list:
DFHFCAT provides the following functions:
By DFHFCRP as part of file control initialization.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
DFHFCBD. The entry point address is held in FC static storage in a field named FC_BDAM_ENTRY_ADDRESS.
AMODE 31.
RMODE 24.
The BDAM request processor is part of the file control component. It processes access requests to BDAM files.
DFHFCFR, after having determined that the request is for a BDAM file.
The FCFR parameter list, as defined by the DFHFCFRA DSECT. Also, the file control environment, including FC static storage and the FCT.
Updated FCFR parameter list.
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.
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 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 is attached by DFHFCDO to load a load-capable coupling facility data tavle with records from a source data set.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
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.
The FCDN parameter list, as defined by the DFHFCDNA DSECT, is created as part of the subroutine call.
The input parameters include:
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:
The inputs are a data set name and an FCTE pointer or an FCTE token, with an indication of whether the entity to be connected is a base or an object.
If the FCT entry is already connected, the connection is broken before connecting it to a DSN block representing the new object. The DSN block that is connected can exist already, or DFHFCDN creates a new block before connecting it.
The request is rejected if it requires an existing connection to be broken, and there are uncommitted updates to the file; that is, there are retained locks.
The connection between the FCT entry and the DSN block is broken. The DSN block remains even if there are no other FCT entries connected to it. The request is rejected if there are uncommitted updates to the file: that is, there are retained locks.
Checks are made to ensure that the DSN block is allowed to be deleted. If the deletion can proceed, the table manager is called to delete the DSN from the DSN index, and the storage domain is called to free the storage.
The attributes stored in the DSN block are returned to the caller in the FCDN parameter list.
The availability status is set in the DSN block. The catalog domain is called to catalog the change.
The DSN blocks are browsed in order. For each, the attributes are returned to the caller.
The information in a DSN block is cataloged to the CICS global catalog.
This function is used by DFHEIQDN. DFHFCDN in turn issues a SET_CATALOG_RECOVERED call to DFHFCAT to update the BWO attributes in the ICF catalog for a given VSAM data set to a ‘forward recovered’ state.
This function is used by DFHFCRC. DFHFCDN in turn issues a SET_CATALOG_RECOV_POINT call to DFHFCAT to update the recovery point in the BWO attributes in the ICF catalog for every data set that is open for update in non-RLS mode and defined as eligible for BWO support.
The recovery point is the time from which a forward-recovery utility should start applying log records. It is always before the time the last backup was taken. For further information about recovery points and backup while open in general, see the CICS Recovery and Restart Guide.
This function is used by DFHFCRD. The DSNB table is scanned, and the quiesce status is reset to normal in each DSNB.
By DFHFCRP as part of file control initialization.
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 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 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 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 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 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 performs resynchronization of coupling facility data table pools and links. It is called using the FCDY parameter list by DFHFCDO, DFHFCDR and DFHFCDU.
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 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.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
DFHFCFR. Stored in the CSA in a field named CSAFCEP.
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:
The FCFR parameter list, as defined by the DFHFCFRA DSECT. Also the file control environment, including FC static storage and the FCT.
Updated FCFR parameter list.
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.
By DFHSIB1 as part of the CICS nucleus.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
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.
The FCFS parameter list, as defined by the DFHFCFSA DSECT, is created as part of the subroutine call.
The input parameters are:
Returned in the FCFS parameter list:
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.
DFHFCFS marks the FCT entry as ‘enabled’, and catalogs the change.
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.
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.
If there is no close qualifier, the file is first implicitly disabled (as described above), 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.
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.
By DFHFCRP as part of file control initialization.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
DFHFCIN1. Stored in the CSA in a field named CSAFCXAD.
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.
DFHSII1, as part of CICS initialization.
The FCIN parameter list, as defined by the DFHFCINA DSECT.
Updated FCIN parameter list.
Initialize:
WAITINIT:
Link-edited with DFHFCIN2 to form the DFHFCIN module, which is loaded by DFHSIB1 as part of the CICS nucleus.
Attached by DFHFCIN1 as a separate CICS task. Given control by means of the DFHKC TYPE=ATTACH mechanism.
DFHFCIN2. Because DFHFCIN2 is link-edited with DFHFCIN1, the entry address is known to DFHFCIN1 at the time the DFHKC TYPE=ATTACH is issued.
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.
CICS task control, after being attached by DFHFCIN1.
None.
The initialized file control component. Addresses and indicators completed in file control static storage.
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.
By DFHSIB1 as part of the CICS nucleus.
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.
BALR, obtaining LIFO storage on entry.
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.
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.
DFHFCL is called exclusively by DFHFCN.
The FCLPARAM parameter list, created in DFHFCN’s automatic storage and addressed by register 1 on the call.
The input parameters are:
Returned in the FCLPARAM parameter list:
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.
As a constituent part of DFHFCFS, which is loaded by DFHFCRP as part of file control initialization.
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 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.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
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).
The FCMT parameter list, as defined by the DFHFCMTA assembler DSECT, is created as part of the subroutine call.
The input parameters are:
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:
Storage for the new FCT entry is obtained out of the VSAM FCT storage subpool (BDAM FCT entries cannot be created).
The new FCT entry is completed by filling in the information from the caller’s parameter list.
The name of the new FCT entry is added to the TMP index.
Finally the information in the new entry is written to the CICS global catalog if required.
The request is rejected if there are uncommitted updates for the file; that is, there are retained locks. DFHTMP is called to locate and quiesce the FCT entry.
Any DSN block that is connected to the FCT entry is disconnected.
The FCT entry name is deleted from the TMP index.
The storage for the FCT entry is freed. In the case of a BDAM FCT entry, its DCB storage is also freed.
Any catalog entries for the FCT entry are deleted.
DFHTMP is called to locate the FCT entry.
The request is rejected if there are uncommitted updates for the file; that is, there are retained locks.
If the FCT entry is not marked ‘closed’ and ‘disabled’ (or ‘unenabled’), the request is rejected.
Changes are made to the information in the FCT according to the caller’s parameter list.
Finally the changes are recorded by writing them to the CICS global catalog.
DFHTMP is called to locate the FCT entry.
The attributes are returned in the FCMT parameter list.
DFHTMP is called to locate the FCT entry.
The connect count is incremented. The FCT token is returned to the caller.
DFHTMP is called to quiesce the FCT entry.
A check is made to ensure that the file is closed and disabled (or unenabled). If the check fails, an error is returned to the caller.
The connect count in the FCT is cleared and a call is again made to DFHTMP to release the quiesce.
By DFHFCRP as part of file control initialization.
BALR, obtaining LIFO storage on entry.
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.
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:
DFHFCFS, exclusively.
The FCSPARMS parameter list, created in DFHFCFS’s automatic storage and addressed by register 1 on the call.
The input parameters are:
Returned in the FCSPARMS parameter list:
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.
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:
The ‘load’ mode indicator is set on.
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:
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.
The file open request is rejected if one of the following is true:
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.
As a constituent part of DFHFCFS, which is loaded by DFHFCRP as part of file control initialization.
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.
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.
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 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 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 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 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 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 is the RLS Quiesce Process module. It processes quiesce requests received from SMSVSAM via the quiesce exit mechanism.
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.In 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.
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 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
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:
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.
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.
Any active VSAM requests are terminated, and any changes made by the unit of work to recoverable user-maintained data tables are backed out.
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.
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.
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.
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.
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.
DFHFCIR is called to process the call.
DFHFCIR is called to process the call.
DFHFCIR is called to process the call.
DFHFCIR is called to process the call.
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:
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.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
FC_FCRF_ADDRESS stored in FC Static Storage.
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:
DFHFCFR, the File Control file request handler.
The FCFR parameter list, as defined by the DFHFCFRA DSECT.
The FCRF parameter list, as defined by the DFHFCRFA DSECT.
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.
By FCRP at file control initialization.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
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.
DFHAMFC, when installing an LSR pool defined by RDO.
The FCRL parameter list, as defined by the DFHFCRLA DSECT, is created as part of the subroutine call.
The input parameters are:
The response and reason codes only. These are returned in the FCRL parameter list.
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.
By DFHFCRP as part of file control initialization.
DFHFCRO performs an equivalent function for RLS opens and closes as is performed by DFHFCN for non-RLS access mode.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
DFHFCRP. This address is needed only by DFHFCIN2 during initialization; it is therefore not saved in FC static storage.
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.
DFHFCIN2, during file control initialization.
None.
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.
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.
By the file control initialization module 2, DFHFCIN2, and deleted after it has completed.
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 performs an equivalent function for RLS access mode record management requests as is performed by DFHFCVS for non-RLS access mode requests.
DFHFCRV performs an equivalent function for RLS access mode record management requests as is performed by DFHFCVR for non-RLS access mode requests.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
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.
DFHSTP, to close all open files managed by CICS file control.
The FCSD parameter list, as defined by the DFHFCSDA DSECT, is created as part of the subroutine call.
The input parameters are:
The response and reason codes only, which are returned in the FCSD parameter list.
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.
By DFHFCRP as part of file control initialization.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
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.
The FCST parameter list, as defined by the DFHFCSTA DSECT, is created as part of the subroutine call.
The input parameters are:
Returned in the FCST parameter list:
The FCT entry token is validated if supplied; otherwise, the file name is used to locate the FCT entry.
The file statistics, and any data table statistics, are collected from the FCTE and copied into the statistics record. The statistics in the FCTE are optionally reset according to the reset indicator.
For data tables, a STATISTICS data table service request is issued to retrieve and reset those statistics that are maintained by data table services. These statistics are appended to the file statistics record.
The FCT entry is unlocked and the statistics record returned to the caller.
The SHRCTL block for the specified pool is addressed. The pool statistics are copied into the statistics record and are returned to the caller.
Storage is obtained from the general file control pool for the browse cursor. The browse token is returned to the caller.
DFHTMP is invoked to locate the FCT entry identified by the browse cursor. If the file uses the specified pool, the shared pool statistics for this file are retrieved and returned in the statistics record.
The statistics contain the data and index buffer sizes, and the number of times buffer waits occurred.
The browse cursor is updated before returning to the caller.
The browse cursor storage is freed before returning to the caller.
By DFHFCRP as part of file control initialization.
BALR, obtaining LIFO storage on entry.
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.
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.
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:
In addition, DFHFCVR requires access to the TCA for certain of its operations.
FCVR_RESPONSE parameter (only), defined as part of the FCWSV parameter list.
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.
Link-edited with DFHFCVS to form the DFHFCVS load module, which is loaded by DFHFCRP as part of file control initialization.
Kernel subroutine call. Automatic stack storage acquired as part of the call.
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.
Processes file control requests to VSAM files.
Also initializes certain FC static storage fields during file control initialization.
The FCFR parameter list, as defined by the DFHFCFRA DSECT. Also the file control environment, including FC static storage and the FCT.
Updated FCFR parameter list.
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.
By DFHFCRP as part of file control initialization.
[[ Contents Previous Page | Next Page Index ]]