The SSCAN record v5.16

Author: Tim M. Mooney
Based on the scan record, written by Ned D. Arnold.

Advanced Photon Source

Argonne National Laboratory

1. Introduction

The function of the SSCAN record is to move positioners through a series of positions and record detector data at each of the positions. The whole sequence of operations is referred to as a scan. After parameters defining the scan have been initialized and the scan has been told to start, the SSCAN record begins a possibly long and involved sequence of operations normally without further input, and it notifies any interested clients as the scan progresses, and when the scan is complete. The data are collected into arrays within the record so that they needn't be written point by point by a client.

A single SSCAN record supports a one dimensional scan. Several SSCAN records can be linked together to perform a multi-dimensional scan. Each SSCAN record can control up to four positioners and acquire data from up to 74 process variables (70 detector values of type float and four positioner readbacks of type double) during a scan. Four additional output variables can be defined to write to other process variables (usually detectors, and usually to cause them to begin acquiring data) between the positioning phase and the data acquisition phase. These outputs are called detector triggers.

Typically, the SSCAN record moves motors and records scaler data at each motor position, but obviously it can also be used for other purposes. Any controllable device can be scanned through a set of values while data are recorded from any other process variables. For example, one of the positioner process variables could be used to vary the gain of a detector during a scan. Therefore, throughout this document the term positioner should be taken to mean "any PV to which you can write a number". Similarly, the term detector trigger typically refers to a PV that will cause data acquisition to begin when it is written to, but could be taken to mean any PV to which you can write a number. Finally, the term detector refers to any readable numeric PV.

All of the process variable names used to identify positioners, detectors, and detector triggers are specified using reassignable links. This allows a scan to be configured on the fly.

1.1. A Simple One Dimensional Scan

In the simplest complete configuration for a one dimensional scan, one positioner PV name is specified in P1PV, the list of positions to visit is constructed by selecting the scan mode "LINEAR" (P1SM), specifying start and end positions (P1SP and P1EP), specifying whether positioner values are to be interpreted as absolute or as relative to before-scan values (P1AR), and specifying the number of positions to visit (NPTS); one detector-trigger PV name is specified in T1PV, and the value to be written to this PV is specified in T1CD; and one detector (signal) PV name is specified in D01PV. When you start a scan (by writing a "1" to the EXSC field) the SSCAN record commands the positioner to move to its starting position. The SSCAN record uses recDynLinkPutCallback() (a routine in the library recDynLink.c, which normally is distributed along with the SSCAN record) to tell the positioner to move, and waits for the resulting callback before moving on to the next step of the scan, which is to trigger the detector. The detector is also triggered using a recDynLinkPutCallback() call, and the SSCAN record waits for it to finish before going on to the next data point. This will continue until the SSCAN record has completed NPTS steps. At the end of the scan, the SSCAN record has filled in an array of the positions visited (P1RA), and an array of detector values acquired (D01DA).

1.2. Multidimensional Scans

Multidimensional scans are easy: the outer SSCAN record (which we'll call "scan2") regards the inner SSCAN record ("scan1") as a detector to be triggered, and each SSCAN record acquires its own data. Thus, scan2.T1PV is set to scan1EXSC, and scan2.T1CD is set to 1. In words, scan2 writes a "1" to the "execute scan" field (EXSC) of scan1.

To initiate a scan, the scan2 record is commanded to begin (scan2.EXSC is set to "1".) scan2 then commands its positioners to their previously specified starting points, and waits for their callbacks. Then scan2 writes to its Detector Trigger, which in this case causes scan1 to begin its own scan. The scan1 record will now go through its entire programmed scan, acquiring data from its detectors at each point.

When the scan1 record is finished, its callback causes scan2 to continue in its scan procedure -- reading detector values, moving positioners to new positions, and causing scan1 to execute again.

This approach to configuring multidimensional scan is very flexible. Note that scan1 can be executed independently of scan2, so a complex multidimensional scan can be built and tested one dimension at a time.

1.3. Client-server Handshaking in Multidimensional Scans

An outer SSCAN record involved in a multidimensional scan doesn't know or care that the "detector" it's triggering is actually another SSCAN record, which is going to do an entire inner scan; the outer SSCAN record simply triggers what it regards as a detector, and waits for that detector to complete. Nor do the inner SSCAN records know that they are parts of something larger than themselves. The only piece of code that has to know a multidimensional scan is occurring is the client that stores the data. This client must collect all of the data from each inner scan before those data are overwritten by the next execution of that inner scan, because SSCAN records store only one-dimensional arrays of data. Clearly, this calls for some handshaking between the client and the SSCAN records involved in a multidimensional scan. The SSCAN record provides two ways to do this:

1) The client notices that an inner SSCAN record has started a scan, and writes a "1" to the outer SSCAN record's WAIT field. This prevents the outer SSCAN record from continuing until the client has read the inner scan's data. When the client has finished reading the inner scan's data, it writes a "0" to the outer SSCAN record's WAIT field, allowing the scan to continue. If there are several clients that want the scan to WAIT for them, they can all write to the WAIT field. Each "1" increments the scan's wait-count WCNT ; each "0" decrements it. When WCNT reaches zero, the scan continues.

