gtpd1m23 | Database Reference |
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:
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:
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:
An element is a subunit of a collection. The following are some key points to remember about elements:
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 |
|
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* |
|
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 |
|
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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:
The property service defines four mutually exclusive property modes:
TPFCS provides the following collection lifetimes:
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.
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.
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.
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.
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.