gtpd1m23Database Reference

TPFCS Database Layout

TPF collection support (TPFCS) contains all the components that you need to access collections. The TPFCS database consists of user-defined data stores. In these data stores are collections. Each collection consists of elements. Elements can contain character data, binary data, structures, or references to other collections or TPF files. The TPFCS database will handle collection sizes from 0 to 2 147 483 647 elements.

To relate the concept to familiar terms, you might say that an element could be a record, a file could be a collection, and a related set of files could be a data store. All of these files put together are the TPFCS database.

Figure 8 shows the general layout of a TPFCS database:

Figure 8. General Layout of a TPFCS Database


The following are some key points to remember about a TPFCS database:

Data Stores

A data store (DS) contains collections. A data store name is a maximum of 8 characters and can use printable special characters (for example: !, &, %, and *). Some data stores are created when TPFCS is initialized; others are user-defined and user-named by entering the ZOODB command (see Maintaining TPFCS).

The following are some important key points to remember about data stores:

Collections

The TPFCS database provides basic support for the following types of collections (whether they are persistent or temporary):

TPFCS uses the collection manipulation routines to maintain its own collections, just as any application would maintain collections. By using this support, it is possible for TPFCS database users to access and retrieve information from the collection without having to retrieve the entire collection.

The following are some key points to remember about collections:

Elements

An element is a subunit of a collection. The following are some key points to remember about elements:

Collection Support

Figure 9 shows an overview of the collection class hierarchy. The dashed boxes represent abstract classes and the solid boxes represent concrete classes (collection types) available with TPFCS. Solid lines between the classes represent logical inheritance of attributes and methods.

Figure 9. TPFCS Abstract Class Hierarchy


The following tables summarize collection support and can help you select the appropriate collection type for your application.

Table 14. Collection Support Summary - Part 1

Collection Keyed Duplicate Keys Duplicate Values Sort Fields Element Equality
Array No N/A Yes No No
Bag No N/A Yes No Yes
BLOB No N/A Yes No No
Key Bag Yes Yes Yes No No
Key Set Yes No Yes No No
Key Sorted Bag Yes Yes Yes No No
Key Sorted Set Yes No Yes No No
Keyed Log Yes No Yes No No
Log No N/A Yes No No
Sequence No N/A Yes No No
Set No N/A No No Yes
Sorted Bag No N/A Yes Yes No
Sorted Set No N/A No1 Yes No
Note:
1 The sort field must be unique, but the rest of the data value may be nonunique.

Table 15. Collection Support Summary - Part 2

Collection Ordered Accessed Added Updated Deleted
Array By position (index) By position (index) At the end By position (index) N/A (zeros/elements)
Bag Randomly By value Randomly N/A By value
BLOB By position (index) By position (index) At the end By position (index) N/A (zeros/elements)
Key Bag Randomly By key Randomly N/A By key
Key Set Randomly By key Randomly N/A By key
Key Sorted Bag By key By key By key By key By key
Key Sorted Set By key By key By key By key By key
Keyed Log By arrival By key; by arrival position At the end, with a wrap N/A N/A
Log By arrival By arrival At the end, with a wrap N/A N/A
Sequence By arrival; by position By position (index) At the end, by position By position (index) By position (index)
Set Randomly By value Randomly N/A By value
Sorted Bag By field By field By field N/A* N/A*
Sorted Set By field By field By field N/A* N/A*
Note:
* Elements in this collection can only be updated or deleted using cursors.

Table 16. Collection Support Summary - Part 3

Collection Maximum Key Length Maximum Element Length1 Fixed Length Elements Required Variable Length Elements Supported
Array N/A 4000 bytes Yes No
Bag N/A 248 bytes No Yes
BLOB N/A 1 byte3 No Yes
Key Bag 248 bytes 1000 bytes No Yes
Key Set 256 bytes 1000 bytes No Yes
Key Sorted Bag 248 bytes 1000 bytes No Yes
Key Sorted Set 256 bytes 1000 bytes No Yes
Keyed Log 256 bytes 4000 bytes Yes No
Log N/A 4000 bytes Yes No
Sequence N/A 4000 bytes No Yes
Set N/A 256 bytes No Yes
Sorted Bag 2482 bytes 1000 bytes No No
Sorted Set 2562 bytes 1000 bytes No No
Notes:
1
The element length does not include the length of a key, but it does include the length of a sort field.
2
The 248- and 256-byte lengths shown here are for sort fields, not keys.
3
A BLOB can also be considered to have a single element that is 2 GB.

Collection Examples

