Chapter 18 The Reactis API
The Reactis Application Programming Interface (API) enables users
to access much of the tool’s functionality from MATLAB or from C programs.
This chapter provides a brief introduction to the use of the API. For
detailed descriptions of all functions available in both the MATLAB and
C bindings, please see:
https://reactive-systems.com/api.msp
18.1 Using the Reactis API from MATLAB
It is easy to access the Reactis API from the MATLAB command line, from
MATLAB scripts, or from MATLAB functions using a library of MATLAB
functions included in the Reactis distribution. To use this API, add
folder lib\api\MATLAB\reactis
within the Reactis installation
directory to the MATLAB search path. If you used the default settings
during the Reactis installation then the correct folder is:
C:\Program Files\Reactis
V2020.2\lib\api\MATLAB\reactis
or (if running a 32-bit Reactis within a 64-bit version of Windows):
C:\Program Files (x86)\Reactis
V2020.2\lib\api\MATLAB\reactis
After adding the folder, you can get information about the Reactis API functions
via the regular MATLAB help functionality. For example, typing “help reactis”
on the MATLAB command line will list information about all Reactis API functions.
Detailed information for each function can be accessed by typing “help [functionname]”
or “doc [functionname]”.
Some examples for using the API can be found in the following folder within the Reactis
installation directory: lib\api\MATLAB\reactis\examples
18.2 Using the Reactis API from C Programs
18.2.1 Quick Start
The following usage scenario highlights the most important functions in the
API and explains the order in which to call them. A more detailed sample
program apitest.c
is included in the distribution to demonstrate
more aspects of how to use the API.
Assume you want to do the following:
-
Create a test suite for a model
- Export the test suite in CSV format to run it in a hardware in
the loop environment.
You will need to call the following functions to accomplish this task:
-
Call rsOpen to receive a RsHandle value which all other
API functions require as a parameter. In the following, the term
RsHandle will refer to the handle returned by this call.
- Call rsTester passing the RsHandle, a model file name
and other parameters according to the documentation of rsTester.
This will create a test suite and return an RsTestSuite value (an
abstract data structure representing the generated test suite).
- If the rsTester call in the previous step fails, call rsGetLastError
to retrieve a description of the problem that caused the call to fail.
This can be done if any of the API functions fail.
- Call the rsGetCoverageCriteria functions to retrieve coverage
of the test suite that was just created.
- Call rsSimOpen passing the RsHandle, and a model file name.
This will return a RsSim value which serves as a handle to the newly created
Simulator session.
- Call rsSimExportSuite passing the RsSim handle returned by
rsSimOpen, the RsTestSuite value returned by rsTester and a filename
with a
.csv
suffix. This will export the test suite created in
step two in the CSV format supported by Reactis.
- Call rsSimClose passing the RsSim handle returned by rsSimOpen.
rsSimClose will free all memory allocated by the Simulator functions.
- Call rsClose, passing the RsHandle as an argument. This will
free all memory allocated by the Reactis API.
18.2.2 Compiling a C or C++ program with the Reactis API
You can compile and run an application that uses the Reactis API as follows.
18.2.3 Reactis API Files for C Programming
The following is a description of files distributed with Reactis
that are related to the Reactis API. You can find these files in
the lib\api
subfolder in your Reactis distribution:
-
reactis.h
-
Header file containing declarations for the API functions.
- libreactis_vc.lib
-
Library file suitable for Microsoft Visual C++ and GCC.
- libreactis_lcc.lib
-
Library file suitable for MathWorks
mex
compiler.
- libreactis.lib
-
Same as
libreactis_vc.lib
- apitest.c
-
Example program to illustrate how to use the API functions.
- apitest.exe
-
Compiled version of apitest.c
- libreactis.dll
-
Dynamic Link Library containing implementations of the API
functions.