spec

Contents → REFERENCE MANUAL → Syntax Description → Variables → Built-In Variables

← Prev | Next →

The following is a list of most of spec's built-in variables. Some site-dependent code, along with most of the standard diffractometer geometry code, will create additional built-in variables. Also, motor and counter mnemonics entered in the hardware configuration file become built-in variables when the config file is read by spec.

A[]

is an array dimensioned to the number of motors as obtained from the config file. The function read_motors(0) fills the array with user angles. The user can assign values to any of the elements. The commands move_all and move_cnt use the values in the array. Also, the various site-dependent, geometry-specific calculations, accessed through the calc() user-hook function, base their results on the values in this array or place new values in it.

CCDS

is the number of 2D image-type devices being used as determined from reading the config file.

COLS

is a number-valued variable set to the number of text columns on the user terminal or workstation window. The value is used for formatting text-mode plots and on-line help files. COLS is generally automatically assigned a value from the system terminal data base when spec starts up, or, if available, by using the TIOCGWINSZ command in the ioctl() system call whenever a value for COLS is needed.

COUNTERS

is the number of counters being used as determined from reading the config file.

CWD

is a string-valued variable that contains the name of the user's current working directory. It is assigned a value when spec starts up, and is updated each time the chdir() function is executed.

DEBUG

is a user-assignable numeric variable that determines the level of debugging messages printed. The level is determined by the sum of the values given in this table:

Hex	Decimal	What is shown
0x1	1	Show input tokens during parsing.
0x2	2	Show node execution while running.
0x4	4	Show node allocate and free.
0x8	8	Show symbol table creation and lookup.
0x10	16	Show value get and set.
0x20	32	Show misc info.
0x40	64	Show hardware related info.
0x80	128	Show more hardware related info.
0x100	256	Show macro substitution.
0x200	512	Show memory allocate and free.
0x400	1024	Show input after macro expansion.
0x800	2048	Print warning messages.
0x1000	4096	Show certain low level hardware info.
0x2000	8192	Show data array allocation.
0x4000		Show signal blocking.
0x8000		Show sleeps and other low level hardware info.
0x10000		Show input file queuing.
0x20000		Show readable runtime debugging.
0x40000		Print input context on execution-time errors.
0x40000		Print input context on execution-time errors.
0x80000		Show sleeps.
0x100000		Show thread stuff.
0x200000		Show state changes.
0x400000		Use hexadecimal for socket debugging output.
0x800000		Show server/client socket messages.

If a debugging log file is open (any file that begins with the characters dlog or ends with the characters .dlog), debugging messages are only written to that file, not to the screen or any other file or device.

DISPLAY

is a user-assignable, string-valued variable. Its value at the time an X-Windows graphics filter process is spawned with the plot_cntl("open") function (with GTERM set to "x11") determines on which host and screen the plot window will be displayed. The initial value for DISPLAY is taken from the environment variable of the same name.

EVAL_ERR

is a built-in variable that will be assigned error messages generated by errors from parsing or executing strings passed to the eval() or eval2() functions. See the eval() function 2.4.1.2 for details.

EVAL_RESULT

is a built-in variable with a value set by the eval() or eval2() functions. If EVAL_RESULT is -1, there was an error parsing or executing the command string, or an attempt was made to return the value of a single uninitialized variable. If EVAL_RESULT is 1, the command string was a statement or was a statement list that ended in a statement. If EVAL_RESULT is zero, the command string or last statement in the string was an expression. See the eval() function 2.4.1.2 for details.

FRESH

is a built-in variable that has an initial nonzero value if spec was invoked with the -f (fresh start) flag or if a fresh start was forced by an incompatible state file version. The value is zero otherwise, and is set to zero in any case after all start-up command files and macros have been read and their commands executed. In the standard start-up macros, the value of FRESH is checked to see if initial default parameter assignments should be made.

GETLINE_EOF

is a built-in variable set by the getline() function to distinguish between an end of file, an error or a literal -1 read from the file. The value of GETLINE_EOF will be 1 if there was an end-of-file condition on the read of the file, -1 if there was an error reading the file or if the file couldn't be opened and zero if the read was successful. See the getline() function 2.4.2.3

GTERM

is a user-assignable, string-valued variable containing a value describing the display type to use for high-resolution graphics. Its value will be taken from an environment variable of the same name when spec starts up, if such a variable exists. The only currently supported GTERM value is x11 for X Window System graphics. If GTERM is not set in the environment or has not been assigned a value, it defaults to x11. Legacy values of vga, ega, herc, sun, etc. are no longer supported.

