gtpc2mevC/C++ Language Support User's Guide

TO2_writeNewBLOB-Create a New BLOB and Add the Passed Data

This function allows an application program to create and populate a new binary large object (BLOB) collection with the passed data. If the data and dataLength parameters are specified as NULL pointers, TPF collection support (TPFCS) will create and return an empty BLOB.

Note:
This function only supports BLOB collections.

Format

#include <c$to2.h>
long  TO2_writeNewBLOB (      TO2_PID_PTR      pid_ptr,
                              TO2_ENV_PTR      env_ptr,
                        const TO2_OPTION_PTR   optionListPtr,
                        const void            *data,
                        const long            *dataLength);

pid_ptr
The pointer to a field where the new persistent identifier (PID) of the collection will be returned by TPFCS.

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

optionListPtr
The pointer to a returned options list from a TO2_createOptionList function call or NULL if no options are required. The option list is used to specify create options to be applied by TPFCS when TPFCS creates the new BLOB collection.

data
The pointer to the new data that will be written to the BLOB, or NULL to create an empty BLOB.

dataLength
The pointer to a field that contains the length of the new data, or NULL to create an empty BLOB. Both the data and dataLength parameters must be specified as NULL to create an empty BLOB.

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_DATA_LENGTH

TO2_ERROR_ENV

TO2_ERROR_METHOD

TO2_ERROR_NOT_INIT

Programming Considerations

Examples

The following example causes a new BLOB to be created and loaded with the passed data.

#include <c$to2.h>                /* TO2 API function prototypes      */
#include <stdio.h>                /* APIs for standard I/O functions  */
 
TO2_ENV_PTR      env_ptr;         /* Pointer to TO2 Environment       */
TO2_PID          blob;
long             dataLength=400;  /* length of data to store in BLOB  */
u_char           data[400];       /* data to store in new BLOB        */
 
/* The initialization of the data field is not shown                  */
 

  ·
  ·
  ·
if (TO2_writeNewBLOB(&blob, env_ptr, NULL, data, &dataLength) == TO2_ERROR) { printf("TO2_writeNewBLOB failed!\n"); process_error(env_ptr); } else { printf("TO2_writeNewBLOB successful!\n"); }

Related Information