gtpc2mbr | C/C++ Language Support User's Guide |
This function inserts the specified data in the collection at the specified relative index. The TO2_addAtIndex function sets the update sequence counter of the element to zero.
Format
#include <to2.h> long TO2_addAtIndex(const TO2_PID_PTR pid_ptr, TO2_ENV_PTR env_ptr, const long *index, 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_DATA_LGH
TO2_ERROR_ENV
TO2_ERROR_EODAD
TO2_ERROR_INDEX
TO2_ERROR_METHOD
TO2_ERROR_NOT_INIT
TO2_ERROR_PID
TO2_ERROR_UPDATE_NOT_ALLOWED
TO2_ERROR_ZERO_PID
Programming Considerations
Inserting an element into a sequence collection increases by one position the relative indexes of all elements following the inserted element. The TO2_addAtIndex function can only be used to insert an element at the beginning of the collection, between two already existing elements, or as the element immediately after the current last element.
Examples
The following example adds an item to a sequence collection at the specified relative index.
#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 seqCol; /* PID for the target collection */ char item =[] "Item A"; /* data */ long itemsiz; long index=5;
·
·
·
/*************************************************************************/ /* Assume that the ordered collection has already been created.. */ /*************************************************************************/ itemsiz = sizeof(item); if (TO2_addAtIndex(&seqCol, env_ptr, &index, item, &itemsiz) == TO2_ERROR) { printf("TO2_addAtIndex failed!\n"); process_error(env_ptr); } else { printf("TO2_addAtIndex successful!\n"); }
Related Information