spec

Software for Diffraction

changes

Highlights for spec release 6.03

April 20, 2016 - RELEASE 6.03.11

IMPROVEMENTS

Updates For spec_menu()

A new "choices" key to spec_menu() can be used to replace the default YES and NO prompts used with the "bit" and "toggle" keys. See the spec_menu help file for details.

MACROS

Fix For wm Macro

A bug in the wm (where motor) macro versions since release 6 of spec caused by a typo has been fixed. Previously, if the number of motor arguments was sufficient to require a second row of motors, the user positions in the second and subsequent lines would belong to the first line.

FIXES

Clarity For When ASCII Plots Get Drawn

A little used but still supported plotting feature that dates from spec's origins is the ability to use ASCII characters and cursor positioning commands to plot scan data on a terminal screen. The option to use ASCII plots is included in the setplot macro and allowed if the standard x11filt plotting is disabled. Although the standard plotting macros would create the correct plot based on the selected options, the functions array_plot() (and data_plot()) would send cursor positioning commands if x11filt plotting was disabled, even when ASCII plotting was also disabled. This spec releases fixes the C code to prevent such output. The macros have been updated to use the plot_cntl() "ascii" and "-ascii" options to ensure the mode is only enabled when specifically configured.

HARDWARE

Software Timer Now Plays Nice With Multiple-Timer Configurations

Previously, the software timer would reset to command level if attempting to count to a monitor preset with mcount(). That may have been sensible when spec only allowed a single master timer. However, spec has allowed multiple master timers since release 5.09.01-1. Now, if counting to monitor, the software timer will simply keep track of elapsed time until halted by another master timer.

Fixes For Multiple Master Timer Configurations

An issue when using multiple master timers, where several models of timers would modify the global count time parameter which was then used by the other timers, has been fixed. The changed value could be passed to macro-hardware timers with the "start_all" and "start_one" keys. The master timers that would change the count time values were the Am9513-based models with count times less than 20 microseconds or greater than 71.5 minutes, the Mizar MZ 8310 with count times greater than 10.92 minutes and the National Instruments 660x or 63xx models if counting to monitor with the hardware prescaling option turned on. In addition, the software timer, the Am9513-based models, the Mizar MZ 8310 and the Siemens D5000 models would change the count time with the move_cnt command. Note, though, in move_cnt mode the count time is otherwise zero and in any case should be ignored.

Fix For motor_par() "read" For PI E-712

A bug that always resulted in an error return for the command pass-through "read" motor_par() option for the Physik Instrumente Model E-712 piezo controller and that has been present in the code since the first version of the support in spec release 5.09.02-1 (2011) has been fixed.

Ketek DDP2 Renamed DPP1

The spec support for the Ketek DPP now refers to the device as a DPP1, which matches Ketek's current nomenclature. See the ketek help file.

February 27, 2016 - RELEASE 6.03.10

IMPROVEMENTS

Improved Locking For State File and settings File

The code to lock and check for locks on the state file and the settings file has been updated to use system calls that should be more robust if the files are on NFS mounts. The state file lock prevents a user from starting multiple instances of the same spec version. The settings file lock prevents more than one instance of spec from trying to control the same hardware. It is also now possible to use reconfig to gain access to previously locked out hardware without exiting spec if the instance of spec that had locked the hardware exits. See the set_sim help file for details.

Fix For Moving Off Limits

For many motor controllers, if a move off of an active limit was not far enough to clear the limit switch, spec would behave as if such a move ended by hitting the still active limit switch. That means spec would print a limit-hit message and abort any other motors that might be moving. With this release, such a move will be treated as a normal move for all motor controllers.

New spec_par() Option To Enable Previous Limit Behavior

The above change in spec code for recognizing a limit condition could be an issue if the spec support for a particular motor controller misidentified the plus and minus limits. If a site finds a problem, a new spec_par("legacy_limit_check") option is available to restore the prior behavior until CSS can fix the motor controller support. See the spec_par help file for details.

Maximum Number Of Scalers Increased To 256

To meet the needs of a least one installation's hardware configuration, the maximum number of scalers allowed by spec has been increased from 128 to 256.

splot Updates

Among the updates for the Python splot utility are a fix for an issue where the first scan might contain spurious points when connecting to spec in server mode. Also, scroll bars are now available with the zoom feature when using the matplotlib 2D plotting library option.

HARDWARE SUPPORT

Support For EPICS Motor Record DISP Process Variable

