gtpc2mbp | C/C++ Language Support User's Guide |
This function adds the specified data to the collection at the position
appropriate for the type of collection being added:
- Type
- Position
- Array
- Appends the element to the current end of the collection.
- Bag
- Adds the element to the collection.
- BLOB
- Appends the data to the current end of the collection.
- Key Bag
- Not supported.
- Key Set
- Not supported.
- Key Sorted Bag
- Not supported.
- Key Sorted Set
- Not supported.
- Keyed Log
- Appends the element to the logical end of the collection and updates the
secondary index with the key field value. The secondary index is a
user-defined key field that can be used for searching.
- Log
- Appends the element to the logical end of the collection.
- Sequence
- Appends the element to the current end of the collection.
- Set
- Adds the element to the collection after checking to make sure the element
is not a duplicate.
- Sorted Bag
- Adds the element to the collection in the correct sequence
position. Elements with the same sort field values are added in a
first-in-first-out (FIFO) order in the collection.
- Sorted Set
- Adds the element in sort sequence determined by the sort field.
Format
#include <c$to2.h>
long TO2_add (const TO2_PID_PTR pid_ptr,
TO2_ENV_PTR env_ptr,
const void *data,
const long *dataLength);
- pid_ptr
- The pointer to the persistent identifier (PID) assigned to the collection
to which the element will be added.
- 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 length of the element that will
be stored.
Normal Return
For a normal return for the following collections, TO2_add
returns the position index of where the element was added:
- Array
- BLOB
- Keyed log
- Log
- Sequence.
- Note:
- The position index for these collections is 1-based; that is, 1
represents the first element.
For a normal return for the following collections, TO2_add
returns a positive value:
- Bag
- Set
- Sorted bag
- Sorted set.
- Note:
- The set collection returns a positive success return for duplicate elements
even though set does not allow duplicate elements.
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_LOCATOR_NOT_UNIQUE
TO2_ERROR_METHOD
TO2_ERROR_NOT_INIT
TO2_ERROR_PID
TO2_ERROR_UPDATE_NOT_ALLOWED
TO2_ERROR_ZERO_PID
Programming Considerations
- A commit scope will be created for the TO2_add request.
If the request is successful, the scope will be committed. If an error
occurs while processing the TO2_add request, the scope will be
rolled back.
- For all collections, the TO2_add request skips the test of the
update sequence counter, which checks for the expected value for the
counter.
Examples
The following example adds an item to a bag collection.
#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 bag; /* will store PID after create */
char item[] = "Item A"; /* data */
long itemsiz;
·
·
·
/*********************************************************************/
/* Make sure that the bag is created before arriving here... */
/*********************************************************************/
itemsiz = sizeof(item);
if (TO2_add(&bag,
env_ptr,
item,
&itemsiz) == TO2_ERROR)
{
printf("TO2_add failed!\n");
process_error(env_ptr);
}
else
{
printf("TO2_add successful!\n");
}
Related Information