gtpd1m24 | Database Reference |
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:
The cursor provides methods that allow an application program to move through a collection one element at a time without needing keys or indexes. See Using Iterative Operations over Collections for more information.
To prevent concurrent updating of a collection while you are accessing elements in the collection, you can establish a locking cursor. When a locking cursor is created for a particular collection, a lock is placed on the entire collection so that only the ECB that created the cursor can update the elements in the collection. See Concurrency Controls for more information.
For certain types of collections, cursors allow you to either access a particular element using a field other than the primary key or sort field, or to iterate through a collection in an order other than that determined by the primary key or sort field. These tasks involve the use of alternate key paths, which can only be used by cursors. See Using Key Paths for more information.
It is more efficient to access multiple elements in a collection by using a cursor. Most TPFCS functions are atomic; that is, the element is read into storage, managed, and removed from storage for each function call. This type of processing requires much overhead. With cursors, once a collection is read into storage, it remains there for the life of the cursor. The cursor is temporary and must be deleted by the application program or when the ECB exits.
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.
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.
TPFCS supports primary and alternate key paths for the following persistent keyed and sorted collections:
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.