gtpc2mfmC/C++ Language Support User's Guide

TO2_nextRBAfor-Return the Next Specified Number of Bytes

This function returns the next specified number of bytes in the collection starting at the current cursor position and updates the cursor to point to the first byte following the returned bytes. The number of bytes read will be the length specified (up to a maximum buffer length of 4 MB (4 194 304)) or the size of the binary large object (BLOB), whichever is smaller.

Note:
This function does not support all collections. See Table 48 for collections that are supported for this function.

Format

#include <c$to2.h>
void * TO2_nextRBAfor (const TO2_PID_PTR  cursorPidPtr,
                             TO2_ENV_PTR  env_ptr,
                       const long        *countOfByte);

cursorPidPtr
The pointer to the cursor persistent identifier (PID) created by one of the TPF collection support (TPFCS) create cursor application programming interfaces (APIs).

env_ptr
The pointer to the environment as returned by the TO2_createEnv function.

countOfByte
The pointer to the number of bytes that will be returned. The maximum buffer length is 4 MB (4 194 304).

Normal Return

A pointer to a buffer containing the requested data is returned.

Error Return

An error return is indicated by NULL. When NULL 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_CURSOR

TO2_ERROR_EMPTY

TO2_ERROR_ENV

TO2_ERROR_EODAD

TO2_ERROR_METHOD

TO2_ERROR_PID

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

The following example shows how the next 10 bytes in the binary large object (BLOB) collection are returned and positions the cursor to point after the 10th byte.

#include <c$to2.h>                 /* Needed for TO2 API Functions    */
#include <stdio.h>                 /* APIs for standard I/O functions */
 
TO2_PID             cursor;
TO2_ENV_PTR         env_ptr;
char               *buffer_ptr;
TO2_ERR_CODE        err_code;      /* TO2 error code value          */
TO2_ERR_TEXT_PTR    err_text_ptr;  /* TO2 error code text pointer   */

  ·
  ·
  ·
/********************************************************************/ /* Read the next 10 bytes in the BLOB and update the cursor. */ /********************************************************************/ if ((buffer_ptr=(char *)TO2_nextRBAfor(&cursor, env_ptr)) == NULL) { err_code = TO2_getErrorCode(env_ptr); if (err_code != TO2_ERROR_EODAD) { printf("TO2_nextRBAfor failed!\n"); process_error(env_ptr); } else printf("Cursor is at the end of the collection!\n"); return(0); } else printf("TO2_nextRBAfor successful!\n");
  ·
  ·
  ·
free(buffer_ptr);

Related Information