This section lists TPFCS collections and provides an example of a potential application for each collection type. The examples can help you to understand the characteristics, behavior, and the overall capabilities of the collections.

Array

An array is an ordered collection of elements with no key. Element equality is not supported. The array elements are a fixed length and are accessed by relative position (index) in the array starting with index 1.

An example of using an array is a program for keeping track of seat assignments on an airplane. The program addresses array elements by using the seat number as an index to the corresponding entry in the array. When the seat is assigned, the name of the passenger is entered into the entry using the seat number as the index. You can determine the name of the passenger assigned to a specific seat by accessing the entry of the array indexed by the seat number. However, you cannot determine empty seats except by iterating through the array and testing for an empty entry.

Bag

A bag is an unordered collection of elements with no key. Nonunique elements having the same value are supported. This collection allows duplicate elements. The elements can have a maximum length of 248 bytes. A request to add an element that already exists will add the element again.

An example of using a bag is a program for tracking supplies in a medical supply room. Each time you spot a supply in the medical supply room, you enter the name of the supply into the collection. If you spot a supply twice during an observation period, the supply is added twice because a bag supports nonunique elements. You can locate the name of a supply that you have observed and you can determine the number of observations of that supply; however, you cannot sort the collection by supply (because a bag is an unordered collection). To sort the elements of a bag, use a sorted bag collection instead.

BLOB

A BLOB, sometimes referred to as a byte array, is a special array collection of elements with an element size of 1 byte. Element equality is not supported. The BLOB elements are addressed by relative byte address (RBA) starting with byte 1. With BLOBs, multiple operations can be performed on ranges of elements and data can be read in its entirety or part by part.

An example of using a BLOB is a program for keeping track of a patient's X rays. The X ray must be available to be read or updated in its entirety or part by part. Each patient X ray is stored in the data store as a BLOB and can be directly addressed.

Key Bag

A key bag is an unordered collection of elements that have a key. Multiple copies of the same key are supported. The element value associated with the key is not relevant and the key is not part of the element data.

An example of using a key bag is a program that tracks assignments of dormitory suites. The element key is the number that is printed on the back of each key. Each element also has data members for the student name, student ID number, dormitory location, and so on. When you arrive at college, you are given one of the available keys, and your name, student ID number, and the dormitory location are entered into the collection. Because a given number on a key may appear on several keys, the program allows the same key number to be added to the collection many times. When you return a key because you are leaving the dormitory, the program finds each element whose key matches the serial number of your key and deletes one such element that has your name associated with it.

Key Set

A key set is an unordered collection of elements that have a unique key. Element equality (where all data members of both elements are equal) is not supported, and only elements with unique keys are supported. The key is not part of the element data. Requests to add an element whose key already exists result in an error return.

An example of using a key set is a program that allocates rooms to patrons checking into a hotel. The room number serves as the key of the element and the patron's name is a data member of the element. When you check in at the front desk, the clerk pulls a room key from the board and enters the number of the key and your name into the collection. When you return the key at checkout time, the record for that key is removed from the collection. You cannot add an element to the collection that is already present because there is only one key for each room. If you attempt to add an element that is already present, the function returns an error to indicate that the element was not added because of duplicate keys.

Key Sorted Bag

A key sorted bag is an ordered collection of elements that have a key. Elements are sorted according to the value of their key field, but the key is not part of the element data. Element equality is not supported while nonunique elements are. The maximum element size is 1000 bytes and the maximum sort field is 248 bytes.

An example of using a key sorted bag collection is a program that maintains a list of zip codes (for marketing purposes), sorted by the number of people in each zip code. The key is the zip code. You can add an element whose key is already in the collection (because two people can have the same zip code), and you can generate a list of people sorted by zip code; however, you cannot locate a person except by their key because a key sorted bag does not support element equality.

Key Sorted Set

A key sorted set, sometimes referred to as a dictionary, is an ordered collection of elements that have a key. Elements are sorted according to the value of their key field but, the key is not part of the element data. Element equality is not supported and only elements with unique keys are supported. Requests to add an element whose key already exists result in an error return.

An example of using a key sorted set is a program that keeps track of canceled credit card numbers and the individuals to whom they are issued. Each card number occurs only once and the collection is sorted by card number. When a merchant enters a customer's card number into a point-of-sale (POS) terminal, the collection is checked to see if that card number is listed in the collection of canceled cards. If the card number is found, the name of the individual is shown and the merchant is given directions for contacting the credit card company. If the card number is not found, the transaction can proceed because the card is considered to be valid. A list of canceled cards is printed out each month, sorted by card number, and distributed to all merchants who do not have an automatic POS terminal installed.

