Beckman Institute            University of Illinois at Urbana-Champaign             

Documentation Table of Contents

This chapter will show you how to configure Syzygy to work with your equipment.

• The Syzygy Database
• Loading a Parameter File with dbatch
• Printing or Saving Lots of Parameters with dget
• Global and Local Parameters
  • Global Parameters
    • Global Graphics Parameters
    • Global Input Device Parameters
    • Getting and Setting Global Parameter Values
  • Local Parameters
    • Getting and Setting Local Parameters
    • Categories of Local Parameters
    • Resource Path Specification
    • Virtual Computers
• Parameter File Format
  • Example Parameter Files

The Syzygy Database

Syzygy maintains a database for storing useful bits of information in a way that your program can easily get at. Some of this information is used by the Syzygy libraries to configure your application; you can also use it for storing your own application parameters.

In Standalone Mode, the information is read in from a parameter file (by default, named either szg_parameters.xml or szg_parameters.txt) in the current directory. You make changes to the configuration by editing this text file before launching the application.

In Cluster Mode, this database is maintained by the Syzygy Server and accessed from within the application by means of the arSZGClient object. The database parameters can be examined and changed one at a time using the dget and dset commands, or they can be set in large batches by invoking the dbatch command with the name of a parameter file. Happily, the parameter file for the dbatch command has the same format as the Standalone Mode parameter file. A separate set of parameters is maintained for each user, so any database commands will access the database for the last user logged in to the Syzygy server using the dlogin command.

Loading a Parameter File with dbatch

This is the simplest way to load a large number of parameters in to the Syzygy database. To load a file-full of parameter information, type:

  dbatch <file path>

<file path> can be either an absolute or relative path from the current directory or a file name. If the latter, dbatch will look for the file in the current working directory. If it isn't there, it will query the Syzygy database for the value of the local parameter SZG_SCRIPT/path. If this parameter is defined it will interpret it as a directory path and look for the named file there.

Printing or Saving Lots of Parameters with dget

Typing:

  dget -a

will print all of the current user's database parameters. If you're using a command shell that allows redirection of the standard output to a file, (e.g. ``dget -a >myparams.xml") you can have the output saved to a file that can be used as the input for a subsequent dbatch command.

To list all parameters containing a particular string (either in the computer name, group name, parameter name, or value), type:

  dget -a <string>

For example, dget -a my_computer will print out all parameters defined for the computer 'my_computer`, and any other ones that happen to contain that string (single lines from virtual computer definitions, for example).

Global and Local Parameters

There are two types of parameters in the Syzygy database, global (i.e. not specific to any computer) and local (computer-specific).

Global Parameters

Global parameters contain information that is not tied to a particular computer in the cluster. There are two main types of global parameters: graphics configurations and input device descriptions. These parameters allow the user to define complex attributes of the system --for example, a graphics window corresponding to one eye of a head-mounted display, or the configuration of a tracking device--without having to consider which computer will perform those functions. This facility makes it easier to re-arrange and replace computers in your cluster.

Global parameters are keyed only by name, and their values are specified in XML. Their structure can be quite complex, so they are discussed in two separate chapters:

Global Graphics Parameters

Read the Syzygy Graphics Configuration chapter.

Global Input Device Parameters

Read the Syzygy Input Device Configuration chapter.

Getting and Setting Global Parameter Values

When running a Syzygy cluster, it is possible (although not very practical) to get and set values of individual global parameters at the command line.

To set a single global parameter using the dset command, type:

    dset parameter_name parameter_value

However, the value is typically a longish XML string; global parameters are generally specified in a parameter file.

Similarly, you could set a single parameter value using:

    dget parameter_name

Local Parameters

Local parameters give information that is particular to a given computer. They are specified or keyed within the database by the computer name, a parameter group, and the parameter name. In documentation, these are typically written as a slash-delimited string, i.e.

    <computer name>/<parameter group>/<parameter name>

For example, the parameter to tell a computer named 'my_computer' the standard location for data files, is represented by:

    my_computer/SZG_DATA/path

However, to set these parameters, use the format below.

Getting and Setting Local Parameters

When interacting with the database, either via dget and dset in Cluster Mode or in a parameter file, the key elements are separated by spaces. A parameter file entry line for the parameter above might look like this:

    my_computer SZG_DATA path G:\Data

or to set it in Cluster Mode using dset, you might type this:

    dset my_computer SZG_DATA path G:\Data

If you were to then type

    dget my_computer SZG_DATA path

the command would return the value

    G:\Data

Categories of Local Parameters

Head Parameters

See the relevant section in the Syzygy Graphics Configuration chapter.

Display Selection

See the relevant section in the Syzygy Graphics Configuration chapter.

Resource Path Specification

Read the chapter on Resource Path Specification.

Virtual Computers

A virtual computer is a means of specifying how a set of computers are wired together and what functions each will perform. You run a program on a virtual computer by issuing a single command; the separate instances of the program and any supporting services are then launched automatically.

See Virtual Computer Configuration and Using a Virtual Computer for more information.

Parameter File Format

Syzygy parameter files are written in XML. A parameter file can contain 3 types of XML records, <comment>, <assign>, and <param>. These records cannot be nested. For instance, a <comment> block cannot appear within an <assign>. They can appear in the file in any order, however, and there can be any number of them.

A <comment> record contains a comment. These are discarded by the parser. An <assign> record contains either a list of local parameter definitions or a virtual computer definition. Finally, a <param> record contains a global parameter definition.

Here is an example. Note the required <szg_config>/</szg_config> tags that enclose the entire file:

    <szg_config>
      <comment>
        This is what comments look like in a complex parameter file.
        The following 'assign' record contains a number of local
        parameter definitions.
      </comment>
      <assign>
        smoke SZG_DATA path /home/public/Data
        smoke SZG_RENDER texture_path /home/public/Texture
        smoke SZG_RENDER text_path /home/public/Texture/Text
        smoke SZG_SOUND path /home/public/Sounds
        smoke SZG_DISPLAY0 name head_mounted
      </assign>
      <comment>
        The following 'param' record contains a global device definition.
      </comment>
      <param>
        <name> windows_joystick_filter </name>
        <value>
          define filter_axis_0
            getCurrentEventAxis 0.000031 * setCurrentEventAxis
          enddef
          define filter_axis_1
            getCurrentEventAxis -0.000031 * setCurrentEventAxis
          enddef
        </value>
      </param>
    </szg_config>

Example Parameter Files

We've included several templates for the main parameter files in use at the Integrated Systems Lab. For each template, a valid configuration file for a particular user is generated by substituting his Syzygy user name for "THE_USER_NAME".

The file cube.txt gives a template parameter file for a 6-sided fixed screen VR environment (virtual computer=cube). It also demonstrates how different virtual computers (cube and wincube) can share the same virtual computer location (cube).

The file lab.txt gives a template parameter file for a lab containing a group of workstations, a dual-headed passive stereo display (virtual computer=passive), an Immersadesk-style active stereo display (virtual computer=idesk), and a 3x2 video wall (virtual computer=wall). This template also demonstrates the use of include directives in dbatch files. The include locations are given by SZG_SCRIPT local parameters and the included files contain screen configurations, device configurations, and virtual computer definitions respectively.

The file cave.txt gives a template parameter file for a 4-sided fixed screen VR environment (virtual computer=cave).

[Schedule] [Labs] [Beckman Meeting Rooms] [Equipment] [Projects] [CUBE Projects] [Syzygy] [VSS] [People] [Events] [Publications]