gtpc2mbpC/C++ Language Support User's Guide

TO2_add-Add an Element to a Collection

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:

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:

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

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