gtpc2mbhC/C++ Language Support User's Guide

Retrieving Error Information

Use the following steps to retrieve error information:

  1. Enter a request; for example:
    TO2_copyCollectionTemp
    

    An error occurs and a zero is returned.

    Note:
    If no error is found, a positive value is returned.
  2. Enter the following to retrieve the error code value:
    TO2_getErrorCode
    
  3. Enter the following to retrieve the error code message text for the returned value:
    TO2_getErrorText
    

For more information about error codes, see Table 46.

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 FALSE while a nonzero error code value indicates an error return from the Boolean API function. This applies for the following APIs:

TO2_atEnd

TO2_atLast

TO2_more

TO2_includes

TO2_isEmpty

TO2_isCollection.

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

Error Handling

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. For example:

#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_code = TO2_getErrorCode(env_ptr); err_text_ptr = TO2_getErrorText(env_ptr, err_code); printf("err_text_ptr 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");