Chapter 15 The Reactis for C API
The Reactis for C 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/doc/reactis-for-c/api.
15.1 Using the Reactis for C 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\reactis4c
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
V2022\lib\api\MATLAB\reactis4c
or (if running a 32-bit Reactis within a 64-bit version of Windows):
C:\Program Files (x86)\Reactis
V2022\lib\api\MATLAB\reactis4c
After adding the folder, you can get information about the Reactis API functions
via the regular MATLAB help functionality. For example, typing help reactis4c
on the MATLAB command line will list information about all Reactis API functions.
Detailed information for each function can be accessed by typing help function
or doc function.
Some examples for using the API can be found in the following folder within the Reactis for C
installation directory: lib\api\MATLAB\reactis4c\examples
15.2 Using the Reactis for C API from C Programs
15.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 rcOpen to receive an RcHandle value which all other
API functions require as a parameter. In the following, the term
RcHandle will refer to the handle returned by this call.
- Call rcTester passing the RcHandle, a model file name
and other parameters according to the documentation of rcTester.
This will create a test suite and return an RcTestSuite value (an
abstract data structure representing the generated test suite).
- If the rcTester call in the previous step fails, call rcGetLastError
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 rcGetCoverageCriteria functions to retrieve coverage
of the test suite that was just created.
- Call rcSimOpen passing the RcHandle, and a model file name.
This will return a RcSim value which serves as a handle to the newly created
Simulator session.
- Call rcSimExportSuite passing the RcSim handle returned by
rcSimOpen, the RcTestSuite value returned by rcTester 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 rcSimClose passing the RcSim handle returned by rcSimOpen.
rcSimClose will free all memory allocated by the Simulator functions.
- Call rcClose, passing the RcHandle as an argument. This will
free all memory allocated by the Reactis for C API.
15.3 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
libreactis4c.lib
to the linker arguments,
so that the linker will be able to find the functions in
libreactis4c.dll
.libreactis4c.lib
will work with a wide range
of C compilers, including Microsoft compilers and any compiler which accepts
Microsoft .lib format, such as the Gnu C compiler (GCC).
If you are using a compiler that does not accept Microsoft .lib format,
check to see if your compiler
includes a tool which can create .lib
files from a
.dll
file. If so, use it to create a .lib
library from libreactis4c.dll
which is compatible with your compiler.
If no tool is available, send an email to help@reactive-systems.com describing your compiler type and version,
and 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, the following command
compiles apitest.c using GCC:
gcc -o apitest.exe apitest.c libreactis4c.lib
- Add the Reactis
lib\api
folder
(e.g., C:\Program Files\Reactis for C V2020\lib\api
)
to your Windows search path, so that your application can find the
libreactis.dll
library. Alternatively, you can copy libreactis.dll
into
the folder where your application’s executable file is located.
15.4 Reactis API files
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:
reactis4c.h | Header file containing declarations for the API functions. |
libreactis4c.lib | Library file suitable for Microsoft Visual C++ and GCC. |
apitest4c.c | Example program to illustrate how to use the API functions. |
apitest4c.exe | Compiled version of apitest4c.c. |
libreactis.dll | Dynamic library containing the API functions.
|
15.5 C Coverage Details
The rcSimExportCCoverageDetails API call produces a primary output file containing
target coverage information for C source code and an optional second file
containing data for targets generated by macro expansion.
Each row of data in the primary output file contains the following columns:
-
The target id number (1 … n, where n is the number of targets).
- A string describing the target kind:
"s" | Statement |
"dt" | Decision true |
"df" | Decision false |
"ct" | Condition true |
"cf" | Condition false |
"m" | MC/DC
|
- For condition targets, this field contains the id number of the
decision target which contains the condition target.
For MC/DC targets, this field contains the id number of the corresponding
condition-true target.
For decision and statement targets, this field will be zero.
- The coverage status of the target (1 if covered, 0 if uncovered).
- The test number in which the target was covered (-1 if uncovered or unknown).
- The step number in which the target was covered (-1 if uncovered or unknown).
- The path to the program component containing the target.
This is useful when the same source file is used in more than one S-function.
- The pathname of the C source file to which the target belongs.
- The starting line number of the target.
- The starting column number of the target.
- The ending line number of the target.
- The ending column of the target.
- If the target is not defined within a macro expansion, this field will be
zero. If the field is positive, it will contain an id number which
can be used to find the macro expansion data in the macro data file.
- The starting line within the macro expansion of the target.
- The starting column within the macro expansion of the target.
- The ending line within the macro expansion of the target.
- The ending column within the macro expansion of the target.
Notes:
-
All strings are encoded as C literals.
- All numbers are encoded as decimal integers.
- Target ids, macro ids, lines and columns are numbered starting with 1 (not zero).
- For targets within macro expansions, the starting and ending source file locations
will be the points where the macro expansion started and ended.
- If the target is not defined within
a macro expansion, then columns 13-17
will contain zeros.
-
If no macro data file is generated, then columns 13-17
will be omitted (the CSV data will contain only 12 columns).
15.5.1 Macro file format
Each row of CSV data in the secondary macro information file
contains the following columns:
-
The id number of the macro expansion (1 … n, where n
is the number of macro expansions).
- The name of the macro which was expanded.
- The file where the macro was defined.
- The line number where the macro was defined.
- The column number where the macro was defined (should always be 1).
- The line number where the macro definition ended.
- The column number where the macro definition ended.
- The file in which the macro invocation occurred.
- The line number at which the macro invocation started.
- The column number at which the macro invocation started.
- The line number at which the macro invocation ended.
- The column number at which the macro invocation ended.
- The text of the macro expansion, encoded as a C string literal.
Notes:
-
All strings are encoded as C literals.
- All numbers are encoded in decimal.
- Macro ids, lines and columns are numbered starting with 1.