Veil variables exist to record session and system state. They retain their values across transactions. Variables may be defined as either session variables or shared variables.

All variables are referenced by name; the name of the variable is passed as a text string to Veil functions.

Session variables are private to the connected session. They are created when first referenced and, once defined, their type is set for the life of the session.

Shared variables are global across all sessions. Once a shared variable is defined, all sessions will have access to it. Shared variables are defined in two steps. First, the variable is defined as shared, and then it is initialised and accessed in the same way as for session variables. Note that shared variables should only be created within registered initialisation functions or veil_init(doing_reset bool).

Note that bitmap refs and bitmap hashes may not be stored in shared variables.

The following types of variable are supported by Veil, and are described in subsequent sections:

integers
ranges
bitmaps
bitmap refs
bitmap arrays
bitmap hashes
integer arrays

The following functions comprise the Veil variables API:

share(name text)
veil_variables()

Note again that session variables are created on usage. Their is no specific function for creating a variable in the variables API. For an example of a function to create a variable see init_bitmap(bitmap_name text, range_name text).

share(name text)

function veil.share(name text) returns bool

Implemented by C function veil_share(), this is used to define a specific variable as being shared. A shared variable is accessible to all sessions and exists to reduce the need for multiple copies of identical data. For instance in the Veil demo, role_privileges are recorded in a shared variable as they will be identical for all sessions, and to create a copy for each session would be an unnecessary overhead. This function should only be called from registered initialisation functions or veil_init(doing_reset bool).

veil_variables()

function veil.veil_variables() returns setof veil_variable_t

This function, implemented by C function veil_variables(), returns a description for each variable known to the session. It provides the name, the type, and whether the variable is shared. It is primarily intended for interactive use when developing and debugging Veil-based systems.

Next: Basic Types: Integers and Ranges