spec

Software for Diffraction

changes

Highlights for spec release 6.08

September 3, 2019 - RELEASE 6.08.06

IMPROVEMENTS

More Robust State File

When saving the state information either at exit or with the savstate command, spec will now fully write out a new state file with a name ending in ".new" before renaming the new file to replace the the previous. In addition, the previous state file will be maintained with a suffix ".old". If on start up, the standard state file is missing or corrupted, spec will attempt to read from a ".new" file, if it exists. If it doesn't, spec will try to read from the ".old" file. The same procedure is followed for the command-line history file. These change should greatly reduce the already small chances of a corrupt state file forcing spec to start fresh. A state file could become corrupted if a computer is shutdown or spec is killed while the state file was in the process of being written.

FIXES

Fix For sixc Pseudo Motors With Tracking Off

When tracking is off for calculational pseudo motors, moving the pseudo motor should not change the positions of the associated real motors and vice versa. The sixc geometry code has been fixed to make sure that is the case.

HARDWARE

Fix For Enabling Multiple PCI Boards Of the Same Type

Some Linux systems are configured so that access to PCI board I/O ports and memory registers is disabled by default on boot with the expectation that kernel drivers will enable access if the PCI board is to be used. spec driverless support for PCI boards also enables access. A bug that only enabled access to the first board when multiple boards of the same type were installed has been fixed.

Support For SPring-8 MADOCA Request Server Layer

The SPring-8 "equipment manager" RPC layer support added to spec in 1999 has been updated to also support the "request server" socket layer. In addition, the naming has been changed to MADOCA to reflect the naming conventions used at SPring-8. The built-in em_io() function has been renamed madoca_io(). An em_io is now included in the standard macros (defined simply as madoca_io) to maintain backward compatiblity with existing local macros. See the madoca help file (formerly named equipman) for details.

MACROS

New save_state Macro To Aid In Diagnostics

The new standard macro save_state invokes the utility show_state (included with the spec package) to write the current state file contents along with config and settings file information, all in human readable format, to either the file specified by an optional argument or to a file beginning with the name /tmp/state. Such a file can be useful at CSS for diagnosing or debugging user issues.

June 16, 2019 - RELEASE 6.08.05

IMPROVEMENTS

New tolower() and toupper() Functions

New string manipulation functions tolower() and toupper() are available to change the case of strings. Optional arguments provide a character count and starting position. See the funcs help file for details.

New Position Argument To asc()

The asc() function, which returns the ASCII value of the first character of the string argument, now accepts an optional second argument to specify a position within the string rather than the first character. Positions are counted from 1. See the funcs help file for details.

New "every" Option to array_op()

A new array_op() "every" option returns every n-th element of a data array. See the arrays help file for details.

Improvements to spec_menu()

A new "alist" key allows selecting multiple items from a list. The list of items must be passed as an associative array. A new "bracket" key allows specifying the bracket characters that indicate selections made with the "list" and "alist" keys. All the descriptive text can now include special text formatting strings for bold, underline, etc. See the spec_menu help file for details.

The show_state Utility Will Attempt To Find Associated Files

The show_state utility presents information not only from the user state file but also from the associated history, config and settings files. When invoked with an explicit state file argument, the locations of the other files are not necessarily known, so the command output doesn't include those elements. With this release of spec, if the file argument to show_state includes the userfiles/ path component, the command will try to locate the associated files based on that path. That is, if the history file is in the same directory as the state file and if the config and settings files are at the same level as userfiles, show_state will find them.

Interruptible Socket Connect

spec uses a four-second timeout when attempting to connect to a socket. That timeout can now be interrupted with a ^C, both with user-level socket commands and hardware initialization from the config file. While initializing hardware from the config file, processing will continue as if the attempt to open the socket failed. During the user-level socket calls, the ^C will jump back to the command prompt, as usual.

Additional Check For Socket Lost Connection

spec will now take notice when a socket connection has been dropped by a server when doing a read of an associated socket. Some spec hardware support recognizes a lost connection and will attempt to reconnect. This check is an addition to the existing tests for lost connections.

Updated Meaning For MCAS and CCDS Global Variables

