Simulator Bridge Developers Guide

AVEVA™ DYNSIM Dynamic Simulation
Simulator Bridge Developer’s Guide

Version 2021
November 2020
aveva.com
© 2020 AVEVA Group plc and its subsidiaries. All rights reserved.
No part of this documentation shall be reproduced, stored in a retrieval system, or transmitted by any means,
electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of AVEVA.
No liability is assumed with respect to the use of the information contained herein.
Although precaution has been taken in the preparation of this documentation, AVEVA assumes no responsibility
for errors or omissions. The information in this documentation is subject to change without notice and does not
represent a commitment on the part of AVEVA. The software described in this documentation is furnished under
a license agreement. This software may be used or copied only in accordance with the terms of such license
agreement.
ArchestrA, Aquis, Avantis, Citect, DYNSIM, eDNA, EYESIM, InBatch, InduSoft, InStep, IntelaTrac, InTouch, OASyS,
PIPEPHASE, PRiSM, PRO/II, PROVISION, ROMeo, SIM4ME, SimCentral, SimSci, Skelta, SmartGlance, Spiral
Software, Termis, WindowMaker, WindowViewer, and Wonderware are trademarks of AVEVA and/or its
subsidiaries. An extensive listing of AVEVA trademarks can be found at: https://sw.aveva.com/legal. All other
brands may be trademarks of their respective owners.
Publication date: Tuesday, September 29, 2020
Contact Information
AVEVA Group plc
High Cross
Madingley Road
Cambridge
CB3 0HB. UK
https://sw.aveva.com/
For information on how to contact sales and customer training, see https://sw.aveva.com/contact.
For information on how to contact technical support, see https://sw.aveva.com/support.
Table of Contents
1 INTRODUCTION .......................................................................................................... 1
2 ARCHITECTURE OVERVIEW ................................................................................... 3
2.1 SIMSCI DSS SIMULATION ENVIRONMENT ...................................................................... 3
2.2 INTEGRATION STRATEGY .............................................................................................. 4
2.3 BRIDGE SOFTWARE STRUCTURE .................................................................................... 5
3 BRIDGE MANAGEMENT APIS .................................................................................. 7
3.1 CREATION ..................................................................................................................... 7
3.1.1 Prototype ............................................................................................................... 7
3.1.2 Parameters ............................................................................................................. 7
3.1.3 Return Value .......................................................................................................... 7
3.2 STARTUP ....................................................................................................................... 7
3.2.1 Prototype ............................................................................................................... 7
3.2.2 Parameters ............................................................................................................. 7
3.2.3 Return Value .......................................................................................................... 7
3.3 REMOTE STARTUP ......................................................................................................... 8
3.3.1 Prototype ............................................................................................................... 8
3.3.2 Parameters ............................................................................................................. 8
3.3.3 Return Value .......................................................................................................... 8
3.4 SHUTDOWN ................................................................................................................... 9
3.4.1 Prototype ............................................................................................................... 9
3.4.2 Parameters ........................................................................................................... 10
3.4.3 Return Value ........................................................................................................ 10
3.5 REMOTE SHUTDOWN ................................................................................................... 10
3.5.1 Prototype ............................................................................................................. 10
DYNSIM Simulator Bridge Developer’s Guide TOC-I

3.5.2 Parameters ........................................................................................................... 10
3.5.3 Return Value ........................................................................................................ 10
3.6 GET SIMEXEC MODE ................................................................................................... 10
3.6.1 Prototype ............................................................................................................. 10
3.6.2 Parameters ........................................................................................................... 10
3.6.3 Return Value ........................................................................................................ 10
3.7 ENABLE CLIENT MESSAGES......................................................................................... 11
3.7.1 Prototype ............................................................................................................. 11
3.7.2 Parameters ........................................................................................................... 11
3.7.3 Return Value ........................................................................................................ 11
3.8 DISABLE CLIENT MESSAGES........................................................................................ 11
3.8.1 Prototype ............................................................................................................. 11
3.8.2 Parameters ........................................................................................................... 12
3.8.3 Return Value ........................................................................................................ 12
3.9 GETPASTMESSAGES .................................................................................................... 12
3.9.1 Prototype ............................................................................................................. 12
3.9.2 Parameters ........................................................................................................... 12
3.9.3 Return Value ........................................................................................................ 12
3.10 CLEANUPPASTMESSAGES......................................................................................... 12
3.10.1 Prototype ............................................................................................................. 12
3.10.2 Parameters ........................................................................................................... 12
3.11 SIM4ME EVENT LOG CONTROL............................................................................... 13
3.11.1 Prototype ............................................................................................................. 13
3.11.2 Parameters ........................................................................................................... 13
3.11.3 Return Value ........................................................................................................ 13
SIM4ME REPORT CLIENT MESSAGES OBJECT ....................................................................... 13
TOC-II
3.12 SAMPLE PROGRAM – BRIDGE FRONT-END MANAGEMENT ........................................ 14
3.12.1 Source Code ......................................................................................................... 14
3.12.2 Building the Sample Program Using Visual C++ ................................................. 15
3.12.3 Building the Demo Program Using Visual C++ ................................................... 18
3.13 LOGGER ................................................................................................................... 19
4 SIMULATION CONTROL API .................................................................................. 21
4.1 OVERVIEW .................................................................................................................. 21
4.1.1 Prototype ............................................................................................................. 21
4.1.2 Parameters ........................................................................................................... 21
4.1.3 Return Value ........................................................................................................ 22
4.2 SIMULATOR OPERATING MODE CONTROL ................................................................... 22
4.3 SIMULATION PROCESS CONTROL ................................................................................. 24
4.3.1 Synchronization Time Step.................................................................................... 25
4.3.2 Synchronization Scheme ....................................................................................... 25
4.3.3 Prototype ............................................................................................................. 29
4.3.4 Parameters ........................................................................................................... 29
4.3.5 Return Value ........................................................................................................ 29
4.4 SIMULATION SNAPSHOT CONTROL .............................................................................. 29
4.4.1 Introduction ......................................................................................................... 29
4.4.2 Saving a Snapshot ................................................................................................ 30
4.4.3 Restoring a Snapshot ............................................................................................ 30
4.4.4 Deleting a Snapshot ............................................................................................. 30
4.5 SIMULATION SPEED CONTROL ..................................................................................... 31
4.6 CLOSE SIMULATION .................................................................................................... 31
5 DATA POINT API ....................................................................................................... 33
5.1 DATA POINT AND POINT PATH..................................................................................... 33
DYNSIM Simulator Bridge Developer’s Guide TOC-III

5.2 DATA POINT TYPES ..................................................................................................... 33
5.3 INDIVIDUAL DATA POINT MANIPULATION ................................................................... 33
5.3.1 Prototypes ............................................................................................................ 34
5.3.2 Parameters ........................................................................................................... 34
5.3.3 Return .................................................................................................................. 35
5.4 SAMPLE PROGRAM – DEMONSTRATING THE DATA POINT API ..................................... 35
5.5 INTRODUCTION............................................................................................................ 37
5.6 BASIC CONCEPTS AND DATA STRUCTURES .................................................................. 38
5.6.1 Information .......................................................................................................... 38
5.6.2 Data ..................................................................................................................... 38
5.6.3 Data Type ............................................................................................................ 38
5.6.4 Value (Data value) ............................................................................................... 39
5.6.5 Point .................................................................................................................... 40
5.6.6 Point Type ............................................................................................................ 40
5.6.7 Point Data............................................................................................................ 41
5.7 CONFIGURE A SIM4MEDATAROUTER OBJECT ............................................................ 41
5.7.1 Overview .............................................................................................................. 41
5.7.2 Prototype ............................................................................................................. 41
5.7.3 Parameters ........................................................................................................... 42
5.7.4 Return Value ........................................................................................................ 42
5.7.5 Specify Analog Data Transfer Information............................................................ 42
5.7.6 Specify Discrete Data Transfer Information.......................................................... 44
5.8 DATA ROUTER MANAGEMENT API.............................................................................. 46
5.8.1 Creating a SIM4MEDataRouter Object ................................................................ 46
5.8.2 Prototype ............................................................................................................. 46
5.8.3 Parameters ........................................................................................................... 46
TOC-IV
5.8.4 Return Value ........................................................................................................ 46
5.8.5 Starting Data Transfer ......................................................................................... 47
5.8.6 Prototype ............................................................................................................. 47
5.8.7 Parameters ........................................................................................................... 47
5.8.8 Return Value ........................................................................................................ 47
5.8.9 Stopping Data Transfer ........................................................................................ 47
5.8.10 Prototype ............................................................................................................. 47
5.8.11 Parameters ........................................................................................................... 47
5.8.12 Return Value ........................................................................................................ 47
5.8.13 Sample Code – Router Management .................................................................... 47
5.9 RETRIEVE DATA IN BULK ............................................................................................ 49
5.9.1 Data Updating API............................................................................................... 49
5.9.2 Prototypes ............................................................................................................ 49
5.9.3 Parameters ........................................................................................................... 49
5.9.4 Return Values ....................................................................................................... 49
5.9.5 Exception Handling .............................................................................................. 49
5.9.6 Memory Management ........................................................................................... 50
5.9.7 Sample Code – Retrieving Data in Bulk ................................................................ 50
5.10 SEND DATA TO SIM4ME IN BULK ........................................................................... 52
5.10.1 Data Updating API............................................................................................... 52
5.10.2 Prototype ............................................................................................................. 52
5.10.3 Parameters ........................................................................................................... 53
5.10.4 Return Value ........................................................................................................ 53
5.10.5 Exception Handling .............................................................................................. 53
5.10.6 Sample Program – Sending Data in Bulk .............................................................. 53
6 SIMULATOR ACTION CAPTURE............................................................................ 63
DYNSIM Simulator Bridge Developer’s Guide TOC-V

6.1 INTRODUCTION............................................................................................................ 63
6.2 REGISTER FUNCTION TO CAPTURE OPERATOR ACTIONS .............................................. 63
6.3 REPLAY OPERATOR ACTIONS ...................................................................................... 65
7 SCENARIOS IN THE SIMULATOR BRIDGE .......................................................... 67
7.1 OVERVIEW .................................................................................................................. 67
7.2 CLASS LAYOUT ........................................................................................................... 67
7.3 SIM4MESCENARIOPROXY OBJECT ............................................................................. 67
7.3.1 Get all Scenarios .................................................................................................. 67
7.3.2 Get Scenario ........................................................................................................ 68
7.3.3 Create Scenario.................................................................................................... 69
7.3.4 Delete Scenario .................................................................................................... 69
7.3.5 Add a Scenario Listener ....................................................................................... 69
7.3.6 Remove a Scenario Listener.................................................................................. 71
7.3.7 Get Next ID .......................................................................................................... 71
7.3.8 Set Record Mode .................................................................................................. 71
7.3.9 Get Record Mode ................................................................................................. 72
7.3.10 Save Recording .................................................................................................... 72
7.3.11 Add a Playback Listener ....................................................................................... 72
7.3.12 Remove a Playback Listener ................................................................................. 73
7.4 SCENARIO OBJECT....................................................................................................... 73
7.4.1 Run Scenario ........................................................................................................ 73
7.4.2 Stop Scenario ....................................................................................................... 74
7.4.3 Pause Scenario..................................................................................................... 74
7.4.4 Resume Scenario .................................................................................................. 74
7.4.5 Save Scenario ....................................................................................................... 75
7.4.6 Load Scenario ...................................................................................................... 75
TOC-VI
7.4.7 Get Active Scenario Data ..................................................................................... 75
7.4.8 Get Scenario ID ................................................................................................... 76
7.4.9 Get Scenario Name............................................................................................... 76
7.4.10 Scenario Active .................................................................................................... 77
7.4.11 Scenario Paused ................................................................................................... 77
7.4.12 Set Run Mode ....................................................................................................... 77
7.4.13 Get Run Mode ...................................................................................................... 78
8 MALFUNCTIONS IN THE SIMULATOR BRIDGE ................................................. 79
8.1 OVERVIEW .................................................................................................................. 79
8.2 CLASS LAYOUT ........................................................................................................... 79
8.3 SIM4MEMALFUNCTIONPROXY OBJECT ...................................................................... 79
8.3.1 Get GetMalfunctionable objects ........................................................................... 79
8.3.2 Get New Client List ID ......................................................................................... 80
8.3.3 Get Number of Malfunctions................................................................................. 80
8.3.4 Get Malfunction Data from Cached List ............................................................... 81
8.3.5 Get Status of Malfunctions.................................................................................... 84
8.3.6 Create a malfunction object .................................................................................. 84
8.3.7 Create a malfunction object from Predefined ........................................................ 85
8.3.8 Release a Malfunction .......................................................................................... 85
8.3.9 Get Active Malfunction ......................................................................................... 85
8.3.10 Get Failure Modes ............................................................................................... 86
8.3.11 Get Data from Predefined Malfunction ................................................................. 87
8.3.12 Is There a Predefined Malfunction........................................................................ 87
8.3.13 Delete Predefined Malfunction ............................................................................. 88
8.3.14 Get Next Predefined Malfunction Number ............................................................ 88
8.3.15 Add a Malfunction Listener .................................................................................. 88
DYNSIM Simulator Bridge Developer’s Guide TOC-VII

8.3.16 Remove a Malfunction Listener ............................................................................ 89
8.3.17 Deactivate all Malfunctions .................................................................................. 89
8.4 MALFUNCTION OBJECT ............................................................................................... 90
8.4.1 Set Initial Data ..................................................................................................... 90
8.4.2 Get Initial Data .................................................................................................... 90
8.4.3 Save Predefined Data ........................................................................................... 90
8.4.4 Load Predefined Data .......................................................................................... 91
8.4.5 Activate Malfunction ............................................................................................ 91
8.4.6 Deactivate Malfunction ........................................................................................ 91
8.4.7 Is Malfunction Active............................................................................................ 92
8.4.8 Get Active Malfunction Data ................................................................................ 92
8.4.9 Get ID .................................................................................................................. 93
8.4.10 Get Name ............................................................................................................. 93
9 TPMS IN THE SIMULATOR BRIDGE...................................................................... 94
9.1 OVERVIEW .................................................................................................................. 94
9.2 CLASS LAYOUT ........................................................................................................... 94
9.3 SIM4METPMPROXY OBJECT ..................................................................................... 94
9.3.1 Get Exercise object............................................................................................... 95
9.3.2 Get All Exercises .................................................................................................. 95
9.3.3 Get Number of All Exercises ................................................................................. 97
9.3.4 97
9.3.5 Get Number of All Exercises for all Users............................................................. 97
9.3.6 Get Number of all Configured exercises ............................................................... 97
9.3.7 Get the number of exercises for one user .............................................................. 98
9.3.8 Get Exercise at a specified index .......................................................................... 98
9.3.9 Create an exercise in a simulation ........................................................................ 99
TOC-VIII
9.3.10 Add a new run TPR Exercise .............................................................................. 100
9.3.11 Delete a TPR Exercise ........................................................................................ 101
9.3.12 Release a TPR Exercise ...................................................................................... 102
9.3.13 Gets the MAX number used for TPMs ................................................................. 102
9.3.14 Does a TPR Exist ............................................................................................... 103
9.3.15 Return number of active exercises ...................................................................... 103
9.3.16 Return Active Exercise for a given row ............................................................... 104
9.3.17 Add an Active Exercise ....................................................................................... 104
9.3.18 Remove an Active Exercise ................................................................................. 105
9.3.19 Export an exercise to a .csv file .......................................................................... 105
9.4 EXERCISE OBJECT ..................................................................................................... 106
9.4.1 Set TPR number for an Exercise ......................................................................... 106
9.4.2 Get TPR number for an Exercise ........................................................................ 106
9.4.3 Set Description for an Exercise........................................................................... 106
9.4.4 Get Description for an Exercise.......................................................................... 107
9.4.5 Set IC number for an Exercise ............................................................................ 107
9.4.6 Get IC Number for an Exercise........................................................................... 107
9.4.7 Set Student Name for an Exercise ....................................................................... 108
9.4.8 Get Student Name for an Exercise ...................................................................... 108
9.4.9 Set Scoring Equation for an Exercise .................................................................. 108
9.4.10 Get Student Name for an Exercise ...................................................................... 108
9.4.11 Set Score for an Exercise .................................................................................... 109
9.4.12 Get Score for an Exercise ................................................................................... 109
9.4.13 Set Comments for an Exercise ............................................................................ 109
9.4.14 Get Comments for an Exercise............................................................................ 110
9.4.15 Set Trends for an Exercise .................................................................................. 110
DYNSIM Simulator Bridge Developer’s Guide TOC-IX