The spec support for the standard EPICS motor record (as used at the APS) now includes the generic DISP (disable) process variable. spec will register to receive DISP events for all motor channels. When a DISP event is received, the associated motor will be disabled or enabled as appropriate. The behavior in spec is the same as if the motor_par() "disable" command had been issued for the motor. However, motor_par() cannot be used to undo the results of the DISP event.

Fix For Huber SMC 9300 Limit Sense

A long standing error in the support for the Huber SMC 9300 motor controller that switched the sense of plus and minus limit status indications has been corrected. Unless user macros relied on differences in return value of the motor_par() "high_lim_hit" and "low_lim_hit" options, there should be no difference in behavior, other than in the messages that describe which limit has been hit.

Fix For Amptek DP5/PX5 Support

Recent updates to the spec support for the Amptek DP5/PX5 latest firmware broke sending the TPFA (fast channel peaking time) parameter for firmware prior to 6.7.5. This release fixes that issue. In addition, the code to display parameters from the diagnostic packet has been revised, which may result in more sensible values displayed on the screen with the mca_par("diagnostics") command.

Preliminary Support For Encoders With TMCL Controllers

This spec release includes preliminary support for encoders on the Trinamic TMCL motor controllers. If the controller type is selected as TMCL_E, spec will use relative moves for positioning, read the position from axis register 209 and write the position to register 209 with the chg_dial() function. In addition, if the optional motor parameter "encoder_step_size" is set, spec will scale the values accordingly. See the tmcl help file for details.

Support For Deceleration Parameter On Compumotor 4000

The spec support for the Compumotor 4000 motor controller will now program the deceleration parameter, if it has been set in the hardware configuration file or via motor_par(). If not set, the deceleration will be programmed with the same value as the acceleration parameter.

January 16, 2016 - RELEASE 6.03.09

IMPROVEMENTS

New plot_cntl() Commands

The plot_cntl() function, used with the x11filt, now recognizes commands "grid" and "-grid" to enable or disable display of a grid over the plot, "dotsize=value" to set the size of large dots and "width=value" to set the width of the lines connecting the data points. See the plot_cntl help file for details.

splot Utility Updated To Version 2

spec now includes a new release of the Python splot plotting utility. Version 2 of splot can now use either the PyQt5 or PySide Qt binding libraries, in addition to the PyQt4 supported by splot version 1. Also, splot version 2 can use the matplotlib 2D plotting library instead of the PyQwt5 library required by version 1. Finally, a number of issues have been fixed and new features added. See the update notes in the splot distribution directory for details.

BUG FIXES

Fix For prefix_ADDR For Macro Hardware Image Devices

A bug where the edconf configuration editor didn't read an optional ADDR value from the config file when associated with with a macro hardware image device has been fixed. The value in that field can be accessed in the macro hardware macro functions as a local variable named prefix_ADDR where prefix is the identifier configured for the particular macro hardware device.

MACRO UPDATES

Logarithmic x-Axis Now Supported In the Plotting Macros

The setplot and draw_plot() macros have been updated to allow using a logarithmic x axis.

draw_plot() Updated For New plot_cntl() Options

The draw_plot() macro, which does the main work of creating plots, now implements grid mode, dot size and line width for x11filt plots.

New vscan Global Parameters To Set Default Values

The new variable step size macros, vscan and v2scan, now recognize global variables named VSCAN_EXPON and VSCAN_MINSTEP which, if nonzero, will provide default values to use for the exponent and minimum step size if the value are not specified as a macro arguments. See the comments in vscan.mac source file for details on the macros. The vscan macros require the new array-based scan engine from newscans.mac.

fscan Bug When Scanning Single Motor Fixed

A bug in the initial release of the fscan macro, which prevented the macro from working if the scan was for just one motor, has been fixed. The fscan macro requires the new array-based scan engine from newscans.mac.

Macro cplot_plot Updated To Work With Current Plotting Macros

Obsolete code from the cplot_plot macro that attempted to make the macro work with the very old plotting macros has been removed.

sevc Geometry _assign Macro Fixed

The _assign macro, which is defined for each geometry to assign the special geometry motors to the first positions in the mA[] array, was missing a required call to _assign_mA, which is a macro that assigns the rest of the motors to mA[]. This spec release fixes the macro definition.

HARDWARE SUPPORT

Kohzu Motor Controller Support Updated To Recognize New Models

The code to support the Kohzu model SC-200, SC-400 and SC-800 motor controllers has been updated to also recognize the newer model SC-210 and SC-410 controllers. The programming sent by spec to the controllers is unchanged.

