Coupling facility data tables 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 coupling facility data table support is designed to provide 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 in many ways to a shared user-maintained data table. This topic describes how to define the resources required for coupling facility data tables in an MVS™ coupling facility resource management (CFRM) policy.
Because read access and write access have similar performance, this form of table is particularly 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 coupling facility data tables. Coupling facility data tables are particularly useful for grouping data into different tables, where the items can be identified and retrieved by their keys. For example, you could use a field in a coupling facility data table to maintain the next free order number for use by an order processing application, or you could maintain a list of the numbers of lost credit cards in a coupling facility data table.
To an application, a coupling facility data table (CFDT) appears much like a sysplex-wide user-maintained data table, because it is accessed in the same way using the file control API. However, in a CFDT there is a maximum key-length restriction of 16 bytes.
There are two models of coupling facility data table:
This model is non-recoverable: CFDT updates are not backed out if a unit of work fails.
This model can either be:
The recoverable locking model supports in-doubt and backout failures: if a unit of work fails when backing out an update to the CFDT or if it fails in-doubt during syncpoint processing the locks are converted to retained locks and the unit of work is shunted.
You specify the model you want for each table on its file resource definition, enabling different tables to use different models.
Coupling facility data tables are held in coupling facility structures. Access to a coupling facility data table is through a named server, which can be thought of as similar to a shared data tables file-owning region (see the CICS Shared Data Tables Guide for information about shared data tables support). Coupling facility data tables support allows you to separate related groups of coupling facility data tables by storing them in separate pools. For example, you might want to have one pool for production and another for test.
A coupling facility data table pool is a coupling facility list structure, and access to it is provided by a coupling facility data table server. Within each MVS image, there must be one CFDT server for each CFDT pool accessed by CICS regions in the MVS image. The names of the servers are formed by adding the prefix DFHCF to the pool name, giving DFHCF.poolname. Coupling facility data table pools are defined in the coupling facility resource management (CFRM) policy. The pool name is then specified in the start-up JCL for the table server.
A coupling facility data table 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 may exist in different pools, and will be entirely separate entities.
CICS automatically connects to the coupling facility data table server for a given pool the first time that a coupling facility data table within that pool is referenced. CICS also automatically reconnects to the coupling facility data table server when the server restarts after a failure.
Coupling facility data table servers are protected against misuse by CICS regions that call them, thus ensuring system integrity. In particular, protection is provided to prevent calling region from being able to modify sensitive parameters to authorized functions.
Likewise, CICS is protected from any side effects if a coupling facility data table server fails. If a CICS region issues a file control request to a coupling facility data table server that has failed, the resulting MVS abend is trapped and returned to the application program as a SYSIDERR condition.
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 of other files that name the same coupling facility data table.
CICS can optionally load the coupling facility data table automatically from a source VSAM (KSDS) data set when it is first opened. Unlike user-maintained data tables, with coupling facility data tables 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 coupling facility data table 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 continues to remain in the coupling facility until you either take explicit action to delete the structure, or the coupling facility. You can delete the CFDT contents or structure with a MODIFY cfdt_server, DELETE TABLE=name command.
CICS provides some utility functions that allow you to obtain, from a coupling facility data table server, summary information and periodic statistics on coupling facility data tables defined within a pool. This information is designed to help you to administer coupling facility data table pools, and to help you to evaluate capacity. See Coupling facility data table server parameters for details.
You define the list structure for a coupling facility data table in a coupling facility resource manager (CFRM) policy in a sysplex couple data set. A coupling facility data table pool, containing one or more coupling facility data tables, is accessed by CICS through a server region using cross-memory services. (See Setting up and running a coupling facility data table server for information about setting up and starting a coupling facility data table region.)
From the application point of view, a pool and its server are similar to a file-owning region, and the pool can contain any number of tables provided that each one has a unique table name.
Before a coupling facility data table server can use its pool, the active CFRM policy must contain a definition of the list structure to be used for the pool. To achieve this, add a statement that specifies the list structure to a selected CFRM policy, and then activate the policy.
The CFRM structure definition specifies the size of the list structure and the preference list of coupling facilities in which it can be stored. You create the name of the list structure for a coupling facility data table pool by adding the prefix DFHCFLS_ to the pool name, giving DFHCFLS_poolname.
To update an adminstrative policy in the CFRM couple data set, use the administrative data utility, IXCMIAPU. The utility adds or changes policy data in the administrative policies only: it does not change any information in the system's copy of the active CFRM policy. For an example of a job to run this utility, see member IXCCFRMP in the SYS1.SAMPLIB library. An example of a policy statement for a coupling facility data table pool is shown in Figure 23.
STRUCTURE NAME(DFHCFLS_PRODCFT1)
SIZE(1000)
INITSIZE(500)
PREFLIST(FACIL01,FACIL02)
When you have defined the list structure in a CFRM policy, activate the policy using the MVS command SETXCF START,POLICY,POLNAME=policyname,TYPE=CFRM. Note that activating a CFRM policy that contains a definition of a list structure does not create the structure. It is created the first time an attempt is made to connect to it, which occurs when the first coupling facility data table server that refers to the corresponding pool is started.
When the server creates a list structure, it is allocated with an initial size, which can be increased up to a maximum size as specified in the CFRM policy. All structure sizes are rounded up to the next multiple of 256KB at allocation time. Provided that space is available in the coupling facility, you can dynamically expand a list structure from its initial size up to its maximum size, or contract it to free up coupling facility space for other purposes. Note that if the initial structure allocation becomes full, the structure does not expand automatically, even if the structure allocated is less than the specified maximum size. To expand a list structure when the allocation becomes full, you can expand it (up to its maximum size) using the following SETXCF command:
SETXCF START,ALTER,STRNAME=DFHCFLS_poolname,SIZE=nnnn
Note that if you dynamically increase the size of a list structure in this way, also update the INITSIZE parameter in the policy to reflect the new size, so that the structure does not revert to its original size if you subsequently recreate or reload it.
A coupling facility structure contains not only stored data but
also the information needed to manage and access that data, in a similar way
to a key-sequenced data set. The data for each entry in the coupling facility
is stored as a chain of fixed size (usually 256-byte) elements, which means
that the exact length for variable-length data has to be stored separately. CICS does this by including a length prefix in the stored data, so space
calculations have to allow for each entry using a whole number of elements.
The amount of internal control information depends on the level of functionality
and performance of the coupling facility control code for the current CFLEVEL.
The storage requirements can increase for a higher CFLEVEL. For more information
about how the coupling facility structure storage is organized, see Coupling facility storage management.
The easiest way to calculate accurate structure storage requirements
is to use the web-based IBM® CFSizer tool at http://www-1.ibm.com/servers/eserver/zseries/cfsizer/ . The tool takes these factors into account and communicates with a coupling
facility at a current CFLEVEL to perform the calculation. You need to enter
some minimum input to get an accurate storage calculation as follows:
If all queue items are approximately the same size, calculate this value by taking the average data size, adding two, and rounding up to the next multiple of 256. If queue items are different sizes, round up each size first before taking the average. For example, if half of the items are 100 bytes and half are 300 bytes, then the rounded sizes are 256 and 512. The average rounded item size is half way between those values, 384, which is more accurate than taking the overall average item size of 200 and rounding it up to 256.
Alternatively you can use the following calculation, which applies
up to CFLEVEL 11 of the coupling facility. If you have a coupling facility
at CFLEVEL 12, you need to change the calculation to add 10% and 2MB to the
sizings in the formula below.
Data entry size = (170 + (average record data size1))
+ 5% extra for control information
1 Average record data size must have a 2-byte prefix added
and be rounded up to a multiple of 256 bytes.
Total size = 200KB
+ (number of tables x 1KB)
+ (number of records in all tables x data entry size)
The above calculation assumes that the structure is allocated at its maximum size. If it is allocated at less than its maximum size, the same amount of control information is still required, so the percentage of space occupied by control information is correspondingly increased. For example, if a structure is allocated at one third of its maximum size, the overhead for control information increases to around fifteen per cent.
The calculation determines the size of a structure that would be approximately 100% full for the specified level of usage. For practical operation, however, a reasonable proportion of free space must be available, not only to minimize the risk of the structure becoming totally full but also to avoid triggering low space warning messages and additional activity to alter entry to element ratios. The maximum normal usage should therefore aim to be about 75% of the structure size. Expected usage values should therefore be adjusted upwards to allow for the required amount of free space (for example, by about one third to aim for 75% usage).
For information about the reserved space parameters you can use to enable the server to avoid a structure full condition, see Reserved space parameters and Avoiding structure full conditions.
[[ Contents Previous Page | Next Page Index ]]