2) In very fast scans, there might not be time for a client to notice that an inner scan has started and write that "1" to the outer scan's WAIT field before the inner scan completes and is triggered again. In this case, the outer scan can be made automatically to write a "1" to it's own WAIT field whenever it triggers detectors. It will do this if its autoWaitCount (AWCT) field is set to "1". In this case, the client must NOT write another "1" to the outer scan's WAIT field, but must only write "0" to the WAIT field to indicate that it is ready for the scan to continue. If there are N clients, the autoWaitCount can be set to N, and the scan will continue only after N "0"s have been written to the WAIT field. The advantage of method (1) is that scans can be performed whether or not a client is available to write to the WAIT field. The disadvantage is that the method 1 handshake is not reliable for fast scans. The advantage of method (2) is that it absolutely guarantees the handshake will succeed, no matter how fast the scan goes. The disadvantage is that a client must be available to write "0" to the WAIT field.

1.4. Completion of positioner and detector-trigger operations

As was mentioned previously, all of the process variable names used to identify positioners, detectors, and detector triggers are specified using reassignable links. These links are implemented differently than standard EPICS links (e.g., the output link of an analog output record). SSCAN-record links are channel-access links implemented with the recDynLink library (originally written by Marty Kraimer and Ned Arnold, modified to use callbacks and currently maintained by Tim Mooney). These links perform writes with the channel-access function, ca_put_callback(), and expect the callback function to be called only after all processing caused by the write operation is complete. For simple positioners and detectors, this is never a problem. Inidividual records using either synchronous or asynchronous completion strategies (as these terms are defined in the EPICS Application Developer's Guide) always satisfy the completion-callback criterion. Special records (MOTOR, SCALER, MCA, and SSCAN record) which do not use either synchronous or asynchronous strategies have been engineered to satisfy the completion-callback criterion simply by having them refrain from calling recGblFwdLink() (i.e., from firing their Forward Links) until the operation they started has finished.

If a positioner or detector is implemented with a collection of linked records all of which individually satisfy the completion-callback criterion, the whole series of records will also satisfy the criterion if all links in the processing chain started by the sscan record's write have the attribute PP, and all of the records that process are scan-passive (i.e., their .SCAN fields are set to "Passive"). Databases that do not satisfy this criterion can still satisfy the completion-callback criterion very simply: at least one record in the database must refrain from firing its Forward Link until the operation is finished, and that record must be either be the record written to, or it must be linked with attribute PP to the record. The BUSY record was implemented for this purpose. Using the BUSY record, any sort of processing, even processing that involves an external, non-EPICS processor can esily satisfy the completion-callback criterion.

Database developers should note that a PP link from a record in one crate to a record in another crate will silently be converted to a CA link, which will not satisfy the completion-callback criterion. In this case, there are two options: the BUSY-record solution, and using either the SSCAN record or the SWAIT record to make the inter-crate link. (The SWAIT record is a variant of the EPICS WAIT record that uses ca_put_callback() to implement its output link, just as the SSCAN record does.) Because only these two record types request and wait for completion callbacks from records they write to, only they can send scan commands to another crate.

2. Scan Parameters

Many options are available to control the execution of a scan. All parameters for a particular SSCAN record must be configured prior to initiating the scan, as the SSCAN record will not allow most fields to be written to while a scan is in progress. However, in a multidimensional scan, outer scans can modify the parameters of inner scans, because at the time an outer SSCAN record is writing to positioners, all inner SSCAN records are idle. You should use caution in programming such self modifying scans, because clients displaying and storing multidimensional-scan data may have trouble dealing with parameters changing during a scan. In this documentation, many of the SSCAN-record PV's will be listed in tables containing the following informational headings:

Field: The name of the SSCAN-record field
Summary: Basic purpose of the field
Type: Data type of the field. If the field is a menu, the menu choices (text strings) are listed in quotes. (Don't include the quotes when you write to the field.) Note that if you write a numeric value to a menu field, the number will be interpreted as an index into the list of menu choices. The first item in the list has the index 0.
DCT: Can this field be modified by database-configuration tools?
Initial/Default: Value if the field is not specified in the .db file. If the field is a menu, the text string will be shown, followed by the corresponding index.
Read: Can user read this field?
Modify: Is user ever allowed to write to this field? (Note that the SSCAN record will reject writes to certain otherwise writable fields while a scan is underway.)
Posted: If the record should modify the field, will the new value be posted?
PP: Does a channel-access write to this field cause the record to process?

2.0. Global Parameters

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
`NPTS`	Number of Points	SHORT	Yes	100	Yes	Yes	Yes	No
`MPTS`	Maximum Number of Points	SHORT	Yes	100	Yes	No	No	No
`PASM`	Positioner After-Scan Mode	Menu ("STAY", "START POS", "PRIOR POS", "PEAK POS", "VALLEY POS", "+EDGE POS", "-EDGE POS")	Yes	"STAY" (0)	Yes	No	No	No
PASM allows the user to control where positioners are left after a scan is finished. Here are the possibilities: "STAY" Do nothing. Leave positioners where they were when the last data point was acquired. "START POS" Go the the position of the first data point acquired. "PRIOR POS" Go to the position they occupied prior to the scan. "PEAK POS" Attempt to find the highest point in the data from the detector specified by the REFD field. If a highest point is found, go to its position, else "STAY". "VALLEY POS" Attempt to find the lowest point in the data from the detector specified by the REFD field. If a lowest point is found, go to its position, else "STAY". "+EDGE POS" Take the derivative of the REFD data, then do "PEAK POS". "-EDGE POS" Take the derivative of the REFD data, then do "VALLEY POS".
`REFD`	Reference detector for After-Scan mode	SHORT	Yes	1	Yes	Yes	No	No
`BSPV`	Before-Scan Process Variable link	STRING [40]	Yes	Null	Yes	Yes	No	No
`BSNV`	BSPV Name Valid	LONG	No	0	Yes	No	Yes	No
`BSCD`	Before-Scan Command Data	FLOAT	Yes	1	Yes	Yes	No	No
`ASPV`	After-Scan Process Variable link	STRING [40]	Yes	Null	Yes	Yes	No	No
`ASNV`	ASPV Name Valid	LONG	No	0	Yes	No	Yes	No
`ASCD`	After-Scan Command Data	FLOAT	Yes	1	Yes	Yes	No	No

2.1. Positioner Parameters

Each SSCAN record may control up to four positioners that are commanded to a new desired position after collecting data at each point. The positioners are defined by typing in an ASCII string that represents the process variable name of the positioner.

There are three modes for determining the desired value for the positioner. The desired mode is specified in the P1SM-P4SM fields: Linear, Table, and On-The-Fly. If a positioner is specified as Linear, its desired value is determined by using parameters such as start position, step increment, number of points, and end position (which are explained below). If a positioner is specified as Table, its next position is found in an array that has been loaded into the record prior to initiating a scan. If the positioner is specified as On-The-Fly, the SSCAN record sends it to the start position at the beginning of a scan, waits for it to get there, acquires one data point, sends the positioner to the end position, and begins acquiring the remaining data points while the positioner presumably is travelling to the end position.

Currently, the SSCAN record does not wait for an On-The-Fly positioner to arrive at the end point. Ideally, the SSCAN record should finish the data-acquisition portion of a scan but not enter the post-scan phase (sending positioners to after-scan positions, and executing the after-scan link) until the positioner has declared itself done. But this is not what is done.

For n in [1..4]:

Field Summary Type DCT Initial/Default Read Modify Posted PP

PnPV Positioner n Process Variable ame STRING [40] Yes Null Yes Yes No No

PnNV PnPV Name Valid LONG No 0 Yes Yes Yes No

PnSM Positioner n Step Mode Menu ("LINEAR", "TABLE", "FLY") Yes "LINEAR" (0) Yes Yes No No

PnAR Positioner n Absolute/Relative Mode Menu ("ABSOLUTE", "RELATIVE") Yes "ABSOLUTE" (0) Yes Yes No No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
`PnPV`	Positioner n Process Variable ame	STRING [40]	Yes	Null	Yes	Yes	No	No
`PnNV`	PnPV Name Valid	LONG	No	0	Yes	Yes	Yes	No
`PnSM`	Positioner n Step Mode	Menu ("LINEAR", "TABLE", "FLY")	Yes	"LINEAR" (0)	Yes	Yes	No	No
`PnAR`	Positioner n Absolute/Relative Mode	Menu ("ABSOLUTE", "RELATIVE")	Yes	"ABSOLUTE" (0)	Yes	Yes	No	No

2.2. Linear Mode

If a positioner's step mode field (P1SM) specifies Linear, a scan can be fully defined by three parameters, e.g., the start position (P1SP), the step increment (P1SI ), and the number of data points (NPTS). A scan involving N positioners is defined by merely 2N+1 parameters, since NPTS applies to all positioners. For the convenience of interactive users, and to support channel access clients that define scans differently, the first positioner can be specified by as many as six parameters: starting position (P1SP), ending position (P1EP), center position (P1CP ), scan width (P1WD ), step increments (P1SP), and NPTS. For the other three positioners, the same parameters are available minus the NPTS field, since that applies to all. The parameters that pertain to the same positioner are a set. The record imposes an upper limit (MPTS) on NPTS. Both MPTS and NPTS are configured by the user. The positioner width, configurable in the P1WD -P4WD fields, may be negative.

For n in [1..4]:

Field Summary Type DCT Initial/Default Read Modify Posted PP

PnSP Positioner n Starting Point DOUBLE Yes 0 Yes Yes Yes No

PnEP Positioner n Ending Point DOUBLE Yes 0 Yes Yes Yes No

PnCP Positioner n Center Point DOUBLE Yes 0 Yes Yes Yes No

PnWD Positioner n Width DOUBLE Yes 0 Yes Yes Yes No

PnSI Positioner n Step Increment DOUBLE Yes 0 Yes Yes Yes No

Field	Summary	Type	DCT	Read	Modify	Posted	PP
`PnSP`	Positioner n Starting Point	DOUBLE	Yes	Yes	Yes	Yes	No
`PnEP`	Positioner n Ending Point	DOUBLE	Yes	Yes	Yes	Yes	No
`PnCP`	Positioner n Center Point	DOUBLE	Yes	Yes	Yes	Yes	No
`PnWD`	Positioner n Width	DOUBLE	Yes	Yes	Yes	Yes	No
`PnSI`	Positioner n Step Increment	DOUBLE	Yes	Yes	Yes	Yes	No

Some of these fields can be redundant. For instance, the positioner width (P1WD -P4WD ) is simply the distance from the starting position to the ending position (PnEP - PnSP ). The record calculates redundant parameters for the same set, if the parameters are left undefined. However, the user can still configure the redundant parameters anyway.

There is no unique prescription for removing inconsistencies among redundant parameters, and no hard-coded set of preferences among parameters is likely to please everyone. Therefore, the SSCAN record allows the user to "freeze" parameters with flags so that they will not be changed by the record's internal attempts to ensure consistency among the parameter set. Frozen parameters can be changed by the user and by any other client, but not by the record. It is the user's responsibility to ensure that frozen parameters do not prevent freely specifying unfrozen parameters. For example, if both PnSI and NPTS are frozen, changes to PnWD will be rejected. Similarly, if both PnSP and PnCP are frozen, changes to PnEP and PnWD will have no effect. By default, PnSP , PnSI , and NPTS are frozen. When the record cannot adjust the parameters to be consistent, a flag is raised in the alert field (ALRT) and a message reported in the state message field (SMSG).

The freeze flag override field (FFO ) has two choices: Use F-Flags and Override. Override causes the current settings of all the freeze flags to be saved and monitors to be called for those that have changed. Use F-Flags causes the flags saved with the Override command to be restored if any have changed. Changing the choice of this field at run-time causes the special record support routines to perform these actions. So if Override is chosen at run-time, then all current settings are saved, and can be restored at a later time by changing the FFO field to Use F-Flags.

For n in [1..4]:

Field Summary Type DCT Initial/Default Read Modify Posted PP

FPTS Freeze Flag for NPTS Menu ("NO", "FREEZE") Yes "FREEZE" (1) Yes Yes No No

FFO Freeze Flag Override Menu ("USE F-FLAGS", "OVERRIDE") Yes "USE F-FLAGS" (0) Yes Yes No No

PnFS Positioner n Freeze Flag for PnSP Menu ("NO", "FREEZE") Yes "NO" (0) Yes Yes No No

PnFE Positioner n Freeze Flag for PnEP Menu ("NO", "FREEZE") Yes "NO" (0) Yes Yes No No

PnFI Positioner n Freeze Flag for PnSI Menu ("NO", "FREEZE") Yes "NO" (0) Yes Yes No No

PnFC Positioner n Freeze Flag for PnCP Menu ("NO", "FREEZE") Yes "NO" (0) Yes Yes No No

PnFW Positioner n Freeze Flag for PnWD Menu ("NO", "FREEZE") Yes "NO" (0) Yes Yes No No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
`FPTS`	Freeze Flag for `NPTS`	Menu ("NO", "FREEZE")	Yes	"FREEZE" (1)	Yes	Yes	No	No
`FFO`	Freeze Flag Override	Menu ("USE F-FLAGS", "OVERRIDE")	Yes	"USE F-FLAGS" (0)	Yes	Yes	No	No
`PnFS`	Positioner n Freeze Flag for `PnSP`	Menu ("NO", "FREEZE")	Yes	"NO" (0)	Yes	Yes	No	No
`PnFE`	Positioner n Freeze Flag for `PnEP`	Menu ("NO", "FREEZE")	Yes	"NO" (0)	Yes	Yes	No	No
`PnFI`	Positioner n Freeze Flag for `PnSI`	Menu ("NO", "FREEZE")	Yes	"NO" (0)	Yes	Yes	No	No
`PnFC`	Positioner n Freeze Flag for `PnCP`	Menu ("NO", "FREEZE")	Yes	"NO" (0)	Yes	Yes	No	No
`PnFW`	Positioner n Freeze Flag for `PnWD`	Menu ("NO", "FREEZE")	Yes	"NO" (0)	Yes	Yes	No	No

Although this approach may seem to present the user with an overwhelming number of choices when it comes to linear scans, it should be noted that by default the user only has to configure NPTS, and the starting position (PnSP) and the step increment (PnSI) fields for each positioner in order to fully define the scan of a positioner. The operator interface (usually DM, medm or another CA client) need only present the user with these fields. However, by changing the freeze flags from the defaults and presenting the user with different fields to fill in, the scan can be defined in a completely flexible way. The result is that a simple scan can be defined easily, but advanced users are not limited in flexibility.

2.3. Table Mode

In Table mode, the user provides the values for the PnPA arrays prior to the start of a scan. These arrays are used only in Table mode.

For n in [1..4]:

Field Summary Type DCT Initial/Default Read Modify Posted PP

PnPA Positioner n Position Array DOUBLE array No Null Yes Yes Yes No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
`PnPA`	Positioner n Position Array	DOUBLE array	No	Null	Yes	Yes	Yes	No

2.4. Position Verification, Readback Process Variable, and Delta Parameters

For each positioner, the user may specify a process variable in the R1PV -R4PV fields that corresponds to the actual (or measured) position of the motor. If this readback field is configured, the SSCAN record will confirm after each movement that the actual position is within a specified delta to the desired position. The delta is specified in the R1DL -R4DL fields. If the delta is exceeded, the scan will abort and the record will go into an alarm state. A text field within the record (SMSG) will inform the operator of the error condition.

For n in [1..4]:

Field Summary Type DCT Initial/Default Read Modify Posted PP

RnPV Readback n Process Variable STRING [40] Yes Null Yes Yes No No

RnNV Readback /n Name Valid LONG No 0 Yes Yes Yes No

RnDL Readback n Delta DOUBLE Yes 0 Yes Yes No No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
`RnPV`	Readback n Process Variable	STRING [40]	Yes	Null	Yes	Yes	No	No
`RnNV`	Readback /n Name Valid	LONG	No	0	Yes	Yes	Yes	No
`RnDL`	Readback n Delta	DOUBLE	Yes	0	Yes	Yes	No	No

2.5. Detector Trigger Process Variables and Command data

If valid process variable names are entered into the detector trigger fields (T1PV-T4PV ) fields, the SSCAN record will write the specified command data (the floating point numbers T1CD-T4CD ) to those process variables between the positioning phase and the data acquisition phase. If no detector trigger field contains a valid PV, the SSCAN record will skip this step and acquire the data immediately.

For n in [1..4]:

Field Summary Type DCT Initial/Default Read Modify Posted PP

TnPV Detector Trigger n Process Variable STRING [40] Yes Null Yes Yes No No

TnNV Trigger n Name Valid LONG No 0 Yes Yes Yes No

TnCD Trigger n Command Data FLOAT Yes 1 Yes Yes No No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
`TnPV`	Detector Trigger n Process Variable	STRING [40]	Yes	Null	Yes	Yes	No	No
`TnNV`	Trigger n Name Valid	LONG	No	0	Yes	Yes	Yes	No
`TnCD`	Trigger n Command Data	FLOAT	Yes	1	Yes	Yes	No	No

2.6. Delay variables

Generally, after the SSCAN record has written to positioners and waited for all positioners to declare themselves done, it waits an additional settling time, specified in seconds by the PDLY field, before entering the next scan phase. Similarly, after detector triggers have declared themselves done, the SSCAN record waits for DDLY seconds before reading positioner and detector data. If no positioners are defined, then PDLY is ignored. If no detector triggers are defined, then DDLY is ignored. PDLY does not apply to after-scan positioner motions.

2.7. Client handshaking variables

Immediately before data are to be read from positioners and detectors, the SSCAN record checks the WCNT field. If this field is nonzero, the SSCAN record waits until it gets set to zero before reading data and continuing with the scan. The WCNT is not directly writable by clients. Instead, a client wanting to put a hold on the scan writes a "1" to the WAIT field, which increments WCNT by one. When the client is ready for the scan to continue, it writes a "0" to the WAIT field, which decrements the WCNT field. This mechanism allows several clients independently to handshake with the SSCAN record, and it is intended or two purposes:

1) In a multidimensional scan, a data-storage client can put a hold on scan2 while it is writing data from scan1.

2) A data-acquisition client that can't or doesn't want to declare completion via EPICS' putNotify mechanism can declare completion using WAIT.

