System Variables

SilverScreen system variables are named storage objects that are global to the SilverScreen system. They are useful for communicating between SilverC program invocations, and returning the results of certain SilverScreen commands (see below) . In addition, some SilverScreen commands also produce their results in system variables (as with the GEOMETRY MEASURE commands).

Three types of system variables are allowed:

SilverC supports access to system variables in two ways: the direct access method, and via the load_variable function.

The direct access method entails 'declaring' a variable in a C program, and then using it much like any other variable (with some caveats). The load_variable method entails using the load_variable function to copy system variable data into a structure.

Direct Access Method

With the direct access method, you declare a system variable to the compiler, and then use the variable as a normal char *, double or struct _xyz variable. On encountering such a declaration, if it is either a value or XYZ variable, the compiler will allocate an appropriately sized static storage location for its value. If it is a text variable, then if it is the first text variable declaration encountered in the compilation, then a single 200 byte buffer is allocated in static storage; this buffer will be shared among all system text variables.

To declare a system variable in C, the #pragma sysvar directive must be used. There are three forms

 #pragma sysvar text <name>

 #pragma sysvar value <name>

 #pragma sysvar xyz <name>

where <name> is the name of a SilverScreen system variable. <name> must begin with a dollar sign ('$'). For example:

#pragma sysvar value $volume

Value variables behave like normal double variables. Text variables behave as if they were character arrays (char *). XYZ variables behave as if they were of the predefined type struct _xyz, where struct _xyz is defined as follows:

 struct _xyz

    {

    double x;

    double y;

    double z;

    };

Whenever a variable is encountered as an rvalue (on the right-hand side of an assignment or as a function argument), an instruction is generated that will load the value of the appropriate variable from the system into its location.

System variables may be used as targets of assignment statements, but the value of the system variable does not change as a result of this type of usage. The address of a system variable may also be taken (using the & operator); the result is the location of the static memory buffer used to hold the variable when it is loaded into the run-time environment. The variable should be used in a context appropriate to its declared type.

A simple example:

 #pragma sysvar value $amount

 #pragma sysvar text $command

 #pragma sysvar xyz $point

 ...

 double d;

 char buf[40];

 char c;

 d = $amount + $point.x * 3.2;

 strcpy( buf, $command );

 c = $command[3];

Using the load_variable Function

An alternative to the direct access method is to use the load_variable function. load_variable takes as parameters the name of a system variable and the address of an SS_VARIABLE structure (defined in silver.h), and copies the value of the specified variable into the SS_VARIABLE structure. In this method it is not necessary to declare the system variables using #pragma sysvar .

The load_variable function returns 0 if it succeeds; a non-zero return value means that either the variable does not exist, or if it is a text variable, memory could not be allocated to hold it.

In this example, assume that $tvar is the name of a text system variable, $vvar is the name of a value system variable and $xyzvar is the name of an XYZ system variable:

 #include "silver.h"

 ...

 SS_VARIABLE var;

 if ( ! load_variable( "$tvar", &var ) && var.type == V_TEXT )

    ss_command( "note $tvar = %s", var.text );

 if ( ! load_variable( "$vvar", &var ) && var.type == V_VALUE )

    ss_command( "note $vvar = %d", var.xyz.x );

 if ( ! load_variable( "$xyzvar", &var ) && var.type == V_XYZ )

    ss_command( "note $xyzvar = %z", $var.xyz );

System Variables and SilverScreen

In SilverScreen, system variables are created, destroyed and assigned by using LANGUAGE VARIABLE commands:

They can be assigned a value by the VARIABLE ASSIGN script command. The command has three forms, each corresponding to a data type that can be associated with a system variable:

 VARIABLE ASSIGN <name> VALUE <value>

 VARIABLE ASSIGN <name> TEXT <string>

 VARIABLE ASSIGN <name> XYZ <xyz location>

Groups of variables can be assigned values by means of a VARIABLE LOAD command. This command is related to the VARIABLE SAVE command. The latter command saves all currently active variables in a disk file with extension .VAR. These variables can then be reloaded with the VARIABLE LOAD command. See the SilverScreen Reference Manual for further details on these commands.

Groups of variables may also be assigned values with the VARIABLE V-EDIT command. This command is essentially a variant of the VARIABLE LOAD command. For further information on this topic, see the SilverScreen Reference Manual.

Variables can be assigned values as a result of a MEASURE command. There are roughly a dozen variables that are set by this command to reflect the result of a measurement. A listing of these variables appears at the end of this section.

Variables retain their values until they are unassigned with the VARIABLE UNASSIGN command, or until the CLEAR command is issued.

To use system variables in a SilverC program, the variable must first be defined in SilverScreen, either by using a VARIABLE ASSIGN command, or by loading a group of variables from disk using the VARIABLE LOAD command.

GEOMETRY MEASURE

The GEOMETRY MEASURE command family produces results that are assigned to various specific system variables. The following table describes the variable created, the SilverScreen command that creates it and the data type of the variable created (the GEOMETRY prefix is not included in the command description):