gtpc2mc6 | C/C++ Language Support User's Guide |
This function can be called to read either a complete binary large object (BLOB), or only part of a BLOB by specifying the starting byte position.
The data that is read is placed in the buffer specified by the caller. The number of bytes read will be the length specified, the maximum buffer length of 32 KB (8 × 4096), or the size of the BLOB, whichever is smaller.
Format
#include <c$to2.h> void * TO2_atRBAWithBuffer (const TO2_PID_PTR pid_ptr, TO2_ENV_PTR env_ptr, const long *relativeByteToRead, long *bufferLength, long *updateSeqCtr, void *buffer);
Normal Return
The normal return is a pointer to the buffer (array of character) supplied by the caller. This buffer now contains the requested data.
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_BUFFER_SIZE
TO2_ERROR_DATA_LGH
TO2_ERROR_EMPTY
TO2_ERROR_ENV
TO2_ERROR_EODAD
TO2_ERROR_INDEX
TO2_ERROR_METHOD
TO2_ERROR_NOT_INIT
TO2_ERROR_PID
TO2_ERROR_SEQCTR
TO2_ERROR_ZERO_PID
Programming Considerations
Examples
The following example copies data into a specified buffer 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; 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 */ char buff[40]; /* use buffer */ char * buff_ptr; long buffL; /* length of user buffer */
·
·
·
/********************************************************************/ /* Copy data from the BLOB starting at the 5th position for up */ /* to 40 bytes, that is the size of the user buffer. */ /********************************************************************/ buffL = sizeof(buff); buff_ptr = TO2_atRBAWithBuffer(&blob, env_ptr, &position, &buffL, &seq_ctr, buff); if (buff_ptr == NULL) { printf("TO2_atRBAWithBuffer failed!\n"); process_error(env_ptr); } else { printf("TO2_atRBAWithBuffer successful!\n"); }
Related Information