DESCRIPTION

The spec_par() function allows access to certain internal parameters of spec as described below. Most parameters can be set using the -o start-up option (see the spec help file). Some parameters can only be set using the start-up option. As of spec release 5.03.01, some hardware-related parameters can also be set in the config file, using the following syntax:

SPEC_PAR: epics_timeout = 2

The declarations have to be entered manually, but will be maintained by the edconf configuration editor. The declaration can be located anywhere in the file.

spec_par("?")

Displays all the parameters and their values. If the current value differs from the default value, the default value is displayed in parenthesis (as of release 5.08.02-8).

spec_par("set_defaults")

Sets all parameters to their default values.

spec_par(par)

Returns the current value of the parameter par.

spec_par(par, value)

Sets the internal parameter par to value.

The spec_par() parameters are:

"anka_remote_host", "anka_remote_node", "anka_local_node"

These parameters are only visible when the ANKA RST Gamma hardware is configured. See the anka help file for an explanation of what they mean. These parameters can be set in the config file.

"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 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. Early versions of spec made more frequent use of interrupt-driven devices (certain motor controllers and timers), for which this mode is irrelevant.

"auto_savstate"

When automatic save-state mode is enabled, the user's state file and history are written out before the main spec prompt, but no more frequently than the number of seconds set by this parameter. A value of zero disables the auto save. Normally, the state information is written when spec exits and with the savstate command. Enabling auto save can be useful in an environment where the computer running spec is prone to crashing. The state files are what allows the resumption of a spec session, retaining output file names, parameter values, macro definitions, command line history and assorted hardware parameters from the previous session.

"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 a error messages and reset to command level. By default, this mode is on.

"confirm_quit"

If set, spec prompts with a "Really quit?" message when the 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.

"date_format"

Specifies the format of the date/time string displayed with the date() function. The default format is "%a %b %d %T %Y" which produces a string of the sort "Tue Aug 15 13:16:32 2023". Many conversion options are available, as documented on the system strftime() man page (type man strftime from the shell). Summaries are also available on the internet, such as at strftime.org. One should make sure that any changes to the format will work with any utilities one uses to parse date strings in spec data files. Available as of spec release 6.12.01. Note, any format provided as an optional argument in a call of the date() function will override the value set with spec_par().

"elog_level"

The level at which commands are saved to the elog error files is set using this option. At level 1, the default, only commands typed at the keyboard are logged. At level 2, the commands read from command files are also logged.

"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 5 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. However, for time-stamp intervals less than 1 second (or 0.01666 min), every command and error message will be preceded by a time stamp, and the time stamp will include fractional seconds in the epoch value.

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

"fast_hdw_checks"

Obsolete in spec release 6.06.01.

"flush_interval"

The flush-interval parameter controls how often spec flushes output to the hard disk or other output devices. 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.

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

"legacy_quit"

Prior to spec release 6.09.04, the quit command to exit spec (same as ^D typed at the main prompt) was only allowed at the beginning of a line either typed on the keyboard or read from a command file. The command could not be included in a macro. As of spec release 6.09.04, quit became an ordinary command that could be included in macros, flow control statement, etc. If set, this parameter restores the legacy behavior.

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

"move_timeout"

When set, establishes the default move timeout for all motors. If a move timeout exists for a motor and a motor fails to complete a move or homing operation in the time set by the timeout, spec aborts the move and resets. Move timeouts can also be set in the config file as a nonstandard optional controller parameter that will apply to all motors associated with the controller, or as nonstandard optional motor parameter to apply to an individual motor. The motor parameter takes precedence over the controller parameter, which takes precedent over the sepc_par() parameter. Units are seconds with fractional values allowed. A value of zero disables the move timeout feature. The default value is zero. This parameter can be set in the config file. Available as of spec release 6.09.08.

"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. Unit parsing dates from very early versions of spec, still exists for backward compatibility, but use is not recommended. This mode is off by default.

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

Note, the standard macros onwiz and offwiz are convenient wrappers for the spec_wiz feature.

"undef_threshold"

The undef command to undefine macros accepts wildcard characters in its arguments. To avoid accidentally deleting all macros (with an inadvertent undef * for example), if the number of macros that match the arguments is greater than the value of "undef_threshold", spec will ask for confirmation. The default value for this parameter is 10. Available as of spec release 6.11.02.

"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). Note, if the final position is within the motor's "slop" parameter, no message is printed. The "slop" parameter is in units of steps, is a standard optional motor parameter in the config file and can also be set with motor_par().