Design overview

File control provides the following services and features:

Deblocking services for BDAM data sets

CICS® provides deblocking of logical records on a direct-access (BDAM) data set. This service is provided for both fixed-length and variable-length records. The data set must have been created according to standard System/370 record-formatting conventions.

Concurrency control

Protection is provided against the concurrent updating (adding, deleting or changing) of a data set record by two or more transactions (or strictly speaking, two or more units of work; a transaction may optionally consist of a sequence of units of work). This protection is in most cases achieved using locking. If a second unit of work attempts to update a record which has been locked by another unit of work, the second unit of work is normally queued until the first releases its lock. If the lock has been converted into a retained lock (this is done if a syncpoint failure occurs) then the second unit of work gets an error response rather than being queued. An optimized alternative to locking is used to achieve concurrency control for coupling facility data tables. This is described in the section 'Concurrency control for coupling facility data tables'.

For a VSAM data set being accessed in non-RLS mode, CICS acquires locks (or enqueues) using the NQ domain that prevent the same record from being updated by more than one unit of work at a time. If the file is recoverable, then the lock is not released until syncpoint (that is, the end of the unit of work), otherwise it is released when the request thread completes. A request thread consists, for example, of a read update followed by a rewrite. In non-RLS mode, VSAM also provides a form of concurrency control known as exclusive control. The sphere of exclusive control is the control interval (CI), and this means that two different records cannot be concurrently updated if they are both within the same CI. Exclusive control is only maintained while a record is being updated, and is released as soon as the operation is complete.

For a VSAM data set being accessed in RLS mode, VSAM acquires locks at the record level to prevent the same record from being updated by more than one unit of work within the sysplex at a time. If the data set is recoverable, then the lock is not released until syncpoint, otherwise it is released when the request sequence completes. There is no CI locking with RLS mode.

For a recoverable BDAM file, CICS acquires locks using the NQ domain that prevent the same record from being updated by more than one unit of work at a time.

Concurrency control for coupling facility data tables

Concurrency control for coupling facility data tables is provided by using one of two update models provided by coupling facility data tables support (CFDT support).

The default is the locking update model, in which the CFDT server acquires locks at the record level to prevent the same record from being updated by more than one unit of work within the sysplex at a time. If the data set is recoverable, then the lock is not released until syncpoint, otherwise it is released when the request sequence completes.

The contention update model is an optimized alternative to using locking to achieve update integrity (concurrency control). With this model, which can be specified on a per-data table basis, no locks are acquired when a record is read for update, but if another unit of work subsequently changes or deletes this record, then the first unit of work will be informed that the record has changed (or been deleted) when it comes to rewrite or delete the record itself. The occurrence of such a contention is detected by the CFDT server, and the contention update model is only available for coupling facility data tables.

Sequential retrieval

A facility supported by CICS file control is the sequential retrieval of records from the database. This facility is known as browsing. To initiate a browse operation, the user provides either a specific or generic (partial) record reference (key) for the point at which sequential retrieval is to begin. Each subsequent get request by the user initiates retrieval of the next sequential record. The application, while in browse mode, can issue random get for update requests to a different data set, without interrupting the browse operation. For VSAM files accessed in RLS mode, the application can update the records that it is browsing. For VSAM files accessed in non-RLS mode, and BDAM files, in order to update a record of the same data set, the application must first terminate the browse operation. The same application can concurrently browse several different data sets and browse the same data set with multiple tasks.

With VSAM data sets, the application can skip forward during a browse operation to bypass unwanted data.

All types of CICS data tables (CICS-maintained, user-maintained and coupling facility) can be browsed.

Read Integrity

When a file is accessed in RLS mode, three levels of read integrity are supported:

Backout logging

File control will perform automatic logging of file operations which update recoverable files. This logging is written to the CICS system log stream. In the event of either a system or a transaction failure, the information can subsequently be used to restore the recoverable data set as though the current transaction had never run.

For coupling facility data tables, the CFDT server performs its own logging, and is responsible for backing out updates in the event of a failure.

Forward Recovery Logging

If a file (non-RLS VSAM) or data set (RLS or non-RLS VSAM) is defined to be forward recoverable, then CICS will perform automatic logging of file operations which update it. This logging is written to the forward recovery log stream specified on the file definition or data set. In the event of a failure, the information can be used to forward recover from a backup copy of the data set.