9.4.16 Get Comments for an Exercise............................................................................ 110
9.4.17 Set the Start Time for an Exercise ....................................................................... 111
9.4.18 Get Start Time for an Exercise............................................................................ 111
9.4.19 Set the Stop Time for an Exercise........................................................................ 111
9.4.20 Get Stop Time for an Exercise ............................................................................ 112
9.4.21 Set the Duration Time for an Exercise ................................................................ 112
9.4.22 Get Duration Time for an Exercise ..................................................................... 112
9.4.23 Set the TPR Date for an Exercise ........................................................................ 112
9.4.24 Get TPR Date for an Exercise............................................................................. 113
9.4.25 Set the list of Dynamic points for an Exercise ..................................................... 113
9.4.26 Get the list of Dynamic Points for an Exercise .................................................... 115
9.4.27 Add a Config Point for an Exercise..................................................................... 116
9.4.28 Delete a Config Point for an Exercise ................................................................. 117
9.4.29 Set the list of Config points for an Exercise ......................................................... 117
9.4.30 Get the list of Config Points for an Exercise ....................................................... 118
9.4.31 Get the Results for an Exercise ........................................................................... 118
9.4.32 Start the Exercise ............................................................................................... 118
9.4.33 Stop the Exercise ................................................................................................ 119
9.4.34 Save the Exercise................................................................................................ 119
9.4.35 Save the Exercise to another number .................................................................. 119
9.4.36 Get unique ID for a TPR..................................................................................... 119
9.4.37 Get the ID Number for an Exercise ..................................................................... 120
9.4.38 Get the number of points for an Exercise ............................................................ 120
9.4.39 Get Config Point at Specified Index .................................................................... 120
9.4.40 Get Dynamic Point at Specified Index................................................................. 121
9.4.41 Set the Instructor for an Exercise........................................................................ 121
TOC-X
9.4.42 Get Instructor for an Exercise ............................................................................ 121
10 SIMULATOR BRIDGE DEVELOPMENT KIT ...................................................... 123
10.1 OVERVIEW ............................................................................................................. 123
10.2 RUNTIME ENVIRONMENT ....................................................................................... 124
10.2.1 Simulator Bridge Front-end................................................................................ 124
10.2.2 Third Party Runtime Support .............................................................................. 125
10.3 LIBRARY FILES ...................................................................................................... 125
10.4 HEADER FILES ....................................................................................................... 126
10.5 DEMONSTRATION FILES ......................................................................................... 127
APPENDIX A – FOXSCI CONVERSION METHODS ...................................................... 129
DYNSIM Simulator Bridge Developer’s Guide TOC-XI

1 Introduction
The Simulator Bridge Developers Guide discusses how to develop integration software between
SimSci ® simulation products and those from third party companies.
The Simulator Bridge provides a single simulator communication interface between a customer
simulator and the SimSci dynamic Simulation Executive, known as either the SIM4ME/Dynamic
Simulation Suite (SIM4ME/DSS) SimExec or simply the SimExec.
In the integrated simulation environment, the Simulator Bridge’s API and runtime environment
gives the third party, or ‘customer,’ simulator these capabilities:
• Exchange simulation data between the SimExec and other simulation engines, such
as FSIM Plus®, DYNSIM®, ABSIM, etc.
• Take complete control of the SimExec and drive it as a simulation sub-system. In this
situation, the SimExec becomes the “slave” to the driving simulator that acts as the “master.”
The Simulator Bridge is designed with Object Oriented Technologies (OOT) and implemented in
standard C++. This guide details the development of an application using OOT and C++.
The Simulator Bridge is delivered with an easy to use software package called the “Simulator
Bridge Development Kit” (SBDK). SBDK contains the necessary runtime environment, library
and include files that are used by the compiler, linker and application programs. The end user
should use Visual Studio 2003 (English) or a later of Visual Studio to customize the connection to
the third party simulator.
Dynsim Simulator Bridge Developer’s Guide 1

2 Architecture Overview
2.1 SimSci DSS Simulation Environment

The modular simulation architecture of a SimSci simulator allows multiple simulation engines,
which could be spread over multiple computers, to execute lock-step with the Simulation
Executive (SimExec) for use with dynamic simulation applications such as Operator Training
Simulators (OTS).
The SimExec is the core piece of this distributed system. It not only integrates the capabilities of
numerous SimSci simulation products into a single environment, but also provides capability for
splitting OTS tasks between multiple processors and/or multiple computers. The environment
appears seamless to the user.
Numerous SimSci simulation products can be integrated into the environment, such as:
• DYNSIM – Process model package
• FSIM Plus – Foxboro® DCS emulation
• TRISIM Plus® – Triconex emulation
• ABSIM – Allen Bradley PLC5 emulation
• BALTRAN – Bailey control system, full emulation
• Ovation Engine Link – Ovation control system, full stimulation
The diagram below describes the architecture of a SimExec based simulation system.
DYNSIM TRISIM
Baltran Pl
FSIM
Third Party Pl
SBDK
Simulator SimExec
ABSIM
GUI

2.2 Integration Strategy
Normally, simulators are distributed processes running in separated memory space, allowing
them to be used as stand-alone applications. To integrate distributed processes into a single
simulation environment, the Simulator Bridge consists of two pieces of software: the “bridge
front-end” and the “bridge servant.” The bridge front-end is installed and running in the
customer’s simulator, while the bridge servant resides within the SimExec.
The two distributed bridge components are coupled together by the communication channel in the
Simulator Bridge runtime environment.
The bridge front-end publishes a set of methods to interface programmatically with the customer
simulator. Using these APIs, the customer can develop software that joins their simulator with the
bridge front-end, hence with the SimExec in the SimSci system.
This integration strategy is illustrated in the following chart.
SimSci-Esscor Simulator Customer Simulator
(Slave) (Master)
SimExec
Simulator Bridge
Simulator Bridge
Servant
The Simulator Bridge front-end APIs can be divided into the following groups:
Bridge management APIs Creates the bridge front-end object, starts and stops the bridge
communication.
Simulation control APIs Provides operating mode change, simulation process state
control, snapshot save/restore, individual point data
manipulation, etc.
Bulk data transfer APIs Provides data router management, router configuration,
sending/retrieving data in bulk via a router, etc.
Note: The remainder of document will use the term “Simulator Bridge” or just “Bridge” to refer
the “Simulator Bridge front-end.” This is the only portion of the Simulator Bridge that is exposed
to the developer.
2.3 Bridge Software Structure
The bridge (front-end) interface consists of four major classes and six support classes. The class
structure for the bridge is as follows:
The SIM4MEProxy class is the main implementation class of the bridge. It acts as a front-end
delegate for the SimExec. It provides methods for bridge management and SimExec control and
launches these objects when asked:
• SIM4MEDataRouter
• SIM4MEMalfunctionProxy
• SIM4ScenarioProxy
• SIM4TPMProxy
The SIM4MEProxy class also launches an instance of the SIM4MEReportClient Messages class
which allows the user to receive client messages generated by the SIM4ME application.
The SIM4MEDataRouter class is the data transfer interface of the bridge that provides data
routing and delivery.
The SIM4MEMalfunctionProxy is the interface between the SimSci malfunction

infrastructure and the bridged application. It provides access to all the malfunction function
capabilities found in the SimSci software. This class includes two support classes:
1. Malfunction: This class acts on a single malfunction that was acquired through the
SIM4MEMalfunctionProxy object.
2. SIM4MEMalfunctionListener: This class provides back messages when a

malfunction changes state.
The SIM4MEScenarioProxy is the interface between the SimSci scenario infrastructure and
the bridged application. It provides access to scenario features, such as record and playback,
found in the SimSci software. This class includes three support classes:
1. Scenario: This class acts on a single scenario that was

acquired through the SIM4MEScenarioProxy object.
2. SIM4MEScenarioPlaybackListener: This class provides messages

when a scenario changes state.
3. SIM4MEScenarioListener: This class provides messages when a

scenario is activated.

The SIM4METPMProxy is the interface between the SimSci scenario infrastructure and the
bridged application. It provides access to TPM features, such as stop, start and save found in the
SimSci software. This class includes one support class:
1. Exercise: This class acts on a single exercise that was

acquired through the SIM4MEScenarioProxy object.
The class diagram shown in Figure 1 on the next page reveals the internal structure of the bridge
software.
The remainder of this document covers the usage of the SIM4MEProxy class, the
SIM4MEDataRouter class, the SIM4MEMalfunctionProxy class, the SIM4MEScenarioProxy
class, the SIM4METPMProxy class, and all their supporting classes. The declarations of the
classes are in the header files: SIM4MEProxy.h,SIM4MEDataRouter.h.,
SIM4MEMalfunctionProxy.h, SIM4MEScenarioProxy.h, and SIM4METPMProxy. These files
are discussed in the
Appendices.
SIM4MEDataRouter 1:1
9 methods
SIM4MEProxy 1:1 SIM4MEScenarioProxy
20 methods 12 methods
SIM4MEReportClientMessages
6 methods 1:1
1:1
SIM4MEScenarioListener
1:1 13 mrthods
SIM4MEMalfunctionProxy 1:1
16 methods
1:1
SIM4MEPlaybackListener
1 method
MalfunctionListener 1:1 SIM4METPRProxy
7 methods 18 methods
1:n
1:n 1:n Scenario
Malfunction
10 methods Exercise 7 methods
42 methods
Figure 1. Simulator Bridge Class Diagram
3 Bridge Management APIs
3.1 Creation
The SIME4MEProxy provides a factory pattern method that can be used to generate an instance
of this class.
3.1.1 Prototype
static SIM4MEProxy* createSIM4MEProxy ();
3.1.2 Parameters
None
3.1.3 Return Value
• A pointer to a SIME4MEProxy instance as the bridge (front-end)
• NULL if a proxy can’t be created
3.2 Startup
The start() method activates the simulator bridge. It initializes the proxy object and sets up
the communication between the proxy and the bridge servant on the target SimExec.
3.2.1 Prototype
bool start(int& argc, char* argv[])
3.2.2 Parameters
• argc number of command line arguments
• argv command line arguments
3.2.3 Return Value

• TRUE on success
• FALSE on failure
The arguments of this method are in the format of program command line. They should provide
necessary information for the initialization of bridge communication, such as CORBA naming
service, SimExec name and hosts name.
Note: CORBA is the underlying platform of the Simulator Bridge. The Simulator Bridge front-
end and servant find each other via the CORBA naming service. They also exchange messages
and data through the CORBA RPC mechanism. However, the bridge software package

encapsulates the CORBA specific implementation, so that the developer does not need to know
CORBA to use the bridge API.
An example of the arguments is shown below.
argc = 12
argv = -sim4mehost simhost -sim4mename SimExecutive -ORBInitRef

NameService=iioploc://simhost:10152/NameService -
ORBSvcConfDirective "static Server_Strategy_Factory '-
ORBConcurrency thread-per-connection'" –nsversion DSS45
where
sim4mehost The host machine name (where the SimExec is running).
sim4mename SimExec name in CORBA naming service
ORBInitRef The ORB initial reference argument specifies the CORBA naming
service
ORBSvcConfDirective Specifies an ORB service configuration directive
nsversion The version of SIM4ME that the user is connecting to
3.3 Remote Startup

The remoteStart() method activates the simulator bridge and starts the entire simulation
environment including the target SimExec based on specified command line options. It initializes
the proxy object and sets up the communication between the proxy and the bridge servant on the
target SimExec.
3.3.1 Prototype
bool remoteStart(int& argc, char* argv[])
3.3.2 Parameters
• argc number of command line arguments
• argv command line arguments
3.3.3 Return Value

• TRUE on success
• FALSE on failure
The arguments of this method are in the format of program command line. They should provide
necessary information for the initialization of bridge communication and simulation startup, such
as CORBA naming service, SimExec name and hosts name and simulation information.

Note: CORBA is the underlying platform of the Simulator Bridge. The Simulator Bridge front-
end and servant find each other via the CORBA naming service. They also exchange messages
and data through the CORBA RPC mechanism. However, the bridge software package
encapsulates the CORBA specific implementation, so that the developer does not need to know
CORBA to use the bridge API.
An example of the arguments is shown below.
argc = 20
argv = -sim4mehost simhost -sim4mename SimExecutive –nshost

nshost –nsport 10152 –dbhost databasehost –simulation
simulationname –simfullpath simulationpath -ORBInitRef
NameService=iioploc://simhost:10152/NameService
–ORBSvcConfDirective "static Server_Strategy_Factory
'-ORBConcurrency thread-per-connection'" –nsversion DSS51
where
sim4mehost Host machine name (where the SimExec is running)
sim4mename SimExec name in CORBA naming service
nshost Host machine name for CORBA naming service
nsport Port number for CORBA naming service
dbhost Database host machine name
simulation Name of the simulation that is being used
simfullpath Full path name for s4m file used to load the specified simulation
ORBInitRef ORB initial reference argument specifies the CORBA naming service
ORBSvcConfDirective Specifies an ORB service configuration directive
nsversion Version of SIM4ME that the user is connecting to
3.4 Shutdown
The shutdown() method closes the communication between the proxy and bridge servant on
the target SimExec, it also destroys the proxy itself and all the data routers that have been created.
3.4.1 Prototype
void shutdown()

3.4.2 Parameters
None
3.4.3 Return Value

None
3.5 Remote Shutdown

The remoteShutdown() method closes the communication between the proxy and bridge
servant on the target SimExec and shuts down the entire simulation including the target SimExec.
It also destroys the proxy itself and all the data routers that have been created.
3.5.1 Prototype
void remoteShutdown()
3.5.2 Parameters
None
3.5.3 Return Value

None
3.6 Get SimExec Mode

This method returns what mode the SimExecutive is in.
3.6.1 Prototype
SimMode getSimMode()
3.6.2 Parameters
None
3.6.3 Return Value

Valid modes are determined by the following enum defined in SimProxy.h:
enum SimMode
FROZEN,
RUNNING,

IC_SAVED,
IC_RESET,
BACKTRACK_RESET,
SHUTDOWN,
SINGLE_STEP,
ENGINE_ERR,
UNKNOWN
};
3.7 Enable Client Messages

This method will enable the bridge application to receive messages generated by the SIM4ME
environment. The SIM4MEReportClientMessages object is passed to the server. The
server will call the methods on this object respective to the each message type generated on the
server.
3.7.1 Prototype
void
enableClientMessages(SIM4MEReportClientMessages* obj)
3.7.2 Parameters
obj – This object is the listener inherited from the SIM4MEReportClientMessages
object defined in the SIM4MEProxy.h file.
3.7.3 Return Value

None
3.8 Disable Client Messages

This method will disable the bridge application from receiving messages generated by the
SIM4ME environment. The ID is retrieved from the SIM4MEReportClientMessages object
passed to the enableClientMessages method.
3.8.1 Prototype
void disableClientMessages(long id);

3.8.2 Parameters
long id – Id is retrieved from the object derived in SIM4MEProxy.h. Use the getID()
method defined by this object.
3.8.3 Return Value

None
3.9 getPastMessages
This method will return all the messages that have been generated since the simulation started.
The SIM4MEControlDemo.cpp example code in the SBDK demonstrates how to use the
cleanupPastMessages and getPastMessages methods.
3.9.1 Prototype
long getPastMessages(char*** messages);
3.9.2 Parameters
Messages – An array of strings of messages
3.9.3 Return Value

Number of messages returned.
3.10 cleanupPastMessages
This method is used to clean up the messages in memory passed by the getPastMessages method.
This method is required since in Microsoft Windows systems memory objects created in a dll
need to be released in the dll. The SIM4MEControlDemo.cpp example code in the SBDK
demonstrates how to use the cleanupPastMessages and getPastMessages methods.
3.10.1 Prototype
void cleanupPastMessages(long numMessages, char*** messages);
3.10.2 Parameters
numMessages – This value is the number of messages returned by the getPastMessages
method.
messages – This value are the message data items passed by the getPastMessages nethod
Return Value
None

3.11 Sim4ME Event Log Control
This method is used start and stop the DynSim Event logging mechanism. Passing a true value to
this method will enable the DynSim Event logger and passing a false will disable the DynSim
event logger. The log file (eventLog.txt) is written to the %UserHomeDirectory% which is
typically which is c:\SIMSCI\DSSxx\User on the SimExec machine.
3.11.1 Prototype
void startEventLog(bool start);
3.11.2 Parameters
start – A true value will start the event logging and a false value will stop the event
logging.
3.11.3 Return Value

None
SIM4ME Report Client Messages Object

This object, when created by the user and registered with the SIM4MEProxy object, will receive
SIM4ME messages that are sent to the Simulation Executive. This object inherits it definition
from the SIM4MEReportClientMessages class defined in the SIM4MEProxy.h found in the
SBDK toolkit. The user implements an object of this class type and registers it with the SIM4ME
Simulation Executive via the enableClientMessages method described in the previous section.
This object has the following four methods that are called whenever messages are sent to the
Simulation Executive:
1) reportSevereError Called when a Severe Error is issued to the

SIM4ME Simulation Executive
2) reportError Called when an Error is issued to the SIM4ME

Simulation Executive
3) reportWarning Called when a warning is issued to the SIM4ME

Simulation Executive
4) reportInformationOnly Called when an Information Message is issued

to the SIM4ME Simulation Executive
Each of these methods will also receive the text messages that were sent to the executive. This
class also has two other methods getID and setID to get and receive this objects ID.

