gtpc2mgi | C/C++ Language Support User's Guide |
This function locates the entry represented by the specified key and returns its contents to the requester. If the key length is less than 64 bytes, the first entry with a key that matches the passed key string will be returned.
Format
#include <c$to2.h> TO2_BUF_PTR TO2_atBrowseKey ( TO2_ENV_PTR env_ptr, const void *key, const long *keyLength);
Normal Return
The normal return is a pointer (TO2_BUF_PTR) to a structure (buffer) of type TO2_BUF_HDR (see Type Definitions).
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_LGH
TO2_ERROR_LOCATOR_NOT_FOUND
TO2_ERROR_METHOD
TO2_ERROR_NOT_INIT
TO2_ERROR_PID
TO2_ERROR_ZERO_PID
Programming Considerations
None.
Examples
The following example retrieves the element from the browser dictionary using a specified key.
#include <c$to2.h> /* Needed for TO2 API functions */ #include <stdio.h> /* APIs for standard I/O functions */ #define UNDEF -1 /* Error return indication */ long err_code; char key[64]; TO2_BUF_PTR buf_ptr; /* TO2 buffer pointer returned */ TO2_ENV_PTR env_ptr; /* Pointer to TO2 environment */ long keyLength;
·
·
·
buf_ptr = TO2_atBrowseKey(env_ptr, key, &keyLength); if (buf_ptr == TO2_ERROR) { err_code = TO2_getErrorCode(env_ptr); if (err_code == TO2_ERROR_LOCATOR_NOT_FOUND) return UNDEF; { printf("TO2_atBrowseKey failed!\n"); process_error(env_ptr); } else { printf("TO2_atBrowseKey successful!\n"); } }
Related Information