A client may not be able to write quickly enough to WCNT to ensure that the scan holds before data acquisition. In this case, the client can cause the SSCAN record to write automatically to WCNT whenever detectors are triggered, by incrementing the value of the AWCT field. The client must remember to decrement AWCT before exiting, otherwise scans will hang waiting for a nonexistent client.

Field Summary Type DCT Initial Read Modify Posted PP

WAIT Wait for client SHORT No 0 Yes Yes No No

WCNT Wait count SHORT No 0 Yes No Yes No

AWCT Auto Wait SHORT No 0 Yes Yes No No

WTNG Waiting SHORT No 0 Yes No Yes No

Field	Summary	Type	DCT	Read	Modify	Posted	PP
`WAIT`	Wait for client	SHORT	No	Yes	Yes	No	No
`WCNT`	Wait count	SHORT	No	Yes	No	Yes	No
`AWCT`	Auto Wait	SHORT	No	Yes	Yes	No	No
`WTNG`	Waiting	SHORT	No	Yes	No	Yes	No

3. Data Acquisition Parameters

Each SSCAN record can acquire data from up to 89 process variables (70 detector signals D01-D70; 15 additional detector signals, D1-DF, which are supported only for backward compatibility with previous versions of the record; and four positioner readbacks, R1-R4) at each point in the scan. These data will most commonly be from a detector or from a position readback (which would record the actual motor positions at each point and could then be compared to the desired position array). Although positioner readbacks are normally used to confirm the position at which data actually were acquired (as opposed to the position to which the SSCAN record told a positioner to go), they can be used to record any data. These four variables are the only place to record double-precision scan data.

