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
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.
Let's run through that again, this time more generally, with more detail, and including more of the available options.
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.
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) 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.
There are two mechanisms the client can use to signal completion that will work with the SSCAN record:
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.
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.)
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.)
In this documentation, many of the SSCAN-record PV's will be listed in tables containing the following informational headings:
Field | Summary | Type | DCT | Initial/Default | Read | Modify | Posted | PP |
---|---|---|---|---|---|---|---|---|
NPTS | Number of Points | LONG | Yes | 100 | Yes | Yes | Yes | No |
MPTS | Maximum Number of Points | LONG | 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", CNTR OF MASS) | 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:
|
||||||||
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 |
BSWAIT | Wait for completion? | MENU ("YES", "NO") | Yes | "YES" (0) | Yes | Yes | Yes | No |
BSPV, BSNV, BSCD, and BSWAIT allow the user to specify a PV to be
written to before every scan starts. (If the sscan record is part of a
multidimensional scan, each participating sscan record has its own set of
before-scan parameters, so you can cause an action to occur before the whole
scan starts, and before each nested loop starts.)
To specify a before-scan PV write, write the name of the PV to BSPV, and the value to be written to BSCD. If you want the sscan record to wait for completion of processing triggered by the write, before going on with the rest of the scan, set BSWAIT to "YES" (1). You can check to status of the link by looking at BSNV. If the link is good, BSNV will be zero. Note that the before-scan link is permitted to change only selected fields of its own sscan record: it cannot change PV names (i.e., links); and it cannot change the acquisition type (ACQT) or mode (ACQM). If this sscan record is part of a multidimensional scan, the before-scan link can change any field of a lower-level sscan record (i.e., one that its record it driving), and no field of a higher level scan record. |
||||||||
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 |
ASWAIT | Wait for completion? | MENU ("YES", "NO") | Yes | "YES" (0) | Yes | Yes | Yes | No |
ASPV, ASNV, ASCD, and ASWAIT allow the user to specify a PV to be
written to after every scan is finished. (If the sscan record is part of a
multidimensional scan, each participating sscan record has its own set of
after-scan parameters, so you can cause an action to occur after the whole
scan is done, and after each nested loop is done.)
To specify an after-scan PV write, write the name of the PV to ASPV, and the value to be written to ASCD. If you want the sscan record to wait for completion of processing triggered by the write, before going on with the rest of the scan wrap-up, set ASWAIT to "YES" (1). You can check to status of the link by looking at ASNV. If the link is good, ASNV will be zero. Note that the after-scan link is permitted to change only selected fields of its own sscan record: it cannot change PV names (i.e., links); and it cannot change the acquisition type (ACQT) or mode (ACQM). If this sscan record is part of a multidimensional scan, the after-scan link can change any field of a lower-level sscan record (i.e., one that its record it driving), and no field of a higher level scan record. |
||||||||
A1PV | Array-read trigger 1 PV Name | STRING [40] | Yes | Null | Yes | Yes | No | No |
A1NV | A1PV Name Valid | LONG | No | 0 | Yes | No | Yes | No |
A1CD | A1 Cmnd | FLOAT | Yes | 1 | Yes | Yes | No | No |
A1PV, A1NV, and A1CD allow the user to specify a PV to be
written to before the sscan record tries to read array-valued data. (It may be
necessary, for example, to cause data to be read from hardware into a set of
EPICS PV's, or to execute some calculation on the data, before the sscan record
acquires it. The sscan record will wait for processing triggered by this write to
complete before reading arrays.
To specify an array-preparation PV write, write the name of the PV to A1PV, and the value to be written to A1CD. You can check to status of the link by looking at A1NV. If the link is good, A1NV will be zero. |
||||||||
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 |
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.
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 |
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 |
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 |
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.
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 |
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 |
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:
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 |
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 |