gtpd1m2g | Database Reference |
TPFCS uses object aggregation to represent actual collections (see Collection Parts Stored in the TPF Database). Apart from the many data elements that can be contained in a collection, TPFCS groups more than one object together to represent the collection itself. Objects such as these are referred to as collection part objects, which are also known as collection parts or part objects. TPFCS uses part objects to store control information about collections as well as to hold or point to the data elements that are contained in those collections. To be a collection part, an object must inherit from the ObjectPart class as defined in the TPFCS source code. Do not let the name of this class mislead you: a collection part, while a member of the ObjectPart class, is itself an entire object because the ObjectPart class inherits from the OBJECT class. 3
The group of internal part objects that represent a collection are packaged into a larger object, which is an instance of the DATXPAGE class, and will be referred to as a DATXPAGE envelope. A DATXPAGE envelope appears in a pool record after the TPF record header as follows.
Figure 29. DATXPAGE Envelope Format
Figure 29 shows that:
The DATXPAGE envelope and all the collection parts contained in it are filed in the TPF database in a record known as the control record.
Every persistent collection has a control record associated with it. To an application programmer, the unique persistent identifier (PID) associated with a given collection serves as a token that applications must supply to TPFCS to perform any operation on the collection after it is created. The PID represents an anchor to which an associated collection and all its data are tied. From the perspective of a database administrator, the control record serves as the anchor to which all of the parts that represent an associated collection (including its data) are chained.
The control record contains a DATXPAGE envelope in which all of the collection part objects used to represent a collection are stored. The following example shows the contents of a control record for an array collection that is not shadowed:
Figure 30. Example of a Collection Control Record
The following objects are all packaged in the DATXPAGE envelope filed in the control record:
An OIDentry object is the first collection part packaged in the DATXPAGE envelope. Its purpose is to serve as a table of contents by identifying how many other collection parts follow in the envelope and where each part begins (relative to the beginning of the OIDentry object itself). The OIDentry object contains a table of contents attribute with as many entries as there are additional objects in the DATXPAGE envelope. Each entry contains:
This varies according to collection type. For example, if the collection is an array, its collection object is an ARRAY object. The collection object contains information that is unique to the type of collection. For example, for arrays, one of the attributes stored in the ARRAY object is the next index to be used.
For compact-resident collections, the structure object follows (see Collection Residency for more information about residency). This is the object that contains control information as well as the actual data elements stored in those collections.
For extended-resident collections, the DATXPAGE envelope contains an xStructDASD object instead of a structure object because the structure object is too large. The xStructDASD object, in turn, contains a pointer to the structure object. This structure object will contain control information used to locate the data elements elsewhere in the TPF database, rather than containing the data elements themselves.
This is an object that contains information about the data definition used to store the collection.
TPFCS stores some types of collections using more than one structure. For example, a keyed log collection can be stored using the same structure object used for regular (nonkeyed) logs to contain the data, and another structure that is the same structure object as a key set collection to maintain the key associated with each entry there. When this occurs, TPFCS will use a separate collection object as well as a separate DDEF_OBJ object for each structure object. In our example, TPFCS would implement the keyed log collection using both a log collection as well as a key set collection. There would still be just one PID assigned to the keyed log. The contents of the control record associated with the PID would be as follows:
Figure 31. Conceptual View of a Control Record for a Keyed Log Collection
To make it easier, all other discussions in this publication assume a single structure for a collection unless otherwise noted. Furthermore, our discussion of both the DATXPAGE envelope and the control record has been based upon a logical representation. In reality, it is possible that all of the objects which TPFCS intends to package in a single DATXPAGE envelope and corresponding control record will not fit in a single 4-K pool record on DASD. See How an Object Can Overflow into Additional Records for detailed information about how a logical control record and the objects it contains are split across multiple physical records.