3.12 Sample Program – Bridge Front-end Management
3.12.1 Source Code
The following source code demonstrates the use of the bridge management APIs. It creates a
SIM4MEProxy instance, connects it to remote SimExec, and then shuts it down.
#include <cstdlib> // EXIT_SUCCESS, EXIT_FAILURE
#include <iostream> // cout
// DLL import
#include <SimulatorBridge/Published/SimulatorBridge_exports.h>
// Bridge front end API
#include <SimulatorBridge/Published/SIM4MEProxy.h>
using namespace std;
int main(int argc, char* argv[])
{ int ret = EXIT_SUCCESS; // Return value.
//
// *** Step 1: Create a SIM4ME proxy instance.
//
SIM4MEProxy* proxy = SIM4MEProxy::createSIM4MEProxy ();
std::cout << “\tproxy created” << endl;
//
// *** Step 2: Start the proxy by connecting to the remote SimExec
// exit if fails
//
if (!proxy->start (argc, argv))
std::cout << “\tproxy start failed” << endl;
return EXIT_FAILURE;
std::cout << “\tproxy started” << endl;

//
// *** Step 3: SimExec control and data transfer
//
//
// *** Step 4: Shut down the bridge front-end
//
proxy ->shutdown ();
std::cout << “\tproxy shutdown” << endl;
// return
return ret;
3.12.2 Building the Sample Program Using Visual C++

This section describes the steps needed to build the sample program using Visual C++. To get
started, create a directory C:\Program Files\SIMSCI\SimulatorBridge, then copy the directories
bin, demo, doc, include, and lib from your SBDK CD to this directory.
Creating a New Workspace and Project
• Launch Visual C++
• Click on New... menu item under File
• In the dialog box, click on the Projects tab
• Click on Win32 Console Application option
• Select C: \ Program Files \ SIMSCI \ SimulatorBridge \ demo directory in place for

Location
• Enter Sample34 in the Project Name
• Click OK
Developing the C++ Source Code
• Click on New.. menu item under File
• Click on C++ Source File and check the Add to project check box
• In the File Name editor field, type Sample34.cpp

• Click OK
• A blank window will be created. Now copy the source code listed in the Source Code
section above into Sample34.cpp window
• Click on Save menu item
Changing Project Build Settings to use Debug Multithreaded DLL
1. Click on Settings under Project menu
2. Click on C/C++ tab
3. Select Code Generation under Category
4. Select Debug Multithreaded DLL under Use run-time library
5. Click OK
Including the Simulator Bridge API Header Files
1. Click on menu item Files in Add To Project under Project Menu
2. Select C:\ Program Files \ SIMSCI \ SimulatorBridge \ include \ SimulatorBridge \ Published

directory
3. Select SIM4MEProxy.h, SIM4MEDataRouter.h and

SimulatorBridge_exports.h from the folder
4. Click OK
6. Click on C/C++ tab
7. Select Preprocessor from Category dropdown
8. Type C: \ Program Files \ SIMSCI \ SimulatorBridge \ include in the Additional include

directories editor field
9. Click OK
Including Libraries in Project Settings
2. Click on Link tab
3. Select Input from Category dropdown
4. Add SimBridge.lib in Object/Library Modules field

5. Add C: \ Program Files \ SIMSCI \ SimulatorBridge \ lib \ windows in Additional library path
field
6. Click OK
Building the Sample Program
Click on Build sample34.exe under Build menu (or press F7). The build process should generate
server.exe with no errors. If there are errors, go through the steps again and fix them before
proceeding.
Setting the Execution Path
2. Click on Debug tab
3. Set the Executable for Debug Session to C:\ Program Files \ SIMSCI \ SimulatorBridge \ bin \
windows \ Sample34_dbg.exe
4. Click OK
6. Click on Link tab
7. Select General category
8. Under Output File Name, enter C: \ Program Files \ SIMSCI \ SimulatorBridge \ bin \
windows \ Sample34_dbg.exe
9. Click OK
Changing Project Run Settings
Start your DYNSIM or FSIM Plus session that this bridge demo program will attach to. You’ll
need the following information in order to enter the run arguments. To do this, enter your
username and password (e.g. simsci simsci), but click on Options before completing the login.
Record the following information from the Options pane:
Example:
• SimExec CORBA name: SimExecutive
• SimExec host name: simhostname01
• CORBA Naming Server name: simhostname01
• CORBA Naming Server port: 10001
1. Click on Settings under Project menu and ensure that Win32 Release is selected

3. In Program arguments field, type in: -sim4mehost simhostname01 -sim4mename

SimExecutive -ORBInitRef
NameService=iioploc://simhostname01:10001/NameService -ORBSvcConfDirective
"static Server_Strategy_Factory '-ORBConcurrency thread-per-connection'" -
logging_level NOLOG -logging_file simbridge.log
4. Click OK
Running the Sample Program
Press <Control>-F5 to start the program in a DOS window. Observe following messages on the
console window.
proxy created
proxy started
proxy shutdown
If the bridge fails to start, the following message displays.
proxy created
proxy start failed
3.12.3 Building the Demo Program Using Visual C++

This section describes the steps needed to build the demo program using Visual C++. To get
started, create a directory C:\Program Files\SIMSCI\SimulatorBridge, then copy the directories
bin, demo, doc, include, and lib from your SBDK CD to this directory.
Building the demo programs
1. Make sure all files copied from the SBDK CD are writable
2. Open C:\ Program Files \ SIMSCI \ SimulatorBridge \ demo \ SimBridgeDemo \ windows \

SimBridgeDemo.dsw
3. Select one of the projects to be the active project
4. Click on menu item Files in Add To Project under Project Menu.
5. Select C:\Program Files \ SIMSCI \ SimulatorBridge \ include \ SimulatorBridge \ Published

directory.
6. Select SIM4MEProxy.h, SIM4MEDataRouter.h and

SimulatorBridge_exports.h from the folder
7. Click OK

8. Add an environment variable called SBDK to the “system variables” and set it’s value to C:
\Program Files \ SIMSCI \ SimulatorBridge
9. Add %SBDK%\bin\windows to the system PATH environment variable
10. Build
Running the demo programs
1. Click on Settings under Project menu and ensure that Win32 Release is selected.
3. In Program arguments field, type in: -sim4mehost simhostname01 -sim4mename

SimExecutive -ORBInitRef
NameService=iioploc://simhostname01:10152/NameService -ORBSvcConfDirective
"static Server_Strategy_Factory '-ORBConcurrency thread-per-connection'" -
logging_level NOLOG -logging_file simbridge.log (replace the host names with
correct machine name)
4. Run
3.13 Logger
The Simulator Bridge logger can be used to provide information, warnings, errors and other
generic messages for the user. There are 2 command line arguments that are required for this
feature.
-logging_level – logging level. Valid values include:
• NOLOG – no logging
• ERROR – log error messages
• WARN – log warning messages
• INFO – log information messages
-logging_file – log file name. Messages will be written to this file

4 Simulation Control API
4.1 Overview
The SIM4MEProxy class provides a command execution method to receive control commands
(messages) from a customer simulator that has successfully connected via the bridge. The
customer simulator can use this method to control the SimExec as one of its sub-systems, and
hence create an integrated simulation environment.
4.1.1 Prototype
bool executeSIM4MECommand (
const char* command, const char* args)
4.1.2 Parameters
The command and its arguments are in string format for flexibility. Currently supported
commands and their arguments are listed in the following table. These commands are
designed to allow complete control over the SimExec by an external customer simulator.
Command Argument Description
"ENTER_SLAVE_MODE" <no argument> Command the SimExec into

slave mode.
"EXIT_SLAVE_MODE" <no argument> Command the SimExec out of

slave mode.
Command the SimExec into
"ENTER_SYNC_MODE" <no argument>
sync mode. When in sync mode,
the SimExec will try to release
the synchronization semaphore
(which was locked by the
Simulator Bridge by calling the
simulationSynchronization()
method) at the end of each of its
calculation cycle passes.
"EXIT_SYNC_MODE" <no argument> Command the SimExec out of
sync mode. The SimExec will
not try to signal the Bridge at
the end of each of its calculation
cycle passes.
Change the SimExec speed
"SET_REAL_TIME_RATE" Real Time Rate, for
relative to real “wall clock”
example, “200,”
time. For example if the
“350,” etc.
simulation is running real time,
its real time rate will be “100,”
if it is running at 2 times real

time, its real time rate will be
“200.”
"RUN" <no argument> Command the SimExec into the
running state.
"FREEZE" <no argument> Command the SimExec into the

frozen state.
"SINGLE_STEP" <no argument> Command the SimExec into the

single-step state.
“SAVE_IC” IC file name, for Ask the SimExec to save an IC

example, “ic_no_1” (Initial Condition Snapshot).
“RESTORE_IC” IC file name, for Ask the SimExec to load an IC

example, “ic_no_1” (Initial Condition Snapshot).
“DELETE_IC” IC file name, for Ask the SimExec to delete an

example, “ic_no_1” IC (Initial Condition Snapshot).
“SAVE_BKT” Backtrack number, for Ask the SimExec to save a

example, “1,” “2,” … backtrack snapshot.
“RESTORE_BKT” Backtrack number, for Ask the SimExec to load a

“DELETE_BKT” Backtrack number, for Ask the SimExec to delete a

“CLOSE_SIMULATION” Name of Simulation to Ask the SimExec to save and

save and close close a simulation
4.1.3 Return Value

TRUE on success, FALSE on failure.
4.2 Simulator Operating Mode Control

The SimExec can operate in “normal” or “slave” mode. If a customer simulator intends to drive
the SimExec as one of its sub-systems, it must first send the SimExec an
"ENTER_SLAVE_MODE" command, using the executeSIM4MECommand()method. The
purpose of this command is to instruct the SimExec to turn into slave operation mode.

If the SimExec accepts the slave-mode request, it will return a TRUE enabling the customer
simulator to send other control commands. If the SimExec rejects the mode-changing request, it
will return a FALSE and ignore any future commands from the customer simulator.
When the customer simulator wants to relinquish its control of the SimExec, it should send an
"EXIT_SLAVE_MODE" command with no argument.
The binding-unbinding process described above is carried out in following code sample.
//
// *** Step 1: Create a SIM4ME proxy instance
//
//
// *** Step 2: Start the proxy by connecting to the remote SimExec
// exit if fails
//
//
// *** Step 3: send "ENTER_SLAVE_MODE" message to SimExec
//
if (proxy-> executeSIM4MECommand ("ENTER_SLAVE_MODE", ""))
// send other control commands
// release control when finished
proxy-> executeSIM4MECommand ("EXIT_SLAVE_MODE", "")

}
The following UML state diagram shows how the simulator mode changes upon the
commands that are received.
ENTER SLAVE MODE
Normal Slave Mode

Mode
4.3 Simulation Process

EXITControl
SLAVE MODE
After the SimExec is turned into a slave, its simulation process is under the control of the external
“master” simulator.
The SimExec process can be placed into any of the following modes:
RUNNING The running state means the simulator is processing data and executing the
simulation logic.
FROZEN The frozen state means the simulator isn’t performing any tasks.
SINGLE-STEP The single-step state means the simulator runs for one time step, then freezes
until the next RUN command is received.
The three commands are designed to control the state changes: “RUN,” “FREEZE” and
“SINGLE-STEP.” Each of these commands takes no argument. Their usage is explained in the
examples below:
Run State Example
proxy -> executeSIM4MECommand ("RUN", "")
The simulation process starts to run. If the process is in the SINGLE-STEP state, it would run for
one step and then freeze until next RUN command.
Freeze State Example
proxy -> executeSIM4MECommand ("FREEZE", "")
The simulation process would stop.
Single-Step State Example
proxy -> executeSIM4MECommand ("SINGLE_STEP", "")
The simulation process would toggle between the “FROZEN” and “SINGLE-STEP” states.
The following UML state diagram shows the process state changes.

FREEZE
RUNNING FROZEN
RUN
SINGLE STEP SINGLE STEP
SINGLE-STEP
Simulator Synchronization
4.3.1 Synchronization Time Step

In a united simulation system, simulators are running in parallel. Each piece is allocated a small
period of time to performs it tasks (e.g. calculating data values). This time period is called the
synchronization time step. In a master-slave integration, the synchronization time step of the
slave is determined by the master simulator. The time step should be long enough so that slave
can make reasonable progress in the simulation process (for example, enough data should be
transferred and processed, or model makes meaningful changes, etc).
4.3.2 Synchronization Scheme

The following pseudo-code shows a typical synchronization scheme for synchronization with the
SimExec.
Step–wise Synchronous Operation
The runtime execution control is executed as a series of single step commands, each followed by
a semaphore wait. The wait returns after all SimExecutive and engine processing has completed.
IF Simulator Bridge connects OK, DO:
- Put simulation in slave mode (executeSIM4MECommand ("ENTER_SLAVE_MODE", “”));
- Put simulation in sync mode (executeSIM4MECommand ("ENTER_SYNC_MODE", “”));
- Put SimExec in running state (executeSIM4MECommand ("SINGLE_STEP ", “”));
REPEAT:

- Send simulation data to SimExec;
- Tell the SimExec to complete a step (executeSIM4MECommand ("RUN", ));
- Wait for simulationSynchronization() return;
- Retrieve data from SimExec,
- Process data and execute the simulation logic;
UNTIL termination condition is met.
- Exit sync mode (executeSIM4MECommand ("EXIT_SYNC_MODE", “”));
- Exit slave mode (executeSIM4MECommand ("EXIT_SLAVE_MODE", “”));
The following code sample is a skeleton implementation of the scheme described above.
Note: the data exchange code is omitted from this example.
Public Void goRunMode()
proxy-> executeSIM4MECommand ("ENTER_SYNC_MODE", "");
proxy-> executeSIM4MECommand ("SINGLE_STEP ", "");
Public void stepOnce()
// Do mode check – are we in the correct mode SLAVE + SYNC + SINGLE_STEP
// Send simulation data into SimExec
proxy-> executeSIM4MECommand ("RUN ", "");
// wait for a synchronization time step
proxy->simulationSynchronization();
// retrieve data values from SimExec and process

}
Public void doShutdown()
proxy->executeSIM4MECommand("FREEZE", "");
proxy->executeSIM4MECommand("EXIT_SYNC_MODE", "");
proxy->executeSIM4MECommand("EXIT_SLAVE_MODE", "");
The simulationSynchronization() method locks a local semaphore in the simulation

bridge and waits for the Simulation Executive to release the lock when it has executed one
synchronized time step within it’s own simulation environment.
Continuous Operation
The runtime execution control is achieved by a continuous RUN commend to the SimExec,
interrupted by semaphore wait statements after each step. This means a control thread is kept
alive in the bridge and the simulation master has to communicate with it in a thread safe way (not
illustrated).
IF Simulator Bridge connects OK, DO:
- Put simulation in slave mode (executeSIM4MECommand ("ENTER_SLAVE_MODE", “”));
- Put simulation in sync mode (executeSIM4MECommand ("ENTER_SYNC_MODE", “”));
- Put SimExec in running state (executeSIM4MECommand ("RUN", “”));
REPEAT:
- Send simulation data to SimExec;
- Wait for a synchronization time step;
- Retrieve data from SimExec,
- Process data and execute the simulation logic;
UNTIL termination condition is met.
- Put SimExec in frozen state (executeSIM4MECommand ("FREEZE", “”));

- Exit sync mode (executeSIM4MECommand ("EXIT_SYNC_MODE", “”));
- Exit slave mode (executeSIM4MECommand ("EXIT_SLAVE_MODE", “”));
The following code sample is a skeleton implementation of the scheme described above.
Note: the data exchange code is omitted from this example.
// loop stopper
bool stopped = false;
proxy-> executeSIM4MECommand ("ENTER_SYNC_MODE", "");
proxy-> executeSIM4MECommand ("RUN", "");
while (!stopped)
// Send simulation data into SimExec
// wait for a synchronization time step
proxy->simulationSynchronization();
// retrieve data values from SimExec and process
// check for termination condition, if true, set stopped = true
proxy->executeSIM4MECommand("FREEZE", "");
proxy->executeSIM4MECommand("EXIT_SYNC_MODE", "");
proxy->executeSIM4MECommand("EXIT_SLAVE_MODE", "");
The simulationSynchronization() method locks a local semaphore in the simulation

bridge and waits for the Simulation Executive to release the lock when it has executed one
synchronized time step within its own simulation environment.
Asynchronous Operation
It is possible to communicate with the SimExec using either of the above techniques without
waiting for the simulationSynchronization() call to return.

In this case the execution control will be asynchronous. Asynchronous communication is
appropriate for a small minority of systems where the Simulation master does not include a
scheduler.
4.3.3 Prototype
void simulationSynchronization()
4.3.4 Parameters
None
4.3.5 Return Value

None
This method does not have any arguments and does not return any values. The caller of this
method does not need to know anything about the semaphore. It is recommended that the caller
should implement the synchronization mechanism within a separate thread in the adapter and
manage the frequency of synchronization between the adapter and the Simulation Executive.
4.4 Simulation Snapshot Control

4.4.1 Introduction
In simulation, a “snapshot” is a picture of the state of a simulation engine at a specific
point in time. The purpose of the taking a snapshot is to provide a means to instantly
bring the simulation system back to a desired set of operating conditions. By saving the
operating conditions at any given time, the user can go back to those operating
conditions with a single command.
In the SimExec, there are two kinds of snapshots: initial condition (IC) and backtrack.
The differences between the two depend on the following:
1. How the snapshot is initiated. (An IC is typically triggered by a user action, while a backtrack
is typically triggered by a scheduler that routinely causes a numbered backtrack to be
written.)
2. How the snapshot action affects the simulation process. (Taking an IC switches the
simulation to the FROZEN state, while taking a Backtrack doesn’t change the simulation
state.)
All snapshots are designated by their given names when taken. Usually the name of
backtrack snapshot is an integral number.
Note: The SimExec has a backtrack scheduler that normally saves a backtrack
periodically. The default rate is every minute. However, this backtrack scheduler is
stopped when the SimExec is in slave mode. In this situation, the master simulator must
provide its own backtrack scheduler who issues a SAVE_BKT command periodically.

