xHarbour Reference Documentation > Function Reference

HB_Serialize()

Converts an arbitrary value to a binary string.

Syntax

HB_Serialize( <xValue> ) --> cBinary

Arguments

<xValue>

This is an arbitrary value to convert to a binary string. The value can be of any data type, except Pointer.

Return

The function returns the binary representation of <xValue> as a character string.

Description

Function HB_Serialize() converts an arbitrary value to its binary string representation. The binary string can then be treated like a regular character string and written to a file, for example. The original value can be obtained by passing the binary string to HB_DeSerialize().

Although values of any data type can be passed to the function, certain limitations must be complied with when values are (de)serialized:

Simple data types

There is no limit for the serialization of values having the data type Character, Date, Numeric, Logic or NIL

Arrays and Hashes

No limitation exists for arrays and hashes when their elements contain values of simple data types. Nested arrays and hashes can be serialized as long as they do not reference themselves in their elements. When complex data types are stored in arrays or hashes, the same limitations as for the respective data type exist for arrays and hashes.

Code blocks

As a general rule, only code blocks that access items having a symbolic name at runtime can be serialized. This excludes code blocks referencing GLOBAL, LOCAL or STATIC variables and/or STATIC FUNCTIONs and PROCEDUREs from conversion, since their symbolic names do not exist at runtime. Passing such a code block to HB_Serialize() generates a runtime error.

The code block can only be deserialized in the exact same binary that converted the code block. That means, only executables that are created with the same PCode version of xHarbour and have the same symbol table can deserialize a serialized code block.

Objects

The same limits as for code blocks exist for objects. It is recommended to subclass from the HBPersistent() class when objects should be serialized.

Pointers

Pointers cannot be serialized since they refer to memory locations at runtime. HB_Serialize() returns always NIL when a pointer is passed.

Info

See also:	HB_Deserialize(), HB_SerializeSimple(), HB_SerialNext(), RESTORE, SAVE
Category:	Conversion functions , Serialization functions , xHarbour extensions
Source:	rtl\hbserial.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// In this example, a code block is created and stored in a MEM file.
// The second invocation of the example code loads the stored code block
// and evaluates it. Note that the code block referenes a PRIVATE variable
// that is restored along with the code block.

   PROCEDURE Main
      LOCAL bBlock := {|| Alert( pcString ) }

      IF .NOT. File( "Codeblock.mem" )

         PRIVATE pcString := "code block restored from file"
         PRIVATE pcBlock  := HB_Serialize( bBlock )

         SAVE TO Codeblock.mem ALL LIKE pc*
         ? "Restart program to load code block"

      ELSE
         RESTORE FROM Codeblock.mem

         bBlock := HB_DeSerialize( pcBlock )

         Eval( bBlock )
      ENDIF

   RETURN