gtpd1m24Database Reference

Cursors

A cursor is a nonpersistent internal structure associated with a collection that is used to reference an element in the collection. Cursors are used for the following:

Cursors can be used with any collection. If you use the cursor APIs to add or remove elements, cursor positioning remains valid unless an error occurs. If you use the collection (non-cursor) APIs on collections that have a cursor associated with them to add or remove elements, cursor positioning might not be valid. For more information about cursors, see TPF Application Programming.

Using Iterative Operations over Collections

Iterating over all or some elements of a collection is a common operation. TPFCS gives you two methods of iteration:

Some ordered collections, such as an array or sequence collection, are easy to traverse because elements can be referenced by a numerical position. However, other ordered collections, such as key sorted sets and sorted bags, cannot be easily traversed without advance knowledge of the key and sort values. Unordered collections, such as bag and key set, also cannot be easily traversed. Using one of the two TPFCS methods of iteration allows all elements to be visited exactly once. For unordered collections, there is no defined order in which the elements are visited, but each element is still visited exactly once. If you add or remove elements from a collection while you are iterating over a collection (except by using the cursor doing the iteration), all elements may not be visited once. See TPF Application Programming for information about adding and removing elements.

Using Key Paths

TPFCS supports primary and alternate key paths for the following persistent keyed and sorted collections:

Note:
Sorted bag and sorted set collections do not have primary keys; they only have sort fields.

A key path establishes the order in which elements will be sequentially accessed when iterating through a collection using a cursor. There are two types of key paths: primary and alternate. When a collection is first created, the primary key path of the collection is used by default for searching and accessing data. After the key path has been defined, TPFCS will automatically update it whenever the collection is updated. Therefore, collections with alternate key paths will take longer to update because they have to maintain the internal structures of every key path.

You can use the TO2_setKeyPath function to override the default setting or any previous TO2_setKeyPath function calls to specify an alternate key path. A maximum of 16 alternate key paths (in addition to the primary) can be defined for each collection. When the TO2_setKeyPath function call is issued, the position of the cursor must be reestablished by using one of the positioning functions, such as TO2_first.

See TPF Application Programming for information about adding, using, and removing alternate key paths or the TPF C/C++ Language Support User's Guide for information about the TO2_first or TO2_setKeyPath function.