Having spec perform several different ccdseries or getflux commands in sequence requires the user to supply beforehand some additional information. That information, along with one or more ccd_batch commands, is entered into a .do file. The .do files are ASCII text, and are typically stored in opal:/home1/user1/batches/.

Once written, the .do file can be run with the command 'qdo <filename.do>' in spec on opal.

The column on the left shows the literal contents of a .do file, in the order they should appear. Whitespaces and blank lines are ignored by spec, so your .do file may not have the exact look-and-feel of the one in the table and still function properly. The right column contains relevant explanatory detail.

qdo ccd_batch0101.mac Ensures that the proper definititions of macros related to ccd_batch are loaded

def ccd_batch '{
local i ndark ndata nrpt xtime firstframe
start_batch $*
takeflux vacuum
for (i=1;i<=nrpt;i++) {
    movesample
    takeflux
    takedark ndark xtime
    takedata ndata xtime
    }
}' While the default version of ccd_batch will be defined in the 'qdo' above, it is useful to define ccd_batch explicitly here. This allows one to customize exactly which commands are run in which order.
The lines starting with 'local' and 'start_batch' must be kept as shown here.
The lines that may be changed, replicated, rearranged, or omitted, are:

takeflux vacuum; moves the sample out of the beam and measures the direct flux

movesample; moves the sample to the next position in which to take data. One or more such positions can be specified (see below).

takeflux; measures the flux through the sample, at whatever position it is currently in.

takedark ndark xtime; runs ccdseries with the beam off

takedata ndata xtime; runs ccdseries with the beam on

To comment out a line, add # at the beginning.
For example, if the sample holder has no through hole for the beam to pass without hitting the sample, one could comment out the 'takeflux vacuum' line.
Or, to do two sets of data before taking a dark, one could write:
for (i=1;i<=nrpt;i++) {
    movesample
    takeflux
    takedata ndata xtime
    takedata ndata xtime
    takedark ndark xtime
    }
NOTE: to keep the sample in one place during ccd_batch, one should not comment out 'movesample', but rather specify only one sample position below.

def blockbeam 'att 15'
def showbeam 'att 0' The commands to keep the beam off the sample and allow it to be on. The usual form is att (short for "attenuate") with 15 being full attenuation and 0 being none.
Another possibility is
def blockbeam 'global samxpos;
               local blockpos;
               samxpos = A[samx];
               blockpos = 5;
               print "Moving samx to " blockpos;
               mv samx blockpos'
def showbeam 'print "Moving samx to " samxpos;
              mv samx samxpos'
in which case blockbeam would move the sample holder somewhere to block the beam, and showbeam would return it to its previous position.

def shutteroff 'mv dac2 5; print "dac2 -> 5"'
def shutteron 'mv dac2 0; print "dac2 -> 0"' These commands are used when getting the flux on the beamstop.
The shutteroff command takes control of the shutter away from the CCD, so the measurement can be done even if the CCD is not actively recording images. The shutteron command returns control to the CCD.
If a shutter is not being used, these can be replaced by
def shutteroff ''
def shutteron ''

batch_name = "sample1_n5" A name specific to the data set being collected. The "child" directory will take its name from this variable, as will the .imm and .info files. In this example, the child directory would be sample1_n5/ and the image filename would be sample1_n5_0001.imm.

data_dir = "/opal1/feb2001/feb02" The location to store the data. Also called the "parent" directory. A single "parent" directory can contain many "child" directories.

log_dir = "/opal1/feb2001/logs" The location to store the log files.
In this example, the short log file would be called /opal1/feb2001/logs/sample1_n5.short, and the long log file would be called /opal1/feb2001/logs/sample1_n5.out.

