Structs

A Struct is a tree-like data structure in memory that is used to dynamically manipulate complex data and transform it from or to XML, JSON, or Uniface component data. A Struct can be addressed by assigning it to a variable, parameter, or non-database field of type struct, and manipulated using ProcScript commands, access operators, and information functions.

For information on using Structs and the Struct helper libraries that Uniface provides, see Transforming Complex Data Using Structs.

Structs

A Struct is a collection of data objects, or nodes, that are hierarchically organized under a single root node.

Simple Struct

simple struct

A node that has a parent node is a Struct member. A member can be a Struct itself, in which case it is called a nested Struct.

Struct Variables

A Struct exists only in memory, and it exists only as long as there is a variable, parameter, or non-database field of type struct that refers to it (or one of its members).

Note:  For purposes of discussion, the term struct variable is usually used, but it can equally apply to struct parameters and non-database fields.

The struct variable does not contain the value. Instead, it contains zero or more references to Struct nodes.

One struct variable can contain multiple references to different Struct nodes, and several variables can refer to one Struct node.

Struct Variables

One Struct variable references multiple nodes, and multiple variables reference the same node.

For more information, see Struct Variables.

Creating and Deleting Structs

A Struct can be explicitly created using the $newstruct ProcScript function (vStruct = $newstruct), or it can be implicitly created in the following ways:

  • Assigning a value to a struct variable or parameter.
  • Assigning a value to an allowed Struct function ($name, $parent, or $scalar) or to $tags. 
    vStruct->$name = "My Book"

    Note:  Struct access operators, such as the de-reference operator (->) and the index operator ({N}), enable you to address Structs and their members by name and index number. Struct functions enable you to get and set the values and properties of Structs and their members, and insert, copy, move, and remove them. For more information, see Struct Access Operators and Struct Functions.

  • A ProcScript conversion instruction, such as xmlToStruct or componentToStruct is used. For example:
    xmlToStruct vStruct, "Book.xml"

    For more information, see ProcScript for Manipulating Structs.

A Struct exists in memory as long as there is a struct variable or parameter that points to it. There is no ProcScript command to delete a Struct. Instead, a Struct is deleted as soon as it is no longer referenced by any struct variable or parameter, or it is no longer owned by another Struct. For example, reassigning the vStruct1 variable to another value deletes the Struct it refers to.

vStruct1 = ""
Deleted Struct

Struct is deleted when it is no longer referenced by a Struct variable

However, the Struct referenced by vStruct2 continues to exist.

For more information, see Creating and Deleting Structs and Assigning Values to Structs.

Note: Manipulating Structs is memory-intensive. If the Struct is very large or complex, or Struct nodes contain many annotations, Uniface may run out of memory and exit without warning. This depends on the platform and the amount of memory available. For more information, see Structs and Memory.

Related Topics