Release Date: 1 February 2008
Nameoptions - Daylight Options
DescriptionDaylight programs and user interfaces use a consistent, powerful mechanism for controlling adjustable program values. Options include user-interface preferences (e.g. fonts, colors), parameters defining the local environment (e.g. operating system, database search path), and a few adjustable system values (e.g. directory containing the software, location of license key file).
The Daylight Toolkits do NOT require any options. In the Daylight system, options are used only for application programs and interfaces (application programs such as xvthor, and by the Widgets).
All options are defined in an "options definition file". The default file is $DY_ROOT/etc/unix/dy_options.dat for Unix (For Unix, $DY_ROOT is typically /usr/local/daylight/v4xx, where "xx" is the particular release).
In any case, the options file definition may be specified by defining the environment variable DY_OPTIONS. This file consists primarily of "include" directives which include other .dat files which contain option definitions, separated by application (e.g. dy_xvmerlin.dat). Option definitions in these .dat files define all properties of an option, including its name, type (STRING, INTEGER, REAL, BOOLEAN), description, limits (LOWER, UPPER), emumeration (ONEOF), class (FLAGS), and initial value. An example entry (from dy_widgets.dat) is:
STRING OPTION TRACKBALL_DEPTHCUE_COLOR TITLE: Default trackball depth cueing method FLAGS: WIDGETS, TRACKBALL, XWINDOWS, COLOR ONEOF: NONE|STYLE|WIDTH|GRAYSCALE VALUE: NONE
These .dat files are NOT user-servicable: the definitions match what is coded into the corresponding program and should never be modified or extended.
The attribute of interest to both managers and users is the option value. Option values may set in the following ways (in increasing priority):
1. Options are defined in dy_options.dat (or DY_OPTIONS), and in the files it includes (look for "#include" statements). The initial value is set on the VALUE: line. This should be set to a reasonable default that will work for everybody. Do not change these values. For instance, the value of the option TRACKBALL_DEPTHCUE_COLOR is NONE (as defined above).
2. The option SYSPROFILE (typically "dy_sysprofile.opt") names a file that will be read for ALL users at a particular site. System managers typically put modifications here that they want for everyone on their system. A profile is a file, with suffix ".opt" by convention, which contains option value settings in the format:
<name> = <value>
For instance, if the system profile contained the line
TRACKBALL_DEPTHCUE_COLOR = WIDTH
then all trackball (3-D) widgets run on color devices on the system would default to line-width depth cueing, superceding the initial setting of NONE. Note that if you define SYSPROFILE to be "$HOME/dy_mysysprofile.opt", your programs won't see the normal system-wide profile options.
3. The option PROFILE (default $HOME/dy_profile.dat) names a file that is specific to each user. This is in the same format as SYSPROFILE. Users who prefer grayscale depthcueing might add this line to their PROFILE:
TRACKBALL_DEPTHCUE_COLOR = GRAYSCALE
which will override their system default.
4. An environment variable DY_XXX sets a value for option XXX, overriding other defaults. E.g., this sh(1) script invokes xvmerlin with style:
DY_TRACKBALL_DEPTHCUE_COLOR = STYLE export DY_TRACKBALL_DEPTHCUE_COLOR xvmerlin $*
csh(1) users need only use:
setenv DY_TRACKBALL_DEPTHCUE_COLOR STYLE xvmerlin $*
5. A command-line option -XXX overrides an option XXX. For example, this sh (or csh) command does the same job as above, but only for this run:
xvmerlin -TRACKBALL_DEPTHCUE_COLOR STYLE $*
6. Finally, a program can override or reset (or ignore) any option it likes. This is mainly of interest only to Widget programmers, but the consequences to the user are that programs like the Edgar Widget can be used to set various options.
Many options take optional values. These options all must be specified with an option name and value or it is an error. Options which are defined as 'LOGICAL' in the options definition files can have values of either TRUE or FALSE.
When logical options are specified on the command line there are several valid syntaxes which may be used. Consider the option:
LOGICAL OPTION VERBOSE TITLE: Print more information as program progresses VALUE: FALSE
On the command line to a program the option may be specified several ways for each value: -VERBOSE TRUE or +VERBOSE both set the value to TRUE, and -VERBOSE FALSE or +NOVERBOSE both set the value to FALSE. The +OPTION and +NOOPTION work for all LOGICAL options.
It is often necessary to have different option values for different users or different machines. For example, users on different machines may have different printer commands.
Conditional evaluation of lines in a .opt file is possible using the "#if/#else/#endif" directives. These statements allow you to check the value of specific environment variables and selectively set option values.
Note that the #if statement does NOT look at option values, only environment variables, and that #if phrases can't be nested.
Two environment variable are set automatically if undefined when a Daylight program starts:
DY_OPERATINGSYSTEM set to "uname -s" (e.g. SunOS, IRIX) DY_HOSTNAME set to "uname -n" (i.e. the hostname)
These can be used to set operating-system and machine-specific options in a single .opt file that is shared by many users on many machines.
We also recommend that you set the environment variable DY_WINDOW_ENVIRONMENT to name the windowing environment you are using; e.g. SGI_4DWM, SUN_OLWM,etc. The file $DY_ROOT/etc/unix/dy_sysprofile.opt shows how this works.
In addition, you may want to customize the dy_sysprofile.opt file using your own environment variables. For example, each user could define a variable DY_PRINTER to one of "LP1", "LP2", etc. You could then have the proper options set up for each printer, e.g.:
#if DY_PRINTER LP1 PRINT_PS_COLOR_CMD = lpr -h -Plp1 %s & ... etc. #endif
#if DY_PRINTER LP2 PRINT_PS_COLOR_CMD = lpr -h -Plp2 %s & ... etc. #endif
There are several kinds of errors that can arise when using options.
First, a program might request an expected option only to find that it has not been defined. This is a very serious problem; the program is not working with a definition of its environment that it understands, because the option definition file is not in place, or is not a compatible version. In such cases, the program prints out the required option and exits.
Second, the option manager might encounter an invalid value for an option, for instance, if TRACKBALL_DEPTHCUE_COLOR was set to something invalid, like PINK. In such cases, the initial value is restored and a warning is generated.
Also, when an option missing its value, programs will generally print out an error message and exit.
Finally, the option manager might encounter a command line option which it doesn't know, for instance, if a user entered:
$ xvthor -TRACKBALL_DEPTHCUEING_METHOD NONE
In such cases, the offending option is ignored and a warning is generated.
The Daylight system requires very few environment variables. When running application programs, the only ones actually required are DY_ROOT, defining the Daylight root directory, plus a platform-dependent environment variable which sets the runtime library path (typically LD_LIBRARY_PATH, etc.).
Environment variables are also used as part of the values of some of the option entries. If these are not set the default option values may not be useful (although the programs will execute properly). The definitions supplied with the release use:
DY_ROOT ..... the location of Daylight software HOME ........ the option PROFILE is set to $HOME/dy_profile.opt DY_THORDB ... DATABASE_PATH is set to $DY_THORDB
User-written toolkit programs do not use the option manager. Environment variables are only needed for licensing (see licensing(5)).
Related Topicsclogp(1) cmr(1) dayevict(1) daymessage(1) fingerprint(1) jarpat(1) jpscan(1) mcl(1) mergeneighbors(1) merlindbping(1) merlinload(1) merlinls(1) merlinping(1) merlinserver(1) merlinwho(1) nearneighbors(1) prado(1) rubicon(1) showclusters(1) sthorman(1) tablet(1) tdtcat(1) tdtcount(1) testlicense(1) thorchange(1) thorcrunch(1) thordbinfo(1) thordbping(1) thordelete(1) thordestroy(1) thordiff(1) thordump(1) thorfilters(1) thorlist(1) thorload(1) thorlookup(1) thorls(1) thormake(1) thorping(1) thorserver(1) thorwho(1) treetops(1) xvmerlin(1) xvthor(1) licensing(5)