DESCRIPTION

These notes summarize many of the modifications made for spec release 2.15, as of February 21, 1992.

INCOMPATIBILITIES

Release 2.15 includes a number of changes that make certain prior usages obsolete.

1. The getmca() function has been eliminated. A new interface to MCA-type devices has been established using the functions mca_par(), mca_get() and mca_sel(). See the funcs help file for details.
2. The syntax of the C-PLOT user function scans.4 has been modified slightly to clear up ambiguities concerning how the data points are to be normalized. The -m and -t flags have been replaced with a +n or -n flag to indicate whether the data is to be normalized, and .BI m= col and .BI t= col arguments to specify column numbers for the monitor-counts or time normalization values. If columns aren't specified, the normalization is taken from the #M or #T directives in the data file.
3. The method for subtracting a linear background based on a scan's end points has been changed. A new macro, based on the new internal data-handling routines and named do_bg, is now provided. See the plot help file for more information.
4. Two arguments to plot_cntl() have been renamed. Use plot_cntl("open") and plot_cntl("close") instead of plot_cntl("openpl") and plot_cntl("closepl"). Also, the arguments to plot_cntl() that specify the graphics terminal type have been eliminated. Instead, a new global variable named GTERM, which can take its value from the environment or be assigned to, is used to specify the graphics device type.
5. The macros named U and P introduced in the last release are now named UN and UP. The name U is now reserved for the array of orientation matrix parameters used with a number of geometry configurations.

USER INTERFACE

The internal data-handling portion of spec has been entirely rewritten, adding greatly to the types of data manipulation that can be done within spec. The data help file explains the new functions. In brief, the internally stored data points are divided into independent groups. Each data point can have several numbers associated with it, such as H, K, L and counts from the detector. In addition a number of functions are provided that allow math operations on all the data points in a group or among groups, and the reading of values into a group from a file.

Data points are now saved in the state files. Thus, when scans are continued after exiting and restarting spec, the entire data set can still be plotted and saved.

The gethelp() function, used by the help macros, now responds to single character commands to page forward and back or quit, instead of waiting for a newline to be typed.

When built-in functions are used with the wrong number of arguments, an error message is now printed that indicates what the correct usage is.

A new built-in macro named cleanup1 will be called on errors or user aborts, if it has been defined. This new macro will be called after the cleanup macro if they are both defined.

The high resolution graphics programs for SunTools and X Windows have been improved. In particular, the X Window filter does a better in loading the correct font. The filter for SunTools has been entirely rewritten.

High resolution screen plots can now show error bars. Error bars are calculated as the square root of the y-data values. Use the setplot macro or call the function plot_cntl("ebars") to turn error-bar drawing mode on.

The colors on high resolution plots on color display devices are now assigned using the plot_cntl() function. Also, use of colors can be turned on or off with the plot_cntl() function. See the funcs help file for details.

Pseudomotors and pseudocounters can now be configured by selecting the controller named NONE. Pseudomotors may be linked to the motions of other motors in the geometry code (see how the alf motor is used in geo_w21h.c for an example.) Otherwise choosing NONE as the controller type lets you execute counting and moving commands without being in simulate mode.

A software timer is now available. Use it by selecting the SFTWARE controller in the configuration file. This timer uses the system clock to gate the scalers, MCAs, etc.

The high-resolution graphics on AT&T System V/386 systems can be displayed on a different virtual terminal then you use for the text. Set GTERM to something like vga_vt07 to use /dev/vt07 as the virtual terminal for graphics. You shouldn't be using the selected virtual terminal for a login session. You will have to use the terminal hot keys to switch back to the text screen in order to type commands to spec.

spec now checks for write errors after most output is sent to the various files and devices. In the event of a write error, spec resets to command level.

MACROS

A new getscan macro lets you read in scan data from an existing data file. With no arguments, you will be prompted for the name of the spec data file, the scan number, and columns for x and y. You can also provide all four values as arguments. Once the data file name and column numbers have been entered, you can subsequently call the macro with just the scan number as a single argument.

A new _scan_time macro prints the estimated counting time for a scan. The macro is called as part of the default scan_head macro. The reintroduced MON_RATE variable is used in the estimate of the scan time if counting to monitor counts. MON_RATE is the average monitor counts per second and is automatically calculated in the count macro. If the global settle-time variable _sleep is nonzero, that time for each point is also included in the estimate.