Keyed Log

The elements in a keyed log collection are ordered by arrival sequence; when the collection is full, the collection wraps and starts overlaying elements at the start of the collection. The keyed log consists of an element and key, where the key is a field contained in the element, and is not part of the element data. The keyed log assumes that the elements are a fixed length and are accessed by relative position (index) in the keyed log starting with index 1. The key can be used to access the collection to retrieve the element. There is no order to the keys of the collection.

Element fields other than the key field may be duplicated. If the key field is not unique, the add to the collection request will fail with an error return code. The elements can be a maximum length of 4000 bytes. The maximum key length is 256 bytes. For a keyed log collection, the first element is always the oldest entry still in the collection and the last element is the last to be added to the collection. Elements cannot be removed from a keyed log collection. The keyed log collection supports both access by position and by element key.

An example of using a keyed log collection is a program for tracking an account closing balance over the last 90 days. The keyed log collection would allow key access to specific dates over the 90 days being tracked. After 90 days, the collection is full and will begin overlaying transactions at the start of the collection.

Log

The elements in a log collection are ordered by arrival sequence; when the collection is full, the collection wraps and starts overlaying elements at the start of the collection. For a log collection, the first element is always the oldest entry still in the collection and the last element is the last to be added to the collection. The log assumes that the elements are a fixed length and are accessed by relative position (index) in the log starting with index 1. Elements cannot be removed from a log collection. The elements can have a maximum length of 4000 bytes.

An example of using a log collection is a program for tracking an account closing balance over the last 90 days. After 90 days, the collection is full and will begin overlaying transactions at the start of the collection.

Sequence

A sequence is a collection of elements with no keys. The elements are ordered by the arrival of requests. Element equality is not supported, while nonunique elements are supported. The type and value of the elements have no effect on the behavior of the sequence collection. Elements can be added and deleted from any position in the collection, can be retrieved or replaced. A sequence collection does not support element equality or a key.

An example of a sequence collection is a program that maintains a list of the words in a paragraph. The order of the words is obviously important; you can add or remove words at a given position, but you cannot search for individual words except by iterating through the collection and comparing each word to the word you are searching for. You can add a word that is already present in the collection because a given word may be used more than once in a paragraph.

Set

A set is an unordered collection of elements with no key. Element equality is supported and the values of the elements are relevant. Only unique elements are supported. A request to add an element that already exists is ignored.

An example of a set is a program that creates a packing list for a box of free samples to be sent to a warehouse customer. The program searches a database of in-stock merchandise and selects 10 items at random whose price is below a threshold level. Each item is then added to the set. The set does not allow an item to be added if it is already present in the collection, ensuring that a customer does not get two samples of a single product. The set is not sorted and elements of the set cannot be located by key.

Sorted Bag

A sorted bag collection is an ordered collection of elements with no key. Element equality is not supported, while nonunique elements are supported. Elements are sorted according to the value of their sort field, which is part of the element data. Nonunique elements are supported and a request to add an element that already exists will add the element again. The maximum element size is 1000 bytes and the maximum sort field is 248 bytes.

An example of using a sorted bag collection is a program for entering observations on the types of stones found in a riverbed. Each time you find a stone on the riverbed, you enter the mineral type of the stone into the collection. You can enter the same mineral type for several stones because a sorted bag collection supports nonunique elements. You can search for stones of a particular mineral type and you can determine the number of observations of stones of that type. You can also display the contents of the collection, sorted by mineral type, if you want a complete list of observations made to date.

Sorted Set

A sorted set collection is an ordered collection of elements with no key. Elements are sorted according to the value of their sort field, which is part of the element data. Element equality is not supported, while unique elements are supported; and a request to add an element that already exists will result in an error. The maximum element size is 1000 bytes and the maximum sort field is 256 bytes.

An example of using a sorted set collection is a program that tests numbers to see if they are prime. Two complementary sorted sets are used: one for prime numbers and one for nonprime numbers. When you enter a number, the program first looks in the set of nonprime numbers. If the value is found there, the number is nonprime. If the value is not found there, the program looks in the set of prime numbers. If the value is found there, the number is prime. Otherwise, the program determines whether the number is prime or nonprime and places it in the appropriate sorted set. The program can also display a list of prime or nonprime numbers beginning at the first prime or nonprime number following a given value because the numbers in a sorted set are sorted from smallest to largest.

Data Definitions

A data definition (DD) is an integral part of a collection definition. It provides characteristics for collections in a data store.

The following are some key points to remember about data definitions:

Property Service

