4D v14.3

VARIABLE TO BLOB

Home

 
4D v14.3
VARIABLE TO BLOB

VARIABLE TO BLOB 


 

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

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.

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)

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)

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

 
PROPERTIES 

Product: 4D
Theme: BLOB
Number: 532

The OK variable is changed by the command

 
HISTORY 

New
Created: 4D v6
Modified: 4D v14

 
SEE ALSO 

BLOB to list
BLOB TO VARIABLE
LIST TO BLOB

 
TAGS 

Variable, ListRef

 
ARTICLE USAGE

4D Language Reference ( 4D v14 R2)
4D Language Reference ( 4D v14 R3)
4D Language Reference ( 4D v14.3)
4D Language Reference ( 4D v14 R4)

Inherited from : VARIABLE TO BLOB ( 4D v13.5)