How it works: CFDTs and CFDT servers

CICS® coupling facility data tables (CFDTs) are designed to provide rapid sharing of working data within a sysplex, with update integrity. The data is held in a table that is similar in many ways to a shared user-maintained data table, and the API used to store and retrieve the data is based on the file control API used for user-maintained data tables. CFDTs are held in coupling facility list structures. Access to a CFDT is through a named CFDT server.

Figure 1 illustrates a Parallel Sysplex® with three CICS AORs linked to the coupling facility data table servers.

Figure 1. Conceptual view of a Parallel Sysplex with coupling facility data table servers
This diagram shows three AORs in a Parallel Sysplex with Coupling facility data table servers. They each have a DFHCFMN CFDT server, which links to the Coupling facility data table pool.

Coupling facility data tables

Coupling facility data tables (CFDTs) provide a method of file data sharing, using CICS file control, without the need for a file-owning region, and without the need for VSAM RLS support. CICS CFDT support provides rapid sharing of working data within a sysplex, with update integrity. The data is held in a coupling facility, in a table that is similar to a shared user-maintained data table. You must define the resources required for CFDTs in a z/OS® coupling facility resource management (CFRM) policy.

Because read access and write access have similar performance, this form of table is useful for scratchpad data. Typical uses might include sharing scratchpad data between CICS regions across a sysplex, or sharing of files for which changes do not have to be permanently saved. There are many different requirements for scratchpad data, and most of these can be implemented using CFDTs.

CFDTs are useful for grouping data into different tables, where the items can be identified and retrieved by their keys. For example:
  • You can use a field in a CFDT to maintain the next free order number for use by an order processing application.
  • You can maintain a list of the numbers of lost credit cards in a CFDT.

To an application, a CFDT appears much like a sysplex-wide user-maintained data table, because it is accessed in the same way, by using the file control API. However, in a CFDT there is a maximum key-length restriction of 16 bytes.

A CFDT is accessed from CICS through file control commands. The file name specified on the command indicates the name of the table and pool in which it resides. The table name is either specified on the file definition or is the same as the file name, and the pool name is specified on the file definition. The table is uniquely identified by the pool name and table name, so that two tables with the same name can exist in different pools, and are entirely separate entities.

Coupling facility data table structures

Coupling facility data tables (CFDTs) are held in coupling facility list structures. A CFDT pool is a coupling facility list structure, and access to it is provided by a coupling facility data table server. You can use CFDT support to separate related groups of CFDTs by storing them in separate pools. For example, you can have one pool for production and another for test.

Coupling facility list structures are defined in the coupling facility resource management (CFRM) policy. Structure names for CFDTs take the form DFHCFLS_poolname. The CFDT pool name is then specified in the startup JCL for the CFDT server.

Coupling facility data table models

CFDTs can use the contention model or the locking model. You specify the model that each table uses on its file resource definition, so different tables can use different models.
  • The contention model gives optimal performance but generally requires programs written to exploit it. This is because the CHANGED condition code (which indicates that the data has changed since the application program issued a read-for-update request) is specifically for this model. Programs that are not written for the contention model might not be able to handle this condition correctly. The CHANGED response can occur on a REWRITE or DELETE command. There is also a situation with the contention model in which the NOTFND response can be returned on a REWRITE or DELETE.

    This model is nonrecoverable: CFDT updates are not backed out if a unit of work fails.

  • The locking model is API-compatible with programs that conform to the UMT subset of the file control API (this subset is almost the full file control API). This model can be one of the following:
    • Nonrecoverable.

      Locks do not last until syncpoint, and CFDT updates are not backed out if a unit of work fails.

    • Recoverable.

      CFDTs are recoverable after a unit-of-work failure or a CICS region failure (updates made by units of work that were in-flight at the time of the CICS failure are backed out).

      The recoverable locking model supports indoubt and backout failures. If a unit of work fails when backing out an update to the CFDT, or if it fails indoubt during syncpoint processing, the locks are converted to retained locks and the unit of work is shunted.

Coupling facility data table servers

The CFDT server can be thought of as similar to a shared data tables file-owning region. For information about shared data tables support, see The data table sharing environment.

Within each z/OS image, there must be one CFDT server for each CFDT pool accessed by CICS regions in the z/OS image.

The names of the servers are formed by adding the server address space name to the pool name. For example, for FACILTY class RACF® profiles, the server name is DFHCF.poolname.

Automatic connection to CFDT pools

CICS connects to the CFDT server for a given pool the first time that a CFDT in that pool is referenced. CICS also reconnects automatically to the CFDT server when the server restarts after a failure.

CFDT servers are protected against misuse by CICS regions that call them, thus ensuring system integrity. Protection is provided so that the calling region cannot modify sensitive parameters to authorized functions.

Similarly, CICS is protected from any side effects if a CFDT server fails. If a CICS region issues a file control request to a CFDT server that has failed, the resulting z/OS abend is trapped and returned to the application program as a SYSIDERR condition.

A client CICS region establishes a single cross-memory connection to a server the first time a request refers to the pool for that server. If the server connection fails, there are implications for coupling facility data tables. See Server connection management and Named counter recovery.

CFDT creation and deletion

CICS automatically creates a coupling facility data table (CFDT) when a first reference requires the CFDT to be opened. This CFDT is then used by the same region, or other CICS regions, that issue subsequent open requests for other files that name the same coupling facility data table.

CICS can optionally load the CFDT automatically from a source VSAM (KSDS) data set when it is first opened. Unlike user-maintained data tables, with CFDTs you can specify that there is no associated source data set, allowing you to create an empty CFDT.

Your application programs have access to a CFDT as soon as it is created, although there are some restrictions on the keys that can be accessed while data is being loaded.

When a CFDT is loaded, it becomes an independent entity, separate from the behavior of the CICS regions that access the table, or caused the table to be loaded. Even when all CICS regions have terminated, either normally or abnormally, a CFDT remains in the coupling facility until you take explicit action to delete the structure or the coupling facility.

To delete the CFDT contents or structure, you can use the following command:
MODIFY cfdt_server, DELETE TABLE=name
For more information on the MODIFY command, see MODIFY command.

Information and tools for CFDT administration

CICS provides some utility functions that you can use to obtain summary information and periodic statistics from a coupling facility data table server about CFDTs defined in a pool. See Using coupling facility data tables for an analysis of the coupling facility data table statistics reports and Coupling Facility Data Table Pools report for further reference information. You can use this information when you administer coupling facility data table pools, and to evaluate capacity. See Coupling facility data table server parameters for details.