# sample positions for data
# must be arrays of size 1 or more
# span syntax:   min   max   #
span samxdata   -0.3 0.25 6
span samzdata    1.3   1.6   4
#    if # = 1, span uses min only This is where one specifies the data collection positions for motors samx and samz. In general, the variables samxdata and samzdata must be arrays. The arrays can be assigned in any way. Note that samxdata and samzdata can have different sizes.
Each time movsample is called within ccd_batch, the sample is moved to the next samx and samz positions as listed in the samxdata and samzdata arrays, respectively. Upon reaching the end of an array, movesample loops back around to the array's beginning.
It is possible to call movesample by hand from the SPEC> prompt, provided that samxdata, samzdata, and nextpos (see the next segment below) are defined already. This is helpful for moving away from ill-chosen sample positions.
The example on the left uses the 'span <name> <min> <max> <#>' command to fill the arrays. span creates an array of size <#>, named <name>, and then fills it with uniformly spaced values from <min> to <max> (inclusive). If <#> is 1, then the array contains only the value <min>.
Another way to define the arrays is through standard spec syntax. This defines each array entry directly. An example would be,
array samzdata[4]
samzdata[0] = 1.3
samzdata[1] = 1.4
samzdata[2] = 1.5
samzdata[3] = 1.6

# beamstop positions
bstopdata = 3.1
bstopflux = -2 In practice, the beamstop is usually positioned differently for data (CCD image) collection and for flux measurement. These two variables are the positions to use for each.

# sample position for vacuum flux measurement
samxvac = samxdata[0] + 1.0
samzvac = samzdata[0] There is usually a position in the sample holder which allows the beam to go straight through to the detector without hitting the sample. This is used for getting the vacuum flux. The samx and samz positions are entered into the two variables at the left.
In this case, the two are set relative to the already-defined data positions. However, a direct definition, e.g.,
samxvac = 1.3
is also possible.

# some setup is done here
# if you hit ctrl-c to stop the set, then
# comment this line out before running qdo again
start_set This will do some last-minute initialization before running the batches. It should only be run once per .batchinfo file.

# first index to move samx and samz to
nextpos = 0 nextpos is a global variable which is incremented each time movesample is called. Its initial value, set here, will be the first sample position index used by ccd_batch.

# syntax: #dark #data #repeat exptime(ms) [1stframe]
ccd_batch   5      10     1       1000
ccd_batch 10     50     2       350
ccd_batch 15    100    1       150 We finally reach the actual ccd_batch commands. There can be as few as 1, and as many as desired.
The number of repeats must be 1 or more.
The last column, <[1stframe]> is an optional parameter which sets the number of the first frame. If omitted, the first frame will be 1 larger than the greatest existing frame number of the same name, or 1 if none exist.

# write the .batchinfo file and
# print out the short log file
finish_set This does a few final things. It should be run only when all of the batches for the .batchinfo file have been completed.

