The SSCAN record v5.25

 Advanced Photon Source
 Argonne National Laboratory

Contents:
1.    Introduction
1.1. A Simple One Dimensional Scan
1.2. Multidimensional Scans
1.3. Handshaking with clients
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 s and Command Data
2.6. Delay variables
2.7. Client handshaking variables
3.    Data Acquisition Parameters
4.    Operator Display Parameters
5.    Run-time Parameters

1. Introduction

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, trigger up to four detectors, and acquire data from up to 74 process variables (70 detector values of type float and four positioner readbacks of type double).

 Typically, the SSCAN record moves motors and acquires scaler data at each motor position, but obviously it can also be used for other purposes. Any writable EPICS PV (process variable) can be scanned through a set of values while data are recorded from any other PVs. For example, one of the positioner PVs could be used to vary the gain or dwell time 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.

The SSCAN record normally acquires sets of scalar data values and assembles them into arrays, but it can also acquire arrays directly from array-valued PVs. The end results can only be one-dimensional arrays, however; a single SSCAN record cannot acquire multi-dimensional data.

 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. Currently, these links are implemented with the recDynLink library, which is distributed along with the scan module. In the future, they will be converted to use dbCaPutCallback, which is part of EPICS base.

1.1. A Simple One Dimensional Scan

P1PV

the name of a positioner (e.g., "myMotor.VAL")

P1SP

start position -- the first position at which data will be acquired

P1EP

end position -- the last position at which data will be acquired

NPTS

the total number of positions to visit

T1PV

the name of a detector-trigger PV. This PV will be written to after the positioner has arrived at each position.

D01PV

the name of a detector (signal) PV. The value of this PV will be recorded after the detector-trigger has finished acquiring data.

Let's run through that again, this time more generally, with more detail, and including more of the available options.

Positioners

You can specify zero to four positioners. Positioners are expected to tell the SSCAN record when they're done moving (more about this later). After all positioners have declared themselves done, the SSCAN record waits for a user-specified settling time (PDLY, normally zero) before firing detector triggers. (If no positioners, then no positioner settling time.)

Positions to visit

There are lots of possibilities here. You can specify any combination of the set [start, end, center, width, step-size] for each positioner; you can load a table of positions for each positioner; or you can specify that positioners are to be moved continuously during a scan. You can specify that positions be regarded as absolute, or as relative to the pre-scan position.

Detector triggers

Detector triggers act much like positioners, in that they write a value and wait for any ensuing processing to finish, but they send the same value at every data point (TnCD). After all detectors have declared themselves done, the SSCAN record waits for a user-specified settling time (DDLY, normally zero) before reading data from detector-signal PVs. (If no detector triggers, then no detector settling time.)

Detector signals

Typically, detector signals are scalar PV's, but they can be array-valued PV's. If so, the SSCAN record will read them at the end of the scan. If array-valued PVs require processing to acquire their values, the SSCAN record can fire a special array trigger (A1PV A1CD, exactly analogous to detector triggers), and wait for any ensuing processing to finish before reading the arrays. If all detector signals are array valued, it's probably better to use array mode (see ACQT).

Detector-signal values can be accumulated from scan to scan, so you can sweep over a set of positions, building up statistical precision and averaging over any positioning errors or variable external conditions.

After the scan

You can tell positioners what to do after the scan is finished, using the PASM field. The default behavior is simply to remain where the scan left them, but you could tell them to return to their pre-scan positions, go to their start positions, or go to positions calculated from acquired data (e.g., the position at which a specified detector signal REFD reached its peak value during the scan).

1.2. Multidimensional Scans

 To initiate the scan, the scan2 record is commanded to begin (scan2.EXSC is set to "1"). scan2 sends its positioners to their starting points, and waits for their callbacks. Then scan2 writes to its Detector Trigger(s), (one of) 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 scan1 is finished, and its data have been written (or at least secured), 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 scans is very flexible and permits scans of any dimension. Note that scan1 can be executed independently of scan2, so a complex multidimensional scan can be built and tested one dimension at a time. (In principle, it's possible to run several inner-loop scans in parallel from a single outer-loop scan, but in practice, the capability is of limited use, because there is no coordination between the inner-loop scans, and no data-storage client exists that would correctly understand the acquired data.)

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 hold 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 next section describes the handshake mechanisms implemented by the SSCAN record.

1.3. Handshaking with clients

1.3.1 Handshaking with data-storage clients

1) The new way, using the AWAIT and AAWAIT fields:

