spec

Software for Diffraction

2.4.1.2. - Miscellaneous



lscmd
This command lists all the built-in commands, functions and keywords.

lscmd pattern ...
As above, except only names matching pattern are listed.

memstat
Shows the current memory usage.

eval(string)
Parses and executes the string string, which can contain one or more statements or statement blocks. If the last statement in the string string is an expression, its value is returned. A single number, a quoted string or a single variable is considered an expression and its value will be returned. However, a single uninitialized variable will generate an error.

If the last statement is not an expression, eval() returns true (nonzero) if there were no errors executing the statement(s). The type of errors that normally cause spec to reset to command level (syntax errors, for example) will cause eval() to return false rather than reset to command level.

To distinguish between a true (1) or false (0) return value and an expression returning a value, eval() assigns a code to the built-in global variable EVAL_RESULT (as of spec release 6.04.05). If EVAL_RESULT is -1, there was an error parsing or executing the string, or an attempt was made to return the value of a single uninitialized variable. If EVAL_RESULT is 1, the string was a statement or was a statement list that ended in a statement. If EVAL_RESULT is zero, the string or last statement in the string was an expression.

An empty string or a string containing only white-space characters is a special case. EVAL_RESULT is set to 1 to indicate a statement, but the return value of eval() is zero.

If the string string contains multiple statements, the value of EVAL_RESULT will 0 or 1 based on the result of the last statement. If any of the statements generate an error, EVAL_RESULT will be set to -1 and the parsing and execution of the statements in the string string is abandoned.

If there is an error parsing or executing the string, in most cases, an error message will be assigned to the built-in global variable EVAL_ERR (as of spec release 6.04.05).

EVAL_RESULT and EVAL_ERR are reset to 0 and "" respectively on each call of eval(). With nested calls to eval(), EVAL_RESULT and EVAL_ERR will be associated with the most recently completed call.

Note, local symbols defined in the statement block in which eval() is used are not visible to the statements in the string string. Use eval2(), below, to access such symbols.

eval2(string)
Similar to eval(), but local symbols in the statement blocks surrounding the eval2() function call are visible and can be read or modified. To use local variables within the eval2() string that won't be associated with local variables of the same name outside the eval2() call, use curly brackets to enclose the statements with the local declaration within the string string.

sleep(t)
Suspends execution for a minimum of t seconds, where t may be non-integral. Actual sleep times may vary depending on other activity on the system and the resolution of the system clock. Returns true . Can be interrupted with ^C.

gethelp(topic [, flags])
Displays the help file topic on the screen. If topic contains a / , the argument is treated as an absolute or relative pathname. Otherwise, the argument refers to a file in the spec_help (or help) subdirectory of the SPECD directory. Returns non-zero if the file couldn't be opened.

The SPECD/spec_help/.links contains a list of alternative help files names and topics. If an entry matching topic is listed in .links, the corresponding file will be displayed.

Prior to spec release 6, spec contained an internal help file parser and formatter. With release 6, help files are formatted using the standard groff utility and paginated using the standard less utility.

If the argument topic is a pathname and the optional flags argument has bit 0x02 set, spec will use groff formatting macros appropriate for help files written using pre-release 6 conventions.

Current spec help files are written in the format called .pdfhref W -D http://docutils.sourceforge.net/rst.html -- reStructuredText. The .rst files are included in the help subdirectory of the spec distribution. The spec distribution also includes versions of the help files converted to groff format and versions preformatted for pagination for a screen width of 80 columns. It is these files that are copied to the directories SPECD/spec_help/help_man and SPECD/spec_help/help_pre, respectively. The preformatted files are displayed if the current screen width is between 80 and 92 columns or if the groff utility is unavailable. Otherwise the groff files are processed and displayed to fit the current screen width. The gethelp() function will also create commands to process .rst files and pass them through groff and the paginator, but only if Python and the Python docutils package are installed.

The paths and options for the system tools used by spec's help facility are configured in the file SPECD/spec.conf.

whatis(string)
Returns a number that encodes what the identifier in string represents. The return value is a two-word (32-bit) integer, with the low word containing a code for the type of object and the high word containing more information for certain objects.
 High Word   Low Word   Meaning 

 0   0   Not a command, macro or keyword. 
 0   1   Command or keyword. 
 length   2   Macro (length is in bytes). 
 0x0001   4   A data array or data array element. 
 0x0010   4   Number-valued symbol. 
 0x0020   4   String-valued symbol. 
 0x0040   4   Constant-valued symbol. 
 0x0100   4   Associative array name. 
 0x0200   4   Built-in symbol. 
 0x0400   4   Global symbol. 
 0x0800   4   Unset symbol. 
 0x2000   4   Immutable symbol. 
 0x4000   4   Local symbol. 
 0x8000   4   Associative array element. 

Most type-4 symbols have more than one of the high-word bits set.

The following two macros uses the whatis() function. The first determines whether or not a symbol has been given a value by looking at the unset bit. The second checks whether or not a symbol is the name of a macro.
1.FOURC> def unset(x) '{ return(whatis(x)&0x8000000? 1:0) }'
2.FOURC> def is_macro(x) '{ return(whatis(x)&2? 1:0) }'
3.FOURC>