4.4.2 Saving a Snapshot
Saving a snapshot refers to recording, thus saving, the current status of the simulation.
This electronic snapshot produces an Initial Condition (IC) or a Backtrack (BKT). Both
reflect the current status of all operating parameters, including malfunctions.
The “SAVE_IC” and “SAVE_BKT” commands can be used to trigger a snapshot saving
action in the SimExec. A name for the snapshot must be given as the argument. If a
snapshot with the same name already exists, it will be overwritten.
The following examples show how to save the snapshot as an initial condition (IC) with
name “ic_name” and how to save a backtrack snapshot with number “1001.”
proxy -> executeSIM4MECommand ("SAVE_IC", “ic_name”);
proxy -> executeSIM4MECommand ("SAVE_BKT", “1001”);
4.4.3 Restoring a Snapshot

Restoring a snapshot is the process of resetting a simulation with the values captured by
executing a “SAVE_IC” or “SAVE_BKT” command. The restore commands for this
action are “RESTORE_IC” and “RESTORE_BKT.”
The following example initialized the simulation to the condition of snapshot

“ic_name,”
proxy -> executeSIM4MECommand ("RESTORE_IC", “ic_name”);
This example brings the simulation back to of state when backtrack snapshot 1001 is
taken.
proxy -> executeSIM4MECommand ("RESTORE_BKT", “1001”);
4.4.4 Deleting a Snapshot

Deleting a snapshot refers to removing the actual snapshot file from the system.
The “DELETE_IC” and “DELETE_BKT” commands can be used to trigger a snapshot

deletion action in the SimExec. A name for the snapshot must be given as the argument
for deleting IC’s. In order to delete backtracks, the backtrack number must be provided as
the argument.
The following examples show how to delete the snapshot as an initial condition (IC) with
name “ic_name” and how to delete a backtrack snapshot with number “1001.”
proxy -> executeSIM4MECommand ("DELETE_IC", “ic_name”);
proxy -> executeSIM4MECommand ("DELETE_BKT", “1001”);

4.5 Simulation Speed Control
The speed of a SimExec is the rate at which it advances through simulation time. The rate is
expressed as a percentage of the real “wall clock” time, so the speed is also call the “real time
rate.” For example, if the simulation is running real time, its real time rate will be “100,” if it is
running at 2 times real time, its real time rate will be “200.”
The master simulator may change the SimExec real time rate when it is in the RUNNING state or
FROZEN state, using the “SET_REAL_TIME_RATE” command as shown in this example.
proxy -> executeSIM4MECommand ("SET_REAL_TIME_RATE", “350”);
The argument of this command should represent the rate (“350”). Once the speed is set, the
simulation goes on with the new speed until changed.
Simulation speed is saved within a snapshot (IC or Backtrack), and will be restored to the saved
value if the snapshot is reloaded.
4.6 Close Simulation

Normally when a bridge application exits a simulation the simulation is not saved. The master
simulator may close and save the simulation by using the “CLOSE_SIMULATION” command as
shown in this example:
proxy -> executeSIM4MECommand ("CLOSE_SIMULATION", “test”);
The argument of this command (i.e. –“test”) should be the name of the simulation that was
opened by the bridge application.

5 Data Point API
5.1 Data Point and Point Path
Data Points are basic entities in a simulation system. The Simulator Bridge sees a data point as an
abstract location, storing data that represent a numerical value in the model (e.g. the simulation
time), in a model object (e.g. as a parameter), or at a control point (e.g. as a unit operation).
A data point is uniquely identified by its “path” in the SimExec name space. Generally, the path
is made up of the point name and an optional naming context string in front of it. The “/” sign is
used to separated context and name strings.
Point path = [Context_string/]point_Name
For example, the path of a Foxboro control point can be:
FSIMEngine_name/compound_X:Block_X.point_X
The compound_X:Block_X.point_X string is the name of the point, following the Foxboro
naming convention. The “FSIMEngine_name” is the context of the point in the SimExec
naming space. It is the name of the FSIM engine that controls the point.
If the point name is sufficient to distinguish this point apart from other points in the system, the
context string can be omitted from the path. In the above example, the path of a Foxboro control
point can simply be:
compound_X:Block_X.point_X
5.2 Data Point Types

There are two primary types of data points available: STATIC and DYNAMIC.
A STATIC data point represents a value that cannot be changed while the simulation is running,
therefore it is not saved in Initial Conditions or Backtracks. The value of a static point can only
be changed by reconfiguring the simulation, which is not supported when using the bridge. An
example of a static point is the Tank Wall Thickness parameter of a Tank object.
A DYNAMIC data point represents a value that can be changed while the simulation is running.
The values of dynamic points are saved in Initial Conditions and Backtracks. An example of a
dynamic point is the Tank Fluid Temperature parameter of a Tank object.
The Simulator Bridge provides APIs for accessing and changing the value of a DYNAMIC data
point.
5.3 Individual Data Point Manipulation

The Simulator Bridge provides “accessor method” and “mutator method” for both analog type
and discrete type data points. To be specific, the getAnalogPointValue and
getDiscretePointValue methods access the data values of points, while

setAnalogPointValue and setDiscretePointValue methods change the data values
of points.
5.3.1 Prototypes
bool
setAnalogPointValue(
const analog_value_t value,
const char* pointPath,
const char* uom)
bool
getAnalogPointValue(
analog_value_t& value,
const char* uom)
bool
setDiscretePointValue(
const discrete_value_t value,
const char* uom)
bool
getDiscretePointValue(
discrete_value_t& value,
const char* uom)
5.3.2 Parameters
Argument Type Description
value analog_value_t Data value of the point. For analog value, the
type is analog_value_t; for discrete
34 Data Point API

discrete_value_t point, the type is discrete_value_t.
pointPath const char* The string identification of the data point in

the SimExec.
Uom const char* Unit of measure, volts, feet, degrees, MW, etc.
If the string is empty, it is assumed that the
value is in the internal units of measure.
5.3.3 Return
TRUE on success, FALSE on failure.
Note: Since data can be represented in different types, programming aliases are used for
implementation flexibility. In the current C++ implementation, the data type aliases are
defined in the SIM4MEDataRouter.h header file.
typedef float analog_value_t;
typedef bool discrete_value_t;
5.4 Sample Program – Demonstrating the Data Point API

The following is an example on the usage of data point API. This sample uses the tutorial in the
FSIM Plus Getting Started Guide. The user should consult this guide for details on how to load
this model into the FSIM Plus simulator.
This sample keeps increasing the value of analog point DEMO:B1.POINT and toggling the state
of discrete point DEMO:B3.FBCIN_1.
//-----------------------------------------------------------------------------
#include <iostream>
#include <utilities.h> // msecond(), nap(), not available to customer
#include <SimulatorBridge/Published/SimulatorBridge_exports.h> // DLL import
int main(
int argc,
char* argv[])
int ret = EXIT_SUCCESS; // Return value.

// create a proxy instance
// start the proxy
if (!proxy -> start (argc, argv))
// define the point value holders
analog_value_t a_value = 0.0;
discrete_value_t d_value = 0;
// define the points
const char* analogPointPath = "DEMO:B1.POINT";
const char* uom = "%";
const char* discretePointPath = "FSIMEngine/DEMO:B3.FBCIN_1";
while (true && (a_value <= 40.0)) // Terminate after a few cycles
try
// if get value succeeds, change the value
if (proxy -> getAnalogPointValue (a_value, analogPointPath, uom))
std::cout << "a_value = " << a_value << endl;
a_value += 20;
proxy -> setAnalogPointValue (a_value, analogPointPath, uom);
catch (SIM4ME_CommandException& ex)
36 Data Point API

cout << ex.reason_ << endl;
break;
try
if (proxy -> getDiscretePointValue (d_value, discretePointPath, ""))
std::cout << "d_value = " << (d_value ? "TRUE" : "FALSE") << endl;
d_value = !d_value;
proxy -> setDiscretePointValue (d_value, discretePointPath, "");
catch (SIM4ME_CommandException& ex)
cout << ex.reason_ << endl;
break;
// nap for 1 second
::nap (1000);
proxy -> shutdown ();
// return
return ret;
}Bridge Bulk Data Transfer API

5.5 Introduction
Efficient data transfer among the simulation sub-systems is essential to build a high performance
simulation system. The Simulator Bridge’s SIM4MEDataRouter class supports high-speed,
large volume yet low-cost data transfer. This class achieves the data transfer efficiency in two
ways:
• By bundling the transfer of many values together into a single transfer call.

• By transferring only values that have changed significantly from the last time they
were transferred (this called “updating”).
The SIM4MEDataRouter class is defined in the SIM4MEDataRouter.h header file.
In the following sections, we will cover the fundamental concepts of simulation data transfer,
how to create and configure a router, and the techniques to exchange data between the SimExec
and the router APIs.
5.6 Basic Concepts and Data Structures

For a better understanding of the bridge data transfer API, this section explains some basic
concepts and their programming representation defined in the SIM4MEDataRouther.h header
file.
5.6.1 Information
The SIM4MEDataRouter.h header file defines several data structures to retain the
information about the entities involved in data transfer, such as:
• SimPointInfo – defines a simulation data point
• AnalogPointDataInfo – defines an analog point data
• SIM4ME_AnalogPointDataTransferInfo – provides information about

how to transfer analog data
5.6.2 Data
Data is a re-interpretable representation of information in a formalized (numerical)
manner suitable for communication, interpretation or processing.
In order to transfer data between simulators, the bridge data transfer APIs identify data
using its location and value. The location of data tells where to retrieve or send data,
while the value of the data tells how to use it. Data location is also called point (see
definition below), so data is also called “point data.”
5.6.3 Data Type

Data Type is a set of data units sharing a common representation and operation along with
their associated operations.
Possible data types used in bridge data transfer are: analog, discrete and undefined. These
types are designated in the enumeration SimDataType.
enum SimDataType
ANALOG_DATA,
38 Data Point API

DISCRETE_DATA,
UNDEFINED_DATA
};
5.6.4 Value (Data value)

Value is data that has a data type, i.e. a single occurrence of data and the same occurrence
regardless of representation techniques.
Representation of a value generally makes the difference between data.
In standard C/C++, representation properties of float-point numbers are described in

<float.h> (<cfloat>), where FLT_MAX macro yields the largest finite representable value of
type single-precision float and FLT_MIN macro yields the smallest normalized, finite
representable value of single-precision float.
In the simulation bridge, an analog value is represented as single-precision float. The

following macros are used for implementation flexibility:
#define analog_value_max FLT_MAX
#define analog_value_min FLT_MIN
Value Type
Value type determines the operations that may be performed on a value. For example, analog
double-precision values and analog single-precision values have different rounding
behaviors.
The bridge data transfer API represents analog data values in single-precision float-point
type, and discrete data values in boolean type.
typedef float analog_value_t;
typedef bool discrete_value_t;
Note: Using single-precision float-point value to represent analog data is based on

the fact that the bridge’s primary task is to transfer data and single-precision is
sufficient is most cases.
In most common CPUs, the FPU does all operations internally in an extended precision
(often 80 bits, i.e. long double) unless specifically instructed to use less precision (e.g.,
use an fmuls instruction vs. fmul). In many cases the single, double, and extended
precision operations take the same amount of time (e.g., 1-1-1 clocks per pipeline stage
w/3 stages).
CPUs often can load the float and convert to double for free (in same instruction), and
store double converted to float for free (in same instruction). Therefore using single-
precision or double-precision value in calculating operations costs the same.

However, when dealing with frequent transfer of possible large amounts of data, the
critical issue on modern platforms is memory bandwidth (the memory is considerably
slower than the CPU). Double type value typically takes twice as much memory
bandwidth as float type value. That is, the CPU has to load and store 4 bytes per float into
memory, and 8 bytes per double into memory. Memory bus bandwidth and cache space
being limited, using single-precision floats would transfer faster than double precision
floats.
5.6.5 Point
A point is an abstract location in the simulation environment, which stores data that
represents values.
For the bridge data transfer API, point is the source or destination of data. Data structure
SimPointInfo provides the information about a point.
struct SimPointInfo
char* pointPath;
SimDataType dataType;
char* uom;
long array_number; // Do not modify this value
long point_number; // Do not modify this value
long pointIndex; // Do not modify this value
};
where the pointPath data member tells the bridge where to locate the data, data type
and unit of measure tells the bridge about the nature the data, therefore, how to interpret
the data.
Note:Do not modify the values in array_number, point_ number, and

pointIndex. These values are managed by the SimBridge dll. The value
pointIndex will be unique for every analog value and every discrete value
that is identified by the SimBridge software.
5.6.6 Point Type

A point type is the type of data it represents.
40 Data Point API

5.6.7 Point Data
Two types of point data include analog and discrete, which are defined in following
structures:
Analog data:
struct AnalogPointDataInfo
SimPointInfo* pointInfo;
analog_value_t dataValue;
};
Discrete data:
struct DiscretePointDataInfo
SimPointInfo* pointInfo;
discrete_value_t dataValue;
};
5.7 Configure a SIM4MEDataRouter Object

5.7.1 Overview
Before a data router can be used, it must be configured (i.e. it must be given information
on how to transfer data). The information includes the data properties (point path, data
type, etc), the transfer period (how fast the data is transferred), the tolerance (threshold by
which to re-transfer data), and the data transfer direction (to or from the SimExec), etc.
Router configuration can be done through the specifyDataTransferInfo()

method. It is important that the router be configured before the invoking of method
start ().
5.7.2 Prototype
SIM4MEDataRouter::
specifyDataTransferInfo (
int analogPointNo,
int discretePointNo,

SIM4ME_AnalogPointDataTransferInfo alist[],
SIM4ME_DiscretePointDataTransferInfo dlist[])
5.7.3 Parameters
Argument Type Description
AnalogPointNo* int Number of

analog points in
the following
list – alist
DiscretePointNo* int Number of

discrete points
in the following
list – dlist
Alist SIM4ME_AnalogPointDataTransferInfo[] Analog point

data transfer
information
Dlist SIM4ME_DiscretePointDataTransferInfo[] Discrete point

data transfer
information
Note: Make sure that the analogPointNo and discretePointNo are dynamically calculated
at runtime based on the size of alist and dlist respectively
Data structures SIM4ME_AnalogPointDataTransferInfo and

SIM4ME_DiscretePointDataTransferInfo contain information on how to
transfer analog and discrete data.
5.7.4 Return Value

None
5.7.5 Specify Analog Data Transfer Information

The data router class supports complicated and flexible analog data transfer by allowing
custom calculations and engine specific conversion methods. The specification can be
passed via the SIM4ME_AnalogPointDataTransferInfo structure.
struct SIM4ME_AnalogPointDataTransferInfo
SimPointInfo* SIM4ME_PointInfo;
float period;
42 Data Point API

char* equationString;
analog_value_t tolerance;
char* convMethod;
analog_value_t min_scale;
analog_value_t max_scale;
analog_value_t low_limit;
analog_value_t hi_limit;
bool toSIM4ME;
};
Members in the structure are explained in this table.
Member Type Description
SIM4ME_PointInfo SimPointInfo* Information of the data point in the

SimExec environment.
period float Time interval between two data transfers.
tolerance analog_value_t Value change tolerance, by which to re-

transfer data.
equationString char* Customer calculation equation
convMethod char* Conversion method during data transfer.

This is required for certain control
systems, such as Foxboro I/A Series®
systems. This is a text string that uniquely
identifies the function. Where required,
enter name of conversion type, for
example, “FOXSCI3_16.” For all others,
enter “SIMPLE.”
Min_scale analog_value_t Minimum scale for data value conversion.

For FOXSCI conversion methods other
than thermocouples and RTDs, this value
is used for scaling the converted value to
Raw Counts. This parameter is not used
for FOXSCI thermocouples and RTD
types. For simple conversion types, this

value is used for clipping the output.
Max_scale analog_value_t Maximum scale for data value conversion
low_limit char* Low point at which to clip the data value

at. For FOXSCI conversion methods, this
value is used to clip the value before SCI
conversion. This parameter is NOT used
for SIMPLE conversion methods.
high_limit char* High limit at which to clip the data value.

For FOXSCI conversion types, this value
is used to clip the value before SCI
conversion. This parameter is NOT used
for SIMPLE conversion methods.
toSIM4ME bool Data transfer direction flag: if it is true

then data point is the destination of data
transfer; if it is false data point is the
source of data transfer.
5.7.6 Specify Discrete Data Transfer Information

SIM4ME_DiscretePointDataTransferInfo is the structure used to pass
discrete data transfer information to a data router.
struct SIM4ME_DiscretePointDataTransferInfo
SimPointInfo* SIM4MEPointInfo;
float period;
char* equationString;
char* setCriteria;
float setThreshold;
char* resetCriteria;
float resetThreshold;
char* true_state;
char* false_state;
bool toSIM4ME;
};
44 Data Point API

