gtpa2m1tApplication Programming

Application Characteristics

This section provides information about some of the characteristics that are unique to TPFCS application programs.

TPFCS Environment Block

To access TPFCS data stores and collections, the application must do the following:

Calling the TO2_createEnv function accomplishes all of these goals.

The TO2_createEnv function is issued once by each ECB for each data store in the database that is accessed by that ECB. In other words, if the application will be creating collections in multiple data stores, the application will have to issue a TO2_createEnv for each data store. The environment block that is created is built in ECB private storage and, therefore, cannot be shared among ECBs and its pointer cannot be saved to be used by other ECBs.

A pointer to the environment block is returned by the TO2_createEnv function so that your application can access the database. The environment block that is created is used on almost all the TPFCS function calls. The collection creation functions (TO2_create...) use the environment block to determine in which data store to create the collection.

Because the TPFCS system can usually determine the correct data store to work with from the persistent identifier (PID) of the collection, the data store of the environment passed to a function call does not need to be the same as the data store in which the collection was created. For example, an environment could be created with the TPFDB data store and be used by an application to access any collection already created in any data store. However, if a target collection PID is not included on a function call (such as with the TO2_atDSdictKey function), the appropriate data store environment must be used.

When the ECB has completed accessing the TPFCS database, enter a TO2_deleteEnv function call to allow TPFCS to clean up and release any allocated system resources that it is still holding.

Type Definitions

The following type definitions are found in the c$to2.h header file:

TO2_ENV_PTR
This type is defined as a pointer to void. A variable of this type is set by calling the TO2_createEnv function and passing a pointer to this pointer. It is set by TPFCS to point to the environment block, which is used on almost all TPFCS API calls.

TO2_PID
This type defines the TPFCS PID assigned to a collection when it is created and then used to reference to the collection until it is deleted from the TPFCS database.

TO2_PID_PTR
This type is defined as a TO2_PID pointer and should be set to point to a variable of type TO2_PID.

TO2_BUF_HDR
This type defines the returned TPFCS data buffer header returned on an element retrieval using such TPFCS functions as TO2_at, TO2_atKey, TO2_atCursor, and TO2_key. See Returned Data Structures for the format of the buffer.

TO2_BUF_PTR
This type is defined as a TO2_BUF_HDR pointer.

TO2_ERR_CODE
This type is defined as a long integer that, on return from a TO2_getErrorCode function call, contains the actual error code value that is stored in the environment.

TO2_ERR_TEXT_PTR
This type is defined as a char pointer and is returned from a TO2_getErrorText call. It will point to text that describes the actual error that occurred.

Error Handling

When a TPFCS function is successful, it returns a positive value to the application program. When an error occurs in an attempt to process a TPFCS function, TPFCS sets an error code in the environment block and returns TO2_ERROR (which is defined as zero) to the application program. Once the application identifies that an error has occurred, it can query the environment block using the TO2_getErrorCode function to determine the specific error that has occurred. If additional text describing the error is desired, the error code can be passed to the TO2_getErrorText function. Error processing is handled the same way regardless of the type of function being called. See Types of Functions for more information.

Note:
The error code in the environment block is not reset until another error occurs or a Boolean-type request is entered that returns TO2_IS_FALSE.

For more information about error codes, see the TPF C/C++ Language Support User's Guide.

Boolean Error Handling

By convention, TPF API return codes indicate successful or unsuccessful completion by returning positive or zero values, respectively. This convention is violated somewhat by TPFCS API functions returning positive or zero values for true or false results, respectively.

To distinguish an unsuccessful API return code from a Boolean zero result, use the TO2_getErrorCode function call for error value retrieval. A zero error code value indicates a successful return of TO2_IS_FALSE while a nonzero error code value indicates an error return from the Boolean API function.

The following logic might be used in an application program to test for an error on a Boolean function:

  1. Call a Boolean TPFCS API; for example:
    TO2_isEmpty
    

    If a value of TO2_ERROR (0) is returned, this indicates that either an error has occurred or a value of TO2_IS_FALSE has been returned. If a value of TO2_IS_TRUE is returned, this indicates that no error has occurred.

  2. Call the following TPFCS API to retrieve the error code value:
    TO2_getErrorCode
    

    If a value of TO2_IS_FALSE (0) is returned, this indicates that no error has occurred. All other values returned from TO2_getErrorCode indicate the error that occurred.

  3. If an error has occurred, you can optionally call the following TPFCS API to retrieve the error code message text for the returned value:
    TO2_getErrorText
    

