Software for Diffraction


Highlights for spec release 6.06

December 13, 2017 - RELEASE 6.06.11


New Variable Argument Feature For Macro Functions

New local variables now exist within macro functions. The variables are named argc and possibly arg1, arg2, etc. The value of the variable argc is the number of arguments used to invoke the macro function. The additional variables arg1, arg2, etc., contain the values of arguments not included in the macro definition, but used in the macro invocation. The argument number corresponds to the position of the argument. If the macro definition defines an argument, there will be no new argument variable created for that position. For example, consider this macro function:

def test(par1, par2) '{ ... }

When called as:

test(1, 2, 3, 4)

the value of argc will be 4, arg3 will be 3 and arg4 will be 4. There will be no arg1 or arg2, since the macro has named parameters in those positions.

With respect to backward compatibility with existing macros that may use these names, a macro argument or local variable named argc will take precedence. However, a global variable named argc will not be visible in macro functions. Also, in the unlikely scenario there are explicitly declared variables named arg1, arg2, etc., and the macro function creates variables for missing arguments, the created variables will mask the existence of the declared variables. For example:

1.SPEC> def test(arg3) '{ print argc, arg3 }'

2.SPEC> test(PI)
1 3.14159

3.SPEC> test(PI, 2, 3)
3  3

In the first instance, no arg3 was created, since the macro was called with only one argument. In the second instance, a new arg3 local variable is created that takes precedence over the declared variable.

Just as with declared macro function arguments, the type of the created variable will be the same type as the variable used in the macro call, whether number, string, associative array or data array.

Server Mode Events Now Sent For "status" Property Registrations

When a client registers for events for a property on a spec server, spec sends an initial event with the current value of the property. However, prior spec releases did not send initial connection events for the status/shell, status/quit, status/simulate, status/ready, and error properties. This spec release remedies that. The value sent for the connection event for the error property is the message "No error". See the server help file for details on server properties.

splot Updates

This spec release includes splot version 3.1.01, which contains various fixes and stability improvements, particularly with respect to making initial connections to spec and for displaying 2D mesh scans. There is also a new feature that allows having the spec command line embedded as a panel in the splot window. The splot update notes are available in the splot/docs directory of the splot distribution.


Fix For ^C During getval() and getsval()

The update in spec release 6.06.04 that enabled command-line editing with the getval() and getsval() data entry functions broke the expected ^C (interrupt signal) and ^\ (quit signal) response on Linux (but not macOS) platforms. That issue is fixed in this release.

Fix For Possible Crash With getval(), getsval() and input()

The update in spec release 6.06.04 that enabled command-line editing with the user input functions included bugs which could sometimes lead to a crash if getval() or getsval() were called with just one argument or if input() was called with no arguments.

Legacy Behavior Restored For Reading mca_par() and image_par() "disable" Status

In adding the support for the mca_spar() and image_par() "unusable" argument in spec release 6.06.01 (which returns zero/nonzero to indicate if the specific device is available), the behavior for the "disable" argument was changed slightly, in that spec would print out an error message if used with an unconfigured device. In consideration of legacy macros at some locations, the previous behavior, where checking the "disable" status of an unconfigured device would silently return zero, has been restored. CSS recommends that new macros that use mca_spar() or image_par() check the "unusable" status for a particular device before issuing additional commands.

Stability Fixes

This spec release fixes an issue with macro functions where the last executed statement in the function assigns a value to a local variable.

Fix For Crash While Waiting For Child Process

A possible segmentation fault when spec looks at child processes that have exited has been fixed. The bug is very old, and the only known manifestation has been when the process created by the EPICS libraries exited after not locating a caRepeater executable file.


New Settle Time Option for Each Row of Mesh Scans

