NAME
rtrun_matlab - run a Matlab process under an Antelope real-time system
SYNOPSIS
rtrun_matlab [-s] [-v] [-p pfname] [-l lockfile]
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
rtrun_matlab allows the user to run a Matlab process under an Antelope
real-time system, usually out of the
rtexec(1) cron table. All details of the
Matlab commands to be run, and how to run them, are stored in the
rtrun_matlab.pf parameter file (or alternate parameter-file name as specified
with the -p option). If the -l option is used to specify a lock file, multiple
instances of
rtrun_matlab will protect themselves from running simultaneously
(the first instance to acquire the lock will run; the rest of the
processes using the same lock file will exit immediately).
The unix command-line used to launch the Matlab interpreter should be
specified in the
matlab_interpreter parameter of the parameter file. The
matlab_timeout_sec parameter specifies the maximum number of seconds
the Matlab interpreter is allowed to run. If this is exceeded, the Matlab
process is killed and
rtrun_matlab exits. A
matlab_timeout_sec value
of 0 will allow the interpreter to run indefinitely.
rtrun_matlab builds two preparatory files for the Matlab interpreter before
launching it. The first is a parameter file with the contents of the
matlab_pf array from
rtrun_matlab.pf. These parameters will be available to the
Matlab program during execution through the Matlab parameter-file variable
named by
matlab_pf_varname.
The second file is a script that will be given to the Matlab
interpreter to execute. The script that
rtrun_matlab gives to the
interpreter contains the commands in the
matlab_startup parameter if specified;
commands to add the Matlab paths specified in
matlab_paths; a command to make the contents of
matlab_pf available through the Matlab variable
matlab_pf_varname
(this variable will contain an Antelope parameter-file object);
and the literal contents of the
matlab_script parameter.
The
matlab_script parameter may very well hold only a single Matlab
command that launches the user's processing procedures through an m-file on
the path; or it may be a more involved script, specified verbatim.
OPTIONS
-
-p pfname
Specify an alternate parameter-file name (the default is rtrun_matlab.pf)
-
-v
Verbose
-
-l lockfile
Specify a lock file, for coordination amongst multiple instances of
rtrun_matlab.
-
-s
Save the temporary script and parameter files rather than deleting them
at the end of the run; also announce their location at the end of the run.
PARAMETER FILE
Parameters
-
matlab_interpreter
This parameter specifies the Unix executable command line that rtrun_matlab
will invoke to launch the Matlab interpreter.
-
matlab_startup
Once the Matlab interpreter is launched,
rtrun_matlab will run the Matlab command contained in the matlab_startup parameter
(usually a parameter-file Literal value as documented in pf(5)). If the value is left
blank, no startup commands will be run.
-
matlab_paths
If this parameter-file table is not empty, each line is interpreted as a pathname, which will
be added to the Matlab execution path after any startup command is run but before the Matlab
script is invoked.
-
matlab_script
After any startup commands are invoked in Matlab and any specified paths are added to the Matlab
execution path, rtrun_matlab will run the script specified in the matlab_script
parameter, usually a parameter-file Literal value.
-
matlab_pf_varname
The contents of a parameter-file for the matlab_script may be made available to it during
run-time. The matlab_pf_varname specifies the name within Matlab that the parameter-file
will have when matlab_script is running (rtrun_matlab will read this parameter file
automatically, so nothing explicit has to be done within matlab_script to make it available).
-
matlab_pf
This parameter gives the contents of the parameter-file named in matlab_pf_varname, to be
fed to the matlab_script.
-
matlab_timeout_sec
The matlab_timeout_sec parameter specifies the maximum number of seconds
the Matlab interpreter is allowed to run.
Parameter File Example
A basic example of the
rtrun_matlab.pf parameter file is as follows:
antelope &env(ANTELOPE)
matlab_interpreter matlab -nosplash -nodesktop -nojvm -nodisplay
matlab_timeout_sec 600
matlab_startup &Literal{
run '&antelope/setup.m'
}
matlab_paths &Tbl{
}
matlab_pf_varname Pf
matlab_pf &Arr{
dbname /opt/antelope/data/db/demo/demo
}
matlab_script &Literal{
dbname = pfget( Pf, 'dbname' )
db = dbopen( dbname, 'r' )
}
For more complicated situations where one set of commands, paths, etc
may be used with different input parameters to the Matlab script (i.e.
multiple instances of rtrun_matlab running the same Matlab code but with
different configurations, or the same Matlab path and interpreter but
different code and different configuration), one may
want to construct a master parameter file with most of the parameters,
then make subsidiary parameter files with the variable elements such as the
matlab_pf contents. This limits the need for repeating large pieces
of the configuration:
% cat rtrun_matlab.pf
matlab_interpreter matlab -nosplash -nodesktop -nojvm -nodisplay
matlab_timeout_sec 60
matlab_paths &Tbl{
/opt/antelope/4.8/data/matlab/antelope/antelope
/opt/antelope/4.8/data/matlab/antelope/scripts
/opt/antelope/4.8/data/matlab/antelope/user
}
matlab_pf_varname Pf
matlab_script &Literal{
dbname = pfget( Pf, 'dbname' )
table = pfget( Pf, 'table' )
db = dbopen( dbname, 'r' )
db = dblookup( db, '', table, '', '' )
nrecs = dbnrecs( db )
}
pf_revision_time 1152828315
% cat matlab_experiment1.pf
matlab_interpreter &ref(rtrun_matlab,matlab_interpreter)
matlab_timeout_sec &ref(rtrun_matlab,matlab_timeout_sec)
matlab_paths &ref(rtrun_matlab,matlab_paths)
matlab_pf_varname &ref(rtrun_matlab,matlab_pf_varname)
matlab_script &ref(rtrun_matlab,matlab_script)
matlab_pf &Arr{
dbname /opt/antelope/data/db/demo/demo
table origin
}
% cat matlab_experiment2.pf
matlab_interpreter &ref(rtrun_matlab,matlab_interpreter)
matlab_timeout_sec &ref(rtrun_matlab,matlab_timeout_sec)
matlab_paths &ref(rtrun_matlab,matlab_paths)
matlab_pf_varname &ref(rtrun_matlab,matlab_pf_varname)
matlab_script &ref(rtrun_matlab,matlab_script)
matlab_pf &Arr{
dbname /opt/antelope/data/db/demo/demo
table wfdisc
}
EXAMPLE
The following example uses the nested parameter-files shown in the
parameter-file section above:
% rtrun_matlab -v -s -p matlab_experiment1
rtrun_matlab: Started (pid 12453) with pf 'matlab_experiment1' at 7/14/2006 23:20:57.714
< M A T L A B >
Copyright 1984-2004 The MathWorks, Inc.
Version 7.0.0.19901 (R14)
May 06, 2004
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
addpath( '/opt/antelope/4.8/data/matlab/antelope/antelope' )
addpath( '/opt/antelope/4.8/data/matlab/antelope/scripts' )
addpath( '/opt/antelope/4.8/data/matlab/antelope/user' )
Pf = dbpf( '/tmp/rtrun_matlab_1001_12453.pf' )
Pf =
dbpf object: 1-by-1
dbname = pfget( Pf, 'dbname' )
dbname =
/opt/antelope/data/db/demo/demo
table = pfget( Pf, 'table' )
table =
origin
db = dbopen( dbname, 'r' )
db =
database: 0
table: -501
field: -501
record: -501
db = dblookup( db, '', table, '', '' )
db =
database: 0
table: 19
field: -501
record: -501
nrecs = dbnrecs( db )
nrecs =
1351
exit
rtrun_matlab: Saving temporary parameter-file '/tmp/rtrun_matlab_1001_12453.pf'
rtrun_matlab: Saving temporary script '/tmp/rtrun_matlab_1001_12453.m'
rtrun_matlab: Finished (pid 12453) with pf 'matlab_experiment1' at 7/14/2006 23:21:15.455
%
SEE ALSO
rtexec(1)
BUGS AND CAVEATS
If the system-wide or user-specific Matlab startup scripts are already
configured to include the Antelope directories, it should not be necessary
to add those Matlab paths again (as is done in the default parameter file
for
rtrun_matlab).
AUTHOR
Kent Lindquist
Lindquist Consulting
Antelope User Group Contributed Software