Example of a Returned Error Code

When an error occurs in the attempt to process a function, TPFCS sets an error code in the environment block and returns a 0 to the application program. The following example shows how an application can check to see if an error occurs when calling a Boolean TPFCS function.

#include <c$to2.h>                /* Needed for TO2 API Functions     */
#include <stdio.h>                /* APIs for standard I/O functions  */
TO2_PID             cursor;
TO2_ENV_PTR         env_ptr;
TO2_ERR_CODE        err_code;     /* TO2 error code value             */
TO2_ERR_TEXT_PTR    err_text_ptr; /* TO2 error code text pointer      */

  ·
  ·
  ·
/**********************************************************************/ /* Are there more elements after the current one? */ /**********************************************************************/ if (TO2_more(&cursor,env_ptr) == TO2_ERROR) { err_code = TO2_getErrorCode(env_ptr); if (err_code != TO2_IS_FALSE) { printf("TO2_more failed!\n"); err_text_ptr = TO2_getErrorText(env_ptr, err_code); printf("The error is: %s\n", err_text_ptr); } else printf("There are no more elements after the current element.\n"); } else printf("There are more elements after the current element.\n");

Data Store Application Dictionary

To access a collection, the application must determine the PID of the collection. The recommended approach is to place the PIDs of data store anchor collections in the data store application dictionary and assign a symbolic name to each one as the key. This dictionary, which has the preassigned name of DS_USER_DICT, is accessed by establishing an environment for the target data store and using the TO2_...DSdict... type functions. For example, you can use the TO2_atDSdictNewKeyPut function to store the PID of an anchor in the dictionary. You can retrieve the PID of an anchor with the TO2_atDSdictKey function. The dictionary uses EBCDIC keys of 64 bytes with data elements of up to 1000 bytes.

Note:
When PIDs are stored in collection elements, a recoup index must be established and associated with that collection, including the application dictionary.

The TPF dictionary (the application dictionary of TPFDB, the base TPFCS data store) can be accessed with a special set of functions (TO2_...TPF...). This allows all applications access to a common dictionary without needing to establish an environment for a particular data store. A possible use for this dictionary is to associate applications with data stores.

Note:
The data store system dictionaries, accessed with the TO2_...DSsystem... and TO2_...TPFsystem... type functions, are used by the TPFCS system and are not intended to be used by applications.

Application Startup Examples

The examples in this section describe the steps that could be followed for initial population of a data store and for application startup.

Initial Population of a Data Store

When a data store is first created, the startup flow for an application that initially populates the data store could be as follows:

  1. Create the environment using the target data store name on the TO2_createEnv function.
  2. Create a recoup index for the application dictionary using the TO2_createRecoupIndex function.
  3. Add a recoup index entry to the index describing how PIDs are stored in the dictionary using the TO2_addRecoupIndexEntry function.
  4. Get the PID of the application dictionary using the TO2_getDSdictPID function.
  5. Associate the recoup index with the dictionary by using the TO2_associateRecoupIndexWithPID function (see TPF Database Reference for more information).
  6. Create an anchor collection using a TO2_create... function.
  7. Store the PID of the anchor collection in the application dictionary by using the TO2_atDSdictNewKeyPut function. The key could be a symbolic name for the collection or any other value.
  8. Optionally assign a name to the collection so that the collection can be easily accessed with the browser functional messages by using the TO2_defineBrowseNameForPID function. Consider using the same symbolic name used to store the PID in the application dictionary.

Optionally, you can associate particular applications with this data store by doing the following:

  1. Create an environment using TPFDB as the data store name.
  2. For each application that will use this data store, store the data store name in the TPF application dictionary using the TO2_atTPFNewKeyPut function with the name of the application as the key.
  3. Enter a TO2_deleteEnv call to delete the environment.

Application Startup Flow

The startup flow for a typical application could be as follows:

  1. Create the environment using the target data store name on the TO2_createEnv function.
  2. Access the TPF application dictionary to read the data store name of this application using the TO2_atTPFKey function.

    Make the following assumptions:

  3. Enter a TO2_deleteEnv call to delete the TPFDB environment because it is not needed again to access TPFDB.
  4. Create a new environment using the retrieved data store name.
  5. Retrieve the PID of an anchor collection from the application dictionary by using the predetermined key on the TO2_atDSdictKey function.
  6. Continue with the remainder of the application processing.
  7. When processing has been completed, enter a TO2_deleteEnv call to delete the environment.