gtpa2m1u | Application Programming |
The provided functions that make up the collection library are divided into three types:
A collection is a related group of elements organized within a data store. Collections are created by applications and may be temporary or persistent. The collection APIs allow collection creation and deletion and element manipulation and interrogation. Collections include abstractions such as array, set, bag, and key sorted set. Most TPFCS functions are atomic; that is, the element is read into storage, managed, and removed from storage for each function call.
Cursors provide you with convenient methods for accessing and iterating through the elements stored in the collections. The cursor APIs allow element manipulation and interrogation. Cursors can also be used to lock collections to prevent other users from updating a collection while you are accessing the elements in the collection. Furthermore, cursors allow parts of collections to stay in memory so that some repetitive or consecutive accesses do not require data to be constantly read from or written to DASD. It also allows you to use alternate key paths.
The auxiliary functions include dictionary, browser, and other miscellaneous functions:
For more information about TPFCS functions, see the TPF C/C++ Language Support User's Guide.
When TPFCS returns an element in response to a TO2_at, TO2_atCursor, TO2_peek, or other similar function (except for TO2_atRBA), it returns a data structure that resides in a private heap storage area. The calling routine must use the free function call to free the buffer once it has completed processing the returned data. When the function call includes the pointer to a buffer (for example, a TO2_atWithBuffer, TO2_atCursorWithBuffer or a TO2_peekWithBuffer function call), the data is also returned in the buffer.
The normal return from these types of APIs is a pointer (TO2_BUF_PTR) to a structure (buffer) of type TO2_BUF_HDR. The structure of this buffer has five fields: