spec

Software for Diffraction

2.3.15.1. - Built-In Variables



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[].