syntax:

Blob.put(BlobVar[, offset], variable, DataType) 

Blob.put(BlobVar[, offset], buffer, bufferLen)

Blob.put(BlobVar[, offset], SrcStruct, DataStructureDefinition)

where:

BlobVar - binary large object variable to use.

offset - the offset or position in the Blob from which to work.

variable - variable with data to put into a Blob.

buffer - buffer with data to put into a Blob.

SrcStruct - structure (object) with data to put into a Blob.

DataType - the type of data with which to work.

bufferLen - the length of data to work with as a buffer or byte array.

DataStructureDefinition - definition of an object (structure) variable.

return:

number - the byte offset to the next byte following the data that was just inserted into a Blob. If at the end of a Blob, then return the value that equals Blob.size(Blob).

description:

This method puts data into a specified location of a Binary Large Object, Blob and, along with Blob.get(), allows for direct access to memory within a variable. The contents of such a variable may be viewed as a packed structure. Data can be placed at any location within a Blob. The parameter BlobVar specifies the Blob to use. The parameter offset specifies where, in the Blob, to write data. The third parameter is the data to write. The last parameter specifies the format of the data in the Blob.

Blob.put() returns the byte offset for the next byte following the section where data was just put. If the data is put at the end of the Blob, then the return is equivalent to the size of the Blob.

If offset is not supplied, then the data is put at the end of the Blob, or at offset 0 if the Blob is not yet defined.

The data in v is converted to the specified DataType and then copied into the bytes specified by offset.

If DataType is not the length of a byte buffer, then it must be one of these types:

UWORD8,  SWORD8,  UWORD16, SWORD16, UWORD24, SWORD24,

UWORD32, SWORD32, FLOAT32, FLOAT64, FLOAT80

See Clib.fread() or blobDescriptor object, below, for more information on these DataType values.

see:

Blob get(), Blob size(), _BigEndianMode, Buffer object

example:

// If you were sending a pointer to data

// in an external C library and knew

// that the library expected the data

// in a packed DOS structure of the form: 

struct foo 

{

   signed char a;

   unsigned int b;

   double    c;

};

// and if you were building this structure

// from three corresponding variables,

// then such a building function might look

// like the following: 

function BuildFooBlob(a, b, c) 

{

   var offset = Blob.put(foo, 0, a, SWORD8);    

   offset = Blob.put(foo, offset, b, UWORD16);    

   Blob.put(foo, offset, c, FLOAT64);    

   return foo; 

} 

// or, if an offset were not supplied:

BuildFooBlob(a, b, c)

{

   Blob.put(foo, a, SWORD8);    

   Blob.put(foo, b, UWORD16);    

   Blob.put(foo, c, FLOAT64);    

   return foo; 

}