gtpd1m2jDatabase Reference

Compact Structures (StructureMem Class)

All compact structure objects inherit from the StructureMem class. This section describes the specific types of compact structure objects provided by TPFCS:

Every compact structure will be an instance of one of these object classes. You will notice that all of these classes are similar in that they each have a data area attribute, but they are different because each has their own specific attributes used to manage the data.

MemFLAT

Of all the structure objects belonging to the StructureMem class, the MemFLAT object is the most simple. The MemFLAT structure object contains a data area attribute where TPFCS stores the collection data. The collection data is stored in the exact order and format the applications using the collection have specified. Each time an application requests data to be stored or retrieved from the collection, TPFCS uses a relative byte position as the displacement into the data area. The applications that store, retrieve, or update data in MemFLAT collections specify this relative byte position either directly or as an index.

Important Attributes

The following are important MemFLAT attributes that precede the data area:

MemFLAT_I_FAL
A 4-byte field containing the number of bytes in the data area available to add new data.

MemFLAT_I_LGH
A 4-byte field containing the length of the data area where the collection data is stored.

MemFLAT_I_NAB
A 4-byte field containing the displacement into the data area where new data can be added.

Graphical Representation

To understand how the MemFLAT object data area will appear on file, it is helpful to understand how TPFCS sets it up in memory. The following figure is a conceptual representation of how TPFCS lays out a MemFLAT object data area in memory:

Figure 33. Example of the Data Area of a MemFLAT Object


Data Format

Each data entry contains the actual user data.

MemHash

TPFCS uses the MemHash object to employ a hashing algorithm to store and retrieve data in collections. The hashing algorithm makes use of an input value, which is extracted from the input that is provided by application programs requesting to store and retrieve data from those collections as well as a hash value, which is produced by the algorithm.

Important Attributes

The following attributes of the MemHash object are most important:

MemHash_I_DataArea
The data area where the collection elements and their hash values are stored. This data area is a contiguous list of data entries that contain the elements of the collection and their hash values.

MemHash_I_FAL
A 4-byte field containing the number of bytes that are available to store additional data and control information.

MemHash_I_LGH
A 4-byte field containing the length of the data area.

MemHash_I_MaxEntryLgh
A 2-byte field containing the maximum data entry length.

MemHash_I_NAB
A 4-byte field containing the number of bytes that are in use to store both data and control information.

MemHash_I_NumEntries
A 2-byte field containing the number of entries or elements stored in the collection.

MemHash_I_ValueLgh
A 2-byte field containing the length of the input value for each data element on which TPFCS will perform a hashing algorithm to locate that element.

Graphical Representation

TPFCS inserts entries into the data area as applications insert elements in the corresponding collection. There is no sorting of elements and there is no chaining of hash synonyms. For example, the data area of a MemHash structure object could contain the following:

Figure 34. Example of the Data Area of a MemHash Object


To retrieve an element in the collection, TPFCS searches the data area sequentially for all occurrences of its hash value until the element input value is found. In Figure 34, if TPFCS needed to process a request to retrieve Element 3, it would perform the MemHash hash algorithm on Element 3 using Input Value 3, which would either be a portion of Element 3 specified by the requesting application or Element 3 itself. 4 The result of the hash operation would be Hash Value A. TPFCS would then search the MemHash data area for a match on Hash Value A that also contained a matching input value. Element 1 would be found but would be bypassed because Input Value 1 does not equal Input Value 3. TPFCS would continue its search and retrieve Element 3 because its entry in the data area contains both a matching hash value as well as a matching input value.

Data Format

Each entry in the data area consists of the following:

MemKey

The MemKey object provides the fastest way to retrieve and store data elements in small collections which are sorted on key. It is also used to store data for other keyed collections which are not sorted.

Important Attributes

The following attributes of a MemKey object are most important:

MemKey_I_DataArea
A data area of varying length where the keys, their data elements, and locators that determine the order of those elements in the collection are stored.

MemKey_I_FAL
A 4-byte field containing the number of bytes remaining in the MemKey data area (MemKey_I_DataArea).

MemKey_I_FirstDeadSlot
A 4-byte field that indicates the displacement to the first inactive entry in the data area. When there are no inactive entries, TPFCS sets this attribute to X'FFFFFFFF'.

An inactive entry is an entry in the MemKey data area that corresponds to an element in the associated collection that an application program has deleted.

MemKey_I_KeyLgh
A 2-byte field that contains the length of a key used for a data element that TPFCS will store in this MemKey object. The length of every key is the same.