November 11, 2015 - RELEASE 6.03.08

IMPROVEMENTS

Fix For Memory Leak In Macro Functions

A memory leak in macro functions has been fixed. The leak occurred when the macro function was defined with arguments, an associative array was assigned to an argument within the function and the function was invoked without an argument. For example, the following minimal code would leak memory:

global ARR[]; ARR[0] = 0; def test(arr) '{ arr[0] = ARR[0] }'; test()

The bug has existed since macros functions were introduced.

Improvements For MCA Sub-Address Syntax

When a single MCA unit has multiple MCA modules (such as the Dectris Mythen 6K/24K or the Canberra Multiport II), the mca_spar(), mca_sget() and mca_sput() functions accept an address argument with a subaddress in the form a.b, "a.b" or "a:b", where a is the MCA unit number and b is the module subaddress. The first form is a number, while the second two forms are strings. Previously, the subaddress of the number form for 1.10 and 1.20 would be interpreted as 1 or 2, respectively. With this spec release, the subaddress will be interpreted as 10 or 20 as intended.

Fixes and Updates For the splot Utility

The Python-based splot utility has several fixes relating to how the axes are drawn and will also now work correctly with energy scans and the reciprocal space parametric scans (hkcircle, hkradial, etc.).

MACRO UPDATES

Continuous Scan Updates

The recently introduced continuous scan macros have been reorganized a bit and new continuous delta scans, cdscan, cd2scan, cd3scan and cd4scan, have been introduced, along with a new continuous delta mesh scan, cdmesh. The delta versions of the continuous scans take position arguments relative to the current positions of the motors and return the motors to their starting positions at the end of the scan or if the scan is interrupted. See the comments in the cscan.mac file included in the spec distribution for usage details.

Fix For Escan Compatibility With splot

The Escan macro has been updated to set global variables (_nm, _s[] and _f[]) used by macros that communicate with the Python-based splot utility.

Fixes For scan_data_init(), scan_data() and scan_meta_update()

The scan_data() macro and the new scan_data_init() and scan_meta_update() macros that that communicate with the Python-based splot utility have been fixed so energy scans and parametric scans, such as the radial and circular reciprocal space scans, will plot correctly. Previously, assignments to the SCAN_COLS and SCAN_D arrays were not quite right for those scans.

More Fixes and Updates For newscans.mac

The macros in newscans.mac that will replace the current scans in scans.mac in a forthcoming spec release have been slightly reorganized. Also, a new scan-type macro named hklscanarr takes an array of HKL positions and an optional count time as arguments. If the count time is missing, the last column of the array contains the count time. See the comments in the newscans.mac file included in the spec distribution for usage details.

New Variable Step-Size Scans

New scans called vscan and v2scan do variable step-sized scans with densest points at a specified "center" position. The scans use the new array-based scan engine contained in newscans.mac. See the comments in the vscan.mac source file.

HARDWARE SUPPORT

Support For Struck SIS3153 USB VME controller

spec now works with the Struck SIS3153 model VME controller over the USB interface. Configuration is the same as for the earlier SIS3150 model. spec will detect which is connected and behave accordingly. Support for the ethernet interface on the module will be included in a future spec release.

Fix To Accommodate OMS MAXnet Firmware Update

The latest firmware (version 1.48) for the Oregon Micro System MAXnet motor controller introduced a change in protocol which broke spec's existing support. This spec release will work with both the new firmware and previous versions.

Fix For Mythen Firmware 3 Multiple-Module Communication

Issues with updating parameters on Mythen 6K and 24K devices with multiple MCA modules using version 3 and later firmware have been fixed.

October 14, 2015 - RELEASE 6.03.07

NEW FEATURES

New "open?" Option For plot_cntl()

A new "open?" query option for the plot_cntl() function returns nonzero if the currently selected filter process is running and zero otherwise. See the plot_cntl help file.

New "depends" Option For motor_par()

A new "depends" option for motor_par() returns an associative array containing a list of motor mnemonics that correspond either to the real motors that the pseudo motor argument depends on, or the pseudo motors that depend on the real-motor argument. If there is no dependency, an empty associative array is returned.

IMPROVEMENTS

Faster Quitting When Multiple Plot Windows Are Open

A delay of 0.25 seconds associated with terminating each plot window when spec exits has been eliminated.

Fix For "prestart_all" and "start_all" Macro-Hardware Motors

Previously, when moving macro-hardware motors from different macro sets at the same time, the macro-hardware motor support would call all macro-hardware motor _cmd() functions with the "prestart_all" and "start_all" command keys when starting backlash moves for any of the motors being moved. The code will now call the _cmd() function only for the motor that is getting the commands to start backlash.