The data-storage client waits for DATA==1, which indicates that the SSCAN record has finished posting all array fields; writes "1" to the AWAIT field to prevent the SSCAN record from overwriting array fields before the client has read them; and writes "0" to AWAIT when it is finished reading. One advantage of this handshake is that it allows the SSCAN record to proceed with the next scan (the SSCAN record's data arrays are double buffered) until it's time to post data. In this way, the data-storage client can be writing one set of scan data while the SSCAN record is acquiring the next set.

For very fast scans, or a very slow data-storage client, there might not be sufficient time, between the posting of one data set and the acquisition of the next, for the client to write "1" to AWAIT (array wait) field. In this case, you can cause the SSCAN record automatically to set AWAIT==1, whenever it posts data, by setting the AAWAIT (auto array wait) field to "1". (It's OK if the client also sets AWAIT==1.)

Only one data-storage client can use AWAIT. If you have more than one data-storage client, you must arrange for them to pool their use of the AWAIT field, so that it gets reset to zero only when all have finished. (It's OK if AWAIT gets set to one more than once. Only the first AWAIT==1 write has any effect.)

Note that this AWAIT handshake protects scan data no matter how the SSCAN record gets executed, unlike the old method described next.

2) The old way, using the WAIT, WCNT, and AWCT fields:

Before the AWAIT field was introduced, the only means of handshaking was an extension of the mechanism by which the SSCAN record waits for detector triggers to signal completion. In this extension, the SSCAN record waits until all detector triggers have signalled completion, and the field WAIT is equal to zero. This extension's intended purpose is to support detectors that can't signal completion with a callback, but that can write to a PV -- for example, a detector that's implemented as a channel-access client -- and it can still be used for that purpose, while a data-storage client is using it to protect data acquired from an inner-loop scan.

Here's how the handshake works in a data-storage application: The data-storage client notices that an inner SSCAN record has started a scan (typically, it monitors the DATA field, which is set to zero at the beginning of 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. The client waits for DATA==1, which indicates that new data are available. 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 field, WCNT; each "0" decrements it. When WCNT reaches zero, the scan continues.

In 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 (that would increment the wait count to 2), 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 the autoWaitCount==0 method is that scans can be performed whether or not a client is available to write to the WAIT field. The disadvantage is that the is not reliable for vry fast scans. Note that this form of handshaking doesn't do a very thorough job of data protection, because it does not directly prevent a SSCAN record from overwriting its own arrays; it only prevents an outer-loop SSCAN record from telling an inner-loop record to overwrite its arrays. If the SSCAN record is executed by some other agent, the WAIT handshake doesn't protect data at all.

1.3.2 Handshaking with CA clients that implement positioners or detectors

1. The client is driven by a PV to which one of the SSCAN record's detector-trigger links writes.
2. The client can signal completion in a way that the SSCAN record understands.

There are two mechanisms the client can use to signal completion that will work with the SSCAN record:

putNotify-based completion signalling

This is the method the SSCAN record uses to drive other records. Clients can't do this directly, but they can do it indirectly, using a BUSY record. A BUSY record is a custom EPICS record, supplied as part of the synApps package, that looks and operates almost exactly like the binary-output record, except that it executes its forward link, FLNK, only when its VAL field has the value zero. As it happens, EPICS putNotify completion mechanism is implemented as part of the processing of forward links, so the fact that the busy record allows a CA client to control the execution of a forward link means that the client can control the timing of a putNotify callback.

Here's how it works in practice: some developer causes a BUSY record (let's call it xxx:detBusy) to be loaded into the IOC; the SSCAN record writes "1" to a xxx:detBusy.VAL; the client monitors xxx:detBusy.VAL, and begins some operation when it goes to "1"; when processing is complete, the client writes "0" to xxx:detBusy.VAL; this causes the record to execute its forward link. Thus, the busy record appears to be executing all the time the client actually is executing, so EPICS knows when the client is done.

Very simple, but it does require that a dedicated record be loaded in some IOC. Here's a database that loads a busy record:

record(busy, "xxx:CCD_Busy")
{
}

Many of the databases in synApps contain BUSY records for this purpose, particularly those that act as front ends for State-Notation_Language (SNL) code. Though motivated by the needs of the SSCAN record, this completion-signalling capability can be used by any CA client.

WAIT-field handshake with the SSCAN record

This handshake is intended for CA clients implementing detectors (though as mentioned above, it can also be useful for data-storage clients). In the detector case, the client monitors a PV to find out when someone wants it to acquire data; the SSCAN record writes some value to the PV to start acquisition; the client writes "1" to <scanrecord>.WAIT, indicating that it wants the SSCAN record to wait; the client performs its data-acquisition task; and the client writes "0" to <scanrecord>.WAIT, indicating that it's done.

Several clients can use the WAIT field, each write of "1" increments a wait count WCNT; each "0" decrements WCNT; the SCAN record stops waiting when WCNT is decremented to zero. The SSCAN record doesn't care, by the way, who writes what to WAIT; it simply waits until the number of WAIT==0 writes equals the number of WAIT==1 writes.

But what if clients are a little slow to react, and the SSCAN record checks its wait-count WCNT before the clients have had time to write 1's to it? If this is a problem, you can cause the SSCAN record to set WCNT at the appropriate time, by setting <scanrecord>.AWCT to the number of slow clients. (But now those clients must NOT write "1" to WAIT.)

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. Reassignable 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, to be replaced eventually by dbCaPutCallback). 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, detailed above, and the use of a buffer record that can do a ca_put_callback() to make the inter-crate link. Currently, I'm aware of six record types that can do a ca_put_callback(): the sscan, swait, and sseq records; an ai record with soft asynchronous device support; and the sCalcout and aCalcout records. (The sscan, swait, sseq, sCalcout, and aCalcout records are distributed with synApps. swait, sCalcout, and aCalcout are variants of the calcout record; sseq is a variant of the seq record.)

