Document version 31-July-2003
Jussi Markkanen
There is new functionality in the runexperiment
command, but some features have been taken away, and some have been moved to
other commands.
1.1
A backstep is that experiments cannot any more
be queued. If an experiment is running and you try to start a new one, EROS
immediately refuses to accept the new experiment. Queuing has not worked
reliably, and has often hanged EROS.
1.2 Another inconvenience is that an explicit starttime
is now obligatory in the runexperiment
command, as the second parameter:
runexperiment
ElanFile StartTime ?arg arg ...?
If you want to start
immediately, use "now" as the time parameter,
run tau1 now,
and if you want to start at next full minute,
use
run tau1 fullminute.
The purpose of this change is to reduce the
risk of bad start times, and also reduce confusion when a variable amount of
parameters (the args) is now possible in the run command, see (1.4).
1.3 The -test option has been removed from the run command. There is now a separate testexperiment command, see section 2.
1.4 It is now possible to feed parameters to the experiment script at experiment start time, using the runexperiment command. All parameters after the second parameter, the starttime, in the runexperiment command are made available to the script via a new EROS command, argv. The argv command returns a list containing those parameters. One possibility to make use of them is to have the following structure in the elan file.
BLOCK tau1 { {scan cp1} {owner CP} {height 292.9} } {
...
...
};#endblock
eval callblock tau1 [argv]
For a complete example, see
/kst/eros4/exp/tau1.elan.
Instead of BLOCK tau1, you could also use the standard tcl procedure
declaration, proc tau1. The proc would then be invoked in the
normal tcl way,
eval tau1 [argv].
The BLOCK/callblock is recommended, for it allows EROS to perform some bookkeeping
and cleanup.
Note the use of the tcl eval command in
front of the EROS callblock command when
invoking the tau1 BLOCK in the elan
file. The eval is necessary if argv returns more than one parameter.
Note also the use of callblock, not gotoblock, in this kind of context. A callblock command does not affect experiment syncronization, but
a gotoblock command has a time parameter
that must be taken care off. Gotoblock
is normally more useful when used interactively.
The above tau1 BLOCK has default values
for all three of its formal parameters. Therefore, it can be called with zero, one, two or three
arguments. For example,
runexperiment tau1
13:00
==> tau1 is called without arguments, and
hence uses the default values for all three parameters.
runexperiment tau1
13:00 cp3
==> tau1 is called with argument cp3, and "owner" and "height"
get the default values.
There is a new testexperiment command. When an experiment is started with the testexperiment command, no data is recorded, and no logbook entries
are made. No entries are made to the official EROS log, such as /kst/log/SODlog.log
either, but instead, log entries are made to
test-log, such as /kst/log/SODtestlog.log.
By default, an experiment
started using the testexperiment command
does not move the antenna, and the EROS messages window says that
"Antenna access blocked by eros".
The syntax of testexperiment command is
testexperiment
?Options? Elanfile Starttime ?Arg Arg ...?
Options: -useant
-noant (default)
Ex.1. test tau1 now
Ex.2. test -useant tau1 10:30 cp3
If you want allow antenna motion during a testexperiment, you must explicitly use the -useant option as in the above Ex.2.
IMPORTANT. When a testexperiment is
active in the default (-noant) mode,
also interactive antenna
commands, including setting antenna to standby and computer mode, are disabled.
Even the automatic setting of antenna to standby by EROS does not work.
When a testexperiment is running, the printexperiment output looks something like this
TEST EXPERIMENT (SOD) 23-Jul-2003 17:04:29.7
--------------------------------------------
Exp file : tau1.elan
dir :
/work/kst/exp
state : RUNNING since
23-Jul 17:03:31.8
...
A facility similar to the old EROS II IPAR/RPAR has been implemented to get
user definable parameters recorded into the parameter block (d_parbl).
In current implementation, 20 locations in the d_parbl vector in the data dump
are reserved for the user parameters. Each variable is a 8-byte real
("double") value, there are no integer-type user parameters. The
variables are kept in the EROS rt-common as doubles, but in the present
implementation, are read and written there via a four decimal digit fixed-point
string representation. This means that an attempt to set an upar to the value
0.00004 will set it to (exact) zero instead. This implementation may change in
the future.
The new eros command to access the upars, either interactively or in an elan
file, is upar, see below for usage.
Implementing upar required expanding the rt-common data structure, defined in /kst/dsp/include/kstsys.h. Many programs
depending on that header file required recompilations. I have compiled many of
them in Sodankyla, but not necessarily all.
The parameterblock version number (d_parbl(40)) was changed from 2.1 to 2.2.
Starting from 2.2, Upar(1-20) are available in d_parbl(43-62).
3.1
The EROS command to read current value of a user parameter, directly from the
rt-common (the upars are stored in the rt-common so that they will always be
up-to-date), is
upar Index,
where Index is from 1 to MAX_UPAR, which currently is 20.
The Index can also be the keyword "all" to return a list of all
MAX_UPAR values, or can be a list of indexes, to return a subset. For example,
upar 1
returns the value of first upar, upar(1), which is in the parameter block
location d_parbl(43), and
upar { 2 5 }
returns the values of upar(2) and upar(5).
To make use of an upar value in EROS commands, the standard tcl bracket syntax
must be used. For example, if upar(2) stores the desired common volume
altitude, we can use that value in a pointing command as
pointrheight 180 70 [upar 2]
3.2 The EROS command to set an upar's value (in the rt-common) is
upar Index Value
For example, to set upar(2) to 295.6, use the
command
upar 2 295.6
EROS does not explicitly initialize the upars,
because it is not clear when such an initialization should be done. It could be that a user wants to preserve upar values from
experiment to experiment, say. However, it is possible to use an explicit
command like
upar all -1,
either interactively or in the elan file, to
set all upars to a known initial value.
3.3
The upar
command syntax allows simple arithmetic to be done in a simpler way compared to
the standard tcl math command, expr,
using c-language-mimicking operators. For example,
upar 5 ++ ==>
increment upar(5) by one
upar 5 -- ==>
decrement upar(5) by one
upar 5 += 2.5 ==> increment upar(5) by 2.5
upar 5 *= 2.5 ==> multiply upar(5) by 2.5
With the standard expr command, the first example would have to be written
as
upar 5 [expr [upar 5]
+ 1 ]
The command
writeexperimentfile
Filelist Directory
copies the files listed in Filelist to the
specified Directory. If no Directory is specified, that is, we use
writeexperimentfile
Filelist
the files are copied to a daily subdirectory of the experiment's "information
directory", as required by the archiver. The name of the information
directory is deduced from the experiment identifier, ExpID, of the current (or
last run) experiment. The ExpID is a required parameter of the EROS startdata command. After the startdata command is given, normally in the elan file, EROS
knows the ExpID, and can form the information directory name. (EROS uses ExpID
also to form the name of the actual data directories.) Therefore, in an elan
file, writeexperimentfile Filelist
command should come only after
the startdata command.
...
set Expfiles [list \
$XDIR/tau1.elan
$SCAN_FILE \
$XDIR/tau1-r.tlan
$XDIR/tau1-u.tlan $XDIR/tau1-v.tlan \
$NCO1 $NCO2 $NCO4
$NCO5 $Filter12 $Filter45 \
$Corrfile ]
...
startdata $Corrfile
$Expid $Iper_us
writeexperimentfile
$Expfiles
...
If the information directory does not exist, EROS attempts to create it, including all necessary higher level directories.
Note that in testexperiment mode, the writeexperimentfile shows the names of the directories it would create, but does not actually create them. Nor does it copy any of the files.
There are no defaults for the Filelist. All desired files
must be specified explicitly, and preferably using absolute path names (there
is no guarantee about what is the working directory when the experiment is
run).
Until we get our experiment directories drastically purged, it could be helpful to be able to use the unix find command to search for stuff. The new findfile EROS command implements a restricted form of find. For example, the EROS command
findfile tau1*.elan
maps to the unix command
find /kst/exp -name
"tau1*.elan" -print
irrespective of what is the current working
directory. If some other search root directory than /kst/exp is required, it can be specified explicitly, for
example,
findfile /kst *.fir
uses /kst
as the search root directory.
There is a new EROS
command, printdata, to summarize data
access status, with the following output format
DATA ACCESS (SOD) 29-Jul-2003 00:52:25.9
----------------------------------------
Data
access : running
Recording : enabled
Corr
program : /kst/exp/tau1/tau1-r.fil
ExpId
: kst0 tau1r_cp1_1.30_CP
Integration : 5.0 s
Disk : /data1
(14.415 GB avail)
Data path :
tau1r_cp1_1.30_CP@sod
Latest
dump :
20030729_00/18060744.mat
time : 29-Jul 00:52:25
The first field (Data access) can be "running" or "stopped". The second field shows the status of the enablerecording bit as read from the rt-common. This bit is controlled by the disablerecording and enablerecording commands. Correlator program name and the "experiment identifier" string are got via the latest startdata command. The fields Disk, Data path and Latest dump show the file path name components of the latest data dump.
The EROS4 script (normally
executed via the Eros command) can do a few other things besides kicking EROS
running. These utilities are accessed by the commands
Eros check
Eros kill
Eros printant
Eros printdata
Eros printexp
The commands must be given in the main process
computer (t4501 etc). The commands might be useful e.g. when the on-duty person
logs-on to the site from home and wants to see how EROS is doing.
The command
Eros check ?LocalRadar?
checks whether the various EROS wishe processes are running. When all processes are found, the output should be similar to the following.
eiscat@s2501:/home/eiscat> Eros check
Checking EROS4 processes in SOD ...
SOD_MONITOR:
running (2)
SOD_EXPDOER:
running (2)
SOD_EXPRUN: running
(2)
SOD_COMPRO:
running (2)
SOD_ACU in
s5011.eiscat.sgo.fi: running (2)
The command
Eros kill
?LocalRadar?
can be tried to get rid of a hanging or
otherwise misbehaving EROS. You must be logged-in either as root or as the
owner of the EROS processes (which is either eiscat or kstdev, but you must
know which one) to be able to do the kill.
The print commands
Eros printXXX
?LocalRadar?
require that EROS is running, and return the
same status info as when the commands is given from EROS console.
The command
Eros simulate
?RadarName?
starts EROS simulation. The simulation runs
entirely on the local computer, no network is needed. The simulation is mainly
intended for EROS development, but should also be useful when testing
experiment files for syntax errors and general structure, when the official
EROS is not available.
Note that in the present implementation only a single simulated EROS can be
running on a given computer. That is because the simulation (as well as the
real EROS) create an "rt-common" in a fixed location in the memory of
the computer which runs the EROS "acu" process. Therefore:
WARNING. Do not run the simulation on the receiver crate computer (which hosts
the real rt-common).
It is safe to run the simulation on the main server, even simultaneously with
the actual EROS.
I have ported the simulated EROS to Mac OS X also. Those interested can ask me
for more details about how to set up the necessary X11/tcl/tk environment.
Eros online help is slightly changed. The EROS command
help CommandName
now always shows as much help as is available,
not only the command's parameter list. I have also updated the help information
for several -- but not nearly all -- individual commands. The help command
without arguments now also prints out a pointer to the EROS-related web pages
in HQ.
There is now a master makefile /kst/eros4/Makefile
that attempts to build all binaries actually used to run experiments, but not
too many of the innumerable test programs and old versions that litter the /kst/bin directory at the moment.
The master makefile invokes recursively five other makefiles. Those makefiles
have been slightly reorganized, especially, they all now initially build
executables to the source directories only -- a "make install" is
required to copy the executables to the kst/bin
directory where EROS can see them.
WARNING. The build system has been tested only in Sodankyla. The directory
structures even on the mainland sites are slightly different, most especially
with regard to the contents of /opt
and opt1, and this means that the
makefiles will not work at the other sites without modifications.
Also, there are some OS-dependent stuff incorporated in the makefiles, with the
purpose of allowing EROS, in simulation mode, to run natively on Mac OS X
("Darwin") also.
The changes described in this document have so far (30-Jul-2003) been implemented only at the Sodankyla site. The changes have been checked in to EISCAT CVS repository, but have not been implemented at the other sites.