The scan results will most frequently be read as position arrays (P1RA-P4RA ), which are mentioned above, and arrays of detector data (D01DA-D70DA, D1DA-DFDA) where each detector data element corresponds to the position element. For backward compatibility with previous versions of the SSCAN and scan records, the SSCAN record maintains 15 detectors D1 through DF. These fields are expected to go away someday.

A one-dimensional scan is complete when the BUSY field goes back to zero (during the scan its value is 1). A client program monitoring the scan can read the position and data arrays when the DATA field is set to 1. (The client could have a monitor set on the data-array fields so the record will post them when the scan is finished.)

For two-dimensional scans, the client should read the arrays from the scan1 record after the completion of each inner scan and associate these data with the current outer-scan information. (Let's call the inner scan 'x', and the outer scan 'y'.) This will allow the client to display data after each x scan. The SSCAN record will buffer the data for only one x scan, so the client must read the arrays before the next x scan is completed. If the scan is too fast for this, the application program can write a 1 to the WAIT field of the scan2 record when the x scan starts. This will cause scan2 to WAIT for the client before triggering the next x scan. The client shows that it's ready for the new scan by writing a 0 to scan2's WAIT field. If scans are too fast even for this, you can arrange for scan2 to set its own WAIT field for you whenever it starts an x scan. You can do this by setting scan2's AWCT (auto-wait count) to 1. If you have done this, you must write a 0 to scan2's WAIT field after every x scan, because the scan will WAIT indefinitely or this to occur. You can see whether scan2 is waiting for a client by looking at its WCNT field.

On slow scans, the application program may want to see that the scan is processed on a point by point basis. Therefore, the SSCAN record will post monitors on fields that it updates each point, but it will not post monitors faster than 20 times per second. If a scan is proceeding at a rate less than 20 points per second, every point will be posted. If a scan is proceeding at 100 steps per second, scalar values will be posted every 5th point (approx.). In either case, the array data will contain every point at the completion of the scan. It is not recommended that a client use the point to point data except for keeping the operator aware of the progress of the scan.

Special Acquisition Parameters:

Field Summary Type DCT Initial/Default Read Modify Posted PP

version 5.16 and earlier:

ACQM Acquisition Mode Menu ("NORMAL", "ACCUMULATE", "ADD TO PREV", "GET ARRAYS") Yes "NORMAL" (0) Yes Yes No No

version 5.17 and later:

ACQM Acquisition Mode Menu ("NORMAL", "ACCUMULATE", "ADD TO PREV") Yes "NORMAL" (0) Yes Yes No No

ACQT Acquisition Type Menu ("SCALAR", "1D ARRAY") Yes "SCALAR" (0) Yes Yes No No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
version 5.16 and earlier:
`ACQM`	Acquisition Mode	Menu ("NORMAL", "ACCUMULATE", "ADD TO PREV", "GET ARRAYS")	Yes	"NORMAL" (0)	Yes	Yes	No	No
version 5.17 and later:
`ACQM`	Acquisition Mode	Menu ("NORMAL", "ACCUMULATE", "ADD TO PREV")	Yes	"NORMAL" (0)	Yes	Yes	No	No
`ACQT`	Acquisition Type	Menu ("SCALAR", "1D ARRAY")	Yes	"SCALAR" (0)	Yes	Yes	No	No

Data and Execution Flags:

Field Summary Type DCT Initial/Default Read Modify Posted PP

For nn in [01..70] (e.g., "D01PV", "D02PV", ... "D70PV") :

DnnPV data nn Process Variable name STRING [40] Yes Null Yes Yes No No

DnnNV data nn Name Valid LONG No 0 Yes Yes Yes No

DnnDA Detector nn data Array FLOAT[ ] No Null Yes No Yes No

EXSC Execute Scan Flag SHORT No 0 Yes Yes Yes No

XSC Internal copy of EXSC SHORT No 0 Yes No Yes No

BUSY Scan-is-busy Flag SHORT No 0 Yes No Yes No

DATA Data-are-ready flag SHORT No 0 Yes No Yes No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
For nn in [01..70] (e.g., "D01PV", "D02PV", ... "D70PV") :
`DnnPV`	data nn Process Variable name	STRING [40]	Yes	Null	Yes	Yes	No	No
`DnnNV`	data nn Name Valid	LONG	No	0	Yes	Yes	Yes	No
`DnnDA`	Detector nn data Array	FLOAT[ ]	No	Null	Yes	No	Yes	No
`EXSC`	Execute Scan Flag	SHORT	No	0	Yes	Yes	Yes	No
`XSC`	Internal copy of `EXSC`	SHORT	No	0	Yes	No	Yes	No
`BUSY`	Scan-is-busy Flag	SHORT	No	0	Yes	No	Yes	No
`DATA`	Data-are-ready flag	SHORT	No	0	Yes	No	Yes	No

4. Operator Display Parameters

Prior to beginning an actual scan, the record can be commanded to check the scan parameters to ensure that all positioner requests are within reasonable limits. This is done by writing "1" to the CMND field. The record will do a "dry run" by calculating every positioner value (or looking it up in the table) and comparing it with the high range and low range values (P1HR-P4HR and P1LR-P4LR) associated with that positioner's Process Variable. (Drive limits are an attribute of most process variables). If any step would exceed the drive limits, the operator is notified via the SMSG field.

Other than that, the High Range and Low Range value fields are only used as the display limits for an operator interface. The same is true for the rest of these fields, which are configured to affect the information displayed to the operator. Each positioner and the detector for each positioner have the following fields:

An Engineering Units Field (P1EU-P4EU, D01EU-D70EU), which has a string that is given to it by the user.
A Precision Field (P1PR-P4PR, D01PR-D70PR), which holds an integer that controls the decimal precision that the corresponding field is displayed with. For instance, P1PR controls the decimal precision for positioner 1 array elements.

See the EPICS Record Reference Manual for more on the record name (NAME) and description (DESC) fields.

Field Summary Type DCT Initial/Default Read Modify Posted PP

For n in [1..4]:

PnEU Positioner n Eng. Units STRING [16] Yes 16 Yes Yes No No

PnHR Pos. n High Range DOUBLE Yes 0 Yes Yes No No

PnLR Pos. n Low Range DOUBLE Yes 0 Yes Yes No No

PnPR Pos. n Precision SHORT Yes 0 Yes Yes No No

For nn in [01..70]:

DnnEU Detector nn Eng. Units STRING [16] Yes 16 Yes Yes No No

DnnHR Det. nn High Range DOUBLE Yes 0 Yes Yes No No

DnnLR Det. nn Low Range DOUBLE Yes 0 Yes Yes No No

DnnPR Det. nn Precision SHORT Yes 0 Yes Yes No No

NAME Record Name STRING [29] Yes 0 Yes No No No

DESC Description STRING [29] Yes Null Yes Yes No No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
For n in [1..4]:
`PnEU`	Positioner n Eng. Units	STRING [16]	Yes	16	Yes	Yes	No	No
`PnHR`	Pos. n High Range	DOUBLE	Yes	0	Yes	Yes	No	No
`PnLR`	Pos. n Low Range	DOUBLE	Yes	0	Yes	Yes	No	No
`PnPR`	Pos. n Precision	SHORT	Yes	0	Yes	Yes	No	No
For nn in [01..70]:
`DnnEU`	Detector nn Eng. Units	STRING [16]	Yes	16	Yes	Yes	No	No
`DnnHR`	Det. nn High Range	DOUBLE	Yes	0	Yes	Yes	No	No
`DnnLR`	Det. nn Low Range	DOUBLE	Yes	0	Yes	Yes	No	No
`DnnPR`	Det. nn Precision	SHORT	Yes	0	Yes	Yes	No	No
`NAME`	Record Name	STRING [29]	Yes	0	Yes	No	No	No
`DESC`	Description	STRING [29]	Yes	Null	Yes	Yes	No	No

5. Run-time Parameters

These fields are used to process the record, to implement monitors for certain fields, and/or to keep track of data for processing and/or for the operator. None of these fields are configurable by a database configuration tool. Most of them can be accessed at run-time, and many can be modified at run-time.

The Code Version (VERS) field reflects the version of SSCAN record processing routines.

The VAL field is not used.

The State Message (SMSG) field holds a message sent by the record that alerts the operator to an error condition. It can be cleared by writing a 0 to the Command (CMND) field.

The Alert (ALRT) field is a flag which indicates if an error condition currently exists. 1 means YES; 0, NO. The cause of the condition will be displayed in the SMSG field.

The scan-phase (FAZE) field indicates in which phase of a scan the record currently is. The possible phases are as follows:

phase message meaning

0 IDLE Nothing is going on.

1 INIT_SCAN A scan is starting

2 DO:BEFORE_SCAN The next thing to do is trigger the before-scan link.

3 WAIT:BEFORE_SCAN The before-scan link has been triggered. We're waiting for its callback to come in.

4 MOVE_MOTORS The next thing to do is to write to positioners.

5 WAIT:MOTORS We've told motors to move. Now we're waiting for their callbacks to come in.

6 TRIG_DETECTORS The next thing to do is to trigger detectors.

7 WAIT:DETECTORS We've triggered detectors. Now we're waiting for their callbacks to come in.

8 START_FLY This is an on-the-fly scan

9 RETRACE_MOVE The next thing to do it send positioners to their post-scan positions.

10 WAIT:RETRACE We've told positioners to go to their post-scan positions. Now we're waiting for their callbacks to come in.

11 DO:AFTER_SCAN The next thing to do is trigger the after-scan link.

12 WAIT:AFTER_SCAN The after-scan link has been triggered. We're waiting for its callback to come in.

13 SCAN_DONE The scan in finished.

14 PREVIEW We're doing a preview of the scan.

15 SCAN_PENDING A scan has been commanded, but has not yet started

phase	message	meaning
0	IDLE	Nothing is going on.
1	INIT_SCAN	A scan is starting
2	DO:BEFORE_SCAN	The next thing to do is trigger the before-scan link.
3	WAIT:BEFORE_SCAN	The before-scan link has been triggered. We're waiting for its callback to come in.
4	MOVE_MOTORS	The next thing to do is to write to positioners.
5	WAIT:MOTORS	We've told motors to move. Now we're waiting for their callbacks to come in.
6	TRIG_DETECTORS	The next thing to do is to trigger detectors.
7	WAIT:DETECTORS	We've triggered detectors. Now we're waiting for their callbacks to come in.
8	START_FLY	This is an on-the-fly scan
9	RETRACE_MOVE	The next thing to do it send positioners to their post-scan positions.
10	WAIT:RETRACE	We've told positioners to go to their post-scan positions. Now we're waiting for their callbacks to come in.
11	DO:AFTER_SCAN	The next thing to do is trigger the after-scan link.
12	WAIT:AFTER_SCAN	The after-scan link has been triggered. We're waiting for its callback to come in.
13	SCAN_DONE	The scan in finished.
14	PREVIEW	We're doing a preview of the scan.
15	SCAN_PENDING	A scan has been commanded, but has not yet started

The CMND field supports six commands, as follows:

CMND Command
0 Clear the State Message field (SMSG)

1 Execute a "dry run", checking the desired position against the range limits for each positioner

2 Check to see if limits would be violated if the currently programmed scan were actually performed

3 Clear all PV's, freeze flags, modes, switches, etc.

4 Clear all positioner-related PV's, freeze flags, modes, and switches.

5 Clear positioner-name PV's.

`CMND`	Command
0	Clear the State Message field (`SMSG`)
1	Execute a "dry run", checking the desired position against the range limits for each positioner
2	Check to see if limits would be violated if the currently programmed scan were actually performed
3	Clear all PV's, freeze flags, modes, switches, etc.
4	Clear all positioner-related PV's, freeze flags, modes, and switches.
5	Clear positioner-name PV's.

The Current Point (CPT) field contains the current point of an active scan. The Desired Value fields for each positioner (P1DV-P4DV) contain the desired value of each positioner for the current point (CPT) in the scan. The Readback Current Value (R1CV-R4CV) fields contain the current readback value for each positioner. The Detector Current Value (D01CV-D70CV) contain each detector's current value for the current point in the scan. The event posting for these fields is throttled to 20 Hz, so for fast scans not every value will be posted.

The PCPT, PXSC, P1LV-P4LV, R1LV-R4LV, and D01LV-D70LV fields all contain the previous or "last" value for their corresponding fields. For instance, the R1LV field contains the last value for the R1CV field. These fields are used to implement monitors for the corresponding field. For instance, if CPT does not equal PCPT when the record is processed, then monitors are triggered for CPT.

The Name Valid fields (xxNV) are flag fields which indicate if the corresponding process variable field contains an existing process variable. For instance, the P1NV field indicates whether the P1PV field contains a valid process-variable name; the R4NV field indicates whether R4PV contains a valid PV name, and so on. If a positioner's PV name field is blank, all other fields associated with that positioner are ignored. If a PV name field is not empty, but consists purely of "whitespace" characters (blanks or tabs, say) then the SSCAN record will silently set the PV name field to the empty string.

The database Address fields (xxDB) are of normally of interest only to the record itself, and are not even accessible at run-time. They contain pointers to the dbAddr structures of the corresponding process variables. For instance, P1DB points to the dbAddr structure of P1PV.

Field Summary Type DCT Initial/Default Read Modify Posted PP

VERS Code Version FLOAT No 1.0 Yes No No No

VAL Value Field DOUBLE No 0 Yes Yes No No

SMSG State Message STRING [40] No Null Yes Yes Yes No

CMND Command Field ENUM No 0 Yes Yes Yes No

ALRT Alert Field UCHAR No 0 Yes No Yes No

RPVT Record Private NOACCESS No Null No No No No

PXSC Previous Execute Scan UCHAR No 0 Yes No No No

CPT Current Point SHORT No 0 Yes No Yes No

PCPT Previous Current Point SHORT No 0 Yes No No No

TOLP Time of Last Posting ULONG No 0 Yes No No No

For n in [1..4]:

PnDV Pos. n Desired Value DOUBLE No 0 Yes No Yes No

PnLV Pos. n Last Value DOUBLE No 0 Yes No No No

RnCV Readback n Current Value DOUBLE No 0 Yes No Yes No

RnLV Readback n Last Value DOUBLE No 0 Yes No No No

PnDB Pos. n dbAddr NOACCESS No Null No No No No

RnDB Readback n dbAddr NOACCESS No Null No No No No

For nn in [01..70]:

DnnCV Detector nn Current Value FLOAT No 0 Yes No Yes No

DnnLV Detector nn Last Value FLOAT No 0 Yes No No No

DnnDB Detector nn dbAddr NOACCESS No Null No No No No

Field	Summary	Type	DCT	Initial/Default	Read	Modify	Posted	PP
`VERS`	Code Version	FLOAT	No	1.0	Yes	No	No	No
`VAL`	Value Field	DOUBLE	No	0	Yes	Yes	No	No
`SMSG`	State Message	STRING [40]	No	Null	Yes	Yes	Yes	No
`CMND`	Command Field	ENUM	No	0	Yes	Yes	Yes	No
`ALRT`	Alert Field	UCHAR	No	0	Yes	No	Yes	No
`RPVT`	Record Private	NOACCESS	No	Null	No	No	No	No
`PXSC`	Previous Execute Scan	UCHAR	No	0	Yes	No	No	No
`CPT`	Current Point	SHORT	No	0	Yes	No	Yes	No
`PCPT`	Previous Current Point	SHORT	No	0	Yes	No	No	No
`TOLP`	Time of Last Posting	ULONG	No	0	Yes	No	No	No
For n in [1..4]:
`PnDV`	Pos. n Desired Value	DOUBLE	No	0	Yes	No	Yes	No
`PnLV`	Pos. n Last Value	DOUBLE	No	0	Yes	No	No	No
`RnCV`	Readback n Current Value	DOUBLE	No	0	Yes	No	Yes	No
`RnLV`	Readback n Last Value	DOUBLE	No	0	Yes	No	No	No
`PnDB`	Pos. n dbAddr	NOACCESS	No	Null	No	No	No	No
`RnDB`	Readback n dbAddr	NOACCESS	No	Null	No	No	No	No
For nn in [01..70]:
`DnnCV`	Detector nn Current Value	FLOAT	No	0	Yes	No	Yes	No
`DnnLV`	Detector nn Last Value	FLOAT	No	0	Yes	No	No	No
`DnnDB`	Detector nn dbAddr	NOACCESS	No	Null	No	No	No	No

1. - Introduction
1.1. - A Simple One Dimensional Scan
1.2. - Multidimensional Scans
1.3. - Client-server Handshaking in Multidimensional Scans
1.4. - Completion of positioner and detector-trigger operations
2. - Scan Parameters
2.0. - Global Parameters
2.1. - Positioner Parameters
2.2. - Linear Mode
2.3. Table Mode
2.4. - Position Verification, Readback Process Variable, and Delta Parameters
2.5. - Detector Trigger Process Variables and Command data
3. - Data Acquisition Parameters
4. - Operator Display Parameters
5. - Run-time Parameters