Automated Testing and Validation with Reactis®

 
 Reactis for C User's Guide   Contents  |  Index
 Chapters:  1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17

Chapter 15  The Reactis API

15.1  Overview

The Reactis for C Application Programming Interface (API) enables users to access some of the Reactis for C’s functionality from C programs. The operations listed in the following section are implemented in the libreactis4c.dll library that is included in the Reactis for Cdistribution.

The following usage scenario highlights the most important functions in the API and explains the order in which to call them. A sample program apitest.c, which demonstrates how to use the API, is included in the distribution.

Assume you want to do the following:

  • Create a test suite for a program
  • 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 a 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 build 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 rcGetCoverageMetric  functions to retrieve coverage of the test suite that was just created.
  5. Call rcSimOpen  passing the RcHandle, and a build 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 API.

15.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 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, to compile the apitest.c example using GCC, type
    gcc -o apitest.exe apitest.c libreactis4c.lib
  • Add the Reactis lib\api folder (e.g., C:\Program Files\Reactis for C V2014\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.3  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.4  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.
  12. The ending column of the target.
  13. 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.
  14. The starting line within the macro expansion of the target.
  15. The starting column within the macro expansion of the target.
  16. The ending line within the macro expansion of the target.
  17. 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.4.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.

15.5  API Types

15.5.1  RcCoverageMetric 

Bit-mask type used to represent Reactis coverage metrics.

Associated Constants

Individual Coverage Metric Constants
RcCvgDecision Decision coverage metric.
RcCvgCondition Condition coverage metric.
RcCvgMCDC MC/DC coverage metric.
RcCvgMCC MCC coverage metric.
RcCvgBoundary Boundary coverage metric.
RcCvgUserTarget User-defined target coverage metric.
RcCvgAssertion Assertion coverage metric.
RcCvgCStatement C statement coverage metric.
RcCvgCFunction C function coverage metric.
RcCvgCFunctionCall C function call coverage metric.
 
Group Coverage Metric Constants
RcCvgAll The set of all coverage metrics.
RcCvgNone The empty set.
RcCvgDefault The default set of coverage metrics.
 (Includes all metrics except MCC.)
 
Other Related Constants
RcCvgNum The number of individual coverage metrics.

Names for coverage metrics are listed in Section 15.12.1.

15.5.2  RcHandle 

Abstract type used to manage Reactis API sessions.

15.5.3  RcReportConfig 

Abstract type used to configure Reactis test execution reports.

15.5.4  RcReportItem 

Bit-mask type used to select Reactis test execution report items.

Associated Constants

Individual Severity Constants
RcRptExportDate The time/date section of a report.
RcRptFilePaths The file paths section of a report.
RcRptTableOfContents The table of contents of a report.
RcRptSummary The execution summary section of a report.
RcRptFunCalls The function call counts section of a report.
RcRptCoverage The test coverage section of a report.
 
Group Severity Constants
RcRptAll The set of all report items
RcRptNone The empty set.
RcRptDefault The default set of report items.
 (Equivalent to RcRptAll .)
 
Other Related Constants
RcRptNum The number of individual report items.

Names for report items are listed in Section 15.12.2.

15.5.5  RcRshFile 

Abstract type used to access Reactis test harness libraries.

15.5.6  RcRshHarness 

Abstract type used to access Reactis test harnesses.

15.5.7  RcRshInterfaceLevel 

Enumerated type used to distinguish between C code names and test harness names when constructing an RcRshNameMap .

Associated Constants

Individual Severity Constants
RcCodeLevel The prefix/suffix applies to names in the C code.
RcHarnessLevel The prefix/suffix applies to names in the test harness.
 
Other Constants
RcRshInterfaceLevelFirst The smallest interface level.
RcRshInterfaceLevelLast The largest interface level.
RcRshInterfaceLevelCount The number of interface levels.
RcRshNumInterfaceLevels The number of interface levels.

15.5.8  RcRshNameMap 

Abstract type used to import Reactis test harnesses from Reactis info (.rsi) files.

15.5.9  RcRshVar 

Abstract type used to access variables used by Reactis test harnesses.

15.5.10  RcRshVarKind 

Enumerated type representing the purpose of a Reactis test harness variable.

Associated Constants

Individual Severity Constants
RcInputVar Variable is used as a harness output.
RcOutputVar Variable is used as a harness output.
RcConfigVar Variable is a configuration variable.
 
Other Constants
RcRshVarKindFirst The smallest variable kind.
RcRshVarKindLast The largest variable kind.
RcRshVarKindCount The number of variable kinds.
RcRshNumVarKinds The number of variable kinds.

Names for variable kinds are listed in Section 15.12.5.

15.5.11  RcSeverity 

Bit-mask type used to represent the severity of a message.

Associated Constants

Individual Severity Constants
RcSevNote Message is a not an error.
RcSevWarning Message is a potential error.
RcSevError Message is a definite error.
 
Group Severity Constants
RcSevAll The set of all message severities.
RcSevNone The empty set.
 
Other Constants
RcSevNum The number of individual severity values.

Names for these values are listed in Section 15.12.3.

15.5.12  RcSim 

Abstract type used to manage Reactis Simulator sessions.

15.5.13  RcTargetStatus 

Bit-mask type used to represent the status of a coverage target.

Associated Constants

Individual Severity Constants
RcTgtCovered Target is covered.
RcTgtUncovered Target is not covered.
RcTgtUnreachable Target is unreachable.
 
Group Severity Constants
RcTgtAll The set of all target statuses.
RcTgtNone The empty set.
RcRptDefault The default set of target statuses.
 (Equivalent to RcTgtAll .)
 
Other Constants
RcTgtNum The number of individual target status values.

Names for target status values are listed in Section 15.12.4.

15.5.14  RcTester 

Abstract type used to manage Reactis Tester sessions.

15.5.15  RcTestSuite 

Abstract type used to access Reactis test suites.

15.6  Alphabetical list of API functions

rcClose
rcCoverageMetricFromString
rcCoverageMetricToString
rcGetCoverageCriteriaCount
rcGetCoverageCriteriaName
rcGetCoverageCriteriaNumCovered
rcGetCoverageCriteriaNumTargets
rcGetCoverageCriteriaNumUncovered
rcGetCoverageCriteriaNumUnreachable
rcGetCoverageCriteriaPercentCovered
rcGetCoverageMetricCount
rcGetCoverageMetricName
rcGetCoverageMetricNumCovered
rcGetCoverageMetricNumTargets
rcGetCoverageMetricNumUncovered
rcGetCoverageMetricNumUnreachable
rcGetCoverageMetricPercentCovered
rcGetLastError
rcGetParameterValue
rcGetParameterValueBool
rcGetParameterValueDouble
rcOpen
rcReportConfig
rcReportConfigDefault
rcReportConfigClose
rcReportConfigGetDetailMetrics
rcReportConfigGetDetailStatus
rcReportConfigGetItems
rcReportConfigGetSummaryMetrics
rcReportConfigSetDetailMetrics
rcReportConfigSetDetailStatus
rcReportConfigSetItems
rcReportConfigSetSummaryMetrics
rcReportItemFromString
rcReportItemToString
rcRshClose
rcRshGetCoverageEnabled
rcRshGetCurrentHarness
rcRshGetEntryFunCandidateFullName
rcRshGetEntryFunCandidateName
rcRshGetHarness
rcRshGetNumEntryFunCandidates
rcRshGetNumHarnesses
rcRshGetParameterValue
rcRshHarnessAddVar
rcRshHarnessCheckVarCandidate
rcRshHarnessCopy
rcRshHarnessCreate
rcRshHarnessGetEntryFunFullName
rcRshHarnessGetEntryFunName
rcRshHarnessGetName
rcRshHarnessGetNumVarCandidates
rcRshHarnessGetNumVars
rcRshHarnessGetSampleRate
rcRshHarnessGetVar
rcRshHarnessGetVarCandidate
rcRshHarnessGetVarCandidateByFullName
rcRshHarnessImport
rcRshHarnessSetSampleRate
rcRshHarnessSync
rcRshNameMapClose
rcRshNameMapCreate
rcRshNameMapGetPrefix
rcRshNameMapGetSuffix
rcRshNameMapSetPrefix
rcRshNameMapSetSuffix
rcRshOpen
rcRshSave
rcRshSetCoverageEnabled
rcRshSetCurrentHarness
rcRshSetParameterValue
rcRshVarDelete
rcRshVarGetFullName
rcRshVarGetHarnessType
rcRshVarGetInternalType
rcRshVarGetKind
rcRshVarGetLocation
rcRshVarGetName
rcRshVarGetProperties
rcRshVarGetTolerance
rcRshVarHasProperty
rcRshVarKindFromIndex
rcRshVarKindFromString
rcRshVarKindIsValid
rcRshVarKindToIndex
rcRshVarKindToString
rcRshVarSetHarnessType
rcRshVarSetInternalType
rcRshVarSetName
rcRshVarSetTolerance
rcRsmAddDefine
rcRsmAddIncludeDir
rcRsmAddLibrary
rcRsmAddSourceFile
rcRsmClose
rcRsmGetCoverageEnabled
rcRsmGetDefine
rcRsmGetIncludeDir
rcRsmGetLibrary
rcRsmGetNumDefines
rcRsmGetNumIncludeDirs
rcRsmGetNumLibraries
rcRsmGetNumSourceFiles
rcRsmGetParameterValue
rcRsmGetSourceFile
rcRsmOpen
rcRsmRemoveDefine
rcRsmRemoveIncludeDir
rcRsmRemoveLibrary
rcRsmRemoveSourceFile
rcRsmSave
rcRsmSetCoverageEnabled
rcRsmSetParameterValue
rcRsmStub
rcSetParameterValue
rcSetStringEncoding
rcSeverityFromString
rcSeverityToString
rcSetParameterValue
rcSetStringEncoding
rcSeverityFromString
rcSeverityToString
rcSimClose
rcSimExportCCoverageDetails
rcSimExportSuite
rcSimExportSuiteEx
rcSimImportSuite
rcSimImportSuiteEx
rcSimImportSuites
rcSimOpen
rcSimRunSuite
rcSimRunSuiteWithReport
rcSimUpdateOutputs
rcSuiteClose
rcSuiteGetNumTests
rcSuiteGetReactisVersion
rcSuiteGetTestNumSteps
rcSuiteGetTestName
rcSuiteOpen
rcSuiteSave
rcTargetStatusFromString
rcTargetStatusToString
rcTester
rcTesterClose
rcTesterGetProgress
rcTesterGetStatus
rcTesterGetSuite
rcTesterIsRunning
rcTesterStart
rcTesterStartWithReport
rcTesterStop
rcTesterWithReport
rcVersion
rcVersionParse

15.7  API Operations

15.7.1   rcClose 

Terminates a Reactis API session.

Syntax

void rcClose (RcHandle *h);
Parameters
h
Pointer to an RcHandle structure as returned by rcOpen . This handle will be invalidated. Using the closed handle in subsequent to other API functions (including rcClose ) will cause the calling program to crash.
Return Value
None.

15.7.2   rcCoverageMetricFromString 

Converts a string to an individual RcCoverageMetric value.

Syntax

RcCoverageMetric  rcCoverageMetricFromString (const char *str);
Parameters
str
String holding the name of an RcCoverageMetric value. Recognized names are listed in Section 15.12.1.
Return Value
Returns an individual RcCoverageMetric value whose name matches str (using case-insensitive comparison). The RcCoverageMetric values are listed in Section 15.5.1.

Returns RcCvgNone if there is no match, in which case rcGetLastError should not be called.

15.7.3   rcCoverageMetricToString 

Converts an individual RcCoverageMetric value to a string.

Syntax

const char *rcCoverageMetricToString (RcCoverageMetric  metric);
Parameters
metric
One of the individual RcCoverageMetric values listed in Section 15.5.1.
Return Value
Returns a constant string representing the value of metric if metric is one of the individual coverage metric values. See Section 15.12.1 for the list of coverage metric names.

Returns NULL if metric is not one of the individual RcCoverageMetric values, in which case rcGetLastError should not be called.

15.7.4  rcGetCoverageCriteriaCount 

This function is an alias for rcGetCoverageMetricCount .

15.7.5  rcGetCoverageCriteriaName 

This function is an alias for rcGetCoverageMetricName .

15.7.6  rcGetCoverageCriteriaNumCovered 

This function is an alias for rcGetCoverageMetricNumCovered .

15.7.7  rcGetCoverageCriteriaNumTargets 

This function is an alias for rcGetCoverageMetricNumTargets .

15.7.8  rcGetCoverageCriteriaNumUncovered 

This function is an alias for rcGetCoverageMetricNumUncovered .

15.7.9  rcGetCoverageCriteriaNumUnreachable 

This function is an alias for rcGetCoverageMetricNumUnreachable .

15.7.10  rcGetCoverageCriteriaPercentCovered 

This function is an alias for rcGetCoverageMetricPercentCovered .

15.7.11   rcGetCoverageMetricCount 

Returns the number of coverage metrics corresponding to most recent call to rcTester or rcSimRunSuite .

Syntax

int rcGetCoverageMetricCount (RcHandle *h);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
Return Value
Number of coverage metrics being tracked. When calling any of the rcGetCoverageMetric functions, the ’index’ parameter must be less than the value returned by rcGetCoverageMetricCount .

The return value is 0 if rcTester or rcSimRunSuite was not called before or an error occurred during the last call.

15.7.12   rcGetCoverageMetricName 

Returns the name of a coverage metric corresponding to the most recent call to rcTester or rcSimRunSuite .

Syntax

int rcGetCoverageMetricName (
    RcHandle *h,
    int index,
    char *buffer,
    int bufferSize
);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcGetCoverageMetricCount .
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcGetCoverageMetricName will be the buffer size required to store the metric’s name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcGetCoverageMetricName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred (either the index parameter is outside the valid range or neither rcTester or rcSimRunSuite have been called before)..
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.13   rcGetCoverageMetricNumCovered 

Returns the name of a coverage metric corresponding to the most recent call to rcTester or rcSimRunSuite .

Syntax

int rcGetCoverageMetricNumCovered (RcHandle *h, int index);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcGetCoverageMetricCount .
Return Value
Returns -1 if an error occurred (either the index parameter is outside the valid range or neither rcTester or rcSimRunSuite have been called before).

Returns the number of covered targets for the coverage metric specified by the index parameter.

15.7.14   rcGetCoverageMetricNumTargets 

Returns the name of a coverage metric corresponding to the most recent call to rcTester or rcSimRunSuite .

Syntax

int rcGetCoverageMetricNumTargets (RcHandle *h, int index);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcGetCoverageMetricCount .
Return Value
Returns -1 if an error occurred (either the index parameter is outside the valid range or neither rcTester or rcSimRunSuite have been called before).

Returns the total number of targets for the coverage metric specified by the index parameter.

15.7.15   rcGetCoverageMetricNumUncovered 

Returns the name of a coverage metric corresponding to the most recent call to rcTester or rcSimRunSuite .

Syntax

int rcGetCoverageMetricNumUncovered (RcHandle *h, int index);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcGetCoverageMetricCount .
Return Value
Returns -1 if an error occurred (either the index parameter is outside the valid range or neither rcTester or rcSimRunSuite have been called before).

Returns the number of uncovered targets for the coverage metric specified by the index parameter.

15.7.16   rcGetCoverageMetricNumUnreachable 

Returns the name of a coverage metric corresponding to the most recent call to rcTester or rcSimRunSuite .

Syntax

int rcGetCoverageMetricNumUnreachable (RcHandle *h, int index);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcGetCoverageMetricCount .
Return Value
Returns -1 if an error occurred (either the index parameter is outside the valid range or neither rcTester or rcSimRunSuite have been called before).

Returns the number of unreachable targets for the coverage metric specified by the index parameter.

15.7.17   rcGetCoverageMetricPercentCovered 

Returns the percentage of covered targets for a coverage metric corresponding to the most recent call to rcTester or rcSimRunSuite .

Syntax

double rcGetCoverageMetricPercentCovered (RcHandle *h, int index);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcGetCoverageMetricCount .
Return Value
Returns -1 if an error occurred (either the index parameter is outside the valid range or neither rcTester or rcSimRunSuite have been called before).

Returns the percentage of covered targets for the coverage metric specified by the index parameter. The value ranges from 0.0 (nothing was covered) to 100.0 (all reachable targets were covered).

15.7.18   rcGetLastError 

Returns a string describing the most recent error that occurred during a Reactis API function call.

Syntax

const char *rsGetLastError(RcHandle *h);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
Return Value
Pointer to a string describing the most recent error message. A NULL value is returned if no error has occurred so far. Reactis allocates and releases the memory needed for the string. The pointer is only valid until the next call to any other API function.

15.7.19   rcGetParameterValue 

Get the value of a global Reactis parameter. This function can be used to retrieve values for any type of parameter. For boolean parameters, the value returned is either the string “0” or “1”. For double parameters, the value returned is the double value converted to a string. For a more convenient way to access boolean or double parameters, use functions rcGetParameterValueBool and rcGetParameterValueDouble .

Syntax

int rcGetParameterValue (
    RcHandle *h,
    char *name,
    char *buffer,
    int bufferSize
);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
name
The name of the parameter. See Sections 15.8 and 15.9.
buffer
The buffer that receives the value of the parameter. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcGetCoverageMetricName will be the buffer size required to store the parameter’s value.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the parameter’s value is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcGetParameterValue will be the buffer size that would be required to receive the whole value.
Return Value
−1if an error occurred (the parameterName parameter is not valid).
0on success.
N > 0if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the complete value. In this case N specifies the buffer size required to store the complete value.

15.7.20   rcGetParameterValueBool 

Get the value of a Boolean global Reactis parameter.

Syntax

int rcGetParameterValueBool (
    RcHandle *h,
    int parameterName,
    int *value,
);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
parameterName
The name of the parameter. See Sections 15.8 and 15.9.
value
A pointer to an integer variable that will receive the value of the Boolean parameter (0 for false and 1 for true).
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.21   rcGetParameterValueDouble 

Get the value of a double global Reactis parameter.

Syntax

int rcGetParameterValueDouble (
    RcHandle *h,
    int parameterName,
    double *value,
);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
parameterName
The name of the parameter. See Sections 15.8 and 15.9.
value
A pointer to a double variable that will receive the value of the parameter.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.22   rcOpen 

Starts a Reactis API session.

Syntax

RcHandle  *rcOpen (
    const char *licenseServer,
    char *errorBuf,
    unsigned int errorBufSize
);
Parameters
licenseServer
Character string of the form "server[:port]" that specifies how the API session should contact the Reactis License Manager. The server can be either specified by name ("ReactisLM:3999") or by IP address ("192.168.1.10:3999"). If the port number is omitted, then default 3999 is used. If licenseServer is NULL, information from the Reactis initialization file is used if available, otherwise the default "127.0.0.1:3999" is used.
errorBuf
Buffer to receive the error description if rcOpen fails. Memory for this buffer must be allocated by the caller before calling rcOpen . If rcOpen fails and errorBuf is NULL then the error message will be discarded.
errorBufSize
Size of errorBuf, i.e. maximum size of error message string. If actual error message string is longer than errorBufSize, it will be truncated.
Return Value

Pointer to a RcHandle structure which contains internal information about the new API session. This handle will be passed to all other API functions. If the open operation fails, then a NULL value is returned and (if errorBuf is non-NULL) an error message is copied into errorBuf.

15.7.23   rcReportConfig 

Creates a report configuration.

Syntax

RcReportConfig *rcReportConfig (
    RcReportItem  items,
    RcCoverageMetric  summaryMetrics,
    RcCoverageMetric  detailMetrics,
    RcTargetStatus  detailStatus
);
Parameters
items
The set of items to appear in the report.
summaryMetrics
The set of coverage metrics to be displayed in the coverage summary.
detailMetrics
The set of coverage metrics to be included in the coverage details.
detailStatus
The set of coverage statuses to be included in the coverage details.
Return Value
Pointer to a Report configuration, which will produce a report containing the specified information.

The returned configuration should be discarded via a call to rcReportConfigClose once it is no longer needed. Note that functions which generate reports make their own copy of the configuration, so deleting the configuration will not affect any report data which has already been generated.

15.7.24   rcReportConfigClose 

Stop using a report configuration.

Syntax

void rcReportConfigClose (RcReportConfig *config);
Parameters
config
A report configuration generated by rcReportConfig or rcReportConfigDefault .
Return Value
None. The memory which holds the value of config is recycled. Any subsequent use of the configuration is erroneous any will have unpredictable effects. Note that functions which generate reports make a copy of the configuration, so it is safe to delete the configuration immediately after they are used.

15.7.25   rcReportConfigDefault 

Creates a report configuration with default settings.

Syntax

RcReportConfig *rcReportConfigDefault (void);
Parameters
None.
Return Value
Pointer to a report configuration which will produce a report containing default information, which includes everything except MCC coverage data. The configuration can be changed using the rsReportConfigSet functions.

Note that rcReportConfigDefault () is equivalent to rcReportConfig (RcRptDefault , RcCvgDefault , RcCvgDefault , RcTgtDefault ).

The returned configuration should be closed via a call to rcReportConfigClose once it is no longer needed. Note that functions which generate reports make their own copy of the configuration, so deleting the configuration will not affect any report data which has already been generated.

15.7.26   rcReportConfigGetDetailMetrics 

Get the set of metrics which will appear in the Coverage Details section of a report.

Syntax

RcCoverageMetric rcReportConfigGetDetailMetrics (const RcReportConfig *config);
Parameters
config
A report configuration.
Return Value
The set of coverage metrics (in the form of an RcCoverageMetric bit-mask) which will appear in the Coverage Details section of any report generated via config.

15.7.27   rcReportConfigGetDetailStatus 

Get the set of coverage statuses which will appear in the Coverage Details section of a report.

Syntax

RcTargetStatus  rcReportConfigGetDetailStatus (const RcReportConfig *config);
Parameters
config
A report configuration.
Return Value
The set of target coverage statuses (in the form of an RcTargetStatus bit-mask) which will appear in the Coverage Details section of any report generated from config.

15.7.28   rcReportConfigGetItems 

Get the set of items which will appear in a report.

Syntax

RcReportItem  rcReportConfigGetItems (const RcReportConfig *config);
Parameters
config
A report configuration.
Return Value
The set of items (in the form of an RcReportItem bit-mask) which will appear in any report generated from config.

15.7.29   rcReportConfigGetSummaryMetrics 

Get the set of metrics which will appear in the Coverage Summary section of a report.

Syntax

RcCoverageMetric  rcReportConfigGetSummaryMetrics (const RcReportConfig *config);
Parameters
config
A report configuration.
Return Value
The set of items (in the form of an RcCoverageMetric bit-mask) which will appear in the Coverage Summary section of any report generated from config.

15.7.30   rcReportConfigSetDetailMetrics 

Specify which metrics will appear in the Coverage Details section of a report.

Syntax

void rcReportConfigSetDetailMetrics (
    const RcReportConfig *config,
    RcCoverageMetric  metrics
);
Parameters
config
A report configuration.
metrics
A set of coverage metrics.
Return Value
None. The set of coverage metrics which will appear in the Coverage Details section of any report generated from config is set to metrics.

15.7.31   rcReportConfigSetDetailStatus 

Specify which coverage statuses will appear in the Coverage Details section of a report.

Syntax

void rcReportConfigSetDetailStatus (
    const RcReportConfig *config,
    RcTargetStatus status
);
Parameters
config
A report configuration.
status
A set of target coverage statuses.
Return Value
None. The set of target coverage statuses which will appear in the Coverage Details section of any report generated from config is set to status.

15.7.32   rcReportConfigSetItems 

Specify which items will appear in a report.

Syntax

void rcReportConfigSetItems (
    const RcReportConfig *config,
    RcReportItem items
);
Parameters
config
A report configuration.
items
A set of report items.
Return Value
None. The set of items which will appear in any report generated from config is set to items

15.7.33   rcReportConfigSetSummaryMetrics 

Specify which metrics will appear in the Coverage Summary section of a report.

Syntax

void rcReportConfigSetSummaryMetrics (
    const RcReportConfig *config,
    RcCoverageMetric  metrics
);
Parameters
config
A report configuration.
metrics
A set of coverage metrics.
Return Value
None. The set of items which will appear in the Coverage Summary section of any report generated from config is set to metrics.

15.7.34   rcReportItemFromString 

Converts a string to an individual RcReportItem value.

Syntax

RcReportItem  rcReportItemFromString (const char *str);
Parameters
str
String holding the name of an RcReportItem . See Section 15.12.2 for the list of recognized names.
Return Value
Returns the individual RcReportItem value whose name matches str (using case-insensitive comparison). The RcReportItem values are listed in Section 15.5.4.

Returns RcRptNone if there is no match. In this case rcGetLastError should not be called.

15.7.35   rcReportItemToString 

Converts an individual RcReportItem value to a string.

Syntax

const char *rcReportItemToString (RcReportItem  item);
Parameters
item
An individual report item. The RcReportItem values are listed in Section 15.5.4.
Return Value
Returns a constant string representing the value of sev if item is one of the individual report items. The string hold one of the values listed in Section 15.12.2.

Returns NULL if item is not one of the individual RcReportItem values. In this case rcGetLastError should not be called.

15.7.36   rcRshClose 

Closes a harness library (.rsh) file.

Syntax

void rcRshClose (RcRshFile *hRsh);
Parameters
hRsh
pointer to RcRshFile structure as returned by rcRshOpen .
Return Value
No value is returned.

15.7.37   rcRshGetCoverageEnabled 

Get the enabled/disabled status of a coverage metric. The names of coverage metrics can be retrieved via the rcRshGetCoverageEnabled API function. Coverage metric names are listed in Section 15.12.1.

Syntax

int rcRshGetCoverageEnabled (
     RcRshFile *hRsh,
     const char *name );
Parameters
hRsh
A pointer to an harness library as returned by rcRshOpen .
name
The name of a coverage objective.
Return Value
Returns 1 if the coverage objective is enabled.

Returns 0 if the coverage objective is disabled.

Returns -1 if an error occurred, in which case rcGetLastError can be called to retrieve the error message.

15.7.38   rcRshGetCurrentHarness 

Get the currently selected test harness from a harness library.

Syntax

RcRshHarness *rcRshGetCurrentHarness (RcRshFile *hRsh);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
Return Value
Returns the (non-negative) index of the current harness if successful.

Returns −1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message.

15.7.39   rcRshGetEntryFunCandidateFullName 

Get the full name of an entry function candidate.

Syntax

int rcRshGetEntryFunCandidateFullName (
     RcRshFile *hRsh,
    int index,
    char *buffer,
    int bufferSize
);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcRshGetNumEntryFunCandidates .
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshGetEntryFunCandidateFullName will be the buffer size required to store the metric’s name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshGetEntryFunCandidateFullName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred (the index parameter is outside the valid range)..
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.40   rcRshGetEntryFunCandidateName 

Get the name of an entry function candidate.

Syntax

int rcRshGetEntryFunCandidateName (
     RcRshFile *hRsh,
    int index,
    char *buffer,
    int bufferSize
);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcRshGetNumEntryFunCandidates .
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshGetEntryFunCandidateName will be the buffer size required to store the metric’s name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshGetEntryFunCandidateName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.41   rcRshGetHarness 

Get a test harness from a harness library.

Syntax

rcRshGetHarness (RcRshFile *hRsh, int index);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
index
The index of the harness This value must be greater or equal to 0 and less than the return value of rcRshGetNumHarnesses .
Return Value
Returns a pointer to a test harness stored in the harness library referenced by hRsh.

Returns NULL if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.42   rcRshGetInitFunCandidateFullName 

Get the full name of an initialization function candidate.

Syntax

int rcRshGetInitFunCandidateFullName (
     RcRshFile *hRsh,
    int index,
    char *buffer,
    int bufferSize
);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcRshGetNumInitFunCandidates .
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshGetInitFunCandidateFullName will be the buffer size required to store the metric’s name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshGetInitFunCandidateFullName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred (the index parameter is outside the valid range)..
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.43   rcRshGetInitFunCandidateName 

Get the name of an initialization function candidate.

Syntax

int rcRshGetInitFunCandidateName (
     RcRshFile *hRsh,
    int index,
    char *buffer,
    int bufferSize
);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
index
The index of the coverage metric. This value must be greater or equal to 0 and less than the return value of rcRshGetNumInitFunCandidates .
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshGetInitFunCandidateName will be the buffer size required to store the metric’s name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshGetInitFunCandidateName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.44   rcRshGetNumEntryFunCandidates 

Get the number of entry function candidates.

Syntax

int rcRshGetNumEntryFunCandidates (RcRshFile *hRsh);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
Return Value
Returns the number of entry functions available for use in test harnesses, or -1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.45   rcRshGetNumHarnesses 

Get the number of test harnesses stored in a harness library.

Syntax

rcRshGetNumHarnesses (RcRshFile *hRsh);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
Return Value
Returns the number of test harnesses contained in the harness library referenced by hRsh, or -1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.46   rcRshGetNumEntryFunCandidates 

Get the number of initialization function candidates.

Syntax

int rcRshGetNumInitFunCandidates (RcRshFile *hRsh);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
Return Value
Returns the number of entry functions available for use in test harnesses, or -1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.47   rcRshGetParameterValue 

Get the value of a harness library parameter.

Syntax

rcRshGetParameterValue (
    RcRshFile *hRsh,
    int paramName,
    char *buffer,
    int bufferSize
);
Parameters
hRsh
A pointer to an RcRshFile structure as returned by rcRshOpen .
paramName
The parameter name.
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshGetEntryFunCandidateName will be the buffer size required to store the metric’s name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshGetEntryFunCandidateName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the parameter value. In this case, N specifies the buffer size required to store the complete parameter value.

15.7.48   rcRshHarnessAddVar 

Add a variable to a test harness.

Syntax

rcRshHarnessAddVar (
    RcRshHarness *harness,
    RcRshVarKind   kind,
    RcRshVar *var
);
Parameters
harness
A test harness.
kind
The purpose for which the variable will be used.
var
A variable returned by rcRshHarnessGetVarCandidate .
Return Value
Returns a non-null pointer to a new RcRshVar structure if successful.

Returns NULL if unsuccessful, in which case you may call rcGetLastError to retrieve the error message.

15.7.49   rcRshHarnessCheckVarCandidate 

Syntax

rcRshHarnessCheckVarCandidate (
    RcRshHarness *harness,
    RcRshVarKind   kind,
    RcRshVar *var
);
Parameters
harness
A test harness.
kind
The purpose for which the variable will be used.
var
A variable returned by rcRshHarnessGetVarCandidate .
Return Value
Returns 1 if the variable can be used for the given purpose in the test harness.

Returns 0 if the variable cannot be used for the given purpose in the test harness.

Returns -1 If an error occurred, in which case you may call rcGetLastError to retrieve the error message string.

15.7.50   rcRshHarnessCopy 

Make a copy of a harness.

Syntax

rcRshHarnessCopy (
    RcRshHarness *harness,
    const char *newName,
    const char *newEntry
);
Parameters
harness
A test harness.
newName
The name of the new harness.
newEntry
The name of the entry function to be used with the new harness. This should be a value returned by rcRshHarnessGetEntryFunFullName . If newEntry is NULL, the entry function used by harness is used in the new harness.
Return Value
Returns a non-NULL pointer to the new harness if successful, in which case the current harness will be set to the new harness.

Returns NULL if an error occurred, in which case rcGetLastError may be used to retrieve the error message.

15.7.51   rcRshHarnessCreate 

Syntax

rcRshHarnessCreate (
    RcRshFile *hRsh,
    const char *harnessName,
    const char *entryName
);
Parameters
hRsh
A harness library returned by rcRshOpen .
harnessName
The name of the new harness.
entryName
The name of the entry function to be used with the new harness. This should be a value returned by rcRshHarnessGetEntryFunFullName .
Return Value
Returns a non-NULL pointer to the new harness if successful, in which case the current harness will be set to the new harness.

Returns NULL if an error occurred, in which case rcGetLastError may be used to retrieve the error message.

15.7.52   rcRshHarnessGetEntryFunFullName 

Get the full name of the entry function used by a test harness.

Syntax

rcRshHarnessGetEntryFunFullName (
     RcRshFile *harness,
    char *buffer,
    int bufferSize
);
Parameters
harness
A test harness.
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshHarnessGetEntryFunFullName will be the buffer size required to store the name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshHarnessGetEntryFunFullName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.53   rcRshHarnessGetEntryFunName 

Get the name of the entry function used by a test harness.

Syntax

rcRshHarnessGetEntryFunName (
     RcRshFile *harness,
    char *buffer,
    int bufferSize
);
Parameters
harness
A test harness.
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshHarnessGetEntryFunName will be the buffer size required to store the name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshHarnessGetEntryFunName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.54   rcRshHarnessGetInitFunFullName 

Get the full name of the initialization function used by a test harness.

Syntax

rcRshHarnessGetInitFunFullName (
     RcRshFile *harness,
    char *buffer,
    int bufferSize
);
Parameters
harness
A test harness.
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshHarnessGetInitFunFullName will be the buffer size required to store the name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshHarnessGetInitFunFullName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.55   rcRshHarnessGetInitFunName 

Get the name of the initialization function used by a test harness.

Syntax

rcRshHarnessGetInitFunName (
     RcRshFile *harness,
    char *buffer,
    int bufferSize
);
Parameters
harness
A test harness.
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshHarnessGetInitFunName will be the buffer size required to store the name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshHarnessGetInitFunName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.56   rcRshHarnessGetName 

Get the name of a test harness.

Syntax

rcRshHarnessGetName (
     RcRshFile *harness,
    char *buffer,
    int bufferSize
);
Parameters
harness
A test harness.
buffer
The buffer that receives the name of the coverage metric. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshHarnessGetName will be the buffer size required to store the metric’s name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshHarnessGetName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.57   rcRshHarnessGetNumVarCandidates 

Return the number of variable candidates available for use in a test harness.

Syntax

rcRshHarnessGetNumVarCandidates (RcRshFile *harness);
Parameters
harness
A test harness.
Return Value
Returns the number of variable candidates available for use with the given harness, or -1 if an error occurred. In the latter case you may call rcGetLastError to retrieve the error message.

15.7.58   rcRshHarnessGetNumVars 

Return the number of variables used by a test harness.

Syntax

rcRshHarnessGetNumVars (
     RcRshFile *harness,
     RcRshVarKind   kind
);
Parameters
harness
A test harness.
kind
The variable kind of interest.
Return Value
Returns the number of variables used by harness whose kind is kind, or -1 if an error occurred. In the latter case you may call rcGetLastError to retrieve the error message.

15.7.59   rcRshHarnessGetSampleRate 

Get the sample rate of a harness.

Syntax

rcRshHarnessGetSampleRate (RcRshFile *harness);
Parameters
harness
A test harness.
Return Value
Returns the (positive) sample rate on success.

Returns a non-positive value if an error occurred, in which case rcGetLastError can be called to get the error message.

15.7.60   rcRshHarnessGetVar 

Retrieve a variable from a test harness.

Syntax

rcRshHarnessGetVar (
     RcRshFile *harness,
     RcRshVarKind   kind,
     int index
);
Parameters
harness
A test harness.
kind
The variable kind
index
A value in the range 0 … n−1, where n is the value returned by rcRshHarnessGetNumVars 
Return Value
Returns a non-NULL pointer to an RcRshVar structure if successful.

Returns a or a NULL pointer if unsuccessful, in which case you may call rcGetLastError to retrieve the error message.

15.7.61   rcRshHarnessGetVarCandidate 

Retrieve a variable candidate from a test harness.

Syntax

rcRshHarnessGetVarCandidate ((
     RcRshFile *harness,
     int index
);
Parameters
harness
A test harness.
index
A value in the range 0 … n−1, where n is the value returned by rcRshHarnessGetNumVarCandidates 
Return Value
Returns a non-NULL pointer to an RcRshVar structure if successful, or a NULL pointer if unsuccessful. In the latter case you may call rcGetLastError to retrieve the error message.

15.7.62   rcRshHarnessGetVarCandidateByFullName 

Return the variable candidate with the given full name.

Syntax

rcRshHarnessGetVarCandidateByFullName (
     RcRshFile *harness,
     const char *fullName
);
Parameters
harness
A test harness.
fullName
The full name of a variable candidate, as returned by rcRshVarGetFullName .
Return Value
Returns a non-NULL pointer to an RcRshVar structure if successful, or a NULL pointer if unsuccessful. In the latter case you may call rcGetLastError to retrieve the error message string.

15.7.63   rcRshHarnessImport 

Import a test harness from an .rsi file.

Syntax

rcRshHarnessImport (
    RcRshFile *hRsh,
    const char *harnessName,
    const char *entryName
    const char *rsiFileName
    const RcRshNameMap *nameMap );
Parameters
hRsh
A harness library.
harnessName
The name of the new harness.
entryName
The name of the entry function to be called by the new harness.
rsiFileName
The name of an .rsi file to import I/O definitions from.
nameMap
Mapping between code variable names and test harness variable names. If NULL, code variable names and test harness variables names will be identical.
Return Value
Returns A (non-NULL) pointer to the new harness if successful, in which case the current harness will be set to the new harness.

Returns NULL if an error occurred, in which case rcGetLastError may be used to retrieve the error message.

15.7.64   rcRshHarnessGetInitFunName 

Set the initialization function used by a test harness.

Syntax

rcRshHarnessGetInitFunName (
     RcRshFile *harness,
    const char *name
);
Parameters
harness
A test harness.
name
The name or full name of an initialization function, as returned by rcRshGetInitFunCandidateName or rcRshGetInitFunCandidateFullName . If this parameter is NULL or the empty string, harness will be configured to not call an initialization function.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.65   rcRshHarnessSetSampleRate 

Set the sample rate of a harness.

Syntax

rcRshHarnessSetSampleRate (
    RcRshFile *harness,
    double rate );
Parameters
harness
A test harness.
rate
The new sample rate.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.66   rcRshHarnessSync 

Syntax

rcRshHarnessSync (
    RcRshFile *harness,
    double flags );
Parameters
harness
A test harness.
flags
A string containing optional settings that control the synchronization. Currently this argument is ignored.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.67   rcRshNameMapClose 

Close a name map.

Syntax

rcRshNameMapClose (RcRshNameMap *map);
Parameters
map
A pointer to a name map.
Return Value
Nothing is returned. The memory which stores the name map is freed.

15.7.68   rcRshNameMapCreate 

Syntax

rcRshNameMapCreate (RcHandle *h);
Parameters
h
A pointer to a Reactis for C session.
Return Value
Returns a pointer to a name map in which C code names exactly match test harness names. This name map may be subsequently modified via rcRshNameMapSetPrefix and rcRshNameMapSetSuffix .

Returns NULL if an error occurred, in which get rcGetLastError may be called to retrieve the error message.

Note that it is the responsibility of the caller to call rcRshNameMapClose once the name map is no longer needed.

15.7.69   rcRshNameMapGetPrefix 

Get a prefix from a name map.

Syntax

rcRshNameMapGetPrefix (
    RcRshNameMap *map,
    RcRshInterfaceLevel  level,
    RcRshVarKind  kind,
    char *buffer,
    int bufferSize );
Parameters
map
A pointer to a name map.
level
An interface level. See Section 15.5.7.
kind
A variable kind.
buffer
The buffer that receives the prefix. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshNameMapGetPrefix will be the buffer size required to store the prefix.
bufferSize
The size of the buffer passed in as the third argument. If the prefix is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshNameMapGetPrefix will be the buffer size that would be required to receive the whole prefix.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the prefix. In this case, N specifies the buffer size required to store the complete prefix.

15.7.70   rcRshNameMapGetSuffix 

Get a suffix from a name map.

Syntax

rcRshNameMapGetSuffix (
    RcRshNameMap *map,
    RcRshInterfaceLevel  level,
    RcRshVarKind  kind,
    char *buffer,
    int bufferSize );
Parameters
map
A pointer to a name map.
level
An interface level. See Section 15.5.7.
kind
A variable kind.
buffer
The buffer that receives the suffix. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshNameMapGetSuffix will be the buffer size required to store the suffix.
bufferSize
The size of the buffer passed in as the third argument. If the suffix is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshNameMapGetSuffix will be the buffer size that would be required to receive the whole suffix.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the suffix. In this case, N specifies the buffer size required to store the complete suffix.

15.7.71   rcRshNameMapSetPrefix 

Set a prefix within a name map.

Syntax

rcRshNameMapSetPrefix (
    RcRshNameMap *map,
    RcRshInterfaceLevel  level,
    RcRshVarKind  kind,
    const char *prefix );
Parameters
map
A pointer to a name map.
level
The interface level to which the prefix should be applied. See Section 15.5.7 for a list of interface level values.
kind
The interface level to which the prefix should be applied. See Section 15.5.7 for a list of interface level values.
prefix
A string containing one of more prefixes. Each prefix is composed from alphanumeric characters and the underscore character. Multiple prefixes are separated by commas. The prefix string is copied, so it can be safely deallocated after rcRshNameMapSetPrefix returns.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.72   rcRshNameMapSetSuffix 

Set a suffix within a name map.

Syntax

rcRshNameMapSetSuffix (
    RcRshNameMap *map,
    RcRshInterfaceLevel  level,
    RcRshVarKind  kind,
    const char *suffix );
Parameters
map
A pointer to a name map.
level
The interface level to which the suffix should be applied. See Section 15.5.7 for a list of interface level values.
kind
The interface level to which the suffix should be applied. See Section 15.5.7 for a list of interface level values.
suffix
A string containing one of more suffixes. Each suffix is composed from alphanumeric characters and the underscore character. Multiple suffixes are separated by commas. The suffix string is copied, so it can be safely deallocated after rcRshNameMapSetSuffix returns.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.73   rcRshOpen 

Syntax

rcRshOpen (
    RcHandle *h,
    const char *rsmFileName
    const char *rshFileName );
Parameters
h
A pointer to a Reactis for C session handle as returned by rcOpen .
rsmFileName
The pathname of a Reactis build file.
rshFileName
The pathname of a Reactis harness library.
Return Value
Returns a Pointer to an RcRshFile structure that must be used in all subsequent calls to rcRsh* functions.

Returns NULL if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.74   rcRshSave 

Save a harness library which was previously opened by rcRshOpen without closing it.

Syntax

rcRshSave (
    RcRshFile *hRsh,
    const char *rshFileName );
Parameters
hRsh
A pointer to a harness library as returned by rcRshOpen .
rshFileName
The pathname of the output file. If NULL, the current filename is used.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.75   rcRshSetCoverageEnabled 

Enable or disable tracking of a coverage metric.

Syntax

rcRshSetCoverageEnabled (
     RcRshFile *hRsh,
     const char *name
     int  enabled );
Parameters
hRsh
A pointer to an harness library as returned by rcRshOpen .
name
The name of a coverage objective. See rcRshGetCoverageEnabled for a list of coverage objective names.
enabled
If 0, coverage tracking for the objective will be disabled. Otherwise, it will be enabled.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.76   rcRshSetCurrentHarness 

Set the current test harness in a harness library.

Syntax

rcRshSetCurrentHarness (
    RcRshFile *hRsh,
    RcRshHarness *harness );
Parameters
hRsh
A pointer to a harness library as returned by rcRshOpen .
harness
A pointer to a harness.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.77   rcRshSetParameterValue 

Set a harness library parameter

Syntax

rcRshSetParameterValue (
    RcRshFile *hRsh,
     const char *name
     const char *value
);
Parameters
hRsh
A pointer to a harness library as returned by rcRshOpen .
name
The name of a harness library parameter. Parameter names and values are listed in Section 15.10.
value
The value to assign to the named parameter.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.78   rcRshVarDelete 

Remove a variable from a test harness and delete it.

Syntax

rcRshVarDelete (RcRshVar *var);
Parameters
var
A pointer to a variable returned by rcRshHarnessGetVar . This pointer is no longer valid once rcRshVarDelete returns.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.79   rcRshVarGetFullName 

Get the full name of a test variable.

Syntax

rcRshVarGetFullName (
     RcRshVar *var,
    char *buffer,
    int bufferSize
);
Parameters
var
A pointer to a variable.
buffer
The buffer that receives the full name of the variable. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshVarGetFullName will be the buffer size required to store the variable’s full name.
bufferSize
The size of the buffer passed in as the third argument. If the full name of the variable is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshVarGetFullName will be the buffer size that would be required to receive the full name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.80   rcRshVarGetHarnessType 

Get the harness type of a test variable.

Syntax

rcRshVarGetHarnessType (
     RcRshVar *var,
    char *buffer,
    int bufferSize
);
Parameters
var
A pointer to a variable.
buffer
The buffer that receives the harness type of the variable. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshVarGetHarnessType will be the buffer size required to store the variable’s harness type.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case, the return value of rcRshVarGetHarnessType will be the buffer size that would be required to receive the whole harness type.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the harness type. In this case, N specifies the buffer size required to store the complete harness type.

15.7.81   rcRshVarGetInternalType 

Get the internal type of a test variable.

Syntax

rcRshVarGetInternalType (
     RcRshVar *var,
    char *buffer,
    int bufferSize
);
Parameters
var
A pointer to a variable.
buffer
The buffer that receives the internal type of the variable. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshVarGetInternalType will be the buffer size required to store the variable’s internal type.
bufferSize
The size of the buffer passed in as the third argument. If the actual name of the metric is longer than this value, it will be truncated to the length of the buffer. In that case, the return value of rcRshVarGetInternalType will be the buffer size that would be required to receive the whole internal type.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the internal type. In this case, N specifies the buffer size required to store the complete internal type.

15.7.82   rcRshVarGetKind 

Get the kind of a test variable.

Syntax

rcRshVarGetKind (RcRshVar *var);
Parameters
var
A pointer to a variable returned by rcRshHarnessGetVar 
Return Value
Returns -1 if the variable does not have an assigned kind because it is a variable candidate (returned by rcRshHarnessGetVarCandidate ) which has not been assigned for use in a test harness.

Returns one of the RcRshVarKind values if successful.

15.7.83   rcRshVarGetLocation 

Get the location of a test variable.

Syntax

rcRshVarGetLocation (
     RcRshVar *var,
    char *buffer,
    int bufferSize );
Parameters
var
A pointer to a variable.
buffer
The buffer that receives the location of the variable. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshVarGetLocation will be the buffer size required to store the variable’s location.
bufferSize
The size of the buffer passed in as the third argument. If the location of the variable is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshVarGetLocation will be the buffer size that would be required to receive the location.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the location. In this case, N specifies the buffer size required to store the complete location.

15.7.84   rcRshVarGetName 

Get the name of a test variable.

Syntax

rcRshVarGetName (
     RcRshVar *var,
    char *buffer,
    int bufferSize );
Parameters
var
A pointer to a variable.
buffer
The buffer that receives the name of the variable. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshVarGetName will be the buffer size required to store the variable’s name.
bufferSize
The size of the buffer passed in as the third argument. If the name of the variable is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshVarGetName will be the buffer size that would be required to receive the name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.

15.7.85   rcRshVarGetProperties 

Get the properties of a test variable.

Syntax

rcRshVarGetProperties (
     RcRshVar *var,
    char *buffer,
    int bufferSize );
Parameters
var
A pointer to a variable.
buffer
The buffer that receives the properties of the variable. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRshVarGetProperties will be the buffer size required to store the variable’s properties.
bufferSize
The size of the buffer passed in as the third argument. If the properties of the variable is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcRshVarGetProperties will be the buffer size that would be required to receive the entire properties string.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the properties string. In this case, N specifies the buffer size required to store the complete properties string.

15.7.86   rcRshVarGetTolerance 

Set the relative tolerance of a test variable.

Syntax

rcRshVarGetTolerance (
    RcRshVar *var,
    double *tolerance );
Parameters
var
A pointer to an output variable.
tolerance
A pointer to a double value which will receive the tolerance value.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.87   rcRshVarHasProperty 

Syntax

rcRshVarHasProperty (
    RcRshVar *var,
    const char *name );
Parameters
var
A pointer to a variable.
name
The name of a property.
Return Value
1
if the variable possesses the named property.
0
if the variable does not possess the named property.
−1
if an error occurred, in which case you may call rcGetLastError to retrieve the error message.

15.7.88   rcRshVarKindFromIndex 

Convert an index to a variable kind.

Syntax

rcRshVarKindFromIndex (int  index);
Parameters
index
A integer in the range 0 … RcRshNumVarKinds−1.
Return Value
A value k which can be tested for validity by calling rcRshVarKindIsValid (k). If k is invalid, then the index is not in the range 0 … RcRshNumVarKinds−1.

15.7.89   rcRshVarKindFromString 

Convert a string to a variable kind.

Syntax

rcRshVarKindFromString (const char *name);
Parameters
name
The name of a variable kind as returned by rcRshVarKindToString . See Section 15.12.5 for a list of valid names.
Return Value
A value k which can be tested for validity by calling rcRshVarKindIsValid (k). If k is invalid, then name does not match one of the names listed in Section 15.12.5.

15.7.90   rcRshVarKindIsValid 

Determime if an integer is a valid variable kind.

Syntax

rcRshVarKindIsValid (int  x);
Parameters
x
A integer.
Return Value
1
if x is equal to one of the RcRshVarKind values listed in Section 15.5.10.
0
otherwise.

15.7.91   rcRshVarKindToIndex 

Convert a variable kind to a index.

Syntax

rcRshVarKindToIndex (RcRshVarKind   kind);
Parameters
kind
A variable kind.
Return Value
Returns an index in the range 0 … RcRshNumVarKinds−1 if successful.

Returns −1 if kind is not one of the valid RcRshVarKind values listed in Section 15.5.10.

15.7.92   rcRshVarKindToString 

Get the name of a variable kind.

Syntax

rcRshVarKindToString (RcRshVarKind   kind);
Parameters
kind
A variable kind.
Return Value
Returns a pointer to a string which contains one of the names listed in Section 15.12.5 if successful.

Returns NULL if kind is not one of the valid RcRshVarKind values listed in Section 15.5.10.

15.7.93   rcRshVarSetHarnessType 

Set the harness type of a variable.

Syntax

rcRshVarSetHarnessType (
    RcRshVar *var,
    const char *type );
Parameters
var
A pointer to a variable which is used as a harness input or output (i.e., its kind is either RcRshOutputVar or RcRshInputVar).
type
A type (see Section 6.8 for a description of types). If var is an output variable, the type must not have any constraints.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.94   rcRshVarSetInternalType 

Set the internal type of a variable. The internal type of a variable should only be changed if the variable contains a fixed point value.

Syntax

rcRshVarSetInternalType (
    RcRshVar *var,
    const char *type );
Parameters
var
A pointer to a variable which is used as a internal input or output (i.e., its kind is either RcRshOutputVar or RcRshInputVar).
type
A type (see Section 6.8 for a description of types).
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.95   rcRshVarSetName 

Set the name of a variable.

Syntax

rcRshVarSetName (
    RcRshVar *var,
    const char *name );
Parameters
var
A pointer to a variable which is used as a harness input, output, or configuration variable.
name
The new name of the variable.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.96   rcRshVarSetTolerance 

Set the tolerance of a test harness output.

Syntax

rcRshVarSetTolerance (
    RcRshVar *var,
    double *tolerance );
Parameters
var
A pointer to a variable which is used as a harness input, output, or configuration variable.
tolerance
The new tolerance of the variable. If tolerance is not positive, var will be set to inherit its tolerance.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.97   rcRsmAddDefine 

Add a macro definition to a build file.

Syntax

rcRsmAddDefine (
    RcRsmFile *hRsm,
    int i,     const char *macroDef );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index. If i is in the range 0..n−1, where n is the value returned by rcRsmGetNumDefines , then macroDef will be inserted into the list of macro definitions at position i. If i is not in the range 0..n−1, then macroDef will be appended to the list.
macroDef
A string containing a macro definition. The macro definition may be just a name, or have a name and a body separated by an equal sign. (e.g., "DEBUG" or "DEBUG=1").
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.98   rcRsmAddIncludeDir 

Add a directory to the list of directories searched when processing #include preprocessor directives.

Syntax

rcRsmAddIncludeDir (
    RcRsmFile *hRsm,
    int i,
    const char *dir );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index. If i is in the range 0..n−1, where n is the value returned by rcRsmGetNumDefines , then dir will be inserted into the list of directories at position i. If i is not in the range 0..n−1, then dir will be appended to the list.
dir
The pathname of a directory.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.99   rcRsmAddLibrary 

Add a library to the list of libraries used by a build file.

Syntax

rcRsmAddLibrary (
    RcRsmFile *hRsm,
    int i,
    const char *lib );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index. If i is in the range 0..n−1, where n is the value returned by rcRsmGetNumDefines , then lib will be inserted into the list of libraries at position i. If i is not in the range 0..n−1, then lib will be appended to the list.
lib
The pathname of a build file (a file with extension .rsm).
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.100   rcRsmAddSourceFile 

Add a source file to a build file.

Syntax

rcRsmAddSourceFile (
    RcRsmFile *hRsm,
    int i,
    const char *lib );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index. If i is in the range 0..n−1, where n is the value returned by rcRsmGetNumDefines , then lib will be inserted into the list of libraries at position i. If i is not in the range 0..n−1, then lib will be appended to the list.
lib
The pathname of a build file (a file with extension .rsm).
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.101   rcRsmClose 

Close a build file which was previously opened by rcRsmOpen without saving any changes which were made.

Syntax

rcRsmClose (RcRsmFile *hRsm);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
Return Value

15.7.102   rcRsmGetCoverageEnabled 

Determine if coverage tracking is enabled for a build file.

Syntax

rcRsmGetCoverageEnabled (RcRsmFile *hRsm);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
Return Value
1
If coverage is enabled.
0
If coverage is disabled.
−1
If an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.103   rcRsmGetDefine 

Get a macro definition from a build file.

Syntax

rcRsmGetDefine (
    RcRsmFile *hRsm,
    int i,
    char *buffer,
    int bufferSize );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is the value returned by rcRsmGetNumDefines .
buffer
The buffer that receives the macro definition. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRsmGetDefine will be the buffer size required to store the entire macro definition.
bufferSize
The size of the buffer passed in as the third argument. If the properties of the variable is longer than this value, it will be truncated to the length of the buffer and the return value of rcRsmGetDefine will be the buffer size that would be required to receive the entire macro definition.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the macro definition. In this case, N specifies the buffer size required to store the complete macro definition.

15.7.104   rcRsmGetIncludeDir 

Get a directory from the #include search path of a build file.

Syntax

rcRsmGetIncludeDir (
    RcRsmFile *hRsm,
    int i,
    char *buffer,
    int bufferSize );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is the value returned by rcRsmGetNumIncludeDirs .
buffer
The buffer that receives the macro definition. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRsmGetIncludeDir will be the buffer size required to store the directory name.
bufferSize
The size of the buffer passed in as the third argument. If the properties of the variable is longer than this value, it will be truncated to the length of the buffer and the return value of rcRsmGetIncludeDir will be the buffer size that would be required to receive the entire directory name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the directory name. In this case, N specifies the buffer size required to store the complete directory name.
.

15.7.105   rcRsmGetLibrary 

Get an entry from the list of libraries required by a build file.

Syntax

rcRsmGetLibrary (
    RcRsmFile *hRsm,
    int i,
    char *buffer,
    int bufferSize );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is the value returned by rcRsmGetNumLibraries 
buffer
The buffer that receives the macro definition. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRsmGetLibrary will be the buffer size required to store the library name.
bufferSize
The size of the buffer passed in as the third argument. If the properties of the variable is longer than this value, it will be truncated to the length of the buffer and the return value of rcRsmGetIncludeDir will be the buffer size that would be required to receive the entire library name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the library name. In this case, N specifies the buffer size required to store the complete library name.

15.7.106   rcRsmGetNumDefines 

Get the number of macro definitions stored in a build file.

Syntax

rcRsmGetNumDefines (RcRsmFile *hRsm);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
Return Value
Returns the number of macro definitions in the build file referenced by hRsm.

Returns -1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.107   rcRsmGetNumIncludeDirs 

Get the length of the #include search path stored in a build file.

Syntax

rcRsmGetNumDefines (RcRsmFile *hRsm);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
Return Value
Returns the number of entries in the #include search path stored in the build file referenced by hRsm.

Returns -1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.108   rcRsmGetNumLibraries 

Get the number of libraries listed in a build file.

Syntax

rcRsmGetNumLibraries (RcRsmFile *hRsm);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
Return Value
Returns the number of entries in the list of libraries stored in the build file referenced by hRsm.

Returns -1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.109   rcRsmGetNumSourceFiles 

Get the number of source files listed in a build file.

Syntax

rcRsmGetNumSourceFiles (RcRsmFile *hRsm);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
Return Value
Returns the number of entries in the list of libraries stored in the build file referenced by hRsm.

Returns -1 if an error occurred, in which case rcGetLastError may be used to retrieve the error message string.

15.7.110   rcRsmGetParameterValue 

Get a parameter value from a build file.

Syntax

rcRsmGetParameterValue (
    RcRsmFile *hRsm,
    const char *name,
    char *buffer,
    int bufferSize );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
name
The name of a build file parameter.
buffer
The buffer that receives the parameter value. the buffer’s size must correspond to the value of the bufferSize parameter. If buffer is NULL, the value returned by rcRsmGetSourceFile will be the buffer size required to store the parameter value.
bufferSize
The size of the buffer passed in as the third argument. If the storage size of the parameter value is larger than bufferSize, the parameter value will be truncated to the length of the buffer and the return value of rcRsmGetSourceFile will be the buffer size that would be required to receive the entire parameter value.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the parameter value. In this case, N specifies the buffer size required to store the complete parameter value.
.

15.7.111   rcRsmGetSourceFile 

Get an entry from the list of source files required by a build file.

Syntax

rcRsmGetLibrary (
    RcRsmFile *hRsm,
    int i,
    char *buffer,
    int bufferSize );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is the value returned by rcRsmGetNumSourceFiles 
buffer
The buffer that receives the source file name. the buffer’s size must correspond to the value of the bufferSize parameter. If the this parameter is NULL then the value returned by rcRsmGetSourceFile will be the buffer size required to store the source file name.
bufferSize
The size of the buffer passed in as the third argument. If the storage size of the source file name is larger than this value, the source file name will be truncated to the length of the buffer and the return value of rcRsmGetSourceFile will be the buffer size that would be required to receive the entire source file name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the source file name. In this case, N specifies the buffer size required to store the complete source file name.

15.7.112   rcRsmOpen 

Open a build file.

Syntax

rcRsmOpen (
    RcHandle *h,
    const char *rsmFileName );
Parameters
h
A pointer to a session handle returned by rcOpen .
rsmFileName
The path and name of a Reactis build file. If this file does not exist, an empty .rsm file will be created..
Return Value
 

A pointer to an RcRsmFile structure.

NULL if an error occurred, in which case rcGetLastError can be called to retrieve the error message.

15.7.113   rcRsmRemoveDefine 

Remove a macro definition from a build file.

Syntax

rcRsmRemoveDefine (
    RcRsmFile *hRsm,
    int  i );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is value returned by rcRsmGetNumDefines .
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.114   rcRsmRemoveIncludeDir 

Remove an entry from the included file search path stored in a build file.

Syntax

rcRsmRemoveDefine (
    RcRsmFile *hRsm,
    int  i );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is value returned by rcRsmGetNumIncludeDirs .
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.115   rcRsmRemoveLibrary 

Remove a library reference from a build file.

Syntax

rcRsmRemoveDefine (
    RcRsmFile *hRsm,
    int  i );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is value returned by rcRsmGetNumLibraries .
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.116   rcRsmRemoveSourceFile 

Remove a source file from a build file.

Syntax

rcRsmRemoveDefine (
    RcRsmFile *hRsm,
    int  i );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
i
An index in the range 0..n−1, where n is value returned by rcRsmGetNumSourceFiles .
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.117   rcRsmSave 

Save a build file.

Syntax

rcRsmSave (
    RcRsmFile *hRsm,
    const char *rsmFileName );
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
rsmFileName
The path and name of a Reactis build file.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.118   rcRsmSetCoverageEnabled 

Syntax

rcRsmSetCoverageEnabled (
    RcRsmFile *hRsm,
    int  onOff
);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
onOff
A Boolean flag.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.119   rcRsmSetParameterValue 

Syntax

rcRsmSetParameterValue (
    RcRsmFile *hRsm,
    char *name,
    char *value,
);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
name
The name of the parameter.
value
The new value of the parameter. For Boolean parameters, allowed values are "0", "false", "1" or "true".
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.120   rcRsmStub 

Generate a stub file.

Syntax

rcRsmStub (
    RcRsmFile *hRsm,
    char *stubFile,
    char *params,
);
Parameters
hRsm
A pointer to a build file as returned by rcRsmOpen .
stubFile
The name of the stub file. C source code containing definitions for all incomplete variable and function declarations will be stored in this file.
params
A string containing additional parameters. Currently, params is ignored, so it can be NULL.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.121   rcSetParameterValue 

Set the value of a global Reactis parameter.

Syntax

int rcSetParameterValue (
    RcHandle *h,
    char *name,
    char *value,
);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
name
The name of the parameter. See Sections 15.8 and 15.9.
value
The new value of the parameter. For Boolean parameters, allowed values are "0", "false", "1" or "true".
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.122   rcSetStringEncoding 

Sets the character encoding for strings returned by functions like rcGetLastError and rcTesterGetStatus . If not set, the strings will be UTF8-encoded.

Syntax

int rcSetStringEncoding (const char *s);
Parameters
s
Name of a character encoding standard, such as "UTF8". Note that s is not case-sensitive.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.123   rcSeverityFromString 

Converts a string to an individual RcSeverity value.

Syntax

RcSeverity  rcSeverityFromString (const char *str);
Parameters
str
String holding the name of an RcSeverity value.
Return Value
Returns the individual RcSeverity value whose name matches str (using case-insensitive comparison). The RcSeverity values are listed in Section 15.5.11.

Returns RcSevNone if there is no match, in which case rcGetLastError should not be called.

15.7.124   rcSeverityToString 

Converts an individual severity value to a string.

Syntax

const char *rcSeverityToString (RcSeverity  str);
Parameters
str
String containing the name of a target status.
Return Value
Returns a constant string representing the value of sev if sev is one of the individual severity values. The RcSeverity values are listed in Section 15.5.11.

Returns NULL if sev is not one of the individual RcSeverity values, in which case rcGetLastError should not be called.

15.7.125   rcSimClose 

Terminates a Reactis Simulator session started by rcSimOpen .

Syntax

void rcSimClose (RcSim *sim);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
Return Value
None.

15.7.126   rcSimExportCCoverageDetails 

Exports C source code coverage details to CSV (comma separated value) format.

Syntax

int rcSimExportCCoverageDetails (
    RcSim *sim,
    const char *fileName1,
    const char *fileName2,
    const char *options
);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
fileName1
Path and name of the coverage details output file. The format of this file is described in Section 15.4.
fileName2
Path and name of the macro information output file. The format of this file is described in Section 15.4.1. If NULL, no macro is information is exported.
options
Export control options. This argument is for future expansion and is currently ignored.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.127   rcSimExportSuite 

Exports a test suite to CSV (comma separated value) or MATLAB script format.

Syntax

int rcSimExportSuite (
    RcSim *sim,
    RcTestSuite *suite,
    const char *fileName
);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
suite
Pointer to RcTestSuite structure that was created by rcSuiteOpen , rcTester  or rcSimImportSuite .
fileName
Path and name of the target file. The export function determines the export format by the filename extension:
.csvExport as a CSV (comma separated value) file
.mExport as a MATLAB script file
.matExport as a MATLAB binary file
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.128   rcSimExportSuiteEx 

Exports a test suite to CSV (comma separated value) or MATLAB script format.

Syntax

int rcSimExportSuiteEx (
    RcSim *sim,
    RcTestSuite *suite,
    const char *fileName,
    const char *params
);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
suite
Pointer to RcTestSuite structure that was created by rcSuiteOpen , rcTester  or rcSimImportSuite .
fileName
Path and name of the target file. The export function determines the export format by the filename extension:
.csvExport as a CSV (comma separated value) file
.mExport as a MATLAB script file
.matExport as a MATLAB binary file
params
Additional parameters for the export function:
-f formatSet export format. Use this to set the export format if it can not be determined by the file name extension of your file name. Possible values are the same as the file name extensions given above (without the leading “.”).
-wExport to From Workspace block format. Use this in conjunction with a mat export format to export data that can be used in fromWorkspace blocks.
-C When exporting CSV format, specify this option to strip the leading “|” character off configuration variable names.
-cWhen exporting CSV format, specify this option to omit test steps where no exported item (except simulation time) has changed from the previous step.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.129   rcSimImportSuite 

Imports a test suite from a CSV (comma separated value) formatted file or from an RST file. In the latter case ports or configuration variables may be deleted or added to the test suite to make the imported suite conform to the current test harness.

Syntax

RcTestSuite * rcSimImportSuite (
    RcSim *sim,
    const char *fileName
);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
fileName
Path and name of the source file. The import function determines the file format by the filename extension:
.csvImport a CSV (comma separated value) file
.rstImport a Reactis test suite. Add or remove input ports, output ports and configuration variables to match the current test harness.
Return Value
Pointer to a RcTestSuite structure that can be used to run it in a Simulator session. NULL, if the import failed. In that case, call rcGetLastError to retrieve the error message string.

15.7.130   rcSimImportSuiteEx 

Imports a test suite from a CSV (comma separated value) formatted file or from an RST file. In the latter case ports or configuration variables may be deleted or added to the test suite to make the imported suite conform to the current test harness.

Syntax

RcTestSuite * rcSimImportSuiteEx (
    RcSim *sim,
    const char *fileName,
    const char *params
);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
fileName
Path and name of the source file. The import function determines the file format by the filename extension:
.csvImport a CSV (comma separated value) file
.rstImport a Reactis test suite. Add or remove input ports, output ports and configuration variables to match the current test harness.
params
Additional parameter for the export function:
-f formatSet import format. Use this to set the import format if it can not be determined by the file name extension of your file name. Possible values are the same as the file name extensions given above (without the leading “.”).
-cWhen importing CSV format, specify this flag to automatically insert missing steps in the test data. If this flag is not given, the time values in the CSV file must match up exactly with the time steps in the program under test.
Return Value
Pointer to a RcTestSuite structure that can be used to run it in a Simulator session. NULL, if the import failed. In that case, call rcGetLastError to retrieve the error message string.

15.7.131   rcSimImportSuites 

Imports multiple test suites from CSV (Comma separated value) format into the same RST file.

Syntax

RcTestSuite * rcSimImportSuites (
    RcSim *sim,
    int numFiles
    const char *fileNames[]
);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
numFiles
Number of filenames provided in the fileNames array parameter
fileNames
Array containing paths and names of the source files. The import function determines the file format by the filename extension:
.csvImport a CSV (comma separated value) file
Return Value
Pointer to a RcTestSuite structure that can be used to run it in a Simulator session. NULL, if the import failed. In that case, call rcGetLastError to retrieve the error message string.

15.7.132   rcSimOpen 

Initializes a Reactis Simulator session.

Syntax

RcSim *rcSimOpen (     RcHandle *h,
    const char *buildFileName,
    const char *harnessFileName
);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
buildFileName
path and name of a Reactis build file (.rsm file).
harnessFileName
Path and name of a Reactis harness library file (.rsh file). Can be NULL, in which case the name will] be derived by changing the extension of buildFileName to .rsh.
Return Value
Pointer to a RcSim structure that must be used in all subsequent calls to this simulator session. A NULL value is returned, if the invocation of Reactis Simulator failed. In that case, calling rcGetLastError retrieves the error message string.

15.7.133   rcSimRunSuite 

Runs a test suite in a Reactis Simulator session.

Syntax

int rcSimRunSuite (RcSim *sim, RcTestSuite *suite);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
suite
Pointer to RcTestSuite structure that was created by rcSuiteOpen or rcTester .
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.134   rcSimRunSuiteWithReport 

Run a test suite in a Reactis Simulator session and generate an HTML report about the simulation run.

Syntax

int rcSimRunSuiteWithReport (
    RcSim  *sim,
    RcTestSuite  *suite,
    const char *reportFileName,
    const RcReportConfig *reportConfig
);
Parameters
sim
pointer to an RcSim structure that was previously opened with rcSimOpen .
suite
pointer to RcTestSuite  structure that was created by rcSuiteOpen  or rcTester .
reportFileName
file name of the HTML report produced for the simulation run.
reportConfig
Determines what information is included in the test execution report. If reportConfig is NULL, then a default configuration is used, which currently includes everything in the report except MCC target information.
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.135   rcSimUpdateOutputs 

Runs a test suite in a Reactis Simulator session and update the test suite’s output vectors according to the values produced by the program under test. The filename specifying the new test suite must not equal the test suite’s current location.

Syntax

int rcSimUpdateOutputs (
    RcSim *sim,
    RcTestSuite *suite,
    const char *fileName
);
Parameters
sim
Pointer to RcSim structure that was previously opened with rcSimOpen .
suite
Pointer to RcTestSuite structure that was created by rcSuiteOpen , rcTester  or rcSimImportSuite .
fileName
The new filename of the test suite after updating the outputs. If the filename has an extension of .mat then Reactis will update the outputs using Simulink (same as invoking Test Suite -> Update Outputs -> Using Simulink from the Reactis GUI).
Return Value
1
if successful.
0
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.

15.7.136   rcSuiteClose 

Closes a test suite that was opened by rcSuiteOpen or created by rcTester .

Syntax

void rcSuiteClose (RcTestSuite *suite);
Parameters
suite
Pointer to RcTestSuite structure as returned by rcSuiteOpen or rcTester .
Return Value
None.

15.7.137   rcSuiteGetNumTests 

Returns the number of tests in a test suite.

Syntax

int rcSuiteGetNumTests (RcTestSuite *suite);
Parameters
suite
Pointer to RcTestSuite structure as returned by rcSuiteOpen or rcTester .
Return Value
Returns the number of tests in the test suite specified by the suite parameter or -1 if an error occurred. In that case you may call rcGetLastError to retrieve the error message string.

15.7.138   rcSuiteGetReactisVersion 

Returns the version of Reactis that created this test suite.

Syntax

const char *rsSuiteGetReactisVersion(RcTestSuite *suite);
Parameters
suite
Pointer to RcTestSuite structure as returned by rcSuiteOpen or rcTester .
Return Value
Pointer to an internal character buffer containing the Reactis version string. For information on version string composition see appendix B. NULL, if an error occurred while retrieving the version. In that case you may call rcGetLastError to retrieve the error message string.

15.7.139   rcSuiteGetTestNumSteps 

Returns the number of steps for a test in a test suite.

Syntax

int rcSuiteGetNumTestSteps (RcTestSuite *suite, int index);
Parameters
suite
Pointer to RcTestSuite structure as returned by rcSuiteOpen or rcTester .
index
Index of the test to query. This value must be greater or equal to 0 and less than the return value of rcSuiteGetNumTests .
Return Value
Returns the number of steps in the test specified by the index parameter in the test suite specified by the suite parameter or -1 if an error occurred. In that case you may call rcGetLastError to retrieve the error message string.

15.7.140   rcSuiteGetTestName 

Returns the name of a test in a test suite.

Syntax

int rcSuiteGetTestName (
    RcTestSuite *suite,
    int index,
    char *buffer,
    int bufferSize
);
Parameters
suite
Pointer to RcTestSuite structure as returned by rcSuiteOpen or rcTester .
index
Index of the test to query. This value must be greater or equal to 0 and less than the return value of rcSuiteGetNumTests .
buffer
The buffer that receives the test name. The buffer’s size must correspond to the value of the bufferSize parameter. If the buffer parameter is NULL then the value returned by rcSuiteGetTestName will be the buffer size required to store the whole name.
bufferSize
The size of the buffer passed in as the third argument. If the actual name is longer than this value, it will be truncated to the length of the buffer. In that case the return value of rcSuiteGetTestName will be the buffer size that would be required to receive the whole name.
Return Value
−1
if an error occurred, in which case rcGetLastError may be called to retrieve the error message.
0
if successful.
N
if either the buffer parameter is NULL or the bufferSize parameter was not sufficient to receive the name. In this case, N specifies the buffer size required to store the complete name.
.

15.7.141   rcSuiteOpen 

Loads a test suite from a file.

Syntax

RcTestSuite *rsSuiteOpen(RcHandle *h, const char *testSuiteFileName);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
testSuiteFileName
Path and name of the Reactis test suite file (.rst file) to open.
Return Value
Pointer to a RcTestSuite structure that can be run in a simulator session. A NULL value is returned if file does not exist or cannot be read.

15.7.142   rcSuiteSave 

Saves a test suite.

Syntax

int rcSuiteSave (RcTestSuite *suite, const char *filename);
Parameters
suite
Pointer to RcTestSuite structure as returned by rcSuiteOpen or rcTester .
filename
Filename and path to which the suite should be saved.
Return Value
1
if successful.
0
if unsuccessful, in which case rcGetLastError should not be called.

15.7.143   rcTargetStatusFromString 

Converts a string to an individual target status.

Syntax

RcTargetStatus rcTargetStatusToString (const char *str);
Parameters
str
A string containing the name of an individual target status. See Section 15.12.4 for the list of valid names.
Return Value
Returns the target status whose value matches str (using case-insensitive comparison). The target status values are listed in Section 15.5.13.

Returns RcTgtNone if there is no match. In this case rcGetLastError should not be called.

15.7.144   rcTargetStatusToString 

Converts an individual target status to a string.

Syntax

const char *rcTargetStatusToString (RcTargetStatus  stat);
Parameters
stat
One of the individual target status values listed in Section 15.5.13.
Return Value
Returns a constant string representing the value of stat, if stat is one of the individual status values listed in Section 15.5.13. The value of this string will be one of the names listed in Section 15.12.4.

Returns NULL if stat is not one of the individual target status values. In this case rcGetLastError should not be called.

15.7.145   rcTester 

Creates a test suite.

Syntax

RcTestSuite *rcTester (
    RcHandle *h,
    const char *buildFileName,
    const char *harnessFileName,
    const char *testSuiteFileName,
    const char *params
);
Parameters
h
Pointer to RcHandle structure as returned by rcOpen .
buildFileName
path and name of a Reactis build file (.rsm file).
harnessFileName
Path and name of a Reactis harness library file (.rsh file). Can be NULL, in which case the name will] be derived by changing the extension of buildFileName to .rsh.
testSuiteFileName
Path and name of the resulting test suite file (.rst file). The file must be writable and will be overwritten if it already exists. testSuiteFileName can be NULL in which case a temporary file will be created which will be deleted when calling rcSuiteClose .
params
A string containing parameters for test-suite generation. See Section 15.11 for details.
Return Value
Pointer to a RcTestSuite structure that can be used to run it in a Simulator session. NULL, if Reactis Tester failed. In that case, call rcGetLastError to retrieve the error message string.