Updates For HDW_ERR Implementation

HDW_ERR is now a built-in global variable. It no longer has to be created at user level to take effect. HDW_ERR will now be set on failed calls to motor_par() and counter_par() in order to distinguish a failed call from a valid return value of zero or -1. See the HDW_ERR help file for details and a list of the possible error codes.

Updates For psic Sectors Implementation

The sectors implementation for the psic geometry has been cleaned up and now works more in line with how it is documented in the psic help file. In addition, the sectors macro now takes an optional argument to select how to display the results. See the psic help file for details.

Updates For fmt_read() and fmt_write()

The API for the user fmt_*.c has a couple of changes. The data set number passed to the read and save functions now begins at one rather than zero. A bug in the ff_get_next_head_item() function that could return a spurious command and ID that has values for both of "0" has been fixed.

Updates To ESRF Format Binary File Writing and Reading

The implementation of the "esrf" format for the fmt_write() and fmt_read() commands has updated to allow setting the ID number in the data block header. In addition, a new "esrf2" format is included which aligns both the header and the data on 1024-byte boundaries. The "esrf" format only aligns the data on 1024-byte boundaries. See the notes in the fmt_esrf.c file included in the spec distribution for complete details.

BUG FIXES

Fix For Crash When An Output File Disappears and Cannot Be Reopened

Updates in spec release 6.02 to implement the built-in OUTFILES associative array introduced a bug where a crash could occur if an output file disappeared while spec was running and the output file could not be reopened. That could happen, for example, if the path leading to the file no longer existed. That bug is now fixed.

Fix For x11filt Additional Window Parameters In .Xdefaults

A feature documented in the spec x11 help file, where parameters can be set in a user's .Xdefaults file for additional plot windows, such as spec_2.geometry, spec_3.Foreground, etc, has not been working since spec release 5.01.02. This spec release restores that feature. With the new macro support for multiple plot windows, it is important to be able to set the default location and parameters of the additional windows.

Fix For User Process Termination If splot Cannot Be Found

A bug, where spec would issue the kill() system call with the pid argument equal to -1 after approximately 64 failures to execute the program assigned to SPLOT_PROGRAM, has been fixed. The effect of calling kill() with pid set to -1 is to terminate all the user's processes.

Fix For unix() Return Value

A bug introduced in release 6.02.08 where the return value of the unix() built-in function was shifted up eight bits has been fixed. (The return value of unix() is the exit status of the system command executed by unix().)

Fix For HDW_ERR In Server Mode

An old problem, where a socket error in the spec server read or write threads could set the HDW_ERR value associated with a user function call in the command thread, has been fixed. For example, during execution of a command such as gpib_get(), HDW_ERR could be set by the read thread if it loses a client connection even though the GPIB call had no error. In this spec release, socket errors associated with the spec server read or write threads will no longer change the value of HDW_ERR.

MACRO UPDATES

New Macro Support For Multiple Plot Windows

The standard macros now support assigning different counters to different plot windows. The feature works with both the traditional x11filt plotting and the new Python-based splot plotting. Use the setplot macro to enable using multiple plot windows. Use the plotselect (or counters) macros to assign particular counters to up to five different plot windows. If both x11filt and splot utility are enabled, the same window assignment of counters is applied to each.

Updates To splot Utility To Reduce Use of splot_cntl()

The standard plotting macros have been updated to reflect the new ability of the Python-based splot utility to adjust plots to user preferences automatically. For plotting during scans, it is no longer necessary to include any splot_cntl() commands in the macros other than an "open" command. The plot configuration is now added to the meta region of the SCAN_D shared array.

Update To setplot Argument Behavior

Without arguments, setplot prompts for plot configuration options, most of which are toggles assigned to bits in the PLOT_MODE global variable. With an argument, PLOT_MODE is set directly. If the argument begins with a + or - sign, previously, the value would be added to or subtracted from PLOT_MODE. With this spec release, bit-wise operations will be used instead to add to PLOT_MODE or remove from PLOT_MODE the bits contained in the argument, so that repeated calls with the same argument will not change bits not in the argument.

Spurious Comments Generated By the set Macro Eliminated

To accommodate using the set macro with pseudo motors, the macro compares positions returned by getangles before and after changing the offset. Changing the offset for a pseudo motor that depends on real motors or for a real motor that is used by pseudo motors, can change the user position of the associated motors. However, motors with fluctuating positions due to sensitive encoders could also show up as having the offset changed. The set macro has been revised to use the new "depends" option for motor_par() and will now only reported changed offsets for the relevant motors.

