4D Doc Center : VARIABLE TO BLOB

Home

4D v14.3

BLOB

VARIABLE TO BLOB


VARIABLE TO BLOB ( variable ; blob {; offset \| *} )

Parameter	Type	Description
variable	Variable	Variable to store in the BLOB
blob	BLOB	BLOB to receive the variable
offset \| *	Variable, Operator	Offset within the BLOB (expressed in bytes) or * to append the value
		New offset after writing if not *

Description

The VARIABLE TO BLOB command stores the variable variable in the BLOB blob.

If you specify the * optional parameter, the variable is appended to the BLOB and the size of the BLOB is extended accordingly. Using the * optional parameter, you can sequentially store any number of variables or lists (see other BLOB commands) in a BLOB, as long as the BLOB fits into memory.

If you do not specify the * optional parameter or the offset variable parameter, the variable is stored at the beginning of the BLOB, overriding its previous contents; the size of the BLOB is adjusted accordingly.

If you pass the offset variable parameter, the variable is written at the offset (starting from zero) within the BLOB. No matter where you write the variable, the size of the BLOB is increased according to the location you passed (plus the size of the variable, if necessary). Newly allocated bytes, other than the ones you are writing, are initialized to zero.

After the call, the offset variable parameter is returned, incremented by the number of bytes that have been written. Therefore, you can reuse that same variable with another BLOB writing command to write another variable or list.

VARIABLE TO BLOB accepts any type of variable (including other BLOBs), except the following:

Pointer
Array of pointers

Note that:

if you store a Long Integer variable that is a reference to a hierarchical list (ListRef), VARIABLE TO BLOB stores the Long Integer variable, not the list. To store and retrieve hierarchical lists in and from a BLOB, use the LIST TO BLOB and BLOB to list commands.
if you pass a C_OBJECT object in the variable parameter, the command places it in the BLOB as JSON in UTF-8. If the object contains pointers, their dereferenced values are stored in the BLOB, not the pointers themselves.

However, if you store a Long Integer variable that is a reference to a hierarchical list (ListRef), VARIABLE TO BLOB will store the Long Integer variable, not the list. To store and retrieve hierarchical lists in and from a BLOB, use the commands LIST TO BLOB and BLOB to list.

WARNING: If you use a BLOB for storing variables, you must later use the command BLOB TO VARIABLE for reading back the contents of the BLOB, because variables are stored in BLOBs using a 4D internal format.

After the call, if the variable has been successfully stored, the OK variable is set to 1. If the operation could not be performed, the OK variable is set to 0; for example, there was not enough memory.

Note regarding Platform Independence: VARIABLE TO BLOB and BLOB TO VARIABLE use a 4D internal format for handling variables stored in BLOBs. As a benefit, you do not need to worry about byte swapping between platforms while using these two commands. In other words, a BLOB created on Windows using either of these commands can be reused on Macintosh, and vice-versa.

Example 1

The two following project methods allow you to quickly store and retrieve arrays into and from documents on disk:

  ` SAVE ARRAY project method

  ` SAVE ARRAY ( String ; Pointer )

  ` SAVE ARRAY ( Document ; -> Array )

 C_STRING(255;$1)

 C_POINTER($2)

 C_BLOB($vxArrayData)

 VARIABLE TO BLOB($2->;$vxArrayData) ` Store the array into the BLOB

 COMPRESS BLOB($vxArrayData) ` Compress the BLOB

 BLOB TO DOCUMENT($1;$vxArrayData) ` Save the BLOB on disk

 

  ` LOAD ARRAY project method

  ` LOAD ARRAY ( String ; Pointer )

  ` LOAD ARRAY ( Document ; -> Array )

 C_STRING(255;$1)

 C_POINTER($2)

 C_BLOB($vxArrayData)

 DOCUMENT TO BLOB($1;$vxArrayData) ` Load the BLOB from the disk

 EXPAND BLOB($vxArrayData) ` Expand the BLOB

 BLOB TO VARIABLE($vxArrayData;$2->) ` Retrieve the array from the BLOB

After these methods have been added to your application, you can write:

 ARRAY STRING(...;asAnyArray;...)

  ` ...

 SAVE ARRAY($vsDocName;->asAnyArray)

  ` ...

 LOAD ARRAY($vsDocName;->asAnyArray)

Example 2

The two following project methods allow you to quickly store and retrieve any set of variables into and from a BLOB:

  ` STORE VARIABLES INTO BLOB project method

  ` STORE VARIABLES INTO BLOB ( Pointer { ; Pointer ... { ; Pointer } } )

  ` STORE VARIABLES INTO BLOB ( BLOB { ; Var1 ... { ; Var2 } } )

 C_POINTER(${1})

 C_LONGINT($vlParam)

 

 SET BLOB SIZE($1->;0)

 For($vlParam;2;Count parameters)

    VARIABLE TO BLOB(${$vlParam}->;$1->;*)

 End for

 

 

  ` RETRIEVE VARIABLES FROM BLOB project method

  ` RETRIEVE VARIABLES FROM BLOB ( Pointer { ; Pointer ... { ; Pointer } } )

  ` RETRIEVE VARIABLES FROM BLOB ( BLOB { ; Var1 ... { ; Var2 } } )

 C_POINTER(${1})

 C_LONGINT($vlParam;$vlOffset)

 

 $vlOffset:=0

 For($vlParam;2;Count parameters)

    BLOB TO VARIABLE($1->;${$vlParam}->;$vlOffset)

 End for

After these methods have been added to your application, you can write:

 STORE VARIABLES INTO BLOB(->vxBLOB;->vgPicture;->asAnArray;->alAnotherArray)

  ` ...

 RETRIEVE VARIABLES FROM BLOB(->vxBLOB;->vgPicture;->asAnArray;->alAnotherArray)

System variables and sets

The OK variable is set to 1 if the variable has been successfully stored, otherwise it is set to 0.