HDW_ERR

is a user-assignable number-valued variable that can be set before hardware calls to affect how spec responds to certain errors. After hardware calls, the value of HDW_ERR conveys information on any errors encountered. By default, certain hardware errors cause spec to reset to command level. By setting HDW_ERR to -1 before a call to user-level hardware access functions, there is no reset, the function returns and HDW_ERR contains an error code.

Functions which set HDW_ERR include counter_par(), motor_par(), mca_par(), ca_get(), ca_put(), ca_fna(), gpib_get(), gpib_put(), gpib_poll(), gpib_cntl(), gpib_par(), port_get(), port_getw(), port_put(), port_putw(), ser_get(), ser_put(), ser_par(), sock_get(), sock_put(), sock_par(), fbus_get(), fbus_put(), vxi11_get() and vxi11_put().

When there is an error in these functions, they usually return -1, or sometimes zero. However, such values can also be valid return values. If one is doing error checking, one should check HDW_ERR after the function call. The following table lists the possible values for HDW_ERR and what each value indicates:

1	Generic error
2	GPIB no listener
3	Timeout
4	A non-fatal error
5	Function called with bad argument
6	Trying to access unconfigured hardware
7	Function called with bad address
8	Lost connection
9	User abort (^C)
10	Unresponsive hardware
11	Disabled hardware
12	Bad parameter
13	Read only parameter
14	Write only parameter

If the value of HDW_ERR is -1 before the call to the user-level hardware access function, no reset to command level will take place for any errors. Otherwise, traditionally fatal errors will still be fatal.

HOME

is string valued and is initialized to the user's home directory as taken from the environment variable HOME. If not found in the environment, its value is set to the current directory.

HOSTNAME

is a built-in variable containing the platform host name as returned by the gethostname() system call.

IS_SERVER

is a built-in variable that contains the TCP port number on which spec is listening if running in server mode. Otherwise, the value is zero.

MCAS

is the number of 1D MCA-type devices being used as determined from reading the config file.

MOTORS

is the number of motors being used as determined from reading the config file.

OUTFILES[][]

is a two-dimensional associative array that holds information about all open output files. The first index is the name by which the file was opened using open(), on(), fprintf() or the -l outputfile start-up option. Currently, only two options are available for the second index: "name" and @path@. The "name" element repeats the name used for the first index. The "path" element is the full path name of the file. Additional elements may be added in the future. For example:

1.FOURC> for (i in OUTFILES[]["name"])
2.more>      printf("%10s %s\n",OUTFILES[i]["name"],OUTFILES[i]["path"])
      dlog /tmp/dlog
     data1 /tmp/data1
       tty /dev/tty
 /dev/null /dev/null

3.FOURC> 

or

1.FOURC> p OUTFILES[DATAFILE]["path"]
/private/tmp/data1

2.FOURC> 

Note, the special built-in name "pipe" is not included in OUTFILES. The special built-in name "/dev/null" includes the full path in both "name" and "path" to work with the standard macros that always refer to that special file by the full path name.

PI

is a number-valued symbol with the value 3.14159....

ROWS

is a number-valued variable set to the number of text rows on the user terminal or workstation window. The value is used for formatting text-mode plots and on-line help files. ROWS is generally automatically assigned a value from the system terminal data base when spec starts up, or, if available, by using the TIOCGWINSZ command in the ioctl() system call whenever a value for ROWS is needed.

S[]

is an array that will be filled with the hardware scaler contents when the command getcounts is executed.

SPEC

is string valued and set to the name by which spec is invoked, such as fourc.

SPECD

is string valued and set to spec's auxiliary file directory. The default name is compiled in when spec is installed, but can be overridden by the -D invocation option or by the SPECD environment variable.

TERM

is a user-assignable, string-valued variable. It is initialized to the user's terminal type as taken from the environment variable TERM. If not found in the environment, it is set to terminal-type vt100.

USER

is string valued and is set to the login name of the current user.

VERSION

is string valued and is set to the version number of spec, as in 3.03.11.

The values of A[], S[], DEBUG, HDW_ERR, DISPLAY, TERM, GTERM, ROWS and COLS can be changed by the user.

Motor mnemonics obtained from the config file become built-in, immutable variables. User-added code, such as the X-ray diffractometer geometry code, typically creates other built-in variables, such as G[], Q[], U[] and Z[].

Top ↑

← Prev | Next →