gtpc2mc2 | C/C++ Language Support User's Guide |
This function searches the specified collection for the specified key and, if not found, the key is added to the collection with the associated element value.
If the collection allows duplicate keys, the search is bypassed and the key and its associated element are added to the collection.
Format
#include <c$to2.h> long TO2_atNewKeyPut (const TO2_PID_PTR pid_ptr, TO2_ENV_PTR env_ptr, const void *key, 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_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_atNewKeyPut request. If the request is successful, the scope will be committed. If an error occurs while processing the TO2_atNewKeyPut request, the scope will be rolled back.
Examples
The following example adds a new key and its associated data to the specified key bag collection.
#include <c$to2.h> /* Needed for TO2 API functions */ #include <stdio.h> /* APIs for std I/O functions */ #include <stdlib.h> /* APIs for std library functions */ TO2_PID collect; /* must set to existing KeyBag PID */ TO2_ENV_PTR env_ptr; /* Pointer to the TO2 environment */ char keya[] = "KeyA"; /* key to search for */ char objecta[] = "ObjectA"; /* data */ long objsiza; /* size of data */
·
·
·
/*************************************************************************/ /* Add key and its data to the collection. */ /*************************************************************************/ objsiza = sizeof(objecta); if (TO2_atNewKeyPut(&collect, env_ptr, keya, objecta, &objsiza) == TO2_ERROR) { printf("TO2_atNewKeyPut failed!\n"); process_error(env_ptr); } else { printf("We have added key %s with data %s.\n", keya, objecta); printf("TO2_atNewKeyPut is successful!\n"); }
Related Information