MemKey_I_LGH
A 4-byte field containing the length of the data area when TPFCS reads the MemKey object into memory. This length will differ from the actual length of the data area on file because TPFCS will strip the data area of its unused bytes before filing the MemKey object to the TPF database.

MemKey_I_MaxEntryLgh
A 4-byte field that contains the maximum size of a data element that TPFCS will insert into the MemKey data area.

MemKey_I_NAB
A 4-byte field containing the displacement in MemKey_I_DataArea where TPFCS will insert the next key and data element that is added to the collection.

MemKey_I_NumEntries
Contains the number of active data entries that the MemKey object currently holds. Each data entry is composed of a key as well as the data element that corresponds to that key in the collection.

Graphical Representation

To understand how the MemKey object data area will appear on file, it is helpful to understand how TPFCS sets it up in memory. The following figure is a conceptual representation of how TPFCS lays out a data area of MemKey in memory:

Figure 35. Data Area of MemKey in Memory


The conceptual order of the data entries stored in a MemKey object differs greatly from the physical order in which TPFCS stores them. This conceptual order is determined by the order of the locators, which are displacement fields that TPFCS keeps at the bottom of the data area. TPFCS sorts the locators based on the keys of the data entries to which they point rather than sorting those entries themselves. When an application wants to delete an element from a collection that is represented by a MemKey object, TPFCS usually deletes the locator to the corresponding data entry that holds that element rather than deleting the entry itself. TPFCS only stores elements with unique keys in a MemKey object. As a result, if there appear to be entries with duplicate keys in a data area of a MemKey object, it is most likely that all but one of those entries are remnants of data elements that have been deleted from the associated collection. Even though TPFCS files MemKey objects whose data areas contain inactive entries, TPFCS always strips the data area of any gap of unused bytes between the last data entry and the start of the locators before filing a MemKey object. Therefore, when you display a record that contains a MemKey object, you will find its locators immediately following the last entry in the data area.

Data Format

The format of each data entry is as follows:

Each locator is 4 bytes long and contains the following:

Note:
The format of the MemKey object when written to DASD differs from its format in memory because TPFCS condenses the object by removing all unused bytes from the data area. See How Some Objects Are Condensed to Save Space for more information.

MemList

The MemList object is similar to the MemKey object because data elements stored in a MemList are sorted using locators. The main differences are that there are no keys associated with each element stored in a MemList object and there is no inherent order to those data elements. The order of the data elements for MemList structure collections is determined solely by the applications that create and populate them with elements.

Important Attributes

The following attributes of a Memlist object are most important:

MemList_I_DataArea
A data area of varying length where the data elements and locators that determine the order of those elements in the collection are stored.

MemList_I_DataLgh
A 4-byte field containing the length of the data area where elements are stored.

MemList_I_FAL
A 4-byte field containing the number of bytes available in the unused portion of the data area where the next element will be inserted.

MemList_I_NAB
A 4-byte field containing the displacement from the beginning of the data area where the next element will be inserted.

MemList_I_NumEntries
A 4-byte field containing the number of active entries (elements) in the collection.

Graphical Representation

To understand how the MemList object data area appears on file, it is helpful to understand how TPFCS sets it up in memory. The following figure is a conceptual representation of how TPFCS arranges a MemList data area in memory:

Figure 36. Example of a MemList Data Area in Memory


The conceptual order of the data entries stored in a MemList object differs greatly from the physical order in which TPFCS stores them. This conceptual order is determined by the order of the locators, which are displacement fields that TPFCS keeps at the bottom of the data area. TPFCS sorts the locators based on the order of the entries to which they point as indicated by the application rather than sorting those entries themselves. When an application wants to delete an element from a collection that is represented by a MemList object, TPFCS usually just deletes the locator to the corresponding data entry that holds that element rather than deleting the entry itself. Even though TPFCS files MemList objects whose data areas contain inactive entries, TPFCS will always strip the data area of any gap of unused bytes between the last data entry and the start of the locators. Therefore, when you display a record that contains a MemList object, you will find its locators immediately following the last entry in the data area.

Data Format

The format of each data entry is as follows:

Each locator is 4 bytes long and contains the following:

Note:
The format of the MemList object when written to DASD differs from its format in memory because TPFCS condenses the object by removing all unused bytes from the data area. See How Some Objects Are Condensed to Save Space for more information.

Footnotes:

4
Whether the input value is part of, or the same as, the collection element depends on the type of collection represented by the MemHash structure object.