Documentation Home Page RT-LAB Home Page
Pour la documentation en FRANÇAIS, utilisez l'outil de traduction de votre navigateur Chrome, Edge ou Safari. Voir un exemple.

C-API Reference v11x and up Functions Reference


The following functions are available to a user in order to interface their application to RT-LAB.

Library & Header, Throughout

OpalAbortCompile

GroupModel preparation
DescriptionStops the currently executing compilation.
Required ControlSystem control
Usageint OpalAbortCompile();
InputNone
OutputNone
Return value
  • EOK: Success.
  • EPRM: System control was not granted to this client.
  • EIO: Error sending the request or receiving the reply.
ExamplesNone
Related items

OpalStartCompile2, OpalDisplayInformation

OpalAddExtraFile

Group

Model Preparation

Description

This function adds a file to the list of files to be transferred or retrieved during one of the following steps:

  • transfer of files during compilation from the host to the target.

  • retrieval of files during compilation from the target to the host

  • transfer of files from the host to the target before the model is loaded

  • retrieval of files from the target to the host after the model is reset

Required Control

Configuration control

Usage

int OpalAddExtraFile (OP_EXTRA_FILE_TRANSFER_TIME transferTime, unsigned short logicalId,char *filePathName,OP_FILE_TRANSFER_MODE fileMode);

Input
  • transferTime: See OP_EXTRA_FILE_TRANSFER_TIME.
  • logicalID: See Glossary. To specify all subsystem, set the logicalId to 0.file
  • PathName: Extra file path and name.
  • fileMode: File transfer type (ascii or binary). See OP_FILE_TRANSFER_MODE.
Output

None

Return value
  • EOK: Success.
  • EFAULT: Invalid parameter.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ESRCH: Specified subsystem id not found.
Examples

See example configuration.

Related items

OpalGetExtraFiles, OpalRemoveExtraFile, OP_EXTRA_FILE_TRANSFER_TIME, OP_FILE_TRANSFER_MODE

OpalAddToSelection

GroupUtilities
DescriptionGiven the object's reference ID, adds it to the selected items.
Required ControlNone
Usage

int OpalAddToSelection(P_REF_ID *refId);

Input
  • *refId: Pointer to the reference ID (type UINT_64_T).
OutputNone
Return value
  • EOK: Success.
ExamplesNone
Related itemsNone

OpalCloseMetaController

GroupUtilities
Description

Close the currently running MetaController. This function should be called only once all projects have been closed and all clients have disconnected from running simulations.

After invoking this function, most API calls will not be operational until the MetaController executable is started again.

Required ControlNone
Usage

int OpalCloseMetaController();

InputNone
OutputNone
Return value
  • EOK: Success.
ExamplesNone
Related itemsNone


OpalCloseProject 

GroupModel Selection
DescriptionDisconnects the API from the currently connected project and model. The model's state does not change as a result of this call. Any control granted to this client is revoked.
Required ControlNone
Usagevoid OpalCloseProject(void);
InputNone
OutputNone
Return valueNone
ExamplesSee example basic_example1.
Related items

OpalGetActiveProjects, OpalConnect (deprecated), OpalConnectByName (deprecated), OpalSetCurrentModel, OpalOpenProject

OpalCommand

GroupGeneric
DescriptionRun an RT-LAB command for a certain RT-Lab object.
See the OP_COMMAND enumeration for a complete list of available commands and their specific requirements.
Required ControlSpecific to each command, see OP_COMMAND.
Usageint OpalCommand (OP_REF_ID ownerId, OP_COMMAND command, int numAttributesIn,OP_ATTRIBUTE attributes[], void * attributeValues[], OP_REF_ID * outputId)
Input
  • ownerId: The ID of the object that owns the command. Where there is ambiguity, the owner of the two objects is the expected ID. For example CMD_REMOVE: when the owner is a project, the command removes a model.
  • command: The command to be executed
  • numAttributes: The number of attributes to send as arguments for the command.
  • attributes: The array of attributes to send to the command. The size of the array must be equal to the numAttributes argument. May be NULL is numAttributes is 0.
  • attributeValues: The pointer to the array of values to be used as arguments for the command. The type of each value must correspond to the attribute of the same index in attributes. The size of the array must be equal to the numAttributes argument. May be NULL is numAttributes is 0.
OutputoutputId    The ID corresponding to the object directly affected by the command. If no other object than the parent is affected, the parent ID is returned.
Return value
  • EOK: Success.
  • EBADF: Unsupported ownerId.
  • EINVAL: Invalid arguments specified.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Error allocation memory for request or reply.
ExamplesNone.
Related items

OP_COMMAND, OP_ATTRIBUTE.

OpalConnect (deprecated)

GroupModel selection
DescriptionConnects the API to an active model. Subsequent API calls refer to this model.
Required ControlNone
Usageint OpalConnect(OP_API_INSTANCE_ID instId,unsigned short systemControl, short *modelState);
Input
  • instId: The id of the model instance to which the connection is to be made.
  • systemControl: True to request control of the model.
Output
  • modelState: Current state of the model. See OP_MODEL_STATE.