Members in the structure are explained in this table
Member Type Description
SIM4ME_PointInfo SimPointInfo* Information of the data point in the

SimExec environment.
period float Time interval between two data transfers
equationString char* Customer calculation equation
setCriteria char* Logical test criteria for data setting, should

be one of the following:
"NOT_DEFINED",
"EQUAL",
"NOT_EQUAL",
"LESS_THAN",
"LESS_THAN_OR_EQUAL",
"GREATER_THAN",
"GREATER_THAN_OR_EQUAL"
setThreshold Float Set threshold by which to set the data.
resetCriteria char* Logical test criteria for data resetting,

should be one of the following:
"NOT_DEFINED",
"EQUAL",
"NOT_EQUAL",
"LESS_THAN",
"LESS_THAN_OR_EQUAL",
"GREATER_THAN",
"GREATER_THAN_OR_EQUAL"
resetThreshold Float Reset threshold by which reset the data
true_state char* Interpreting string of the data (signal) in

“TRUE” state. This text description is
usually obtained automatically or manually

from a control system input or listing file.
This is very useful for determining exactly
what the state is and what the threshold
should be if the customer does not supply it.
false_state char* Interpreting string of the data (signal) in

“FALSE” state. This text description is
usually obtained automatically or manually
from a control system input or listing file.
This is very useful for determining exactly
what the state is and what the threshold
should be if the customer does not supply it.
toSIM4ME bool Data transfer direction flag: if it is true then

data point is the destination of data transfer;
if it is false data point is the source of data
transfer.
Note: Unlike analog values, digital values are treated differently based on the direction of
data transfer.
For Discrete Input (toSIM4ME = true), the value is set TRUE (1) when it meets a SET
test, and FALSE (0) when it meets a RESET test. The test results are determined by
setCriteria and setThreshold or resetCriteria and resetThreshold.
For Discrete Output (toSIM4ME = false), the value always comes from the control
system as a TRUE or FALSE.
5.8 Data Router Management API

5.8.1 Creating a SIM4MEDataRouter Object
The SIME4MEProxy class provides a factory pattern method to get an instance of data
router.
5.8.2 Prototype
SIM4MEDataRouter *
getSIM4MEDataRouter()
5.8.3 Parameters
None
5.8.4 Return Value

A reference to a data router object. NULL if no data router created.
46 Data Point API

5.8.5 Starting Data Transfer
The start () method turns on the data flow through the router. It sets up necessary
connection with appropriate targets in the SimExec environment, based on the routing
information given.
5.8.6 Prototype
bool start ()
5.8.7 Parameters
None
5.8.8 Return Value

TRUE if the router starts successfully, FALSE otherwise.
If the start () method returns TRUE, then the router’s “updating methods” can be invoked
to transfer data.
5.8.9 Stopping Data Transfer

The stop () method turns off data flow. It disconnects the communication between the
router and its data transfer targets. After stop () has been called, the router’s
“updating methods” can’t be used to transfer data.
5.8.10 Prototype
void stop ()
5.8.11 Parameters
None
5.8.12 Return Value

None
5.8.13 Sample Code – Router Management

The following code sample shows how to use the router management APIs.
SIM4MEDataRouter * router = 0;

/**
* Create a SIM4ME proxy instance and connect the proxy to the SIM4ME
* environment, if failed, exit
*/
/**
* get a SIM4ME data transfer router from the proxy
*/
router = proxy -> getSIM4MEDataRouter ();
/**
* specify routing info to the router
*/
router ->specifyDataTransferInfo (…);
/**
* start the data transfer
*/
router ->start ();
/**
* Data transfer code goes here …
*/
/**
* stop the data transfer
*/
router ->stop ();
48 Data Point API

}
5.9 Retrieve Data in Bulk

5.9.1 Data Updating API
The bridge’s data router provides data retrieving methods for analog and discrete data.
For efficiency, these methods lump the transfer of many values together into a single
method call, and only transfer data values that have exceeded their tolerance or threshold
since the last time the value was transferred. This means the methods always bring the
caller up to date on the most recent data changing statues. Because of this behavior, these
methods are also called the “updating method.”
5.9.2 Prototypes
AnalogPointDataInfo*
updateAnalogData(int& analogPointNo)
DiscretePointDataInfo*
updateDiscreteData(int& discretePointNo)
5.9.3 Parameters
analogPointNo number of analog points in the return list
discretePointNo number of discrete points in the return list
5.9.4 Return Values

analogPointNo number of analog points in the return list
AnalogPointDataInfo* an array of updated analog point data
discretePointNo number of discrete points in the return list
DiscretePointDataInfo* an array of updated discrete point data
Note: When the methods are called for the first time, all data values are transferred.
5.9.5 Exception Handling

The data updating method is declared without an exception-specification, since the cost
of the run-time check caused by an exception specification is too expensive compared to
the benefit gained.
However, no exception-specification means that the method can throw everything. In

some cases, a developer may need to handle the exceptions raised from the method, but
he would never know what type of exceptions to catch, for they are implementation

specific. (For example, if the data transfer API is implemented using CORBA, then
CORBA::COMM_FAILURE could be thrown by the method.)
To prevent developers from dealing with implementation specific exceptions, the class
SIM4ME_DataTransferException is used to encapsulate the exceptions from the
underlying implementation, such as a CORBA exception, as much as possible:
class SIM4ME_DataTransferException
public:
SIM4ME_DataTransferException (const char* r) : reason_ (r){}
const char* reason_;
};
The data updating method generally tries its best to handle any exception raised during
data transfer. If an exception can’t be handled, it will try to convert it to a
SIM4ME_DataTransferException and throw it to the caller. The caller should
treat the exception as a fatal error and stop using the methods to retrieve data. The
program behavior is undefined if a caller keeps invoking the methods after an exception.
5.9.6 Memory Management

In both analog and discrete updating methods, the memory of the return arrays are allocated using
the new[] operator. The ownership of the memory is handed over to the caller after the methods
return. Therefore, it is the responsibility of the caller to reclaim the memory using the delete[]
operator.
5.9.7 Sample Code – Retrieving Data in Bulk

The code sample below shows how to use the data updating APIs. The code gets updated data
values and displays them on the console. Two things are worth noting in the example below.
1. Once a SIM4ME_DataTransferException exception is caught, the program breaks

out the while loop.
2. At the bottom of the while loop, the memory of the return arrays is freed.
/**
* define receiving handlers
*/
int updatedAnalogPoint = 0;
int updatedDiscretePoint = 0;
50 Data Point API

AnalogPointDataInfo* analogUpdate = 0;
DiscretePointDataInfo* discreteUpdate = 0;
while (true)
/**
* data output from SIM4ME, try to catch exception.
*/
try
// check for analog updates
analogUpdate = router ->updateAnalogData (updatedAnalogPoint);
// check for discrete updates
discreteUpdate = router ->updateDiscreteData (updatedDiscretePoint);
catch (SIM4ME_DataTransferException& ex1)
cerr << "exception during data transfer: " << ex1.reason_ << endl;
break;
/**
* Analog data processing outside of SIM4ME.
* In this example, data is send to consol for display
*/
for (int j = 0; analogUpdate + j, j < updatedAnalogPoint; ++ j)
std::cout << "update Analog j = " << j
<< ": " << analogUpdate[j].pointInfo ->pointPath
<< " -> " << analogUpdate[j].dataValue << endl;

/**
* discrete data processing outside of SIM4ME.
* In this example, data is send to consol for display
*/
for (int i = 0; discreteUpdate + i, i < updatedDiscretePoint; ++ i)
std::cout << "update Discrete i = " << i
<< ": " << discreteUpdate[i].pointInfo->pointPath
<< " -> " << (discreteUpdate[i].dataValue != 0) << endl;
/**
* caller takes the responsibility to reclaim the memory !!
*/
// Clean up data created in SimBridge.dll
router->cleanupAnalogData(analogUpdate);
router->cleanupDiscreteData(discreteUpdate);
/**
* nap for 1 second
*/
::nap (1000);
5.10 Send Data to SIM4ME in Bulk

5.10.1 Data Updating API
A data router provides a single method for sending data to the SimExec. The input provides the
locations of the points and new data values. The bridge will try to transfer them to the destination
based on the information specified.
5.10.2 Prototype
void
updatePointData(
52 Data Point API

const int analogPointNo,
const int discretePointNo,
const AnalogPointDataInfo aValues[],
const DiscretePointDataInfo dValues[])
5.10.3 Parameters
analogPointNo number of analog points in the analog input array
aValues[] input array of analog point data
discretePointNo number of discrete points in the discrete input list
dValues[] input array of discrete point data
5.10.4 Return Value
None
Note: Points with incorrect path or type will be ignored.
5.10.5 Exception Handling

Like data retrieving method, the data sending method generally tries its best to handle
any exception raised during data transfer. If it encounters a fatal error that prevents any
data from being transferred, a SIM4ME_DataTransferException will be thrown.
The caller should treat the exception as a fatal error and stop sending data.
The program behavior is undefined if caller keeps invoking the method after it raises an
exception.
5.10.6 Sample Program – Sending Data in Bulk

The following program shows how to use the data updating APIs. In this case, a simple
control loop of the tank level is simulated. The customer simulator will control the data
transfer between the model variables (DYNSIMEngine) and control points
(FSIMEngine).
Only analog type data is used this example, they are listed the table below.
Model Variable Control Point (FSIM) Description

(DYNSIM)
Tank Level
TCN1.L DEMO:B1.POINT
VCN1.OP DEMO:B2.OUT Valve demand
The control loop is illustrated below.

FSIMEngine DYNSIM Engine
TCN1.L
Sample
DEMO:B1.POINT
Data
transfer
Program
(Customer
DEMO:B2.OUT
VCN1.OP
The steps to run the sample are:
1) Start the SimExec and place it in frozen state
2) Run the RunDataTransferDemo executive
3) Put the SimExec in the running state
4) On the Foxboro Application Workstation, change the output of

DEMO:B2.OUT to manual, and increase the output
5) Note the VCN1.OP value changes in the DOS window – the valve is opened
6) Note the DEMO:B1.POINT value changes on the AW – tank level increases
Note: in the code, the optional engine name (FSIMEngine) is used in the point path.
#include <iostream>
#include <utilities.h> // msecond(), nap()
int main(
int argc,
char* argv[])
54 Data Point API

// Return value.
int ret = EXIT_SUCCESS;
/**
* Create a SIM4ME proxy instance and connect the proxy to the SIM4ME
* environment, if failed, exit
*/
/**
* get a SIM4ME data router from the proxy
*/
SIM4MEDataRouter* router = proxy ->getSIM4MEDataRouter ();
/**
* Specify data transfer information to this router
*/
// analog point number: 2 inputs, 2 outputs
int analogPointNo = 4;
// analog transfer info.
SIM4ME_AnalogPointDataTransferInfo* alist =
new SIM4ME_AnalogPointDataTransferInfo[analogPointNo];
// AI point 1 - DEMO:B1.POINT - FSIM - Tank Level
SimPointInfo* fsim_ai = new SimPointInfo;
fsim_ai->dataType = ANALOG_DATA;
fsim_ai->pointPath = const_cast<char*> ("FSIMEngine/DEMO:B1.POINT");
fsim_ai->uom = const_cast<char*> ("FEET");

SIM4ME_AnalogPointDataTransferInfo *ainfo = &alist [0];
ainfo ->SIM4ME_PointInfo = fsim_ai;
ainfo ->period = 0.25;
ainfo ->equationString = const_cast<char*> ("");
ainfo ->tolerance = 0.002f;
ainfo ->convMethod = const_cast<char*> ("FOXSCI3_16");
ainfo ->hi_limit = 10.f;
ainfo ->low_limit = -0.2f;
ainfo ->max_scale = 10.0f;
ainfo ->min_scale = 0.0f;
ainfo ->toSIM4ME = true;
// AI point 2 - VCN1.OP - DYNSIM - Valve demand
SimPointInfo* asc_ai = new SimPointInfo;
asc_ai->dataType = ANALOG_DATA;
asc_ai->pointPath = const_cast<char*> ("VCN1.OP");
asc_ai->uom = const_cast<char*> ("%");
ainfo = &alist [1];
ainfo ->SIM4ME_PointInfo = asc_ai;
ainfo ->convMethod = const_cast<char*> ("SIMPLE");
ainfo ->low_limit = 0.f;
ainfo ->toSIM4ME = true;
// AO point 1 - DEMO:B2.OUT - FSIM - Valve demand
SimPointInfo* fsim_ao = new SimPointInfo;
56 Data Point API

fsim_ao->dataType = ANALOG_DATA;
fsim_ao->pointPath = const_cast<char*> ("FSIMEngine/DEMO:B2.OUT");
fsim_ao->uom = const_cast<char*> ("%");
ainfo = &alist [2];
ainfo ->SIM4ME_PointInfo = fsim_ao;
ainfo ->toSIM4ME = false;
// AO point 2 - TCN1.L - DYNSIM - Tank Level
SimPointInfo* asc_ao = new SimPointInfo;
asc_ao->dataType = ANALOG_DATA;
asc_ao->pointPath = const_cast<char*> ("TCN1.L");
asc_ao->uom = const_cast<char*> ("FEET");
ainfo = &alist [3];
ainfo ->SIM4ME_PointInfo = asc_ao;

ainfo ->toSIM4ME = false;
/**
* Discrete point info, not point in this demo
*/
int discretePointNo = 0;
SIM4ME_DiscretePointDataTransferInfo* dlist = 0;
/**
* specify point info to the router
*/
router ->specifyDataTransferInfo ( analogPointNo,
discretePointNo,
alist,
dlist);
/**
* start the data transfer router
*/
router ->start ();
/**
* begin to exchange data with the router
*/
int updatedAnalogPoint = 0;
int updatedDiscretePoint = 0;
AnalogPointDataInfo* analogUpdate = 0;
DiscretePointDataInfo* discreteUpdate = 0;
while (true)
/**
* data output from SIM4ME
*/
58 Data Point API

try
// check for analog updates
analogUpdate = router ->updateAnalogData (updatedAnalogPoint);
// check for discrete updates
discreteUpdate = router ->updateDiscreteData (updatedDiscretePoint);
break;
/**
* build the analog data value input list to SIM4ME
*/
AnalogPointDataInfo* aValues =
new AnalogPointDataInfo[updatedAnalogPoint];
/**
* Analog data processing outside of SIM4ME. In this example, input
* values will be changed based on output data values from SIM4ME
*/
for (int j = 0; analogUpdate + j, j < updatedAnalogPoint; ++ j)
std::cout << "update Analog j = " << j
<< ": " << analogUpdate[j].pointInfo ->pointPath
<< " -> " << analogUpdate[j].dataValue << endl;
aValues[j].pointInfo = analogUpdate[j].pointInfo;
aValues[j].dataValue = analogUpdate[j].dataValue;
// DEMO:B2.OUT -> VCN1.OP !!

if (!strcmp ("DEMO:B2.OUT", aValues[j].pointInfo ->pointPath))
aValues[j].pointInfo = asc_ai;
// TCN1.L -> DEMO:B1.POINT !!
if (!strcmp ("TCN1.L", aValues[j].pointInfo ->pointPath))
aValues [j].pointInfo = fsim_ai;
/**
* build the analog data value input list to SIM4ME
*/
DiscretePointDataInfo* dValues =
new DiscretePointDataInfo[updatedDiscretePoint];
/**
* discrete data processing outside of SIM4ME. In this example, input
* values will be changed based on output data values from SIM4ME
*/
for (int i = 0; discreteUpdate + i, i < updatedDiscretePoint; ++ i)
/**
* data transfer into SIM4ME (after processing)
*/
try
60 Data Point API

router ->updatePointData(
updatedAnalogPoint,
updatedDiscretePoint,
aValues,
dValues);
break;
/**
* caller takes the responsibility to reclaim the memory
*/
// Clean up data created in SimBridge.dll
router->cleanupAnalogData(analogUpdate);
router->cleanupDiscreteData(discreteUpdate);
// Clean up data that was created by user
delete[] aValues;
delete[] dValues;
/**
* nap for 1 second
*/
::nap (1000);
/**
* stop the data transfer router
*/
router ->stop ();

// shutdown
proxy ->shutdown ();
// return
return ret;
62 Data Point API

6 Simulator Action Capture
6.1 Introduction
The SIM4ME simulation system has the capability to capture operator actions for later replay
from certain engines that run in it. The engines will write operator actions to an interface on the
simulation executive and they are then recorded to a log file. This record and replay is part of the
basic functionality of SIM4ME. If a bridge application wishes to record the operator actions in his
own log file, an interface has been set so that the bridge developer can register a function to
record the operator actions and so that he can replay the operator actions at the time of his
choosing.
Currently the Simulation Executive is capable of recording operator actions from an FSIM Plus
application, from a TRISIM Plus application that is using Wonderware In-Touch GUI as the
Operator Input station , or any other engine that supports the scenario recording interface
(logEngineAction and performEngine). The Simulation Executive will also record malfunction
activations and deactivations from the SIM4ME Instructor station GUI.
The record descriptions for the operator actions are:
// Malfunction Records
// Time of Day,Simulation Time, MALFUNCTION, Command, customer, Simulation, System,