qdo ccd_batch0101.mac	Ensures that the proper definititions of macros related to ccd_batch are loaded
def ccd_batch '{ local i ndark ndata nrpt xtime firstframe start_batch $* takeflux vacuum for (i=1;i<=nrpt;i++) { movesample takeflux takedark ndark xtime takedata ndata xtime } }'	While the default version of ccd_batch will be defined in the 'qdo' above, it is useful to define ccd_batch explicitly here. This allows one to customize exactly which commands are run in which order. The lines starting with 'local' and 'start_batch' must be kept as shown here. The lines that may be changed, replicated, rearranged, or omitted, are: takeflux vacuum; moves the sample out of the beam and measures the direct flux movesample; moves the sample to the next position in which to take data. One or more such positions can be specified (see below). takeflux; measures the flux through the sample, at whatever position it is currently in. takedark ndark xtime; runs ccdseries with the beam off takedata ndata xtime; runs ccdseries with the beam on To comment out a line, add # at the beginning. For example, if the sample holder has no through hole for the beam to pass without hitting the sample, one could comment out the 'takeflux vacuum' line. Or, to do two sets of data before taking a dark, one could write: for (i=1;i<=nrpt;i++) { movesample takeflux takedata ndata xtime takedata ndata xtime takedark ndark xtime } NOTE: to keep the sample in one place during ccd_batch, one should not comment out 'movesample', but rather specify only one sample position below.
def blockbeam 'att 15' def showbeam 'att 0'	The commands to keep the beam off the sample and allow it to be on. The usual form is att (short for "attenuate") with 15 being full attenuation and 0 being none. Another possibility is def blockbeam 'global samxpos; local blockpos; samxpos = A[samx]; blockpos = 5; print "Moving samx to " blockpos; mv samx blockpos' def showbeam 'print "Moving samx to " samxpos; mv samx samxpos' in which case blockbeam would move the sample holder somewhere to block the beam, and showbeam would return it to its previous position.
def shutteroff 'mv dac2 5; print "dac2 -> 5"' def shutteron 'mv dac2 0; print "dac2 -> 0"'	These commands are used when getting the flux on the beamstop. The shutteroff command takes control of the shutter away from the CCD, so the measurement can be done even if the CCD is not actively recording images. The shutteron command returns control to the CCD. If a shutter is not being used, these can be replaced by def shutteroff '' def shutteron ''
batch_name = "sample1_n5"	A name specific to the data set being collected. The "child" directory will take its name from this variable, as will the .imm and .info files. In this example, the child directory would be sample1_n5/ and the image filename would be sample1_n5_0001.imm.
data_dir = "/opal1/feb2001/feb02"	The location to store the data. Also called the "parent" directory. A single "parent" directory can contain many "child" directories.
log_dir = "/opal1/feb2001/logs"	The location to store the log files. In this example, the short log file would be called /opal1/feb2001/logs/sample1_n5.short, and the long log file would be called /opal1/feb2001/logs/sample1_n5.out.
# sample positions for data # must be arrays of size 1 or more # span syntax: min max # span samxdata -0.3 0.25 6 span samzdata 1.3 1.6 4 # if # = 1, span uses min only	This is where one specifies the data collection positions for motors samx and samz. In general, the variables samxdata and samzdata must be arrays. The arrays can be assigned in any way. Note that samxdata and samzdata can have different sizes. Each time movsample is called within ccd_batch, the sample is moved to the next samx and samz positions as listed in the samxdata and samzdata arrays, respectively. Upon reaching the end of an array, movesample loops back around to the array's beginning. It is possible to call movesample by hand from the SPEC> prompt, provided that samxdata, samzdata, and nextpos (see the next segment below) are defined already. This is helpful for moving away from ill-chosen sample positions. The example on the left uses the 'span <name> <min> <max> <#>' command to fill the arrays. span creates an array of size <#>, named <name>, and then fills it with uniformly spaced values from <min> to <max> (inclusive). If <#> is 1, then the array contains only the value <min>. Another way to define the arrays is through standard spec syntax. This defines each array entry directly. An example would be, array samzdata[4] samzdata[0] = 1.3 samzdata[1] = 1.4 samzdata[2] = 1.5 samzdata[3] = 1.6
# beamstop positions bstopdata = 3.1 bstopflux = -2	In practice, the beamstop is usually positioned differently for data (CCD image) collection and for flux measurement. These two variables are the positions to use for each.
# sample position for vacuum flux measurement samxvac = samxdata[0] + 1.0 samzvac = samzdata[0]	There is usually a position in the sample holder which allows the beam to go straight through to the detector without hitting the sample. This is used for getting the vacuum flux. The samx and samz positions are entered into the two variables at the left. In this case, the two are set relative to the already-defined data positions. However, a direct definition, e.g., samxvac = 1.3 is also possible.
# some setup is done here # if you hit ctrl-c to stop the set, then # comment this line out before running qdo again start_set	This will do some last-minute initialization before running the batches. It should only be run once per .batchinfo file.
# first index to move samx and samz to nextpos = 0	nextpos is a global variable which is incremented each time movesample is called. Its initial value, set here, will be the first sample position index used by ccd_batch.
# syntax: #dark #data #repeat exptime(ms) [1stframe] ccd_batch 5 10 1 1000 ccd_batch 10 50 2 350 ccd_batch 15 100 1 150	We finally reach the actual ccd_batch commands. There can be as few as 1, and as many as desired. The number of repeats must be 1 or more. The last column, <[1stframe]> is an optional parameter which sets the number of the first frame. If omitted, the first frame will be 1 larger than the greatest existing frame number of the same name, or 1 if none exist.
# write the .batchinfo file and # print out the short log file finish_set	This does a few final things. It should be run only when all of the batches for the .batchinfo file have been completed.