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

16.1. Using the Reactis for C API from MATLAB#

It is easy to access the Reactis for C API from the MATLAB command line, from MATLAB scripts, or from MATLAB functions using a library of MATLAB functions included in the Reactis for C distribution. To use the 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 V2024\lib\api\MATLAB\reactis4c

After adding the folder, you can get information about the Reactis for C API functions via the regular MATLAB help functionality. For example, typing help reactis4c on the MATLAB command line will list information about all Reactis for C 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: examples\api\MATLAB

16.2. Using the Reactis for C API from C Programs#

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

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

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

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

  4. Call the rcGetCoverageCriteria functions to retrieve coverage of the test suite that was just created.

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

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

  7. Call rcSimClose passing the RcSim handle returned by rcSimOpen. rcSimClose will free all memory allocated by the Simulator functions.

  8. Call rcClose, passing the RcHandle as an argument. This will free all memory allocated by the Reactis for C API.

16.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 for C lib\api\c\win64 folder (e.g., C:\Program Files\Reactis for C V2024\lib\api\c\win64) 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.

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

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

  1. The target id number (1 … n, where n is the number of targets).

  2. A string describing the target kind:

    s

    Statement

    dt

    Decision true

    df

    Decision false

    ct

    Condition true

    cf

    Condition false

    m

    MC/DC

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

  4. The coverage status of the target (1 if covered, 0 if uncovered).

  5. The test number in which the target was covered (-1 if uncovered or unknown).

  6. The step number in which the target was covered (-1 if uncovered or unknown).

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

  8. The pathname of the C source file to which the target belongs.

  9. The starting line number of the target.

  10. The starting column number of the target.

  11. The ending line number of the target.

  1. The ending column of the target.

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

  2. The starting line within the macro expansion of the target.

  3. The starting column within the macro expansion of the target.

  4. The ending line within the macro expansion of the target.

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

16.5.1. Macro file format#

Each row of CSV data in the secondary macro information file contains the following columns:

  1. The id number of the macro expansion (1 … n, where n is the number of macro expansions).

  2. The name of the macro which was expanded.

  3. The file where the macro was defined.

  4. The line number where the macro was defined.

  5. The column number where the macro was defined (should always be 1).

  6. The line number where the macro definition ended.

  7. The column number where the macro definition ended.

  8. The file in which the macro invocation occurred.

  9. The line number at which the macro invocation started.

  10. The column number at which the macro invocation started.

  11. The line number at which the macro invocation ended.

  12. The column number at which the macro invocation ended.

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