gtpc2mezC/C++ Language Support User's Guide

TO2_allElementsDo-Iterate over All Elements

This function causes the function pointed at to be called for every element in the collection starting at the current element pointed to by the cursor. The specified user-function will be called with a two-word parameter list. The first word will contain a pointer to a buffer containing the current element. The second word will contain the pointer to the parameter list (plist parameter) specified on the TO2_allElementsDo interface. The TO2_allElementsDo function will continue to process each element in the collection until either the end of the collection is found or the called function returns a TO2_ERROR_EODAD return code to the TO2_allElementsDo function.

Format

#include <c$to2.h>
long TO2_allElementsDo (const TO2_PID_PTR   cursor_ptr,
                              TO2_ENV_PTR   env_ptr,
                              long        (*functionPtr) (TO2_BUF_PTR, void *)
                              void         *plist);

cursor_ptr
The pointer to the cursor persistent identifier (PID) created by one of the TPF collection support (TPFCS) create cursor application programming interfaces (APIs).

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

functionPtr
The pointer to the function that will be called for each element of the collection starting at the current cursor position.

plist
The pointer to a parameter list that will be passed to the function on every call.

Normal Return

The normal return is 1.

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. If the collection is empty, a +1 is returned. For more information, see Error Handling.

The following error codes are common for this function:

TO2_ERROR_CURSOR

TO2_ERROR_ENV

TO2_ERROR_METHOD

TO2_ERROR_PID

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

#include <c$to2.h>
#include <stdio.h>
 
#define ERROR 0
#define OK    1
 
struct opt { int option1; char option2; };
 
int example(TO2_PID readCursor)
{
  struct opt options = { 5, 'a' };
 
  /********************************************************************/
  /* Set the cursor to the beginning of the collection.               */
  /********************************************************************/
 
  if (TO2_first(&readCursor, envPtr) == TO2_ERROR)
    return ERROR;
 
  /********************************************************************/
  /* Process all the elements of the collection.                      */
  /********************************************************************/
 
  if (TO2_allElementsDo(&readCursor, envPtr, displayLine, &options)
                                                           == TO2_ERROR)
  {
    /*-----------------------------------------------*/
    /* It's not an error if the collection is empty. */
    /*-----------------------------------------------*/
 
    if (TO2_getErrorCode(envPtr) != TO2_ERROR_EMPTY)
      return ERROR;
  }
  return OK;
}
 
/**********************************************************************/
/* Function called from TO2_allElementsDo to display the data from    */
/* the collection.                                                    */
/**********************************************************************/
 
static long displayLine(TO2_BUF_PTR buffer, void * plist)
{
  struct opt option_ptr = (struct opt *) plist;
 
  if (option_ptr->option2 == 'a')
    printf("option a: %s", buffer->data);
 
  return 0;
}

Related Information

None.