15.7.146   rcTesterClose 

Closes the Reactis Tester instance given as a parameter. The pointer passed as a parameter will be invalid after this call.

Syntax

void rcTesterClose (RcTester *tester);
Parameters
tester
Pointer to an RcTester instance which was previously started with rcTesterStart .
Return Value
None.

15.7.147   rcTesterGetProgress 

Queries the progress of a Reactis Tester instance.

Syntax

double rcTesterGetProgress (RcTester *tester);
Parameters
tester
Pointer to an RcTester instance which was previously started with rcTesterStart .
Return Value
A number between 0 and 100 to indicate the progress of the Reactis Tester instance given as a parameter (similar to the progress indicator in the Tester dialog within the Reactis GUI).

15.7.148   rcTesterGetStatus 

Queries the status of a Reactis Tester instance.

Syntax

const char *rcTesterGetStatus (RcTester *tester);
Parameters
tester
Pointer to an RcTester instance which was previously started with rcTesterStart .
Return Value
A string indicating the current status of the Reactis Tester instance given as a parameter (similar to the status field in the Tester dialog within the Reactis GUI).

15.7.149   rcTesterGetSuite 

Gets the test suite generated by a Reactis Tester instance.

Syntax

RcTestSuite *rcTesterGetSuite (RcTester *tester);
Parameters
tester
Pointer to an RcTester instance which was previously started with rcTesterStart .
Return Value
The test suite generated by the Reactis Tester instance given as a parameter. Must be called after Tester has finished (i.e., when rcTesterIsRunning returns 0). Returns NULL if Tester is still running or an error occurred that prevented the creation of a test suite.