Previously, the values of the built-in MCAS and CCDS global variables were set to the number of 1D and 2D devices in the hardware config file. If all device numbers were used, one could loop from zero to the value of the corresponding global variable to access all configured devices. If an intermediate device number was unused, such a loop would not address all the devices. The values of MCAS and CCDS are now set to one greater than the highest device number to facilitate such loops.

Updated Behavior For Certain mca_spar() and image_par() Commands

The options "controller", "responsive" and "device_id" to the mca_spar() and image_par() commands will no longer print an error message if the device is unconfigured. For unconfigured devices, the functions will return the string "Unconfigured" for "controller", the value 0 for "responsive" and the value -1 for "device_id". In each case, HDW_ERR will be set to the value 6, which corresponds to trying to access unconfigured hardware. (See the HDW_ERR help file.) Note, that the "unusable" option to the commands still returns a zero or one to indicate whether a given device is available and usable and also does not print a message.

HARDWARE

Macro Hardware Timer/Counter Improvement

If no channels are active for a particular macro hardware timer/counter controller due to all configured channels being unresponsive or disabled, spec will no longer send the "prestart_all" and "preread_all" commands to the associated _cmd macro.

Fix For Struck SIS3820 Reset

Previously spec issued a reset command before programming the Struck SIS3820 for each counting interval. The reset produced an undesirable short spike on the enable signal. The reset command has been replaced by appropriate commands to prepare the device for a new counting cycle.

New MCS Support For Struck SIS3820

spec now supports the multi-channel scaling (MCS) capabilities of the Struck SIS3820 VME Scaler. See the sis3820 help file. spec flyscan macros have been updated to include support for the SIS3820. See the updated flyscan help file.

Fix For USB-CTR MCS Pass Sums

A bug with the recently added support for multi-channel scaling (MCS) with the Measurement Computing USB-CTR counter/timer, where the sum of channels accumulated over multiple MCS passes was not done correctly, has been fixed. Note that for fly scans, which were the impetus for adding the MCS capability, only one pass is made, so the bug was not an issue.

Fix For Halting Trinamic TMCL Limit Searches

An issue, where a ^C or stop() command wouldn't stop a chg_dial() "lim+" or "lim-" search on a Trinamic TMCL motor controller, has been fixed.

Fix For Possible Crash When Reading From a spec Server

Under some conditions, a timeout while attempting to read a message from a spec server could cause a segmentation fault. That issue is fixed.

MACROS

Improved Display With Updated Counting During Scans

The screen display of updated counting during scans will no longer round significant figures of integer counter readings.

New Options For uct Display

The setshow macro for setting certain parameters for displaying motor and counter information now has two additional options for configuring the updated counting display associated with the uct macro. The counter mnemonics can now be displayed. A blank line can now be inserted between each set of counter rows.

Updated flyscan Macros

The flyscan macros now support the Struck SIS3820 VME Scaler as the MCS device, along with the existing support for the Measurement Computing USB-CTR. In addition, the optional normalization function is more robust with respect to normalization channels that might contain zeroes.

FIXES

No Longer Limit Capabilities If root User

spec release 6.05.01 replaced the set-userid-root method of allowing the spec executable access to privileged I/O (such as PCI card registers for hardware control) with use of the Linux capabilities facility. Privileges are only enabled briefly around the calls that gain access. After gaining access, the code releases the capabilities, even if the real user ID was the all-privileged root user. One of the needed capabilities is "dac override" for discretionary access control, i.e., file permissions. When spec disabled that capability, even the root user would lose access to permission-protected files and directories. With this spec release, if the real user ID is that of root, the executable does not manipulate the Linux capabilities at all. Note, CSS does not recommend running spec or even a shell as the root user as normal operating procedure due to the possibility of doing catastrophic damage to the operating system with a single mistyped command.

Fix For Possible Buffer Overflow In array_dump()

Previously, if the optional element format for the array_dump() command specified a too-large format width (for example "%5000g"), there could be a buffer overflow leading to a subsequent crash. That bug has been fixed in this release. In addition, the field width for a single element is now limited to 4096 characters.

edconf String Editing Fixes

An issue with the edconf hardware configuration editor introduced in spec release 6.08.02, where the delete character and the delete to the beginning of the line character when entered in the middle of a string would erase to the end of the string, has been fixed.

edconf Default Limits Fix