A new _mesh_sleep global variable can be set to the number of seconds to sleep (as a settling time before counting) after moving the motor associated with the outer loop of a mesh scan. The sleep is contained in the standard _loop macro (as is the existing optional per-point sleep, set with the _sleep global variable) for mesh and dmesh scans and for fscan scans when there is #L loop directive in the scan source file. The sleep is implemented directly in the cmesh and cdmesh scans. The standard macros mstartup and setscans (called by startup) now prompt for a value for the new variable. Of course, the variable can also be assigned to directly.

X11 Plot Tweaked

The macros that display the x11filt plots have been tweaked to display the analysis values (PEAK, FWHM, COM) in a more consistent and readable style.


Support For Tsuji Model UPM4C-01 Motor Controller

spec now supports the Tsuji Model UPM4C-01 motor controller. This model is very similar to the UPM2C-01, but has four axes rather than two.

October 30, 2017 - RELEASE 6.06.10


Fix For ^C During input(n) and With Remote Commands

spec release 6.06.01 broke handling of the interrupt (^C) and quit (^\) keyboard signals during the calls of input(n), where n is 0 or less. Also, keyboard signals were blocked on a spec server while executing commands from a remote client. Those issues are resolved in this spec release.

October 23, 2017 - RELEASE 6.06.09


Fix For Excessive CPU Usage With Software Timer

A bug introduced in spec release 6.06.03 that could result in excessive CPU usage during non-updated counting when using the software timer in interrupt (as opposed to polled) mode has been fixed.

Fix For Memory Corruption In Server Hardware Code

A bug introduced in the server hardware facility overhead module, server.c, in spec release 6.06.01 that could cause unexpected program issues has been fixed. The server hardware facility was introduced in spec release 6.04.01. See the server_hdw help file for more information.


Fix For dscan_cleanup

The updated dscan_cleanup macro, introduced with the new array-based scan engine in spec release 6.03.04, had issues parsing arguments when the macro was used with legacy local macros that invoked dscan_cleanup using variables as arguments. That issue is resolved in this spec release.

October 1, 2017 - RELEASE 6.06.08


Updates For SmarAct Motor Controllers

The SmarAct MCS and SCU motor controllers limit the number of steps that can be sent with the open-loop move commands (MST on the MCS and U/D on the SCU). This spec release will automatically split commanded moves that exceed the limit into as many smaller moves as necessary. Also, the hardware configuration now includes options for both serial and socket interfaces. See the smaract help file for details.

September 24, 2017 - RELEASE 6.06.07


HDF5 Support Updated To Current HDF5 Release

The built-in HDF5 support in spec is now using HDF5 stable release 1.10.1. Previously, spec was built against HDF5 release 1.8.14. See the hdf5 help file for details on spec's HDF5 support.


Fix For Using spec Server Counters From Remote Client

spec release 6.06.01 included improved hardware polling, but introduced a bug that prevented clients from receiving an event that indicated the end of counting when using counters on a spec server. This spec release fixes that bug.

Fix For Passing Macro Function Arguments to eval()/eval2()

spec release 6.04.05 added a new capability that allowed the eval() and eval2() functions to accept and return the value of an input string containing a single number, literal string or a variable. Previously, such input would generate a "Not a command or macro" error, just as at the main spec prompt. spec release 6.05.01 removed the "+0" from the eval2(arg "+0") usage in the standard macros which had been there to force evaluation of an expression when arg was a single number, literal string or variable. This spec releases fixes a bug where the code didn't consider the case where the eval()/eval2() argument was itself a macro function argument, which internally is a different kind of object. With that bug and the updates to the standard macros, usage such as def mymove(pos) '{ mv m1 pos }' stopped working, as the standard mv macro expands to something that uses pos as the argument to an eval2() function.

September 13, 2017 - RELEASE 6.06.06


Continuous Scan Timer Preset Now Configurable

The continuous scan macros (cscan, c2scan, cdscan, etc.) program the timer for long count time. Previously, that value was explicitly set to 999 seconds. Some users want to do continuous scans that last longer than that. The scans now use the value of the new global variable CSCAN_TIMER_PRESET to set the timer. The default is still 999 seconds, but users can assign a different value. See the cscan help file for details.