whatis(string, 1)
With two arguments, returns a printable string explaining in words what kind of thing the thing named in string is to spec.

spec_par(par [, value ])
Sets internal parameters. Typing spec_par("?") lists the available parameters, their current value and the default value, if different. The command spec_par("set_defaults?") sets all parameters to their default values. The currently available parameters are:


"auto_file_close"
The auto-file-close option is available to automatically close output files that haven't been accessed for some interval of time. The parameter units are hours, and the parameter can have nonintegral values. When the auto-close option is enabled, each time an on(), off(), open(), close() or fprintf() function is called, spec will check its list of opened output files. Any files which have not been written to for the length of time given by value hours will be closed. Enabling this option can help prevent errors when your macros or commands do not close files when appropriate, resulting in spec running out of resources to open additional files. As files are opened automatically when sent output, auto-close mode operates transparently for the most part. However, if you change to a different working directory between the time the file is first opened and subsequently automatically closed, and if the file is not opened by an absolute path name, the next time you refer to the file, spec will reopen it using a relative path based on the current directory. If value is zero, the mode is disabled. By default, the mode is initially disabled.

"auto_hdw_poll"
When automatic hardware polling is turned on (which it is, by default), spec will automatically poll busy motor controllers, timers and acquisition devices to determine when they are finished. For some devices, spec needs to perform an action, such as starting a motor backlash move, when the device is finished with its current business. Without automatic hardware polling, a call to the wait() function is necessary. A reason to turn it off may be to reduce the amount of debugging output during hardware debugging.

"check_file_names"
The check-file-names option can prevent you from (accidentally) creating files with names containing nonstandard characters. When enabled, if a file name passed to the on(), open() or fprintf() functions contains any of the characters ()[]{}|$'`*?;!&<>\\@, the space character, any control characters or any characters with the eighth bit set, and the file doesn't already exist, spec will print an error message and the function will fail. By default, this mode is on.

"confirm_quit"
If set, spec prompts with a "Really quit?" message when the . C quit or ^D commands are entered. The question must be answered in the affirmative to exit the program. The value for "confirm_quit" is not saved in the state file. The option must be set again on each spec invocation.

"elog_timestamp"
The time interval for the optional time stamps for the elog error file capability is set using this option. The units of the "elog_timestamp" parameter are minutes. The default value is five minutes. Note, time stamps are only added before a command or error message is logged, so that the interval between time stamps can be greater than that specified if no commands are being typed or errors generated.

"epics_timeout"
Sets the default timeout for channel access ca_pend_io() calls on EPICS. The default value is 0.5 seconds. This option appears only when spec is linked with the EPICS channel access libraries. Timeout values for individual process variables can still be changed with the epics_par() function. This parameter can be set in the config file.

"flush_interval"
The flush-interval parameter controls how often spec flushes output to the hard disk or other output device. Traditionally, spec flushed output after each print command. However, as some users report that this frequent flushing introduces considerable delays when the output device is to an NFS-mounted file system, the flushing interval can now be controlled. The "flush_interval" parameter specifies how many seconds to allow between output buffer flushing. The default value is 0.5 seconds. If the interval is set to zero, the traditional frequent-flushing behavior will be restored. Output to the screen is still flushed immediately. Output is also flushed each time the main spec prompt is issued.

"HKL_rounding"
Traditionally, spec rounded values for H, K, and L (and other geometry values derived from motor positions) to five significant digits for configurations using reciprocal space calculations. The rounding is off by default. It can be turned on using the command spec_par("HKL_rounding", 1e5) where the argument indicates the magnitude of the rounding, i.e., one part in 1e5, for example. Note, values with an absolute value less than 1e-10 are still rounded to zero whether or not the optional rounding is turned on.

"hdw_poll_interval"
When the wait() function is called to wait for polled motors, timers or other acquisition devices to finish, spec sleeps for a small interval between each check of the hardware. Use this spec_par() option to change that interval. The units of the parameter are milliseconds, and the default sleep time is 10msec. A value of zero is allowed, though not recommended if the computer is being used for anything else.

"history_join"
As of spec release 6.06.01, multi-line commands entered at the spec prompt are saved as one item in the history list. This option allows that mode to be disabled.

"history_size"
Configures the number of commands to be saved in the history list. The value can be any positive integer up to a set limit, currently 32768. Prior to spec release 6.05.01, the history size was fixed at 1000.

"keep_going"
Normally, when taking commands from a command file, spec resets to command level and the main interactive prompt when there are syntax errors in the file, certain floating point exceptions, references to unconfigured hardware, hardware access errors, along with a number of other errors. When the "keep_going" option is set, spec will keep reading and executing commands from a command file no matter what errors occur. When there is an error, the next line from the current command file will be read. Note, depending on where the error is in a file, reading subsequent lines may generate more errors, particularly if the error occurs inside a statement block.

