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.