Forward recovery support is not provided for user-maintained data tables or coupling facility data tables.

Automatic journaling and logging

Except in the case of user-maintained data tables and coupling facility data tables, CICS provides optional automatic journaling and logging facilities for records that are updated, deleted from, or added to a file control data set. Automatic journaling is specified in the file control table, by the user, for each data set affected. For a specified data set, a record read for update, a new record added, or an existing record deleted is automatically written to the specified journal. To allow journaled records to be associated with the appropriate data set (instead of with the CICS file name), a special record is journaled showing the current data set allocation whenever it changes.

Use of concurrent tasks

The file control non-RLS VSAM interface program (DFHFCVR) uses a change-mode request to the dispatcher to allow VSAM I/O requests and VSAM UPAD exit code to run under a concurrent task. This provides overlapping of processing in a multiprocessor environment.

RLS requests use a different mechanism: SMSVSAM assigns each request its own SRB, allowing MVS™ to concurrently schedule requests in an analogous way to that provided by subtasking for non-RLS.

Shared Data table services

Shared data tables (that is, CICS-maintained and user-maintained data tables) are managed by a set of OCO modules, referred to in this book as "data table services". The services are invoked by a branch-and-link interface passing a parameter block.

Services provided include the following:

For files that are defined by the user as CICS-maintained or user-maintained data tables, file control invokes these services at appropriate points in the processing of application requests.

Coupling facility data tables server

Coupling facility data tables are managed by a OCO modules within the CICS address space, along with a separate address space, referred to as the "Coupling Facility Data Tables Server". The CFDT server provides access to coupling facility data tables residing in a coupling facility data tables pool, so that they can be shared by CICS regions across a parallel sysplex. Refer to the CICS Supplied Transactions for more details about CFDT servers.

For files that are defined by the user as accessing coupling facility data tables, file control makes calls to the CFDT server at appropriate points in the processing of application requests.

How CICS processes file control requests

CICS receives file control requests from applications through the EXEC interface. This section describes only the mainstream processing for such requests. It does not describe exceptional conditions. For guidance about exceptional conditions, see the CICS Application Programming Guide. For general-use programming interface information about exceptional conditions, see the CICS Application Programming Reference manual. This section also does not provide details about the specific processing for requests to any kind of data table.

Processing using VSAM

For VSAM data sets, this section describes the processing followed when the file is being accessed in non-RLS mode. For RLS mode, the processing is broadly similar, although it differs in some of the interfaces used to VSAM, and the locking mechanisms are very different.

Note:
File control processing is constrained by the availability of buffers, CICS strings and (for local shared resource (LSR) files) LSR strings. Tasks can get suspended during the execution of any file control request if there are not enough strings or buffers available for the immediate processing that is to be done.

With VSAM RLS, a task waiting for buffers will be suspended in VSAM rather than in CICS.

Processing using Data Tables

For shared data tables (CICS-maintained and user-maintained data tables), processing is broadly similar to that for non-RLS VSAM. The main differences are that, for remote files, non-update requests may be processed locally instead of being function shipped, and that, in cases where a request cannot be satisfied from a data table, it may be converted into a non-RLS or RLS VSAM request to be processed by DFHFCVS or DFHFCRS, or function shipped via DFHFCDTX.

For coupling facility data tables, processing is also broadly similar to that for non-RLS VSAM. The main difference is that instead of issuing the request to VSAM, a call or calls are made to entry points within the CFDT server, which then processes the request and returns the results. A task accessing a coupling facility data table may occasionally be suspended in the CFDT server.

Note that the following processing sections do not describe data table processing explicitly.

General request processing

