Binary Fields

Binary data can be stored in eXtremeDB fields of type string, blob, binary and varbinary. Fields of type blob can be used for large data fields (greater than 1 Kb). When a field is not intended to be used in indexes and its data size is less than 64 Kb string fields can be used. String fields in eXtremeDB can contain arbitrary data, not only ASCII characters; i.e. arbitrary binary data can be stored in a string without encoding. The only limitation is that string fields cannot be used in internal comparisons (needed for indexes) and cannot be passed as parameters in xSQL. If a field of binary data is intended to be indexed, the binary or varbinary data type can be used. Unlike blob fields, binary and varbinary fields can be added to both simple and compound indexes.

(See page Using Binary Data for further details.)

Blob Support

eXtremeDB provides support for Binary Large Object (blob) fields through C/C++ interface functions and, for C# and Java applications, the blob field annotation or attribute. A blob field cannot be part of an array or struct. Blob elements are useful when it is necessary to keep streaming data, with no known size limits.

C/C++ applications use the generated classname_fieldname_get() function to copy blob data to an application’s buffer; it allows specification of a starting offset within the blob.

 
    MCO_RET classname_fieldname_get( /*IN*/ classname *handle,
                /*IN*/ uint4 startOffset,
                /*OUT*/ char *buf,
                /*IN*/ uint4 bufsz,
                /*OUT*/ uint4 *len);
                 

The bufsz parameter is the size of the buffer passed by the application in the buf parameter. The len output parameter is the actual number of bytes copied to the buffer (which will be <= bufsz).

The classname_fieldname_size() function returns the size of a blob field. This value can be used to allocate sufficient memory to hold the blob, prior to calling the classname_fieldname_get() function.

 
    MCO_RET classname_fieldname_size( /*IN*/ classname *handle,
                /*OUT*/ uint4 * result);
                 

The classname_fieldname_put() function populates a blob field, possibly overwriting prior contents. It allocates space and copies data from the application’s buffer; the size of the blob must be specified.

 
    MCO_RET classname_fieldname_put( /*IN*/ classname *handle,
                /*IN*/ const void *from,
                /*IN*/ uint4 nbytes);
                 

The classname_fieldname_append() function is used to append data to an existing blob. This method is provided so an application does not have to allocate a single buffer large enough to hold the entire blob, but rather can conserve memory by writing the blob in manageable pieces.

 
    MCO_RET classname_fieldname_append(/*IN*/ classname *handle,
                /*IN*/ const void * from,
                /*IN*/ uint4 nbytes );
                 

To erase (truncate) a blob, pass a size of 0 to the classname_fieldname_put() function.