New Test For Accessible Data File In Standard Scan Header

The standard _head macro used by all the scans will now make sure the current data file (as contained in the DATAFILE symbol) can be accessed using the open() function. If open() fails, the _head macro will execute the exit command which will abort the scan. Previously, repeated messages indicating failure to open the data file would be displayed while the scan continued.

User Hook move_poll Macro Now Included In dscan_cleanup

The move_poll macro, defined as a null macro by default, is now called after the _move command in dscan_cleanup.

HARDWARE SUPPORT

Fix For EPICS Motors With Rapidly Updating Encoders

In configurations with EPICS motors that constantly send updates with small fluctuations in position (due to a sensitive encoder, for example), spec could send move commands to the motors during scans, even if the motors were not involved in the scans. The "slop" parameter can now be used with such motors to create a position dead band. Position events within "slop" counts of the current position won't update the current position in spec. However, at the end of a move or during a sync command, the current position will always be read. The "slop" parameter is set on the second standard optional parameter motor screen of the configuration editor.

Additional Fix For Communication Errors With Tsuji PM16C Motor Controllers

An additional issue where a bad read of the Tsuji PM16C motor controller status could cause a spurious "both limits set" event has been corrected.

July 30, 2015 - RELEASE 6.03.06

Can Return Sub-second File Times with file_info()

The "atime", "mtime" and "ctime" options to file_info() will now return file times to sub-second resolution on platforms and file systems that support the feature. Linux platforms with glib version 2.12 or greater support the feature. All Mac OSX versions supported by spec support the feature, although the HFS and HFS+ file systems do not.

Broken or_swap Macro Fixed

Updates to the orientation matrix macros in spec release 6.02.08 to accommodate a new seven-circle geometry introduced a bug in the or_swap macro used to swap the two orientation vectors. That bug is fixed in this release.

Fix For Server Crash

A rare crash that could occur in a spec server when the socket connection to a client was unexpectedly lost while there were pending events for that client has been fixed.

Improved Handling Of Communication Errors With Tsuji PM16C Motor Controllers

The spec support for the Tsuji PM16C motor controllers now includes code to better detect and deal with communication errors. Previously, if the communication interface was error prone, it was possible for the messages between the controller and spec to get out of sync, with responses getting associated with the wrong command. One symptom of the out-of-sync problem would be a spurious message that a motor hit a limit switch. The code now does consistency checking on the responses to the read-position and get-status commands. If the responses are in the wrong format for the particular command, spec will attempt to resynchronize communications.

Fix For Kontron PCIDCC5 Digital I/O

A bug in the code that prevented the counter_par() commands for setting and reading the digital I/O on the Kontron (ICS Advent) PCIDCC5/5-P model Am9513-based PCI counter/timer card has been fixed. See the am9513 help file for details on the commands.

Fix For Agilis Configuration Crash

A recently introduced bug, where the code for the Newport Agilis motor controller could cause a crash if a controller was configured but not present, has been fixed.

July 7, 2015 - RELEASE 6.03.05

Unlimited Line Length for getline() and array_read()

The getline() function to read a line of text from a file and the array_read() function to fill a data array with values from a text file have been updated to allow reading from files with unlimited line lengths. Previously, getline() would read up to a maximum of 4095 characters and array_read() would allow input lines up to 2047 characters.

New GETLINE_EOF Built-in Symbol For getline()

To distinguish between an end of file, an error or a literal -1, the getline() function now assigns a value to a new built-in variable named GETLINE_EOF. After each call of getline(), the value of GETLINE_EOF will be 1 if there was an end-of-file condition on the read of the file, -1 if there was an error reading the file or if the file couldn't be opened and zero if the read was successful. For backward compatibility, the getline() return value will continue to be -1 on end of file or an error, or if the current line of the file is the string -1.

New array_read() Option To Skip Initial Columns

A new optional "C=#" argument to array_read() can be used to specify from which column in the file to start assigning data. See the arrays help file for details.

Restored Capability For Fixed-Ranged Updated Plots

Release 6.02 of spec included new plotting macros that auto-ranged the x axis in the updated plot displayed during scans. This spec release now includes an option to configure the behavior as either fixed or auto-ranged via the setplot macro.

Updates For New Focus 8742 Motor Controller