All file requests, whatever the request and whatever the file access method, follow the same general sequence of steps:

  1. User exit XFCREQ is called.
  2. The request is converted from EXEC parameter list form to FCFR interface form.
  3. If this is the first file access request by the transaction, a FRAB is obtained and its address stored in Recovery Manager's FC Token. The FRAB provides the anchor for file request state for this transaction.
  4. If this is the first request to this file by the transaction, a FLAB is obtained and the file control table entry is located. If the file is remote or an explicit SYSID has been specified on the request, the FLAB is marked with a remote indicator. If this is not the first request to the file, then the FLAB is located that repressents accesses made to the file by this transaction.
  5. If this is the first, or only, request of a request sequence, a FRTE is obtained. If this is not the first request in a request sequence, the FRTE that represents the sequence is located. rather than being function shipped.
  6. If the request is to a local file, and if resource security is active, the security check is made, unless a check has already been made within the current UOW for this file.
  7. If the request is to a local file and the file is not already open, it is opened and its access method dependent attributes are saved in its file control table entry.
  8. The SERVREQ attributes of the file are checked.
  9. For READ and browse requests, SET storage is released and/or obtained, as necesssary.
  10. The access method specific request processor is called as follows:
  11. CICS has checked whether the file is defined as local or remote. If it is remote, the request is function-shipped to the file-owning region, where CICS processes the request as if it had originated locally.

    There is an exception for CICS-maintained and user-maintained data tables, for which non-update requests are treated as local rather than being function shipped.

    Note that RLS support and coupling facility data tables support both provided shared access within a parallel sysplex without the use of function shipping. Files which use either of these types of sharing will be defined as local on all systems which wish to share the data set (in the case of RLS support) or data table (CFDT support).

  12. SET storage is obtained for BDAM files or below the line READ requests.
  13. The FRTE is released if the request sequence has ended and the file is closed if a close is pending, this FRTE is the last user and the FLAB indicates that the file can be closed.
  14. The FCFR responsed are converted to EXEC parameter list responses. In particular, the EIBRCODE and RESP2 values are constructed.
  15. User exit XFCREQC is called.

READ request processing

The course of READ request processing depends on the access method, and whether or not the UPDATE option is specified on the request:

VSAM processing:

  1. The supplied keylength is validated.
  2. A VSAM work area (VSWA) is created. This includes the request parameter list (RPL) that will be passed to VSAM.

    The processing that follows depends on whether the UPDATE option was specified on the READ request.

    UPDATE option not specified:

    1. The RPL is completed, and a call made to VSAM to get the record.
    2. If the request specifies INTO and the record is too large for the user-specified area, the request is reissued specifying a work area large enough to hold the record. The record is then copied to the user-specified area in truncated form, and the LENGERR condition is raised.
    3. The VSWA is freed.
    4. The read is journaled if specified in the FCT entry.

    UPDATE option specified:

    1. The UPDATE flag is set in the RPL.
    2. An attempt is made to read the record by issuing the VSAM request. READ UPDATE requires exclusive control of the control interval (CI) containing the record. VSAM manages the locking mechanism for control intervals. If the CI is already locked, VSAM returns an error and the requesting task is forced to wait on resource type FCXCWAIT.
    3. CICS file control acquires a record lock on the record just read, using a CICS ENQUEUE request. The record lock prevents any other transaction from updating the record before the owning transaction has reached a syncpoint (for recoverable files), or before the REWRITE, DELETE, UNLOCK or syncpoint that completes the request sequence (non-recoverable files).
    4. Exclusive control of the CI is retained until the REWRITE, DELETE, or UNLOCK request that follows the READ UPDATE has been completed, or until the next syncpoint.

      The CICS record lock (if any) is retained until the next syncpoint, in case the transaction updating the record abends and dynamic transaction backout processing is necessary.

    5. If the file is recoverable the request is logged. If required, the request is also recorded in a user-specified journal.

    BDAM processing:

    1. A file I/O area (FIOA) is obtained.
    2. If the UPDATE option has been specified:
      1. The address of the RIDFLD is saved in the FIOA.
      2. If the data set is recoverable, the RIDFLD is ENQUEUEd on to lock the record against other updates. The ENQUEUE is retained until the next syncpoint.
    3. The KEYLENGTH is checked for validity.
    4. The key field is converted from character string format (TTTTTTRR) to binary format (TTR), if necessary.
    5. A BDAM READ request is issued. If the READ is successful, the required block is returned in the FIOA.
    6. The key field returned by BDAM is converted from binary format to character string format, if necessary.
    7. If the file is recoverable and UPDATE has been specified, the request is logged. If required, the request is also recorded in a user-specified journal.
    8. If deblocking is required, the required record is located in the block that has been returned by BDAM:
      1. If DEBREC has been specified, the record number is used to locate the record.
      2. If DEBKEY has been specified, the embedded key is used to locate the record.