The eval2() Calls Of Macro Arguments Now Protect Double Quotes

spec release 6.05.01 put eval2() calls and double quotes around the value arguments for the standard set, set_dial, set_lm and home macros so that the arguments could be expressions or symbols. In order to allow the arguments themselves to include double quotes, the macros now use escaped single quotes around the arguments. That is, code such as eval2("$1") has been replaced with eval2(\'$1\'). In addition, arguments to aziscan, abscan, abmesh, r2scan, alphascan and betascan, which are associated with particular diffractometer geometries, have had the same update.


Fix For Anorad Presence Test

The code for the presence test for the RS-232C Anorad motor controller used a short 0.5 second timeout while waiting for the reply to the first command. It appears this timeout was too short for some system configurations. The presence test now uses the same two second timeout used by the rest of the Anorad support.

August 31, 2017 - RELEASE 6.06.05


Fix For edconf Crash With 24-Line Window

A crash introduced with the edconf updates for bigger windows in spec release 6.06.03 that occurred when using a 24-line terminal window has been fixed.


New Configurable VME Address Modifier For OMS MAXv

spec now allows the VME address modifier to be configured for the Oregon Micro Systems MAXv motor controller. Previously, the default A16 addressing mode was built into the code. The edconf configuration editor now uses the MODE column to allow choices of A16, A24 or A32 as addressing mode.

August 6, 2017 - RELEASE 6.06.04


Line Editing For input(), yesno(), getval() and getsval()

The spec built-in functions input(), yesno(), getval() and getsval() will now use the command-line editing library to collect user input from the keyboard. All the special key sequences for editing text are available, along with filename completion. The forward and reverse search keys (^S and ^R) can be used to recall command history entered at the main spec prompt, but text entered with these functions is not saved in the history stack. Of course, spec needs to be linked with one of the optional command-line editing libraries (libedit or readline) for the feature to be available. A small change from prior behavior is that with the command-line editing, ^D only terminates entry when it is typed as the first character of an empty line. Otherwise, ^D is interpreted as forward delete. As with the previous implementation, initial white space is removed from the returned value. The new implementation also removes trailing white space.


Fix For Broken vscan Macros

An incomplete edit in the previous release of the vscan macro source file made the variable-spaced scan macros unusable. That issue is fixed. See the vscan help file for a description of the macros.


Support for EPICS release 3.16

This spec release can be linked with EPICS release 3.16 channel access libraries.


Fix For Potential array_op() Crash

A bug that could result in a spec crash when the array_op() commands "fwhm", "cfwhm", "lhmx", "uhmx", "com", "x_at_min" or "y_at_min" were used with an invalid subarray as second argument has been fixed.

^Q/^S Now Available With libedit

The control characters traditionally associated with flow control on old TTY terminals are now enabled for command-line editing when spec is linked with libedit. The default bindings assign ^Q to "ed-quoted_insert" and ^S to "em-inc-search-next". That is, ^Q can be used to insert a literal control character, while ^S searches history in the opposite direction to ^R. As before, alternative key bindings can be assigned in a .spec_keys file in a user's home directory. See the libedit help file for details.

July 17, 2017 - RELEASE 6.06.03


New edconf Features

The edconf hardware configuration editor, usually invoked via the config macro, has several updates.

  • It is now possible to edit existing entries. Use the left- and right-arrow keys to change text insertion position, ^A to move to the beginning of the entry, ^E to move to the end, ^U to delete to the beginning, ^K to delete to the end and ^D (or the forward-delete key) to delete one character forward.
  • When using ' or " to initiate editing of an entry, if the next character typed is one of the above editing characters, the existing value will not be erased.
  • The ^A and ^E commands can be used to initiate editing of existing values starting from the beginning or end of the string, respectively.
  • When multiple motor controllers or counter/timers of the same type are configured, the unit numbers associated with the controllers are now displayed on the far right. Typing the unit number of another controller of the same type in the unit field will swap entries.
  • The motor and counter/timer screen now displays the row number in the first column, which can be used to swap entries by entering a new row number.
  • For lists that page with ^F and ^B commands, a new ^G command will position the cursor on the first item of the list.
  • The editor will now display as many motor columns as fit on the screen (up to ten) rather than the four that can fit in 80 columns.
  • A new startup option -c cols is available, where cols is a number greater than or equal to 80 and less than or equal to the number of columns on the screen. Only as many motor columns as fit in cols will be displayed. (Each additional motor column uses 13 spaces.)
  • The editor will now display as many rows on the Interfaces, Devices, MCA/Image Devices and Scaler screens as will fit.
  • A new startup option -l lines is available, where lines is a number greater than or equal to 24 and less than or equal to the number of lines on the screen. A value less than the maximum will limit the amount of information displayed.
  • A new -O option (for "old" mode) sets columns and lines to 80 and 25, respectively.
  • After changing the window size, the refresh command, ^L, will adjust the display to the new columns and lines values, unless the values were fixed with the -c and/or -l options.
  • The q command can be used as an alternative to ^C to quit the program.
  • The secondary Scaler screen for miscellaneous parameters, accessed with the s command, has been eliminated. Instead, the parameters misc_par_1, misc_par_2, etc., can be configured on the custom optional parameter screen, accessed with the p command.

New Polled-For-Reading Macro Hardware Counter Type

A new MAC_CNTR macro-hardware counter type is available to accommodate implementations of averaging devices, such as an instrument that takes instantaneous readings from a PIN photodiode with multiple readings averaged to create a counter value. The macro-hardware *_cmd() function is called with the "get_status" key while counting is active, but there is no busy status associated with MAC_CNTR counters. In addition, a new optional counter parameter, "min_read_time" can be used to set the minimum read interval in order to limit how many readings are used in the average. See the mac_hdw help file for details.


Support For OMS PCI MAXk Controller

spec now recognizes and supports the Oregon Micro Systems MAXk family of PCI-bus motor controllers. Each board can support up to ten motors.


Fix For History Display With show_state

A bug introduced in spec release 6.06.01, where the show_state utility didn't display command history, has been fixed.

Consistency For Bit-Shift Operators For Arrays

To be consistent with the implementation of 64-bit integer operations for scaler values introduced in spec release 6.05.03, when bit-shift operators are applied to arrays, each array element is now masked to 52-bits before carrying out the shift operation. (spec stores numbers as double-precision floating-point values, which have a 52-bit significand.) Previously, the bit-shift operators didn't mask the operand, which allowed the highest order bits to be used, but if those high-order bits were set, the values of the low-order bits would be lost. (When an operator is applied to an array or subarray, the operation is carried out on each element of the array. See the arrays help file for more information.)

Obsolete PAGER Built-In Global Variable Removed

The PAGER built-in global variable has not been used since the revised help-file utility was introduced with spec release 6 and is no longer created as a built-in symbol with a value fetched from the environment. The help utility reads a file /usr/local/lib/spec.d/spec.conf that assigns values for shell commands and arguments used for help file formatting and display, and a PAGER variable is assigned there.

Fix For taco_io() Possible Fault

A old bug in the implementation of taco_io() which was activated by internal updates in spec release 6.06.01 and that could result in a program crash has been fixed.

June 9, 2017 - RELEASE 6.06.02


Updated tidy_spec Utility

The tidy_spec utility, which reports on user state file usage and optionally removes user state files, has been tidied up. The utility will now include the separate history file in its report. History files can be removed with the new -h option. In addition, the more conventional -g flag can be used to specify which geometries to clean. The prior flag, -s, is still recognized.


Fix For Time Scan Macros

Some of the "unnecessary" code removed in the time scan macros updates in spec release 6.04.05 broke the time scan plotting when x-axis auto-scaling was disabled. The plotting now works properly for timescan and loopscan, even when x-axis auto-scaling is disabled.


Fix For Crash In getline()

A bug introduced in spec release 6.05.04 where the getline() function could crash has been fixed. The crash occurred if getline() was called to read a line from a file, then called with the "close" argument, then called again to read a line from the same file.

Fix For Crash With Empty Command Files

A bug introduced in release 6.06.01, where spec could crash when reading an empty command file using dofile() or qdofile(), has been fixed.

May 8, 2017 - RELEASE 6.06.01


Better Hardware Polling While Waiting For Keyboard Input

While waiting for keyboard input, spec checks the busy status of active motors, timers, etc. spec also checks for events from a spec server (if using), messages from clients if running as a spec server and EPICS event callbacks (if using EPICS), Previously, spec used a select() system call with a short polling time that only responded to keyboard activity. spec now uses the select() call to also monitor server/client related and EPICS activity. If no other I/O, such as with PC board controllers, serial devices, etc., is active, spec is idle, waiting in the select() call. If there is other I/O, spec polls the devices no faster than ten times per second. The new code should provide faster response times to server/client and EPICS events.

The new code also includes a fix for an issue related to pasting text at the prompt. Previously, there was a noticeable delay between display of each character of the pasted text. That delay is gone.

Finally, the spec_par() "fast_hdw_checks" option is no longer relevant. For backward compatibility, it can still be set, but its value is ignored.

Hardware Polling While Running unix() Commands

spec will now use the keyboard-input hardware polling loop while waiting for a child process created with unix() to finish. The same applies to spec's gethelp() function which also creates child processes to format and display help files. This change means that when in server mode, the spec server will now respond to clients even when, for example, the server itself is being used to display a help file.

spec will give the child process up to one second to complete before starting the hardware polling. That avoids any delays when running quick unix() commands.

A known issue occurs if a client sends a command to a spec server to create an interactive subshell while the server itself is in a subshell. The work around is not to do that. If the situation occurs, upon exiting the subshell on the server, one may need to type ^Z to suspend spec, then fg to bring spec to the foreground.

Parser Now Reentrant

The byacc utility is used to compile the spec parser. CSS has modified the version it uses so that the parser is reentrant. That means that as of this spec release, multi-line commands being typed at a spec server will not be corrupted by the arrival of commands from a client, as was previously the case. In addition, nested eval() calls should now work flawlessly.

Initialization Implemented For 2D Associative Arrays

Two dimensional associative array initialization is now available. Each element is initialized with three colon-separated items. The first two items are the array indices and the third is the element value. Syntax is as follows:

testarray = [ 1:2:"item", 2:3:"item2" ]

which results in:

testarray["1"]["2"] = "item"
testarray["2"]["3"] = "item2"

Initialization lists can include a mix of 2D, 1D or index-implicit 1D sequences.

Multi-Line Commands Now Saved As One Entry In History List

Commands or statement blocks entered at the main prompt that extend over multiple lines are now saved as just one item in the command line history. This history mode, which is enabled by default, can be disabled by setting the new spec_par() "history_join" option to zero.

Escaped History Character Now Kept In History Item

In order to use the negation operator ! in an expression entered at the keyboard, the character needs to be preceded by backslash, as in \!, as a bare exclamation mark is interpreted as the history recall character by the command line editing library. Previously, when the line containing \! was saved as a history item, the backslash was removed, meaning if the line was recalled, the line would have to be edited to add back in the backslash. This spec release ensures the backslash remains in the history item. However, it is now not allowed to combine \! and exclamation-mark recalled history items on the same line.

History Restored Even If State File Is Unusable

When not starting fresh, but with a state file that is missing, corrupted or otherwise unusable, spec will still try to restore command-line history, which is stored in a separate file since spec release 6.05.01.

Input Line Length Now Unlimited

The length of an input line is now unlimited. Previously, the maximum number of characters was 4,096. This change is important to accommodate the new "history_join" feature which, for example, will save a statement making a macro definition that includes a long string as a single history item.

New "unusable" Argument for mca_spar() and image_par()

A new "unusable" option for mca_spar() and image_par() will return a nonzero value if the associated device is unusable, either because it didn't pass the presence test, because it was marked "OFF" in the config file or because there is no configured device at the given unit number. No error messages will appear if the arguments refer to unconfigured devices.

New Options and Fixes To strdef()

The strdef() functions returns the macro definition of its argument as a string. A problem where escaped string delimiters were not properly coded in the return strings has been fixed. In addition, strdef() now takes an optional associative array argument. If the macro is a macro function, the associative array elements will be assigned the string names of the arguments in order starting at zero. Also, an element of the array indexed by the string "file" will contain the pathname of the file where the macro definition came from or the string "tty" if the macro was defined at the keyboard.

"Server Hardware" Functionality Improved

The new "server hardware" feature introduced in spec release 6.04.01 now supports MCA-type (1D) and image-type (2D) devices. In addition, spec now supports automatic start up of the server process, whether on a local or remote host. spec will also attempt to restart a server that stops responding. The servers can now be daemonized to run in the background unassociated with a terminal. The servers also use lock files to prevent more than one instance from running. See the server_hdw help file for details.

Image Functions Now Set HDW_ERR

The image_get(), image_put() and image_par() functions now set the built-in HDW_ERR global variable with appropriate values on failed calls. See the HDW_ERR help file for details.

splot Updates

The Python splot utility has improvements in functionality, performance and stability. One notable new capability is 2D contour-plotting for mesh scans. Also, print dialogs and functionality are improved.


New Reciprocal Space and Delta vscan Macros

The vscan family of macros do variable step size scans. The scan arguments include a start, focus and end position for each scanned variable, with point spacing being closest together at the specified focus, which can be anywhere within the scan range, including the end points. New vhscan, vkscan, vlscan and vhklscan macros provide for scanning in reciprocal space. Additional v3scan and v4scan macros have been added to support additional motors. Delta versions dvscan through dv4scan are also now included. See the vscan help file for details.

New disable and enable Macros For Setting Hardware

The standard spec macros now include macros to easily disable or enable hardware devices. The macros are based on similar macros from the ESRF and should be fully compatible with those. See the disable help file for details.

Broken Multiple Motor Continuous Scans Are Fixed

A bug in the internal _cscan_prep macro prevented c2scan through c4scan from working correctly, along with the delta versions. That bug is fixed. See the cscan help file for more information about the scans.


Fix For Restoring History When Starting With -u and -t

An issue with the revamped history facility introduced in spec release 6.05.01, where if spec was invoked with the -u and/or -t flags to start with an initial state file from another user or tty, spec would not also import the associated command history, has been fixed.

Fix For Reading Miscellaneous State File Parameters with -u and -t

An old issue, where the spec_par() options and certain persistent hardware parameters saved in the user state file as "miscellaneous parameters" were not obtained from the alternate initial state file specified with the -u and/or -t command line options, has been fixed.

Fix For Slow Pasting With libreadline

spec now includes a work around for a problem with slow pasting of text when spec is linked with libreadline (but not libedit) in certain environments.

Fix For the "move_done" Property On spec Servers For Pseudomotors

A problem where a request to a spec server for a calculational pseudomotor's "move_done" property would return a value of 0, even when the associated real motors were busy, has been fixed.


New motor_par() "dump" option for Newport SMC100 Motor Controller

A new "dump" option to motor_par() for the Newport SMC100CC/PP motor controllers will display all the controller parameter settings as obtained using the controller's ZT command. In addition, the command motor_par(mne, "read", "ZT") will return a multi-line string that contains the complete ZT response. See the SMC100 manual for more information.