15.7.150   rcTesterIsRunning 

Determines if a Reactis Tester instance is still running.

Syntax

int rcTesterIsRunning (RcTester *tester);
Parameters
tester
Pointer to an RcTester instance which was previously started with rcTesterStart .
Return Value
1
if the Reactis Tester instance given as a parameter is still running.
0
otherwise.

15.7.151   rcTesterStart 

Initiates creation of a test suite. This function is similar to rcTester but returns immediately after initiating the creation of the test suite. Reactis Tester will keep running in the background after this function returns. Use the access functions rcTesterGetProgress , rcTesterGetStatus and rcTesterIsRunning to get the progress and status of the running Tester instance. Use the function rcTesterGetSuite to get the test suite created after Tester has finished. Use the function rcTesterStop to stop a Tester session. Use the function rcTesterClose to close a Reactis Tester instance.

Syntax

rcTester *rcTesterStart (
    RcHandle *h,
    const char *buildFileName,
    const char *harnessFileName,
    const char *testSuiteFileName,
    const char *params
);
Parameters
(Note that the parameters below are the same as for function rcTester .)
h
Pointer to RcHandle structure as returned by rcOpen .
buildFileName
path and name of a Reactis build file (.rsm file).
harnessFileName
Path and name of a Reactis harness library file (.rsh file). Can be NULL, in which case the name will] be derived by changing the extension of buildFileName to .rsh.
testSuiteFileName
Path and name of the resulting test suite file (.rst file). The file must be writable and will be overwritten if it already exists. testSuiteFileName can be NULL in which case a temporary file will be created which will be deleted when calling rcSuiteClose .
params
A string containing parameters for test-suite generation. See Section 15.11 for details.
Return Value
Pointer to a RcTester structure that must be used in all subsequent calls to the functions rcTesterGetStatus , rcTesterGetSuite , rcTesterIsRunning , rcTesterStop and rcTesterClose . NULL, if Reactis Tester failed to start. In that case, call rcGetLastError to retrieve the error message string.