WRITE request processing

The course of WRITE request processing depends on the access method, and for VSAM access on whether the file is a data table: VSAM processing:

  1. The KEYLENGTH is checked for validity. If it is incorrect, the INVREQ condition is raised.
  2. A VSAM work area (VSWA) is created. This includes the request parameter list (RPL) that will be passed to VSAM.

    Different paths are now followed depending on the type of file.

    ESDS file:

    1. If the file is recoverable or writes are to be journaled then
      1. If this is not the first write of a sequence and the ESDS write lock is being waited for by another transaction, then release the lock and end this sequence, logging the completion if recoverable.
      2. If this is (or has become) the first write of a sequence, acquire the ESDS write lock for the data set.
    2. If the file is recoverable, the WRITE ADD request is recorded in the CICS system log.
    3. If required, the WRITE ADD request is recorded in a user-specified journal.
    4. Any fields in the RPL not supplied when the VSWA was created are completed.
    5. The RPL is set to point to the user-specified data area. If the user specified a record that is too large for the file, the length in the RPL is set to the maximum length, so that the record is truncated.
    6. A VSAM PUT request is issued to write the record.
    7. If the file is recoverable, a CICS record lock is obtained for the record that has just been written. The record lock will be retained until the next syncpoint, in case the transaction writing the record abends and dynamic transaction backout processing has to be performed.
    8. If the file is recoverable, the after-image of the record is logged for forward recovery and a write complete record is written on the system log.
    9. If not a MASSINSERT the ESDS write lock is released, if held.

    KSDS or RRDS file:

    1. For KSDS requests, the RIDFLD key specified in the request is checked against the key field in the record to be written. (The record is currently in the application FROM data area.) If it does not match, the INVREQ condition is raised.
    2. If the file is recoverable and not in load mode:
      1. A CICS lock is obtained on the record that is to be written, and an attempt is made to read the record (by means of a VSAM GET request) to discover whether it already exists in the file. If it does, the DUPREQ condition will be raised on the write to VSAM.
      2. If the file is a KSDS, and if this request is part of a MASSINSERT, or if a MASSINSERT is in progress, the read is issued with GTEQ to find the next record in the base data set. A lock is created, using the key of this next record, to prevent other transactions from inserting records into the empty range.
      3. If there is no existing record with the given key, the WRITE ADD request to VSAM is recorded in the CICS system log and, if required, in a user-specified journal.
    3. If the file is not recoverable or in load mode, the WRITE request is recorded, if required, in the user-specified journal, and if recoverable a record lock is obtained and the write logged.
    4. Any fields in the RPL not supplied when the VSWA was created are completed.
    5. If a data table is associated with the base cluster (the data table will be a CICS-maintained table, as user-maintained and coupling facility data tables follow a separate processing path which is not described here). a data table pre-add is issued to place the record in the table as a not-yet-valid entry. If the file is recoverable, a record lock is already held; if not, a lock is acquired before the data table service is called.
    6. A VSAM request is issued to write the record.
    7. If the file is recoverable, the after-image of the record is logged for forward recovery.
    8. If required, the after-image is recorded in a user-specified journal.
    9. If the file is a data table, a data table request is issued to complete the add to the data table by validating the record. If a record lock was obtained for a non-recoverable file, it is released.

  3. If the MASSINSERT option has not been specified on the WRITE request, the VSWA for the operation is released.

    If MASSINSERT has been specified, the VSWA is not released, because it is likely to be needed for subsequent WRITE operations. In this case, the end of MASSINSERT processing is notified to VSAM by the CICS UNLOCK function. (See UNLOCK request processing.)

    Specifying MASSINSERT causes exclusive control of the CI to be acquired. Exclusive control is released by issuing an UNLOCK request. To avoid deadlocks, this should be done immediately after the last WRITE MASSINSERT request.