Malfunction Number
// Trisim Records
// Time of Day,Simulation Time, TRISIM Plus, Engine Name, Point Name Value
// INTOUCH Records
// Time of Day,Simulation Time, INTOUCH, Engine Name, New Window
// Engine Records - i.e FSIM Plus
// Time of Day,Simulation Time, action name, Engine Name, action
//
6.2 Register Function to Capture Operator Actions

The bridge developer can reroute the operator actions so that the bridge can record them. This can
be done by registering a function pointer to the SIM4ME proxy object. To register the function
pointer the developer needs to call the registerCallback method. An example on how to register a
function is given below:
// Define a function pointer that is a void function and takes a

character string input

typedef void(*pt2Func)(char*);
static void testcallback(char* str)
… Capture code goes here …
/**
* Create a SIM4ME proxy instance
*/
// start the target simulation and connect the proxy
// to the SIM4ME environment, if failed, exit
if (remoteStart && !proxy->remoteStart (argc, argv))
// connect the proxy to the SIM4ME environment, if failed, exit
else
// Set up callback from SimExecutive
pt2Func function = &testcallback;
proxy->registerCallbackFunc(function);
64 Simulator Action Capture

6.3 Replay Operator Actions
To replay the operator actions the bridge developer sends the records that he received from the
Simulation Executive back to the SimExecutive at the proper time. Each record that was received
was time stamped with both the actual date and time the action was taken as well as the
simulation time that the action was taken. The record should not be altered from the way that it
was received. The Simulation Executive will not do any time checking. It will play the records as
they are received back from the bridge. The method to replay the record is called
replayLogEntry(char* replayrecord). An example on how to use this method is shown below:
char *record = /* Get this record from somewhere where it was saved by bridge application
….
proxy-> replayLogEntry(record);

7 Scenarios in the Simulator Bridge
7.1 Overview
The Simulator Bridge Development Kit (SBDK) allows the user to create and control SIM4ME
scenarios. The Scenario tool in SIM4ME allows the user to save a sequence of actions, such as
starting a pump, activating a malfunction, or setting a demand, to a file that can be edited.
Scenarios are more fully explained in the Dynamic Simulation Suite User guide.
7.2 Class Layout
7.3 SIM4MEScenarioProxy Object

The SIM4MEScenarioProxy object is the main object that controls scenario handling in a bridge
application. This object is used to create and delete individual scenarios as well as instantiating
listeners which are called whenever a scenario changes state. The bridge user obtains this object
by calling the getSIM4MEScenarioProxy() method in the SIM4MEProxy object. The
SIM4MEScenarioProxy object consists of 12 methods which are described below:
7.3.1 Get all Scenarios
This method will return a list of all scenarios found in a given simulation.
Prototype
ScenarioList getAllScenarios(const char* simulation, long& count)
Parameters
1) const char* simulationName – The name of the simulation that you wish to retrieve
scenarios for.
2) long& count – Numbers of ScenarioData objects returned from

method

Return Value
A list of ScenarioData objects. A ScenarioData object is defined by the following

structure:
struct ScenarioData
/* Simulation that the Scenario belongs to */
char* simulation;
/* Id of the Scenario */
long scenarioID;
/* Name of the scenario */
char* scenarioName;
/* Name of the scenario's author */
char* authorName;
/* Description of the scenario */
char* description;
/* Whether scenario is protected from editing */
bool isProtected;
/* Date and time of scenario creation */
char* creationDate;
/* UserID of the scenario author */
char* authorID;
/* Is the scenario currently active */
bool isActive;
};
7.3.2 Get Scenario

This method retrieves a scenario object for the given scenarioID, which will be used to
perform operations such as activating, deactivating, saving, etc.

Prototype
Scenario* getScenario(long scenarioID)
Parameters
long scenarioID – The ID number of the scenario that you wish to manipulate.
Return Value
The return value for this method is a scenario object which will
be described further in later sections of this document.
7.3.3 Create Scenario

This method creates a new scenario and inserts it into the scenario database.
Prototype
void createScenario(ScenarioData scenData, const char* scenarioScript)
Parameters
ScenarioData scenData – Data defining the scenario
const char* scenarioScript – scenario script of the scenario
Return Value
None
7.3.4 Delete Scenario

This method deletes a scenario from the scenario database.
Prototype
void deleteScenario(long scenarioID)
Parameters
long scenarioID – The ID number of the scenario that you wish to delete.
Return Value
None
7.3.5 Add a Scenario Listener

This method attaches a scenario listener object to the scenario manager. The listener object
will be informed by the scenario manager whenever a scenario is activated, deactivated, is

saved, is deleted, or when the status of a scenario changes. The bridge user creates his
scenario listener object by creating a class that is derived from the SIM4MEScnearioListener
object found in the SIM4MEScenarioProxy.h found in the toolkit.
Prototype
Void addScenarioListener(SIM4MEScenarioListener* listener)
Parameters
SIM4MEScenarioListener* listener – This object is created by the user to capture

scenario events. This object has following seven methods associated with it:
1. void scenarioActivated(long scenarioID)
Notifies this listener when the scenario has been activated.
param: scenarioID IN: unique ID of the scenario
2. void scenarioStatusChanged (const ActiveScenarioData &activescenData)
Notifies this listener when active scenario status has changed.
param: activescenData IN: data related to active scenario
3. void scenarioDeactivated(long scenarioID)
Notifies this listener when the scenario has been deactivated.
param: scenarioID IN: unique ID of the scenario to track
4. void scenarioSaved(const ScenarioData &scenData)
Notifies this listener when the scenario has been saved.
param: scenData IN:data defining the scenario
5. void scenarioDeleted(long scenarioID)
Notifies this listener when the scenario has been deleted.
param: scenarioID IN: unique ID of the scenario
6. long getListenerID()
Gets the listener id.
returns: unique ID of the listener
7. void setID(long id)

Set the client ID
Return Value
None
7.3.6 Remove a Scenario Listener

This method removes a scenario listener from the Scenario Manager Object
Prototype
void removeScenarioListener(long listenerID)
Parameters
long listenerID – The ID number of the scenario listenerID you wish to remove
Return Value
None
7.3.7 Get Next ID

This method returns the ID number for the next available scenario.
Prototype
long getNextID()
Parameters
None
Return Value
The next available ID number
7.3.8 Set Record Mode

This method set the scenario record mode for the SIM4ME Simulation Executive.
Prototype
void setRecordMode(const char* mode)
Parameters
Mode – Mode can either be ON or OFF

Return Value
None
7.3.9 Get Record Mode

This method set the scenario record mode for the SIM4ME Simulation Executive.
Prototype
char* getRecordMode()
Parameters
None
Return Value
Mode can either be ON or OFF
7.3.10 Save Recording

This method saves the recorded actions as a scenario.
Prototype
bool saveRecording(ScenarioData scenData)
Parameters
ScenarioData - Scenario data structure used to configure the scenario in the scenario
database
Return Value
Mode can either be ON or OFF.
7.3.11 Add a Playback Listener

This method attaches a scenario listener object to the scenario manager. The listener object
will be informed by the scenario manager whenever the record mode in the scenario is
changed. The bridge user creates his scenario listener object by creating a class that is derived
from the SIM4MEScnearioListener object found in the SIM4MEScenarioProxy.h found in
the toolkit.
Prototype
void addPlaybackListener(SIM4MEPlaybackListener* listener)

Parameters
SIM4MEPlaybackListener* listener – This object is created by the user to capture

scenario playback events. This object has following method associated with it:
1) void recordModeChanged(const char* recordMode)
Notifies this listener when the record mode is changed
param: recordMode - record mode of the simulaiton
Return Value
None
7.3.12 Remove a Playback Listener

This method removes a playback listener from the Scenario Manager Object
Prototype
void removePlaybackListener(SIM4MEPlaybackListener* Listener)
Parameters
SIM4MEPlaybackListener* Listener – The playbacklistener object to remove from

scenario mananger control
Return Value
None
7.4 Scenario Object

The Scenario object is the object that controls a specific SIM4ME scenario. A Scenario object is
retrieved by call methods on the SIM4MEScenarioProxy object which manages all the scenarios
in a simulation. The Scenario object consists of 13 methods which are described below:
7.4.1 Run Scenario
This method runs the scenario.
Prototype
void runScenario( const char* userName )
Parameters
Const char* userName – The username to display while running the scenario

Return Value
None
7.4.2 Stop Scenario

This method stops running scenario.
Prototype
void stopScenario()
Parameters
None
Return Value
None
7.4.3 Pause Scenario

This method pauses a running scenario.
Prototype
void pauseScenario()
Parameters
None
Return Value
None
7.4.4 Resume Scenario

This method resumes a paused scenario.
Prototype
void resumeScenario()
Parameters
None
Return Value
None

7.4.5 Save Scenario
This method resaves the scenario given the scenario data structure and a scenario script.
Prototype
void saveScenario(ScenarioData scenData,const char* scenarioScript)
Parameters
1) ScenarioData scenData - Scenario data structure used to configure the

scenario in the scenario database
2) const char* scenarioScript – A string that defines a scenario

script for the scenario
Return Value
None
7.4.6 Load Scenario

This method returns the scenario script for editing.
Prototype
char* loadScenario()
Parameters
None
Return Value
Returns the scenario script as a string
7.4.7 Get Active Scenario Data

This method returns the active scenario data as defined by a
ActiveScenarioData structure.
Prototype
ActiveScenarioData getActiveScenarioData()
Parameters
None

Return Value
Returns the following data structure which defines the active scenario data:
struct ActiveScenarioData
/* Id of the scenario */
long scenarioID;
/* Status of the active scenario */
char* status;
};
7.4.8 Get Scenario ID

This method returns the unique ID of the scenario.
Prototype
long getScenarioID()
Parameters
None
Return Value
Returns the unique ID of the scenario
7.4.9 Get Scenario Name

This method returns the name of the scenario.
Prototype
char* getScenarioName()
Parameters
None
Return Value
Returns the name of the scenario

7.4.10 Scenario Active
This method returns true if the scenario is active
Prototype
bool isActive()
Parameters
None
Return Value
Returns true is scenario is active.
7.4.11 Scenario Paused

This method returns true if the scenario is paused.
Prototype
bool isPaused()
Parameters
None
Return Value
Returns true is scenario is paused.
7.4.12 Set Run Mode

This method sets the run mode for the scenario.
Prototype
void setRunMode (SCE_RUN_MODE mode)
Parameters
SCE_RUN_MODE mode
The mode modes for scenarios are as follows:
SCENARIO – Normal Scenario mode
PLAYBACK – Scenario is playback mode

Return Value
None
7.4.13 Get Run Mode

This method gets the run mode for the scenario.
Prototype
SCE_RUN_MODE getRunMode()
Parameters
None
Return Value
SCE_RUN_MODE

8 Malfunctions in the Simulator Bridge
8.1 Overview
The Simulator Bridge Development Kit (SBDK) has been extended to allow the user to create
and control SIM4ME malfunctions. A Malfunction is defined as an unexpected, abnormal
occurrence. For example, a valve that does not operate as commanded. The Malfunction tool in
SIM4ME allows the user to define, delete, activate, and deactivate malfunctions found in the
SIM4ME dynamic simulation. Malfunctions are more fully explained in the Dynamic Simulation
Suite User guide.
8.2 Class Layout
8.3 SIM4MEMalfunctionProxy Object

The SIM4MEMalfunctionProxy object is the main object that controls malfunction handling in a
bridge application. This object is used to create and delete individual malfunctions as well as
instantiating listeners which are called whenever a malfunction changes state. The bridge user
obtains this object by calling the getSIM4MEMalfunctionProxy() method in the SIM4MEProxy
object. The SIM4MEMalfunctionProxy object consists of 17 methods which are described below:
8.3.1 Get GetMalfunctionable objects
This method retrieves a list of malfunctionable objects given the engine name. If the engine
name is blank then a list of all the malfunctionable objects for the engine is returned.
Prototype
MalfuctionableObjectsList getMalfunctionableObjects(const char*
enginename, long& count)
Parameters
const char* engineName The name of the engine from which to retrieve
malfunctions

long& count count of malfunctionable objects found
Return Value
A list of MalfunctionableObjects. A MalfunctionableObject is defined by the following

structure:
struct MalfunctionableObjects
/* engine that model object is in */
char* modelObjectEngine;
/* model object name */
char* modelObjectName;
};
8.3.2 Get New Client List ID

This method obtains a new unique client list ID. The implementation maintains a static, ever
incrementing, "nextID" which returns the incremented next ID. This method must be called
before any of the following methods are called on this object.
Prototype
long getNewListClientID()
Parameters
None
Return Value
Unique ID number
8.3.3 Get Number of Malfunctions

This method gets the number of malfunctions in a list built of the specified criteria. The
criteria to build the list includes the customer, simulation, system, pre-defined and/or
active.
This method builds and caches the malfunction list into a vector indexed from 0, to size-1,
where size is returned from this method. The cache is not rebuilt until this method is called
again (either with different, or the same criteria). For each unique listClientID, this method
implements an independent cached malfunction list.

Prototype
long
getNumMalfunctions( const char* system,
bool includePreDefined,
bool includeActive,
long listClientID)
Parameters
const char* system Name of system, if this string is an empty string, then the list
will include all malfunctions in the entire simulation
bool includePreDefined If true, predefines will be included in the list, if false, they will
not
bool includeActive If true, active malfunctions will be included in the list.
Long listClientID unique client id, used to identify the list built for the specific
client
Return Value
size of the list built, and cached
8.3.4 Get Malfunction Data from Cached List

This method obtains the data structure that defines the malfunction of the given index in the
cached list built by a previous call to getNumMalfunctions.
Prototype
MalfunctionData*
getMalfunctionDataFromCachedList(long index,long listClientID)
Parameters
long index Index number into the cached list
long listClientID ID of the list client, used to determine which cached list to
look in for the returned malfunction data
Return Value
Returns the Malfunction data structure which is defined as:
struct MalfunctionData

{
/* system that the malfunction belongs to */
char* system;
/* number of malfunction */
long number;
/* type of malfunction 0=analog, 1=discrete */
bool type;
/* description of the malfunction */
char* description;
/* failure mode ID */
long failureModeID;
/* delay flag */
bool delayFlag;
/* delay time */
float delayTime;
/* mature value (analog only) */
double matureValue;
/* low limit (analog only) */
double lowLimit;
/* high limit (analog only) */
double highLimit;
/* mature state (discrete only) */
long matureState;
/* engage flag (analog only) */
bool engageFlag;
/* engage rate (analog only) */

double engageRate;
/* disengage flag (analog only) */
bool disengageFlag;
/* disengage rate (analog only) */
double disengageRate;
/* oscillation flag (analog only) */
bool oscFlag;
/* oscillation type (analog only) */
long oscType;
/* oscillation amplitude type (analog only) */
long oscAmpType;
/* oscillation amplitude (analog only) */
double oscAmp;
/* oscillation period (analog only) */
float oscPeriod;
/* chatter flag (discrete only) */
bool chatFlag;
/* chatter on time (discrete only) */
float chatOnTime;
/* chatter off time (discrete only) */
float chatOffTime;
/* is there a set trigger */
bool setTriggerFlag;
/* the equation used to trigger the malfunction */
char* setTriggerEquationString;
/* is there a reset trigger */
bool resetTriggerFlag;
/* the equation used to reset the malfunction */

char* resetTriggerEquationString;
/* is this malfunction currently active */
bool isActive;
};
8.3.5 Get Status of Malfunctions

This method returns the status of malfunctions in Cached List.
Prototype
MalstatusList* getMalStatus(long listClientID, long& count)
Parameters
long listClientID ID of the list client, used to determine which cached list
to look in
long& count Count of items returned in MalstatusList
Return Value
Returns a list of Malstatus structures. These structures are defined as:
struct Malstatus
char* moName;
long status;
};
8.3.6 Create a malfunction object

Create a malfunction object performs operations on the malfunction data, such as activation
or saving as pre-defined.
Prototype
Malfunction* getMalfunction(MalfunctionData malfData)
Parameters
MalfunctionData A malfunction data structure

Return Value
Returns a Malfunction object that the user can operate on.
8.3.7 Create a malfunction object from Predefined

This object performs operations on the malfunction data, such as activation or saving as pre-
defined malfunction.
Prototype
Malfunction* getMalfunctionFromPredefined(MalfunctionData
malfData)
Parameters
MalfunctionData A malfunction data structure
Return Value
8.3.8 Release a Malfunction

Releases the malfunction defined by the unique malfunction ID.
Prototype
Void releaseMalfunction(long id)
Parameters
Long id The unique ID for the malfunction
Return Value
None
8.3.9 Get Active Malfunction

Returns an active malfunction based on its name.
Prototype
Malfunction* getActiveMalfunction(char* malfName)
Parameters
char* malfName The malfunction name.

Return Value
8.3.10 Get Failure Modes

This method obtains the list of all possible failure modes for the given name. The name
will identify an instance of a "Malfunctionable" object in one of the simulation engines.
The implementation of this method searches all attached simulation engines, until the
malfunctionable name is found, then returns the information from that object.
Prototype
FailureModeInformation* getFailureModes(const char*
malfunctionableName)
Parameters
char* malfunctionableName Name of the malfunctionable object
Return Value
Returns failure mode information. The following structure defines the failure mode
information.
struct FailureModeInformation
/* model object class */
char* modelObjectClass;
/* model object description */
char* modelObjectDesc;
/* number of analog failure modes */
long num_analog_failures;
/* list of analog failure modes */
AnalogFailureModeList anaFailureModes;