The scan_on macro that continues aborted scans can now also be invoked using the name resume.

The teramp macro which ramps the temperature controller to a new value has been upgraded. You can now specify an optional third argument, which is the desired controller step size. A small step size will result in shorter intervals between each temperature step. The macro won't let the step size get too small, though, as it insists on at least a 0.2 second interval (actually set by the global variable TERAMP_MIN) between changes, in order to give time to program a slow interface.

The scan macros now assign a value to Y_L which is used as the y-axis label in the plots. In most cases, the assignment is Y_L = cnt_name(DET).

The current scan number is now included on screen plots.

Mesh scans can now do real-time screen plots. The screen plots are erased at the beginning of each row (or is it column?) of the scan.

The macros pts, plot_res, lp_plot and splot now all take one to three optional arguments. The first argument specifies the data group to plot, the second argument specifies the element to use for the x-axis and the third argument specifies the element to use for the y-axis.

A new macro named cplot_plot creates a command file for the C-PLOT program to plot the current data points. The plot is sent to the filter given by the CP_FILTER global variable. Optional arguments specify plot group and x-axis and y-axis elements, as described above.

The analysis results printed at the top of the plots are now defined by the macros splot_res1, splot_res2 and rplot_res. These macros can be redefined to suit a particular experiment.

The colors used by the splot and rplot macros for the various plot elements are contained in the global string variables splot_col and rplot_col, which can be modified to suit individual tastes. See the description of plot_cntl() in the funcs help file and the colors help file.

The lp plots have been moved from macro code to built-in code. If plot_cntl("lp") is called before a call to data_plot(), the plot output will be all printable ASCII with no cursor positioning sequences and formatted for 132 column-wide output.

Counters named "unused" will not be included in the output from the uct, ct and show_cnts macros or in the data files produced by the standard macros.

New standard macros, fon and foff, are provided to turn on and off an arbitrary file. The macros take an argument, which is the name of the file.

To accommodate motor controllers that operate in polled mode, a new macro name move_poll has been placed after the move_em statement in macros such as mv, mvr, br, etc. By default move_poll is defined as a null macro. For polled controllers, it should be defined as waitmove to have the backlash completed before the next prompt.

The warning message in the distributed fourc.src macro file regarding use of the default X-ray wavelength of 1.54 Angstroms has been removed, as it confused certain synchrotron users who have monochromators.

FUNCTIONS

A new form of the input() function lets you check to see if something has been typed at the keyboard without getting stuck waiting for something to be typed. If invoked as input(0), the function will return a null string if nothing has been typed. Otherwise it returns a string consisting of the first character of what was typed.

The syntax of chg_dial() has been expanded to accommodate motor controllers that use home (or origin) switches. The second argument may be one of the strings "home", "home+", "home-", "lim+" or "lim-". With one of the above arguments, the motor indicated by the first argument will move until it hits the home switch or the clockwise or counter-clockwise limit switch. At present, most motor controllers do not implement the home or limit search feature. See the new home and zero macros for a sample implementation.

A new function, fprintf(), has been added. This function works as printf(), but takes an initial string argument that is the name of a file or device. The text is printed only on the named file or device (and log files), unlike printf(), which prints to all turned on files and devices.

A new function, gpib_cntl() has been added. This function sends the GPIB messages GTL, LLO, DCL, SDC and GET to the addressed device. See the gpib or funcs help files for details.

New functions, port_get() and port_put(), are available on PC (AT-type bus) computers to read and write bytes to IO ports. Ports must be first selected in the config file. Ports may be configured read/write or read only.

A new function, split(), can be used to split a string into substrings and assign each substring to an array element. See the funcs help file for usage.

GEOMETRY CODE

The fourc geometry code and macros have been generally fixed up. The sign convention for ALPHA has been changed due to popular demand. Negative two-theta values are now handled correctly when calculating the orientation matrix and reciprocal space positions. The default orientation reflections have been changed to physically reasonable values. Zone mode phi and chi angles are now treated as frozen angles and are saved in the state file, along with the two vectors that define the zone. Cut points are now also saved in the state file. The freeze macro now takes arguments to specify the value(s) of the current mode's frozen angle(s). The two-theta and omega cut points have been eliminated (two theta values will always be between -180 and 180 degrees). New sz, setor0 and setor1 macros let you set the zone plane and the orientation reflections without moving motors.

