gtpc2mf1C/C++ Language Support User's Guide

TO2_atCursorPut-Store Element Where Cursor Points

This function replaces the element pointed to by the cursor with the specified data. If the cursor is pointing at the end of the last element and the collection is an array or a binary large object (BLOB), it will add the element. For other collections, it will result in an error.

Note:
This function does not support all collections. See Table 48 for collections that are supported for this function.

Format

#include <c$to2.h>
long TO2_atCursorPut (const TO2_PID_PTR  cursorPidPtr,
                            TO2_ENV_PTR  env_ptr,
                      const  void        *data,
                      const  long        *dataLength,
                      const  long        *updateSeqCtr);

cursorPidPtr
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.

data
The pointer to the data that will be stored in the element currently pointed to by the cursor.

dataLength
The pointer to the area that contains the length of the element that will be stored.

updateSeqCtr
The pointer to the area where the update sequence counter from a TO2_atCursor request has been stored when the element was read from the collection.

Normal Return

The normal return is a positive value. After the request is completed, the cursor points to the next position in the collection.

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_DATA_LGH

TO2_ERROR_ENV

TO2_ERROR_METHOD

TO2_ERROR_PID

TO2_ERROR_SEQCTR

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

The following example stores a data element where the cursor is currently pointing.

#include <c$to2.h>                 /* Needed for TO2 API functions   */
#include <stdio.h>
 
TO2_PID        cursor;
TO2_ENV_PTR    env_ptr;
TO2_BUF_PTR    buffer_ptr;
  .
  .
  .
/********************************************************************/
/* update the data element where the cursor is currently pointing   */
/********************************************************************/
if ( (buffer_ptr=TO2_atCursor(&cursor, env_ptr)) == TO2_ERROR)
{
   printf("TO2_atCursor failed!\n");
   process_error(env_ptr);
}
else
{
   /* modify buffer_ptr->data */
   if (TO2_atCursorPut(&cursor,
                       env_ptr,
                       buffer_ptr->data,
                       &buffer_ptr->dataL,
                       &buffer_ptr->updateSeqNbr) == TO2_ERROR)
   {
      printf("TO2_atCursorPut failed\n");
      process_error(env_ptr);
   }
   else
      printf("TO2_atCursorPut successful!\n");
   free(buffer_ptr);
}

Related Information