15.7.152   rcTesterStartWithReport 

Initiates creation of a test suite with report generation. This function is similar to rcTesterStart , with a test execution report produced as an additional output. Like rcTesterStart , this function returns immediately after initiating the creation of the test suite. Reactis Tester will keep running in the background after this function returns. Use the access functions rcTesterGetProgress , rcTesterGetStatus and rcTesterIsRunning to get the progress and status of the running Tester instance. Use the function rcTesterGetSuite to get the test suite created after Tester has finished. Use the function rcTesterStop to stop a Tester session. Use the function rcTesterClose to close a Reactis Tester instance.

Syntax

rcTester *rcTesterStartWithReport (
    RcHandle *h,
    const char *buildFileName,
    const char *harnessFileName,
    const char *testSuiteFileName,
    const char *params
    const char *reportFileName,
    const RcReportConfig *reportConfig
);
Parameters
(Note that the first five parameters below are the same as for function rcTesterStart .)
h
Pointer to RcHandle structure as returned by rcOpen .
buildFileName
path and name of a Reactis build file (.rsm file).
harnessFileName
Path and name of a Reactis harness library file (.rsh file). Can be NULL, in which case the name will] be derived by changing the extension of buildFileName to .rsh.
testSuiteFileName
Path and name of the resulting test suite file (.rst file). The file must be writable and will be overwritten if it already exists. testSuiteFileName can be NULL in which case a temporary file will be created which will be deleted when calling rcSuiteClose .
params
A string containing parameters for test-suite generation. See Section 15.11 for details.
reportFileName
Path and name of the resulting test execution report file. The file must be writable and will be overwritten if it already exists. The format of the file is determined by the extension. Currently, an extension of .htm or .html results in HTML data.
reportConfig
Determines what information is included in the test execution report. If reportConfig is NULL, then a default configuration is used, which currently includes everything in the report except MCC target information.
Return Value
Pointer to an RcTester structure that must be used in all subsequent calls to the functions rcTesterGetStatus , rcTesterGetSuite , rcTesterIsRunning , rcTesterStop and rcTesterClose . NULL, if Reactis Tester failed to start. In that case, call rcGetLastError to retrieve the error message string.

