gtpc2meyC/C++ Language Support User's Guide

TO2_addAtCursor-Insert an Element in a Sequence Collection

This function inserts the specified data in the collection at the current position of the cursor. Inserting an element into a sequence collection causes the relative positions of all elements following the inserted element to be increased by one position. The TO2_addAtCursor request sets the update sequence counter of the element to zero.

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

Format

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

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 element that will be stored in the collection.

dataLength
The pointer to an area that contains the maximum length of the element that will be stored. Elements must be less than or equal to the specified size when the collection was created.

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_EODAD

TO2_ERROR_DATA_LGH

TO2_ERROR_ENV

TO2_ERROR_METHOD

TO2_ERROR_NOT_INIT

TO2_ERROR_PID

TO2_ERROR_UPDATE_NOT_ALLOWED

TO2_ERROR_ZERO_PID

Programming Considerations

The TO2_addAtCursor function can only be used to insert an element at the beginning of the collection, between two already existing elements, or as the last element. For example, if you have 10 elements in a collection, you can use the TO2_addAtCursor function to add the first through the 11th element to the collection, but you could not add the 25th element because no elements exist between 12 and 24. On return, the cursor will be positioned to point to the inserted element. So, if the next call was a TO2_atCursor function, the returned element would be the inserted element.

Examples

The following example adds an item to a sequence collection at the current position of the cursor.

#include <c$to2.h>                /* Needed for TO2 API functions    */
#include <stdio.h>                /* APIs for standard I/O functions */
 
TO2_ENV_PTR    env_ptr;           /* Pointer to the TO2 environment  */
TO2_PID        cursorPID;         /*  PID stored here on cursor      */
                                  /*  create.                        */
char           item[] = "Item A"; /* data                            */
long           itemsiz;

  ·
  ·
  ·
/*********************************************************************/ /* Make sure that the bag is created before arriving here... */ /*********************************************************************/ itemsiz = sizeof(item); if (TO2_addAtCursor(&cursorPID, env_ptr, item, &itemsiz) == TO2_ERROR) { printf("TO2_addAtCursor failed!\n"); process_error(env_ptr); } else { printf("TO2_addAtCursor successful!\n"); }

Related Information