/* number of discrete failure modes */
long num_discrete_failures;
/* list of discrete failure modes */
DiscreteFailureModeList disFailureModes;
};
The definitions for the AnalogFailureModeList and DiscreteFailureModeList can be

found in the SIM4MEMalfunctionProxy.h file found in the SBDK.
8.3.11 Get Data from Predefined Malfunction

Returns the data associated with a specific pre-defined malfunction, given by the unique
number of the malfunction.
Prototype
MalfunctionData* getPreDefined(const char* system,long malfNumber)
Parameters
System Name of system (optional, if left blank, the entire simulation
will be searched for the malfunction). Note that the
malfunction number for a pre-defined is unique within the
simulation, not the system.
malfNumber Unique malfunction number
Return Value
Returns the Malfunction data structure.
8.3.12 Is There a Predefined Malfunction

Returns true if there is a predefined matching the specification.
Prototype
bool isTherePreDefined(const char* system, long malfNumber)
Parameters
will be searched for the malfunction) Note that the

Return Value
Returns true if there is one – false if there is not
8.3.13 Delete Predefined Malfunction

Deletes the pre-defined malfunction from the database.
Prototype
void deletePreDefined(const char* system,long malfNumber)
Parameters
will be searched for the malfunction) Note that the
Return Value
None
8.3.14 Get Next Predefined Malfunction Number

Get the next available malfunction number.
Prototype
long getNextPreDefinedMalfNumber()
Parameters
None
Return Value
The next available malfunction number.
8.3.15 Add a Malfunction Listener

This method attaches a malfunction listener object to the malfunction manager. The listener
object is informed by the malfunction manager whenever a malfunction is activated,
deactivated, saved, deleted, or when the status of a malfunction changes. The bridge user
creates his malfunction listener object by creating a class that is derived from the

SIM4MESMalfunctionListener object found in the SIM4MEMalfunctionProxy.h found in the
ToolKit.
Prototype
Void addMalfunctionListener(SIM4MEMalfunctionListener* listener);
Parameters
SIM4MEMalfunctionListener * listener This object is created by the user to
capture malfunction events. This
object has following 7 methods
associated with it:
Return Value
None
8.3.16 Remove a Malfunction Listener

This method removes a scenario listener from the Malfunction Manager Object
Prototype
void removeMalfunctionListener(long listenerID)
Parameters
long listenerID The ID number of the malfunction listenerID you
wish to remove
Return Value
None
8.3.17 Deactivate all Malfunctions

This method deactivates all active malfunctions
Prototype
void deactivateAll()
Parameters
None
Return Value
None

8.4 Malfunction Object
The Malfunction object is the object that controls a specific SIM4ME malfunction. A malfunction
object is retrieved by call methods on the SIM4MEMalfunctionProxy object which manages all
the malfunctions in a simulation. The Malfunction object consists of ten methods which are
described below.
8.4.1 Set Initial Data
This method sets the initialization data for the malfunction.
Prototype
void setInitData(MalfunctionData* malfData)
Parameters
MalfunctionData malfdata This structure is used to define the malfunction to
the SIM4ME system.
Return Value
None
8.4.2 Get Initial Data

This method gets the initialization data for the malfunction.
Prototype
MalfunctionData* getInitData()
Parameters
MalfunctionData malfdata This structure is used to define the malfunction to
the SIM4ME system.
Return Value
None
8.4.3 Save Predefined Data

This method saves the current initialization data as a predefined.
Prototype
void savePredefined()

Parameters
None
Return Value
None
8.4.4 Load Predefined Data

This method loads the predefined data into the current malfunction
Prototype
Void loadPreDefined(const char* system,long malfNumber)
Parameters
* const char* system system (optional)
* long malfNumber predefined malfunction number
Return Value
None
8.4.5 Activate Malfunction

This method activates the malfunction.
Prototype
void activate()
Parameters
None
Return Value
None
8.4.6 Deactivate Malfunction

This method deactivates the malfunction.
Prototype
void deactivate()

Parameters
None
Return Value
None
8.4.7 Is Malfunction Active

This method returns whether or not the malfunction is active or not.
Prototype
bool isActive()
Parameters
None
Return Value
Returns true if the malfunction is active and false if is not.
8.4.8 Get Active Malfunction Data

This method returns the active malfunction data.
Prototype
ActiveMalfunctionData* getActiveMalfunctionData()
Parameters
None
Return Value
Returns the active malfunction data structure.
struct ActiveMalfunctionData
/* status */
long status;

/* delay time remaining */
float delayTimeRemaining;
/* current analog state */
double currentAnalogState;
/* current discrete state */
long currentDiscreteState;
/* current discrete state */
char* currentDiscreteStateLabel;
8.4.9 Get ID
This method returns the malfunction ID.
Prototype
long getID()
Parameters
None
Return Value
The malfunction ID.
8.4.10 Get Name

This method returns the name of the malfunction.
Prototype
char* getName()
Parameters
None
Return Value
The malfunction name

9 TPMs in the Simulator Bridge
9.1 Overview
The Simulator Bridge Development Kit (SBDK) has been extended in version 5.1 to allow the
user to create and control SIM4ME Training Performance Monitoring (TPM) exercises. One of
the distinct applications of a dynamic simulation package is as an Operator Training Simulator.
Here, the instructor uses a simulated version of the process plant and trains the operators in
operating the simulated process plant. The instructor, using a simulator, can trigger critical
scenarios of start-ups, shut-downs and emergency failures, and malfunctions to train
inexperienced operators on safe and efficient plant operations. This interface to Training
Performance Monitoring allows the SimBridge User to have access to all the functions of the
SIM4ME training monitoring system.
9.2 Class Layout
Exercise
setNumber
getNumber
setDescription
getDescription
setICNum
getICNum
setStudent
getStudent
setScoringEquation
getScoringEquation
SIM4METPMProxy setScore
getScore
getExercise setComment
getAllExercises getComment
getNumExercisesAll setTrends
getNumExercisesAllUsers getTrends
getNumExercisesConfig setStartTime
getNumExercisesUser getStartTime
getExerciseRow 1:n setStopTime
addConfigExercise setStopTime n
addRunExercise setDuration
deleteExercise getDuration
releaseExercise setTPRDate
getMaxTPRNum getTPRDate
tprExists setDynamicPointList
getNumActiveExercises getDynamicPointList
getActiveExerciseRow addConfigPoint
addActiveExercise deleteConfigPoint
removeActiveExercise setConfigPointList
exportToCSVFile
getConfigPointList
getResults
start
stop
save
saveAs
getTPRID
getIDNumber
getNumPoints
getConfigRow
getDynamicRow
setInstructor
getInstructor
9.3 SIM4METPMProxy Object

The SIM4METPMProxy object is the main object that controls TPM handling in a bridge
application. This object is used to create and delete individual TPM exercises. The bridge user

obtains this object by calling the getSIM4METPMProxy() method in the SIM4MEProxy object.
The SIM4MEPMProxy object consists of 18 methods which are described below:
9.3.1 Get Exercise object
This method retrieves an exercise object given the customer name, simulation name, and the
exercise ID number. The customer name should be “customer” by default.
Prototype
Exercise*
getExercise(
const char* customer,
const char* simulation,
const long number)
Parameters
• customer - The customer name should be “customer” by default.
• simulation – The simulation name
• number – TPR number
Return Value
A pointer to the Exercise object.
9.3.2 Get All Exercises

This method obtains a list of all the exercises in the simulation.
Prototype
ExerciseItem*
getAllExercises(
long& count)
Parameters
customer - The customer name should be “customer” by default.
simulation – The simulation name

Return Values
count – count of all exercises
A list of all the Exercises in the simulation
The structure for an ExerciseItem is as follows:
struct ExerciseItem
/* exercise number */
long number;
/* exercise description */
char* description;
/* student name */
char* student;
/* date */
char* tprDate;
/* start time */
double startTime;
/* stop time */
double stopTime;
/* duration */
double duration;
/* unique tpr id */
long tprId;
/* instructor Name */
char* instructor;
};

9.3.3 Get Number of All Exercises
This method returns the number of all exercises in a simulation.
Prototype
long
getNumExercisesAll(
const char* simulation)
Parameters
Return Value
Number of all exercises
9.3.4
9.3.5 Get Number of All Exercises for all Users

This method returns the number of all exercises in a simulation for all Users
Prototype
long getNumExercisesAllUsers(
Parameters
Return Value
Number of all exercises for all Users
9.3.6 Get Number of all Configured exercises

This method returns the number of all configured exercises

Prototype
long
getNumExercisesConfig (
Parameters
Return Value
Number of all configured exercises
9.3.7 Get the number of exercises for one user

This method returns the number of exercises for one particular user.
Prototype
long
getNumExercisesUser (
const char* user)
Parameters
• user – The user name
Return Value
Number of all configured exercises for a particular user.
9.3.8 Get Exercise at a specified index

This object retrieves at a specified index.

Prototype
ExerciseItem*
getExerciseRow( const long index)
Parameters
index – Index to retrieve ExerciseItem at.
Return Value
Returns an ExerciseItem object
9.3.9 Create an exercise in a simulation

This method will create an exercise in the simulation
Prototype
Exercise*
addConfigExercise(
const long number,
const char* desc,
const char* icnum,
const char* student,
const long eqid,
const char* comments,
const char* trends,
const char* instructor)
Parameters
• number – The exercise number
• desc – The exercise description

• icnum – The IC to be loaded with the exercise
• student – The student name
• eqid – The ID of the scoring equation to use
• comments – Comments for the Exercise
• trends – Trends to be associated with exercise
• instructor – instructor name
Return Value
Pointer to the exercise object
9.3.10 Add a new run TPR Exercise

Adds a new run TPR exercise
Prototype
Exercise*
addRunExercise(
const long number,
const char* desc,
const char* icnum,
const double starttime,
const double stoptime,
const double duration,
const char* student,
const double score,
const long eqid,
const char* comments,
const char* instructor) = 0;

Parameters
• desc – The exercise description
• icnum – The IC to be loaded with the exercise
• starttime – The TPR start time
• stoptime – The TPR stop time
• duration – The TPR duration
• student – The student name
• score – The student score
• eqid – The ID of the scoring equation to use
• comments – Comments for the Exercise
• instructor – instructor name
Return Value
Pointer to the exercise object
9.3.11 Delete a TPR Exercise

This method deletes a TPR exercise given the TPR number.
Prototype
bool
deleteExercise(
const long number)
Parameters

Return Value
Returns true if successful.
9.3.12 Release a TPR Exercise

This method releases a TPR exercise given the TPR number.
Prototype
void
releaseExercise(
const long number)
Parameters
number – The exercise number
Return Value
None
9.3.13 Gets the MAX number used for TPMs

This method will return the maximum number used for TPM Ids.
Prototype
long
getMaxTPRNum(
Parameters

Return Value
Maximum number used
9.3.14 Does a TPR Exist

Returns true if a TPR exists for a given ID.
Prototype
bool
tprExists(
const long number)
Parameters
Return Value
Returns true if there is one – false if there is not
9.3.15 Return number of active exercises

This method returns the number of active exercises.
Prototype
long getNumActiveExercises()
Parameters
Index – Row number
Return Value
Number of active exercises

9.3.16 Return Active Exercise for a given row
This method will return the active exercise given its row number.
Prototype
ActiveExerciseItem*
getActiveExerciseRow(const long index)
Parameters
Index – index number for active exercise
Return Value
An ActiveExerciseItem object
struct ActiveExerciseItem
/* exercise number */
long number;
/* student name */
char* student;
/* unique id */
long id;
/* index */
long index;
};
9.3.17 Add an Active Exercise

This method will add an active exercise to the list of active erercises.
Prototype
void addActiveExercise(const ActiveExerciseItem activeExercise)
Parameters
activeExecise – An ActiveExerciseItem structure.

Return Value
None
9.3.18 Remove an Active Exercise

This method removes an active exercise from the list of active exercises.
Prototype
void removeActiveExercise(const long tprid)
Parameters
tprid – the id number for the acvie exercise
Return Value
None
9.3.19 Export an exercise to a .csv file

This method will export an exercise to a .csv file.
Prototype
void
exportToCSVFile(
const long TPRId,
const char* fileName)
Parameters
• TPRId – The exercise number
• filename – full file spec for output file
Return Value
None

9.4 Exercise Object
The Exercise object is the object that controls a specific SIM4ME Training Performance exercise.
An exercise object is retrieved by call methods on the SIM4METPMProxy object which manages
all the training exercises in a simulation. The Exercise object consists of forty-two methods which
are described below.
9.4.1 Set TPR number for an Exercise
This method sets the TPR number for an exercise.
Prototype
void setNumber( const long number )
Parameters
number – tpr number
Return Value
None
9.4.2 Get TPR number for an Exercise

This method gets the TPR number for an exercise.
Prototype
Long getNumber();
Parameters
None
Return Value
The TPR number for an exercise
9.4.3 Set Description for an Exercise

This method sets the description for an exercise.
Prototype
void setDescription(const char* description)
Parameters
description

Return Value
None
9.4.4 Get Description for an Exercise

This method gets the description for an exercise.
Prototype
char* getDescription()
Parameters
None
Return Value
The description for an exercise
9.4.5 Set IC number for an Exercise

This method sets the IC Number for an exercise.
Prototype
void setICNum( const char* icnum)
Parameters
IC Number
Return Value
None
9.4.6 Get IC Number for an Exercise

This method gets the description for an exercise.
Prototype
char* getICNum()
Parameters
None
Return Value
The IC number for an exercise

9.4.7 Set Student Name for an Exercise
This method sets the student name for an exercise.
Prototype
void setStudent(const char* student)
Parameters
Student name
Return Value
None
9.4.8 Get Student Name for an Exercise

This method gets the student name for an exercise.
Prototype
char* getStudent()
Parameters
None
Return Value
The student name for an exercise
9.4.9 Set Scoring Equation for an Exercise

This method sets the scoring equation for an exercise.
Prototype
Void setScoringEquation( const long scoringEquation)
Parameters
ScoringEquation – The scoring equation number for the exercise
Return Value
None
9.4.10 Get Student Name for an Exercise

This method gets the scoring equation number for an exercise.

Prototype
Long getScoringEquation()
Parameters
None
Return Value
The scoring equation number for an exercise
9.4.11 Set Score for an Exercise

This method sets the score for an exercise.
Prototype
void setScore(const double score)
Parameters
The exercise score
Return Value
None
9.4.12 Get Score for an Exercise

This method gets the score for an exercise.
Prototype
double getScore()
Parameters
None
Return Value
The score for an exercise
9.4.13 Set Comments for an Exercise

This method sets the comments for an exercise.
Prototype
void setComment(const char* comment)

Parameters
The exercise comments
Return Value
None
9.4.14 Get Comments for an Exercise

This method gets the comments for an exercise.
Prototype
char* getComment()
Parameters
None
Return Value
The comments for an exercise
9.4.15 Set Trends for an Exercise

This method sets the trends for an exercise.
Prototype
void setTrends(const char* trends)
Parameters
The exercise trends
Return Value
None
9.4.16 Get Comments for an Exercise

This method gets the trends for an exercise.
Prototype
char* getTrends()
Parameters
None

Return Value
The trends for an exercise
9.4.17 Set the Start Time for an Exercise

This method sets the start time for an exercise.
Prototype
void setStartTime(const double startTime)
Parameters
The exercise start time
Return Value
None
9.4.18 Get Start Time for an Exercise

This method gets the start time for an exercise.
Prototype
double getStartTime()
Parameters
None
Return Value
The start time for an exercise
9.4.19 Set the Stop Time for an Exercise

This method sets the stop time for an exercise.
Prototype
void setStopTime(const double stopTime)
Parameters
The exercise stop time
Return Value
None

9.4.20 Get Stop Time for an Exercise
This method gets the stop time for an exercise.
Prototype
double getStopTime()
Parameters
None
Return Value
The stop time for an exercise
9.4.21 Set the Duration Time for an Exercise

This method sets the duration time for an exercise.
Prototype
void setDuration(const double duration)
Parameters
The exercise duration time
Return Value
None
9.4.22 Get Duration Time for an Exercise

This method gets the duration time for an exercise.
Prototype
double getDuration()
Parameters
None
Return Value
The duration time for an exercise
9.4.23 Set the TPR Date for an Exercise

This method sets the TPR Date when executed for an exercise.

Prototype
void setTPRDate(const char* tprDate)
Parameters
The exercise TPR date when executed
Return Value
None
9.4.24 Get TPR Date for an Exercise

This method gets the TPR Date when executed for an exercise.
Prototype
char* setTPRDate()
Parameters
None
Return Value
The exercise TPR date when executed for an exercise
9.4.25 Set the list of Dynamic points for an Exercise

This method sets the list of Dynamic points for an exercise.
Prototype
void setDynamicPointList(const long count,
DynamicPointItem** theList)
Parameters
• count – the number of dynamic points in the list
• theList – A list of DynamicPointItems
struct DynamicPointItem
/* name of point */
char* name;

/* minimum limit */
double minLimit;
/* maximum limit */
double maxLimit;
/* time of high excursion */
double highTime;
/* time of low excursion */
double lowTime;
/* number of high excursions */
long highExc;
/* number of low excursions */
long lowExc;
/* highest value reached */
double highVal;
/* lowest value reached */
double lowVal;
/* point score */
double score;
/* index */
long index;
/* weight of the point */
double weight;
/* score based on scoring algorithm 1 */
double score1;
double score2;
double score3;

double score4;
/* area of high excursions */
double highArea;
/* area of low excursions */
double lowArea;
/* min deviation allowed */
double minDev;
/* maximum deviation allowed */
double maxDev;
/* maximum time out of limits */
double maxTime;
/* max limit point name */
char* max_limit_point;
/* min limit point name */
char* min_limit_point;
long boundsFail;
double failTime;
};
Return Value
None
9.4.26 Get the list of Dynamic Points for an Exercise

This method gets the list of Dynamic Points for an exercise.
Prototype
DynamicPointItem* getDynamicPointList(long& count) = 0;
Parameters
None

Return Value
count – The count of dynamic points in the list
The list of dynamic points
9.4.27 Add a Config Point for an Exercise

This method adds a ConfigPoint for an exercise.
Prototype
bool addConfigPoint(const ConfigPointItem configPoint)
Parameters
ConfigPointItem
struct ConfigPointItem
/* name of point */
char* name;
/* minimum limit */
double minLimit;
/* maximum limit */
double maxLimit;
/* index */
long index;
/* weight of the point */
double weight;
/* min deviation allowed */
double minDev;
/* maximum deviation allowed */
double maxDev;
/* max limit point name */

char* max_limit_point;
/* min limit point name */
char* min_limit_point;
/* fail if outside HH or LL */
bool bounds_fail;
};
Return Value
True if successful – false if not
9.4.28 Delete a Config Point for an Exercise

