gtpc2meg | C/C++ Language Support User's Guide |
This function searches the specified collection for the specified key and, if found, the key and the associated element are removed from the collection. If the collection contains duplicate keys equal to the specified key, the first one found will be removed.
Format
#include <c$to2.h> long TO2_removeKey (const TO2_PID_PTR pid_ptr, TO2_ENV_PTR env_ptr, const void *key);
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_EMPTY
TO2_ERROR_ENV
TO2_ERROR_LOCATOR_NOT_FOUND
TO2_ERROR_METHOD
TO2_ERROR_PID
TO2_ERROR_UPDATE_NOT_ALLOWED
TO2_ERROR_ZERO_PID
Programming Considerations
A commit scope will be created for the TO2_removeKey request. If the request is successful, the scope will be committed. If an error occurs while processing the TO2_removeKey request, the scope will be rolled back.
Examples
The following example removes the key.
#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_PTR pid_ptr; char key[] = "Some key value of appropriate length";
·
·
·
if (TO2_removeKey(pid_ptr, env_ptr, key) == TO2_ERROR) { printf("TO2_removeKey failed!\n"); process_error(env_ptr); } else { printf("TO2_removeKey successful!\n"); }
Related Information