2. Scan Parameters

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

2.1. Positioner Parameters

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 currently 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

2.2. Linear Mode

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

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

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

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

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

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

2.5. Detector Triggers and Command Data

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

2.6. Delay variables

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

1) A data-storage client can put a hold on a SSCAN record whose data it is writing by writing to the AWAIT field. This hold doesn't prevent the record from executing, or even from acquiring new data, but it does prevent the record from switching data buffers.

2) In a multidimensional scan, a data-storage client can put a hold on scan2 while it is writing data from scan1, by writing to the WAIT field. This relatively inefficient handshake is still used by some data-storage clients.

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

A client may not be able to write quickly enough to WAIT 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.

A client may not be able to write quickly enough to AWAIT to ensure that the scan holds before switching buffers. In this case, the SSCAN record can be made to write automatically to AWAIT whenever data are posted, by setting the AAWAIT field to "1".

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
AWAIT	Waiting for data-storage client	SHORT	No	0	Yes	Yes	Yes	Yes
AAWAIT	AutoWait for data-storage client	MENU ("NO","YES")	Yes	0	Yes	Yes	No	No

3. Data Acquisition Parameters

The scan results will most frequently be read as position arrays (P1RA-P4RA) and arrays of detector data (D01DA-D70DA) where each detector data element corresponds to the position element.

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, see section 1.3. - Handshaking with clients

During slow scans, the application program may want to display scan progress point-by-point. The SSCAN record posts monitors on fields that it updates each point, but it doesn't post point-by-point 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 approximately every 5th point. In either case, the array data will contain every point at the completion 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

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

4. Operator Display Parameters

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.

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

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

The VAL field is used only as a progress indicator. It is posted after all point-by-point PV have been posted. (So, if a PV you're interested in hasn't been posted by the time you get the VAL-field monitor, that PV's value hasn't changed since the last time it was posted.)

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 is finished.
14	WAIT:SAVE_DATA	The scan is waiting for AWAIT -> 0 so it can switch data buffers.
15	SCAN_PENDING	A scan has been commanded, but has not yet started
The remaining menu choices can't be displayed as strings by CA clients, but should be displayed as numbers.
16	TRIG_ARRAY_READ	The scan is about to trigger array reads (A1PV)
17	WAIT:ARRAY_READ	The scan is waiting for a callback from the array-read PV
18	PREVIEW	We're doing a preview of the scan.

The data-state (DSTATE) field indicates in what state is the processing of data arrays. The possible states are as follows:

state	message	meaning
0	UNPACKED	Data arrays are either idle or being filled. If a client should read an array now, it would get last scan's data.
1	TRIG_ARRAY_READ	The next thing to do is trigger the array-read PV, A1PV. If a client should read an array now, it would get last scan's data.
2	ARRAY_READ_WAIT	A1PV has been triggered, and the callback is still outstanding. If a client should read an array now, it would get last scan's data.
2	ARRAY_GET_CALLBACK_WAIT	recDynLinkGetCallback() has been issued for array-valued PV's, and one or more callbacks are still outstanding.
3	RECORD_ARRAY_DATA	It's time to read array data. If any array-valued PV's exist, the data state will change to ARRAY_GET_CALLBACK_WAIT while waiting for the callbacks.
3	SAVE_DATA_WAIT	Arrays are filled, but cannot be posted yet because the data-storage client is not finished writing last scan's data. If a client should read an array now, it would get last scan's data.
4	PACKED	Arrays are filled, and buffers have been switched, but they haven't yet been posted. If a client should read an array now, it would get last scan's data.
5	POSTED	Data arrays have been posted. Now the data-storage client can read this scan's array data.

The command (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.

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	LONG	No	0	Yes	No	Yes	No
PCPT	Previous Current Point	LONG	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