This method deletes a point for an exercise.
Prototype
DynamicPointItem* getDynamicPointList(long& count) = 0;
Parameters
None
Return Value
• count – The count of dynamic points in the list
• The list of dynamic points
9.4.29 Set the list of Config points for an Exercise

This method sets the list of Config points for an exercise.
Prototype
void setConfigPointList(const long count,
ConfigPointItem** theList)
Parameters
• count – the number of dynamic points in the list
• theList – A list of ConfigPointItems
Return Value
None

9.4.30 Get the list of Config Points for an Exercise
This method gets the list of Config Points for an exercise.
Prototype
ConfigPointItem* getConfigPointList(long& count)
Parameters
None
Return Value
• count – The count of Config points in the list
• The list of Config points
9.4.31 Get the Results for an Exercise

This method gets the results for an exercise.
Prototype
void getResults()
Parameters
None
Return Value
None
9.4.32 Start the Exercise

This method starts the exercise.
Prototype
bool start()
Parameters
None
Return Value
True if exercise is started

9.4.33 Stop the Exercise
This method stops the exercise.
Prototype
bool stop()
Parameters
None
Return Value
True if exercise is stopped
9.4.34 Save the Exercise

This method saves the exercise.
Prototype
bool save()
Parameters
None
Return Value
True if exercise is saved
9.4.35 Save the Exercise to another number

This method saves the exercise to another TPR number.
Prototype
bool saveAs(const long newNumber)
Parameters
newNumber – The new number to save the TPR to.
Return Value
True if exercise is saved
9.4.36 Get unique ID for a TPR

This method gets unique number for a TPR

Prototype
long getTPRID()
Parameters
None
Return Value
The unique number for the TPR
9.4.37 Get the ID Number for an Exercise

Get the unique id number associated with this TPR exercise. This number will be referenced
for deleting the exercise.
Prototype
long getIDNumber()
Parameters
None
Return Value
The id number
9.4.38 Get the number of points for an Exercise

This method gets the number of points for an exercise.
Prototype
long getNumPoints()
Parameters
None
Return Value
The number of points in the exercise
9.4.39 Get Config Point at Specified Index

This method gets the Config point at the specified row index

Prototype
• ConfigPointItem
• getConfigRow(const long index)
Parameters
Index – Row index
Return Value
The Config point at the index
9.4.40 Get Dynamic Point at Specified Index

This method gets the Dynamic point at the specified row index
Prototype
• DynamicPointItem
• getDynamicRow(const long index)
Parameters
Index – Row index
Return Value
The Dynamic point at the index
9.4.41 Set the Instructor for an Exercise

This method sets the Instructor for an exercise.
Prototype
void setInstructor(const char* instructor)
Parameters
The exercise instructor
Return Value
None
9.4.42 Get Instructor for an Exercise

This method gets the instructor for an exercise.

Prototype
char* getInstructor()
Parameters
None
Return Value
The instructor for an exercise

10 Simulator Bridge Development Kit
10.1 Overview
The Simulator Bridge Development Kit (SBDK) is the software package for developing the
bridge integration applications. It contains the necessary runtime environment, library, and
include files that are used by the compiler, linker and application programs.
This section describes the files and directories in the SBDK. The following chart shows the
organization of directories on the Windows platforms:
$SBDK_ROOT
+--- bin (bridge runtime)
+--- demo (demonstration)
+--- doc (documentation)
+-- include
| |
| +-- SimulatorBridge
| |
| +-- Published (header files)
+--- lib (lib file)
$SBDK_ROOT is the root directory of the SBDK software installation, for example, C:\Program
Files\SIMSCI\SimulatorBridge. It contains copyright, license, and README files.

This table describes the contents of each folder under $SBDK_ROOT and how they should be
used to setup a development environment.
Folder name Description Usage
Doc Documentation directory
Bin The simulator bridge (front-end) On Windows platform, the PATH

runtime environment on Windows environment variable should contain an
platform. On Solaris, this folder is entry for this directory.
empty
include
Header files declaring the The compiler’s include searching path
should contain an entry for this folder or
Simulator Bridge APIs the compiler should use it as an
additional search path within /I
Lib Library file for linking with the The LIB should contain an entry for this
simulator bridge libraries folder or the linker should use it with
/LIBPATH option
10.2 Runtime Environment
10.2.1 Simulator Bridge Front-end

On Windows platform, the Simulator Bridge software front-end is made up of several
DLLs, each providing some essential services. These files are installed under the
$SBDK_ROOT \bin\SimBridge directory. They are briefly described below.
DLL file name Description Service provided
SimBridgeEngine.dll The Simulator Bridge front The concrete implementation

end of SIM4MEProxy and
SIM4MEDataRouter classes
SimCorbaConfig.dll CORBA platform support The CORBA distributed

computing services
SimEngineToolkit.dll SIM4ME communication The data transfer service

infrastructure inside SimExec
Util_SimUtilities.dll SIM4ME application Include messaging services,

utilities etc.
UOMServerLib.dll UOM conversion UOM conversion services.

application

10.2.2 Third Party Runtime Support
Third party software needed by the Simulator Bridge runtime is also installed under the
$SBDK_ROOT \bin directory.
DLL file name Description Service provided
ACE.dll ACE ORB (TAO) high-performance

libraries. CORBA runtime
TAO.dll support.
TAO_Svc_Utils14.dll
TAO_CosNaming14.dll
TAO_IORTable14.dll
TAO_PortableServer14.dll
TAO_CodeSet14.dll
TAO_CosNaming14.dll
TAO_CosNaming_Serv14.dll
TAO_CosNaming_Skel14.dll
TAO_IORMessaging14.dll
TAO_Valuetype14.dll
pthreadVCE.dll POSIX thread library POSIX thread support
Note: CORBA is used extensively through the SimSci dynamic simulation solution. It is
also the underlying platform on which the Simulator Bridge is built. The Simulator Bridge
front-end and servant find each other through CORBA naming service, and exchange
messages and data via CORBA RPC mechanism. However, the bridge software package
encapsulates the CORBA specific implementation, so the user does not need to know
CORBA to use the bridge.
10.3 Library Files
For the Windows platform, SimBridgeEngine.dll has the concrete implementation of the
SIM4MEProxy and SIM4MEDataRouter classes. To use these classes in an application, the
SimBridge.lib, under directory $SBDK_ROOT\lib, must be linked to resolve the load
address of the classes.

The SimBridge.lib file should be given to the linker. In Visual C++, add the
SimBridgeEngine.lib name to the project Setting dialog box, on the Link tab, under
General category, in the Object/Library Modules edit field.
The $SBDK_ROOT\lib directory path should be added to the linker search path: $LIB
(Windows). Another approach is to give the directory path to linker as an additional library path,
for instance, in Visual C++, add the lib file name to the project Setting dialog box, on the Link
tab, under Input category, in the Additional Library Path edit field.
10.4 Header Files
The $SBDK_ROOT\include directory contains headers files that declare the Simulator Bridge
APIs (SIM4MEProxy.h and SIM4MEDataRouter.h interfaces), which should be included in the
application source code. Also, there is a SimulatorBridge_exports.h file that enables the customer
application import functions, data, and objects to and from a DLL.
The $SBDK_ROOT\include should be put in the compiler’s include search path. An example
of how the application program can include the files is:
#include <SimulatorBridge/Published/SIM4MEDataRouter.h>
#include <SimulatorBridge/Published/SIM4MEMalfunctionProxy.h>
#include <SimulatorBridge/Published/SIM4MEScenarioProxy.h>
#include <SimulatorBridge/Published/SIM4METPMProxy.h>
#include <SimulatorBridge/Published/SimulatorBridge_exports.h>
Header file name Defined
SIM4MEProxy.h The SIM4MEProxy classes
SIM4MEDataRouter.h The SIM4MEDataRouter class and other data

transfer structures
SIM4MEMalfunctionProxy.h The SIM4MEMalfunctionProxy class and other

data structures needed to do malfunctions
SIM4MEScenarioProxy.h The SIM4MEScenarioProxy class and other data

structures needed to do scenarios
SIM4METPMProxy.h The SIM4METPMProxy class and other data

structures needed to control TPMs.

10.5 Demonstration Files
The $SBDK_ROOT\SimBridgeDemo directory contains sample code that demonstrates the use
of the Simulator Bridge development kit. In this directory and the it’s windows sub-directory the
user will find eight projects that demonstrate the use of different aspects of the developer’s kit.
The user can build the demonstration executables by running the Microsoft project files found in
the windows sub-directory. A sample SIM4ME simulation file (SBtest.s4m) and a batch
command file (SB_ControlDemo.bat) is also included in the SimBridgeDemo directory to drive
the demonstration code. The user will need to slightly modify the batch command file so that it
will run on his system.
The following nine executables demonstrate the following features in the Simulator Bridge:
1) DataTransferDemo – This demo shows how to send and receive data to a SIM4ME
application using a SIM4MEDataRouter object. This program connects to a running
simulation.
2) RetrieveDataDemo – This demo shows how to receive data from a running SIM4ME
application using a SIM4MEDataRouter object. This program connects to a running
simulation.
3) SendDataDemo – This demo shows how to send data to a running SIM4ME application
using a SIM4MEDataRouter object. This program connects to a running simulation.
4) SetDataValueDemo – This demo shows how to send and receive data to a simulation
using the get and set methods on the simulation proxy object. This program connects to a
running simulation.

5) SIM4MEControlDemo – This demo shows how to control a simulation (i.e. – run, pause,
take/load snapshots, set simulation speed) using the SIM4ME proxy object. This
program also demonstrates how to open and start a simulation using program control.
6) SyncronizationDemo – This demo shows the user how to make synchronization calls on
the simulation proxy object. The program connects to a running simulation
7) MalfunctionDemo – The demo shows how to make calls to SIM4ME proxy object to
retrieve the SIM4MEMalfunctionProxy object. Once this object is retrieved then the user
can make calls to control malfunctions in the simulation. Like the
SIM4MEControlDemo, this demo opens and starts a simulation.
8) ScenarioDemo – The demo shows how to make calls to the SIM4ME proxy object to
retrieve the SIM4MEScenarioProxy object. Once this object is retrieved then the user
can make calls to control scenarios in the simulation. Like the SIM4MEControlDemo,
this demo opens and starts a simulation.
9) TPMDemo – The demo shows how to make calls to the SIM4ME proxy object to
retrieve the SIM4METPMProxy object. Once this object is retrieved then the user can
make calls to control TPM exercises in the simulation. Like the SIM4MEControlDemo,
this demo opens and starts a simulation.

Appendix A – FOXSCI Conversion Methods
SCI means “Signal Conditioning Indexes.” Each SCI index specifies a particular conversion
algorithm that converts the FBM raw count data value to a real floating-point value in the
specified engineering units span.
The standard names for the conversion functions used by ESSCOR is FOXSCI<nn>_<tt> where
<nn> is the SCI value contained in the block’s definition and <tt> is the data type associated with
the I/O point. Allowable data types are FL, 16, and 32, for floating-point, 16-bit integer, and 32-
bit integer, respectively.
For example, if SCI = 3 (Linear 12800 to 64000 raw counts), the FOXSCI methods name can be:
• “FOXSCI3_FL” for float-point value
• “FOXSCI3_16” for 16-bit integer value
• “FOXSCI3_32” for 32-bit integer value
Do not attempt to manually generate the list of SCI conversion types for FSIM Plus. Instead, use
the automatic cross reference generation tool found within the DYNSIM GUI that is a
prerequisite install for FSIM Plus. The FSIM Plus Getting Start Guide provides a demonstration
that includes creating a dummy process model, loading controls, and generating the cross
reference list. Export the Cross Reference list and merge it into the simulator bridge application.

Simulator Bridge Developers Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Simulator Bridge Developers Guide

Uploaded by

Copyright:

Available Formats

AVEVA™ DYNSIM Dynamic Simulation

Simulator Bridge Developer’s Guide

2 ARCHITECTURE OVERVIEW ................................................................................... 3

2.1 SIMSCI DSS SIMULATION ENVIRONMENT ...................................................................... 3

2.2 INTEGRATION STRATEGY .............................................................................................. 4

2.3 BRIDGE SOFTWARE STRUCTURE .................................................................................... 5

3 BRIDGE MANAGEMENT APIS .................................................................................. 7

3.1 CREATION ..................................................................................................................... 7

3.1.1 Prototype ............................................................................................................... 7

3.1.2 Parameters ............................................................................................................. 7

3.1.3 Return Value .......................................................................................................... 7

3.2 STARTUP ....................................................................................................................... 7

3.2.1 Prototype ............................................................................................................... 7

3.2.2 Parameters ............................................................................................................. 7

3.2.3 Return Value .......................................................................................................... 7

3.3 REMOTE STARTUP ......................................................................................................... 8

3.3.1 Prototype ............................................................................................................... 8

3.3.2 Parameters ............................................................................................................. 8

3.3.3 Return Value .......................................................................................................... 8

3.4 SHUTDOWN ................................................................................................................... 9

3.4.1 Prototype ............................................................................................................... 9

3.4.2 Parameters ........................................................................................................... 10

3.4.3 Return Value ........................................................................................................ 10

3.5 REMOTE SHUTDOWN ................................................................................................... 10

3.5.1 Prototype ............................................................................................................. 10

DYNSIM Simulator Bridge Developer’s Guide TOC-I

3.5.3 Return Value ........................................................................................................ 10

3.6 GET SIMEXEC MODE ................................................................................................... 10

3.6.1 Prototype ............................................................................................................. 10

3.6.2 Parameters ........................................................................................................... 10

3.6.3 Return Value ........................................................................................................ 10

3.7 ENABLE CLIENT MESSAGES......................................................................................... 11

3.7.1 Prototype ............................................................................................................. 11

3.7.2 Parameters ........................................................................................................... 11

3.7.3 Return Value ........................................................................................................ 11

3.8 DISABLE CLIENT MESSAGES........................................................................................ 11

3.8.1 Prototype ............................................................................................................. 11

3.8.2 Parameters ........................................................................................................... 12

3.8.3 Return Value ........................................................................................................ 12

3.9 GETPASTMESSAGES .................................................................................................... 12

3.9.1 Prototype ............................................................................................................. 12

3.9.2 Parameters ........................................................................................................... 12

3.9.3 Return Value ........................................................................................................ 12

3.10.1 Prototype ............................................................................................................. 12

3.10.2 Parameters ........................................................................................................... 12

3.11 SIM4ME EVENT LOG CONTROL............................................................................... 13

3.11.1 Prototype ............................................................................................................. 13

3.11.2 Parameters ........................................................................................................... 13

3.11.3 Return Value ........................................................................................................ 13

SIM4ME REPORT CLIENT MESSAGES OBJECT ....................................................................... 13

3.12.1 Source Code ......................................................................................................... 14

3.12.2 Building the Sample Program Using Visual C++ ................................................. 15

3.12.3 Building the Demo Program Using Visual C++ ................................................... 18

3.13 LOGGER ................................................................................................................... 19

4 SIMULATION CONTROL API .................................................................................. 21

4.1 OVERVIEW .................................................................................................................. 21

4.1.1 Prototype ............................................................................................................. 21

4.1.2 Parameters ........................................................................................................... 21

4.1.3 Return Value ........................................................................................................ 22

4.2 SIMULATOR OPERATING MODE CONTROL ................................................................... 22

4.3 SIMULATION PROCESS CONTROL ................................................................................. 24

4.3.1 Synchronization Time Step.................................................................................... 25

4.3.2 Synchronization Scheme ....................................................................................... 25

4.3.3 Prototype ............................................................................................................. 29