The portion of the four-circle geometry code in the source file geo_fourc.c that dealt with orientation matrix calculations has been relocated and the orientation matrix code can now be used by any geometry. Also, a new macro file, ub.mac, now contains the orientation-matrix specific macros.

Since the orientation-matrix code has been generalized to work with any geometry, the names used to refer to the primary and secondary reflection angles have been changed to g_u00, g_u01, etc., for the primary reflection, and g_u10, g_u11, etc., for the secondary reflection. New (redundant) macro aliases, tth0, th0, chi0, phi0, tth1, th1, chi1 and phi1, have been created for the primary and secondary orientation reflections in the fourc geometry.

The gpset macro is redefined to include a calcG call for geometries that use an orientation macro. (The calcG call is necessary to have the orientation matrix recalculated.)

A new sectors macro is available with the fourc geometry. The macro prints the motor positions that would be used for all the possible sectors for the (HKL values given as arguments.

A geometry-less version of spec can be installed by choosing the spec geometry target.

A new setrlat macro can be used to set the reciprocal lattice parameters. (The setlat macro sets lattice parameters in direct space.) New macros calcD and calcR calculate direct-space lattice parameters from reciprocal-space lattice parameters and vice-versa.

New geometry code for configurations called w21h and w21v have been added. The code is for a diffractometer used at LURE W21.

New geometry code for a configuration called fivec has been added. The code is for a diffractometer built by MIT and used at NSLS X-20.

New geometry code for a configuration called s2d2 has been added. The code is for a diffractometer built by AT&T Bell Labs and used at NSLS X-16 and X-25.

The MIT surface diffractometer geometry code and macros have been revised to reflect the current diffractometer configuration.

The surf geometry code has been expanded to include a liquid surface diffractometer used at the BNL HFBR.

HARDWARE

On AIX systems, spec enforces a lock on the GPIB device, such that only one process can open it at a time. (On all systems that use a National Instruments GPIB board, only one process should be using the GPIB device at a time.)

The ACS Steppak MCU code has been revised to better handle certain read errors. Also, a motor controller keyword MCU_E is available in the config file to indicate that encoders are being used on a motor. If so indicated, when there are position discrepancies between spec and the controller that are below a threshold amount, the controller's position is automatically taken as correct. In addition, the home and limit search capabilities now available with chg_dial() have been implemented.

The code for the Ortec 9XX counter/timer code has been changed to better detect if the "dwell" switch is set incorrectly.

The Ortec 997 single channel counter is now recognized.

Support for the Oxford Tennelec/Nucleus PCAII MCA PC board is now included. The board supports multichannel scaling and pulse height analysis modes. The macros to use the board are still in an early stage of development.

Support for the Compumotor 3000 motor controller on serial and GPIB interfaces has been added. (There are problems, though, when using this motor controller with the National Instruments GPIB driver on IBM PS/2 AIX 1.2 due to bugs in the GPIB driver and the Compumotor controller.)

Support for the Compumotor 4000 motor controller on serial and GPIB interfaces has been added.

Support for the Microcontrole SIX19 motor controller on a serial interface has been added.

Support for the INEL XRGCI motor controller and timer-counter device has been added.

Support for the Kinetic Systems 2926 IBM PC Interface with 3922 Parallel Bus Crate Controller has been added. The source to the driver is in the file drivers/ksc.c. The script to install the driver is install_ksc.

Support for the Kinetic Systems 3929 SCSI Crate Controller is now supported on Sun Sbus systems. The instructions for installing the driver are in drivers/ksc.README.

Support for the National Instruments GPIB11-2 for the Q-bus is now supported on BSD 4.3 and Ultrix systems.

Support for the National Instruments GPIB-SPARC1-B for Sun computers is now supported.

Code for the Scientific Solutions GPIB board now supports the gpib_poll() and the new gpib_cntl() function.

The code for the LeCroy 2301 MCA has been rewritten to use the new mca_par() and mca_get() functions. See the lc2301 help file for details.

The Nicomp TC-100 autocorrelator is now supported. Access to it is through the mca_par() and mca_get() functions. See the nicomp help file for details.

The Klinger MC-4 motor controller output pins used for gating an external counter and checking for completed moves have been changed from pins 1, 2 and 3 to pins 6, 7 and 8 to avoid conflict with the controller's plug-in remote control device.

UTILITIES

The number-of-columns directive in scans.4 (#N) can now take an optional second argument which is the number of data points per line. The number of numbers per line of data is the product of the two arguments. For example, #N 1 16 would indicate there are 16 data points per line, while #N 4 4 would indicate there are four data points per line, with each data point having four numbers associated with it. In both examples, there would be 16 numbers printed on each line. The purpose of this new feature is to allow representation of MCA data in a visually compact form. (There is no saving in file space, as both a space character and a newline character consume one byte.)

ADMINISTRATION

The edconf program (invoked by the config macro) has had the devices screen split into two screens, one for devices (motors, scalers and MCAs) and one for interfaces (CAMAC, GPIB, serial and I/O ports).

The number of motor controllers and scaler devices allowed has been increased.

Serial devices used with ser_get() and ser_put() can now have raw or cooked line characteristics selected using edconf. In cooked mode, you can also add noflow, igncr, evenp or oddp modes.

The "user can move motor" and "user can change limits" fields displayed by the edconf program have been combined into just one field. Also the number of wizard protection levels has been increased from one to three. Parameters that are protected are now indicated on the motor screen with square brackets.

A facility for sharing a single copy of the config and settings files among several spectrometers that have some motors in common is now available. See the config_adm help file for more information.

New commands to insert i or delete d motors using edconf are available.

When installing spec for the first time, a default config file is created that contains names and mnemonics for all the required geometry motors.

A new administrative utility called tidy_spec is provided to clean out old user state files from the spec auxiliary file directory. Invoked without arguments, the utility prints the disk usage by user, terminal, geometry and age. Arguments are available to remove files by user, terminal, geometry or age. Type tidy_spec - to see usage. When installed by the Install script, the file modes of the program restrict its use to owner and group. The Install script also patches the tidy_spec executable to make the configured auxiliary file directory the default.

The spec.msgs messages file, used in earlier versions to help cope with the limited program size available on the 286 and PDP 11/73 platforms, has been done away with. All currently supported platforms can easily accommodate the extra 30 kilobytes or so of data space that are thus needed by the program.

MISCELLANEOUS

spec is now available for the IBM RS/6000 running the AIX operating system. CAMAC support is currently only through a Kinetic Systems 3988 GPIB-to-CAMAC crate controller.

New startup options, -p and -q, have been added to make spec work as the tail end of a windowing front-end program. The -p option says that input from spec is from a pipe. The -q option can only be used with -p and says that spec should operate quietly and not write messages to the "tty" device unless it is explicitly turned on.

Internal signal handling (signals are associated with typing ^C, with internal timers and with certain hardware controllers) code has been rewritten (again) to make spec more robust.

A number of internal limits have been increased, including the maximum number of bytes of macros, the size of the internal memory arena and the length of strings that can be printed.

BUG FIXES

The showscans program is now automatically patched when it is installed to reflect the correct auxiliary file directory. Previously, the path name /usr/lib/spec.d was built in.

A bug in the scans.4 C-PLOT user function that calculated error bars incorrectly when the #I second normalization was being used has been fixed.

A bug in the motor moving code where, when in simulate mode, simulated motor positions would change when they weren't supposed to has been fixed.

A bug in the powder-mode macros where powder mode would not work properly if the powder-mode motor was not one of the motors involved in the geometry calculations has been fixed.

A bug in the CAMAC TS201 counter/timer code where the variable that kept track of detector overflows never got cleared has been fixed.

Another bug in the CAMAC TS201 counter/timer code where, when counting to certain values of monitor counts, the count time was off by a factor of two or so from what it should be, has been fixed.

A bug in the Oregon Micro Systems PCX code where backlash was done on the wrong motor for certain multi-motor moves has been fixed. Also, several modifications were made to make the code more robust.

A bug in the code for the Ortec 9XX counter/timers where the program would get stuck printing an error message under certain conditions has been fixed.

A bug in the code for the LeCroy 2301 MCA, where channel counts greater than 32,768 were saved as negative numbers, has been fixed.

Bugs in the code for the Scientific Solutions GPIB board that prevented it from working on 386 machines have been fixed.