Main Content

Access Element-Specific C API Maps

Element-specific maps are structure arrays dedicated each for storing information about a distinct type of model elements such as model signals. Each entry within these arrays corresponds to a particular model element, acting as the gateway to obtain information about the element. These are the element-specific C API maps:

  • Root-level input port signals — Gateway to output signals of root-level input port blocks

  • Root-level output port signals — Gateway to input signals of root-level output port blocks

  • Inner model signals — Gateway to output signals of blocks that are not root-level input-port blocks

  • Model parameters — Gateway to parameters that are available to be used by the model, and that are used by at least one model element

  • Block parameters — Gateway to block parameters

  • Block states — Gateway to block states

Each entry contains:

  • Direct information such as the element name (as a field of type char*).

  • Indirect information in the form of indices that reference entries in property-specific C API arrays. The referenced entries provide further information about the model element. For example, the data type of the element is provided as an index that references the data type map array. The referenced entry in the data type map array contains information about the data type of the element. To learn how to use those indices, see Access Property-Specific C API Arrays.

Some model elements belong to multiple types of C API elements and can therefore be accessed in multiple ways. For example, a signal line that connects a Gain block and an Outport block can be accessed as a model signal or as a root-level output port signal.

For exhaustive information about how to access element-specific C API information, see C Code Syntax for Accessing Element-Specific C API Arrays, which includes:

Access Model Signals Example

This is an example C language function that obtains initial information about model signals.

The example code is also provided as standalone code (see Standalone C Code for Accessing Model Signals Example) so that you can copy it more easily.

C Code for Accessing Model Signals Example

DescriptionSample C Code with Direct Data Structure AccessSample C Code with Macros and Get-Functions

Include these header files:

  • AccessCapiDemoMdl.h — The generated model header, so you can access the real-time model object.

  • capiAccessModelSignals.h — The file that contains the declaration of the function provided in the example.

  • rtw_capi.h and rtw_modelmap.h — The files that contain declarations and definitions of the structures accessed and macros used in the example. These files are located in the folder matlabroot/rtw/c/src/.

 
# include "AccessCapiDemoMdl.h"
# include "rtw_modelmap.h"
# include "rtw_capi.h"
# include <stdio.h>
# include "capiAccessModelSignals.h"

# include "AccessCapiDemoMdl.h"
# include "rtw_modelmap.h"
# include "rtw_capi.h"
# include <stdio.h>
# include "capiAccessModelSignals.h"
Declare variables to use for storing the map objects and the signals information. 
const rtwCAPI_ModelMappingInfo *mainCapiMap;
const rtwCAPI_ModelMappingStaticInfo *capiStaticMap;

uint_T sigCount;
const rtwCAPI_Signals *capiSigArr;

const rtwCAPI_ModelMappingInfo *mainCapiMap;