Traditionally, when motors were added to the config file using the edconf hardware configuration editor, default values for limits were set to -180 and 180. Recent changes to implement 64-bit motor positions inadvertently caused the default limit values to be set to zero for newly added motors. This release restores the traditional behavior.

March 27, 2019 - RELEASE 6.08.04

FIXES

Another Fix For Escan fixQ Mode

When the Escan macro was rewritten to use the new array-based scan engine in spec release 6.03.08, the implicit calculation of H, K and L from current motor positions via the scan_head call was overlooked, with the result that if geometry motors were moved prior to the Escan, the HKL used in fixQ mode would not necessarily be the HKL associated with the motor positions at the start of the scan. This spec release includes an updated Escan macro that restores the traditional and expected behavior by including an explicit calcHKL call.

Fix For eval2() Replacement

The update in spec release 6.08.02 that replaced the now deprecated eval2() function with a call of eval() with the new optional flags "reset_on_error, local_visible" was mishandled. The eval2() call was replaced with a macro function called eval_arg(). However, macro functions always hide local variables defined outside the macro function, thus defeating the purpose of the "local_visible" flag. This spec release replaces the macro function with a direct call of eval() that includes the flags "reset, local" (the alternative short form names).

March 13, 2019 - RELEASE 6.08.03

IMPROVEMENTS

New "prestatus_all" and "preread_all" Commands For Macro Hardware Counters

To accommodate macro hardware counter configurations where hardware reads multiple channels with a single command, the macro hardware facility now implements "prestatus_all" and "preread_all" commands that can be used to create simpler macro hardware implementations. See the mac_hdw help file for details.

Additional Enhancements For edconf

The ^F and ^B keys can now be used to page through the nonstandard optional parameters screens of motor controllers and counter/timers. In addition, a new help screen describes the value-editing special commands.

Updates To New sixc Geometry Configurations

The new six-circle geometry configurations introduced in spec release 6.07.07 have been updated in order to provide more fine-tuned control over the pseudo motor tracking. See the sixc help file for details.

Support For %a, %A and %F Formatting In printf() Functions

The printf(), fprintf() and sprintf() built-in functions now recognize the %a and %A conversion specifiers, which print float and double values using a hexadecimal notation including an exponent. The %F format is identical to %f and is included for compatibility with the standard C library syntax. See a UNIX/Linux manual page for the printf() function for details on the conversions.

HARDWARE

Updates For Trinamic TMCL Controllers

spec will now, by default, automatically check for a power cycle on the Trinamic TMCL controllers and will restore positions and motion parameters if needed. In addition, reading the controller is more robust, with an automatic retry of commands that have a checksum error in the reply. Also, if the "check_interval" optional parameter is set to -1, power-cycle detection will be disabled. See the tmcl help file for details.

New ANC150 and Updated ANC300 Support

