The Reactis API

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:

https://reactive-systems.com/api.msp

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 V2024\lib\api\MATLAB\reactis

or (if running a 32-bit Reactis within a 64-bit version of Windows):

C:\Program Files (x86)\Reactis V2024\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

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 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.

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.

Insert #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 .lib library 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 .lib file formats. The Reactis distribution contains .lib files suitable for a few compilers:

Microsoft Visual C++ .net, 7.0, 8.0, 2005 and 2008
The correct library file for this compiler is libreactis_vc.lib

GCC
The Gnu C compiler included in distributions like Cygwin or MinGW accepts the Microsoft .lib file format. Use libreactis_vc.lib

MathWorks “mex” compiler
If you want to use Reactis API functions in code compiled with the “mex” compiler tool distributed with MATLAB, use the libreactis_lcc.lib library file.

If you are using a compiler that is not listed, you can try the following:
- Some compilers include tools that can create .lib files from a given DLL. Check whether that is true for your compiler. If so, create a .lib library from libreactis.dll and use that.
- Other compilers accept the Microsoft .lib file format. Try adding libreactis_vc.lib to your linker input settings.
- Send an email to help@reactive-systems.com describing 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.dll library. Alternatively, you can copy libreactis.dll into 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 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.