For a description of how to define a coupling facility data table (CFDT), and start a coupling facility data table server, see the CICS® System Definition Guide.
A CFDT 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. The data, unlike a UMT, is not kept in a dataspace in an MVS™ image and controlled by a CICS region, but kept in a coupling facility list structure, and control is shared between CFDT server regions. A CICS region requesting access to a CFDT communicates with a CFDT server region running in the same MVS image, using the MVS authorised cross-memory (AXM) server environment. This is the same technique used by CICS temporary storage servers.
CFDTs are particularly useful for informal shared data. Uses could include a sysplex-wide shared scratchpad, look-up tables of telephone numbers, and creating a subset of customers from a customer list. Compared with existing methods of sharing data of this kind, such as shared data tables, shared temporary storage or RLS files, CFDTs offer some distinct advantages:
There are two models of coupling facility data table, a contention model or locking model.
Using the contention model, an exception condition (CHANGED) notifies an application that a rewrite following a read for update, or a delete following a read for update, needs to be retried because the copy of the record in the table has been updated by another task before the rewrite or delete could be performed. The contention model does not lock a record, but uses the version number of the table entry for the record to check that it has not been altered. If the version of this record on rewrite or delete is not the same as when the original read for update was performed, the CHANGED condition is returned.
The locking model causes records to be locked following a read for update request so that multiple updates cannot occur.
A contention model CFDT is non-recoverable. A locking model CFDT may be recoverable or non-recoverable. For a non-recoverable locking model, CFDT locks are held until a read for update sequence is completed by a rewrite, a delete or an unlock, but not until the next syncpoint. Changes are not backed out if a unit of work fails. In the recoverable case, locks are held until syncpoint, and the CFDT record is recoverable in the event of a unit of work failure, CICS region failure, CFDT server failure, or MVS failure.
The relative cost of using update models and recovery is related to the number of coupling facility accesses needed to support a request. Contention requires the least number of accesses, but if the data is changed, additional programming and coupling facility accesses would be needed to handle this condition. Locking requires more coupling facility accesses, but does mean a request will not need to be retried, whereas retries can be required when using the contention model. Recovery also requires further coupling facility accesses, because the recovery data is kept in the coupling facility list structure.
The following table shows the number of coupling facility accesses needed to support the CFDT request types by update model.
Request description | Contention | Locking | Recoverable |
---|---|---|---|
Open, Close | 3 | 3 | 6 |
Read, Point | 1 | 1 | 1 |
Write new record | 1 | 1 | 2 |
Read for Update | 1 | 2 | 2 |
Unlock | 0 | 1 | 1 |
Rewrite | 1 | 1 | 3 |
Delete | 1 | 1 | 2 |
Delete by key | 1 | 2 | 3 |
Syncpoint | 0 | 0 | 3 |
Lock WAIT | 0 | 2 | 2 |
Lock POST | 0 | 2 | 2 |
Cross-system POST | 0 | 2 per waiting server | 2 per waiting server |
Records held in a coupling facility list structure are marked as locked by updating the adjunct area associated with the coupling facility list structure element that holds the data. Locking a record requires an additional coupling facility access to set the lock, having determined on the first access that the data was not already locked.
If, however, there is an update conflict, a number of extra coupling facility accesses are needed, as described in the following sequence of events:
The contention update model uses the entry version number to keep track of changes. The entry version number is changed each time the record is updated. This allows an update request to check that the record has not been altered since its copy of the record was acquired.
When an update conflict occurs, additional coupling facility accesses are needed:-
In a test that compared the use of a CFDT with a function-shipped UMT between 2 CICS regions running on different MVS members of a sysplex, it was found that overall CPU utilization was reduced by over 40% by using CFDTs. Some general observations that may be useful are:
Choose an appropriate use of a CFDT. For example, for cross-system, recoverable scratchpad storage, where shared TS does not give the required functionality, or VSAM RLS incurs too much overhead.
A large file requires a large amount of coupling facility storage to contain it. Smaller files are better CFDT candidates (unless your application is written to control the number of records held in a CFDT).
The additional cost of using a locking model compared with a contention model is not great. Considering that using the contention model may need application changes if you are using an existing program, locking is probably the best choice of update model for your CFDT. If coupling facility accesses are critical to you, they are minimized by the contention model.
Recovery costs slightly more in CPU usage and in coupling facility utilisation.
Allow for expansion when sizing the CFDT. The amount of coupling facility storage a structure occupies can be increased dynamically up to the maximum defined in the associated coupling facility resource management (CFRM) policy with a SETXCF ALTER command. The MAXTABLES value defined to the CFDT server should allow for expansion. Therefore, consider setting it to a value higher than your initial requirements. If a CFDT does become full, its capacity can be increased using the CFDT operator command SET TABLE=name,MAXRECS=n.
The utilization of the CFDT should be regularly monitored both through CICS and CFDT statistics and RMF™. Check that the size of the structure is reasonable for the amount of data it contains. A maximum-used of 80% is a reasonable target. Defining a maximum coupling facility list structure size in the CFRM policy definition to be greater than the initial allocation size specified by the POOLSIZE parameter in the CFDT server startup parameters enables you to enlarge the structure dynamically with a SETXCF ALTER command if the structure does fill in extraordinary circumstances.
Ensure that the AXMPGANY storage pool is large enough. This can be increased by increasing the REGION size for the CFDT server. Insufficient AXMPGANY storage may lead to 80A abends in the CFDT server.
A CFDT is defined to a CICS region using a FILE definition with the following parameters:
MAXNUMRECS specifies the maximum number of records that that CFDT can hold.
The first CICS region to open the CFDT determines the attributes for the file. Once opened successfully, these attributes remain associated with the CFDT through the data in the coupling facility list structure. Unless this table or coupling facility list structure is deleted or altered by a CFDT server operator command, the attributes persist even after CICS and CFDT server restarts. Other CICS regions attempting to open the CFDT must have a consistent definition of the CFDT, for example using the same update model.
The CFDT server controls the coupling facility list structure and the data tables held in this structure. The parameters documented in the CICS System Definition Guide describe how initial structure size, structure element size, and entry-to-element ratio can be specified.
Both CICS and the CFDT server produce statistics records. These are described in Appendix C. Coupling facility data tables server statistics.
The CICS file statistics report the various requests by type issued against each CFDT. They also report if the CFDT becomes full, the highest number of records held and a Changed Response/Lock Wait count. This last item can be used to determine for a contention CFDT how many times the CHANGED condition was returned. For a locking CFDT this count reports how many times requests were made to wait because the requested record was already locked.
The CFDT server reports comprehensive statistics on both the coupling facility list structure it uses and the data tables it supports. It also reports on the storage used within the CFDT region by the AXM routines executed (the AXMPGLOW and AXMPGANY areas). This data can be written to SMF and may also be produced automatically at regular intervals or by operator command to the joblog of the CFDT server.
The following is an example of coupling facility statistics produced by a CFDT server:
DFHCF0432I Table pool statistics for coupling facility list structure DFH
CFLS_PERFCFT2:
Structure: Size Max size Elem size Tables: Current Highest
12288K 30208K 256 4 4
Lists: Total In use Max used Control Data
137 41 41 37 4
100% 30% 30% 27% 3%
Entries: Total In use Max used Free Min free Reserve
3837 2010 2010 1827 1827 191
100% 52% 52% 48% 48% 5%
Elements: Total In use Max used Free Min free Reserve
38691 12434 12434 26257 26257 1934
100% 32% 32% 68% 68% 5%
This above example shows the amount of space currently used in a coupling facility list structure (Size) and the maximum size (Max size) defined for the structure. The structure size can be increased by using a SETXCF ALTER command. The number of lists defined is determined by the MAXTABLES parameter for the CFDT server. In this example, the structure can support up to 100 data tables (and 37 lists for control information).
Each list entry comprises a fixed length section for entry controls and a variable number of data elements. The size of these elements is fixed when the structure is first allocated in the coupling facility, and is specified to the CFDT server by the ELEMSIZE parameter. The allocation of coupling facility space between entry controls and elements will be altered automatically and dynamically by the CFDT server to improve space utilization if necessary.
The reserve space is used to ensure that rewrites and server internal operations can still function if a structure fills with user data.
The amount of storage used with the CFDT region to support AXM requests is also reported. For example:-
AXMPG0004I Usage statistics for storage page pool AXMPGANY:
Size In Use Max Used Free Min Free
30852K 636K 672K 30216K 30180K
100% 2% 2% 98% 98%
Gets Frees Retries Fails
3122 3098 0 0
AXMPG0004I Usage statistics for storage page pool AXMPGLOW:
Size In Use Max Used Free Min Free
440K 12K 12K 428K 428K
100% 3% 3% 97% 97%
Gets Frees Retries Fails
3 0 0 0
The CFDT server uses storage in its own region for AXMPGANY and AXMPGLOW storage pools. AXMPGANY accounts for most of the available storage above 16MB in the CFDT region. The AXMPGLOW refers to 24-bit-addressed storage (below 16MB) and accounts for only 5% of this storage in the CFDT region. The CFDT server has a small requirement for such storage.
In addition to the statistics produced by CICS and the CFDT server, you can monitor the performance and use of the coupling facility list structure using the Resource Measurement Facility (RMF) facilities available on z/OS®. A ‘Coupling Facility Activity’ report can be used to review the use of a coupling facility list structure. For example, this section of the report shows the DFHFCLS_PERFCFT2 structure size (12M), how much of the coupling facility is occupied (0.6%), some information on the requests handled, and how this structure has allocated and used the entries and data elements within this particular list structure. The headings are 'Type', 'Structure name', 'Status chg', 'Alloc size', '% of CF storage', '# req', '% of all req', 'Avg req/sec', 'Lst/dir entries tot/cur', 'Data elements tot/cur', 'Lock entries tot/cur'and 'Dir rec/ Dir rec XI's'.
% OF % OF AVG LST/DIR DATA LOCK DIR REC/
STRUCTURE ALLOC CF # ALL REQ/ ENTRIES ELEMENTS ENTRIES DIR REC
TYPE NAME STATUS CHG SIZE STORAGE REQ REQ SEC TOT/CUR TOT/CUR TOT/CUR XI'S
LIST DFHCFLS_PERFCFT2 ACTIVE 12M 0.6% 43530 93.2% 169.38 3837 39K N/A N/A
1508 11K N/A N/A
RMF will also report on the activity (performance) of each structure. The example report below shows the system name, the total number of requests and the average requests per second. For requests, it gives the number of each type of request, the percentage of all requests that this number represents, the average service time and the standard deviation. For delayed requests, it gives the number of requests delayed for each reason, the percentage of all requests that this number represents, the average delay time and the standard deviation for each type of delay, and the average delay time for all delayed requests.
STRUCTURE NAME = DFHCFLS_PERFCFT2 TYPE = LIST
# REQ -------------- REQUESTS ------------- -------------- DELAYED REQUESTS -------------
SYSTEM TOTAL # % OF -SERV TIME(MIC)- REASON # % OF ---- AVG TIME(MIC) -----
NAME AVG/SEC REQ ALL AVG STD_DEV REQ REQ /DEL STD_DEV /ALL
MV2A 43530 SYNC 21K 49.3% 130.2 39.1
169.4 ASYNC 22K 50.7% 632.7 377.7 NO SCH 0 0.0% 0.0 0.0 0.0
CHNGD 0 0.0% INCLUDED IN ASYNC
DUMP 0 0.0% 0.0 0.0
This report shows how many requests were processed for the structure DFHFCLS_PERFCFT2 and average service times (response times) for the two categories of requests, synchronous and asynchronous. Be aware that requests of greater then 4K are handled asynchronously. For an asynchronous request, the CICS region can continue to execute other work and is informed when the request completes. CICS waits for a synchronous request to complete, but these are generally very short periods. The example above shows an average service time of 130.2 microseconds (millionths of a second). CICS monitoring records show delay time for a transaction due waiting for a CFDT response. In the example above, a mixed workload of small and large files was used. You can see from the SERV TIME values that, on average, the ASYNC requests took nearly 5 times longer to process and that there was a wide variation in service times for these requests. The STD_DEV value for SYNC requests is much smaller.