gtpd1m32Database Reference

Coupling Facility List Structure Concepts

The topics that follow topics provide basic information about the CF list structure.

See Allocating a Coupling Facility Structure for more information about how the TPF system handles a request for CF list structure allocation. Understanding this concept will help you provide assistance to anyone using CF support.

Coupling Facility List Structure

Rather than accessing data in a CF by address, you can allocate objects called structures and access data in the structures as logical entities (for example, by name). The ability to access data this way frees you from having to be concerned with the physical location or address of the data. One type of object that CF support provides is a CF list structure. Each CF list structure must reside entirely in a single CF and applications can use multiple CF list structures.

The CF can support multiple occurrences of the CF list structure at the same time. However, a CF list structure found in one CF cannot be seen by another CF. A CF list structure consists of a number of lists, each with a number of list items.

The characteristics and services associated with a CF list structure support certain types of uses and offer certain unique functions. A CF list structure is a named piece of storage on a CF that enables TPF systems to share information organized as entries on a set of lists or queues. Connections could use a CF list structure, for example, to distribute work or maintain shared status information. By using a CF list structure, you can monitor list transitions from an empty state to a nonempty state without accessing the CF and checking the lists directly.

A CF list structure consists of a set of lists and an optional lock table of exclusive locks that you can use to serialize the use of lists, list entries, or other resources in the CF list structure. A list header points to a CF list, which can contain a number of list entries. A list entry consists of list entry controls and can also include a data entry, an adjunct area, or both. Data entries and adjunct areas are both optional. However, data entries are optional for each list entry while adjunct areas exist for all list entries or no list entries. A CF list structure that includes a lock table is called a serialized list structure. Figure 60 shows a serialized list structure.

Figure 60. A Serialized List Structure


The following are the parts of the CF list structure:

Part
Description

 List Header 
Anchors the list to the CF list structure and contains control information that is associated with the list. The control information is known as list controls. The first TPF system to connect to the CF list structure designates the number of list headers it is to have and allocates the CF list structure.

 List Entry 
An entry on the list. Data in the CF list structure is stored in list entries, each of which can consist of a data entry of up to 16 data elements in a CF level 6 and an optional adjunct data area. A list entry contains the following:

Each list entry can reside on only one list at a time. Unused list entries do not reside on any list.

 Lock Table 
An array of exclusive locks that you can use to serialize access to CF list structure resources such as lists or list entries. The purpose and scope of the exclusive locks are defined by the application. Lock table users create and maintain the association between a lock table entry and its associated resource. The lock table can be used:

See Coupling Facility Locking Functions for more information about a serialized list structure, the CF locking functions, and the lock table.

How Data Is Maintained in a Coupling Facility List Structure

Data in the CF list structure is stored in list entries, each of which can consist of a data entry up to 255 data elements in a CF level 6 and an optional adjunct data area. The number of data element sizes and the range in the number of elements for each data entry provides a tremendous choice of data entry sizes. The maximum data entry size is 64 KB, except in a CF list structure that has a data element size of 256 bytes. Because the maximum number of data elements for each data entry is 255, the maximum data entry size with 256-byte data elements is 65 280 bytes (255 × 256). All other combinations of data element size and data entry size allow a maximum of 64 KB (65 536 bytes). Although a data entry consists of a number of data elements, list operations handle the data entry as a single entity; data elements cannot be read or written individually. The adjunct area can be used to hold additional, user-defined information about the data entry.

Figure 61 shows a list that contains list entries with various numbers of data elements; list entry controls are not shown in this figure. See the OS/390 MVS Sysplex Services Guide for more information about how data is maintained in a CF list structure.

Figure 61. A List Containing Entries with Various Numbers of Data Elements


Specifying Connection Parameters for the Coupling Facility List Structure

This section provides general information about how to code the CFCONC macro so you can connect to a CF list structure. See TPF System Macros for detailed information about each parameter of the CFCONC macro.

Data Element Size

To select the data element size for a CF list structure you must understand the approximate sizes of the smallest and largest pieces of data you want stored in the list entries. If the data can fit into adjunct areas, you can avoid using data entries altogether. If you specify 0, the CF list structure is allocated without data elements. The TPF system ignores the MAXELEMNUM parameter if you specify it with the ELEMENTRATIO parameter set to 0.

The CF allows a maximum of 255 data elements for each data entry, but you can use the MAXELEMNUM parameter to specify a smaller maximum number if you want to additionally restrict the size of the largest data entries.

The value you specify for the MAXELEMNUM parameter must be greater than or equal to the value specified for the ELEMENTRATIO parameter divided by the value specified for the ENTRYRATIO parameter:

MAXELEMNUM >= (ELEMENTRATIO / ENTRYRATIO)

The data element size multiplied by the maximum number of data elements must be enough to accommodate the largest piece of data that you need to manage as a single entry.

Entry-to-Element Ratio

You cannot directly control the number of list entries or data elements the CF list structure holds. When the CF list structure is allocated, its storage is subdivided to reserve space for CF list structure components like data elements and list entry controls. The value you specify for the entry-to-element ratio is used by the TPF system to determine the proportion of the CF list structure storage to allocate to each component. The ratio, expressed as a pair of whole numbers like 1:4, is passed to the CFCONC macro using the ENTRYRATIO and ELEMENTRATIO parameters:

In general, the entry-to-element ratio should reflect the average number of data elements for each list entry. For example, if your data element size is 4096 bytes and you estimate that about half of the list entries will require 1 data element and about half of the list entries will require 8 data elements, you want a ratio of 1:4.5, which you would express in whole numbers as 2:9.

Although you request a particular entry-to-element ratio through the CFCONC macro, the CF may use a slightly different ratio. The actual number of entries and elements in the CF list structure, rather than the ratio, is returned to you in the CFCONC answer area, which is mapped by the ICFCAA DSECT.

Note:
The values in the CFCONC answer area are not exact values.

Limiting the Storage Used by Each List

The LISTCNTLTYPE parameter allows you to choose how storage use is managed for individual lists. You can limit either the number of list entries for each list or the number of data elements for each list. A limit on storage use for each list may be needed to prevent the excessive use of storage by certain lists.

The flexibility offered by the choice of limits allows you to select the type of limit that best suits your use of the CF list structure. For example, if your main concern is to limit the number of entries that may build up on a list, limit the number of list entries for each list. If your main concern is to prevent the entries on a given list from consuming too much of the storage in a CF list structure, limit the number of data elements on a list.

Adjunct Areas

The adjunct area can contain 64 bytes of user-defined data such as information about the status of the data entry or time stamp. The adjunct area is maintained separately from the data entry so you can change the contents of the data entry or the adjunct area independently.

Named or Keyed List Entries

Named entries let users reference list entries by a user-defined name. Keyed entries let users maintain list entries in a keyed order. The choice of named or keyed entries, or the use of neither, depends on how you are using the CF list structure. For example, if the list entries represent units of work ordered by priority, you may choose keyed entries. If the list entries represent customer records in a particular category, you may choose named entries. If the lists represent units of work to be processed on a first-in-first-out (FIFO) basis, there may be no need for names or keys. Use the REFOPTION parameter on the CFCONC macro to specify how to reference the list entries in the CF list structure.

List Transition Exit

CF support provides the list transition exit routine, which plays a critical role in the operation of the CF list structure. TPF systems provide the address of the exit routine when they issue the CFCONC macro to connect to the CF list structure. See Defining Exit Routines for more information.