BDAM processing:

  1. The KEYLENGTH is checked for validity. If it is incorrect, the INVREQ condition is raised.
  2. The WRITE command input is checked to ensure that MASSINSERT has not been specified--BDAM does not support MASSINSERT processing. If it has, condition INVREQ is raised.
  3. A file I/O area (FIOA) is obtained.
  4. If the file is recoverable, the record to be written is ENQUEUEd on. The lock is retained until the next syncpoint.
  5. The record to be written is copied from the user-supplied data area to the FIOA. If the record is too large, it is truncated.
  6. If the file is recoverable, the request is logged. If required, the request is also recorded in a user-specified journal.
  7. The key field is converted from character string format to binary format, if necessary, and the BDAM I/O request issued.
  8. The key returned by BDAM is converted from binary format to character string format, if necessary, and passed to the application.
  9. A supervisor call (SVC 53) is issued to release BDAM exclusive control, if necessary.
  10. The FIOA is FREEMAINed.

REWRITE request processing

The REWRITE request is used to write a record back to a file following a READ UPDATE request. VSAM processing:

  1. The RPL is set to point to the user-specified data area. If the user specified a record that is too large for the file, the length in the RPL is set to the maximum length, so that the record is truncated.
  2. The RPL is completed.
  3. If there is a data table associated with the base cluster (this will be a CICS-maintained table, as user-maintained tables follow data table processing):
    1. If the file is nonrecoverable, a record lock is obtained. (If the file is recoverable, a lock is already held).
    2. A data table request is issued to invalidate the record in the table before the VSAM update.
  4. VSAM is called to PUT(UPDATE) the record. Exclusive control of the CI, which was obtained for the preceding READ UPDATE request, is released, but the CICS record lock (for recoverable files) is retained until the next syncpoint, in case the transaction abends and dynamic transaction backout processing is necessary.
  5. If there is a data table associated with the data set, the table record is updated and its validity is reinstated, by issuing a call to data table services. If the file is nonrecoverable, the record lock is released.
  6. If the file is recoverable, and if the record is successfully rewritten, the after-image is written to the log for forward recovery.
  7. The VSWA for the operation is released.

    Note:
    When a record is updated by way of a path, the corresponding alternate index is updated by VSAM to reflect the change. However, if the record is updated directly by way of the base, or by a different path, the AIX® will only be updated by VSAM if it has been defined to VSAM (when created) to belong to the upgrade set of the base data set.

BDAM processing:

  1. The FIOA that was used in the corresponding READ UPDATE request is located, and the modified record read into it from the user-specified area. If the record is too long, it is truncated.
  2. A FREEMAIN call is issued to release the FWA.
  3. If the file is recoverable, the request is logged. If required, the request is also recorded in a user-specified journal.
  4. The key field is converted from character string format to binary format, if necessary, and the BDAM I/O request issued.
  5. The key returned by BDAM is converted from binary format to character string format, if necessary, and passed to the application.
  6. A supervisor call (SVC 53) is issued to release BDAM exclusive control, if necessary.
  7. A FREEMAIN call is issued to release the FIOA.

UNLOCK request processing

The UNLOCK request is used to release exclusive control obtained during a READ UPDATE (VSAM or BDAM) or WRITE MASSINSERT (VSAM only) request.

VSAM processing (including CICS-maintained data tables):

  1. The VSWA for the operation is released, together with associated storage.
  2. An ENDREQ request is sent to VSAM. This releases exclusive control of the CI, if it is held, and frees any VSAM strings.

BDAM processing:

  1. A supervisor call (SVC 53) is issued to release BDAM exclusive control, if necessary.
  2. A FREEMAIN call is issued to release the FIOA.

DELETE request processing

The course of DELETE request processing depends on whether a RIDFLD has been specified. The processing for user-maintained data tables differs from that for CICS-maintained data tables. DELETE requests are not valid for VSAM ESDS or for BDAM files.

