2.4.1.2. - Miscellaneous
gethelp(topic)-
Formats and displays the help file with the name
topic
to fit the current screen size (as defined by the built-in
variables
ROWS and
COLS). The argument
topic
is a string constant or expression.
If
topic
is a path name containing the
/ character, that is the path name used for locating the file.
Otherwise, the file must be in the subdirectory
help
of spec's auxiliary file directory, given by the global variable
SPECD. The function returns nonzero if the file
could not be opened.
spec will also read a file named
SPECD/help/.links that contains a list of help topics and file names.
If a file corresponding to
topic
is listed in
.links,
that file will be displayed.
Normally, the help file is displayed one screenful at a time.
At the end of each page, the user may type
<space>,
<return>,
y
or
Y
to see the next page,
b
to go back a page or anything else to return to the spec prompt.
If the variable
PAGER is set, the command therein is executed with the formatted help file
as input.
Typically,
PAGER is set to a pagination utility such as the
more
or
less
programs.
The help file contents are only written to the screen or display window
and not to any other turned on output files or devices.
The syntax recognized by
spec's built-in formatting
uses the conventions of the traditional
UNIX text formatters (nroff,
troff,
ditroff,
etc.),
although only a small subset of the formatting directives are
supported.
Those are described below.
The spec distribution includes utilities
for preparing both PostScript and HTML (hyper text mark-up language)
versions of the help files using either the standard
ditroff
or the GNU
groff
packages.
Input text that has a dot on the first line is a formatting
command.
Unrecognized formatting commands are ignored.
A
command such as
ft ...
can be used to insert commands to be executed only when the help files
are being printed with
troff,
etc., as the
f
is not recognized by spec.
The following commands are supported:
.\"-
Begins a comment.
The rest of the text on the line is ignored.
.bp-
Begins a new page.
.BP-
Same as above.
.ne N-
Indicates
N
lines are needed on the current page.
If there isn't enough room on the current page, a new page is started.
.sp N-
spaces
N
lines.
Without an argument, one line is skipped.
The argument may contain a decimal point and a unit indicator for the
benefit of
nroff/
troff,
although with spec, only the integer part of the argument is
used.
.ta N-
Start words every
N
letters, somewhat like using tabs.
.br-
Causes a line break.
The current line is finished and a new line is started.
Useful for forcing a newline in fill mode.
.fi-
Switch to fill mode. Words are collected from the input until
a full line of output is available.
.nf-
Switch to no-fill mode. Each newline in the input causes a newline
in the output.
.TH name category date SCCS_info-
Should be on the first line of a help file.
The arguments are used in the page header (and footer, when printed) and
are, respectively, the name of the help file, the category (such as
macro, function, reference, etc.), the date the file was last revised
and the source-code control information.
.SH subhead ...-
Does a subhead.
There can't be more than six arguments, although you can use
double quotes to put more than one word in an argument.
Subheads are placed all the way to the left of the page.
.HP N-
Starts a hanging paragraph.
The optional argument
N
specifies the indent level.
The default is 0.
.hp N-
Can be used within a
.HP block to increase or decrease the indent.
The optional argument
N
specifies the indent level.
This command will skip a line.
.PP-
Starts a paragraph.
.LP-
Same as above.
.(L F N I-
Starts a no-fill block.
The optional argument
F
indicates the font to use and may be
R, I, C, B or
O. (See below for a description of the font code letters.)
The optional argument
N
is the number of lines needed.
If there is not enough room to print that many lines on the current page,
a new page will be started.
The optional argument
I
is the number of spaces of extra indentation to add.
.)L-
Ends the no-fill block started by
.(L.
.Q-
Puts quotation marks around the arguments.
If no arguments, puts quotation marks around text on the next input line.
.NE-
Only relevant for screen displays, this command indicates the screen
should not be erased before displaying the first page.
#-
Starts a comment if it is the first character on a line.
The rest of the text on the line is ignored.
This comment notation is only for files that will not be run off
using
nroff/
troff.
.BL-
Begin a list of items.
.EL-
Ends a list of items.
.LI item-
Adds
item
to a list of items.
For HTML documents, one list item appears per line of output.
For non-HTML documents, list items are separated by tabs, and will
fill the row according to the current tab stops.
.DL + or .DL --
For HTML output, indicates the start or end of a definition block.
.DD text-
For HTML output, indicates the start of a definition.
For the other formats, the optional argument is simply copied verbatim.
.HR text [ C [ URL ]])-
For HTML output, creates a hypertext link.
If one or two arguments are present, names the link
.co text .html
.
If the second argument is
C, outputs
text
in Courier font.
If the third argument is present, uses that as the URL link.
For non-HTML formats, the text is copied verbatim in the indicated font.
The help files use the following fonts for the purposes indicated.
In the printed documentation, the New Century
Schoolbook typeface is used for the Roman, italic and bold fonts.
When used with spec and C-PLOT, the directives to switch to bold,
italic or one of the Courier typefaces result in highlighted text
on a video terminal.
- Roman (R)"
- Used for normal text.
- Italic (I)"
- Used for file and path names,
including system commands, along with
book titles, etc.
- Bold (B)"
- Used for section heads.
Occasionally used for emphasis.
Sometimes used to display
arguments to system commands.
Courier (C)" - Used to represent literal text that might be output by
the computer program
or might be typed by a user at the keyboard.
- Courier Bold (CB)"
- Occasionally used to distinguish text a user types
from text output by the computer.
- Courier Oblique (O)"
- Used to represent variable computer text, such
as the argument to a function.
- "Quoted Text" (Q)"
- Not really a font, but used to place double quotes
around a bit of text.
All the fonts, except Roman, display as highlighted text on the video
terminal.
The formatting commands:
.B .I.O
put their arguments in the associated font.
If there are no arguments to the above commands,
the next line of input is put in that font.
The formatting commands:
.RB .BR .IR .CR .OR .CB
.RI .BI .IB .CI .OC
.RC .IC .CO
.RO
place the first argument in the first font, the second argument in
the second font and append an optional
third argument in the regular text font,
except for
,.rb r
.ri .ci .oc
.rc c .co
.ro
work as above, except a space characters is not appended after the last
argument.
The
symbol is used in the help file sources to represent literal double quote characters,
which
makes it easier to insert literal double quote characters into
formatting command arguments.
To enter a literal
use both a backslash and the troff directive,as in a literal \\@ appears
The following special character sequences are recognized:
\" |
A double quote |
\& |
A zero-width space |
\0 |
A digit-width space |
\| |
A sixth-em space (no space on screen) |
\(** |
An asterisk (*) |
-- |
A long dash (--) |
\(hy |
A hyphen (-) |
\(mu |
The multiplication sign (×) |
\(space) |
An unpaddable space |
\*(CP |
The string C-PLOT |
\*(SP |
The string spec |
\*(UN |
The string UNIX |
\- |
A minus sign (-) |
\*- |
A long dash (--) |
\\" |
An \" sign |
\\ |
A backslash |
\e |
A backslash |
\f1 |
Switch to font R |
\fC |
Switch to font C |
\fP |
Switch to previous font |
\f\*(#B |
Switch to font B |
\f\*(#C |
Switch to font C |
\f\*(#I |
Switch to font I |
\f\*(#O |
Switch to font O |
getenv(string)-
Returns the value of the environment variable represented by
the string
string.
If the environment variable is unset, the null string is returned.
Environment variables are exported to spec by the invoking shell program.
file_info(filename [, cmd ])-
Returns information on the file or device named
filename.
With a single
filename
argument,
file_info() returns
true if the file or device exists.
If the argument
filename
is the string
"?", the possible values for
cmd
are listed.
If
filename
is the string
".", spec uses the information from the last
stat()
system call made using the previous argument for
filename,
avoiding the overhead associated with an additional
system call.
Possible values for
"dev" - The device number on which
filename
resides.
"ino" - The inode number of
filename.
"mode" - A number coding the access modes and file attributes.
"nlink" - The number of hard links for
filename.
"uid" - The user id of the owner.
"gid" - The group id of the owner.
"rdev" - The device ID if
filename
is a block or character device.
"size" - The size in bytes of
filename.
"atime" - The time when
filename's
data was last accessed.
"mtime" - The time when
filenames's
data was last modified.
"ctime" - The time when
filenames's
attributes were last modified.
"isreg" or "-f"-
Returns
true if
filename
is a regular file.
"isdir" or "-d"-
Returns
true if
filename
is a directory.
"ischr" or "-c"-
Returns
true if
filename
is a character device.
"isblk" or "-b"-
Returns
true if
filename
is a block device.
"islnk" or "-h or @-L"-
Returns
true if
filename
is a symbolic link.
"isfifo" or "-p"-
Returns
true if
filename
is a
named pipe
(sometimes called a
fifo).
"issock" or "-S"-
Returns
true if
filename
is a socket.
"-e" - Returns
true if
filename
exists.
"-s" - Returns
true if the size of
filename
is greater than zero.
"-r" - Returns
true if
filename
is readable.
"-w" - Returns
true if
filename
is writable.
"-x" - Returns
true if
filename
is executable.
"-o" - Returns
true if
filename
is owned by you.
"-G" - Returns
true if
filename
is owned by your group.
"-u" - Returns
true if
filename
is setuid mode.
"-g" - Returns
true if
filename
is setguid mode.
"-k" - Returns
true if
filename
has its sticky bit set.
Finally, the usage
file_info(pid, "alive")
will return
true if the process associated with the process ID
pid
exists.
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 name (length is in bytes). |
| 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. |
| 0x0001 |
4 |
A data array or data array element. |
Most type-4 symbols have more than one of
the high-word bits set.
The following code
uses the
whatis() function
to determine whether or not a value has been
assigned to the
PRINTER variable:
1.FOURC> if ((whatis("PRINTER")>>16)&0x0800) {
2.more> printf("Warning: No open printer.\n")
3.more> open(PRINTER = "/dev/null")
4.more> }
5.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.
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.
Fractional-second sleeps are available on
all currently supported systems, although on
on the System V/386 UNIX
systems, such sleeps are available
only if the special
nap
driver has been installed.
spec_par(par [, value ])-
Sets internal parameters.
Typing
spec_par("?")
lists the available parameters.
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,
spec will automatically poll busy motor controllers, timers and
acquisition devices to determine when they are finished.
For interrupt-driven devices (certain motor controllers and timers),
this mode is irrelevant.
For some polled 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.
The default is for this mode to be on.
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 reset to command level.
By default, this mode is on.
"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.
"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.
As of release 4.03.01, the rounding is now turned 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.
"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.
"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.
"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 (as of release 4.03.07)
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.
"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.
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.6
in the
Administrator's Guide
for information on how to include other user-added functions
in the program.
history-
This command lists the 1000 most recent commands typed at the keyboard.
See the description of the command-recall (history)
feature
2.3.8
.
history N-
As above, but only prints the
N
most recent commands.
If
N
is negative, the commands are printed in reverse order.
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.
savstate-
Writes the current state to the state file.
The
state
file
contains the variables, macro-file bitmap,
output file names and command history
unique to each user, terminal and
diffractometer.
The state file
preserves 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.
Note, as of release 4.05.01, a new
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.
sock_io(host:port, cmd [, arg ])-
Connects and communicates with sockets created by other processes
on the local or a remote host.
The
host
can be specified by a symbolic name or by an IP address.
The string
cmd
is one of the following:
"?" - Lists the command options available.
"show" - Lists the current open sockets and their status.
"connect" - Opens the socket to the specified host and port.
Returns
true for success
and
false for failure.
"listen" - Sets up a socket for listening, allowing another instance of spec or
some other program to make a connection.
"close" - Closes the socket associated with the specified host and port.
"send" - Sends the string
arg
to the specified socket, opening it if not already connected.
"read" - Reads from the specified socket,
opening it if not already connected.
Currently, the message to be read can be no longer than 1,024 bytes.
With no argument, reads until a newline or until the timeout expires.
An optional string argument can specify an end-of-string (EOS) delimiter, in
which case the socket will be read until characters matching the EOS
sequence are read or until the timeout expires.
Trailing newlines and carriage returns will be removed from the returned
string.
Also, if the optional argument is a number, it specifies
the number of bytes to be read.
That number of bytes
(or less, if the timeout expires)
will be read and returned.
"timeout" - With no argument, returns the current read-timeout value in seconds.
Otherwise, sets the read timeout to
arg.
A negative timeout value causes the socket read to block until
it is satisfied.
The default timeout value is five seconds.
Note, the
"connect" command
doesn't generally need to be used,
as the connection will be made if needed with the
other commands.
However, the return value from the
"connect" command may be used to test if a socket can be created.
A connection remains open until the
"close" argument is used.
Simultaneous connections to multiple ports are allowed.
The following example connects to the
echo
service on port 7 of the local host.
1.FOURC> sock_io("localhost:7", "send", "This is a test.\n")
2.FOURC> print sock_io("localhost:7", "read")
This is a test.
3.FOURC>
|
Prev | Next 