• Antelope Release 5.5 Linux 2.6.32-220.el6.x86_64 2015-04-21

 

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

PARAMETER FILE

Parameters

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
Printer icon