VSAM processing (including CICS-maintained data tables):

  1. If a RIDFLD has been specified:
    1. If a KEYLENGTH has been specified, it is checked for validity.
    2. If the GENERIC option has been specified, and the file is not a KSDS, condition INVREQ is raised.
    3. A VSWA is created.
  2. If no RIDFLD was specified, the SERVREQ attribute of the file is checked to ensure that DELETE requests are valid for this file. If not, the INVREQ condition is raised.

    If a RIDFLD has been specified, the cycle of actions described below is performed once if GENERIC has not been specified, or is repeated until there are no more records containing the generic key, if GENERIC has been specified.

    Start of cycle:

  3. VSAM is requested to GET for UPDATE a record with the specific or generic key. GET UPDATE processing requires exclusive control of the CI. The record is read into an internal buffer.

    The generic key value, if supplied, is checked against the key contained in the record. If it does not match, there are no more records containing the generic key in the file.

  4. If the file is recoverable:
    1. A CICS record lock is obtained for the record. This will be held until the next syncpoint.
    2. The VSAM GET UPDATE request is recorded synchronously on the system log.
    3. A CICS range lock is obtained for the record to be deleted if a MASSINSERT is in progress. This is to prevent an end-of-range record from being deleted while the range is in use for a MASSINSERT sequence.
  5. If there is a data table (which will be CICS-maintained) associated with the base cluster, a record lock is acquired if the file is nonrecoverable, and a data table pre-update call is issued to invalidate the record before the VSAM update.
  6. A VSAM ERASE request is issued, to delete the record from the file.
  7. If there is a data table associated with the base cluster, the record is deleted from the table by issuing a call to data table services. If the file is nonrecoverable, the record lock is released.
  8. If a range lock was acquired, it is released.
  9. If the file is recoverable, a WRITE DELETE record is written in the system log for forward recovery.
  10. If required, a WRITE DELETE record is written to a user-specified journal.

    End of cycle.

  11. The VSWA is released.

STARTBR and RESETBR request processing

STARTBR and RESETBR request processing are very similar, and are described together.

VSAM processing:

  1. A VSWA is created if STARTBR.
  2. The user key is recorded in the VSWA for use in subsequent BROWSE processing.
  3. A call is made to VSAM to point to the record, and to acquire shared control of the CI.

BDAM processing:

  1. An FIOA is obtained and initialized if STARTBR.
  2. The initial key is saved in the FIOA, converting the key from character string format to binary format if necessary.
  3. If deblocking is required, the deblocking indicator (DEBREC or DEBKEY) is saved in the FIOA.

READNEXT and READPREV request processing

READNEXT and READPREV request processing are very similar, and are described together.

VSAM processing:

  1. A check is made that READPREV with a generic key was not requested. If it was, condition INVREQ is raised.
  2. If KEYLENGTH was specified, it is checked for validity. If it is incorrect, the INVREQ condition is raised.
  3. The RPL options are set.
  4. If SET is specified, an internal work area is obtained and the RPL is set to point to the work area. The area is either above or below the 16MB line, depending on the requirements of the application.
  5. If INTO is specified, the RPL is set to point to the user-specified area.
  6. A VSAM request is issued to read the record. Shared control of the CI is needed, and the request will not succeed if some other task already has exclusive control. In such a case, a call is made to VSAM to reestablish the correct position in the file. The task then waits until VSAM informs CICS that the CI is available to the task. CICS resumes the task, which can now acquire shared control and obtain the required record.
  7. If SET is specified, the SET pointer points to the work area.
  8. If INTO is specified, a check is made to see if the record is too large to fit into the user-specified area. If it is too large, the request is reissued using an internal work area, the data is copied from the work area into the user-specified area and truncated, and the LENGERR condition is raised.
  9. If required, the request is recorded in a user-specified journal.

BDAM processing--READNEXT requests:

  1. A check is made that READPREV was not issued. If it was, condition INVREQ is raised.
  2. The FIOA that was created on STARTBR is located.
  3. If a new block is required, a BDAM I/O request is issued to get it.
  4. If deblocking is required, the required record is located in the block that has been returned by BDAM:
    1. If DEBREC has been specified, the record number is used to locate the record.
    2. If DEBKEY has been specified, the embedded key is used to locate the record.
  5. If INTO is specified, the record or block is moved from the FIOA to the user-specified area. If the record is longer than the user-specified area, it is truncated, and the LENGERR condition is raised.
  6. If SET is specified, the SET pointer points to the record in the FIOA.
  7. The RIDFLD of the record is returned to the application.
  8. The current browse position is recorded in the FIOA.

ENDBR request processing

The ENDBR request is used to end a browse session on a file. To avoid deadlocks, ENDBR must be issued when the browse session is complete.

VSAM processing:

  1. An ENDREQ request is sent to VSAM. This frees any VSAM strings that are held, and relinquishes shared control of the CI.
  2. The VSWA for the operation is released.

BDAM processing:

[[ Contents Previous Page | Next Page Index ]]