15.7.153   rcTesterStop 

Stops execution of a Reactis Tester instance.

Syntax

void rcTesterStop (RcTester *tester);
Parameters
Stops the Reactis Tester instance given as a parameter. rcTesterGetSuite can still be called after this and will return the (incomplete) test suite.
Return Value
tester
Pointer to an RcTester instance which was previously started with rcTesterStart .

None.

15.7.154   rcTesterWithReport 

Creates a test suite and a test execution report.

Syntax

RcTestSuite *rcTesterWithReport (
    RcHandle *h,
    const char *buildFileName,
    const char *harnessFileName,
    const char *testSuiteFileName,
    const char *params
    const char *reportFileName,
    const RcReportConfig *reportConfig
);
Parameters
(Note that the first five parameters below are the same as for function rcTester .)
h
Pointer to RcHandle structure as returned by rcOpen .
buildFileName
path and name of a Reactis build file (.rsm file).
harnessFileName
Path and name of a Reactis harness library file (.rsh file). Can be NULL, in which case the name will] be derived by changing the extension of buildFileName to .rsh.
testSuiteFileName
Path and name of the resulting test suite file (.rst file). The file must be writable and will be overwritten if it already exists. testSuiteFileName can be NULL in which case a temporary file will be created which will be deleted when calling rcSuiteClose .
params
A string containing parameters for test-suite generation. See Section 15.11 for details.
reportFileName
Path and name of the resulting test execution report file. The file must be writable and will be overwritten if it already exists. The format of the file is determined by the extension. Currently, an extension of .htm or .html results in HTML data.
reportConfig
Determines what information is included in the test execution report. If reportConfig is NULL, then a default configuration is used, which currently includes everything except MCC target information.
Return Value
Pointer to a RcTestSuite structure that can be used to run it in a Simulator session.

