gtpc2mey | C/C++ Language Support User's Guide |
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.
Format
#include <to2.h> long TO2_addAtCursor (const TO2_PID_PTR cursorPidPtr, TO2_ENV_PTR env_ptr, const void *data, const long *dataLength);
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