What is a List Structure?

A list structure consists of a set of lists and an optional lock table of exclusive locks, which you can use to serialize the use of lists, list entries, or other resources in the list structure. Each list is pointed to by a header and 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. Both data entries and adjunct areas are optional. However, data entries are optional for each list entry while a list structure either has or doesn't have adjunct areas. Figure 1 shows a list structure that contains an optional lock table. A list structure that includes a lock table is called a serialized list structure.

Figure 1. Serialized List Structure

The parts of the coupling facility list structure are:

List header

Anchors the list to the list structure and contains control information associated with the list (list controls). The first user to connect to the list structure designates the number of list headers it is to have, and allocates the list structure.

List entry

An entry on the list. A list entry consists of:

List entry controls, which contain control information associated with the list entry.
An optional data entry, which holds user-specified data. Data entries are composed of units of storage called data elements. In a coupling facility of CFLEVEL=0, data entries can be composed of 0 to 16 data elements. In a coupling facility of CFLEVEL=1 or higher, data entries can be composed of 0 to 255 data elements. In either case, a data entry can contain up to 64K (65536 bytes) of data.
An adjunct area used to hold up to 64 bytes of data. You could use the adjunct area to maintain control information about the contents of the data entry. If your data is always 64 bytes or less, you could use adjunct areas to hold your data and omit the use of data entries.

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 can be used to serialize access to list structure resources such as lists or list entries. Lock table users create and maintain the association between a lock table entry and its associated resource. The lock table can be used:

Together with list entry operations such as reading or writing list entry data
Independently of list entry operations