uint_T sigCount;
const rtwCAPI_Signals *capiSigArr;
Get the pointers to the main and the static C API maps. See Obtain Access to C API Maps Example. 
void accessModelSignals()
{
  mainCapiMap = &AccessCapiDemoMdl_M->DataMapInfo.mmi;
  capiStaticMap = mainCapiMap->staticMap;
 
void accessModelSignals()
{
  mainCapiMap = ...
         &rtmGetDataMapInfo(AccessCapiDemoMdl_M).mmi;

  % You do not need the static map when using macros.
Extract the number of signals that are included in the generated C API code. 
  sigCount = (capiStaticMap->Signals).numSignals;
 
  sigCount = rtwCAPI_GetNumSignals(mainCapiMap);
Obtain the pointer to the signal structure array. 
  capiSigArr = (capiStaticMap->Signals).signals;
 
  capiSigArr = rtwCAPI_GetSignals(mainCapiMap);
Print the number of signals and their names. 
  printf("Found %i signals, with these names:.\n",sigCount);
  for(int idx=0 ; idx<sigCount ; idx++)
  {
    if(strlen(capiSigArr[idx].signalName))
    {
      printf("    Signal %i is named '%s'.\n",
                 idx,capiSigArr[idx].signalName);
    }
    else
    {
      printf("    Signal %i has no name.\n",idx);
    }
  }
}
 
  printf("Found %i signals, with these names:.\n",sigCount);
  for(int idx=0 ; idx<sigCount ; idx++)
  {
    if(strlen(capiSigArr[idx].signalName))
    {
      printf("    Signal %i is named '%s'.\n",
        idx,rtwCAPI_GetSignalName(capiSigArr,idx);
    }
    else
    {
      printf("    Signal %i has no name.\n",idx);
    }
  }
}

Here is a schematic illustration of the map structure that is accessed by the code in the example:

The model has two signals named mySig_1 and mySig_1.

Standalone C Code for Accessing Model Signals Example

 Ready-to-Copy Standalone C Code

C Code Syntax for Accessing Element-Specific C API Arrays

In these tables you can find exhaustive information about how to access element-specific C API arrays. Your code can access each type of model elements by using the direct approach, or by using get-function-like macros.

C Code for Accessing Signal C API Information

Required Item / InformationCode for Direct Data Structure AccessCode for Access Through Get-Function-Like Macros

For each type of model signal, the signal count and the signal array. There are three main types of model signals:

  • Signals originating from root-level input port blocks

  • Signals originating from blocks that are not root-level input port blocks

  • Signals that enter root-level output port blocks

 
# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that capiStaticMap already defined and instantiated */

/* Signals that originate from root-level input port blocks */
uint_T inportCount = (capiStaticMap->Signals).numRootInputs;
const rtwCAPI_Sigs* inportSigArr = (capiStaticMap->Signals).rootInputs;

/* Signals that originate from non root-level input port blocks */
uint_T innerSigCount = (capiStaticMap->Signals).numSignals;
const rtwCAPI_Sigs* innerSigArr = (capiStaticMap->Signals).signals;

/* Signals that enter root-level output port blocks */
uint_T outportCount = (capiStaticMap->Signals).numRootOutputs;
const rtwCAPI_Sigs* outportSigArr = (capiStaticMap->Signals).rootOutputs;

# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that mainCapiMap already defined and instantiated */

/* Signals that originate from root-level input port blocks */
uint_T inportCount = rtwCAPI_GetNumRootInputs(mainCapiMap);
const rtwCAPI_Sigs* inportSigArr = rtwCAPI_GetRootInputs(mainCapiMap);

/* Signals that originate from non root-level input port blocks */
uint_T innerSigCount = rtwCAPI_GetNumSignals(mainCapiMap);
const rtwCAPI_Sigs* innerSigArr = rtwCAPI_GetSignals(mainCapiMap);

/* Signals that enter root-level output port blocks */
uint_T outportCount = rtwCAPI_GetNumRootOutputs(mainCapiMap);
const rtwCAPI_Sigs* outportSigArr;
outportSigArr = rtwCAPI_GetRootOutputs(mainCapiMap);
Direct information about specific signals 
# include "rtw_capi.h"

/* capiSigArr is any of the three types of model signals */
/* sigIdx is the zero-based index of the specific signal in capiSigArr */

/* Empty string if the signal has no name */
const char_T* sigName = capiSigArr[sigIdx].signalName;

/* Path of owner block */
const char_T* sigPath = capiSigArr[sigIdx].blockPath;

/* Zero-based port number used for signal by owner block */
uint16_T sigPortNum = capiSigArr[sigIdx].portNumber;

/* System identification number, where 0 is root */
uint_T sigSysNum = capiSigArr[sigIdx].sysNum;
 
# include "rtw_capi.h"

/* capiSigArr is any of the three types of model signals */
/* sigIdx is the zero-based index of the specific signal in capiSigArr */

/* Empty string if the signal has no name */
const char_T* sigName = rtwCAPI_GetSignalName(capiSigArr,sigIdx);

/* Path of owner block */
const char_T* sigPath = rtwCAPI_GetSignalBlockPath(capiSigArr,sigIdx);

/* Zero-based port number used for signal by owner block */
uint16_T sigPortNum = rtwCAPI_GetSignalPortNumber(capiSigArr,sigIdx);

/* System identification number, where 0 is root */
uint_T sigSysNum = rtwCAPI_GetSignalSysNum(capiSigArr,sigIdx);
Indirect information about specific signals, provided as indices that reference entries in property-specific arrays. For more information about property-specific C API arrays, see Access Property-Specific C API Arrays. 
# include "rtw_capi.h"

/* capiSigArr is any of the three types of model signals */
/* sigIdx is the index of the specific signal in capiSigArr */

/* Index into rtwCAPI_SampleTimeMap, which provides Task infomation */
uint8_T sigSampTimeInd = capiSigArr[sigIdx].sTimeIndex;

/* Index into rtwCAPI_DataTypeMap */
uint16_T sigDataTypeInd = capiSigArr[sigIdx].dataTypeIndex;

/* Index into rtwCAPI_DimensionMap */
uint16_T sigDimMapInd = capiSigArr[sigIdx].dimIndex;

/* Index into rtwCAPI_FixPtMap, holding fixed-point signal information */
uint16_T sigFxpInd = capiSigArr[sigIdx].fxpIndex;

/* Index into the (primitive type) address map holding the value of the signal */
uint_T sigAddMapInd = capiSigArr[sigIdx].addrMapIndex;
 
# include "rtw_capi.h"

/* capiSigArr is any of the three types of model signals */
/* sigIdx is the index of the specific signal in capiSigArr */

/* Index into rtwCAPI_SampleTimeMap, which provides Task infomation */
uint8_T sigSampTimeInd = rtwCAPI_GetSignalSampleTimeIdx(capiSigArr,sigIdx);

/* Index into rtwCAPI_DataTypeMap */
uint16_T sigDataTypeInd = rtwCAPI_GetSignalDataTypeIdx(capiSigArr,sigIdx);

/* Index into rtwCAPI_DimensionMap */
uint16_T sigDimMapInd = rtwCAPI_GetSignalDimensionIdx(capiSigArr,sigIdx);

/* Index into rtwCAPI_FixPtMap, holding fixed-point signal information */
uint16_T sigFxpInd = rtwCAPI_GetSignalFixPtIdx(capiSigArr,sigIdx);

/* Index into the (primitive type) address map holding the value of the signal */
uint_T sigAddMapInd = rtwCAPI_GetSignalAddrIdx(capiSigArr,sigIdx);

C Code for Accessing Model Parameters C API Information

Required Item / InformationCode for Direct Data Structure AccessCode for Access Through Get-Function-Like Macros
Model parameters, which can be shared by multiple model blocks 
# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that capiStaticMap already defined and instantiated */

/* Parameters shared by all model blocks */
uint_T modelParamCount = (capiStaticMap->Params).numModelParameters;

const rtwCAPI_ModelParameters* modelParamArr;
modelParamArr = (capiStaticMap->Params).modelParameters;

# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that mainCapiMap already defined and instantiated */

/* Parameters shared by all model blocks */
uint_T modelParamCount = rtwCAPI_GetNumModelParameters(mainCapiMap);

const rtwCAPI_ModelParameters* modelParamArr;
modelParamArr = rtwCAPI_GetModelParameters(mainCapiMap);
Direct information about specific parameters 
# include "rtw_capi.h"

/* modelParamArr is the pointer to the model parameter array */
/* paramIdx is the index of the specific parameter in modelParamArr */

const char_T* myModelParamName;
myModelParamName = modelParamArr[paramIdx].varName;
 
# include "rtw_capi.h"

/* modelParamArr is the pointer to the model parameter array */
/* paramIdx is the index of the specific parameter in modelParamArr */

const char_T* myModelParamName; 
myModelParamName = rtwCAPI_GetModelParameterName(modelParamArr,paramIdx);
Indirect information about specific parameter, provided as indices that reference entries in property-specific arrays. For more information about property-specific C API arrays, see Access Property-Specific C API Arrays 
# include "rtw_capi.h"

/* modelParamArr is the pointer to the model parameter array */
/* paramIdx is the index of the specific parameter in modelParamArr */

/* Index into rtwCAPI_DataTypeMap */
uint16_T myParamDataTypeInd = modelParamArr[paramIdx].dataTypeIndex;

/* Index into rtwCAPI_DimensionMap */
uint16_T myParamDimMapInd = modelParamArr[paramIdx].dimIndex;

/* Index into rtwCAPI_FixPtMap, holding fixed-point parameter information */
uint16_T myParamFxpInd = modelParamArr[paramIdx].fxpIndex;

/* Index into the (primitive type) address map 
   that holds the real-time value of the parameter */
uint_T myParamAddMapInd;
myParamAddMapInd = modelParamArr[paramIdx].addrMapIndex;
 
# include "rtw_capi.h"

/* modelParamArr is the pointer to the model parameter array */
/* paramIdx is the index of the specific parameter in modelParamArr */

/* Index into rtwCAPI_DataTypeMap */
uint16_T myParamDataTypeInd = rtwCAPI_GetModelParameterDataTypeIdx(modelParamArr,paramIdx);

/* Index into rtwCAPI_DimensionMap */
uint16_T myParamDimMapInd = rtwCAPI_GetModelParameterDimensionIdx(modelParamArr,paramIdx);

/* Index into rtwCAPI_FixPtMap, holding fixed-point parameter information */
uint16_T myParamFxpInd = rtwCAPI_GetModelParameterFixPtIdx(modelParamArr,paramIdx);

/* Index into the (primitive type) address map 
   that holds the real-time value of the parameter */
uint_T myParamAddMapInd;
myParamAddMapInd = rtwCAPI_GetModelParameterAddrIdx(modelParamArr,paramIdx);

C Code for Accessing Block Parameters C API Information

Required Item / InformationCode for Direct Data Structure AccessCode for Access Through Get-Function-Like Macros
Block parameters, used privately by specific model blocks 
# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that capiStaticMap already defined and instantiated */

uint_T blockParamCount = (capiStaticMap->Params).numBlockParameters;
const rtwCAPI_BlockParameters* blockParamArr;
blockParamArr = (capiStaticMap->Params).blockParameters;
 
# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that mainCapiMap already defined and instantiated */

/* Parameters used privately by specific blocks */
uint_T blockParamCount = rtwCAPI_GetNumBlockParameters(mainCapiMap);
const rtwCAPI_BlockParameters* blockParamArr;
blockParamArr = rtwCAPI_GetBlockParameters(mainCapiMap);
Direct information about specific parameters 
# include "rtw_capi.h"

/* blockParamArr is the pointer to the block parameter array */
/* paramIdx is the index of the specific parameter in blockParamArr */

const char_T* blockParamName = blockParamArr[paramIdx].paramName;

/* Path of owner block */
const char_T* blockParamPath;
myBlockParamPath = blockParamArr[paramIdx].blockPath;
 
# include "rtw_capi.h"

/* blockParamArr is the pointer to the block parameter array */
/* paramIdx is the index of the specific parameter in blockParamArr */

const char_T* blockParamName = 
                  rtwCAPI_GetBlockParameterName(blockParamArr,paramIdx);

/* Path of owner block */
const char_T* blockParamPath;
myBlockParamPath = rtwCAPI_GetBlockParameterBlockPath(blockParamArr,paramIdx);
Indirect information about specific parameter, provided as indices that reference entries in property-specific arrays. For more information about property-specific C API arrays, see Access Property-Specific C API Arrays. 
# include "rtw_capi.h"

/* blockParamArr is the pointer to the block parameter array */
/* paramIdx is the index of the specific parameter in blockParamArr */

/* Index into rtwCAPI_DataTypeMap */
uint16_T paramDataTypeInd = blockParamArr[paramIdx].dataTypeIndex;

/* Index into rtwCAPI_DimensionMap */
uint16_T paramDimMapInd = blockParamArr[paramIdx].dimIndex;

/* Index into rtwCAPI_FixPtMap, holding fixed-point parameter information */
uint16_T paramFxpInd = blockParamArr[paramIdx].fxpIndex;

/* Index into the (primitive type) address map 
   that holds the real-time value of the parameter */
uint_T paramAddMapInd = blockParamArr[paramIdx].addrMapIndex;
 
# include "rtw_capi.h"

/* blockParamArr is the pointer to the block parameter array */
/* paramIdx is the index of the specific parameter in blockParamArr */

/* Index into rtwCAPI_DataTypeMap */
uint16_T paramDataTypeInd = rtwCAPI_GetBlockParameterDataTypeIdx(blockParamArr,paramIdx);

/* Index into rtwCAPI_DimensionMap */
uint16_T paramDimMapInd = rtwCAPI_GetBlockParameterDimensionIdx(blockParamArr,paramIdx);

/* Index into rtwCAPI_FixPtMap, holding fixed-point parameter information */
uint16_T paramFxpInd = rtwCAPI_GetBlockParameterFixPtIdx(blockParamArr,paramIdx);

/* Index into the (primitive type) address map 
   that holds the real-time value of the parameter */
uint_T paramAddMapInd;
myParamAddMapInd = rtwCAPI_GetBlockParameterAddrIdx(blockParamArr,paramIdx);

C Code for Accessing Block States C API Information

Required Item / InformationCode for Direct Data Structure AccessCode for Access Through Get-Function-Like Macros
Block states 
# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that capiStaticMap already defined and instantiated */

uint_T stateCount = (capiStaticMap->States).numStates;
const rtwCAPI_States stateArr* statArr;
statArr = (capiStaticMap->States).states;
 
# include "rtw_modelmap.h"
# include "rtw_capi.h"

/* Assuming that mainCapiMap already defined and instantiated */

uint_T stateCount = rtwCAPI_GetNumStates(mainCapiMap);
const rtwCAPI_States stateArr* statArr;
statArr = rtwCAPI_GetStates(mainCapiMap);
Direct information about specific states 
# include "rtw_capi.h"

/* stateArr is the pointer to the block state array */
/* stateIdx is the index of the specific state in stateArr */

const char_T* stateName = stateArr[stateIdx].stateName;

/* Path of alias block */
const char_T* stateAliasBlockPath;
stateAliasBlockPath = stateArr[stateIdx].pathAlias;

/* Path of owner block */
const char_T* stateBlockPath;
stateBlockPath = stateArr[stateIdx].blockPath;

uint8_T isContinuous = stateArr[stateIdx].isContinuous;

/* (-1) if there is no hierarchy */
int_T stateHierIdx = stateArr[stateIdx].hierInfoIdx;

/* Flat element index in hierarchy */
uint_T stateFlatHierIdx = stateArr[stateIdx].flatElemIdx;

/* Starting index in model continuous state and state 
   derivative vectors, or (-1) for discrete states */
int_T stateContStartIdx;
stateContStartIdx = stateArr[stateIdx].contStateStartIndex;
 
# include "rtw_capi.h"

/* stateArr is the pointer to the block state array */
/* stateIdx is the index of the specific state in stateArr */

const char_T* stateName = rtwCAPI_GetStateName(stateArr,stateIdx);

/* Path of alias block */
const char_T* stateAliasBlockPath;
stateAliasBlockPath = rtwCAPI_GetStateName(stateArr,stateIdx);

/* Path of owner block */
const char_T* stateBlockPath;
stateBlockPath = rtwCAPI_GetStateBlockPath(stateArr,stateIdx);

uint8_T isContinuous = rtwCAPI_IsAContinuousState(stateArr,stateIdx);

/* (-1) if there is no hierarchy */
int_T stateHierIdx = rtwCAPI_GetStateHierInfoIdx(stateArr,stateIdx);

/* Flat element index in hierarchy */
uint_T stateFlatHierIdx = rtwCAPI_GetStateFlatElemIdx(stateArr,stateIdx);

/* Starting index in model continuous state and state 
   derivative vectors, or (-1) for discrete states */
int_T stateContStartIdx;
stateContStartIdx = rtwCAPI_GetContStateStartIndex(stateArr,stateIdx);
Indirect information about specific states, provided as indices that reference entries in property-specific arrays. For more information about property-specific C API arrays, see Access Property-Specific C API Arrays. 
# include "rtw_capi.h"

/* stateArr is the pointer to the block state array */
/* stateIdx is the index of the specific state in stateArr */

/* Index into the Block DWork, 0 for continuous states  */
uint16_T dWorkIndex = stateArr[stateIdx].dWorkIndex;

/* Index into rtwCAPI_DataTypeMap */
uint16_T stateDataTypeInd = stateArr[stateIdx].dataTypeIndex;

/* Index into rtwCAPI_DimensionMap */
uint16_T stateDimMapInd = stateArr[stateIdx].dimIndex;

/* Index into rtwCAPI_FixPtMap, holding fixed-point state information */
uint16_T stateFxpInd = stateArr[stateIdx].fxpIndex;

/* Index into rtwCAPI_SampleTimeMap, which provides Task infomation */
uint8_T stateSampTimeInd = stateArr[stateIdx].sTimeIndex;

/* Index into the (primitive type) address map 
   that holds the real-time value of the state */
uint_T stateAddMapInd = stateArr[stateIdx].addrMapIndex;

# include "rtw_capi.h"

/* stateArr is the pointer to the block state array */
/* stateIdx is the index of the specific state in stateArr */

/* Index into the Block DWork, 0 for continuous states  */
uint16_T dWorkIndex = rtwCAPI_GetStateDWorkIdx(stateArr,stateIdx);

/* Index into rtwCAPI_DataTypeMap */
uint16_T stateDataTypeInd = rtwCAPI_GetStateDataTypeIdx(stateArr,stateIdx);

/* Index into rtwCAPI_DimensionMap */
uint16_T stateDimMapInd = rtwCAPI_GetStateDimensionIdx(stateArr,stateIdx);

/* Index into rtwCAPI_FixPtMap, holding fixed-point state information */
uint16_T stateFxpInd = rtwCAPI_GetStateFixPtIndex(stateArr,stateIdx);

/* Index into rtwCAPI_SampleTimeMap, which provides Task infomation */
uint8_T stateSampTimeInd = rtwCAPI_GetStateSampleTimeIdx(stateArr,stateIdx);

/* Index into the (primitive type) address map 
   that holds the real-time value of the state */
uint_T stateAddMapInd = rtwCAPI_GetStateAddrIdx(stateArr,stateIdx);

Related Topics