VARIABLE TO BLOB

version 6.0

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

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

• Two-dimensional arrays

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.

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)

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)

BLOB to list, BLOB TO VARIABLE, LIST TO BLOB.

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