20. 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:
20.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 V2023.2\lib\api\MATLAB\reactis
or (if running a 32-bit Reactis within a 64-bit version of Windows):
C:\Program Files (x86)\Reactis V2023.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:
20.2. Using the Reactis API from C Programs#
20.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
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
.csvsuffix. 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.
20.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.
#include "reactis.h"at the top of your C (or C++) code. This compiler directive specifies the names, parameters and return values of the Reactis API functions.
Add a suitable
.liblibrary file to your linker options to specify to the linker how to find the Reactis API functions in the “libreactis.dll” dynamic link library. Unfortunately, different compilers use different
.libfile formats. The Reactis distribution contains
.libfiles suitable for a few compilers:
- Microsoft Visual C++ .net, 7.0, 8.0, 2005 and 2008
The correct library file for this compiler is
The Gnu C compiler included in distributions like Cygwin or MinGW accepts the Microsoft
.libfile format. Use
- MathWorks “mex” compiler
If you want to use Reactis API functions in code compiled with the “mex” compiler tool distributed with MATLAB, use the
If you are using a compiler that is not listed, you can try the following:
Some compilers include tools that can create
.libfiles from a given
DLL. Check whether that is true for your compiler. If so, create a
libreactis.dlland use that.
Other compilers accept the Microsoft
.libfile format. Try adding
libreactis_vc.libto your linker input settings.
Send an email to
firstname.lastname@example.org your compiler type and version. We will try to generate a matching “.lib” file as soon as possible.
Compile your application. The way to do this is highly dependent on your compiler and application code. For example, to compile the “apitest.c” example using GCC, type
gcc -o apitest.exe apitest.c libreactis_vc.lib
Add the Reactis “
lib\api” folder (e.g.,
c:\Program Files\Reactis\lib\api) to your Windows search path. This is necessary so your application can locate the
libreactis.dlllibrary. Alternatively, you can copy
libreactis.dllinto the folder where your application’s executable file is located.
20.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
subfolder in your Reactis distribution:
Header file containing declarations for the API functions.
Library file suitable for Microsoft Visual C++ and GCC.
Library file suitable for MathWorks
Example program to illustrate how to use the API functions.
Compiled version of apitest.c
Dynamic Link Library containing implementations of the API functions.