The spec support for the New Focus 8742 controller now works with its USB and RS-485 (via RS-232C) interfaces. In addition, daisy-chained units connected in series with a master (gateway) controller using the RS-485 connections are now supported. When using daisy-chained units, set the "crate" address in the motor configuration to the module address. Finally, the socket connection code will now automatically attempt to reconnect when connections are dropped by the controller.

Fix For Mythen When Specifying a TrimMo Settings File

An old typo in the spec Dectris Mythen MCA support that translated the deprecated (in firmware version 2) "-trimfile TrimMo" command to the "-settings StdmMo" command has been corrected by removing the surplus lower case m. In addition, the deprecated (in firmware version 3) "-settings" arguments that begin with Hg, Std, and Fast have those prefixes automatically removed when using firmware version 4.

Fix For Reporting Trinamic TMCL Parameter Values

All the Trinamic TMCL motor controller parameters can be accessed via the motor_par() function using generic numbered names, such as "par6". Some of these parameters have aliases such as "PeakCurrent" which corresponds to parameter 6. Previously, if the parameter value was changed using the generic name ("par6"), the value reported by motor_par() for the alias ("PeakCurrent") would not reflect the new value. That issue is corrected in this release.

Fix For Server Mode Interactive Command Echoing

An issue where characters typed at the keyboard of a spec server session could be echoed twice to the screen if typed while the server was executing a client command has been fixed.

Updates For splot Utility

The splot utility now supports x-axis logarithmic plotting. Also, an issue with y-axis logarithmic plotting in shared-data mode, where data was not always plotted, has been fixed. In addition, a new splot_cntl() command "plotrange" provides the same functionality as the plot_range() function for the traditional plotting and is used in the standard plotting macros to implement the setplot options to force the y-axis minimum to zero and to use fixed ranges for the x axis during scans.

A new splot_cntl() command "showstats" can be used to toggle the display of the peak, center-of-mass and full-width-at-half-max markers.

A new splot_cntl() command "showmotor" can be used to toggle the display of a marker showing the current position of the

Fixes and Updates For newscans.mac

The previous release included a file named newscans.mac that contains a new implementation of the standard macros that will replace the standard macros in a forthcoming update. There are a few updates to these new scan macros as follows:

The HEADING string (used in the screen display, data file and plots) for the dscan macros had showed incorrect start and end positions, but is now fixed.

The new fscan (file scan) macro has been updated to allow the count time to be optionally assigned at the end of each row of motor positions. If invoked without a count-time option, and if the file contains a count time at the end of each row of motor positions, the file count times will be used at each point. If the scan is invoked with a count-time argument, the file count times will be ignored. Also, the motor mnemonics for the scan must now be proceeded by a #M and a space rather than a lone # to allow for comments in the file and future # directives. A single # followed by a space introduces a comment.

May 11, 2015 - RELEASE 6.03.04

New String-Handling Functions With Regular Expressions

New built-in string-handling functions use an extended regular expression as an argument as follows:

rsplit()
like split() in that it splits a string and places the parts into an array, but the delimiter can be a regular expression.
match()
finds the position in a string where a regular expression occurs, and optionally places matched subexpressions into an array.
sub()
replaces a single instance of text in a string that matches a regular expression.
gsub()
replaces all instances of text in a string that match a regular expression.
gensub()
replaces selected instances of text that match a regular expression.

See the entries for each function in the funcs help file for further details and features.

New Macro Special Symbol $@

It is often useful when parsing macro arguments, particularly when the macro is called with a variable number of arguments, to use the split() function to place the arguments into an associative array. The normal syntax is:

{
  local ac, av[]
  ac = split("$*", av)
}

However, that usage does not respect quoted arguments, since $* removes quotation marks when concatenating the macro arguments. This spec release introduces a new sequence $@. When an ordinary macro with arguments is expanded, $@ will be replaced with the concatenated arguments delimited by the special character \a (the audible bell, ^G, ASCII 7). The string can then be split as follows:

{
  local ac, av[]
  ac = split("$@", av, "\a")
}

The elements of av[] will respect the quoted arguments in the macro invocation. There is no syntax to escape the \a.

New "lines" Option For file_info()

A new "lines" option for the file_info() function returns the number of newline characters in the specified file. See the file_info() entry in the funcs help file for a description of all the available options.

New Flexibility For the Indirection Operator @

The spec parser now allows the indirection operator @ to be applied to a parenthesized variable or associative array element. The priority of @ is higher than the square brackets of the array, so parenthesis must be used if the array element contains the string which points to the symbol. For example:

SPEC> arr[0] = "PI"; s = "arr"
SPEC> print @s[0], @(arr[0]), @(@s[0])
PI 3.14159 3.14159

The expanded syntax allows cascaded usage as shown above.

strdef() Can Now Return Chained Macro Segments

The strdef() function, which returns the string definition of the macro name given as an argument, can now return segments of a chained macro as specified by the associated key given as a second argument. See the strdef() entry in the funcs help file for a detailed description.

get_lim() Can Now Take Backlash Into Account

The get_lim() function to return software motor limits will return the limit corrected for backlash if the magnitude of the second argument is greater than 1. For example, for a motor with sign of user*dial positive, backlash positive and steps per degree positive, the corresponding return values might be:

SPEC> p get_lim(tth, -1), get_lim(tth, -10)
-180 -179.99

That is, although the actual soft limit is -180, when taking account the configured backlash, the effective limit is -179.99.

Move Macros Now Allow Variables For Motor Mnemonics (Really)

The feature announced with release 6.02 that allowed motor mnemonics to be given as variables for the motor-move macros (mv, umv, mvr, umvr, mvd and umvd) didn't actually work when the release came out. The parser modification for the indirection operator (@) that enabled the feature was problematic and immediately reverted. This spec release fixes the problems and restores the behavior. Thus, usage such as:

for (i = 0; i < 5; i++) mv i 10

and:

{ par="phi"; umv par 4; par=th; umv par 1 }

will work.

New Return Value For srand()

The srand() function, used to set the seed value for the pseudo-random number generator now has a return value, namely the value of the previous seed.

delete Can Now Be Used On Entire Associative Array

The delete built-in command can now be used to delete all elements from an associative array. Previously, delete would only remove one element. Note, delete doesn't remove the array or change its type, it just removes all the elements. Use unglobal to remove the array from the symbol table.

Preliminary Release of Updated Scan Macro Package

A file named newscans.mac is included in the distribution that contains a preliminary release of a new array-based scan engine and several new standard scans. These scans will replace the standard scans in scans.mac in a subsequent release. The new scan engine uses a pre-filled array of motor positions for the scan points, which allows better pre-scan limit checks and enables new scan types. Existing scans that are replaced include ascan through a5scan, dscan through d5scan, lup, th2th, mesh, hscan, kscan, lscan, hklscan, hklmesh, hkcircle, hlcircle, klcircle, hkradial, hlradial and klradial. The standard _ascan macro will no longer be used, but will continue to be included in the distribution for the benefit of local scans that use it.

The macros in newscans.mac are not installed with this release, but can be activated by reading the file with qdofile() or qdo.

New scans in newscans.mac include:

A new fscan does motor scans based on positions in a file. The first line of the file contains a list of motor mnemonics as a comment. Subsequent lines contain corresponding motor positions. Each line is one point in the scan.

A new dmesh scan, which is a delta mesh scan, similar to a delta motor scan. Endpoints are specified relative to the starting positions and motors are returned to the starting positions as the end of the scan.

A series of expanded motor scans named xascan through xa4scan and xdscan through xd4scan add a configurable number of points at the beginning and end of regular motor scans at a lower point density.

A region scan named rscan allows specifying a single motor scan with various point densities in consecutive segments.

See the comments in the newscans.mac file in the spec distribution for additional details.

Fix For split() In Macro Functions

An old bug, where an "Illegal reference to array" error would occur when using a local associative array as a return value in a macro function when the array had been used with the split() function but where elements had not otherwise been assigned any values, has been fixed.

Fix For array_read()

The return value of array_read() is the number of points read from the file. A bug, where the value did not include points assigned when the number of columns in the data file was less than the array dimension, has been fixed. spec has always assigned as many elements to the array as are available in the file, but had not been including points in the return value when a line of data from the file did not have values to fill every column (or row for a column-wise array).

Fix For counters/plotselect Macro

An issue with the interactive spec_menu() versions of the counters/plotselect macro introduced in spec release 6.02, where the wrong value would be assigned to DET or MON if there were any lower-numbered disabled counters, has been fixed.

Fixes and Updates For splot Utility

Arguments in the scan_info_update() macro function in the standard _tail and _scanabort macros along with the splot Python code have been fixed to correct an issue where the last point of scans wasn't always drawn. Another issue with the splot utility, where plots sometimes did not refresh correctly when switching between types of scans, has been fixed. New options for the splot_cntl() "marker" command are available. A new splot option to display the current motor position is available from the PLOT menu of the splot window.

Fixes For Trinamic TMCL Support

