gtpc2mc4 | C/C++ Language Support User's Guide |
This function can be called to read either a complete binary large object (BLOB) or only a part of a BLOB by specifying the starting byte position.
The number of bytes read will be the length specified (up to 4 MB (4 194 304)) or the size of the BLOB, whichever is smaller.
Format
#include <c$to2.h> void * TO2_atRBA (const TO2_PID_PTR pid_ptr, TO2_ENV_PTR env_ptr, const long *relativeByteToRead, long *lengthToRead, long *updateSeqCtr);
Normal Return
The normal return is a pointer to a buffer containing the requested data. Once the caller has stopped using the returned data, it is the responsibility of the caller to free the data buffer. The lengthToRead parameter is updated with the actual number of bytes read.
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_EMPTY
TO2_ERROR_ENV
TO2_ERROR_EODAD
TO2_ERROR_INDEX
TO2_ERROR_METHOD
TO2_ERROR_PID
TO2_ERROR_REREAD
TO2_ERROR_SEQCTR
TO2_ERROR_ZERO_PID
TO2_ERROR_NOT_INIT
Programming Considerations
Examples
The following example obtains a buffer with a copy of the data from a given BLOB starting at a specified relative byte position for a specified length.
#include <c$to2.h> /* Needed for TO2 API functions */ #include <stdio.h> /* APIs for standard I/O functions */ TO2_PID blob; /* Pointer to the TO2 environment */ TO2_ENV_PTR env_ptr; /* Pointer to the TO2 environment */ long position=5; /* We will try to get starting at 5 */ long seq_ctr; /* will hold update sequence count */ long size=40; /* number bytes to copy */ char * buf_ptr;
·
·
·
/********************************************************************/ /* Copy data from the BLOB starting at the 5th position for a */ /* length of 40 bytes. */ /********************************************************************/ buf_ptr = TO2_atRBA(&blob, env_ptr, &position, &size, &seq_ctr); if (buf_ptr == NULL) { printf("TO2_atRBA failed !\n"); process_error(env_ptr); } else { printf("TO2_atRBA successful!\n"); }
Related Information