The TPFCS database supports a property service for persistent collections that are created. Properties are essentially typed named values that you can dynamically associate with an already existing persistent collection. Once these properties are defined, they can be named, their values can be set and obtained, their access modes can be set, and they can be deleted. These operations can be performed by using either the ZBROW PROPERTY command or the TPFCS property APIs.

The typed named values are:

Typed Name Value
Description

TO2_PROPERTY_CHAR
1-byte value.

TO2_PROPERTY_LONG
4-byte value.

TO2_PROPERTY_DOUBLE
8-byte value.

TO2_PROPERTY_STRING
C character string (maximum 256 bytes).

TO2_PROPERTY_STRUCT
Structure (maximum 1000 bytes).

The property service defines four mutually exclusive property modes:

NORMAL
The property can be read, changed, or deleted (there are no restrictions).

NOCHANGE
The property can only be read and deleted. It cannot be changed.

NODELETE
The property can be read or changed but it cannot be deleted. A NODELETE property mode is deleted only when the target collection is deleted.

READONLY
The property can only be read. It cannot be changed or deleted. A READONLY property mode is deleted only when the target collection is deleted.

Collection Lifetimes

TPFCS provides the following collection lifetimes:

Persistent long-term
Exists beyond the life of the creating ECB, resides on DASD in 4-KB long-term pools, and can survive a re-IPL. TPFCS reuses its own long-term pool addresses so applications do not flush through pool records too quickly, causing the TPF system to run out of long-term pool records.

TPFCS reuses long-term pool records by maintaining a table for each subsystem. Each table is large enough to hold 100 file addresses. When TPFCS decides to return a long-term pool record, rather than release it to the system, it stores the file address of the record in the appropriate table if the following conditions are met:

If any of these conditions are not met or if the record is a short-term pool, the record is released to the system and its address is not stored in the table. When TPFCS needs to obtain a new long-term pool record, before allocating one using the GETFC macro, it looks in the appropriate table for a pool record it can reuse and then removes that entry from the table. Additionally, when TPFCS recoup starts, it releases all file addresses from each subsystem table and removes them.

Persistent short-term
Exists beyond the life of the creating ECB, resides on DASD in 4-KB short-term pools, and can survive a re-IPL. Persistent short-term collections are distinguished from persistent long-term collections by assigned record IDs and their RIAT attributes. Because the collection resides in short-term pools, it will be deleted when the short-term pools are recycled.

Temporary
Resides in the private heap area of the ECB and overflows to short-term pools. It is deleted when the ECB exits because the private heap area of the ECB is reclaimed by the system when the ECB exits. In order for the resources to be reclaimed correctly by the system, the collection should be explicitly deleted by the application before the ECB exits. This allows any overflow to short-term pools to be released and returned to the short-term pool directories for possible reuse.

The lifetime for a collection is established when the collection is created and cannot be subsequently changed. A collection lifetime is specified by selecting the appropriate collection creation API and data definition.

Deleting Collections

When you define a data store using the ZOODB DEFINE command, you can specify the disposition of deleted collections; that is, whether the collection deletion will be delayed 48 hours or whether the collection will be deleted immediately. If the deletion is delayed, collections can be reclaimed until the actual deletion takes place using the ZBROW COLLECTION command or the TO2_reclaimPID function. See Maintaining TPFCS and the TPF C/C++ Language Support User's Guide for more information.

Entering the ZBROW COLLECTION command with the EMPTY parameter specified on a DS_DELETED collection forces delayed deletions to occur for the particular data store. See TPF Operations for more information about the ZBROW COLLECTION command.

Data Store Application Dictionary

Each data store contains a dictionary automatically created by TPFCS that is available for use by the application. This dictionary is known as the data store application dictionary and is assigned the name DS_USER_DICT. This dictionary is accessed by establishing an environment for the target data store and using the TO2_...DSdict... type functions. The dictionary uses EBCDIC keys of 64 bytes with data elements of 1000 bytes.

One suggested use for the application dictionary is to place the PIDs of data store anchor collections in the dictionary and to assign a symbolic name to each one as the key.

Note:
When PIDs are stored in collection elements, a recoup index must be established and associated with that collection.

The application dictionary of TPFDB, the base TPFCS data store, can be accessed with a special set of functions (TO2_...TPF...). This allows all applications access to a common dictionary without needing to establish an environment for a particular data store. A possible use for this dictionary is to associate applications with data stores.

Note:
The data store system dictionaries, accessed with the TO2_...DSsystem... and TO2_...TPFsystem... type functions, are used by the TPFCS system and are not intended to be used by applications.