NULL, if Reactis Tester failed. In that case, call rcGetLastError to retrieve the error message string.

15.7.155   rcVersion 

Determine the Reactis version.

Syntax

const char *rsVersion();
Parameters
None.
Return Value
Pointer to an internal character buffer containing the Reactis version string. For information on version string composition see appendix B.

15.7.156   rcVersionParse 

Parses a Reactis version string (as returned by functions rcVersion or rcSuiteGetReactisVersion ) and returns the major, minor and patch number.

Syntax

int rcVersionParse (
    const char *versionString,
    int *major,
    int *minor,
    int *patch
);
Parameters
versionString
Character string representing a version of Reactis as returned by function rcVersion or rcSuiteGetReactisVersion . For information on version string composition see appendix B.
major
Pointer to an integer receiving the major version number.
minor
Pointer to an integer receiving the minor version number.
patch
Pointer to an integer receiving the patch number.
Return Value
1
if successful.
0
if unsuccessful, in which case rcGetLastError should not be called.

15.8  Reactis Global Parameters

The general behavior of Reactis is influenced by a set of general parameters, which can be accessed via the rcGetParameterValue  and rcSetParameterValue  functions. Each parameter described in this section can also be manipulated from the Global Settings dialog invoked via File -> Global Settings... in the main window of the Reactis GUI. The parameter names and allowed values are described below. For a more detailed description of the functionality being controlled see Section 4.3. The parameters are listed below in groups corresponding to the different tabs of the Global Settings dialog.