"legacy_limit_check"
Prior to spec release 6.03.10, when a motor stopped, if either limit status was active, spec would report the motor hit a limit. Depending on how the controller reported the limit condition, this behavior could be an issue if the motor had executed a small move off an active limit, but hadn't moved enough to clear the limit switch. Even though the move was away from the limit, the limit status was still active, and spec would behave as if the move terminated due to a limit. Release 6.03.10 improves the logic so that the direction of the move is checked against the limit status, and no action is taken if the active limit is not in the direction of the move. It turns out that if spec's code for a particular motor controller had the sense of the plus and minus limits reversed, the old code worked, but the new code does not. The error in limit sense was found and fixed with one controller model. If the issue is found with additional controllers, CSS will correct the code. In the meantime, the "legacy_limit_check" option can be set to a nonzero value to enable the pre 6.03.10 behavior. Note, motors still stop when they hit a limit switch. The behavior that is affected concerns whether spec notices, prints a message and perhaps aborts other moves or a scan.

"modify_step_size"
Normally, spec doesn't allow users to modify the motor step-size parameter with the motor_par() function, as the consequences are generally undesirable. However, in the rare circumstance that it is necessary, this parameter allows you to enable such modifications.

"old_shared"
With spec release 5.02.01, the structure of the shared array header was changed so that the data portion of the array would lie on a memory page boundary. To allow compatibility with applications built with the old header structure, the "old_shared" option can be set. However, this option can only be set as a -o command line start-up option, and the parameter is not saved in the state file. It must be set each time spec is invoked.

"parse_units"
When parsing of units is turned on, numbers typed as input to spec's parser with one of the following suffixes appended will automatically be multiplied by the corresponding factor.
 1r   57.2958   radian 
 1mr   0.0572958   milliradian 
 1d   1   degree 
 1md   0.001   millidegree 
 1mm   1   millimeter 
 1um   0.001   micrometer 
 1m   0.0166667   minute 
 1s   0.000277778   second 

Note, however, suffixes on numbers converted from strings or entered using the getval() function are not parsed. The only known use for unit-suffix parsing is with the user-contributed macros in the file macros/units.mac. These macros require that unit suffixes be supplied for all motor position arguments in the standard spec macros. The default is for this mode to be off.

"show_prdef_files"
When this mode is on, the source file for each macro definition is displayed with the prdef command. The default is for this mode to be on.

"specwiz"
Allows spec administrators to gain access to motors locked out in the config file to ordinary users. This feature allows the administrator to position the motors without having first to go into the configuration editor to change access modes. Entering spec_par("specwiz", 1) causes spec to prompt for the "Wizard's password" ." If entered correctly, the characters _WIZ are appended to the spec prompt to remind the administrator of the special powers, and motors configured with protected status can be moved. Entering spec_par("specwiz", 0) disables the special mode. spec looks for the encrypted password belonging to the spec_wiz (or specwiz) user in the files SPECD/passwd, /etc/shadow, and /etc/passwd in turn. If a shadow password file is used, ordinary users won't be able to read it, and the normal password file won't contain the encrypted password. The spec distribution includes a wiz_passwd utility the can be used to create a passwd file in the spec auxiliary file directory that contains just the entry for the spec_wiz user. The SPECD/passwd file should probably be owned and writable only by root or the spec administrator. Note, the standard macros onwiz and offwiz are convenient wrappers for the specwiz feature.

"use_sem_undo"
This flag relates to whether the SEM_UNDO flag is set when semaphores are used. It exists to get around a memory leak bug observed with some releases of the Solaris 2 operating system. The flag should be ignored unless you are instructed otherwise by CSS.

"warn_not_at_pos"
When enabled, spec prints a warning message whenever a motor doesn't reach its final position (as of release 5.08.02-8).


calc(i)
Calls a user-added function having code i. Codes are assigned in the distribution source file u_hook.c. Returns a user-supplied value or zero if there is no user-supplied value.

calc(i, x)
As above, but passes the argument x to the user-supplied function.

The geometry calculations that transform motor positions to reciprocal space coordinates and vice versa are implemented using calls to calc(). A description of the particular calls implemented for the four-circle diffractometer are in the Four-Circle Reference. See 5.3.4 in the Administrator's Guide for information on how to include other user-added functions in the program.

history
This command lists the most recently entered commands. The maximum number of commands can be set using the spec_par("history_size") command (see 2.4.1.2 and defaults to 1000. See the description of the command-recall (history) feature 2.3.10

history N
As above, but only prints the N most recent commands. If N is negative, the commands are printed in reverse order.

savstate
Writes the current state to the state files.

The state file contains the variables, macro definitions, output file names and additional parameter values unique to each user, terminal and diffractometer. A separate file stores the user's command line history. The state files preserve the current situation when the user leaves the program, so that the same situation can be restored when the user later returns to the program.

spec can be invoked with a -u user flag and a -t tty flag. These flags instruct the program to initialize the current user's state from the files associated with the other user and/or terminal. Subsequent savstate commands access the user's natural state file.

The savstate command does not save the state files until the entire parsed mini-program in which the command occurs has been run. spec also automatically does a savstate before re-reading the hardware config file when the reconfig command is entered and when spec exits.

Note, a show_state utility is included in the spec distribution. This utility can display the contents of spec state files. Type show_state - to see the utility's usage message.