gtpa2m1vApplication Programming

Collection APIs

TPFCS provides APIs for performing certain operations on a collection. This section describes the types of operations that can be performed on a collection.

Creating and Deleting Collections

When you create the collection instance, you do so by calling the appropriate TO2_create... function for the instance you want. There is a unique create function for each TPFCS collection type. The TO2_create... function returns the PID assigned to the collection.

Several different options can be selected when creating collections using the TO2_create...WithOptionList type APIs and specifying customized data definitions. These options include:

For more information about collection lifetimes, see TPF Database Reference.

You can delete collections dynamically by using the TO2_deleteCollection function. After you enter the TO2_deleteCollection function, the collection is either marked for deletion or actually deleted from the database and cannot be accessed by other TPFCS functions. For persistent short-term collections and temporary collections, the deletion always takes place immediately. For persistent long-term collections, the deletion is controlled by the data store characteristics set with the ZOODB command. A persistent long-term collection marked for deletion can be reclaimed by entering the TO2_reclaimPID function in the time period between the TO2_deleteCollection request and the time the actual deletion occurs (48 hours).

Accessing and Modifying Collections

You can perform the following operations to modify a collection:

Modification
Operation

 Adding elements 
Use the TO2_add function and its variants.

 Finding and retrieving elements 
Use the TO2_at function and its variants.

 Updating elements 
Use the TO2_atPut function and its variants.

 Removing elements 
Use the TO2_remove function and its variants.

Adding Elements

For nonkeyed collections, the TO2_add function places the element identified by its argument into the collection. For keyed collections, the TO2_atNewKeyPut function places the element identified by its key into the collection. See TPF C/C++ Language Support User's Guide for more information about the TO2_add and TO2_atNewKeyPut functions. For binary large objects (BLOBs), you can operate on elements using the TO2_atRBAPut function. In general, you can copy one collection to another collection that is initially empty by iterating through the elements of the first collection and calling TO2_add or TO2_atNewKeyPut with each element as an argument.

For sequence collections, elements can be added at a given position using TO2_addAtIndex.

Table 13 describes how the TO2_add and TO2_atNewKeyPut APIs function with unique and nonunique collections:

Table 13. Adding Elements to a Collection

Type of Collection Description
Unique collections without keys The TO2_add function will not add an element that is equal to an element that is already in the collection.
Nonunique collections without keys The TO2_add function adds elements regardless of whether they are equal to any existing elements.
Unique collections with keys The TO2_atNewKeyPut function will not add a key that is equal to a key that is already in the collection.
Nonunique collections with keys The TO2_atNewKeyPut function adds keys regardless of whether they are equal to any existing keys.

Finding and Retrieving Elements

You can find an element without using a cursor by searching for it based on position or key by using the TO2_at, TO2_atKey, and TO2_atRBA function. In arrays, BLOBs, keyed logs, logs, or sequence collections, elements are addressed by their index. The index of the first element is always 1; that is, they are 1-based. Elements in these types of collections are accessed using the TO2_at API (data in BLOBs are accessed using the TO2_atRBA API). For keyed collections, an element can be addressed by its key using TO2_atKey. For collections without unique keys, such as key bags, only the first element with the given key can be explicitly addressed. In collections such as bags, sets, and sorted bags, elements have no address component and, therefore, cannot be individually selected except through the use of cursors (see Cursors). Once you have found and retrieved the element, you can update it and then replace it.

Updating Elements

It is possible to modify collections by updating the value of an element occurrence. The maximum length of the updated element cannot be changed; however, elements can be shorter than the specified maximum length.

The key or element value that must be preserved is called the positioning property of the element in the given collection. For nonkeyed collections with element equality (bags and sets), an update function is not provided. Element equality is a condition where two elements in a single collection are equal in length and equal in bit sequence. To change an element for a nonkeyed collection, the old element must be removed and the new element added to the collection.

For sorted collections that are organized according to an element property (the sort field), if the update function changes this element property, the old element is automatically deleted and the new updated element is automatically placed in its correct position in the collection.

Arrays, BLOBs, keyed logs, logs, and sequence collections do not have a positioning property; that is, instead of having a key that can be preserved or element value, they have a logical position that is independent of the content of the element. Element values in these collections can be changed freely using the TO2_atPut function.

Update sequence counter

As a form of database integrity for those collections that allow element updating, an update sequence counter is stored in each element in a given collection and optimistic concurrency is enforced on the element during update processing. For more information, see Optimistic Concurrency (Update Sequence Counter).

Removing Elements

To remove elements from a collection, you can either use a specific remove-type function (TO2_removeIndex, TO2_removeValue, or TO2_removeKey) or you can remove an element that is pointed to by a given cursor (see Using Cursors for Locating, Accessing, and Removing Elements).

There is an important difference between element values and element occurrences. An element value may, for nonunique collections, occur more than once. The basic remove-type function removes only the first occurrence of an element. If you want to remove all occurrences of the elements in a collection that have a given property, use the TO2_removeValueAll function.

For collections with key equality or element equality, removal functions remove one or all occurrences of a given key or element. Sequence collections provide functions for removing an element at a given index.