15.8.1  General

EnableLogging
(boolean): Enable Reactis’ logging facility. Enabling this can decrease performance and may generate large log files. Only enable this if asked to do so by the Reactis support team.
LogLevel
(string): Set information about what to write to the Reactis log file (see parameter EnableLogging). If you are asked to create a log file by the Reactis support team, the required LogLevel string will be indicated.
LogFile
(string): Set the location of Reactis’ log file to be created if logging is enabled (see parameter EnableLogging).

15.8.2  Files

ReactisFilesDir
(string): The directory where Reactis stores files that it creates and uses.

15.8.3  User Info

UserName
(string): Name of the current user. Setting this to three dashes ("---") will make Reactis use the logon name of the current user. This information will be reported to the license server.
UserPhone
(string): Phone number of the current user. This information will be reported to the license server.

15.9  Default Harness Library Parameters

When a harness library is created, the initial value of each parameter listed in Section 15.10 is set to a default value, which is stored in a global parameter with the same name, which is accessed via rcGetParameterValue  and rcSetParameterValue . These parameters can also be changed from the Default Harness Library Settings dialog.

15.10  Harness Library Parameters

Each harness library (.rsh file) contains a set of parameters which are shared between all harnesses in the library and control the behavior of Reactis when the harness library is loaded. These parameters are accessed via the API functions rcRshGetParameterValue and rcRshSetParameterValue . Each parameter described in this section can also be manipulated from the Reactis Harness Editor dialog and are grouped by the subsection in which they appear.

