TO2_cursorPlus–Increment cursor to next element

This function increments the cursor to the next element in the collection.

Format

#include <tpf/c_to2.h>
int  TO2_cursorPlus (const TO2_PID_PTR cursorPidPtr,
                           TO2_ENV_PTR env_ptr);

cursorPidPtr: The pointer to the cursor persistent identifier (PID) created by one of the z/TPF collection support (z/TPFCS) create cursor application programming interfaces (APIs).
env_ptr: The pointer to the environment as returned by the TO2_createEnv function.

Normal return

The normal return is a positive value.

Error return

An error return is indicated by a zero. When zero is returned, use the TO2_getErrorCode function to determine the specific error code. For more information, see Error handling.

The following error codes are common for this function:

TO2_ERROR_CURSOR
TO2_ERROR_ENV
TO2_ERROR_EODAD
TO2_ERROR_METHOD
TO2_ERROR_PID
TO2_ERROR_ZERO_PID

Programming considerations

This function causes the cursor to be advanced to point to the next element in the collection. The next element is determined based on what type of collection is involved. If the cursor is currently pointing at the last element in the collection, a TO2_ERROR_EODAD error code will be returned.
This function does not use z/TPF transaction services on behalf of the caller.

Examples

The following example increments the cursor to point to the next element in the collection.

#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");

Related information

TO2_cursorMinus–Decrement Cursor to Previous Element.

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