Return value
  • EOK: Success.
  • EIO: Error sending the request or receiving the reply.
  • ESRCH: Invalid instance id or instance id not found.
  • EPERM: Control requested, but already given to another client.
  • ENOEXEC: Could not connect to model. Not all of the subsystems are still active.
  • EINVAL: Trying to connect to a model whose local and UNC path are both empty.
  • ENOENT: Could not find the original model we are trying to connect to.
  • OP_API_EBAD_CONFIG: Node mapping not valid or IP address of controller machine not specified (environment variable OPAL_META_CTL_IP not set).
  • OP_API_EBAD_PHYS_NODE: Physical node not found.
  • OP_API_EMODEL_CHANGED: The original model has been changed (number of sub-systems, sub-systems names, etc.
  • OP_API_ENO_LICENSE: No license.
  • OP_API_ENO_PRODUCT: No license for RT-LAB and RT-LABx.
  • OP_API_MODEL_IO_ TIMEOUT
  • OP_API_MODEL_IO_ERROR: Model is missing some or all processes or subsystems.
ExamplesNone
Related items

OpalConnectByName (deprecated), OpalDisconnect (deprecated), OpalOpenProject, OpalCloseProject, OpalGetModelState

OpalConnectByName (deprecated)

GroupModel Selection
Description
Connects the API to an active model. Subsequent API calls refer to this model.
When trying to establish a connection with a model when there are multiple models that correspond to the specified ModelName and ModelPath, a window is displayed prompting you to choose a model. This may occur when:
  • modelName is not NULL. The window displays a list of active models with the specified ModelName and ModelPath, unless ReturnOnAmbiguity is set to True1.



  • modelName is not NULL, there is more than one active model with a specified path and name and returnOnAmbiguity is False(0).

exactMatch exactMatch modelName returnOnAmbiguity E2BIG
Required ControlNone
Usageint OpalConnectByName (const char *modelName,const char *modelPath, unsigned short exactMatch, unsigned short systemControl,unsigned short returnOnAmbiguity, OP_API_INSTANCE_ID *pInstId, OP_MODEL_STATE*pModelState);
Input
  • modelName: name of the model to which connection is desired
  • modelPath: Path where original model resides. May be NULL; used to resolve ambiguity when more than one model of the same name are active.
  • exactMatch: True(1) to request an exact name match.
  • systemControl: True(1) to request control of the model.
  • returnOnAmbiguity: No window is displayed, an error code (E2BIG) isreturned.
Output
  • instId: Current active model’s instance ID. See Glossary.
  • modelState: Current model's state.
Return value
  • EOK: Success.
  • EIO: Error sending the request or receiving the reply.
  • ENOENT: No active model found.
  • OP_API_CMD_CANCELED: Active model(s) found but no model has been selected.
  • ENOSPC: No active model with specified name, path and type.
  • E2BIG: More than 1 active models with specified name and path (only if returnOnAmbiguity is TRUE).
  • EPERM: Control requested, but already given to another client.
  • ENOEXEC: Could not connect to model. Not all of the subsystems are still active.
  • ENOMEM: Internal memory allocation error.
  • OP_API_EBAD_CONFIG: Node mapping not valid or IP address of controllermachine not specified (environment variable OPAL_META_CTL_IP not set).
  • OP_API_EBAD_PHYS_NODE: Physical node not found.
  • OP_API_ECREATE_SHMEM: Could not create shared memory.
  • OP_API_ECREATE_PROCESS: Error launching OpalChooseModel.exe - Error displayingthe dialog box. Process OpalChooseModel.exe is called by this function. This process is placed RTLAB_ROOT\common\bin folder.
  • OP_API_ENO_LICENSE: No license for one or more of RT-LAB components.
  • OP_API_ENO_PRODUCT: No license for RT-LAB and RT-LABx.
  • OP_API_MODEL_IO_ TIMEOUT
  • OP_API_MODEL_IO_ERROR: Model is missing some or all processes or subsystems.
ExamplesSee the example basic_example1.
Related items

OpalSetCurrentModel, OpalGetActiveProjects, OpalConnect (deprecated), OpalDisconnect (deprecated), OpalOpenProject, OpalCloseProject, OpalGetModelState

OpalCreateAlias

GroupModel Interaction, Alias
Description

Creates a new alias which is used as a reference to an absolute path of a parameter or signal.

The alias is appended to the current list of aliases. The alias’s name is a no case-sensitive string that should be unique. It should not contains the following special character: an asterisk (*) and question mark (?).

It consists of partitions and a name, or a name only. A partition is an organizational unit, or container, used to organize aliases into a hierarchical structure. Partitions and name of the alias are separated by slash (/) characters. The topmost partition in any partition is called the root partition. A partition that is below another partition is called a subpartition. A partition above a subpartition is called the parent partition. The root partition is a slash (/) characters.

Below are examples of valid alias names:

  • myAliasName
  • /myPartition/myAliasName
  • /myRootPartition/myChildrenPartition/myAliasName


When using alias’ API functions, many syntaxes is available to refer to one specific alias. For example, an alias called “/myPartition/myAlias” can be referenced with the following syntax:
  • /myPartition/myAlias,
  • myPartition/myAlias or
  • myAlias (required a unique name)
Note that the last syntax is only available if no other partitions contain an alias with the name “myAlias”.With Matlab/Simulink, the absolute path of a parameter is the concatenation of the path of the block that contains the parameter and the name of the parameter. Below are examples of parameter’s paths of a SineWave block:
  • Subsystem/SineWave/Amplitude
  • Subsystem/SineWave/Frequency
By analogy, with Matlab/Simulink, the absolute path of a signal is the concatenation of the path of the block that outputs the signal and the signal’s label. If the label is empty in the Simulink model, the port’s name that outputs the signal is used instead of the label. Below are examples of paths for a signal at the outport 1 of a SineWave block:
  • Subsystem/SineWave/Amplitude
  • Subsystem/SineWave/Frequency
By analogy, with Matlab/Simulink, the absolute path of a signal is the concatenation of the path of the block that outputs the signal and the signal’s label. If the label is empty in the Simulink model, the port’s name that outputs the signal is used instead of the label. Below are examples of paths for a signal at the outport 1 of a SineWave block:
  • SubSystem/SineWave/MySignalLabel, or

  • SubSystem/SineWave/Port1
Note that any of the following kind of signals can be referenced: control signals, acquisition signals, and dynamic signals.
Required ControlSystem control
Usageint OpalCreateAlias(const char * aliasName,const char * referencePath);
Input
  • aliasName: Name of the alias. It must be unique.
  • referencePath: Absolute path of the parameter or signal referenced by the alias. This path must exist in the model.
OutputNone
Return value
  • EOK: Success.
  • EPERM: System control has not been granted to this client.
  • EINVAL: The reference path of the parameter or signal is not found in the model.
  • EACCES: The alias already exists.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
Examples
Related items

OpalRemoveAlias, OpalLoadAlias, OpalSaveAlias, OpalGetValueByAlias, OpalSetValueByAlias.

OpalCreatePackage

GroupUtilities
Description

Creates a package (zip) ready to be deployed on a target for executing the current model using API.

The project must be first open (cf. OpalOpenProject) and loadable before calling this function.

Required ControlSystem control (OP_FB_SYSTEM)
Usage

int OpalCreatePackage(const char *packageName, const OP_TARGET_PLATFORM targetPlatform);

Input
  • packageName: Absolute file path of the package to be created
  • targetPlatform: See OP_TARGET_PLATFORM.
OutputNone
Return value
  • EOK: Success.
  • OP_API_INVALID_PARAMETER: Missing packageName
  • OP_API_OUT_OF_MEMORY: Not enough memory
  • OP_API_BAD_PATH: Invalid packageName
  • OP_API_NOT_ENOUGH_PRIVILEGE: System Control not granted
  • OP_API_INVALID_TARGET_PLATFORM: Target platform not supported
  • OP_API_ENO_MODEL_NOT_LOADABLE: Missing model compilation
ExamplesNone
Related items

OpalOpenProject, OP_TARGET_PLATFORM

OpalDeleteConnHandle

GroupModel selection
DescriptionThe specified handle must have been obtained from OpalGetConnHandle or OpalNewConnHandle. The specified connection is deleted. If connected, it is disconnected before deleting.
Required ControlNone
Usageint OpalDeleteConnHandle(unsigned long handle);
Inputhandle of a connection
OutputNone
Return value
  • EOK: success
  • ENOMEM: memory allocation error
  • E2BIG: too many open connections for this process
ExamplesSee multi_models
Related items

OpalNewConnHandle, OpalGetConnHandle, OpalSetConnHandle

OpalDisconnect (deprecated)

GroupModel Selection
DescriptionDisconnects the API from the currently connected model. The model's state does not change as a result of this call. Any control granted to this client is revoked.
Required ControlNone
Usagevoid OpalDisconnect(void);
InputNone
OutputNone
Return valueNone
ExamplesSee example basic_example1.
Related items

OpalGetActiveProjects, OpalConnect (deprecated), OpalConnectByName (deprecated), OpalSetCurrentModel, OpalOpenProject, OpalCloseProject

OpalDisplayInformation

GroupUtilities
DescriptionGets the compilation or execution messages as well as return the compilation or execution status. You must call OpalRegisterDisplay before calling this function to indicate to the controller to send messages to the client.
Required ControlNone
Usageint OpalDisplayInformation(char *results,unsigned short bufLen, int timeout,unsigned short *done, unsigned short *displayId);
Input
  • bufLen: Available buffer size in bytes (provided by the caller). Minimum recommended size is 512 bytes.
  • timeout: Milliseconds to wait for available results. 0 = do not wait.OP_API_INFINITE = block for available results.
Output
  • done: Status of the compilation or the execution. Return True if the compilation has completed or execution has been reset.
  • displayId: Message’s source
    • 0: compilation
    • 1: Master subsystem
    • 2+: Slave subsystems
  • results: Buffer supplied by the caller where the API stores the available messages. Can be NULL if results are not desired. Compilation or execution messages are a C string (terminated by a '\0').
Return value
  • EOK: Success.
  • EAGAIN: No more information to display.
  • OP_API_ESEPARATION: Error while separating the model's subsystems.
  • OP_API_ECODE_GENERATION: Error while generating code for the subsystems.
  • EPERM: System control had not been granted to this client.
  • EBUSY: Model executables already loaded.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • OP_API_ENO_PRODUCT: No license for RT-LAB and RT-LABx.
ExamplesSee example compilation.
Related itemsOpalRegisterDisplay

OpalExecute

GroupModel Execution
DescriptionStarts execution of the currently connected model. When in real-time mode, the execution rate is the model's sampling rate times the time factor.
Required ControlSystem Control
Usageint OpalExecute(double timeFactor);
Input
  • timeFactor: See Glossary
OutputNone
Return value
  • EOK: Success.
  • EPERM: System control had not been granted to this client.
  • EINVAL: Model not loaded.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • OP_API_MODEL_IO_TIMEO UT
  • OP_API_MODEL_IO_ERROR: Model is missing some or all processes or subsystems.
ExamplesSee example basic_example1.
Related items

OpalPause, OpalGetSystemControl

OpalExecuteConsole

GroupModel Interaction, Console
Description

Starts execution of the Simulink console subsystem associated with the current connected model. Before calling this function, the client must call OpalLoadConsole.


Please note that this function is only available on Windows and Linux operating system when the model contains a Simulink console subsystem. The client machine must have Matlab install.

Required ControlNone
Usageint OpalExecuteConsole();
InputNone
OutputNone
Return value
  • EOK: success
  • EBADF: model not specified by previous OpalConnect or OpalSetCurrentMode
  • EINVAL: not a Simulink model
  • EIO: error sending the request or receiving the reply
  • ENOENT: the model path and/or name is NULL
  • EACCES: cannot access the modelname.subsys file (this file is generated during the model’s compilation)
  • OP_API_SEPARATION: the model doesn’t contain a Simulink console subsystem or the format of the *.subsys file is incorrect (this file is generated during the model’s compilation).
ExamplesNone
Related items

OpalLoadConsole, OpalPauseConsole, OpalResetConsole, OpalStopConsole

OpalExecuteMatlabCmd

GroupUtilities
DescriptionSends a command to Matlab and returns Matlab's messages. If Matlab has not been started yet, the function starts Matlab before sending the command.
Required ControlNone
Usageint OpalExecuteMatlabCmd (char *cmd,char *result,unsigned short resultBufferLen);
Input
  • cmd: Matlab command to be executed.
  • resultBufferLen: Size (in chars) of the pResult buffer parameter.
Output
  • result: Messages returned by Matlab. You must create this array.
Return value
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EINVAL: Model is of a type for which this operation is not supported.
  • EFAULT: Invalid parameter.
ExamplesSee example matlab_analysis.
Related items
None

OpalFindObjectId

GroupUtilities
DescriptionGiven the object's path and type, returns the Object ID.
Required ControlNone
Usage

int OpalFindObjectId(OP_OBJECT_TYPE objectType, const char *path, OP_REF_ID *refId);

Input
  • objectType: Object type (enum → OP_T).
  • *path: Pointer to the path.
  • *refId: Pointer to the reference ID (type UINT_64_T).
OutputNone
Return value
  • EOK: Success.
ExamplesNone
Related itemsNone

OpalFreeMemory

GroupUtilities
DescriptionFree memory allocated by a previous API call.
Required Control
Usageint OpalFreeMemory(void *pMemory);
Input
  • pMemory: Pointer to memory to be freed.
OutputNone
Return value
  • EINVAL: Invalid parameter.
ExamplesNone
Related itemsNone

OpalGetAcqBlockLastVal

GroupModel Configuration, Acquisition
DescriptionGet the current settings for the blocking / non-blocking, and associated last value flag, for signal acquisition. This information is used by the API acquisition functions, which have the option not to wait for data, needed by some console's lack of multiple thread support.
These settings apply to the current model. These settings only apply to the command station from which this call is made.
Required ControlNone
Usageint OpalGetAcqBlockLastVal(short *blockOnGroupshort *lastValues);
InputNone
Output
  • blockOnGroup: Acquisition group for which the API functions will wait for data (specify n for group n).If 0, API function will wait for data for all groups.If -1, API functions will not wait for any group's data.
  • lastValues: Boolean, 1 means API functions will output the last values received while a group's data is not available. If 0, the API function will output zeroes. This paramater is ignored when blockOnGroup is not egal to -1
Return value
  • EOK: success
  • ENOMEM: memory allocation error
  • EBADF: model not specified by previous OpalConnect
  • EIO: error sending the request or receiving the reply from Controller
ExamplesNone
Related items

OpalSetAcqBlockLastVal

OpalGetAcqGroupSignals

GroupModel Interaction, Signal Acquisition
Description

Returns the acquisition signals sent to the console subsystem while the model is running. The acquisition signals are the signals sent from the computation nodes to console subsystem in the same order that it was specified at the input of the OpComm block for the specified acquisition group.


Observes the blocking / non-blocking properties set for the workstation: if blocking is set, will block until data is available; if non-blocking is set, will return EAGAIN when no data is available. In this case, returned values will be equal to zero or last received values depending on the settings specified by the OpalSetAcqBlockLastVal API function.
For additional information, please see Acquiring and Viewing Data in the RT-LAB User’s Guide.

Required ControlNone
Usageint OpalGetAcqGroupSignals(unsigned short acqGroup,unsigned short allocatedSignals, unsigned int *numSignals, double values[],unsigned short *lastValues, double *timestep);
Input
  • acqGroup: Acquisition group number, starts from 0.
  • allocatedSignals: Number of expected signals.
Output
  • numSignals: number of signals in values signals array
  • values: Simulation signals array into which the API will store the acquired signals. May be NULL if allocatedSignals equals 0.
  • lastValues: Pointer to where API stores true when signals are the last in the acquisition buffer (next values will be in a new frame). May be NULL if not of interest.
  • timestep: Simulation timestep of the acquired data. May be NULL if not of interest.
Return value
  • EOK: Success.
  • E2BIG: Number of allocated signals is less than the number of group signals.
  • EAGAIN: No data available and the timeout has expired.
  • EINVAL: Specified acquisition group is invalid or not active (does not exist on target).
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EACCES: Not connected a loaded model.
  • ENOMEM: Memory allocation error.
  • OP_API_EBAD_SIGNAL: Doing acquisition of one or more dynamic signals that does no longer exist.
  • OP_API_ENO_PRODUCT: No license for RT-LAB and RT-LABx.
  • OP_API_EACQ_MODEL_PAUSED: no data available because the model is paused.
ExamplesNone
Related itemsNone

OpalGetAcqGroupSyncSignals

GroupModel Interaction, Signal Acquisition
Description

Returns the acquisition signals sent to the console subsystem while the model is running. The acquisition signals are the signals sent from the computation nodes to console subsystem in the same order that it was specified at the input of the OpComm block for the specified acquisition group. The outputs contain two arrays: acquisition signals + monitoring signals.


The user can activate the synchronization algorithm to synchronize the acquisition time with the simulation time by inserting data during missed data intervals. The interpolation can be used in this case to get a better result during missed data intervals.

Threshold time between acquisition time and simulation time exceeds the threshold, the acquisition (console) will be updated to overtake the difference. The acqtimestep offers the user a way to change his console step size as in Simulink.
For additional information, please see Acquiring and Viewing Data in the RT-LAB User’s Guide.
Monitoring signals array contains 4 values:

  1. missed data: number of values between two acquisition frame. If the value is 0, there are no missing data between the two frames. Missing data may appear if network communication and display are too slow to refresh the value generated by the model.
  2. offset: simulation time when the acquisition started.

  1. target simulation time: simulation time of the model when the acquisition has been done.
    1. Sample/sec: number of sample/sec received from target. The calculation is made for one sample. Ex: If the model is running at 0.001s, sample/sec value should not exceed 1000 sample/sec.
Required ControlNone
Usageint OpalGetAcqGroupSyncSignals(unsigned short acqGroup,unsigned short allocatedSignals, unsigned int *numSignals, unsigned short synchronization, unsigned short interpolation, double threshold,double acqTimeStep, double *simSignals, double *monSignals,unsigned short *endFrame, double *simTimeStep);
Input
  • acqGroup: Acquisition group number starts from 0.
  • allocatedSignals: Number of expected signals.
  • synchronization: 1/0 = Enable/DisableEnables the synchronization algorithm for a given acquisition group. This algorithm must be used if synchronization is required between acquisition Console time and simulation time. In case of a synchronization problem, the Console detects missing data from the target node and the algorithm either replaces the lost data with the last signal value received or interpolates the data.
  • interpolation: interpolation 1/0 = Enable/Disable
    In case of missed data from a computation subsystem, the synchronization algorithm interpolates data during a range of data loss. The following illustrations make this point clear. The display at left indicates no interpolation during data acquisition while the display at right indicates interpolation between two frames during data loss.
  • Interpolation in data acquisition
  • threshold: Difference between the simulation Console time and the simulation target time. Whenever this difference is exceeded, the synchronization algorithm stops interpolating and re-synchronizes to the new value.
  • acqTimeStep: Sample interval: acquisition (console) timestep must be equal to or greater than the model time step.
Output
  • numSignals: Number of signals in the acquisition group.
  • simSignals: Simulation signals array into which the API will store the acquired signals. May be NULL if allocatedSignals equals 0.
  • monSignals:  Monitoring signals array into which the API will store the monitoring signals (Missed data, offset, target simulation time, Samples/sec). May be NULL if allocatedSignals equals 0.
  • endFrame: Pointer to where API stores true when signals are the last in the acquisition buffer (next values will be in a new frame). May be NULL if not of interest.
  • simTimeStep: Simulation timestep of the acquired data. May be NULL if not of interest.
Return value
  • EOK: Success.
  • E2BIG: Number of allocated signals is less than the number of group signals.
  • EAGAIN: No data available and the timeout has expired.
  • EINVAL: Specified acquisition group is invalid or not active (does not exist on target).
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EACCES: Not connected a loaded model.
  • ENOMEM: Memory allocation error.
  • OP_API_EBAD_SIGNAL: Doing acquisition of one or more dynamic signals that does no longer exist.
  • OP_API_ENO_PRODUCT: No license for RT-LAB and RT-LABx.
ExamplesSee example acquisition1.
Related itemsNone

OpalGetAcqSampleTime

GroupModel Configuration, Acquisition
DescriptionGet the acquisition sample time for the specified group. The acquisition sample time is the interval between two values inside an acquisition frame.
Required ControlNone
Usageint OpalGetAcqSample Time(unsigned short acqGoup,double *sampleTime);
Input
  • acqGroup: acquisition group starting at 1.
Output
  • sampleTime: acquisition group sample time
Return value
  • EOK: Success.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
ExamplesNone
Related itemsNone

OpalGetAcqTrigger

GroupModel Configuration, Acquisition
DescriptionGet the dynamic acquisition trigger that will be used during the simulation. Data will be acquired only when a specific signal is triggered.
Required ControlNone
Usageint OpalGetAcqTrigger( unsigned short acqGroup,unsigned int *signalNameLength, const char *signalName,double *level,unsigned int *trigSignalNameLength, const char *trigSignalName,int *offset,OP_TRIGGER_CONDITION *condition, unsigned char *triggerEnabled, unsigned short *trigType);
Input
  • acqGroup: Acquisition group (numbering starts at 0).
Output
  • signalNameLength: Length of the signal to be triggered.
  • signalName: Name of the triggered signal.
  • level: Value that must be reached by the trigger signal to trigger acquisition.
  • trigSignalName: Name of the triggering signal. If “level” is specified thentrigSignalName is NULL.
  • offset: Number of steps (cycles) to wait before starting the acquisition system.
  • condition: Condition to be satisfied so that the acquisition system is triggered.
  • See OP_TRIGGER_CONDITION.
  • triggerEnabled: Specified if the dynamic trigger is enabled or disabled (1/0 =Enable/Disable).
  • triggerType: Type of trigger that will start the acquisitionTRIG_BY_SIGNAL(0) / TRIG_BY_VALUE(1).
Return value
  • EOK: Success.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EINVAL: invalid acquisition group.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Memory allocation error.
  • E2BIG: Too many open connections for this process.
ExamplesNone
Related itemsOpalSetAcqTrigger

OpalGetAcquisitionControl

GroupModel Configuration, Acquisition
DescriptionRequests or releases the acquisition control of the currently connected model. Acquisition control enables the client API to control the model's acquisition parameters for a specific acquisition group. Only one client API at a time is granted acquisition control for a specific acquisition group.
Required ControlNone
Usageint OpalGetAcquisitionControl(unsigned short acqControl,unsigned short acqGroup);
Input
  • acqControl                    
  • True(1): to request acquisition control for the specified acquisition group,
  • False(0): to release its control.
  • acqGroup: Group for which acquisition control is requested (numbering starts at 0).
OutputNone
Return value
  • EOK: Success.
  • EPERM: Control requested but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EINVAL: Invalid acquisition group.
ExamplesSee example dynamic_acq.
Related items
None

OpalGetActiveModels (deprecated)

GroupModel Selection
Description

Note: This function is for backward compatibility only. Please consider using OpalGetActiveProjects instead. 

Returns a list of active models (see Glossary). The returned names include the file extension (if any) of the original model file.
If the allocated storage is too small for the number of models, or for the longest name or longest path, none of the names, paths or instance Ids are returned, but the numModels, maxNameLen and maxPathLen values are set, and the return value is E2BIG. An application can use this fact to specify lengths of 0 on a first call, allocate the required storage and issue a second call to get the information.

Required ControlNone
Usageint OpalGetActiveModels(unsigned sFindObjectIdhort allocatedModels,unsigned short *numModels, unsigned short allocatedNameLen, unsigned short *maxNameLen, unsigned short allocatedPathLen, unsigned short *maxPathLen, char *name[],char *path[], OP_API_INSTANCE_ID instId[]);
Input
  • allocatedModels: number of models for which storage was allocated by the caller for the names, paths and instance ids.
  • allocatedNameLen: allocated length of storage to receive the names
  • allocatedPathLen: allocated length of storage to receive the paths
Output
  • numModels: pointer to where the API will store the actual number of active models.
  • maxNameLen: pointer to where the API will store the length of the longest name.
  • maxPathLen: pointer to where the API will store the length of the longest path.
  • name: array of strings where the API will store the names of the active models (includes the extension).
  • path: array of strings where the API will store the paths of the active models.
  • instId: array where the API will store the instance Ids of the active models.
Return value
  • EOK: Success.
  • EIO: Error sending the request or receiving the reply.
  • E2BIG: specified storage not big enough to receive values
  • ENOMEM: Internal memory allocation error.
  • OP_API_EBAD_CONFIG: Node mapping not valid or IP address of the controller machine not specified (environment variable OPAL_META_CTL_IP not set).
ExamplesNone
Related items

OpalGetActiveProjects, OpalDisconnect, OpalSetCurrentModel, OpalConnectByName

OpalGetActiveProjects

GroupModel Selection
Description

Returns a list of active projects. For each project, this function returns the full path of the configuration file, the name and the IP address of the machine that opened this project, the instance ID of the current project session, and the list of models belonging to this project. For each model, path, ID and state are returned.


If the allocated storage is too small for any of the arguments, none of the lists are returned, but the numProjects, numModels, maxProjectPathLen, maxModelPathLen, maxMachineNameLen and maxIpLen values are set, and the return value is E2BIG. An application can use this fact to specify lengths of 0 on a first call, allocate the required storage and issue a second call to get the information.

Required ControlNone
Usageint OpalGetActiveProjects(unsigned short allocatedProjects,unsigned short *numProjects, unsigned short allocatedModels, unsigned short *numModels,unsigned short allocatedProjectsPathLen, unsigned short *maxProjectPathLen, unsigned short allocatedModelPathLen, unsigned short *maxModelPathLen, unsigned short allocatedMachineNameLen, unsigned short *maxMachineNameLen, unsigned short allocatedIpLen,unsigned short *maxIpLen, char *projectPaths[], unsigned short instanceIDs[], char *machineNames[],char *controllerIPs[], char *modelPaths[],unsigned short numModelsPerProject[] unsigned short modelIDs[],unsigned short modelStates[]);
Input
  • allocatedProjects: number of projects for which storage was allocated by the caller for the paths, machine name, IP addresses and instance ids.
  • allocatedModels: number of models for which storage was allocated by the caller for the names, paths and instance ids.
  • allocatedProjectPathLen: allocated length of storage to receive the project paths
  • allocatedModelPathLen: allocated length of storage to receive the model paths
  • allocatedMachineNameLen: allocated length of storage to receive the machine names
  • allocatedIpLen: allocated length of storage to receive the IP addresses
Output
  • numProjects pointer to where the API will store the actual number of active projects.
  • numModels pointer to where the API will store the actual total number of models for all active projects.
  • maxProjectPathLen pointer to where the API will store the length of the longest project path.
  • maxModelPathLen pointer to where the API will store the length of the longest model path.
  • maxMachineNameLen pointer to where the API will store the length of the longest machine name.
  • maxIpLen pointer to where the API will store the length of the longest IP address.
  • projectPaths array of strings where the API will store the paths of the active projects’ configuration files.
  • instanceIDs array where the API will store the instance Ids of the active projects.
  • machineNames array where the API will store the machine names.
  • controllerIPs array where the API will store the IP addresses.
  • modelPaths array where the API will store the model paths of all active projects.
  • numModelsPerProject array where the API will store the number of models for each project. Use these values to determine what model belongs to what project.
  • modelIDs array where the API will store the model IDs for all active projects.
  • modelStates array where the API will store the model states for all active projects.
Return value
  • EOK: Success.
  • EIO: Error sending the request or receiving the reply.
  • E2BIG: specified storage not big enough to receive values
  • ENOMEM: Internal memory allocation error.
  • OP_API_EBAD_CONFIG: Node mapping not valid or IP address of the controller machine not specified (environment variable OPAL_META_CTL_IP not set).
ExamplesNone
Related items

OP_COMMAND(OpenProject),OP_COMMAND (CloseProject), OpalDisconnect, OpalSetCurrentModel, OpalConnectByName

OpalGetAliasDescription

GroupModel Interaction, Alias
DescriptionReturns the set of information of aliases active for the current model.
Specifying a pattern ensures that only matching alias information is returned. Wildcard characters (?,*) may be used in the pattern.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetAliasDescription(const char * aliasNamePattern,int * numberAlias, OP_ALIAS_INFO ** aliasInfo);
Input
  • aliasNamePattern: See Glossary
Output
  • numberAlias: The number of aliases returned in the structure.
  • aliasInfo: List of aliases' structure returned. See OP_ALIAS_INFO
Return value
  • EOK: Success.
  • ENOMEM: Memory allocation error.
  • EIO: Error sending the request or receiving the reply.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EINVAL: Alias with the specified path is not found.
ExamplesNone
Related items

OpalCreateAlias, OpalLoadAliasDescription, OP_ALIAS_INFO

OpalGetAttributes

GroupGeneric
DescriptionGet the values of some object attributes.
See the OP_ATTRIBUTE enumeration for a complete list of available attributes.
Required ControlNone
Usage

int OpalGetAttributes (int numAttributes, OP_REF ids[],

OP_ATTRIBUTE attributes [], void ** attributeValues[]);

Input
  • numAttributes:The number of attributes to retrieve
  • ids: The array of object ids on witch the GetAttributes function will act. The size of the array must be equal to the numAttributes argument.
  • attributes: The array of attributes to get on the corresponding objects specified with the ids argument. The size of the array must be equal to the numAttributes argument.
Output
  • attributesValues: The address where the GetAttributes function will store the array of pointers to the attribute values.
Return value
  • EOK: Success.
  • EINVAL: Invalid arguments specified.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Unable to allocate memory for the attributeValues array.
ExamplesNone
Related items

OpalSetAttributes, OpalGetDefaultAttributes, OpalRestoreAttributes, OP_ATTRIBUTE.

OpalGetBlob

GroupModel Interaction, Blobs
DescriptionReceives blobs from all registered target subsystems.
Memory for output structures (blobs) is allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetBlob(const char *pszId,OP_GET_BLOBS **ppBlobs);
InputpszId ID (name) of the blob to request.
Output
  • ppBlobs: pointer to the blob to receive. see OP_GET_BLOBS
Return value
  • EOK: Success.
  • EPERM: Control requested but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Memory allocation error.
  • EAGAIN: Model not loaded.
  • ENOENT: No function registered on target for this blob ID.
  • E2BIG: Blob to receive is too big.
  • EACESS: one or more subsystems registered for this blob ID is running in XHP mode.
  • EINVAL: Invalid blob or blob ID.
  • OP_API_MODEL_IO_ TIMEOUT: Timeout waiting for reply from the model.
  • OP_API_MODEL_IO_ ERROR: Model is missing some or all processes or subsystems.
ExamplesNone
Related itemsOpalSendBlob, OP_GET_BLOBS

OpalGetBlobsControl

GroupModel Interaction, Blobs
DescriptionRequests or releases the blobs control of the currently connected model. Blob control enables the client API to send blobs to the running model. Only one client API at a time is granted blobs control.
Required ControlNone
Usageint OpalGetBlobsControl(unsigned short blobsControl);
Input
  • blobsControl: True(1) to request blobs control of the model, False(0) torelease its control.
OutputNone
Return value
  • EOK: Success.
  • EPERM: Control requested but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Memory allocation error.
ExamplesNone.
Related items

OpalGetBlob, OpalSendBlob

OpalGetChildren

GroupGeneric
DescriptionGet the reference IDs of an object’s children.
Required ControlNone
Usageint OpalGetChildren (OP_REF_ID ownerId, int * numChildren, OP_REF_ID * ids[])
Input
  • ownerId: The ID of the object that owns the children.
Output
  • numChildren: The number reference IDs returned.
  • ids: The array of reference IDs to address each of the owner’s children directly.
Return value
  • EOK: Success.
  • EINVAL: Invalid argument specified.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Unable to allocate memory for the attributeValues array.
ExamplesNone
Related items

OpalCommand, OP_OBJECT_TYPE.

OpalGetClockPeriodInfo

GroupUtilities
DescriptionReturns the ClockPeriod related information associated with the current model. This function is only valid for QNX 6.x models (not supported anymore).
Required ControlNone
Usageint OpalGetClockPeriodInfo (OP_CLOCK_PERIOD_INFO * const pInfo);
Input
  • pInfo: The ClockPeriod information associated with the current model.
OutputNone
Return value
  • EOK: Success.
  • EINVAL: Invalid parameter value.
  • EPERM: Not a QNX 6.x model.
ExamplesNone.
Related items

OP_CLOCK_PERIOD_INFO, OpalSetClockPeriodInfo

OpalGetConfigurationControl

GroupModel Configuration, System
DescriptionRequests or releases the control of the currently connected model. Configuration control enables the client API to change the configuration (OP_GLOBAL_SETTING_FILE) of the model to which it is connected. Only one client API at a time is granted configuration control.
Required ControlNone
Usage int OpalGetConfigurationControl(unsigned short configControl, const char *password);
Input
  • configControl: 1 - reserve the control0 - release the control, password optional
  • password: Configuration control password.
OutputNone
Return value
  • EOK: Configuration control granted.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EPERM: Configuration control refused.
  • EACCES: Incorrect password.
  • EINVAL: Password key not found in the file.
  • ENOENT: Problem with the configuration file.
  • ENOMEM: Not enough memory.
ExamplesNone
Related items

OpalConnect, OpalSetCurrentModel

OpalGetConnectionPointsForIO

GroupConnections
DescriptionReturns the set of information of datapoints for the IO provided.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetConnectionPointsForIO(const char* syncExchangerName,
const char* includeFilter, const char* excludeFilter,
unsigned int *numCnx,
OP_DATAPOINT_INFO** connectionPoints)
Input
  • syncExchangerName: [optional] name of the IO
  • includeFilter: [optional] include filter for the datapoints name
  • excludeFilter: [optional] exclude filter for the datapoints name
Output
  • numCnx: number of connections.
  • connectionPoints: List of datapoint structures returned. Size of the list is numCnx. See OP_DATAPOINT_INFO
Return value
  • EOK: Success.
  • EINVAL: Invalid parameter
  • ENOMEM: Memory allocation error.
  • EIO: Error sending the request or receiving the reply.
  • EBADF: Model not specified by previous OpenProject.
Examples
Related items

OP_DATAPOINT_INFO

OpalGetConnectionsDescription

GroupConnections
DescriptionReturns the set of information of connections for the current model.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetConnectionsDescription (unsigned int *numCnx, OP_CONNECTION_INFO **cnxInfo);
InputNone
Output
  • numCnx: number of connections.
  • cnxInfo: List of connections’ structures returned. Size of the list is numCnx. See OP_CONNECTION_INFO
Return value
  • EOK: Success.
  • ENOMEM: Memory allocation error.
  • EIO: Error sending the request or receiving the reply.
  • EBADF: Model not specified by previous OpenProject.
Examples
Related items

OP_CONNECTION_INFO

OpalGetConnHandle

GroupModel selection
DescriptionReturns an opaque handle associated with the current connection. This handle can be passed back to a subsequent OpalSetConnHandle. If there is no current connection, one is created.
Required ControlNone
Usageint OpalGetConnHandle(unsigned long *pHandle);
InputNone
Output
  • pHandle: handle of the current connection
Return value
  • EOK: success
  • ENOMEM: memory allocation error
  • E2BIG: too many open connections for this process
ExamplesSee multi_models
Related items

OpalDeleteConnHandle, OpalNewConnHandle, OpalSetConnHandle

OpalGetControlSignals

GroupModel Interaction, Control Signals
DescriptionReturns the current values of the control signals (see Glossary) sent to the computation nodes. These signals can be set by a call to OpalSetControlSignals.
Required ControlNone
Usageint OpalGetControlSignals(unsigned short logicalId,unsigned short allocatedSignals, unsigned short *numSignals, double values[]);
Input
  • logicalId: See Glossary.
  • allocatedSignals: Number of expected signals.
Output
  • numSignals: Number of signals in the group.
  • values: User defined array where the API stores the returned list of signal values.
Return value
  • EOK: Success.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EINVAL: Model is not loaded, or invalid logicalId.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Memory allocation error.
  • E2BIG: Specified storage not big enough to receive values.
ExamplesSee example control_signal.
Related items

OpalSetControlSignals

OpalGetControlSignalsDescription


GroupModel Interaction, Signals
DescriptionReturns a set of basic information for each control signal (see Glossary).
If there is no connection from the console to the specified subsystem, returns EOK and sets numSignals to 0.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetControlSignalsDescription(int *pSignalCnt,OP_SIGNAL_INFO **ppSignalInfoList);
InputNone
Output
  • pSignalCnt: Number of control signals returned.
  • ppSignalInfoList: List of control signals' description returned. See OP_SIGNAL_INFO.
Return value
  • EOK: Success.
  • EPERM: Control requested, but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EINVAL: Invalid parameters
ExamplesSee example control_signal.
Related items

OpalGetControlSignals

OpalGetCurrentModel

GroupModel Selection
DescriptionReturns the path and the filename of the current model i.e. the model used by the current API.
Required ControlNone
Usageint OpalGetCurrentModel (char *modelPath,char *modelName);
InputNone
Output
  • modelPath: Path of the current model (where the path is as seen by the controller on host computer).
  • modelName: Name of the original model with the extension.
Return value
  • EOK: Success.
  • EINVAL: No current active model
ExamplesNone
Related items

OpalSetCurrentModel.

OpalGetDefaultAttributes

GroupGeneric
DescriptionGet the default values of some object attributes.
See the OP_ATTRIBUTE enumeration for a complete list of available attributes.
Required ControlNone
Usageint OpalGetDefaultAttributes (int numAttributes, OP_REF ids[], OP_ATTRIBUTEattributes [], void *** attributesValues);
Input
  • numAttributes: The number of attributes to retrieve
  • ids: The array of object ids on witch the GetDefaultAttributes function will act. The size of the array must be equal to the numAttributes argument.
  • attributes: The array of attributes to get on the corresponding objects specified with the ids argument. The size of the array must be equal to the numAttributes argument.
Output
  • attributesValues: The address where the GetAttributes function will store the pointer of the attribute values.
Return value
  • EOK: Success.
  • EINVAL: Invalid arguments specified.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
ExamplesNone
Related items

OpalGetAttributes, OpalSetAttributes, OpalRestoreAttributes, OP_ATTRIBUTE

OpalGetExtraFiles

GroupModel Preparation
DescriptionReturns the list of files to be transferred or retrieved during one of the following steps:
  • transfer of files during compilation from the host to the target.
  • retrieval of files during compilation from the target to the host
  • transfer of files from the host to the target before the model is loaded
  • retrieval of files from the target to the host after the model is reset

Memory for output structures (extraFiles) is allocated by the RT-LAB API. You must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usage
int OpalGetExtraFiles (OP_EXTRA_FILE_TRANSFER_TIME transferTime,
unsigned short logicalId, OP_EXTRA_FILE ** extraFiles, unsigned short * nbFiles);
Input
  • transferTime: Specifies the moment during model compilation or load when the specified extra file is to be transferred or retrieved.
  • logicalId: See Glossary. To specify all subsystem, set the logicalId to 0.
Output
  • extraFiles: Extra file structure list. See OP_EXTRA_FILE.nb
  • Files: Number of files in the extraFiles structure
Return value
  • EOK: Success.
  • EFAULT: Invalid parameter.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ESRCH: Specified subsystem id not found.
ExamplesSee example configuration model.
Related items

OpalAddExtraFile, OpalRemoveExtraFile, OpalFreeMemory, OP_EXTRA_FILE_TRANSFER_TIME, OP_EXTRA_FILE

OpalGetInstalledMatlabReleases

GroupUtilities
DescriptionReturns the list of Matlab releases that currently installed on this computer.
Required ControlNone
Usageint OpalGetInstalledMatlabReleases(OP_MATLAB_VERSION releaseList[],int * numReleases)
Input
  • releaseList: Allocated array to store the result list.
  • numReleases: Number of elements allocated in releaseList.
Output
  • releaseList: Returned list of installed Matlab releases.
  • numReleases: Number of installed releases.
Return value
  • EOK: success
  • E2BIG: not enough elements allocated in releaseList. numReleases has been
  • EINVAL: error reading Windows registry
ExamplesNone
Related itemsNone

OpalGetIOInterfaces

GroupConnections
DescriptionReturns the set of information for IO interfaces of the project.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetIOInterfaces(const char* driverNamePattern, unsigned int* numDrivers, OP_DRIVER_INFO** driversInfo)
Input
  • driverNamePattern: [optional] filter for the IO
Output
  • numDrivers: number of IO interfaces.
  • driversInfo: List of IO interfaces structures returned. Size of the list is numDrivers. See OP_DRIVER_INFO
Return value
  • EOK: Success.
  • EINVAL: Invalid parameter
  • ENOMEM: Memory allocation error.
  • EIO: Error sending the request or receiving the reply.
  • EBADF: Model not specified by previous OpenProject.
Examples
Related items

OP_DRIVER_INFO

OpalGetLastErrMsg

GroupUtilities
DescriptionReturns a message which may have been stored when the last API call was done. This message is cleared or overwritten by subsequent operations. This call itself does not modify the stored message. An application can either preallocate a buffer of sufficient length for anticipated messages, or call this function with bufLen = 0 to retrieve the message length in msgLen, then allocate the required buffer.
Required ControlNone
Usageint OpalGetLastErrMsg(char *buf,unsigned short bufLen, unsigned short *msgLen);
Input
  • bufLen: Size of the specified buffer.
Output
  • buf: Pointer to a buffer where the stored message, if any, is stored. The message is truncated if it is longer than the available buffer length.
  • msgLen: Pointer to where the API stores the length of the stored message. (Can be NULL if not of interest. msgLen does not count terminating '\0' character).
Return valueNone
Examples
None
Related items

Error Codes on page 335

OpalGetModelState

GroupModel Execution
DescriptionReturns the state of the currently connected model and its simulation mode.
Required ControlNone
Usageint OpalGetModelState(OP_MODEL_STATE *modelState, unsigned short *realTimeMode);
InputNone
Output
  • modelState: The state of the model. See OP_MODEL_STATE. Thisparameter can be NULL if not of interest.
  • realTimeMode: The real-time mode of the model. See OP_REALTIME_MODE.This parameter can be NULL if not of interest.
Return value
  • EOK: Success.
  • EINVAL: Not connected to model controller.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
ExamplesSee example basic_example1.
Related items

OP_MODEL_STATE, OP_REALTIME_MODE

OpalGetMonitoringControl

GroupModel Interaction, Monitoring
DescriptionRequests or releases the monitoring control of the currently connected model. Monitoring control allows the client API to take and restore snapshot and also to configure the monitoring settings. Only one client API at a time is granted monitoring control.
Required ControlNone
Usageint OpalGetMonitoringControl(unsigned short monitoringControl);
Input
  • monitoringControl: True(1) to request monitoring control of the model, False(0)to release its control.
OutputNone
Return value
  • EOK: Success.
  • EPERM: Control requested, but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Memory allocation error.
  • ESRCH: Model instance id not found.
ExamplesSee example snapshot.
Related items

OpalSnapshot

OpalGetNodeCpu

GroupModel Preparation
DescriptionGet the cpu assignment option for a list of subsystems of the current model. Cpu assignment is not available for NT target.
Required ControlNone
Usageint OpalGetNodeCpu (unsigned short numSubsys,char *subsysName[], char *cpuOption);
Input
  • numSubsys: Number of subsystems for which the cpu assigment is read.
  • subsysName: Array of the subsystem names.
Output
  • cpuOption: Cpu number assigned to the subsystem. -1 value meansautomatic mode.
Return value
  • EOK: Success.
  • EPERM: System control had not been granted to this client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOENT: Invalid subsystem name found in subsysName list parameter.
ExamplesNone
Related items

OpalSetNodeCpu

OpalGetNodeXHP

GroupModel Preparation
DescriptionGet the XHP mode option for a list of subsystems of the current model.
Required ControlNone
Usageint OpalGetNodeXHP (unsigned short numSubsys,char *subsysName[], char *XHPOption);
Input
  • numSubsys: Number of subsystems for which the XHP option is read.
  • subsysName: Array of the subsystem names.
Outputlist of boolean values showing the XHP mode for the corresponding subystem.FALSE (0) means subsystem will not run in XHP mode. TRUE (1) means the subsystem will run in XHP mode.
Return value
  • EOK: Success.
  • EPERM: System control had not been granted to this client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOENT: Invalid subsystem name found in subsysName list parameter.
ExamplesNone
Related items

OpalSetNodeXHP

OpalGetNumAcqGroups

GroupModel Configuration, Acquisition
DescriptionReturns the number of acquisition groups for the connected model.
Required ControlNone
Usageint OpalGetNumAcqGroups(unsigned short *numAcqGroups);
InputNone
OutputnumAcqGroups number of acquisition group
Return value
  • EOK: Success.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
Examples
None
Related itemsNone

OpalGetNumSignalsForGroup2

GroupModel Configuration, Acquisition
DescriptionReturns the number of signals for the specified acquisition group.
Required ControlNone
Usageint OpalGetNumSignalsForGroup2(unsigned short acqGroup,unsigned short *numSigValues, unsigned short *maxNumDynSigValues, unsigned short *numDynSigValues);
Input
  • acqGroup: Acquisition group (numbering starts at 0).
Output
  • numSigValues: Number of fixed signal values assigned to the specified acquisition group. May be NULL.
  • maxNumDynSigValues: Maximum number of dynamic signal values set for this group. May be NULL.
  • maxDynSigValues: Effective number of dynamic signal values set for the specified acquisition group. May be NULL.
Return value
  • EOK: Success.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EINVAL: Specified acquisition group is invalid or not active (does not exist on target).
  • ENOMEM: Memory allocation error.
ExamplesNone
Related itemsNone

OpalGetParameterControl

GroupModel Interaction, Parameters
DescriptionRequests or releases the parameter control of the currently connected model. Parameter control allows the client API to change the values of models' parameters. Only one client API at a time is granted parameter control.
Required ControlNone
Usageint OpalGetParameterControl(unsigned short paramControl);
Input
  • paramControl: True(1) to request control of model parameters, False(0) torelease control.
OutputNone
Return value
  • EOK: Success.
  • ENOMEM: Memory allocation error.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EPERM: Could not get parameters control.
  • EIO: Error sending the request or receiving the reply.
ExamplesSee example parameter1.
Related items

OpalSetParameters, OpalSetParametersByName

OpalGetParametersByName

GroupModel Interaction, Parameters
DescriptionReturns the parameters’ information for the specified list.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetParametersByName (unsigned int allocatedParams,char *paramPathName[], OP_PARAMETER_INFO **parameterInfo);
Input
  • allocatedParam: number of parameters to get information from
  • paramPathName: list of parameters’ path and name to get information from. Size of the list is allocatedParams
Output
  • parameterInfo: List of parameters’ structures returned. Size of the list isallocatedParam. See OP_PARAMETER_INFO
Return value
  • EOK: Success.
  • ENOMEM: Memory allocation error.
  • EIO: Error sending the request or receiving the reply.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
ExamplesParameter1
Related items

OpalSetParametersByName, OP_PARAMETER_INFO

OpalGetParametersDescription

GroupModel Interaction, Parameters
DescriptionReturns the set of information of parameters and variables for the current model.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetParametersDescription (unsigned int *numParams,OP_PARAMETER_INFO **parameterInfo, unsigned int *numVars, OP_VARIABLE_INFO **variableInfo);
InputNone
Output
  • numParamss: number of model’s parameters.
  • parameterInfo: List of parameters’ structures returned. Size of the list isnumParams. See OP_PARAMETER_INFO
  • numVars: number of model’s variables.
  • variableInfo: List of variables’ structures returned. Size of the list isnumVars. See OP_VARIABLE_INFO THIS STRUCTURE IS ALWAYS NULL IN THIS VERSION OF THE API.
Return value
  • EOK: Success.
  • ENOMEM: Memory allocation error.
  • EIO: Error sending the request or receiving the reply.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
ExamplesParameter1
Related items

OP_PARAMETER_INFO, OP_VARIABLE_INFO

OpalGetPauseTime

GroupModel Execution
DescriptionGets the value of the pause time.
Required ControlNone
Usageint OpalGetPauseTime(double *time);
InputNone
Output
  • time: Pause time in seconds.
Return value
  • EOK: Success.
  • EPERM: System control had not been granted to this client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
ExamplesNone
Related items

OpalSetPauseTime

OpalGetPhysNodeList

GroupModel Preparation
DescriptionReturns the list of physical nodes in the current hardware configuration. The physical node names are as defined in the hardware.config file.
If the allocated storage is too small for the number of physical nodes, or for the longest physical node name, none of the names are returned, but the numPhysNodes and maxPhysNodeNameLen values are set, and the return value is E2BIG. An application can use this fact to specify lengths of 0 on a first call, allocate the required storage and issue a second call to get the information.
Required ControlNone
Usageint OpalGetPhysNodeList(unsigned short allocatedPhysNode,unsigned short *numPhysNodes,unsigned short allocatedPhysNodeNameLen, unsigned short *maxPhysNodeNameLen, char *physicalNodeName[]);
Input
  • allocatedPhysNode: number of physical nodes for which storage wasallocated by the caller for the names and logical Ids.
  • allocatedPhysNodeNameLen: allocated length of the storage buffer to receive thephysical node names.
Output
  • numPhysNodes: Number of physical nodes.
  • maxPhysNodeNameLen: Length of the longest physical node name.
  • physicalNodeName: Array of strings where the API stores the names of the physical nodes.
Return value
  • EOK: Success.
  • E2BIG: Specified storage not big enough to receive values.
  • EBADF:Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • OP_API_EBAD_CONFIG: Hardware configuration file doesn't exist or no nodes are specified.
  • EIO: Error sending the request or receiving the reply.
ExamplesSee example configuration.
Related itemsNone

OpalGetRtlabVersion

GroupUtilities
DescriptionReturns the versions of the RT-LAB API and the currently running MetaController
Required ControlNone
Usageint OpalRtlabVersion(char *metaVersion,unsigned short *metaVersionLen, char *apiVersionunsigned short *apiVersionLen);
Input
  • metaVersionLen: Size of the buffer for the MetaController version.
  • apiVersionLen: Size of the buffer for the API version.
Output
  • metaVersion: Pointer to a buffer where the MetaController version is stored. Buffer must have been allocated before calling the function
  • metaVersionLen: Pointer to where the API stores the length of the MetaController version string. The value is only updated if the MetaController version string’s length is bigger than the allocated one.
  • apiVersion: Pointer to a buffer where the API version is stored. Buffer must has been allocated before calling the function.
  • apiVersionLen: Pointer to where the API stores the length of the API version string. The value is only updated if the API version string’s length is bigger than the allocated one.
Return value
  • EOK: Succes
  • E2BIG: Allocated buffers are too small.
  • EIO: Error connecting to MetaController
ExamplesNone
Related itemsNone

OpalGetRtlabLicenseExpirationDate

GroupModel selection
DescriptionReturns the number of days remaining before the RT-Lab license expires. (deprecated) Always return -1.
Required ControlNone
Usageint OpalGetRtlabLicenseExpirationDate(int *nbDaysLeft);
InputNone
Output
  • nbDaysLeft: Number of days before the license expires. (deprecated) Always return -1.
Return value
  • EOK: success
  • OP_API_ENO_LICENSE: license not available
ExamplesNone
Related itemsNone

OpalGetSignalControl

GroupModel Interaction, Control Signals
DescriptionRequests or releases the signal control of the currently connected model. Signal control allows the client API to change the values of models's control signals. Only one client API at a time is granted signal control.
Required ControlNone
Usageint OpalGetSignalControl(unsigned short logicalId,unsigned short signalControl);
Input
  • logicalId: Always 0.
  • signalControl: True(1) to request control of the signals of the model or thenode, False(0) to release control of all target subsystems.
OutputNone
Return value
  • EOK: Success.
  • EPERM: Control requested, but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
ExamplesSee example control_signal.
Related items

OpalSetControlSignals

OpalGetSignalsByName

GroupModel Interaction, Signals
DescriptionReturns the values for the specified signal names
Required ControlNone
Usageint OpalGetSignalsByName(int signalCnt,char **ppSignalNameList, double *pRetValueList);
Input
  • signalCnt: Number of signals to get.
  • ppSignalNameList: List of signals' names to get the values.
Output
  • pRetValueList: List of value associated to the specified signals’ names
Return value
  • EOK: Success.
  • EPERM: Control requested, but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EINVAL: Invalid parameters
ExamplesNone
Related itemsOpalGetSignalsDescription

OpalGetSignalsDescription

GroupModel Interaction, Control Signals
DescriptionReturns a set of basic information for each available signal in the model.
Memory for output structure has been allocated by the RT-LAB API. User must free this memory with a call to OpalFreeMemory.
Required ControlNone
Usageint OpalGetSignalsDescription(int *pSignalCnt,OP_SIGNAL_INFO **ppSignalInfoList);
InputNone
Output
  • pSignalCnt: Number of signals returned.
  • ppSignalInfoList: List of signals' description returned. See OP_SIGNAL_INFO.
Return value
  • EOK: Success.
  • EPERM: Control requested, but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • EINVAL: Invalid parameters
ExamplesNone
Related items

OpalGetSignalsByName

OpalGetStopTime

GroupModel Execution
DescriptionGets the value of the stop time.
Required ControlNone
Usageint OpalGetStopTime(double *time);
InputNone
Output
  • time: Stop time in seconds.
Return value
  • EOK: Success.
  • EPERM: System control had not been granted to this client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
ExamplesNone
Related items

OpalSetStopTime

OpalGetSubsystemList

GroupModel Preparation
Description

Returns the list of subsystems in the current model: their name, their logical id and the name of the physical node on which each is assigned. The physical node name is an empty string when the subsystem has not yet been assigned to a physical node.


If the allocated storage is too small for the number of subsystems, or for the longest subsystem or physical node name, none of the names or logical ids are returned, but the numSubsys, maxSubsysNameLen and maxPhysNodeNameLen values are returned to the user. An application can use this fact to specify lengths of 0 on a first call, allocate the required storage and issue a second call to get the information.

Required ControlNone
Usageint OpalGetSubsystemList(unsigned short allocatedSubsys,unsigned short *numSubsys,unsigned short allocatedSubsysNameLen, unsigned short *maxSubsysNameLen, unsigned short allocatedPhysNodeNameLen, unsigned short *maxPhysNodeNameLen, char *subsysName[],unsigned short logicalId[], char *physNodeName[]);
Input
  • allocatedSubsys: number of subsystems for which storage was allocatedby the caller for the names and logical Ids.
  • allocatedSubsysNameLen: allocated length of the storage buffer to receive the subsystem names.
  • allocatedPhysNodeNameLen: allocated length of the storage buffer to receive thephysical node names.
Output
  • numSubsys: Number of subsystems.
  • maxSubsysNameLen: Length of the longest subsystem name.
  • maxPhysNodeNameLen: Length of the longest physical node name.
  • subsysName: Array of strings where the API stores the names of the subsystems.
  • logicalId: See Glossary.
  • physicalNodeName: Array of strings where the API will store the names ofthe physical nodes associated to each subsystem.
Return value
  • EOK: Success.
  • E2BIG: Specified storage not big enough to receive values.
  • EBADF:  Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • ESRCH: Model has not been compiled yet.
  • EIO: Error sending the request or receiving the reply.
ExamplesSee example configuration.
Related itemsNone

OpalGetSystemControl

GroupModel Configuration, System
DescriptionRequests or releases the system control of the currently connected model. System control enables the client API to control the model's execution. Only one client API at a time is granted system control.
Required ControlNone
Usageint OpalGetSystemControl(unsigned short systemControl);
Input
  • systemControl: True(1) to request system control of the model, False(0) torelease its control.
OutputNone
Return value
  • EOK: Success.
  • EPERM: Control requested but already given to another client.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EIO: Error sending the request or receiving the reply.
  • ENOMEM: Memory allocation error.
  • ESRCH: Model instance id not found.
ExamplesSee example basic_example1.
Related itemsOpalConnect, OpalConnectByName, OpalSetCurrentModel

OpalGetTargetFile

GroupUtilities
DescriptionTransfers files from the target node to the host development node using the FTP protocol. The FTP user used for the transfer is defined in the RT-LAB hardware configuration which can be modified through the RT-LAB MainControl sub-panels.
Required ControlNone
Usageint OpalGetTargetFile (char *sourceNodeName,char *sourceFile, char *targetPath, OP_FILE_TRANSFER_MODE mode, unsigned short logicalId);
Input
  • sourceNodeName: Physical node name (defined in RT-LAB hardware configuration).
  • sourceFile: Path and name of the file to be transferred (accepts wildcards).
  • targetPath:  Path (only) of the target directory.
  • mode: See OP_FILE_TRANSFER_MODE.
  • logicalId: See Glossary. To specify all subsystem, set the logicalId to 0.
OutputNone
Return value
  • EOK: Success.
  • EFAULT: Invalid parameter.
  • EBADF: Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EINVAL: Invalid subsystem id.
  • EIO: Error sending the request or receiving the reply.
ExamplesSee example file_transfer.
Related items

OP_FILE_TRANSFER_MODE, OpalPutTargetFile

OpalGetTargetNodeSystemInfo

GroupUtilities
DescriptionReturns information about a specified target.
Required ControlNone
Usageint OpalGetTargetNodeSystemInfo (const char * const targetname, OP_NODE_SYSTEM_INFORMATION * pNodeInfo);
Input
  • targetName: RT-LAB target name.
  • pNodeInfo: Information on target. See OP_NODE_SYSTEM_INFORMATION
OutputNone
Return value
  • EOK: Success.
  • EINVAL:  Invalid target name
  • EBADF:  Model not specified by previous OpalConnect or OpalSetCurrentModel
  • EIO:  Error sending the request or receiving the reply.
ExamplesNone
Related items

OP_NODE_SYSTEM_INFORMATION

OpalGetTargetPlatform

GroupModel Preparation
DescriptionReturns the target platform for the local or global settings.
Required ControlNone
Usageint OpalGetTargetPlatform(unsigned short *targetPlatform,unsigned short scope_flag);
Inputscope_flag                   See OP_SETTING_FILE. Valid values are:
0: local settings 1: global settings
Output
  • targetPlatform: Pointer to where the API stores the current target platform (enum OP_TARGET_PLATFORM).
Return value
  • EOK: Success.
  • EBADF:  Model not specified by previous OpalConnect or OpalSetCurrentModel.
  • EINVAL: Target platform not found.
  • ENOENT: Problem with the configuration file.
  • EPERM:  Configuration Control not granted.
  • ENOMEM: Not enough memory.OP_API_UPDATE_ AVAILABLE An update is available for