When a harness library is created, the initial value of each of these parameters is taken from a default value as described in Section 15.9.

15.10.1  Files

See Section 6.2 for additional details on these parameters.

CreateTesterParameterFiles
(Boolean): When creating a test suite, also create a parameters file (a file with extension .rtp)
DoCCaching
(Boolean): Create and use cache files (files with extension .rso, .rsls, .rsld, or .rsx)
CPromoteFloatToDouble
(Boolean): Enable/disable the implicit promotion of float values to double before performing calculations. Setting this to true provides greater accuracy and compatibility with many compilers. For strict C99 compliance, this should be set to false.

15.10.2  Error Detection

See Section 6.10 for additional details on these parameters.

CLoopDetectionTimeout
(double in range 0.0 to 10300): Maximum time in seconds for Reactis to compute a simulation step. If the computation of a simulation step takes longer, Reactis assumes there is an infinite loop, and the simulation is terminated and an error message printed.
DeltaExceedsTypeRange
(possible values: "none", "warning", or "error"): The action to take when the delta setting for an input type is larger than the range of the input type.
OnCDetectInfNan
(possible values: "none", "warning", "error", or "inherit"): Set behavior when encountering ’infinity’ or ’not-a-number’ values in C code. When set to ’inherit’ the C Plugin will use the value of ’OnDetectInfNan.’
OnCEmptyStruct
(possible values: "none", "warning", or "error"): The action to take when a struct is declared with no members. For strict C99 compliance, this should be set to ’error’.
OnCFloatToUIntConversionOverflow
(possible values: "none", "error", or "inherit"): Set integer overflow behavior for C code during conversion from floating- point to unsigned integer. If set to ’inherit’ then the behavior is inherited from the ’OnCIntegerOverflow’ setting.
OnCIntegerOverflow
(possible values: "none" or "error"): Set integer overflow behavior for C code.
OnCIntegerConversionOverflow
(possible values: "none", "error", or "inherit"): Set integer overflow behavior for C code during conversion from unsigned integer to signed integer. If set to ’inherit’ then the behavior is inherited from the ’OnCIntegerOverflow’ setting.
OnCInvalidPointer
(possible values: "none", "warning", or "error"): Set behavior when a pointer expression yields an invalid address.
OnCUndefinedFunctionCall
(possible values: "none" or "error"): The action taken when an undefined function is called. When set to ’none’, Reactis stubs each undefined function that is called with a function that returns zero.
OnCUndefinedExternVar
(possible values: "none", "warning", or "error"): The action taken when an undefined function is accessed. When set to ’none’, Reactis stubs each undefined variable by creating an instance which is initialized to zero.
OnCUnsignedIntegerOverflow
(possible values: "none", "warning", or "error"): The action to take when an unsigned integer overflow occurs.
OnShiftOutOfRange
(possible values: "none", "warning", "error", or "inherit"): The action to take when a value is shifted by an amount which is either (a) greater than or equal to the width of the value, or (b) negative.
Tolerance
(double): When running a test suite in Reactis Simulator, the values of outputs and test points computed by the program under test are compared to those stored in the test suite. A warning is produced if the relative difference exceeds the tolerance given in this parameter. The value of this parameter is used as the default value for any output whose value is inherited.

15.10.3  Coverage

See Section 6.11 for additional details on these parameters.

CoverageAssertion (Boolean): Enables or disables tracking of the Assertion coverage metric.
CoverageBoundary (Boolean): Enables or disables tracking of the Boundary coverage metric.
CoverageCFunction (Boolean): Enables or disables tracking of the CFunction coverage metric.
CoverageCFunctionCall (Boolean): Enables or disables tracking of the CFunctionCall coverage metric.
CoverageCondition (Boolean): Enables or disables tracking of the Condition coverage metric.
CoverageCStatement (Boolean): Enables or disables tracking of the CStatement coverage metric.
CoverageDecision (Boolean): Enables or disables tracking of the Decision coverage metric.
CoverageMCC (Boolean): Enables or disables tracking of the MCC coverage metric.
CoverageMCDC (Boolean): Enables or disables tracking of the MCDC coverage metric.
CoverageUserTarget (Boolean): Enables or disables tracking of the UserTarget coverage metric.
CoverageMCCMaxNumConditions
(Non-negative integer): The maximum number of conditions per decision for which MCC coverage will be tracked.
CDecisionMetric
(possible values: "ifwhilefor", "branching", "nonstatic", "all"): Specifies the criteria for determining which expressions are decisions.
ifwhilefor
Expressions which control if/while/for statements
branching
Expressions which control if/while/for statements or the ? operator
nonstatic
All non-trivial Boolean expressions except static initializers.
all
Same as "nonstatic" (may change in future)

15.11  Tester Parameters

The API functions rcTester , rcTesterStart , rcTesterWithReport , and rcTesterStartWithReport all accept a string containing command line style parameters (separated by whitespace) which control Tester behavior. This string may include zero or more of the following flags, all of which are optional.

-a{0|1}
Turns input abstraction on (1) or off (0). Inputs abstraction usually improves the performance of Tester and should be left on (default). In rare cases, turning it off may improve coverage. If coverage problems are encountered with inputs abstraction on, it may be beneficial to take a test suite produced with abstraction on, preload it into Tester, turn abstraction off, and then run Tester again.
-g m1;m2;;mn
Specify a list of metrics that should be used to guide test suite generation. Possible values for m1, m2, … mn are listed in the table below. The names of the available metrics are given in Section 15.12.1. For additional information on coverage metrics, see Chapter 7.
-p file1={y|n};file2={y|n};;filen={y|n}
Specify a list of .rst files to preload. The y|n argument for each file specifies whether or not pruning of the suite should be allowed. The random and targeted phases will extend the preloaded tests. The preloaded test suite files will not be modified.
-q timeoutSeconds
Specify the number of seconds for which to produce test cases. Tester will stop after either the timeout expires, all steps steps in the random or targeted phases have been executed, or full coverage is achieved for the program under test, whichever comes first. If -q is given and -t is not given then Tester will continue until either the timeout expires or full coverage is achieved.
-r numTests;numSteps
Specify the number of tests and steps in the random phase. The defaults are 5 tests of 1000 steps each.
-s randomSeed
Initial seed for the random number generator.
-t stepsInTargetedPhase
The number of execution steps to take during the targeted phase of test generation. The default is 20000 steps.

15.12  Names recognized by the API

15.12.1  Coverage metric names

The following coverage metric (RcCoverageMetric ) names are recognized by the API:


ConstantName
RcCvgDecision "Decision"
RcCvgCondition "Condition"
RcCvgMCDC "MCDC"
RcCvgMCC "MCC"
RcCvgBoundary "Boundary"
RcCvgUserTarget "UserTarget"
RcCvgAssertion "Assertion"
RcCvgCStatement "CStatement"
RcCvgCFunction "CFunction"
RcCvgCFunctionCall "CFunctionCall"


See Section 15.5.1 for details on RcCoverageMetric .

15.12.2  Report item names

The following coverage report item (RcReportItem ) names are recognized by the API:


ConstantName
RcRptExportDate "ExportDate"
RcRptFilePaths "FilePaths"
RcRptTableOfContents "TableOfContents"
RcRptSummary "Summary"
RcRptFunCalls "FunCalls"
RcRptCoverage "Coverage"


See Section 15.5.4 for details on RcReportItem .

15.12.3  Severity Names

The following message severity (RcSeverity ) names are recognized by the API:


ConstantName
RcSevNote "Note"
RcSevWarning "Warning"
RcSevError "Error"


See Section 15.5.11 for details on RcSeverity .

15.12.4  Coverage status names

The following coverage target status (RcTargetStatus ) names are recognized by the API:


ConstantName
RcTgtCovered "Covered"
RcTgtUncovered "Uncovered"
RcTgtUnreachable "Unreachable"


See Section 15.5.13 for details on RcTargetStatus .

15.12.5  Variable kind names

The following variable kind status (RcRshVarKind ) names are recognized by the API:


ConstantName
RcInputVar "input"
RcOutputVar "output"
RcConfigVar "config"


See Section 15.5.10 for details on RcRshVarKind .

15.13  MATLAB API

Reactis for C includes a library of MATLAB functions which can be used to access the Reactis for C API. To use these functions, you need to add the directories containing (1) the Reactis executable, (2) the API library, and (3) the API MATLAB scripts to the MATLAB search path. If Reactis is installed in the directory REACTIS, then these directories will be (1) REACTIS\bin, (2) REACTIS\lib\api, and (3) REACTIS\lib\api\MATLAB\reactis4c.

For example, if Reactis is installed in C:\Program Files (x86)\Reactis for C V2016, then the following commands will add the required directories to the MATLAB search path:

reactis4cDir='C:\Program Files (x86)\Reactis for C V2016';
addpath(fullfile(reactis4cDir,'bin'));
addpath(fullfile(reactis4cDir,'lib','api'));
addpath(fullfile(reactis4cDir,'lib','api','MATLAB','reactis4c'));

After the search path is updated, the command help reactis4c will list the available Reactis for C API functions.