gtpa2m1yApplication Programming

Key Path Support

Key path support enables you to search for and access data in a collection by using the value of a specified data field or key.

TPFCS supports two types of key paths, primary and alternate, 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.

Primary key paths are sorted in ascending binary value by the primary key, and they can be either unique or nonunique depending on the collection type. Alternate key paths support nonunique key path fields (keys) and are sorted in ascending binary value based on the key path field. A maximum of 16 alternate key paths (in addition to the primary key path) can be defined one at a time for each collection.

Atomic functions (APIs) such as TO2_atKey, TO2_atKeyPut, TO2_atNewKeyPut, and TO2_removeKey use only the primary key path for accessing data. You can use alternate key paths only with cursors. The application program can use a cursor to access primary or alternate key paths. To use a key path, the application program creates a cursor by using either the TO2_createCursor or TO2_createReadWriteCursor function. Initially, the cursor uses the primary key path by default. The application can change the key path and assign an alternate key path to the cursor by using the TO2_setKeyPath function and specifying a key path name.

The application program can also issue a TO2_setKeyPath call with the TO2_PRIME_KEYPATH name to reset the cursor to use the primary key path.

While the key path build process is in progress, the TO2_ERROR_KEYPATH_BUILD_ACTIVE error code is returned. The specified key path is not usable until the build process has ended.

Adding Key Paths

Primary key paths are automatically established when a collection is created in a TPFCS database. Alternate key paths are added to a collection by using the TO2_addKeyPath function. Using the TO2_addKeyPath function, the application program specifies the name of the new key path and the displacement and length of the field in the data element that the key path will reference. If a particular data element is too short to contain the entire field, it will still be included in the key path as if bytes of zero were concatenated at the end for the remaining length of the key.

Key paths are built automatically by an asynchronous task if the collection already exists and contains data elements. The key path is not usable until the build process has completed successfully.

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.

Removing Key Paths

To remove an alternate key path from the collection, the application program issues a TO2_removeKeyPath request specifying the name of the key path to remove. The TO2_removeKeyPath function deletes the key path from the collection and releases the resources of the key path back to the system.

Note:
You cannot remove the primary key path from a collection.