gtpc2mby | C/C++ Language Support User's Guide |
This function returns the data at the specified position in the specified collection. The collection is not changed. If the collection is an array and the position is marked as empty, this method returns a data length of 0 and an update sequence counter of 0.
Format
#include <c$to2.h> TO2_BUF_PTR TO2_at (const TO2_PID_PTR pid_ptr, TO2_ENV_PTR env_ptr, const long *index);
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 NULL pointer. When a NULL pointer 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_EODAD
TO2_ERROR_INDEX
TO2_ERROR_METHOD
TO2_ERROR_NOT_INIT
TO2_ERROR_PID
TO2_ERROR_REREAD
TO2_ERROR_ZERO_PID
Programming Considerations
Examples
The following example obtains a buffer with a copy of the third element of a specified collection.
#include <c$to2.h> /* Needed for TO2 API functions */ #include <stdio.h> /* APIs for standard I/O functions */ TO2_BUF_PTR buffer_ptr; TO2_PID collect; TO2_ENV_PTR env_ptr; /* Pointer to the TO2 environment */ long position=3; /* We will try to get third element */ char *dataField;
·
·
·
/***********************************************************************/ /* Copy the element at the specified position. */ /***********************************************************************/ if ((buffer_ptr = TO2_at(&collect, env_ptr, &position)) == NULL) { printf("TO2_at failed!\n"); process_error(env_ptr); return; } else { dataField = buffer_ptr->data; printf("TO2_at successful!\n"); }
·
·
·
free(buffer_ptr);
Related Information