TO2_getErrorCode: Retrieve the error code value

This function retrieves the error code value from the environment after a reported z/TPF collection support (z/TPFCS) error.

Format

#include <tpf/c_to2.h>
TO2_ERR_CODE TO2_getErrorCode (const TO2_ENV_PTR env_ptr);

env_ptr: The pointer to the environment as returned by the TO2_createEnv function.

Normal return

The normal return is the error code from the environment.

Error return

Not applicable.

Programming considerations

By convention, application programming interface (API) return codes indicate successful or unsuccessful completion by returning positive or zero values respectively. This convention is violated somewhat by API functions returning positive or zero values for TO2_IS_TRUE or TO2_IS_FALSE results. To distinguish an unsuccessful API return code from a Boolean FALSE result, use the TO2_getErrorCode function to retrieve any stored return code value in the user environment. A TO2_IS_FALSE error code value indicates a successful return while a negative error code value indicates an error return from the Boolean API function.
An error in the environment is not reset until another error or a TO2_IS_FALSE condition occurs.

Examples

The following example retrieves the error code value from a z/TPFCS environment.

#include <tpf/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 */
⋮
/**********************************************************************/
/* Increment cursor to point to next element in the collection.       */
/**********************************************************************/
if (TO2_cursorPlus(&cursor, env_ptr) == TO2_ERROR)
{
  err_code = TO2_getErrorCode(env_ptr);
  if (err_code != TO2_ERROR_EODAD)
  {
  printf("TO2_cursorPlus failed!\n");
  process_error(env_ptr);
  }
  else
  printf("Cursor is already positioned at the last element.\n");
}
else
  printf("TO2_atCursorPlus successful!\n");

The following example tests to see if the cursor is pointing at the end of the collection.

#include <tpf/c_to2.h>                /* Needed for TO2 API Functions  */
#include <stdio.h>

TO2_PID             cursor;
TO2_ENV_PTR         env_ptr;
TO2_ERR_CODE        err_code;     /* TO2 error code value             */
⋮
/**********************************************************************/
/* Is the cursor pointing to the end of the collection?               */
/**********************************************************************/
if (TO2_atEnd(&cursor, env_ptr)) == TO2_IS_FALSE)
{
  err_code = TO2_getErrorCode(env_ptr);
  if (err_code != TO2_IS_FALSE)
  {
  printf("TO2_atEnd failed!\n");
  process_error(env_ptr);
  }
  else
  printf("Cursor is not pointing to the end of the collection.\n");
}
else
  printf("Cursor is pointing to the end of the collection.\n");

Related information

TO2_getErrorText: Retrieve the associated error text.

See z/TPF collection support: environment functions overview for more information about this function and z/TPF C/C++ language support.