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 commandsmove_all
andmove_cnt
use the values in the array. Also, the various site-dependent, geometry-specific calculations, accessed through thecalc()
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 theTIOCGWINSZ
command in the ioctl() system call whenever a value forCOLS
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 charactersdlog
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 (withGTERM
set to"x11"
) determines on which host and screen the plot window will be displayed. The initial value forDISPLAY
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()
oreval2()
functions. See theeval()
function 2.4.1.2 for details. EVAL_RESULT
- is a built-in variable with a value set by the
eval()
oreval2()
functions. IfEVAL_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. IfEVAL_RESULT
is 1, the command string was a statement or was a statement list that ended in a statement. IfEVAL_RESULT
is zero, the command string or last statement in the string was an expression. See theeval()
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 ofGETLINE_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 thegetline()
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 isx11
for X Window System graphics. IfGTERM
is not set in the environment or has not been assigned a value, it defaults tox11
. Legacy values ofvga
,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 settingHDW_ERR
to -1 before a call to user-level hardware access functions, there is no reset, the function returns andHDW_ERR
contains an error code.
Functions which setHDW_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()
andvxi11_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 checkHDW_ERR
after the function call. The following table lists the possible values forHDW_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 ofHDW_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>
or1.FOURC> p OUTFILES[DATAFILE]["path"]
/private/tmp/data1 2.FOURC>
Note, the special built-in name"pipe"
is not included inOUTFILES
. 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 theTIOCGWINSZ
command in the ioctl() system call whenever a value forROWS
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[]
.