The scan command groups together the standard observing programs and source checking into one concise setup driven package. The syntax of the scan command is:
scan setup='setupList' [start=value] [stop=value]where the start and stop keywords are optional (see below). The value assigned to the setup keyword may be one setup or a group of several setups. The next two sections will discuss how the scan command behaves for a single setup entry and then how scan handles multiple (or groups of) setups.
If two or more objects (setups or groups) are separated by the OR character (|), then the first object is run through scan. If that object is successful, then none of the remaining OR'd objects will be run. If the first object fails, then the test if applied to the next object. This process continues until either an object is successful; the setup list is completely exhausted; or the AND character (,) is encountered.
When objects are separated by the AND character (,), every object in the AND list is run through scan. The precedence of the operators is always left to right so the logic of the user's operation may need to be explicitly identified by the use of parentheses. When an object is a grouping of setups, the success or failure of the object is based on the resulting logic of the entire grouping; not necessarily on any one setup.
To illustrate the use of these logical operators and how they apply to individual setups and groups, several examples follow. In each of these examples, it is assumed that the setups A, B, C, and D have already been defined.
The other optional keyword to scan is stop. This keyword value specifies how long the scan command has to execute all of the setups present as the value of the setup keyword. This stop time may be referred to as the scan length. Note that this stop time is different from the setup keyword stop in that the setup keyword defines the duration of one setup's observation (or task observation) while scan's keyword identifies how long scan has to finish working through the list of input setups. This optional keyword to scan will, in general, not need to be set by the user since it is set to the project stopping time if it is not present.
Since the scan steps through the setup keyword in a left-to-right fashion, this stop time represents how much time should be needed to execute (or observe) each of the setups. In the most simple case (for example: scan setup='A'), the stop argument would need to just be equivalent to the time needed to observe the one source. However, since the setup can actually request more than one observation (for example: scan setup='A,B,C'), the user needs to be careful when assigning this stop time. It should be reiterated that this time has nothing to do with the individual setup stop times; it is only used to specify how long the scan command has to work through the setup keyword list.
Hence, there are three conditions which determine when scan should stop and the earliest of these always dominates:
loop srcsetup='sourceList' calsetup='calList' [start=value] \ [stop=value] [thresh=mins]where the start, stop, and thresh keywords are optional. As with the scan command, if the start argument is not present, it defaults to now. Likewise, if the stop argument is not present, it defaults to the project stop time. The keyword stop can be used to terminate the loop command so that enough time remains for other scan or loop commands.
The optional keyword thresh specifies the minimum number of minutes that is considered acceptable to observe any object in the source setup list. There is only one value associated with the thresh keyword and it is entered in minutes. If this optional keyword is not present, the threshold will be set internally to the average time spent on the calibrator list (typically between 6 and 10 minutes).
The observing logic of the loop command is that it will call scan using the calsetup value (as scan's setup argument) followed by a call to scan using the srcsetup value (again, as the setup argument). These two calls will alternate finishing up with a final call to scan with the calsetup value.
The loop command will stop when the time specified by the optional keyword stop has been reached or the project stop time has been exceeded; whichever is earlier. The internal structure of loop will attempt to insure that a final call to the calsetup is the last scan call performed before the stop conditional is reached. This may cause the final scan call of the srcsetup to be truncated. The details of how the srcsetup time may be adjusted are explained below.
What happens at the end of the loop command is a function of how much time remains. Remember that loop always tries to save enough time to insure that the calibrator can be done at the end. This means that the last source observation will either be truncated or lengthened to account for the scrap time. Whether the source time is made shorter or longer depends on the value of the thresh parameter. The details are outlined in the following paragraph.
If the amount of time that remains prior to the invocation of a source observation greater than the sum of the average source integration time (Tsrc), twice the average calibrator integration time (Tcal), and the threshold time (Tthresh), then the source setup will be observed as normal. If the time remaining is less than (Tsrc + (2 * Tcal) + Tthresh) but greater than (Tsrc + Tcal), then the source setup will be run but will have its integration time increased so that it ends at the loop stop time minus the calibrator time (stop - Tcal). However,, if the time remaining is less than (Tsrc + Tcal) but greater than (Tthresh + Tcal), then the source setup will be executed but the integration time will be shorten to insure that it ends at (stop - Tcal). Finally, if the time remaining is less than (Tthresh + Tcal), then the final calibrator setup is executed and loop exits with about Tthresh minutes remaining until the scheduled stop of the loop command. Note: This last (pathetic) case will only be reached if the loop command is started with less than (Tthresh + Tcal) minutes remaining.