An issue with spec's support for the Trinamic TMCL motor controllers, where it was not possible to update certain global parameters, has been fixed.

New Timing Parameters For Agilis Communication

New non-standard optional parameters named "wdelay" and "rdelay" are available for the Agilis motor controller. These parameters can set a delay for writing commands to the Agilis and reading replies from the Agilis. See the agilis help file for details.

Fixes For sevc Geometry

The preliminary support for the sevc seven-circle diffractometer geometry has been updated with several fixes in the sevc.src macros.

April 1, 2015 - RELEASE 6.03.03

Fix For tango_put() With String Array

A segmentation fault that occurred with tango_put() when called with an empty associative array for a data type that required a string array has been fixed.

More Fixes For spec_menu() Issues

A bug, where a call to spec_menu() with a menu that had no editable items would cause a segmentation fault, has been fixed.

Correction For Recent whatis() Fix

A fix in release 6.03.01 for an old bug in the whatis() function that inadvertently broke another aspect of the function has been corrected.

Support For Newport Agilis AG-UC8

This spec release includes support for the Newport Agilis AG-UC8 piezo controller. The update to the existing code for the Agilis AG-UC2 model includes support for the absolute positioning command and setting the step-amplitude parameter. See the new agilis help file for details. Note, the update code has only been tested with the serial interface on the AG-UC8. Please contact CSS if any problems using the USB interface on either the AG-UC2 or AG-UC8.

March 22, 2015 - RELEASE 6.03.02

Macro Hardware Support For CCD-type (2D) Devices

The macro hardware facility now includes support for CCD-type (2D) detectors. See the updated mac_hdw help file for details.

Updated Support For Mythen Firmware 3 and Mythen2 Firmware 4 Models

The spec support for the Dectris Mythen MCA has been revised and updated to work with firmware version 3 and the new Mythen2 models that use firmware version 4. See the updated mythen help file for details.

Fix For spec_menu() Issues

The relatively new spec_menu() function has been updated to fix a couple of issues. A crash that could occur when passing an uninitialized symbol as the first argument has been fixed. A crash that could occur when scrolling with a menu that included "desc" keywords for items that had no editable elements has been fixed. In addition, if there is a "desc" keyword with no editable elements, the spec_menu() function will now treat the entry as a "subhead" so that the cursor does not stop on the item.

sync Command Fixed To Halt Multiple Timers

The sync command, normally used to make sure motor hardware and software are synchronized, also aborts the current move and active counting. Previous versions of spec only halted one active timer or acquisition device, even if multiple master timers or acquisition devices were configured. The sync command will now force stop all active timers.

New Indenting Option For config File

The configuration editor edconf now takes optional arguments +w or -w to add or remove a single character white-space indentation in the config file on lines beginning with the words STATE, CONPAR, MOTPAR and CNTPAR. Adding the space aids in readability of the file. The +w adds the indenting when writing out the file. The -w removes the indenting. If the option is unspecified, the existing indenting (or lack thereof) is maintained.

February 12, 2015 - RELEASE 6.03.01

Updates In the HDF5 Support

The standard spec distribution now includes static libhdf5.a and libz.a files that can be linked with spec during installation to provide HDF5 support. The libraries have been built from the open-source HDF5 and ZLIB source packages. The spec Install script now prompts for HDF5 linking specifications.

New options are available to set the raw-data chunk-cache parameters used for writing data to the HDF5 file, either per dataset or for all datasets in an opened file.

A new h5_link() function can be used to create soft links to HDF5 objects in an external file.

A new "flush" option to h5_file() can be used to tell the library to write existing data out to disk.

The format used to save string-valued associative arrays has been changed from using variable-length strings to using fixed-length strings.

One-dimensional arrays can now be set to unlimited size. One scalar value at a time can be added using the frame syntax of h5_data().

spec is now built against release 1.8.14 of the HDF5 libraries.

See the spec hdf5 help file for details on the updates.

Support For ARM Platforms

The spec package can now be built to run on ARM platforms such as the Raspberry PI or BeagleBone Black. Contact CSS for details on OS support.

Fix To Enable Support For Baltic Scientific Instruments Si(Li) Detector

The BSI detector support documented in the spec release 6.02.09 release notes was not actually available due to a coding error. That issue has now been corrected.

Fix For whatis()

A old bug in the built-in whatis() function that could incorrectly identify a local variable as a macro has been fixed. Although unlikely, if a user defined a macro named f, the show_motor_info() macro function used by wa, lm, etc. would fail due to this whatis() bug.