SYNOPSIS

fourc [ -fhsvyFL ] [ -d debug ] [ -g geometry ] [ -l outputfile [...]] [ -o option=value [...]] [ -p fd pid ] [ -t tty ] [ -u user ] [ -A allowed_host [...]] [ -C file [...]] [ -D directory ] [ -N my_name ] [ -S[*#*] | -S[*#*] p1 | -S[*#*] p1-p2 ] [ -T fake_tty ] [ -U fake_user ]

DESCRIPTION

spec provides a software environment for the operation of an X-ray diffractometer and other data-acquisition instruments. spec contains a sophisticated command interpreter that uses a C-like grammar and powerful macro language. spec supports a variety of X-ray diffractometer configurations. The diffractometer geometry is chosen by the program name. Some of the more popular geometries currently supported include:

spec

General instrument control and data acquisition

fourc

Standard four-circle diffractometer

twoc

Standard two-circle diffractometer

sixc

Six-circle diffractometer (delta, theta, chi, phi, mu, gamma)

kappa

kappa diffractometer

psic

Psi-circle, including kappa type

surf

Various liquid surface diffractometer configurations

The following options are recognized:

-A allowed_host

If present, only hosts that match the specified IP addresses will be allowed to connect as clients to a spec server or via socket ports opened with sock_par("listen"). Multiple -A options are allowed. The allowed_host argument recognizes standard CIDR (Classless Inter-Domain Routing) notation. The options -A 127.0.0.1 -A 192.168.1.0/24 would allow the localhost (127.0.0.1) and hosts in the 192.168.1.0 through 192.168.1.255 subnetwork. (This flag added in spec release 6.07.01.)

-C file

Open the command file file as a start-up command file to be read after the standard start-up command files, but before the optional file spec.mac in the current directory, which will always be read last. If there is an error in reading or executing the commands in these files, spec will jump to the main prompt and not read any remaining queued command files. Up to 32 files may be specified with multiple -C options. (This flag added in spec release 5.07.01-1.)

-d debug

Set the initial value of the debugging variable DEBUG to debug. See the debug help file for a list of the debugging categories. A value of 192 is useful for debugging hardware problems.

-D directory

Use directory instead of the compiled-in name (usually /usr/local/lib/spec.d) or the value of the SPECD environmental variable (if set) as the auxiliary file directory.

-f

Fresh start. All symbols are set to their default values and the standard macros are read to establish the default state.

-F

Clean and fresh start. All symbols are set to their default values but no command files are read and no macros are defined. Only the built-in commands are available.

-g geometry

Load macro files and activate geometry calculations for the specified geometry, while using the configuration files taken from the name by which spec is invoked.

-h

Retain history. When starting fresh, reset symbols and macros but keep command-line history. (Added in spec release 6.05.01.)

-l logfile

Specifies an output file. Output to the file will begin immediately, so will include the initial hardware configuration messages. Files will be opened even when starting fresh. (Added in spec release 5.09.02-2.) Files opened this way will not be saved as output files in the state file, so will not be automatically reopened the next time spec starts. (As of spec release 6.04.05.)

-L

Do not check or create the state-file lock. Normally, spec prevents more than one instance of itself from running with the same state file (derived from the user-name plus terminal-name). In some situations, particularly if a site configures the state files to reside on an NFS-mounted disk, the lock test that spec uses always indicates another instance of spec is running, making it impossible to start. This flag overrides that test. Normally, this flag will not be used.

-N my_name

Use my_name for setting the spec prompt and the name of the configuration file directory. Also sets the geometry as if -g was given as an argument. To select a geometry not corresponding to my_name, use the -g flag after the -N flag.

-o option=value

Initializes the spec_par() option to value. See the spec_par help file for a list of the available options. Multiple -o options may be given.

-p fd pid

Indicates that spec input is coming from a pipe from another program. The argument fd is the file descriptor that spec should use for standard input. The argument pid is the process ID of the spawning process. If fd is zero, spec will not re-echo input from the file descriptor to spec's standard output. (This feature is deprecated and may be removed in a future release.)

-s

Simulation mode. No hardware commands are issued. If started in simulation mode, simulation mode cannot be turned off without restarting the program.

-S

Starts spec in server mode (mode 1) listening at the first available port in the default range of 6510 to 6530.

-S1

Same as -S, starts a mode 1 server. With a mode 1 server, hitting a motor limit does not cause spec to abort other moving motors or reset to command level.

-S2

Starts a mode 2 server. With a mode 2 server, hitting a motor limit causes spec to abort other motors and reset to command level, just as with non server-mode spec.

-S3

Starts a mode 1 server in daemonized mode. In daemonized mode, spec runs in the background with no connection to a terminal.

-S4

Starts a mode 2 server in daemonized mode.

-S[*#*] p1

Starts spec in server mode listening at the specified port number p1. An optional # can be 1, 2, 3 or 4, as above.

-S[*#*] p1-p2

Starts spec in server mode listening on the first available port in the given range. An optional # can be 1, 2, 3 or 4, as above.

-t tty

Use the current user (or user's) last saved state from the terminal specified by tty. The terminal can be specified as -t /dev/tty01 or -t tty01. Note, spec uses the string ttyp# to refer to a pseudoterminals on Linux and ttys00 on macOS.

-T fake_tty

This option creates a user state associated with fake_tty, which may be any name (although only the first six characters are used). This option allows you to bypass the locking feature that prevents multiple instances of spec to be started by the same user from the same terminal.

-u user

Use user's last saved state as the current user's initial state.

-U fake_user

Create a user state file associated with fake_user instead of the real user name. (Added in spec release 6.10.04.)

-v

Show version. Print version information and exit.

-y

"Yes", change motor controller registers initially if they disagree with the settings file. Normally, spec requires you to confirm such a change. This flag would be useful if you know controller power had been turned off.

ENVIRONMENT

spec uses the following environment variables:

SPECD

An auxiliary file directory to use instead of the compiled in name.

TERM or term

The text terminal type.

GTERM

The graphics terminal type for high-resolution graphics

HOME

The user's home directory.

SHELL or shell

The shell program to be used for interactive subshells.

DISPLAY

The display name and screen number on which to display the X-window plots.

FILES

spec.d is the auxiliary file directory, often /usr/local/lib/spec.d. gconf is the name by which spec was invoked, as in fourc, twoc, etc. Some significant spec files include the following:

./spec.mac

Optional private command file always read at startup.

spec.d/site.mac

Optional site command file always read at startup.

spec.d/site_f.mac

Optional site command file read on fresh start.

spec.d/standard.mac

Standard macro definitions read on fresh start.

spec.d/gconf.mac

Standard geometry macro definitions read on fresh start. Uses only first 4 letters of gconf.

spec.d/gconf/config

Hardware configuration file.

spec.d/gconf/settings

Motor settings file.

spec.d/gconf/conf.mac

Optional configuration command file always read at startup.

spec.d/gconf/userfiles/hdw_lock

Hardware lock file.

spec.d/gconf/userfiles/user_ttyH

User's history file. Uses only first 6 letters of tty.

spec.d/gconf/userfiles/user_ttyH.old

Previous version of the history file. Used for recovery if the primary version is corrupted.

spec.d/gconf/userfiles/user_ttyL

User's lock file. Uses only first 6 letters of tty.

spec.d/gconf/userfiles/user_ttyS

User's state file. Uses only first 6 letters of tty.

spec.d/gconf/userfiles/user_ttyS.old

Previous version of the state file. Used for recovery if the primary version is corrupted.

spec.d/gconf/userfiles/user_ttyP

User's data points file. Only first 6 letters of tty.

spec.d/spec.conf*

Sets utilities and parameters used for help file formatting and display.

spec.d/servers/*

Servers for the "server hardware" feature. See the server_hdw help file.

spec.d/spec_help/*

Help files.

spec.d/splot/*

Files associated with Python splot utility.

spec.d/pyspec/*

Files associated with Python utilities such as splot and Python-based hardware servers, such as eigerserver.

NOTES

The spec state file retains open output file names, command line history (now in a separate history file), symbol values, macro definitions and miscellaneous session parameters across spec invocations. Ideally, each user will have their own state file associated with a particular instrument.

In the beginning, spec ran on a multi-user UNIX system where separate terminals were connected by serial lines to a minicomputer. Each terminal had a unique node in /dev/. Likewise, each user had a login name. Normally, a particular terminal was associated with a particular X-ray diffractometer. spec state files were attached to the terminal and the user name.

When X11 Windows came to UNIX systems, the terminal window no longer had a unique name associated with a physical location. Instead the system created pseudo terminal devices for each terminal window using various naming conventions, such as /dev/ttypX, /dev/ptyX, etc., depending on the particular UNIX flavor. spec collapses all such names to /dev/ttyp# with corresponding state files no longer associated with a particular physical terminal.

The -t tty startup option has always allowed one to start a spec session using a state file associated with another terminal. Later, the -T fake_tty option was added so that state files could be tied to particular instruments. Sites that use the feature can invoke spec through a shell script and assign the arguments based on existing login environment parameters.

The -u user startup option has always allowed a user to initialize their spec state using another user's existing state. The more recent -U fake_user option allows sites that cannot create login names for visiting users to associate a spec state with a vistor by labeling the state with the fake_user name.

When the -T or -U options are used to specify a non-default state file name for saving the state, that state file name will be used to initialize the session, if the files exist. That is, it is not necessary to also specify -t or -u with the same arguments.