SYNOPSIS

syms [-v] [+|-BGLADNSICW] [name ...]

DESCRIPTION

The command syms lists spec's current variables. Without arguments, all the variables are listed, along with their memory consumption and type. With the -v flag, the variables are listed along with their values in a format that can be saved to a file and read back as commands.

If arguments are given as name  ..., only symbols matching the arguments are printed. Such arguments may contain the *, ? and [] metacharacters. A * matches any string, while a ? matches any single character. With the [...] pattern, any string that contains the characters within the square brackets is matched. Two characters separated by a hyphen specify a range of characters that will match. An initial ^ negates the enclosed character set. (Support for [] added in spec release 6.07.)

Note, the -v flag does not display the values of the data arrays. Rather, a declaration suitable for creating the array is printed. Such a declaration does clear the contents of an already existing array.

In addition, the type of symbols listed can be controlled using the flags in the following table where a - flag prevents symbols with the given attribute from being listed and a + flag includes symbols with the given attribute in the list.

B	Built-In
G	Global
L	Local
A	Associative array
D	Data array
N	Number type
S	String type
I	Immutable attribute
C	Constant attribute
W	Watched
M	Monitored

Symbol attributes are as follows:

Built-In

Symbols that cannot be removed.

Global

Symbols that retain their value outside of statement blocks. All built-in symbols are global.

Local

Symbols that have scope only within the statement block in which they are used.

Constant

Global symbols that cannot have their value altered by ordinary assignment. They can only have their value altered using the constant command.

Immutable

Built-in symbols that cannot have their value altered.

Watched

On a spec server, if a client has registered to get events sent to it when the value of a symbol changes, that symbol is "watched".

Monitored

When spec is linked with EPICS libraries (see the epics help file), indicates the symbol has been linked to a process variable. The value of such a symbol can only be changed by EPICS events. Only global symbols can have a monitored attribute.

Symbols can be of string, number or array type. They may be of both string and number type simultaneously. There are two array types: associative and data.

The print command always prints the string representation of a symbol. The printf() and sprintf() functions print the number or string representation, depending on the given format specifications. Arithmetic operators use the number value of a symbol. The relational operators >, <, <= and >= use the number value if both operands are of number type, otherwise the string values are lexicographically compared.

If the string value of a symbol cannot be interpreted as a number, its number value is zero.

A nonglobal symbol is automatically brought into existence within a statement or statement block ({ ... }) simply by using its name.

A symbol assigned a value at the top level (outside of any curly brackets) is automatically made global.

The local command forces the scope of a symbol to be within the current statement block and allows reuse of global names within statement blocks. Names already used as macro names may be used as local symbols within a statement block, although that macro then becomes unavailable within that block.

BUILT-IN SYMBOLS

spec's built-in symbols include the following:

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. It is 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. The value is updated whenever certain built-in functions that format text, such as tty_move(), tty_fmt(), get_help() or spec_menu(), are called. The user-level function tty_cntl("resized?") forces an update to COLS and ROWS.

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. See the debug help file for a list of the debugging levels. 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 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 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.

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. See the HDW_ERR help file for details.

HISTCMD

is the current command line history number.

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 and devices. The first index is the name by which the file was opened using open(), on(), fprintf() or the -l outputfile start-up option. Currently, three values are available for the second index: "name", "path" and "basename". The "name" element repeats the name used for the first index. The "path" element is the full path name from the root directory. The "basename" element is the last component of the path. It may differ from "name" if the file was opened with a path name. ("basename" added in spec release 6.11.01.)

Note, 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. Also, the special built-in name "pipe" (associated with the -p start-up option) is not included in OUTFILES.

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. It is 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. The value is updated whenever certain built-in functions that format text, such as tty_move(), tty_fmt(), get_help() or spec_menu(), are called. The user-level function tty_cntl("resized?") forces an update to COLS and ROWS.

S[]

is an array dimensioned to the number of scalers as obtained from the config file. The command getcounts fills the array with counter values. The user can assign values to any of the elements.

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.

SPEC_PID

is a number valued variable assigned the process ID of the spec process.

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 6.07.01.

The values for CCDS, COUNTERS, CWD, FRESH, HISTCMD, HOME, HOSTNAME, IS_SERVER, MCAS, OUTFILES, PI, SPEC, SPECD, SPEC_PID, USER and VERSION are immutable and cannot be changed.

Motor and counter 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[], UB[] and Z[].

A built-in, immutable variable is created for each shared-memory data array. The variable name is the array name prepended by SHMID_.

EXAMPLE

SPEC> syms T*

   80 (G.NS.) TEMP_CS       96 (G..S.) TITLE
   80 (G.NS.) TEMP_SP       80 (G.NS.) T_AV
   96 (G.N..) TERAMP_MIN    80 (G.N..) T_HI_SP
   96 (B..S.) TERM          80 (G.NS.) T_L
   80 (G.NS.) TIME          80 (G.N..) T_LO_SP
   96 (G.NS.) TIME_END


SPEC> syms -v T*

TEMP_CS = 0
TEMP_SP = 0
TERAMP_MIN = 0.2
TERM = "xterm"
TIME = 0
TIME_END = 0
TITLE = "fourc"
T_AV = 0
T_HI_SP = 100
T_L = 0
T_LO_SP = -100