Using batch files in Sunsort
A batch file is a sequence of commands for Sunsort to run one after
the other without any user intervention. They are particularly useful
for processing and filtering entire tapes while the user gets on with
something else (usually going home).
Sunsort has a fairly comprehensive set of command line commands which
can also be used in batch files. Some of these are listed in the
relevant sections of this manual, but the complete list is given
below. All command line commands are listed below, most are suitable
for batch files, those that aren't are marked.
You can create a batch file in any text editor, so the programs
textedit, dtpad, emacs,
xemacs and vi are all suitable. Just put
one command on a line. Only put blank lines where they are needed
by commands (save and load selected).
List of all command line commands
batch batch_file_name
Opens the specified file and begin processing it as a sequence of
Sunsort commands. Any errors during the reading of the batch file
will cause processing to terminate. Blank lines also cause the
processing to stop and lines beginning with # are ignored.
This command may not be used inside a batch file.
clear spectra [specnos1] [specnos2] .....
Clear the accumulated data present in the spectra specified by the
argument. The argument (spectra) can be one of the following
strings:
- all: clear all defined spectra
- 1d: clear all 1d spectra or spectrum number specnos1 etc.
- 2d: clear all 2d spectra or spectrum number specnos1 etc.
for example the following command will clear 1d spectra 1,3 and 5:
clear 1d 1 3 5
Note that clear all and clear 2d leave windows
alone, but if the window number is mentioned explicitly with
clear 2d then it is cleared.
close [data_input_stream]
Closes the file connection to Sunsort's READ data stream (see the open
command). The optional argument data_input_stream may be
tape, remote, disk, demon and
pipe, although their use is rather superfluous.
debugsort
This command starts the debugger running on the currently loaded sort
program if there is one. Within the debugger, the user should set any
required breakpoints and then CONTINUE the sort process using the
debugger's continue, step or next commands. Using the debugger's run
command will screw things up!
Note this will only work on systems that have the debugger dbx. If,
for example, you are running Sun's workbench, you will have to start
the debugger and attach it to the sunsort_proc process yourself.
This command should not be used inside a batch file.
display1d specnos1 [specnos2] [specnos3]
[specnos4]
Results in Sunsort sending a request to its 1d graphics process
asking it to display the specified spectra. At least one spectrum
number must be given. For example the following command will
display 1d spectra 1 and 3:
display1d 1 3
Note that if the display action is set to anything other than
display specifying more than one spectrum is unlikely
to work.
It is unlikely that this is useful inside a batch file.
display2d specnos
Results in Sunsort sending a request to its 2d graphics process
asking it to display the specified spectrum.
It is unlikely that this is useful inside a batch file.
displayaction action
This alters the default action when a 1d spectrum is displayed.
Action can be one of display, mstick
or pkfind. Display is the default and no extra
action is taken after the spectrum is displayed. Mstick
causes the 1D viewer to automatically run its matchstick fitting routine.
Pkfind causes the 1D viewer to automatically run its peak
finding routine.
editsort editor sort_program_name
Attempts to start the program editor on a file whose name is given
by the string sort_program_name.
This command should not be used inside a batch file.
eject [access mode]
Will unload the currently mounted read tape if access mode = r or
the write tape if access mode = w. If the access mode argument is
not specified then by default the read tape is unmounted. (See
tapemount and tapeumount commands). Note that if a tape file is
still open (see open and close commands) then this command will
fail.
end
If encountered during processing of a batch file (see batch command)
this command will result in Sunsort ceasing to read commands from
this source. In all other circumstances it will have no effect. It
is recommended that the user always use this command at the end of
their batch files.
exit
This command will cause Sunsort to attempt to terminate all
ancillary processes and then to exit.
This command should probably not be used inside a batch file.
help [command name]
Help without an argument will produce a list of the commands
recognised by Sunsort. Typing help followed a command name will
produce a line of the form:
command-name arguments
or an error message if the command is not recognised.
Using this command inside a batch file is pointless.
killsort
The current sort program running under the control of Sunsort will
be sent a SIGKILL (equivalent to a kill -9 pid) and hence should
be terminated by this command. Try using killsort if during data
reading (see sort command) Sunsort unexpectedly locks up.
load type load_directory format [add]
This command is used to load in to Sunsort previously saved (see
save command) spectrum/variable files from the specified
load directory on disk. The type argument specifies which
category of file Sunsort will attempt to load and may take one of the
following string values:
- all: all spectra in specified directory
- windows: all 2d window spectra
- variables: attempt to load a new set of variables from
load directory/.variables
- selected: prompt the user for a list of 1d and 2d spectrum
numbers to be loaded
The user must also provide an argument to tell Sunsort which format
decoder to use in order to interpret the load files. Allowed format
values are:
- sdb: NSF sdb spectrum database format
- eg: the Eurogam format
- xy: ASCII text x verses y format
The last load argument add (which is optional) will, if set to 1,
cause Sunsort to add the newly loaded spectra to those already
stored in Sunsort on a spectrum by spectrum basis. For example:
load all /stage/sjah sdb 1
loadsort [-keep] [sort_prog_name]
Issuing the command loadsort results in Sunsort generating a
killsort command in order to terminate the current sort process and
then attempting to start a new sort program running. If the optional
argument sort_prog_name is not specified then Sunsort will attempt
to run sunsort_proc by default. Upon loading a new sort process
Sunsort will normally delete its previous set of spectra and
generate new spectra using the definitions found in
sort_prog_name.spec (or sunsort_proc.spec by
default). If the -keep argument is used this behaviour will be
overridden and Sunsort will preserve its previous set of spectra.
makesort sort_source_name [makesort options]
This command is used to run the makesort script in order to
generate a working Sunsort sort program (see load command). All
arguments are the same as for the makesort command script.
newtape volume_name drive_nos
The newtape command will mount a blank tape (see tapemount command)
on the drive specified by the drive_nos argument for use in the
output of filtered event by event data. The new volume label to be
given to the tape is specified by the volume_name argument and can
be no more than eight characters long. For example:
newtape filt96 1
If an ANSI tape header is already present on the tape this operation
will fail.
open data_source sort_file
The open command is used to connect a data file of name sort_file
to Sunsort's READ data stream. The storage media upon which the data
file resides is specified by the argument data_source and can be
one of disk, tape, remote,
demon and pipe.
Once a successful open command has been issued and until a close
command is issued or an end of data condition is encountered,
issuing a sort command will result in Sunsort passing data blocks
from the input data file to the user's sort process.
Examples:
open disk /stage/sjah/run37
open tape run37
open remote dummy
Note that in order to be able to open a tape file, a successful
mount (see tapemount command) must already have performed.
When attempting to open a tape file the user can specify whether
the tape should be rewound first by using tape/1 in place of the
argument tape. More over, if the user would like specify that the
next close command will result in the tape moving back to the
beginning of the file being opened then tape/2 can be used.
overlay1d specnos1 [specnos2] [specnos3] [specnos4]
Results in Sunsort sending a request to its 1d graphics process
asking it to overlay the specified spectra on to the spectra
currently being displayed. (see display1d) At least one spectrum
number must be given.
It is unlikely that this is useful inside a batch file.
printsenv
This command prints out the current values for all of Sunsort's
state variables. These variables affect various operations in
Sunsort such as the block lengths used in data I/O and which data
format decoder is to be employed. See The Sunsort Reference Manual
for more information.
Using this command inside a batch file is pointless.
processes [n]
Read or set the number of simultaneous sort-processes. If n
is not specified then the current status is printed. If n
is specified then the number to use at the next loadsort is changed.
If you specify n = 0 then Sunsort will find out how many
processors the machine has and set the number of processes to match.
Note that the setting that's in effect when a sort code is loaded is
the one that determines how many processes will be used. The default
when Sunsort starts up is 1 (multi-processing disabled).
Be warned with multi-processing that your init and finish code will get
run several times and out of order, that is processes may be sorting when
your init and finish codes run, consequently, if you have non-trivial
initialisation code (like you zero or recalculate a spectrum) then you
should not use this code. Since each process runs in its own memory space
you can initialise variables and arrays without worrying about
interference between processes. Be warned however, that although each
finish routine sees the spectrum data for all processes, data stored in
local memory can only be accessed by the local process.
Filtering data with multi-process code is OK, however events may emerge
out of order in the output stream.
Note that if you run Sunsort on a single processor machine, it will ignore
this setting and always use the single processor version of the code.
To get the multi-process code working I've had to use a number of
sophisticated techniques. Fingers crossed if things go wrong it should fall
back to single process code.
printvars
printvars produces a list of the array indices, names and current
values of all the variables accessible from the user's sort program
as described in The Sunsort Reference Manual.
For example if the printvars command gives output:
1 egain 1.02
2 degain 1.001
then within the FORTRAN subroutine init the array element var(1) =
1.02 and var(2) = 1.001. In a C sort code vars_.var[0] = 1.02 and
vars_.var[1] = 1.001. To get round this confusion, it is recommended
that in C sort codes the VAR macro is used instead. With the above
variable definitions, VAR(1) will return 1.02, and VAR(2) will
return 1.001.
Using this command inside a batch file is pointless.
refresh seconds
Results in Sunsort sending a request to its 1d and 2d graphics
processes every seconds asking them to update the current
displayed spectra.
It is unlikely that this is useful inside a batch file.
reset job
Issuing the reset command causes Sunsort to send a SIGKILL to the
process specified by the argument job and then attempt to restart
it. Allowed values for this argument are:
- graphics: reset the graphics processes
- gui: reset the GUI
It is unlikely that this is useful inside a batch file.
save type save_directory format
[overwrite]
This command is used to store the data held in Sunsort's
spectra/variables to disk as files in the directory save directory.
The type argument specifies which category of file
Sunsort will attempt to save and may take one of the following
string values:
- all: all spectra in specified directory
- windows: all 2d window spectra
- variables: attempt to save the variables to
save directory/.variables
- selected: prompt the user for a list of 1d and 2d spectrum
numbers to be saved
The user must also provide an argument to tell Sunsort which format
encoder to use during the saving of the data to file. Allowed
format values are:
- sdb: NSF sdb spectrum database format
- eg: the Eurogam format
- xy: ASCII text x verses y format
The last save argument overwrite (which is optional) will, if set
to 1, allow Sunsort to overwrite any files that already exist in the
save directory. For example:
save all /stage/sjah sdb 1
setsenv variable_name new_value
This command assigns a new value to the Sunsort state variable
specified by the argument variable_name (see printsenv command).
The values given to these variables affect various operations in
Sunsort such as the block lengths used in data I/O and which data
format decoder is to be employed. For example to use the default
format and decoder for Eurogam style data one would type:
setsenv format egam
setwin window_nos on 2d_spectrum_nos
Results in Sunsort sending a request to its 2d graphics process
asking it to display the designated 2d spectrum and giving it access
permission to modify the specified 2d window spectrum. For example:
setwin 32 on 1
This command should not be used inside a batch file.
sleep seconds
This command results in Sunsort suspending all operations for a
number of seconds given by the commands one and only argument.
sort skip_records records_to_sort
The sort command instructs Sunsort to start reading data from its
READ data stream and to pass it on to the user's sort process. The
skip_records specifies the number of data records to be jumped
over before event by event processing commences. Reading of the
input data stream will stop after records_to_sort number of
records have been sorted or in the event of an error/end of data
condition being encountered. For example, to ask Sunsort to process
the first 10000 event records in a data file use:
sort 0 10000
This command will fail if Sunsort's READ data stream has not already
been connected to a data file using the open command.
status
This command produces a listing of the current status of Sunsort.
Using this command inside a batch file is pointless.
tapemount volume_label drive_nos access_mode
The tapemount command is used to attach a physical tape device (for
instance /dev/rmt/0) to Sunsort and must be issued before the user
can open a data file upon the tape. The volume_label argument
must contain the name used to label the tape if it is in an ANSI
format or nonansi if not. The other two arguments specify the drive
number in which the tape is to be found and whether the tape is to
be accessed for reading data (access mode r) or for writing data
(access mode w). For example, to mount the Charissa E-by-E data tape
oxfc06 on drive 1 use:
tapemount oxfc06 1 r
tapemove nos_of_files
This command enables the user to reposition the tape currently
mounted in Sunsort for READING. It's one and only argument specifies
the number of data files (ANSI format) or tape marks (nonansi) to be
skipped. If this number is larger than the number of files left on
an ANSI tape, tapemove will fail and will attempt to return the tape
to the beginning of the tape's first data file. This command will
also fail if a data file is currently open. For example, to skip
back two data files use:
tapemove -2
tapeumount access_mode
Will unload the currently mounted read tape if access mode = r or
the write tape if access mode = w. If the access mode argument is
not specified then by default the read tape is unmounted. (See
tapemount and eject commands). Note that if a tape file is still
open (see open and close commands) then this command will fail.
update
This command tells the GUI to reacquire its list of variables from
the main process. Use this command after using the var command.
var variable_nos new_value
This command assigns a new value new_value to the user variable
specified by the argument variable_nos (see printvars command).
For example with the variables set up as in the description of
printvars above, after issuing:
var 2 0.001
the printvars command will report something like this:
1 egain 1.02
2 degain 0.001
Note that the GUI display of variables is not updated if you use
this command. Issue the command update to get the display right.
vars
Short hand version of the printvars command.
Using this command inside a batch file is pointless.
wclose destination
Closes the file connection to Sunsort's WRITE data stream (see the
wopen command). One of the optional strings tape and
disk may be used although their use is rather superfluous.
wopen destination write_file
The wopen command is used to connect a data file of name
write_file to Sunsort's WRITE data stream. The storage media upon
which the data file resides is specified by the argument
destination and can be one disk or tape.
Once a successful wopen command has been issued and until a wclose
command is issued or an error condition is encountered, setting the
variable wrtevt to .TRUE. (or adcs_.wrtevt to 1) within the user's
sort code will result in the particular event being processed by
init being written to Sunsort's WRITE data stream.
Examples:
wopen disk /stage/sjah/run37f
wopen tape run37f
Note that in order to be able to wopen a tape file, a successful
mount (see tapemount command) must already have performed.
wrsort line_to_go_to_sort_process
This command queues up the specified text to go to the sort
process as soon as sorting starts. For technical reasons, from
batch files, this command must be given before you start sorting.
So the interactive sequence:
sort 0 1000
calib.dat
would become the following in a batch file:
wrsort calib.dat
sort 0 1000
It is recommended, however, that if you intend to run a sort code
from a batch file that you instead recode the sort code to not
need any user input.
Steven M. Singer
Last modified: Wed Sep 29 18:31:11 BST 1999