Serialize (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / WLanguage / Managing databases / HFSQL / 3-tier architecture / WLanguage functions

Deserialization
Update from version 10: XML serialization for mobile applications
Speed
Serializing the members of classes and structures
Serialization name of classes
Available options for serializing arrays into XML
Limitations

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

Serialize (Function)

In french: Sérialise

Transforms the following elements into a specific format:

a structure (and its subelements).
a class (and its subelements).
an array (including the associative arrays).
a queue.
a stack.
a list.
an advanced type of variable (gglCalendar for example).

The available formats are XML, binary and JSON. Then, the initial format can be retrieved by Deserialize.

Example

See additional examples

// This example explains how to use the Serialize/Deserialize functions
// with an Array variable. 
// These functions can use all types of WLanguage variables.

MyArray is array of strings
bufResult is Buffer

// Adds elements into the array
Add(MyArray, "WINDEV")
Add(MyArray, "WEBDEV")
Add(MyArray, "WINDEV MOBILE")

// Serialize the array in the buffer in JSON
// => Save the array and its entire content in a JSON string
Serialize(MyArray, bufResult, psdJSON)

// Deserialize the JSON buffer
// => Rebuild the WLanguage array from the JSON string
MyRebuiltArray is array of strings
Deserialize(MyRebuiltArray, bufResult, psdJSON)

Syntax

Serialize(<Variable> , <Buffer> , <Parameters> [, <Root name>])

<Variable>: Variable type

Variable to serialize. This variable is a structure, a class, an array, a queue, a list or a stack.

<Buffer>: Ansi character string or buffer

Variable that contains the result of serialization.

<Parameters>: Integer constant

Type of serialization:
psdBinary Binary serialization.
New in SaaS
It is now possible to serialize a member or JSON variable into binary format..
Note: This feature is only available from WINDEV Suite SaaS 2025 - Update 2.
For more details, see Using new features exclusive to WINDEV Suite SaaS 2025.
Binary deserialization is not available.
psdBinaryFormat16 Binary serialization compatible with version 16.
This format must be used if an application in version 17 or later must share data with an application in version 16 or earlier.
This format must not be used in Unicode mode.
Binary deserialization is not available.
psdJSON JSON serialization.
The encoding used corresponds to the JSON standard:
7-bit ASCII encoding, i.e. the first 128 characters, unaccented characters,
JSON encoding for other characters: "\u" followed by the character code in 4-byte hexadecimal format. For example, the "é" character (ASCII code 233, hexadecimal code E9) would be encoded as "\u00E9".
JSON deserialization is not available.
psdMinified Note: This constant must be used in combination with the psdJSON constant. Otherwise, it will be ignored.
The encoding used corresponds to the JSON standard. This constant is used to generate a JSON by removing unnecessary spaces (carriage returns, spacing characters, etc.).
This constant is not available.

psdFormatting Serialization in JSON or XML format with carriage return and indent.
The encoding used corresponds to the JSON or XML standard.
Note: This constant must be used in combination with the psdJSON or psdXML constant.
The serialization in JSON format with formatting is not available.
psdXML XML serialization with reference to sub-objects. This type of serialization allows you to use the XML format as storage and exchange modes between applications written in WLanguage.
psdXMLAggregated XML serialization with direct aggregation of sub-objects. This type of serialization allows you to easily generate an XML file in a standard format to perform exchanges with other systems.
Note: The psdXMLAggregated deserialization mode is available. However, the WLanguage elements (variants, arrays, derived classes, etc.) will be different from the original elements.
This serialization mode is not available.
New in version 2025
psdXMLArrayRepeatedElements
XML serialization mode for handling arrays as a sequence of elements.
Note: This constant must be used in combination with the psdXMLAggregated constant. For more details, see the array serialization examples.
This serialization mode is not available.
Note: This constant is only available from version 2025 Update 1.

<Root name>: Character string

Name of the root of the generated XML. This parameter is taken into account in psdXMLAggregated mode only.
If this parameter is not specified, the name of the root is "DOCUMENT".

Remarks

Deserialization

The deserialization of an array, queue, list or stack deletes the content from this element.

If there are additional members in the structure or in the class:

if a structure or a class is deserialized, additional members keep their values from before the deserialization.
if an array of structures or classes is deserialized, additional members take the default value of the member type.

If there are additional members in the serialized buffer, they are ignored during the deserialization.

To deserialize an untyped dynamic array, it must be allocated beforehand.

To deserialize a class or a structure containing an untyped dynamic array, this array must be allocated beforehand.

The wd300xml.dll or wp300xml.dll library is necessesary to deserialize an XML document.

In order for the serialization format to be compatible between the WINDEV applications and the WINDEV Java applications, the names of the following serialized elements must contain no special character and no accented character:

classes,
arrays of classes,
structures,
arrays of structures.

Update from version 10: XML serialization for mobile applications

Until version 100050, the psdXML constant did not generate a valid XML file. The generated format caused problems on Mobile devices. This problem was fixed.

An XML file created with a version later than version 100050 cannot be read by a program compiled with an earlier version. To keep the operating mode of version 100050, all you have to do is use the psdXML_OldFormat constant.

Speed

The binary serialization is faster than the XML serialization.

Serializing the members of classes and structures

By default, all the members of a class or structure are serialized.

You have the ability to precisely manage the serialization of each member:

by specifying the member that will be serialized during the call to Serialize.
This operation can be performed on all types of serialization (XML, JSON, binary).
by changing the name of the member during the serialization with Serialize.
This operation can be performed during a binary serialization only.

This management of serialization is performed by using the following syntax:

Serialization (or not) of a member:
<Member name> is <Member type> [, Serialize = <True/False>] [, xmlAttribute]
Serialization and change of member name:
<Member name> is <Member type> [, Serialize = <New name>] [, xmlAttribute]

The "xmlAttribute" extension attribute is used to specify that the member is created as attribute (instead of tag). This attribute is taken into account during a psdXMLAggregated serialization only.

The "xmlAttribute" extension attribute is not available.

Example for a class:

Cl is Class
	// Serialized member
	SerializedMember is int 
	// Non-serialized member
	NonSerializedMember is string, serialize = false  
	// Member renamed during the serialization
	RenamedMember is int, serialize = "NewMemberName" 
END

Note: To avoid serializing an array member, use the following syntax:

t is array <Serialize = False> of int
t2 is array <Serialize = "<serialization name>"> of int

Serialization name of classes

The "Serialize" extension attribute is available for the classes in order to specify the serialization name.

The following syntax is used:

<Class name> is Class [, Serialize = <New name>]

Example:

CTest is Class, serialize = "Test"
	m_sLastName is string, serialize = "LastName"
	m_sFirstName is string, serialize = "FirstName"
	m_sMiddleName is string, serialize = "MiddleName"
END

sXML is Buffer
 myTest is CTest
 myTest.m_sLastName = "My last name"
 myTest.m_sFirstName = "My first name"
 myTest.m_sMiddleName = "My middle name"
Serialize(myTest, sXML, psdXMLAggregated)


// Content of sXML where the names in the serialization can be found:
// <?xml version="1.0" encoding="UTF-8"?>
// <Test>
//  <LastName>My last name</LastName>
//  <FirstName>My first name</FirstName>
//  <MiddleName>My middle name</MiddleName>
// </Test>

Available options for serializing arrays into XML

Declare the array:

TheStructure is Structure
	TheArray is array of int
END

the_variable is TheStructure
the_variable.TheArray = [1, 2, 3]

Serialization with the psdXML constant:
```
Serialize(the_variable, XML_document, psdXML)
```
Result:
<?xml version="1.0"?>
<DOCUMENT xmlns:SOAP_ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<TheStructure id="id0">
<TheArray SOAP_ENC:arrayType="TheArray[3]">
<item>1</item>
<item>2</item>
<item>3</item>
</TheArray>
</TheStructure>
</DOCUMENT>
Serialization with the psdXMLAggregated constant:
```
Serialize(the_variable, XML_document, psdXMLAggregated)
```
Result:
<?xml version="1.0"?>
<TheStructure>
<TheArray>
<item>1</item>
<item>2</item>
<item>3</item>
</TheArray>
</TheStructure>
New in version 2025
Serialization with the psdXMLAggrated and psdXMLArrayRepeatedElements constants:
Serialize(the_variable, XML_document_with_array_repeated_elements, psdXMLAggregated+ psdXMLArrayRepeatedElements)
Result:
<?xml version="1.0"?>
<TheStructure>
<TheArray>1</TheArray>
<TheArray>2</TheArray>
<TheArray>3</TheArray>
</TheStructure>
Note: This syntax is only available from version 2025 Update 1.

Limitations

Fixed and associative arrays of local structures cannot be serialized.
The global members of classes are not serialized.
The XML serialization/deserialization of an array of structures with a string member containing "\0" or Charact(0) returns the following error: "Wrong serialization format". In this case, a binary serialization/deserialization must be performed.
You cannot serialize/deserialize an array of classes or structures if this class or structure contains a dynamic array without type. A dynamic array with defined type must be used in this class or in this structure.
To serialize/deserialize a class, you must have a constructor with 0 parameter.
stacks, queues, lists:
- The JSON serialization of stacks, queues and lists is not available.
- You cannot serialize/deserialize Queue, Stack or List variables.
Only JSON serialization is available for Record variables. No deserialization is possible.

Related Examples:

Unit examples (WEBDEV): The Serialize/Deserialize functions

[ + ] This example explains how to use the WLanguage functions Serialize and Deserialize.
The serialization consists in saving a variable, an object, a structure, an array or any other element in a buffer. Then, this buffer can be saved on disk or sent by socket. This allows for the persistence of objects.
The Deserialize function is used to rebuild an object, an array or a structure from a buffer.

Unit examples (WINDEV): The Serialize/Deserialize functions

[ + ] Using the WLanguage Serialize and Deserialize functions
The serialization consists in saving a variable, an object, a structure, an array or any other element in a buffer. Then, this buffer can be saved on disk or sent by socket. This allows for the persistence of objects.
The Deserialize function is used to rebuild an object, an array or a structure from a buffer.

Business / UI classification: Neutral code

Component: wd300vm.dll