Support for the Attocube ANC300 piezo controller has been updated for more robust error handling and to display estimated positions during updated moves, based on the step frequency and elapsed time. When a move is aborted, spec will estimate the current position at the point that the move was halted. In addition, the configured slew rate will be used to program the step frequency (using the controller's setf command). Support for the similar Attocube ANC150 has also been added to spec (although that model controller is out of production). See the new anc help file for more information.

Updated Mythen Support

spec can now load the user-defined flatfield arrays supported by Mythen firmware 4.1.0. The mca_par("flatfield") command now takes options of either a spec data array or a file that contains the array. In addition, a new "flatfield_slot" command can be used to specify which user-defined array to use. See the mythen help file for details.

Fix For phyMOTION Module Numbering

An issue with the Phytron phyMOTION support, where motor controllers installed to the right of any other module types (power supplies, I/O modules) in a phyMOTION crate were not correctly addressed, has been fixed.

Interruptible Firmware Load With USB-CTR

The Measurement Computing USB-CTR counter/timer requires a firmware upload whenever the device is powered up. It takes almost 15 seconds to send the firmware to the device. The loading process can now be interrupted with a ^C. The firmware will still need to be loaded in order to use the device, but one will not be stuck waiting if there is something else that needs to be done first.

MACROS

Fix To Reset Plotting Parameters With Disabled Counters

An issue associated with plotting when counters have been disabled has been fixed. The plotselect (or similar counters) macro assigns a value to the PL_Y1 global variable that points to the column of interest in the SCAN_D data array for plotting and analysis. If counters are disabled or enabled after the value is assigned, the columns in SCAN_D may no longer match the column chosen for PL_Y1. The scan_data_init() macro, called after acquiring (but before saving) the first point of each scan, now recalculates PL_Y1 taking into account the currently enabled counters.

January 17, 2019 - RELEASE 6.08.02

FIXES

Buffer Management Fix

An issue, where under certain conditions a "Can't get a big memory buffer" message would be displayed, sometimes followed by a segmentation fault, has been fixed. The issue was associated with eval() calls of certain functions with particular argument types. The error could also occur when a spec server executed commands from a client, as the same internal code is used.

Fix For Tsuji Model UPM4C Configuration

A bug, where spec mistook the configuration of a Tsuji Model UPM4C as a PM4C, has been fixed.

Fix For edconf Anomalies

A few minor display and data entry glitches in the edconf configuration editor have been fixed.

December 31, 2018 - RELEASE 6.08.01

IMPROVEMENTS

Internal Type of Motor Positions Now 64 Bits

The spec code base has been updated to switch the storage type of motor positions from 32-bit integers to 64-bit integers. Such a change requires an update to the settings file binary format, which has been accomplished in a completely backward compatible manner. Saved position magnitudes greater than 32 bits will be truncated to 32 bits if the settings file is read by an earlier spec release.

Updated settings File Format

For over thirty years, the settings file stored motor positions as 32-bit integers, reflecting the storage type within spec. This spec release introduces an extended format for the settings file to accommodate 64-bit positions while preserving backward compatibility.

The settings files saves motor parameters that are changed during a spec session and is updated whenever any of the parameters are changed, for example, at the end of a move or if the limits or offsets are adjusted.

The long-time settings file data structure saves values for motors in consecutive chunks that are 24 bytes long laid out as follows (where s32_t is a 32-bit signed integer):

struct  sav_mot {
  s32_t   sm_pos;         /* Current position */
  float   sm_off;         /* Current user/dial offset */
  double  sm_low;         /* Software low limit */
  double  sm_high;        /* Software high limit */
};

spec has a compiled-in limit of 320 motors for the settings file. The first 320 times 24 bytes of the new format settings file has the same information and format as before. That occupies exactly 512 bytes less than 8192 bytes. spec now uses that last 512 bytes of the 8K page for a header. Starting on the second 8K page, all four motor values are saved in consecutive 32-byte long data structures formatted as follows:

struct  sav_mot_d {
  s64_t   sm_pos;         /* Current position */
  double  sm_off;         /* Current user/dial offset */
  double  sm_low;         /* Software low limit */
  double  sm_high;        /* Software high limit */
};

Both spec and the edconf configuration editor now write and read motor settings in both locations. When reading a settings file, the code sorts out whether the data was written using the version 1 or version 2 format and uses the appropriate positions. See the spec distribution files settings_file.h for details on the format, including the header definition. See the config/set2asc.c source code for an example of how to test which settings file version was used.

A settings file saved with the new format will not cause issues with older versions of spec or edconf, other than having 64-bit motor positions (if there are any) truncated to 32 bits. An old format settings file will be perfectly understood by new versions of spec and edconf.

New Options To eval()

The eval() function now recognizes optional arguments "quiet", "reset_on_error" (or "reset") and "local_visible" (or "local"). The "quiet" argument suppresses the display of error messages associated with the eval() command on the screen. The "reset_on_error" option causes syntax errors and the like to reset to the command prompt. The "local_visible" argument causes eval() to have the same property as the now deprecated eval2() function, in that local variables defined outside the eval() call are visible to the command being executed within the argument string. Type h eval at the spec prompt for details.

Page Through MCA/Image Optional Parameters With edconf

The edconf hardware configuration editor (usually invoked via the config macro) now allows paging through MCA and image device optional parameter screens (reached via the p command) using the page forward (^F) and page backward (^B) commands. In addition the ^G command jumps to the parameter screen for the first device.

More Consistent Setting Of HDW_ERR With mca_par() and image_par()

Previously, some hardware errors that occurred in the device dependent code reached through the mca_par() and image_par() calls didn't set HDW_ERR. That issue is addressed in this release.

Updates To counter_par() Error Handling

The counter_par() function will now consistently return a -1 value if there is an error in the device dependent code. In addition, HDW_ERR is set for such errors. Note, since -1 may be an allowed value for some parameters, it is more robust to check for errors by looking at the value of HDW_ERR after a call to counter_par().

HARDWARE

Select Motor Controller Support Now Uses 64-Bit Resolution

Support for macro hardware motors, spec server motors, and the EPICS motor record has been updated to use the 64-bit resolution for motor positions available in this spec release.

Updates For CLS EPICS Motor Record

In addition to using 64-bit resolution for motor positions, the support for the CLS EPICS motor record contains a fix for a scaling issue. In addition, process variable names generated from motor numbers are now always at least two digits with a leading zero for motor numbers 0 through 9.

Initial Support For SmarAct MCS2 Controllers

This spec release supports the SmarAct MCS2 motor controllers. These controllers use a completely new protocol and syntax compared to the previously supported SmarAct models. The support for these controllers uses the new 64-bit resolution for motor positions. Currently, only the ethernet interface with closed-loop mode is supported. See the mcs2 help file for details.

Fix For EPICS Motor Soft Limits

An issue where the spec soft motor limits didn't properly account for backlash set within the EPICS motor record has been fixed.

Fix For New EPICS Scaler "timestamp" Option

A bug that prevented the counter_par() "timestamp" option introduced in the previous release from working for EPICS scaler counters has been fixed.

MACROS

Replace eval2() With eval_arg()

All 100+ calls of eval2() in the standard macros have been replaced with eval_arg() calls. The eval_arg() macro is a new standard macro defined as:

def eval_arg(s) '{ return(eval(s, "reset_on_error, local_visible")) }'

The "local_visible" option invokes the functionality of the now deprecated eval2(). The option allows the eval() call to see local variables defined outside the function call. The "reset_on_error" option addresses an issue associated with the relatively recent introduction of eval() in the standard macros. Using eval() allows expressions and variables as macro arguments. Until this release, the eval() function did not reset to command level if there were syntax errors in the arguments (for example, typing ,01 instead of .01). The "reset_on_error" option causes such errors to reset to command level, restoring the traditional behavior.

FIXES

Fix For Possible Crash With ser_get(), sock_get(), gpib_get() and vxi11_get()

A very old bug that became an issue with unrelated changes made in release 6.06.01, where spec could crash on some platforms when the ser_get(), sock_get(), gpib_get() or vxi11_get() functions were called with an optional argument ("byte", "short", "long_swap", etc.) to read a single binary number, has been fixed.

Fix For HDW_ERR With Successful motor_par()

A bug where the global HDW_ERR symbol was set to "generic error" on successful calls of motor_par() has been fixed. See the HDW_ERR help file for details on the HDW_ERR feature.

Fix For ^C Interrupt While Waiting For Unresponsive DP5/PX5/MCA8000D

The spec support for the Amptek DP5/PX5/MCA8000D accommodates the fifteen second reconnect timeout in the device firmware, but allows the user to ^C out of the wait during hardware configuration. A bug, where a ^C typed during the reconnect timeout on a reconfig call made while spec was running would subsequently disable ^C altogether, has been fixed.

Fix For Process Accounting With splot

A bug, where if the Python splot utility exited for any reason spec did not clean up spec's process accounting table, has been fixed. Previously, one might have seen a "Too many processes for spec" message after that happened sixty or so times.

Fix For Internal Process Creation Error

A bug, where if spec's internal code failed to create a new process (particularly when using the unix() command), pathological behavior occurred, such as run away CPU usage or spec killing all of the user's processes, has been fixed.

Fix For readline Key Binding

An old bug in a key-binding call in spec (but only when linked with the readline command line editing library -- not the default libedit library included with the spec distribution) bound the circumflex key (^) to the reverse incremental search command. That bug is fixed in this release. The behavior can be fixed when running older releases of spec by putting the line:

"^": self-insert

in a file named ~/.spec_keys. See spec's readline help file and the official readline documentation for further details.

Assorted splot Fixes And Enhancements

The Python splot utility included with spec is updated to the current release. See the splot update notes in the distribution for details.