gtpc2mc5C/C++ Language Support User's Guide

TO2_atRBAPut-Store Data in a BLOB

This function is used to either add data to a binary large object (BLOB), completely replace the contents of a current BLOB, or change a specific set of bytes in a BLOB. If the BLOB is larger than a single transmission buffer, multiple TO2_atPut functions can be entered as each buffer is received to add the new data to the BLOB. The number of bytes stored will be the length specified (up to 4 MB (4 194 304)) or the size of the BLOB, whichever is smaller. To completely replace the data in an existing BLOB, call the TO2_makeEmpty function before the first TO2_atRBAPut is entered with the replacement data.

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

Format

#include <c$to2.h>
long  TO2_atRBAPut (const TO2_PID_PTR      pid_ptr,
                          TO2_ENV_PTR      env_ptr,
                    const long             *startByteToPut,
                    const void             *data,
                    const long             *dataLength,
                    const long             *updateSeqCtr,
                    const TO2_ATPUT_STATE  *moreData);

pid_ptr
The pointer to the persistent identifier (PID) assigned to the collection.

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

startByteToPut
The pointer to a 1-based value that specifies the relative byte position in the collection to start storing the data.

data
The pointer to the data that will be stored in the collection.

dataLength
The pointer to an area that contains the number of bytes that will be stored. The data written will be all or none because no partial writes are allowed. The maximum length that can be read is 4 MB (4 194 304).

updateSeqCtr
The pointer to an area where the update sequence counter from a TO2_atRBA request has been stored. If this sequence counter value is not equal to the current update sequence counter value of the collection, the TO2_atRBAPut request will not be processed.

moreData
A pointer to a character that signals if there is more data that will be placed in the BLOB, or if this is the last or only TO2_atRBAPut request that will be entered for the BLOB.

TO2_ATPUT_ONLY
This is the only TO2_atRBAPut function call. The BLOB is completed and can be closed out.

TO2_ATPUT_FIRST
This is the first function call and there is more data that will be placed in the BLOB using TO2_atRBAPut. The BLOB will not be closed out.

TO2_ATPUT_MORE
This is not the first call and there is more data that will be placed in the BLOB using TO2_atRBAPut. The BLOB will not be closed out.

TO2_ATPUT_LAST
Last TO2_atRBAPut. The BLOB is completed and can be closed out.

Normal Return

The normal return is a positive value.

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_ACCESS_MISMATCH

TO2_ERROR_DATA_LGH

TO2_ERROR_ENV

TO2_ERROR_INDEX

TO2_ERROR_METHOD

TO2_ERROR_NOT_INIT

TO2_ERROR_PID

TO2_ERROR_SEQCTR

TO2_ERROR_UPDATE_NOT_ALLOWED

TO2_ERROR_ZERO_PID

Programming Considerations

Examples

The following example resets specific bytes of a specified BLOB.

#include <c$to2.h>              /* Needed for TO2 API functions        */
#include <stdio.h>              /* APIs for standard I/O functions     */
#include <stdlib.h>             /* APIs for standard library 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    */
long                size=8;     /*  number bytes to read/write         */
mode                long;
char                *buff_ptr;
char                newdata[] = "NewData"; /* new data                 */
TO2_ATPUT_STATE     moreData = TO2_ATPUT_ONLY;

  ·
  ·
  ·
/***********************************************************************/ /* Look at the BLOB to set the contents of sequence counter for */ /* to use for subsequent update. */ /***********************************************************************/ buff_ptr = TO2_atRBA(&blob, env_ptr, &position, &size, &seq_ctr); if (buff_ptr == NULL) { printf("TO2_atRBA failed!\n"); process_error(env_ptr); exit(0); }
  ·
  ·
  ·
free(buff_ptr); /********************************************************************/ /* Now update BLOB to change data starting at position 5 to new */ /* data.... */ /********************************************************************/ size = sizeof(newdata); if (TO2_atRBAPut(&blob, env_ptr, &position, newdata, &size, &seq_ctr, &moreData) == TO2_ERROR) { printf("TO2_atRBAPut failed!\n"); process_error(env_ptr); } else { printf("TO2_atRBAPut successful!\n"); }

Related Information