Edition 11/2022

FUNCTION MANUAL

SIMATIC
S7-1500
S7-PLCSIM Advanced

support.industry.siemens.com
 Introduction
1

Safety instructions
2

SIMATIC Product overview

3

S7-PLCSIM Advanced Installing

4

Function Manual
Communication paths
5

Simulating
6

Virtual time response

7

User interfaces (API)

8

Restrictions, messages and

solution
9

List of abbreviations
A

11/2022
A5E37039512-AE
Legal information
Warning notice system
This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent
damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert
symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are
graded according to the degree of danger.

DANGER
indicates that death or severe personal injury will result if proper precautions are not taken.

WARNING
indicates that death or severe personal injury may result if proper precautions are not taken.

CAUTION
indicates that minor personal injury can result if proper precautions are not taken.

NOTICE
indicates that property damage can result if proper precautions are not taken.
If more than one degree of danger is present, the warning notice representing the highest degree of danger will
be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to
property damage.
Qualified Personnel
The product/system described in this documentation may be operated only by personnel qualified for the specific
task in accordance with the relevant documentation, in particular its warning notices and safety instructions.
Qualified personnel are those who, based on their training and experience, are capable of identifying risks and
avoiding potential hazards when working with these products/systems.
Proper use of Siemens products
Note the following:

WARNING
Siemens products may only be used for the applications described in the catalog and in the relevant technical
documentation. If products and components from other manufacturers are used, these must be recommended or
approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and
maintenance are required to ensure that the products operate safely and without any problems. The permissible
ambient conditions must be complied with. The information in the relevant documentation must be observed.

Trademarks
All names identified by ® are registered trademarks of Siemens AG. The remaining trademarks in this publication
may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.
Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and software
described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the
information in this publication is reviewed regularly and any necessary corrections are included in subsequent
editions.

Siemens AG A5E37039512-AE Copyright © Siemens AG 2016 - 2022.

Digital Industries Ⓟ 10/2022 Subject to change All rights reserved
Postfach 48 48
90026 NÜRNBERG
GERMANY
Table of contents

1 Introduction........................................................................................................................................ 10
1.1 Function Manuals documentation guide........................................................................... 12
1.1.1 Information classes Function Manuals............................................................................... 12
1.1.2 Basic tools........................................................................................................................ 13
1.1.3 SIMATIC Technical Documentation.................................................................................... 15

2 Safety instructions.............................................................................................................................. 17
2.1 Security information......................................................................................................... 17

3 Product overview ............................................................................................................................... 18

3.1 What is S7-PLCSIM Advanced? .......................................................................................... 18
3.2 S7-PLCSIM products.......................................................................................................... 19
3.3 Compatibility in case of updates........................................................................................ 20
3.4 Security for S7-PLCSIM Advanced...................................................................................... 22
3.5 Support simulation........................................................................................................... 23
3.6 Supported CPUs................................................................................................................ 24
3.7 Differences between a simulated and a real CPU................................................................ 25
3.7.1 Restrictions for all supported CPUs.................................................................................... 26
3.7.2 Notes............................................................................................................................... 27
3.8 Password to protect confidential configuration data.......................................................... 28

4 Installing............................................................................................................................................. 31
4.1 Introduction..................................................................................................................... 31
4.1.1 System requirements........................................................................................................ 31
4.1.2 Restrictions due to antivirus programs .............................................................................. 32
4.1.3 Licenses............................................................................................................................ 34
4.1.4 Trial License...................................................................................................................... 34
4.1.5 Installation log.................................................................................................................. 36
4.2 S7-PLCSIM Advanced ........................................................................................................ 37
4.3 Installing S7-PLCSIM Advanced.......................................................................................... 37
4.4 Changing S7-PLCSIM Advanced......................................................................................... 39
4.5 Repairing S7-PLCSIM Advanced......................................................................................... 39
4.6 Uninstalling S7-PLCSIM Advanced..................................................................................... 40

S7-PLCSIM Advanced
4 Function Manual, 11/2022, A5E37039512-AE
 Table of contents

5 Communication paths........................................................................................................................ 42
5.1 Local communication ....................................................................................................... 43
5.2 Communication via TCP / IP............................................................................................... 44
5.2.1 Communication via TCP/IP in Multi-Adapter Network Mode (non-promiscuous mode)........ 47
5.3 Enable distributed communication ................................................................................... 54

6 Simulating.......................................................................................................................................... 57
6.1 Simulate CPU.................................................................................................................... 57
6.1.1 Basic procedure for the simulation.................................................................................... 57
6.1.2 Control Panel - User interface............................................................................................ 58
6.1.2.1 S7-PLCSIM Advanced Symbol............................................................................................ 58
6.1.2.2 Graphical interface............................................................................................................ 59
6.1.2.3 S7-PLCSIM Advanced Control Panel................................................................................... 59
6.1.2.4 Importing instances.......................................................................................................... 64
6.1.3 Downloading a STEP 7 project........................................................................................... 66
6.1.4 Network addresses in the simulation................................................................................. 69
6.1.4.1 Siemens PLCSIM Virtual Ethernet Adapter.......................................................................... 69
6.1.4.2 PLCSIM Advanced instances.............................................................................................. 70
6.1.5 Simulate peripheral I/O..................................................................................................... 72
6.1.6 Simulate communication.................................................................................................. 72
6.1.6.1 Communication services that can be simulated................................................................. 72
6.1.6.2 Communication between instances................................................................................... 74
6.1.7 Provide project data offline for simulation ........................................................................ 74
6.2 Simulate CPU with ODK functionality................................................................................. 76
6.2.1 Special features of ODK..................................................................................................... 76
6.2.2 Loading functions ............................................................................................................ 79
6.2.3 Calling functions............................................................................................................... 80
6.2.4 Unloading functions......................................................................................................... 80
6.3 Simulating Motion Control................................................................................................ 81
6.4 Simulating the SIMATIC Drive Controller............................................................................ 83
6.5 Simulating a redundant S7-1500R/H system...................................................................... 84

7 Virtual time response......................................................................................................................... 87

7.1 Speed up and slow down simulation................................................................................. 88
7.2 Stop simulation................................................................................................................. 90
7.3 Synchronize simulation partner......................................................................................... 92
7.3.1 Synchronize simulation partner cycle-controlled................................................................ 92
7.3.2 Synchronize simulation partner time-controlled................................................................ 96

8 User interfaces (API)........................................................................................................................... 98

8.1 Introduction..................................................................................................................... 98
8.1.1 Access to instances........................................................................................................... 99
8.1.2 Interfaces of the Simulation Runtime................................................................................. 100
8.1.3 Overview of user interfaces for native C++........................................................................ 101
8.1.4 Overview of user interfaces for managed code ................................................................. 105
8.1.5 Overview of data types for native C++............................................................................... 108
8.1.6 Overview of data types for managed code......................................................................... 110

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 5
Table of contents

8.2 Initialize API ..................................................................................................................... 111

8.2.1 Load API library................................................................................................................. 111
8.2.2 Native C++ ....................................................................................................................... 112
8.2.2.1 InitializeApi() ................................................................................................................... 112
8.2.2.2 RuntimeApiEntry_Initialize................................................................................................ 113
8.2.3 .NET (C#).......................................................................................................................... 114
8.2.3.1 Initialize ........................................................................................................................... 114
8.3 Shut down API.................................................................................................................. 115
8.3.1 Native C++........................................................................................................................ 115
8.3.1.1 DestroyInterface()............................................................................................................. 115
8.3.1.2 RuntimeApiEntry_DestroyInterface.................................................................................... 116
8.3.1.3 FreeApi().......................................................................................................................... 116
8.3.1.4 ShutdownAndFreeApi().................................................................................................... 117
8.3.2 .NET (C#).......................................................................................................................... 118
8.3.2.1 Shut down API ................................................................................................................. 118
8.4 Global functions (Native C++)........................................................................................... 118
8.5 API ISimulationRuntimeManager....................................................................................... 123
8.5.1 Interfaces - Information and settings................................................................................. 123
8.5.2 Simulation Runtime instances........................................................................................... 132
8.5.3 Remote connections......................................................................................................... 138
8.5.3.1 RunAutodiscover()............................................................................................................ 142
8.5.4 Events for ISimulationRuntimeManager............................................................................. 143
8.5.4.1 OnSoftwareConfigurationChanged events......................................................................... 143
8.5.4.2 OnRuntimeManagerLost events........................................................................................ 146
8.5.4.3 OnAutodiscoverData events.............................................................................................. 148
8.6 API IInstances................................................................................................................... 149
8.6.1 Interfaces - Information and settings................................................................................. 149
8.6.2 Controller - Information and settings................................................................................. 153
8.6.3 Operating state ................................................................................................................ 163
8.6.4 Tag list.............................................................................................................................. 172
8.6.5 I/O access......................................................................................................................... 177
8.6.5.1 Synchronizing inputs and outputs..................................................................................... 177
8.6.5.2 I/O access via address - Reading......................................................................................... 178
8.6.5.3 I/O access via address - Writing.......................................................................................... 183
8.6.5.4 I/O access via tag name - Reading...................................................................................... 188
8.6.5.5 I/O access via tag name - Writing....................................................................................... 206
8.6.6 Settings for the virtual time............................................................................................... 224
8.6.7 Cycle control..................................................................................................................... 226
8.6.8 Acyclic services................................................................................................................. 233
8.6.8.1 Overview.......................................................................................................................... 233
8.6.8.2 ReadRecordDone/WriteRecordDone................................................................................... 235
8.6.8.3 AlarmNotification............................................................................................................. 237
8.6.8.4 ProcessEvent.................................................................................................................... 239
8.6.8.5 PullOrPlugEvent................................................................................................................ 240
8.6.8.6 StatusEvent...................................................................................................................... 241
8.6.8.7 ProfileEvent...................................................................................................................... 242
8.6.8.8 UpdateEvent..................................................................................................................... 243
8.6.8.9 GetConfiguredProcessEvent.............................................................................................. 244
8.6.8.10 RackOrStationFaultEvent................................................................................................... 245
8.6.9 Events for IInstances......................................................................................................... 246

S7-PLCSIM Advanced
6 Function Manual, 11/2022, A5E37039512-AE
 Table of contents

8.6.9.1 Events for operating state and cycle control...................................................................... 246

8.6.9.2 Events for acyclic services................................................................................................. 260
8.7 API IRemoteRuntimeManager............................................................................................ 267
8.7.1 Interfaces - Information and settings................................................................................. 267
8.7.2 Simulation Runtime instances........................................................................................... 272
8.7.2.1 Simulation Runtime instances (remote)............................................................................. 272
8.7.3 Events for IRemoteRuntimeManager................................................................................. 278
8.7.3.1 OnConnectionLost events................................................................................................. 278
8.8 Data types........................................................................................................................ 280
8.8.1 DLL import functions (Native C++)..................................................................................... 281
8.8.1.1 ApiEntry_Initialize............................................................................................................. 281
8.8.1.2 ApiEntry_DestroyInterface................................................................................................. 281
8.8.2 Event callback functions (Native C++)................................................................................ 282
8.8.2.1 EventCallback_VOID.......................................................................................................... 282
8.8.2.2 EventCallback_SRCC_UINT32_UINT32_INT32..................................................................... 282
8.8.2.3 EventCallback_SRRSI_AD................................................................................................... 282
8.8.2.4 EventCallback_IRRTM........................................................................................................ 283
8.8.2.5 EventCallback_II_SREC_ST_SROS_SROS ............................................................................. 283
8.8.2.6 EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32................................................. 284
8.8.2.7 EventCallback_II_SREC_ST................................................................................................. 285
8.8.2.8 EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32.................................. 285
8.8.2.9 EventCallback_II_SREC_ST_SRLT_SRLM.............................................................................. 286
8.8.2.10 EventCallback_II_SREC_ST_SDRI........................................................................................ 286
8.8.2.11 EventCallback_II_SREC_ST_SDRI_BYTE............................................................................... 286
8.8.2.12 EventCallback_II_SREC_ST_UINT32_UINT32....................................................................... 287
8.8.2.13 EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32 ................................................ 288
8.8.2.14 EventCallback_II_SREC_ST_UINT32_EPPET_UINT32 ........................................................... 288
8.8.2.15 EventCallback_II_SREC_ST_UINT32_ERSFET....................................................................... 289
8.8.2.16 EventCallback_II_SREC_ST_UINT32.................................................................................... 289
8.8.3 Delegate definitions (managed code)................................................................................ 290
8.8.3.1 Delegate_Void.................................................................................................................. 290
8.8.3.2 Delegate_SRCC_UINT32_UINT32_INT32............................................................................ 290
8.8.3.3 Delegate_SRRSI_AD........................................................................................................... 291
8.8.3.4 Delegate_II_EREC_DT........................................................................................................ 291
8.8.3.5 Delegate_II_EREC_DT_EOS_EOS........................................................................................ 291
8.8.3.6 Delegate_II_EREC_DT_ELT_ELM......................................................................................... 292
8.8.3.7 Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32........................................................ 293
8.8.3.8 Delegate_IRRTM ............................................................................................................... 293
8.8.3.9 Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32......................................... 294
8.8.3.10 Delegate_II_EREC_DT_SDRI................................................................................................ 294
8.8.3.11 Delegate_II_EREC_DT_SDR................................................................................................ 295
8.8.3.12 Delegate_SREC_ST_UINT32_EPPET_UINT32....................................................................... 295
8.8.3.13 Delegate_SREC_ST_UINT32_UINT32_EPET_UINT32............................................................ 296
8.8.3.14 Delegate_SREC_ST_UINT32............................................................................................... 296
8.8.3.15 Delegate_SREC_ST_UINT32_UINT32.................................................................................. 297
8.8.3.16 Delegate_SREC_ST_UINT32_ERSFET.................................................................................. 297
8.8.4 Definitions and constants.................................................................................................. 298
8.8.5 Unions (Native C++).......................................................................................................... 299
8.8.5.1 UIP................................................................................................................................... 299
8.8.5.2 UDataValue...................................................................................................................... 299
8.8.6 Structures......................................................................................................................... 300

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 7
Table of contents

8.8.6.1 SDataValue....................................................................................................................... 301

8.8.6.2 SDVBNI............................................................................................................................. 302
8.8.6.3 SDataValueByAddress....................................................................................................... 302
8.8.6.4 SDataValueByAddressWithCheck....................................................................................... 303
8.8.6.5 SDataValueByName.......................................................................................................... 304
8.8.6.6 SDataValueByNameWithCheck.......................................................................................... 305
8.8.6.7 SConnectionInfo............................................................................................................... 305
8.8.6.8 SInstanceInfo.................................................................................................................... 306
8.8.6.9 SDimension...................................................................................................................... 306
8.8.6.10 STagInfo........................................................................................................................... 307
8.8.6.11 SIP ................................................................................................................................... 308
8.8.6.12 SIPSuite4.......................................................................................................................... 309
8.8.6.13 SOnSyncPointReachedResult............................................................................................. 309
8.8.6.14 SDataRecordInfo............................................................................................................... 311
8.8.6.15 SDataRecord..................................................................................................................... 312
8.8.6.16 SConfiguredProcessEvents ............................................................................................... 312
8.8.6.17 SDiagExtChannelDescription............................................................................................. 313
8.8.6.18 SAutodiscoverData............................................................................................................ 314
8.8.6.19 SMAC address................................................................................................................... 315
8.8.6.20 SNetInterfaceInfo.............................................................................................................. 315
8.8.7 Enumerations................................................................................................................... 315
8.8.7.1 ERuntimeErrorCode.......................................................................................................... 316
8.8.7.2 EArea............................................................................................................................... 319
8.8.7.3 EOperatingState............................................................................................................... 319
8.8.7.4 EOperatingMode.............................................................................................................. 320
8.8.7.5 ECPUType......................................................................................................................... 321
8.8.7.6 ECommunicationInterface................................................................................................. 323
8.8.7.7 ECommunicationMode..................................................................................................... 323
8.8.7.8 EPLCInterface.................................................................................................................... 323
8.8.7.9 ELEDType......................................................................................................................... 324
8.8.7.10 ELEDMode........................................................................................................................ 324
8.8.7.11 EPrimitiveDataType........................................................................................................... 325
8.8.7.12 EDataType........................................................................................................................ 327
8.8.7.13 ETagListDetails.................................................................................................................. 329
8.8.7.14 ERuntimeConfigChanged.................................................................................................. 330
8.8.7.15 EInstanceConfigChanged.................................................................................................. 331
8.8.7.16 EPullOrPlugEventType....................................................................................................... 331
8.8.7.17 EProcessEventType........................................................................................................... 332
8.8.7.18 EDirection......................................................................................................................... 332
8.8.7.19 EDiagProperty................................................................................................................... 333
8.8.7.20 EDiagSeverity................................................................................................................... 333
8.8.7.21 ERackOrStationFaultType.................................................................................................. 334
8.8.7.22 ECycleTimeMonitoringMode............................................................................................. 334
8.8.7.23 EAutodiscoverType........................................................................................................... 335

S7-PLCSIM Advanced
8 Function Manual, 11/2022, A5E37039512-AE
 Table of contents

9 Restrictions, messages and solution.................................................................................................. 336

9.1 Overview.......................................................................................................................... 336
9.2 OPC UA server................................................................................................................... 336
9.3 Web server....................................................................................................................... 337
9.4 Backing up and restoring the configuration of a PLCSIM Advanced instance....................... 337
9.5 Loading project data of an F-CPU to a standard CPU .......................................................... 338
9.6 Update of a TIA Portal project to a new CPU firmware........................................................ 338
9.7 Restrictions for file paths................................................................................................... 338
9.8 Restrictions for storage paths............................................................................................ 339
9.9 Restrictions for communications services........................................................................... 339
9.10 Restrictions for instructions............................................................................................... 339
9.11 Restrictions to local communication via Softbus................................................................ 340
9.12 Unknown data records...................................................................................................... 340
9.13 Messages for communication via TCP/IP............................................................................ 341
9.14 Time synchronization via NTP mode ................................................................................. 342
9.15 Restrictions of security with VMware vSphere Hypervisor (ESXi)......................................... 342
9.16 Restrictions for Hyper-V..................................................................................................... 343
9.17 Monitoring overflow ........................................................................................................ 343
9.18 Deviating I/O values in the STEP 7 user program ............................................................... 344
9.19 Multiple simulations and possible collision of IP addresses................................................. 344
9.20 Lacking access to an IP address......................................................................................... 344
9.21 Simulation in standby mode.............................................................................................. 344
9.22 Time response of PLCSIM Advanced in connection with I/O systems................................... 345
9.23 Simulation start of SIMIT with S7-PLCSIM Advanced........................................................... 345
9.24 Known restrictions when operating with a co-simulation (e.g. SIMIT)................................. 345
9.25 ET 200SP CPUs: Use of BusAdapters with fiber-optic interface............................................ 346
9.26 Installing SIMATIC NET...................................................................................................... 346

A List of abbreviations........................................................................................................................... 347

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 9
Introduction 1
Purpose of the documentation
This function manual describes the simulation software, SIMATIC S7‑PLCSIM Advanced V5.0.
You can use this software to simulate and test your SIMATIC STEP 7 programs on a virtual
controller. You can also use an API to connect the virtual controller to a system or machine
simulation (co-simulation).

Basic knowledge required

The software must only be used by qualified staff.
The following knowledge is required:
• Industrial Automation and Automation Technology
• Programming with STEP 7 (TIA Portal)
• SIMATIC CPUs and CPU programming
• PC-based automation using S7‑1500 and WinCC Runtime Advanced
• Knowledge of programming with C++ or C#
• PC technology
• Windows operating system

Conventions
STEP 7: In this documentation, "STEP 7" is used as a synonym for all versions of the
configuration and programming software "SIMATIC STEP 7 (TIA Portal)".
We also abbreviate SIMATIC S7‑PLCSIM Advanced V5.0 as "PLCSIM Advanced".

Also observe notes marked as follows:

NOTE
A note contains important information on the product described in the documentation, on
the handling of the product or on the section of the documentation to which particular
attention should be paid.

Scope
This function manual is valid for the following order versions
Article number Product variants
6ES7823-1FA04-0YA5 SIMATIC S7-PLCSIM Advanced V5.0
6ES7823-1FE04-0YA5 SIMATIC S7-PLCSIM Advanced V5.0 Download

S7-PLCSIM Advanced
10 Function Manual, 11/2022, A5E37039512-AE
 Introduction

Article number Product variants

6ES7823-1FA04-0YE5 SIMATIC S7-PLCSIM Advanced V5.0 Upgrade V1.0 -> V5.0
6ES7823-1FE04-0YE5 SIMATIC S7-PLCSIM Advanced V5.0 Upgrade V1.0 -> V5.0 Download
6ES7823-1FE00-0YN5 SIMATIC S7-PLCSIM Advanced Subscription Download

The articles each contain one license, which is valid for two instances.

Special information

NOTE
Readme
You can obtain updates to the function manual as downloads on the Internet
(https://support.industry.siemens.com/cs/us/en/view/109773483).

Application examples
You can find the following application examples for S7‑PLCSIM Advanced on the Internet:
• SIMATIC S7-PLCSIM Advanced: Co-Simulation via API (1
(https://support.industry.siemens.com/cs/ww/de/view/109739660/en))
• Digitalization with TIA Portal: Virtual commissioning with SIMATIC and Simulink (2
(https://support.industry.siemens.com/cs/ww/en/document/109749187))

Recycling and disposal

For environmentally sustainable recycling and disposal of your old equipment, contact a
certified electronic waste disposal service and dispose of the equipment according to the
applicable regulations in your country.

Industry Mall
The Industry Mall is the catalog and order system of Siemens AG for automation and drive
solutions on the basis of Totally Integrated Automation (TIA) and Totally Integrated Power
(TIP).
You can find catalogs for all automation and drive products on the Internet
(https://mall.industry.siemens.com).

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 11
Introduction
1.1 Function Manuals documentation guide

1.1 Function Manuals documentation guide

1.1.1 Information classes Function Manuals

The documentation for the SIMATIC S7‑1500 automation system, for the 1513/1516pro-2 PN,
SIMATIC Drive Controller CPUs based on SIMATIC S7‑1500 and the SIMATIC ET 200MP,
ET 200SP, ET 200AL and ET 200eco PN distributed I/O systems is arranged into three areas.
This arrangement enables you to access the specific content you require.
You can download the documentation free of charge from the Internet
(https://support.industry.siemens.com/cs/ww/en/view/109742705).

Basic information
The system manuals and Getting Started describe in detail the configuration, installation,
wiring and commissioning of the SIMATIC S7‑1500, SIMATIC Drive Controller, ET 200MP,
ET 200SP, ET 200AL and ET 200eco PN systems. Use the corresponding operating instructions
for 1513/1516pro-2 PN CPUs.
The STEP 7 online help supports you in the configuration and programming.
Examples:
• Getting Started S7-1500
• System manuals
• Operating instructions ET 200pro and 1516pro-2 PN CPU
• Online help TIA Portal

Device information
Equipment manuals contain a compact description of the module-specific information, such
as properties, wiring diagrams, characteristics and technical specifications.
Examples:
• Equipment manuals for CPUs
• Equipment manuals for interface modules
• Equipment manuals for digital modules
• Equipment manuals for analog modules
• Equipment manuals for communication modules
• Equipment manuals for technology modules
• Equipment manuals for power supply modules
• Equipment manuals for BaseUnits

S7-PLCSIM Advanced
12 Function Manual, 11/2022, A5E37039512-AE
 Introduction
1.1 Function Manuals documentation guide

General information
The function manuals contain detailed descriptions on general topics relating to the
SIMATIC Drive Controller and the S7-1500 automation system.
Examples:
• Function Manual Diagnostics
• Function Manual Communication
• Function Manuals Motion Control
• Function Manual Web Server
• Function Manual Cycle and Response Times
• PROFINET Function Manual
• PROFIBUS Function Manual

Product Information
Changes and supplements to the manuals are documented in a Product Information. The
Product Information takes precedence over the device and system manuals.
You will find the latest Product Information on the Internet:
• S7-1500/ET 200MP (https://support.industry.siemens.com/cs/de/en/view/68052815)
• SIMATIC Drive Controller
(https://support.industry.siemens.com/cs/de/en/view/109772684/en)
• Motion Control (https://support.industry.siemens.com/cs/de/en/view/109794046/en)
• ET 200SP (https://support.industry.siemens.com/cs/de/en/view/73021864)
• ET 200eco PN (https://support.industry.siemens.com/cs/ww/en/view/109765611)

Manual Collections
The Manual Collections contain the complete documentation of the systems put together in
one file.
You will find the Manual Collections on the Internet:
• S7-1500/ET 200MP/SIMATIC Drive Controller
(https://support.industry.siemens.com/cs/ww/en/view/86140384)
• ET 200SP (https://support.industry.siemens.com/cs/ww/en/view/84133942)
• ET 200AL (https://support.industry.siemens.com/cs/ww/en/view/95242965)
• ET 200eco PN (https://support.industry.siemens.com/cs/ww/en/view/109781058)

1.1.2 Basic tools

The tools described below support you in all steps: from planning, over commissioning, all
the way to analysis of your system.

TIA Selection Tool

The TIA Selection Tool tool supports you in the selection, configuration, and ordering of
devices for Totally Integrated Automation (TIA).
As successor of the SIMATIC Selection Tools , the TIA Selection Tool assembles the already
known configurators for automation technology into a single tool.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 13
Introduction
1.1 Function Manuals documentation guide

With the TIA Selection Tool , you can generate a complete order list from your product
selection or product configuration.
You can find the TIA Selection Tool on the Internet.
(https://support.industry.siemens.com/cs/ww/en/view/109767888)

SIMATIC Automation Tool

You can use the SIMATIC Automation Tool to perform commissioning and maintenance
activities on various SIMATIC S7 stations as bulk operations independent of TIA Portal.
The SIMATIC Automation Tool offers a wide range of functions:
• Scanning of a PROFINET/Ethernet system network and identification of all connected CPUs
• Assignment of addresses (IP, subnet, Gateway) and device name (PROFINET device) to a
CPU
• Transfer of the date and the programming device/PC time converted to UTC time to the
module
• Program download to CPU
• RUN/STOP mode switchover
• CPU localization through LED flashing
• Reading out of CPU error information
• Reading the CPU diagnostic buffer
• Reset to factory settings
• Firmware update of the CPU and connected modules
You can find the SIMATIC Automation Tool on the Internet.
(https://support.industry.siemens.com/cs/ww/en/view/98161300)

PRONETA
SIEMENS PRONETA (PROFINET network analysis) is a commissioning and diagnostic tool for
PROFINET networks. PRONETA Basic has two core functions:
• In the network analysis, you get an overview of the PROFINET topology. Compare a real
configuration with a reference installation or make simple parameter changes, e.g. to the
names and IP addresses of the devices.
• The "IO test" is a simple and rapid test of the wiring and the module configuration of a
plant, including documentation of the test results.
You can find SIEMENS PRONETA Basic on the Internet:
(https://support.industry.siemens.com/cs/ww/en/view/67460624)
SIEMENS PRONETA Professional is a licensed product that offers you additional functions. It
offers you simple asset management in PROFINET networks and supports operators of
automation systems in automatic data collection/acquisition of the components used through
various functions:
• The user interface (API) offers an access point to the automation cell to automate the scan
functions using MQTT or a command line.
• With PROFIenergy diagnostics, you can quickly detect the current pause mode or the
readiness for operation of devices that support PROFIenergy and change these as needed.
• The data record wizard supports PROFINET developers in reading and writing acyclic
PROFINET data records quickly and easily without PLC and engineering.

S7-PLCSIM Advanced
14 Function Manual, 11/2022, A5E37039512-AE
 Introduction
1.1 Function Manuals documentation guide

You can find SIEMENS PRONETA Professional on the Internet.

(https://www.siemens.com/proneta-professional)

SINETPLAN
SINETPLAN, the Siemens Network Planner, supports you in planning automation systems and
networks based on PROFINET. The tool facilitates professional and predictive dimensioning of
your PROFINET installation as early as in the planning stage. In addition, SINETPLAN supports
you during network optimization and helps you to exploit network resources optimally and to
plan reserves. This helps to prevent problems in commissioning or failures during productive
operation even in advance of a planned operation. This increases the availability of the
production plant and helps improve operational safety.
The advantages at a glance
• Network optimization thanks to port-specific calculation of the network load
• Increased production availability thanks to online scan and verification of existing systems
• Transparency before commissioning through importing and simulation of existing STEP 7
projects
• Efficiency through securing existing investments in the long term and the optimal use of
resources
You can find SINETPLAN on the Internet
(https://new.siemens.com/global/en/products/automation/industrial-
communication/profinet/sinetplan.html).

1.1.3 SIMATIC Technical Documentation

Additional SIMATIC documents will complete your information. You can find these
documents and their use at the following links and QR codes.
The Industry Online Support gives you the option to get information on all topics. Application
examples support you in solving your automation tasks.

Overview of the SIMATIC Technical Documentation

Here you will find an overview of the SIMATIC documentation available in Siemens Industry
Online Support:

Industry Online Support International

(https://support.industry.siemens.com/cs/ww/en/view/109742705)

Watch this short video to find out where you can find the overview directly in Siemens
Industry Online Support and how to use Siemens Industry Online Support on your mobile
device:
Quick introduction to the technical documentation of automation products per
video (https://support.industry.siemens.com/cs/us/en/view/109780491)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 15
Introduction
1.1 Function Manuals documentation guide

YouTube video: Siemens Automation Products - Technical Documentation at a

Glance (https://youtu.be/TwLSxxRQQsA)

mySupport
With "mySupport" you can get the most out of your Industry Online Support.

Registration You must register once to use the full functionality of "mySupport". After registra­
tion, you can create filters, favorites and tabs in your personal workspace.
Support requests Your data is already filled out in support requests, and you can get an overview of
your current requests at any time.
Documentation In the Documentation area you can build your personal library.
Favorites You can use the "Add to mySupport favorites" to flag especially interesting or fre­
quently needed content. Under "Favorites", you will find a list of your flagged
entries.
Recently viewed The most recently viewed pages in mySupport are available under "Recently viewed
articles articles".
CAx data The CAx data area gives you access to the latest product data for your CAx or CAe
system. You configure your own download package with a few clicks:
• Product images, 2D dimension drawings, 3D models, internal circuit diagrams,
EPLAN macro files
• Manuals, characteristics, operating manuals, certificates
• Product master data
You can find "mySupport" on the Internet. (https://support.industry.siemens.com/My/ww/en)

Application examples
The application examples support you with various tools and examples for solving your
automation tasks. Solutions are shown in interplay with multiple components in the system -
separated from the focus on individual products.
You can find the application examples on the Internet.
(https://support.industry.siemens.com/cs/ww/en/ps/ae)

S7-PLCSIM Advanced
16 Function Manual, 11/2022, A5E37039512-AE
Safety instructions 2
2.1 Security information
Siemens provides products and solutions with industrial security functions that support the
secure operation of plants, systems, machines and networks.
In order to protect plants, systems, machines and networks against cyber threats, it is
necessary to implement – and continuously maintain – a holistic, state-of-the-art industrial
security concept. Siemens’ products and solutions constitute one element of such a concept.
Customers are responsible for preventing unauthorized access to their plants, systems,
machines and networks. Such systems, machines and components should only be connected
to an enterprise network or the internet if and to the extent such a connection is necessary
and only when appropriate security measures (e.g. firewalls and/or network segmentation)
are in place.
For additional information on industrial security measures that may be implemented, please
visit (https://www.siemens.com/industrialsecurity).
Siemens' products and solutions undergo continuous development to make them more
secure. Siemens strongly recommends that product updates are applied as soon as they are
available and that the latest product versions are used. Use of product versions that are no
longer supported, and failure to apply the latest updates may increase customers' exposure to
cyber threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS
Feed visit (https://www.siemens.com/cert).

NOTE
Administrator rights
For normal operation, the standard user rights are sufficient. You need administrator rights
only when you install or repair S7-PLCSIM Advanced or change the network configuration.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 17
Product overview 3
3.1 What is S7-PLCSIM Advanced?
You use S7-PLCSIM Advanced to simulate your CPU programs on a virtual controller. You do
not need any real controllers for this. You configure your CPU with STEP 7 in TIA Portal,
program your application logic and then load the hardware configuration and the program
into the virtual controller. From there you run your program logic, monitor the effects of
simulated inputs and outputs and adapt your programs.
In addition to communication via Softbus, which limits communication to a local PC or virtual
machine, S7-PLCSIM Advanced offers a full Ethernet connection and thus also supports
distributed I/O systems.
S7-PLCSIM Advanced enables interaction with native C++/C# programs or simulation software
over the user interface (API).

Application areas
Typical application areas of S7-PLCSIM Advanced are:
• Verification of the user program (TIA Portal)
• Automatic testing of the STEP 7 program
• Software in the loop simulation for the virtual commissioning of machine tools/production
machines, production cells and production lines in a plant.
• Operator training through the connection of a real HMI

Advantages
The use of S7-PLCSIM Advanced offers numerous advantages:
• Improve the quality of automation projects by early error detection
• Avoid costs for hardware in simulation environments
• Shorten commissioning time
• Reduce risk for commissioning
• Earlier training of operator is possible
• Increase production efficiency by optimizing program components
• Increase efficiency during replacement of machine components
• Increase efficiency during expansion of existing plants

S7-PLCSIM Advanced
18 Function Manual, 11/2022, A5E37039512-AE
 Product overview
3.2 S7-PLCSIM products

3.2 S7-PLCSIM products

PLCSIM Advanced V5.0, PLCSIM V18 and PLCSIM V5.x

Table 3-1 Comparison of S7-PLCSIM products
Function PLCSIM Advanced V5.0 PLCSIM V18 PLCSIM V5.x
Runtime Independent Programming with STEP 7 Programming with STEP 7
User interface Control Panel/PLCSIM V18 UI Innovated user interface Look&Feel of STEP 7 V5.x
Communication Softbus 4, TCP/IP Softbus 4 Softbus 4
Supported CPU families S7‑1500 (C, T, F), S7-1500R/H, S7-1200 (F), S7-1500 (C, T, F), S7‑300, S7‑300F,
SIMATIC Drive Controller, 1500R/H, S7‑400, S7‑400F
ET 200SP, ET 200SP F, SIMATIC Drive Controller,
ET 200pro, ET 200pro F, ET 200SP, ET 200SP F,
SIPLUS CPUs (S7-1500; Stand­ SIPLUS CPUs (S7-1500; Stand­
ard and F-CPUs, S7-1500R/H ard and F-CPUs, S7-1500R/H
and ET 200SP; Standard and F- and ET 200SP; Standard and F-
CPUs) CPUs)
API for co-simulation1 ✓ - -
Web server ✓, via TCP/IP - -
ODK ✓ - -
OPC UA ✓, via TCP/IP - -
Process diagnostics ✓ ✓ -
S7 communication ✓ Using Softbus Using Softbus
Open user communication ✓, UDP via TCP/IP Using Softbus -
Secure Communication ✓, via TCP/IP - -
Traces2 ✓ - -
Motion3 ✓ ✓ -
Protected blocks (KHP) ✓ ✓, for S7-1500 CPUs only -
Multiple instances Up to 16 Up to 2 -
Support of distributed ✓, via TCP/IP - -
instances
Virtual time ✓ - -
Connection of real CPUs/HMIs ✓, via TCP/IP - -
DHCP/DNS use ✓, via TCP/IP - -
Virtual memory card ✓ - -
1 Via C++ and C# programs and simulation software
2 Can be monitored with PLCSIM V16 and higher in the TIA Portal; can also be monitored with PLCSIM Advanced V3.0 and
higher on the Web server.
3 With PLCSIM V16 and higher, the axes are always in simulation mode irrespective of the axis configuration.
4 You can find more information on Softbus in the "Communication" section.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 19
Product overview
3.3 Compatibility in case of updates

Function PLCSIM Advanced V5.0 PLCSIM V18 PLCSIM V5.x

Communication between the - PLCSIM as of V12 and PLCSIM V5.x can be installed and oper­
instances ated on the same PC or the same virtual machine.
- Instances of PLCSIM as of V12 can communicate via Softbus
with PLCSIM V5.x.
PLCSIM Advanced V3.0 and higher and PLCSIM V15 and higher -
can be installed and operated on the same PC or the same vir­
tual machine. The communication between the two applica­
tions cannot be simulated.
PLCSIM V5.4 SP8 is automatically installed with PLCSIM Advanced. The communication
between the two applications can be simulated. Instances of PLCSIM Advanced can commu­
nicate via Softbus with PLCSIM ≥ V5.4 SP8.
1 Via C++ and C# programs and simulation software
2 Can be monitored with PLCSIM V16 and higher in the TIA Portal; can also be monitored with PLCSIM Advanced V3.0 and
higher on the Web server.
3 With PLCSIM V16 and higher, the axes are always in simulation mode irrespective of the axis configuration.
4 You can find more information on Softbus in the "Communication" section.

3.3 Compatibility in case of updates

Compatibility of API and Runtime Manager versions

S7-PLCSIM Advanced V5.0 contains the Runtime Manager version V5.0 and the API versions
V1.0 (SP1) to V5.0. The task of the Runtime Manager is to establish a connection to
S7-PLCSIM Advanced.
When S7-PLCSIM Advanced V5.0 is installed, any existing, earlier version is updated. The
Runtime Manager of S7-PLCSIM Advanced V5.0 is compatible with projects that were created
with earlier API versions. You can therefore continue to use already created projects.

NOTE
An API with a higher version number (e.g. V5.0) cannot connect to an earlier Runtime
Manager version (e.g. V1.0).

Introductory information on the components of the Runtime simulation can be found in the
section User interfaces (API) (Page 98).

Compatibility with TIA Portal and with CPU firmware versions

The firmware used in S7-PLCSIM Advanced V5.0 corresponds to that of a CPU S7‑15xx V3.0.
The firmware is compatible to the TIA Portal versions V14 to V18.
Table 3-2 Compatibility with CPU firmware versions
S7-PLCSIM Advanced Supported CPU firmware version
V1.0 V1.8, V2.0.1
V1.0 SP1 V1.8, V2.0.1

S7-PLCSIM Advanced
20 Function Manual, 11/2022, A5E37039512-AE
 Product overview
3.3 Compatibility in case of updates

S7-PLCSIM Advanced Supported CPU firmware version

V1.0 SP1 Upd1 V1.8, V2.0.1
V2.0 V1.8 to V2.5.0
V2.0 Upd1 V1.8 to V2.5.2
V2.0 SP1 V1.8 to V2.6.0
V2.0 SP1 Upd1 V1.8 to V2.6.1
V3.0 V1.8 to V2.8.1
V3.0 Upd1 V1.8 to V2.8.1
V3.0 Upd2 V1.8 to V2.8.3
V4.0 V1.8 to V2.9.2
V4.0 SP1 V1.8 to V2.9.4
V5.0 V1.8 to V3.0

The following figure shows the compatibility between the API and the Runtime Manager (RT
Manager) using the example of versions V4.0 and V5.0:

3/&6,0$GYDQFHG &R6LPXODWLRQ
&XVWRPHU$SSOLFDWLRQ
570DQDJHU

):

$3,9
9

WR
):
9

):
570DQDJHU

$3,9

WR
9

):
9

Figure 3-1 Compatibility

NOTE
Password encryption in case of updates
When a TIA Portal project is updated from CPU firmware version < V2.0 to CPU firmware
version ≥ V2.0, the following error message is displayed during a download of the project to
SIMATIC S7-PLCSIM Advanced ≥ V4.0:
"Loading of hardware configuration failed (0020 -3 2 0). Please check the diagnostic buffer of
the target hardware."
To successfully download such a project to SIMATIC S7-PLCSIM Advanced ≥ V4.0, click on the
"Update password encryption" button while updating the project.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 21
Product overview
3.4 Security for S7-PLCSIM Advanced

3.4 Security for S7-PLCSIM Advanced

Restrictions for security

Note the following restrictions when using S7-PLCSIM Advanced:
Authentication
• The user interfaces (API) do not have options for authentication and authorization. There
is no protection using user accounts and passwords.
• The Runtime Manager communication is not protected by authentication.

Communication
• The multi-computer simulation communication is not encrypted.
• A TCP/IP port is opened on the PC for cross-network communication.
• The installed Npcap program library provides access to TCP/IP network communication.

NOTE
For cross-computer communication, use a closed simulation network that is not connected to
a production network.

Know-how protection

NOTE
Know-how protected blocks
If know-how-protected blocks for the simulation support are enabled, the know-how
protection is limited.

NOTE
CPU function libraries for ODK
The SO files (shared object files) for ODK are not know-how-protected. The customer is
responsible for the SO files and its know-how protection.

S7-PLCSIM Advanced
22 Function Manual, 11/2022, A5E37039512-AE
 Product overview
3.5 Support simulation

3.5 Support simulation

Requirement for simulation

NOTE
Enable simulation capability
To use a STEP 7 project with simulation, you must select the "Support simulation during block
compilation" option in the "Protection" tab in the properties of the project and confirm with
OK.

Figure 3-2 Enable simulation capability

Know-how protection
If a know-how-protected block is to be used for the simulation, it must be unlocked by
entering a password.
After you have unlocked the know-how-protected block, you can activate the option
"Simulability with SIMATIC S7-PLCSIM (Advanced)". You will find the option in the properties
of the block in the "General > Compilation" tab.
Additional information can be found on the Internet
(https://support.industry.siemens.com/cs/ww/en/view/109754928).

Global libraries
You cannot use know-how protection with global libraries, because the libraries are write-
protected.
The "Simulation with SIMATIC S7‑PLCSIM Advanced" option must be set when generating the
blocks (source of the blocks).

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 23
Product overview
3.6 Supported CPUs

3.6 Supported CPUs

Supported CPUs from the S7‑1500 family

S7-PLCSIM Advanced V5.0 supports the simulation of the following CPUs:
Table 3-3 Supported CPUs
Type Firmware version V1.8 to V3.0
Standard Fail-safe
CPUs1 CPU 1511‑1 PN CPU 1511F‑1 PN
CPU 1513‑1 PN CPU 1513F‑1 PN
CPU 1515‑2 PN CPU 1515F‑2 PN
CPU 1516‑3 PN/DP CPU 1516F‑3 PN/DP
CPU 1517‑3 PN/DP CPU 1517F‑3 PN/DP
CPU 1518‑4 PN/DP CPU 1518F‑4 PN/DP
CPU 1518-4 PN/DP ODK CPU 1518F-4 PN/DP ODK
CPU 1518-4 PN/DP MFP CPU 1518F-4 PN/DP MFP
Compact CPUs2 CPU 1511C‑1 PN -
CPU 1512C‑1 PN
ET 200SP CPUs1 CPU 1510SP-1 PN CPU 1510SP F-1 PN
CPU 1512SP-1 PN CPU 1512SP F-1 PN
CPU 1514SP-2 PN CPU 1514SP F-2 PN
CPU 1514SP T-2 PN CPU 1514SP TF-2 PN
Technology CPUs CPU 1511T-1 PN CPU 1511TF-1 PN
CPU 1515T-2 PN CPU 1515TF-2 PN
CPU 1516T-3 PN/DP CPU 1516TF-3 PN/DP
CPU 1517T-3 PN/DP CPU 1517TF-3 PN/DP
CPU 1518T-4 PN/DP CPU 1518TF-4 PN/DP
R/H-CPUs2 CPU 1513R-1 PN CPU 1518HF-4 PN
CPU 1515R-2 PN
CPU 1517H-3 PN
ET 200pro CPUs CPU 1513pro-2 PN CPU 1513pro F-2 PN
CPU 1516pro-2 PN CPU 1516pro F-2 PN
SIMATIC Drive Controller - CPU 1504D TF
CPU 1507D TF
1 SIPLUS
CPUs are supported. They are of the same design as the standard and fail-safe CPUs listed here with their own article
numbers. The article numbers of the respective SIPLUS CPUs are part of the API.
2 The on-board I/O of the CPUs is not simulated. The simulation interface corresponds to the process image.

Unsupported CPUs
S7-PLCSIM Advanced does not support the simulation of the following CPUs:
• ET 200SP Open Controller CPU 1515SP PC and S7-1500 Software Controller
• S7‑1200 CPUs
To simulate CPUs of the S7-1200 product family, use S7-PLCSIM. You can find more
information on S7-PLCSIM on the Internet
(https://support.industry.siemens.com/cs/ww/en/view/109797780).
If you download a TIA Portal project whose configuration includes an unsupported CPU, the
following error message appears:

S7-PLCSIM Advanced
24 Function Manual, 11/2022, A5E37039512-AE
 Product overview
3.7 Differences between a simulated and a real CPU

"Loading of hardware configuration failed (0020 -3 2 0). Please check the diagnostic buffer of
the
target hardware."
In this case, use a similar, supported CPU or a supported predecessor version of the relevant
CPU.

3.7 Differences between a simulated and a real CPU

The virtual controller cannot fully simulate a real CPU down to the individual details. Even if a
program is downloaded without errors to the CPU and running successfully, this does not
necessarily mean that the virtual controller in the simulation behaves exactly like a real CPU.

Deterministic
S7-PLCSIM Advanced runs on a PC with the Windows operating system. The scan cycle time
and the exact time of actions in S7-PLCSIM Advanced are not the same as when these actions
run on physical hardware. This is because several programs share the processing resources on
your PC.
To provide the best possible deterministic behavior under these conditions,
S7-PLCSIM Advanced as of V2.0 requires one free Core (CPU core) per instance. Information
on the minimum requirements for the computer hardware or a virtual machine can be found
in the section System Requirements (Page 31).
If your program depends heavily on the time required to execute actions, then make sure that
you do not evaluate your program based only on the results of the simulation time.

Know-how protection
Projects with know-how protection for blocks can only be simulated if they are enabled for
simulation. You need the block password for this purpose.

Instructions
Instructions are simulated with a few exceptions, see Restrictions for instructions (Page 339).
Programs that are based on the instructions behave differently than real CPUs in the
simulation.

Display of the quantity structure

In STEP 7, the maximum quantity structure based on the CPU 1518‑4 PN/DP is shown in the
project tree under "Program information" for all the CPUs.
The maximum quantity structure of the simulated CPU is displayed under "Online &
Diagnostics".

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 25
Product overview
3.7 Differences between a simulated and a real CPU

S7-1500R/H
For communication with other devices, you can configure system IP addresses in STEP 7 for a
redundant S7-1500R/H system.

3.7.1 Restrictions for all supported CPUs

Fieldbus systems
S7-PLCSIM Advanced does not simulate fieldbus systems (PROFINET IO, PROFIBUS DP).

Intelligent I/O devices (I-devices)

S7-PLCSIM Advanced does not simulate I-Device functionality.

I/O
S7-PLCSIM Advanced simulates the real CPU, but not configured I/O modules and the on-
board I/O of the compact CPUs.

Removal and insertion

In contrast to real systems, S7-PLCSIM Advanced allows the removal and insertion of head
modules in distributed I/O systems.

Communications modules and communications processors

S7-PLCSIM Advanced does not support CMs and CPs and the related features such as "Access
to PLC via communications module".

Diagnostics / diagnostic alarms

With the AlarmNotification() API method, simple diagnostic buffer entries can be simulated in
S7-PLCSIM Advanced according to the PROFINET standard.
PROFIBUS-specific diagnostics (e.g. via DS0, DS1) and user-specific text lists are not
supported.

Online and diagnostic functions

Certain online and diagnostic functions (e.g. the "Firmware update" function) are not
supported.

S7-PLCSIM Advanced
26 Function Manual, 11/2022, A5E37039512-AE
 Product overview
3.7 Differences between a simulated and a real CPU

Copy protection
S7-PLCSIM Advanced does not simulate copy protection.

Limited support
S7-PLCSIM Advanced simulates some functions to a limited extent. You can find an overview
in the section Restrictions, messages and solution (Page 336).

3.7.2 Notes

Password applied during CPU swap

Depending on the firmware version of the CPUs affected (the CPU to be replaced and the
replacement CPU), you are either offered an update to the latest algorithm or prompted to
assign a new password because the replacement CPU cannot use the existing password
configuration.
If the CPU to be replaced and the replacement CPU are identical in terms of the algorithm
used, no action is required: the password configuration and the other parameter settings are
transferred.
S7-PLCSIM Advanced does not support any password encryption for CPU versions with
firmware less than V2.0.
In order to use protection levels, the Web server and the access protection of the F‑CPU in the
simulation, click on the "Update password encryption" button. The button is located in the
CPU properties in the "Protection & Security" tab under "Access level".

HMI devices and CPU protection levels

• S7-PLCSIM Advanced supports SIMATIC HMI devices as of version 14. Connections to
SIMATIC HMI devices prior to V14 are not supported.
• S7-PLCSIM Advanced supports protection levels if the virtual S7‑1500 controller is
configured with a firmware version V2.0 or higher.
• It is possible to connect SIMATIC HMI devices as of V14 to virtual S7‑1500 controllers that
are configured with a firmware version V2.0 or higher, with or without protection levels.
• It is possible to connect SIMATIC HMI devices as of V14 to virtual S7‑1500 controllers
which are configured with a firmware version lower than V2.0 without protection levels.

Solution
To establish a connection to the SIMATIC HMI device V13 or earlier, you have to update this
SIMATIC HMI device to version V14.
To establish a connection from the virtual controller that is configured with a firmware
version lower than V2.0 to the SIMATIC HMI device, you have to remove existing protection
levels from the project.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 27
Product overview
3.8 Password to protect confidential configuration data

Safety system versions

To successfully simulate and test a project with fail-safe input and output modules, you need
to use safety system version V1.6, V2.0, V2.1, V2.2, V2.3, V2.4 or V2.5. Simulation of the fail-
safe input and output modules does not work correctly with an older version.

Priority for hardware interrupt OB

The hardware interrupts triggered via the S7-PLCSIM Advanced API are transmitted in
sequence to the user program.
The priority of the assigned hardware interrupt OB determines the sequence of execution
only if events occur simultaneously.

Technology module TM Count - Error message of instruction High_Speed_Counter

When you are using S7-PLCSIM Advanced for the simulation of a high-speed counter in a
TM Count technology module, the instruction High_Speed_Counter signals an error 16#80C7.
The instruction High_Speed_Counter expects that the module has set a bit for "Status ready"
(STS_READY). Because S7-PLCSIM Advanced does not simulate the module behavior, the
instruction signals an error.
The STS_READY bit is located in the input area of the module at offset 13.4. When the input
area of your TM Count module starts at %I32, for example, the STS_READY bit is located at
%I45.4.
To prevent this error message of the High_Speed_Counter instruction, set the STS_READY bit
accordingly.

3.8 Password to protect confidential configuration data

As of STEP 7 V17, you have the option of assigning a password to protect confidential
configuration data of the respective CPU as of FW version V2.9. This refers to data such as
private keys that are required for the proper functioning of certificate-based protocols.

Assign a password to protect confidential configuration data

You assign the password in STEP 7, in the CPU properties, in the area "Protection & Security >
Protection of the PLC configuration data".
You can use the same password for a PLCSIM Advanced instance as for the real CPU. This
makes it easier for you to assign it uniquely.
PLCSIM Advanced stores the password encrypted in a file on the virtual memory card. The
handling of the password is the same as with the real CPU.
Only the current, active Windows user and no other user is allowed to read the password for
the protection of confidential configuration data on the computer.

NOTE
Note that your Windows password protects the password used to protect confidential
configuration data. Therefore, you are not allowed to share the Windows password with
other, untrustworthy users.

S7-PLCSIM Advanced
28 Function Manual, 11/2022, A5E37039512-AE
 Product overview
3.8 Password to protect confidential configuration data

Additional information
Detailed information on the protection of confidential configuration data and on secure
communication can be found in the Communication function manual
(https://support.industry.siemens.com/cs/ww/en/view/59192925).

Special use cases

Move the virtual SIMATIC memory card to another virtual machine (e.g. SIMIT)
If you have not set a password to protect confidential configuration data, there are no
restrictions on move operations.
If you have specified the password to protect confidential configuration data, the following
restriction applies:
When you move the virtual memory card from one computer to another, you cannot start the
PLCSIM Advanced instance on the new system.

NOTE
To ensure maximum security on your systems, the password for protecting confidential
configuration data is not available on a new system. You must reset the password again in
the new system.

Solution:
The computer is part of an Active Directory.
The password encryption is linked to the Windows user. When you use the same Active
Directory user in your domain on another computer, you can start PLCSIM Advanced
instances there.
SIMIT archives the virtual SIMATIC memory card as a ZIP file. and another user/computer
is trying to restart this simulation
Solution:
1. Remove the password for protecting confidential configuration data from the STEP 7
project.
2. Load the project to the virtual controller.
You can move the virtual memory card to other computers without any restrictions.
Switching on the PLCSIM Advanced instance without valid password
When you switch on an instance and the password for the protection of confidential
configuration data is incorrect, the instance restarts automatically and switches to the STOP
operating state. ERROR LED flashes red.
Solution:
1. Enter the password to protect the confidential configuration data in STEP 7 or via the
SIMATIC Automation Tool.
2. Restart the instance.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 29
Product overview
3.8 Password to protect confidential configuration data

Editing an instance created with PLCSIM Advanced V4.0 and higher using PLCSIM
Advanced API V3.0
You have assigned a password to protect confidential configuration data for the real CPU.

NOTE
Editing an instance created with PLCSIM Advanced using PLCSIM Advanced API V3.0
with the functions ArchiveStorage() and RetrieveStorage()
When you edit an instance created with PLCSIM Advanced V4.0 or higher with the API
functions ArchiveStorage() and RetrieveStorage() of V3.0, API V3.0 does not save the entire
card content of the virtual memory card. The retain.pms and sim_hwdb.ini files are missing.
This means that the password to protect confidential configuration data is not saved and will
be lost.

Solution:
You have a variety of solution options:
• Set the password to protect the confidential configuration data before each simulation
again using STEP 7, the SIMATIC Automation Tool or TIA Portal Openness.
• Establish a remote connection of the instance via the Runtime Manager even when the
instance communicates locally. In this case, the password is saved to the virtual memory
card.
• Do not assign a password to protect confidential configuration data.

S7-PLCSIM Advanced
30 Function Manual, 11/2022, A5E37039512-AE
Installing 4
4.1 Introduction

4.1.1 System requirements

You should preferably install PLCSIM Advanced on a SIMATIC Field PG M5 Advanced or
comparable PC.
For PLCSIM Advanced to operate efficiently, the following minimum requirements for
computer hardware or for a virtual machine must be met.
Table 4-1 System requirements
Hardware Virtual machine
Processor • At least one core Intel® Core™ i7 6th Gen­ • One virtual CPU per started instance has
eration or one x86 processor from another to be assigned to the VM
manufacturer per instance started. • A corresponding number of processors
• At least one additional core for the operat­ has to be physically available on the host
ing system • At least one additional core for the operat­
• At least one additional core for the addi­ ing system
tional active applications • At least one additional core for the addi­
tional active applications
• At least two cores, if STEP 7 (TIA Portal) is
installed on the VM
RAM • 1 GB per started instance • 1 GB per started instance
• At least 4 GB for the Windows operating • At least 4 GB for the Windows operating
system system
• Additional RAM corresponding to the • Additional RAM corresponding to the
requirements of the remaining active requirements of the remaining active
applications applications
• At least 8 GB, if STEP 7 (TIA Portal) is
installed on the VM
Free hard disk space 5 GB 5 GB
Screen resolution Minimum 1024 x 768 Minimum 1024 x 768

Operating systems (64-bit versions)

PLCSIM Advanced V5.0 supports the following operating systems
• Windows 10 Home Version 2009/20H2
• Windows 10 Professional Version 2009/20H2
• Windows 10 Professional Version 21H1
• Windows 10 Professional Version 21H2
• Windows 10 Enterprise Version 2009/20H2
• Windows 10 Enterprise Version 21H1
• Windows 10 Enterprise Version 21H2
• Windows 10 Enterprise 2016 LTSB

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 31
Installing
4.1 Introduction

• Windows 10 Enterprise 2019 LTSC

• Windows 10 Enterprise 2021 LTSC
• Windows Server 2016 Standard (full installation)
• Windows Server 2019 Standard (full installation)
• Windows Server 2022 Standard (full installation)
• Windows 11 Home Version 21H2
• Windows 11 Pro Version 21H2
• Windows 11 Enterprise 21H2
For more detailed information on operating systems, refer to the help on Microsoft Windows
or the Microsoft homepage.
Some products might also support additional Windows versions. You can find more
information in the product-specific requirements or check the compatibility with the
compatibility tool. The compatibility tool is available on the Internet
(https://support.industry.siemens.com/kompatool/pages/main/index.jsf?).

NOTE

Make sure that the Windows operating system you are using is up to date.

Virtualization platforms
You can install STEP 7 and PLCSIM Advanced on a virtual machine. For this purpose, use one
of the following virtualization platforms in the specified version or a newer version:
• VMware vSphere Hypervisor (ESXi) 6.7
• VMware Workstation Pro 15.5.0
• VMware Player 15.5.0
• Microsoft Hyper-V Server 2019
The information that you need to install STEP 7 (TIA Portal) on a virtual machine is available
on the Internet (https://support.industry.siemens.com/cs/ww/en/view/78788417).

4.1.2 Restrictions due to antivirus programs

NOTICE
Restrictions due to virus scanners and Advanced Threat Protection software (ATP
software)
Virus scanners and ATP software that monitor the behavior of processes and communication
can have a significant influence on the performance of the runtime and communication of
PLCSIM Advanced and even prevent PLCSIM Advanced instances from starting.

S7-PLCSIM Advanced
32 Function Manual, 11/2022, A5E37039512-AE
 Installing
4.1 Introduction

Solution
You can decrease restrictions during installation and runtime of PLCSIM Advanced. To do so,
define exceptions for the virus scanner for secure files and folders.
Procedure
Add the following folders to the exceptions:
• "C:\Program Files\Common Files\Siemens\PLCSIMADV\Drivers"
• "C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV"
• "C:\Program Files (x86)\SIEMENS\Automation\PLCSIMADV\bin"
If the virus scanner only allows files as exceptions, add all files from the listed folders to the
exceptions. The procedure is described in the instructions of the respective manufacturer.

NOTE
Readme
You can obtain updates to the topic as downloads on the Internet
(https://support.industry.siemens.com/cs/us/en/view/109773483).

Supported antivirus programs

PLCSIM Advanced supports the following virus scanners:
• Symantec Endpoint Protection 14.3
• McAfee Endpoint Security (ENS) 10.6
• McAfee Endpoint Security (ENS) 10.7
• Trend Micro Office Scan 12.0
• Windows Defender (as part of the Windows operating system)
• Qihoo 360 "Safe Guard 12.1" + "Virus scanner"

Known problems and limitations

CrowdStrike Falcon
This software prevents starting a PLCSIM instance.
Solution:
Define exceptions for this software for secure files and folders.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 33
Installing
4.1 Introduction

4.1.3 Licenses

Floating license
PLCSIM Advanced is supplied with a floating type license which is version and/or time-
dependent. The license can be stored locally and shared for a network.

NOTE
Validity
A license is valid for two instances within a PLCSIM Advanced installation.
PLCSIM Advanced V5.0 can only be used with a V5.0 license.

Handling of licenses is described in the Help for SIMATIC Automation License Manager (ALM).

4.1.4 Trial License

A license is available for the limited period of 21 days for S7-PLCSIM Advanced V5.0. After this
Trial License has elapsed, you can no longer start the instance.

Activating the Trial License

As soon as you start an instance in the Control Panel, the Automation License Manager (ALM)
searches the network for a valid license. If a Floating License is available for
S7‑PLCSIM Advanced, the ALM offers the Trial License for activation.

Figure 4-1 Activating the Trial License

S7-PLCSIM Advanced
34 Function Manual, 11/2022, A5E37039512-AE
 Installing
4.1 Introduction

A message at the start of an instance shows the remaining number of days.

Figure 4-2 Trial License

NOTE
Remote access
With remote access you have to confirm the message on the PC on which the instance was
started.

Timeout
If you do not confirm the message for the license in a certain amount of time, the instance is
not started and the following message appears:

Figure 4-3 Timeout

Solution
Start the instance again and confirm the message for the license.

API functions for licenses

PLCSIM Advanced regularly checks whether a license is available. The following return values
provide information about the status (for example, for C++):
• Return values for API function PowerOn() and callback function
OnOperatingStateChanged
– SREC_OK when a floating license is available.
– SREC_WARNING_TRIAL_MODE_ACTIVE when an instance is started with the Trial
License.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 35
Installing
4.1 Introduction

– SREC_WARNING_RUNNING_ON_TIA_PORTAL_TEST_SUITE when no valid license for

PLCSIM Advanced is available, but a "TIA Portal Test Suite" license is available.
PLCSIM Advanced starts with this license. A download from the TIA Portal is possible,
but the instance terminates without feedback if the download was not made from the
TIA Portal Test Suite.
– SREC_NOT_EMPTY when no valid license for PLCSIM Advanced is available, but a
"TIA Portal Test Suite" license is available.
If this is the case, power-up from the Virtual SIMATIC Memory Card is not supported.
• Return value for callback function OnOperatingStateChanged
– SREC_LICENSE_NOT_FOUND when the instance is automatically shut down after
21 days.

4.1.5 Installation log

The log files contain automatically recorded information on the following installation
processes:
• Installation of S7-PLCSIM Advanced
• Change or update of installation of S7‑PLCSIM Advanced
• Repair of an existing installation of S7‑PLCSIM Advanced
• Uninstallation of S7-PLCSIM Advanced
You can evaluate installation errors and warnings using the log files. You can troubleshoot
the installation yourself or contact Siemens Technical Support. Product Support personnel
need information from the installation log to analyze the problem. Send the folder with the
log files as a ZIP file to Support.

Memory location of the installation log

The memory location of the log file depends on the operating system. To open the folder
with the log files, enter the environment variable "%autinstlog%" in the address bar in
Windows Explorer. Alternatively, you reach the appropriate folder by entering
"cd %autinstlog%" in the command line.
The log files are named as follows:
• "SIA_S7-PLCSIM_Advanced_V05@<DATE_TIME>.log"
• "SIA_S7-PLCSIM_Advanced_V05@<DATE_TIME>_summary.log"

Setup_Report (CAB file)

The installation log and other required files are stored in a log file. This file can be found at
"%autinstlog%\Reports\Setup_report.cab".
A separate CAB file with a date ID is saved for each installation.
If you need help during installation, send this CAB file to Siemens Technical Support for
troubleshooting.

S7-PLCSIM Advanced
36 Function Manual, 11/2022, A5E37039512-AE
 Installing
4.3 Installing S7-PLCSIM Advanced

4.2 S7-PLCSIM Advanced

The S7-PLCSIM Advanced package contains the following software:
• S7-PLCSIM Advanced
• Automation License Manager
• S7‑PLCSIM
• .NET Framework
• Npcap

The package is available as a download and on DVD:

• SIMATIC S7-PLCSIM Advanced V5.0 floating license
• Upgrade SIMATIC S7‑PLCSIM Advanced V4.0 → V5.0
After installing PLCSIM Advanced, keep the DVD in a secure, easily accessible place.

Setup program
You can use the Setup program to change, repair, or uninstall your installation, if necessary.

4.3 Installing S7-PLCSIM Advanced

Installation requirements
The Setup program starts automatically with a double-click on the download package or
when you insert the DVD in the drive. Make sure that the following conditions are met before
you begin the installation process:
• The hardware and software of the computer meet the System requirements (Page 31).
• You have administrator rights on the installation computer.
• No other programs are active. This also applies to the Siemens Automation License
Manager and other Siemens applications.
• All TIA Portal versions prior or equal to V14 are uninstalled.

NOTE
Security settings
For licensing via the ALM, you must agree during installation that port 4410 for TCP can be
entered as an exception in the Windows Firewall (procedure step 5).

NOTE
Use of virus scanners
Note the information provided in section Restrictions due to antivirus programs (Page 32).

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 37
Installing
4.3 Installing S7-PLCSIM Advanced

Installing S7-PLCSIM Advanced

To install, follow these steps:
1. Double-click the download package or insert the installation medium into the DVD drive of
your computer. The setup program starts up automatically, provided you have not
disabled the Autostart function on the computer. If the setup program does not start up
automatically, start it manually by double-clicking the "Start.exe" file. The "General
settings" window is displayed.
2. Click the "Read installation notes" button. After you have read the notes, close the file.
3. Click the "Read product information" button. After you have read the information, close
the file.
4. Click "Next". The window with the products to be installed is displayed.
5. Select the products to be installed.
6. Click the "Browse" button if you want to change the default installation path. The
installation path must not exceed 89 characters. The path name must not contain any
UNICODE characters. If you select a different installation path than the default installation
path, the desktop icon may not be displayed correctly.
7. Click "Next". The window with the security settings is displayed. To continue the
installation, select the check box at the bottom of the screen to accept changes to the
security and permissions settings of your system.
8. Click "Next". The window with the installation settings is displayed. You can save or print a
report of the settings by clicking "Save report" or "Print report". Check the settings for
correctness. If you want to make any changes, click "Back" until you reach the point in the
installation process where you want to make changes. Once you have completed your
changes, click "Next".
9. The overview screen shows your installation details. Click the "Install" button. The
installation then starts.
10. After completion of the setup program, you must restart your computer. Select "Yes, I
want to restart the computer now" to restart the computer immediately or select "No, I will
restart computer later" to restart the computer later.
11. Click "Restart". If the computer is not restarted, click "Finish".

Error during installation of S7‑PLCSIM Advanced

The installation of S7-PLCSIM Advanced recognizes an already existing installation of
S7-PLCSIM Advanced.
A requirement for the installation of S7‑PLCSIM Advanced is that no other S7‑PLCSIM
installation prior or equal to TIA Portal version V14 is located on the same computer.
Even though no installation of S7‑PLCSIM is displayed in the "Programs and Features" list, it is
still possible that the computer has an existing installation.
Remedy
Run the setup for S7‑PLCSIM prior or equal to TIA Portal version V14 and uninstall S7-PLCSIM.
When the setup is not available, download the setup files for S7‑PLCSIM via Siemens Mall
(https://support.industry.siemens.com/cs/ww/en/view/65601780).

S7-PLCSIM Advanced
38 Function Manual, 11/2022, A5E37039512-AE
 Installing
4.5 Repairing S7-PLCSIM Advanced

4.4 Changing S7-PLCSIM Advanced

Requirements
The following conditions must be met before you can change the installation:
• The hardware and software of the computer meet the system requirements.
• You have administrator rights on the installation computer.
• No other programs are active.

Procedure
To change your S7-PLCSIM Advanced installation, follow these steps:
1. Double-click the download package or insert the installation medium into the drive. The
setup program starts up automatically, provided you have not disabled the Autostart
function on the computer. If the setup program does not start up automatically, start it
manually by double-clicking the "Start.exe" file.
2. Follow the prompts until you reach the "Configuration" window.
3. Select the "Change upgrade" check box.
4. Follow the remaining prompts to change your installation.
5. Complete the installation operation by restarting your computer.

NOTE
Target directory
You cannot change the target directory because you are changing an existing installation.

4.5 Repairing S7-PLCSIM Advanced

Requirements
The following conditions must be met before you can repair S7-PLCSIM Advanced:
• The hardware and software meet the system requirements.
• You have administrator rights on the installation computer.
• No other programs are active.

Procedure
To repair your installation, follow these steps:
1. Double-click the download package or insert the installation medium into the drive. The
setup program starts up automatically, provided you have not disabled the Autostart
function on the computer. If the setup program does not start up automatically, start it
manually by double-clicking the "Start.exe" file.
2. Follow the prompts until you reach the "Configuration" window. Select the "Repair" check
box.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 39
Installing
4.6 Uninstalling S7-PLCSIM Advanced

3. Follow the remaining prompts to repair your installation.

4. Complete the repair operation by restarting your computer.

4.6 Uninstalling S7-PLCSIM Advanced

You have two options for uninstalling S7‑PLCSIM Advanced:
• Uninstalling the program via the Windows Control Panel
• Uninstalling the entire product via the Setup program.

Uninstalling S7-PLCSIM Advanced using the Windows Control Panel

Proceed as follows:
1. Double-click the "Programs and Features" option in the Windows Control Panel.
2. Right-click on "SIMATIC S7‑PLCSIM Advanced V5.0" and select "Uninstall".
3. Follow the prompts for uninstallation.
4. Complete the uninstallation operation by restarting your computer.
If you do not perform a restart, the Runtime Manager continues running.
If problems occur when uninstalling PLCSIM Advanced using the Windows Control Panel, use
the installation medium for uninstalling.

Uninstalling S7-PLCSIM Advanced using the Setup program

Proceed as follows:
1. Double-click the download package or insert the installation medium into the drive. The
setup program starts up automatically, provided you have not disabled the Autostart
function on the computer. If the setup program does not start up automatically, start it
manually by double-clicking the "Start.exe" file.
If you do not perform a restart, the Runtime Manager continues running.
2. Follow the prompts until you reach the "Configuration" window. Your previous installation
is detected. Select the "Uninstall" check box.
3. Follow the prompts for uninstallation.
4. Complete the uninstallation operation by restarting your computer.
If you do not perform a restart, the Runtime Manager continues running.

Uninstalling additional software

When you uninstall S7-PLCSIM via the setup program, the following software from the
S7-PLCSIM Advanced package remains installed:
• Automation License Manager
• S7‑PLCSIM
• .NET Framework
• Npcap

S7-PLCSIM Advanced
40 Function Manual, 11/2022, A5E37039512-AE
 Installing
4.6 Uninstalling S7-PLCSIM Advanced

If you also want to uninstall this software, use the Windows Control Panel.

NOTE
User data
User data, such as instance data, is not removed by the uninstallation.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 41
Communication paths 5
Local and distributed communication
The following paths are open for communication between STEP 7 V15 or higher and the
instances of PLCSIM Advanced user interfaces:
Table 5-1 Local and distributed communication
Communication paths Local Local Distributed
Protocol Softbus TCP/IP TCP/IP
Communication interface in PLCSIM Advanced PLCSIM PLCSIM Virtual Ether­ PLCSIM Virtual Ether­
net Adapter net Adapter
STEP 7 and instances On a PC / VM On a PC / VM Distributed
Communication...
Between STEP 7 and instances Yes Yes Yes
Among instances Yes Yes Yes
Via OPC UA server and Web server No Yes Yes
Between an instance and a real hardware CPU No No Yes
Between an instance and a real HMI V14 and higher No No Yes
Between an instance and a simulated HMI V14 and Yes Yes Yes
higher
Secure communication...
Via Secure Open User Communication (secure TCP No Yes Yes
communication) V17 and higher
Via OPC UA Server V17 and higher No Yes Yes
Via HTTPS connections to the Web server TIA Portal No Yes Yes
version V17 and higher

Softbus
Softbus is a communication path via a virtual software interface.
The communication is limited to a local PC or a virtual machine. The advantage here is that no
data can be accidentally downloaded to a hardware CPU or communicate with real hardware.

Selecting a communication interface

You program the communication interface via the user interfaces (API) or select them in the
Control Panel under "Online Access". The setting is valid for all generated instances. The
default setting is the communication via "PLCSIM" (Softbus).
Additional network settings are necessary for the distributed communication via the "PLCSIM
Virtual Ethernet Adapter" (TCP/IP), see Network addresses in the simulation (Page 68).

S7-PLCSIM Advanced
42 Function Manual, 11/2022, A5E37039512-AE
 Communication paths
5.1 Local communication

API functions for selecting the communication interface

The following API functions are available for selecting the communications interface:
• GetCommunicationInterface() (Page 148-149)
• SetCommunicationInterface() (Page 148-149)
• CommunicationInterface { get; set; } (Page 148-149)

5.1 Local communication

Local communication can be performed via the Softbus protocol or TCP/IP.
For local communication, the PLCSIM Advanced instance is on the same PC or on the same
virtualization platform such as STEP 7 or another communication partner.

Local communication via Softbus

Local communication is performed via Softbus in PLCSIM Advanced by default.
Local communication via Softbus prevented:
• an accidental download to a hardware CPU
• a communication with real hardware

3&90
67(3

5XQWLPH 5XQWLPH
,QVWDQFH ,QVWDQFH

3/&6,06RIWEXV

Figure 5-1 Local communication via Softbus

Local communication via TCP/IP

Communication is performed via the PLCSIM Virtual Ethernet Adapter, a virtual network
interface that behaves like a real network interface.

NOTE
Local communication via TCP/IP
Make sure that communication is only local and cannot be downloaded to real hardware. For
this, there must be no other adapters of your Windows PC configured in the physical network
and in the subnet protocol of the PLCSIM Virtual Ethernet adapter. Microsoft KB 175767
provides background.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 43
Communication paths
5.2 Communication via TCP / IP

3&90
67(3

5XQWLPH 5XQWLPH
,QVWDQFH ,QVWDQFH

3/&6,09LUWXDO(WKHUQHW$GDSWHU

Figure 5-2 Local communication via TCP/IP

Additional information
See error code SREC_COMMUNICATION_INTERFACE_NOT_AVAILABLE for the function
PowerOn() in the section Operating state (Page 162).

5.2 Communication via TCP / IP

Distributed communication
Distributed communication via TCP/IP means that the PLCSIM Advanced instances
communicate with other devices via the S7-PLCSIM Advanced Virtual Switch . Communication
is possible with real or simulated CPUs, real or simulated HMIs.
The S7-PLCSIM Advanced Virtual Switch must be activated on the PLCSIM Virtual Ethernet
Adapter for instances on the network to be visible.
Each CPU interface can be reached from the PLCSIM Virtual Ethernet Adapter and requires a
unique IP address.
The PLCSIM Virtual Ethernet Adapter must be in the same IP number range (subnet mask) as
the IP address of the controller.
The IP address of the controller must be unique throughout the entire, accessible network.

S7-PLCSIM Advanced
44 Function Manual, 11/2022, A5E37039512-AE
 Communication paths
5.2 Communication via TCP / IP

Example 1: Distributed communication

In the following example, STEP 7 is on a PC and the PLCSIM Advanced instances are on
another PC or a virtual machine. The PCs are connected via their real Ethernet adapter.

1$
 1$7.

3VOUJNF 3VOUJNF
45&1

*OTUBO[
 *OTUBO[


41-$4*.
"EWBODFE
7JSUVBM
4XJUDI

&UIFSOFU
"EBQUFS 1-$4*.
7JSUVBM
&UI
"EBQUFS &UIFSOFU
"EBQUFS

(WKHUQHW7&3,3

Figure 5-3 Distributed communication via Ethernet

Example 2: Distributed communication on a PC

In the following example, STEP 7 is on a PC and the PLCSIM Advanced instances are on a
virtual machine on the same PC. PC and virtual machine are connected via the (virtual)
network adapters.

3&

90
67(3 3/&6,0 3/&6,0
,QVWDQFH ,QVWDQFH

63/&6,0$GYDQFHG9LUWXDO 63/&6,0$GYDQFHG9LUWXDO
1HWZRUNDGDSWHU 6ZLWFK 6ZLWFK
3/&6,09LUWXDO(WK$GDSWHU 1HWZRUNDGDSWHU

909LUWXDO1HWZRUN

Figure 5-4 Distributed communication via network adapters

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 45
Communication paths
5.2 Communication via TCP / IP

Required settings in the "Virtual Machine Settings" dialog using the VMware
visualization platform as an example
If you have opened STEP 7 (TIA Portal) and your project within the virtual machine, enable
the following options for your online connection as follows:
1. Right-click on the VM and select "Settings" or select the menu "VM > Settings".
2. Open the "Virtual Machine Settings" dialog via the menu command "Player > Manage >
Virtual Machine Settings".
3. Then click "Network Adapter" in the "Hardware" tab and activate the following options in
the right window:
– Connected
– Connect at power on
– Bridged: Connected directly to the physical network
– Replicate physical network connection state
4. Click the "Configure Adapters" button and activate your network connection, for example
"Intel(R)82574L LM Gigabit Network Connection".
5. Confirm the setting with OK and exit the "Virtual Machine Settings" dialog with OK.

S7-PLCSIM Advanced
46 Function Manual, 11/2022, A5E37039512-AE
 Communication paths
5.2 Communication via TCP / IP

Example 3: Distributed communication

The following example shows a structure with PCs on which distributed STEP 7,
PLCSIM Advanced instances and virtual machines with PLCSIM Advanced instances are
running.

3& 6HUYHU

90ZDUHY6SKHUH (6;L
,QVWDQFH
 90 90 90 90;

,QVWDQFH ,QVWDQFH
 

6ZLWFK

3&
3&

90ZDUH:RUNVWDWLRQ

67(3 90 90 90

,QVWDQFH ,QVWDQFH ,QVWDQFH

  

Figure 5-5 Distributed communications with PCs and virtual machines

5.2.1 Communication via TCP/IP in Multi-Adapter Network Mode (non-

promiscuous mode)
In Single Adapter Network Mode (promiscuous mode), the network adapter reads all
incoming telegrams. The network adapter also reads telegrams that are not intended for the
network adapter. The network adapter then forwards the data to the operating system for
processing.
In Multi-Adapter Network Mode (non-promiscuous mode), the evaluation of MAC addresses
ensures that only data intended for the network adapter reaches the operating system.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 47
Communication paths
5.2 Communication via TCP / IP

In PLCSIM Advanced versions <V5.0, the use of Single Adapter Network Mode (promiscuous
mode) was necessary for communication with the "outside world". For example, the mode
was necessary for scenarios that met the following 3 conditions:
• You access another virtual machine from one virtualization platform.
• The virtualization platform runs one instance of PLCSIM Advanced.
• TIA Portal is executed on the virtual machine.
However, on virtualization platforms or corporate networks, it is often not permitted to run
the network interface of the PC in Single Adapter Network Mode (promiscuous mode) for
security reasons.

Overview
The following figure provides an overview of the possibilities and differences between the
following communication options:
• Local TCP/IP communication
• Single Adapter Network Mode (promiscuous mode)
• Multi-Adapter Network Mode (non-promiscuous mode)

1-$4*.
OFUXPSLJOH

4PGUCVT
MPDBM
DPNNVOJDBUJPO 51$*1
DPNNVOJDBUJPO "QQMJDBUJPO

.PEF
TFMFDUJPO

QPTTJCMF
WJB
"1*

BOE
6*
/FX

5$1*14JOHMF
"EBQUFS
5$1*1.VMUJ"EBQUFS

.FNPSZCBTFE
51$*1
MPDBM
/FUXPSL
.PEF /FUXPSL
.PEF
MJNJUFE

GVODUJPOBMJUZ

"MM
QPTTJCJMJUJFT
PG
5$1*1

"MM
QPTTJCJMJUJFT
PG
5$1*1
DPNNVOJDBUJPO

"MM
QPTTJCJMJUJFT
PG
MPDBM
DPNNVOJDBUJPO
BWBJMBCMF BWBJMBCMF
5$1*1
DPNNVOJDBUJPO
1SPNJTDVPVT
NPEF
JT
6TF
JO
UIF
DMPVE

BWBJMBCMF SFRVJSFE QPTTJCMF
&YUFSOBM
OFUXPSLT
OPU
$BOOPU
CF
VTFE
GPS
QVCMJD
/FUXPSL
TFQBSBUJPO

WJTJCMF DMPVE
FOWJSPONFOUT QPTTJCMF
.PEF
GPS

&YUFSOBM
OFUXPSLT
OPU
WJSUVBMJ[FE
QVCMJD
DMPVE

WJTJCMF

FOWJSPONFOUT
&YUFSOBM
OFUXPSLT

WJTJCMF

Figure 5-6 PLCSIM networking

Applications
The following applications describe how you can also communicate in Multi-Adapter Network
Mode (non-promiscuous mode). You communicate in this mode by performing a one-to-one

S7-PLCSIM Advanced
48 Function Manual, 11/2022, A5E37039512-AE
 Communication paths
5.2 Communication via TCP / IP

mapping of the MAC addresses between the CPU network interfaces and the network
adapters of the PC.
The following applications assume that you are working in an environment where security
restrictions apply and you have therefore switched to Multi-Adapter Network Mode (non-
promiscuous mode).
Application 1:
You start multiple instances. Each CPU interface is assigned to the MAC address of the
respective physical or virtual PC adapter.
Precondition: Each interface of a running instance is assigned to its own physical or virtual PC
interface (one-to-one mapping).

.VMUJ"EBQUFS
/FUXPSL
.PEF %FEJDBUFE
NBQQJOH
PG
BO
JOUFSGBDF

.VMUJQMF
OFUXPSL
BEBQUFST
NBQQFE
POUP
B
TJNVMBUJPO
JOTUBODF POUP
BO
BEBQUFS
1$

"QQMJDBUJPO 1-$4*.
1PTTJCJMJUZ
PG
1-$4*.
45&1
 *OTUBODF
 *OTUBODF

DPNNVOJDBUJPO
CFUXFFO
$16

$16

EFEJDBUFE
$16
JOUFSGBDFT
0OMZ

JOUFSGBDFT
VTFE
PG
POF
JOUFSGBDF
UP

9 9 9
BOPUIFS
XJUIPVU
IBWJOH

UP
TFU
QSPNJTDVPVT
NPEF

JO
UIF
7.
JOGSBTUSVDUVSF
*OUFSGBDF
NBQQJOH

41-$4*.
"EWBODFE
7JSUVBM

4XJUDI
41-$4*.
"EW 41-$4*.
"EW 41-$4*.
"EW

1-$4*.
7JSUVBM
&UI
"EBQUFS 7JSUVBM
4XJUDI 7JSUVBM
4XJUDI 7JSUVBM
4XJUDI
/FUXPSL
BEBQUFS /FUXPSL
BEBQUFS /FUXPSL
BEBQUFS

/FUXPSL
BEBQUFS

4XJUDI

Figure 5-7 Application 1

Application 2:
The following application shows the behavior with multiple instances that have the same
MAC addresses. Each CPU interface is assigned to the corresponding physical or virtual PC
adapter.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 49
Communication paths
5.2 Communication via TCP / IP

The scenario is only valid if only one instance is running at a time.

0XOWL$GDSWHU1HWZRUN0RGH 'HGLFDWHGPDSSLQJRIDQLQWHUIDFH
0XOWLSOHQHWZRUNDGDSWHUVPDSSHGRQWRDVLPXODWLRQLQVWDQFH RQWRDQDGDSWHU
3&
$SSOLFDWLRQ
90
3RVVLELOLW\RIFRPPXQLFD
WLRQEHWZHHQGHGLFDWHG 3/&6,0
3/&6,0
&38LQWHUIDFHVRIRQH ,QVWDQFH
,QVWDQFH
LQWHUIDFHWRDQRWKHU &38
&38
ZLWKRXWKDYLQJWRVHW 2QO\LQWHUIDFHVXVHG
SURPLVFXRXVPRGHLQWKH ; ; ;
90LQIUDVWUXFWXUH ,QWHUIDFHPDSSLQJ

63/&6,0$GYDQFHG9LUWXDO
1HWZRUNDGDSWHU 6ZLWFK
3/&6,09LUWXDO(WK$GDSWHU 63/&6,0$GY 63/&6,0$GY 63/&6,0$GY
9LUWXDO6ZLWFK 9LUWXDO6ZLWFK 9LUWXDO6ZLWFK
Y1HWZRUNDGDSWHU Y1HWZRUNDGDSWHU Y1HWZRUNDGDSWHU

9LVXDOL]HGLQIUDVWUXFWXUHVZLWFKY1,&

90
3/&6,0
,QVWDQFH
&38
2QO\LQWHUIDFHVXVHG
;
,QWHUIDFHPDSSLQJ

3/&6,09LUWXDO6ZLWFK
3/&6,0
3/&6,09LUWXDO(WK$GDSWHU 9LUWXDO6ZLWFK
Y1HWZRUN$GDSWHU

Figure 5-8 Application 2

S7-PLCSIM Advanced
50 Function Manual, 11/2022, A5E37039512-AE
 Communication paths
5.2 Communication via TCP / IP

Procedure
For external communication in Multi-Adapter Network Mode (non-promiscuous mode), the
following steps are necessary depending on your application.
1. Use the following instruction to switch to Multi-Adapter Network Mode (non-promiscuous
mode):
SetNetworkMode(SRCM_VSWITCH_NON_PROMISCUOUS)
2. To register a new instance, call RegisterInstance().
3. To select which PC interface is assignable to which CPU interface by means of a list of PC
interfaces, call GetNetInterfaces().
4. To execute an interface mapping between CPU and PC interface, call
SetNetInterfaceMapping(0, 23).
5. To check whether the configuration is correct, call CheckNetInterfaceMappig().
6. To start the instance, call PowerOn().
Before starting, the instance performs an internal check.

NOTE
Setting a storage path for a new instance
If you use the SetStoragePath() function to set a storage path for a new instance, call
this function before the MAC address is set. Otherwise, the MAC address is discarded.
This procedure is also valid for the stored CPU type and CPU serial number.
The CleanupStoragePath() function deletes not only the storage path but also the
assignments of the network interfaces.

Examples in C++
The following examples show possible network configurations in C++.
For scenarios with more than one adapter, make sure to register the instance with a CPU that
has the required number of interfaces. In the following examples we use three interfaces.
Therefore we register the instance with a CPU with 3 PROFINET interfaces, such as the CPU
1518-4 PN/DP.
Example 1: Simplified settings

#include "SimulationRuntimeApi.h"

ISimulationRuntimeManager* rtm = nullptr;

IInstance* instance0 = nullptr;
IInstance* instance1 = nullptr;
ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;

//init connection
InitializeApi(&rtm);

//set NON-P mode

rtm->SetNetworkMode(ECommunicationMode::VSWITCH_NON_PROMISCUOUS);

rtm->RegisterInstance(ECPUType::SRCT_1518, &instance0);
instance0->SetNetInterfaceMapping(EPLCInterface::IE1, L"Ethernet");

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 51
Communication paths
5.2 Communication via TCP / IP

instance0->SetNetInterfaceMapping(EPLCInterface::IE1, L"Ethernet
2");
instance0->SetNetInterfaceMapping(EPLCInterface::IE1, L"Ethernet
3");
instance0->PowerOn(60000);

rtm->RegisterInstance(ECPUType::SRCT_1518, &instance0);
instance1->SetNetInterfaceMapping(EPLCInterface::IE1, L"Ethernet
4");
instance1->SetNetInterfaceMapping(EPLCInterface::IE1, L"Ethernet
5");
instance1->SetNetInterfaceMapping(EPLCInterface::IE1, L"Ethernet
6");
instance1->PowerOn(60000);

ShutdownAndFreeApi(rtm);

Example 2: Complete settings

#include <iostream>
#include "SimulationRuntimeApi.h"

ISimulationRuntimeManager* rtm = nullptr;

IInstance* instance0 = nullptr;
IInstance* instance1 = nullptr;
ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;

//init connection
InitializeApi(&rtm);

//set NON-P mode if mode is not non-promiscuous

ECommunicationMode netMode;
rtm->GetNetworkMode(&netMode);
if (netMode != ECommunicationMode::VSWITCH_NON_PROMISCUOUS)
{
rtm->SetNetworkMode(ECommunicationMode::VSWITCH_NON_PROMISCUOUS);
}

rtm->RegisterInstance(ECPUType::SRCT_1518, &instance0);
rtm->RegisterInstance(ECPUType::SRCT_1518, &instance1);

//gather network interfaces in computer

//get count of network interfaces
UINTcount;
result = rtm->GetNetInterfaces(nullptr, &count);

//get actual network interfaces

std::unique_ptr<SNetInterfaceInfo[]> netInterfaces =
std::make_unique<SNetInterfaceInfo[]>(count);
result = rtm->GetNetInterfaces(netInterfaces.get(), &count);

// map desired interface on instance interface

// each instance interface must have unique or no mapping

S7-PLCSIM Advanced
52 Function Manual, 11/2022, A5E37039512-AE
 Communication paths
5.2 Communication via TCP / IP

// we can map interface by these three overloads

//
// interfaceIndex
result = instance0->SetNetInterfaceMapping(EPLCInterface::IE1,
netInterfaces.get()[0].interfaceIndex);
// friendly name
result = instance0->SetNetInterfaceMapping(EPLCInterface::IE2,
netInterfaces.get()[1].interfaceName);
// MAC address
result = instance0->SetNetInterfaceMapping(EPLCInterface::IE3,
&netInterfaces.get()[2].MACAddress);

//set mapping on second instance

result = instance1->SetNetInterfaceMapping(EPLCInterface::IE1,
&netInterfaces.get()[3].MACAddress);
result = instance1->SetNetInterfaceMapping(EPLCInterface::IE2,
&netInterfaces.get()[4].MACAddress);
result = instance1->SetNetInterfaceMapping(EPLCInterface::IE3,
&netInterfaces.get()[5].MACAddress);

// we can also check what is mapped on the interface

INT32 mappedInterfaceIndex =
instance0->GetNetInterfaceMapping(EPLCInterface::IE1);
if(mappedInterfaceIndex == 0)
{
std::cout << "No mapping is set";
}

if (mappedInterfaceIndex == netInterfaces.get()[0].interfaceIndex)
{
std::cout << netInterfaces.get()[0].interfaceName << "is mapped on
EPLCInterface::IE1";
}

//set S7-PLCSIM Advanced Virtual Switch according to set mapping

// !! requires elevated (admin) mode !!
rtm->SetNetInterfaceBindings();

//check if setting is valid - optional - CheckNetInterfaceMapping()

function is also called inside PowerOn()
result = instance0->CheckNetInterfaceMapping();
if (result != SREC_OK)
{
returnresult;
}

instance0->PowerOn(60000);
instance1->PowerOn(60000);

ShutdownAndFreeApi(rtm);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 53
Communication paths
5.3 Enable distributed communication

5.3 Enable distributed communication

The default setting limits the S7-PLCSIM Advanced Virtual Switch to local communication
only. For distributed, i.e. cross-computer, communication to be possible, you must activate
the S7-PLCSIM Advanced Virtual Switch for a real network adapter.

NOTE
Network adapter
Make sure that the S7-PLCSIM Advanced Virtual Switch is activated for only one network
adapter. The Control Panel of PLCSIM Advanced checks the activation and may report an
incorrect configuration (error code -50).

Activating the S7-PLCSIM Advanced Virtual Switch

To make the PLCSIM instances visible on the network and to reach other devices, activate the
S7-PLCSIM Advanced Virtual Switch in the Control Panel of PLCSIM Advanced or under
Windows:
1. To do this, open the "Network and Sharing Center" in the Windows Control Panel.
2. Open the properties of the desired network adapter, for example, for the "Local Area
Connection".
3. Select the check box for the "S7-PLCSIM Advanced Virtual Switch" and confirm with OK.

S7-PLCSIM Advanced
54 Function Manual, 11/2022, A5E37039512-AE
 Communication paths
5.3 Enable distributed communication

Figure 5-9 Activating the S7-PLCSIM Advanced Virtual Switch

Accessible devices
On the local computer, the PLCSIM Advanced instances are always displayed as accessible
devices of the PLCSIM Virtual Ethernet adapter.
The PLCSIM Advanced instances are not visible locally via the configured second adapter,
even if the S7-PLCSIM Advanced Virtual Switch is activated.

Figure 5-10 Accessible devices on the Virtual Ethernet Adapter

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 55
Communication paths
5.3 Enable distributed communication

Distributed communication via WLAN

When using distributed communication via WLAN, it may happen that the Npcap program
library installed by PLCSIM Advanced does not work with the integrated WLAN adapter of the
PC. In this case, no WLAN connection can be established.
Remedy
Use the wired network adapter of the PC/notebook and connect a WLAN adapter upstream.

S7-PLCSIM Advanced
56 Function Manual, 11/2022, A5E37039512-AE
Simulating 6
6.1 Simulate CPU

6.1.1 Basic procedure for the simulation

The following overview shows the basic steps to perform simulation with an instance of a
virtual controller.

Requirements
The following requirements must be met for starting simulation via local communication:
• STEP 7 as of V14 and S7-PLCSIM Advanced V5.0 are installed on the same PC.
• The CPU hardware is configured in STEP 7.

NOTE
Enable simulation support
In the "Protection" tab in the properties of the project in STEP 7, select the check box "Support
simulation during block compilation"; see Support simulation (Page 22).

Create and activate an instance via the Control Panel

• Open PLCSIM Advanced Control Panel (see section Control Panel - User interface (Page
57))
• Open the "Start Virtual S7-1500 PLC" options
• Enter a name for an instance
• Selecting the CPU family
• Create an instance using the "Start" button

In STEP 7, perform the download and start the simulation

• Download the program to the virtual controller (see section Downloading a STEP 7 project
(Page 65))
• Switch the virtual controller to RUN to start the simulation
• Perform diagnostics

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 57
Simulating
6.1 Simulate CPU

6.1.2 Control Panel - User interface

6.1.2.1 S7-PLCSIM Advanced Symbol

After installing PLCSIM Advanced, the following icons are on the Windows desktop:

Figure 6-1 PLCSIM Advanced Symbol

A double-click on the symbol opens the Control Panel for PLCSIM Advanced. If the Control
Panel is in the background, it is moved to the foreground with another double-click.
You can use Windows functions to permanently display the icon in the system tray of the
taskbar.

Opening a graphical interface

Right-clicking the icon in the taskbar opens the Control Panel with the quick view. Double-
click to start the Control Panel as a window.

Figure 6-2 Opening a graphical interface

You can use the mouse-over function to display messages about the current status of the
instances.

Figure 6-3 Example: Message in the taskbar

S7-PLCSIM Advanced
58 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

6.1.2.2 Graphical interface

The graphical interfaces synchronize by means of API commands. They are optional and are
not needed to operate PLCSIM Advanced via the API.
S7-PLCSIM Advanced V5.0 provides the Control Panel with two views.
• Control Panel as quick view
Right-clicking on the icon in the taskbar opens the quick view.
Clicking on an empty area on the desktop minimizes the quick view. The instances are not
affected.
• Control Panel as window
Double-clicking the icon on the desktop or in the taskbar opens the Control Panel as a
window.

Control Panel as window

Unlike the quick view, you can operate the Control Panel with the buttons in the title bar.
You can close this window without exiting the simulation Runtime process.

① Stores the Control Panel as icon in the taskbar.

② No function. The window size cannot be changed.
③ Closes the Control Panel and stores it in the system tray of the taskbar.
The instances and the simulation Runtime process remain active.
This function therefore differs from the Exit function .
The Exit function switches off the local instances, logs them off and closes the Control Panel.
④ Pins the Control Panel on the screen so that it remains in the foreground.
Figure 6-4 Control Panel: Title bar

6.1.2.3 S7-PLCSIM Advanced Control Panel

The S7-PLCSIM Advanced Control Panel is only available in English.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 59
Simulating
6.1 Simulate CPU

Design
The figure below shows the structure of the S7-PLCSIM Advanced Control Panel.

 











① Online access Switch to select the communication interface

② TCP/IP commu­ Selection of network adapter for distributed communication
nication
③ Virtual time Slider to adjust the scaling factor

S7-PLCSIM Advanced
60 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

④ Strict Motion Here you disable the overrun detection for Motion Control (OB MC-Servo [OB91]).
Timing When the check box is selected (default), overruns are detected.
However, you can only change the setting of the overrun detection in the Control Panel for as
long as no instance has been registered yet. The set behavior then applies to all subsequent
registered instances.
You can adapt the behavior for individual instances via the API.
⑤ Start Virtual Opens and closes the input boxes for creating the instance (virtual controller).
S7-1500 PLC
• Name of the Here you enter a unique name for the instance. Enter a minimum of 3, a maximum of 63 charac­
instance ters. If the name is unique in the network, the button "Start" is enabled.
• IP address The input boxes are visible when you switch the communication interface to "PLCSIM Virtual Eth­
• Subnet mask ernet Adapter". The IP address is entered automatically.
• Standard
gateway
• CPU family Here you select the CPU family to be simulated.
• "Start" button Create with the button and start the instance.
⑥ Buttons Buttons for operating the selected instances.
⑦ Instance list The list shows the available local instances. The instances can be resorted using the mouse curs­
or.
⑧ LED displays The meaning of the LED is displayed when you move the mouse over it.
⑨ Icons Icons for operating the instance
⑩ Runtime Man­ Here you open a port on the local PC.
ager Port
⑪ Virtual SIMATIC You open the storage location of the virtual memory card with a double-click to the left of "...".
Memory Card You can change the path to the virtual memory card with a double-click on "...".
⑫ Display messages Here you disable the PLCSIM Advanced messages in the Windows task bar for the duration of the
operation.
⑬ Function manual This is where you open the S7-PLCSIM Advanced Function Manual in a standard PDF viewer.
⑭ Exit Exit logs off all instances and closes the Control Panel.
Figure 6-5 Control Panel

Switch for communication interface

Use the switch to select the communication interface for all instances to be created:
• "PLCSIM" corresponds to the local communication via softbus (default).
• "PLCSIM Virtual Ethernet Adapter" corresponds to the communication via TCP/IP.
The setting applies to all other instances. The selected communication interface for starting
an instance is maintained until all instances are shut down.
When an instance is already started, it sets "its" communication interface as the default for
other instances.
To change the communication interface, switch off all instances and enable the other
interface.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 61
Simulating
6.1 Simulate CPU

TCP/IP communication
You can select a real network adapter from the drop-down list during operation. You thus
activate the S7-PLCSIM Advanced Virtual Switch and establish TCP/IP communication between
the instances and the real network.
The <Local> setting deactivates the S7-PLCSIM Advanced Virtual Switch and disconnects the
instances from the real network. Only local TCP/IP communication over virtual adapter is
possible in this case.

Virtual time
You must enable the virtual time for each instance using the icon . Use the slider or the
mouse wheel to select the scaling factor for the virtual time.
The selected scaling factor applies to the instances for which the virtual time is enabled.
Clicking on "Off" restores the default (1) again. For more information see Virtual and Real
Time (Page 87).

Creating an instance (locally) and starting it

To create an instance, enter a unique name under "Instance Name".
The following rules apply to the creation of an instance name:
• The maximum length of the instance name is < 64 characters.
• The instance name must not start with a dot (.) or a space.
• The instance name must contain at least one of the characters from the following groups:
– Uppercase letters from A to Z
– Lowercase letters from a to z
– Numbers from 0 to 9
– Special characters: Spaces . _ - + @ ! ; # ~ ' ( ) [ ] { } ^ $ % &

NOTE
If the name already exists in the folder of the Virtual SIMATIC Memory Card, this already
existing instance is started.

In the "PLC family" drop-down list, you select a CPU family:

• S7-1500
• S7-1500R/H
• ET 200SP
• ET 200pro
Create the instance with the "Start" button and start this instance.
The instance/virtual controller is initialized with the first download from the TIA Portal.

Instance list
The list contains the instances that are available locally on the PC or virtualization platform.
Instances that have already been started on the runtime API are detected and displayed in the
list.

S7-PLCSIM Advanced
62 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

Select the operating state of the instance with the "RUN" and "STOP" buttons. Select one or
more instances for this purpose. Perform a memory reset with the "MRES" button.
The LED displays show the status of the instance that corresponds to those of the hardware
CPU.
RUN and STOP are displayed depending on the current operating state of the instance.
You can "operate" the instance with icons:
• Enable virtual time, apply scaling factor for the virtual time
• Disable virtual time
• Switch on instance ("PowerOn")
• Switch off instance ("PowerOff")
• Switch off instance and log off from Runtime Manager ("Unregister")

Runtime Manager Port

A remote connection can be established to another Runtime Manager via the specified port.
The value must be greater than 1024.
If you select the check box, the port remains stored. You can use the remote connection
without having to make this setting every time you start the Control Panel. To use this
functionality, the Control Panel must be started and running in the background.

Virtual SIMATIC Memory Card

The user program, the hardware configuration and the retentive data is stored on the Virtual
SIMATIC Memory Card. Use the buttons to adapt the path to the virtual memory card or open
the previously saved path in an Explorer window.

Display messages
Each time the Panel starts, help information and messages relating to the Control Panel are
displayed, for example, when changing the IP address or when a license is missing. Disable
the display if you do not need the messages.

Exit - Log off all instances

The command switches off all local instances on the PC or the VM and logs them off from the
Runtime Manager and closes the Control Panel.
This command closes the Runtime Manager if there are no remote connections to other
Runtime Managers.
If the Runtime Manager has remote connections to instances on additional PCs, these
instances and the Runtime Manager continue to run.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 63
Simulating
6.1 Simulate CPU

6.1.2.4 Importing instances

Requirement
This function is only available if you do not start the Control Panel with admin rights.

Importing instances
You can use the drag-and-drop function to import instances from a folder directly into the
instance list of the Control Panel.
1. Open a folder with instances, for example, using the "Virtual SIMATIC Memory Card"
button.
2. Select one or more instances and drag them into the highlighted area.

S7-PLCSIM Advanced
64 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

Figure 6-6 Control Panel: Importing instances

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 65
Simulating
6.1 Simulate CPU

6.1.3 Downloading a STEP 7 project

Requirements
You can download the STEP 7 project to the virtual controller when the following conditions
are met:
• The instance is created via the Control Panel.
• The check box "Support simulation during block compilation" is selected.

Selecting the communication interface

In the Download dialog box, select the PG/PC interface:
• "PLCSIM" for download via Softbus
• "Siemens PLCSIM Virtual Ethernet Adapter" for download via TCP/IP
• For distributed communication the real adapter that is connected to the network

Display in the download dialog

The dialog in STEP 7 at the first download of the CPU shows the compatible PLCSIM Advanced
instances.
If the instance has not yet been configured after the first download only one interface is
visible and it appears with the device type "CPU-1500 Simulation".
If the instance has been configured, the number of interfaces visible is determined by the
number the CPU type has.
The dialog shows the interfaces of an instance with their IP addresses.

Perform download
To download a project to the virtual controller, proceed as follows:
1. Select the PG/PC interface.
2. Click "Download".
→ In the "Load preview" window, STEP 7 shows the message "The downloads are
performed on a simulated CPU".
→ After the first download, the PLCSIM Advanced instance displays the CPU type.

S7-PLCSIM Advanced
66 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

Figure 6-7 Example: Download via the "PLCSIM Virtual Ethernet Adapter" (TCP/IP) after naming

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 67
Simulating
6.1 Simulate CPU

NOTE
Loading an additional CPU to one instance
Example in TIA Portal:
1. You assign an IO device (e.g. IM 153-4 PN) to a CPU (e.g. CPU 1518-4 PN/DP).
2. You add another CPU of the same product family (e.g. CPU 1511-1 PN) to your project.
3. You start the simulation with online access via PLCSIM Virtual Ethernet Adapter.
4. You load the configuration onto the CPU 1518-4 PN/DP with the assigned IO device (IM
153-4 PN) via the interface X1 with TCP/IP.
5. You load the configuration of the other CPU (CPU 1511-1 PN) using the same instance.
If you go online after this scenario and check the entries in the diagnostic buffer under
"Online & Diagnose", the following message appears: "Error: Multi-interface mismatch -
Inconsistent parameterization for sending LLDP data)."
Solution:
To avoid this error scenario, use one of the following solutions
• Enable the button "Use IEC V2.2 LLDP mode" for the PROFINET interface [X1] for both
CPUs (CPU 1511-1 PN and CPU 1511-1 PN).
You will find the button in the "General" tab under PROFINET interface [X1] > Advanced
options > Interface options.
• After the second download, log out the instance and log it in again.
• Switch the instance off and on again.

NOTE
Note on SingleStep_CP operating mode
Downloading software changes in RUN mode.
If you perform a software download in RUN mode in SingleStep_CP operating mode, the
download may not be possible and the simulation may stop. An overload during the
download in RUN may be the reason for this.
Solution:
1. Use the "Virtual Time Scaling" function and select a low scaling factor (e.g. scaling factor
of 0.25).
2. Provide sufficient resources to increase the runtime performance and the S7-PLCSIM
Advanced communication performance.

S7-PLCSIM Advanced
68 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

6.1.4 Network addresses in the simulation

6.1.4.1 Siemens PLCSIM Virtual Ethernet Adapter

IP address
At the PLCSIM Virtual Ethernet Adapter you assign a static IP address or obtain an IP address
via DHCP (default).

MAC address
A randomly generated MAC address is assigned to the PLCSIM Virtual Ethernet Adapter during
its installation.
PLCSIM Advanced only uses MAC addresses that are designated as "locally administered"
(bit 2 in LSB).
The Siemens-specific prefix is: 02-1B-1B
Three bytes follow, which are determined at random.
Storage location
This MAC address is stored in the registry key "PlcsimvminiMacAddress".
You can overwrite this value.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 69
Simulating
6.1 Simulate CPU

6.1.4.2 PLCSIM Advanced instances

Detect CPUs and instances

If Ethernet interfaces of CPUs and PLCSIM Advanced instances are mixed in a network, the
instances are briefly recognizable by the "PLCSIM" suffix of the device type during the search
for accessible nodes in STEP 7.

Figure 6-8 Search for the devices that are accessible in STEP 7

S7-PLCSIM Advanced
70 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

Structure of the MAC address for an instance

The following figure shows the structure of the dynamically generated, locally managed MAC
address:

,3DGGUHVVYLUWXDODGDSWHU

%\WH %\WH %\WH %\WH %\WH %\WH

%LW 8QLTXHZRUOGZLGH
 0DQDJHGORFDOO\ 1XPEHURIWKH 1XPEHURIWKH
LQVWDQFH (WKHUQHW
LQWHUIDFH

Figure 6-9 Structure of the MAC address for an instance

The MAC address tells you the PC on which a PLCSIM Advanced instance has been started.

Assignment of the Ethernet interfaces

Port configurations of the Ethernet interfaces cannot be simulated in PLCSIM Advanced V5.0.
Topological interconnection is not supported. A MAC address for a port is reserved internally
for each Ethernet interface.

Table 6-1 Assignment of the Ethernet interfaces, for example, for a CPU 1518‑4 PN/DP
Ethernet interface Last digit of the MAC Address
IE 1 0
IE 1 / Port 1 1
IE 2 2
IE 2 / Port 1 3
IE 3 4
IE 3 / Port 1 5

Example
02-C0-A8-00-83-10 means:
02 → locally managed MAC address of a PLCSIM Advanced instance
C0-A8-00-83 → IP of the Siemens PLCSIM Virtual Ethernet adapter = 192.168.0.131
1 → Instance 1
0 → Ethernet interface IE 1
If no Virtual SIMATIC Memory Card is loaded during startup of PLCSIM Advanced, the
interfaces of PLCSIM Advanced display instances with their locally managed MAC address.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 71
Simulating
6.1 Simulate CPU

6.1.5 Simulate peripheral I/O

The Runtime API writes to and reads from a memory area. This memory is synchronized with
the internal process image of the virtual S7‑1500 controller at the cycle control point and
when calling cyclic and acyclic OBs (process image partitions, interrupts, events). The direct
I/O accesses are made to this memory area. Only one process can access this memory at a
given time.
The virtual controller must be in RUN mode to apply changes made by the API.

NOTE
Dominance of the API when synchronizing
The API dominates when synchronizing. If the user program writes to the same address range
as the API, the changes of the API overwrite those of the virtual controller.

6.1.6 Simulate communication

6.1.6.1 Communication services that can be simulated

PLCSIM Advanced V5.0 supports the following communication options:

Table 6-2 Supported communication options
Communications options Functionality / instructions
PG communication On commissioning, testing, diagnostics
Open communication using TCP/IP • TSEND_C / TRCV_C
• TSEND / TRCV
• TCON1
• T_DISCON
Secure Open user communication (secure TCP commu­ • TSEND_C / TRCV_C
nication) • TCON
Open communication using ISO-on-TCP • TSEND_C / TRCV_C
• TSEND / TRCV
• TCON
• T_DISCON
Open communication via UDP2 • TUSEND / TURCV
• TCON
• T_DISCON
Communication via Modbus TCP3 • MB_CLIENT
• MB_SERVER
E-mail2, 3 • TMAIL_C
S7 communication • PUT / GET
• BSEND / BRCV
• USEND / URCV
OPC UA server2, 3 Secure data exchange with OPC UA clients

S7-PLCSIM Advanced
72 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

Web server2, 3 Data exchange via HTTP, HTTPS

1 When the "PLCSIM" interface (Softbus) is set, communication is performed internally via ISO-on-TCP.
2 Communication is only possible via the communication interface "PLCSIM Virtual Ethernet Adapter" (TCP/IP).
3 "Access to PLC via communications module" is not supported.

Special conditions apply when communicating with TUSEND/TURCV, see Restrictions for
communications services (Page 339).

NOTE
Secure Communication
When simulating communication services, also consider the basics of secure data exchange
(Secure Communication). For detailed information on Secure Communication, refer to the
Communication (https://support.industry.siemens.com/cs/ww/en/view/59192925) function
manual.

Additional information
For more information on the various communication services, please refer to the Communic­
ation function manual (https://support.industry.siemens.com/cs/ww/en/view/59192925).

Restrictions for MODBUS communication via Softbus

For communication via Softbus, use the supported Modbus versions shown in the following
table or, alternatively, communication via TCP/IP.

Table 6-3 Modbus communication via Softbus

MODBUS TCP Lib MB_CLIENT MB_SERVER SOFTBUS
V6.0 V6.0 V5.3 ✓
V5.2 V5.2 V5.2 x
V5.1 V5.1 x
V5.0 V5.0 x
V4.2 V4.1 V4.2 x
V4.1 V4.1 x
V4.0 V4.0 ✓
✓ = Communication possible
x = Communication not possible

TMAIL_C
When the TMAIL_C instruction is used, the mail server might not be located on the same PC
as the PLCSIM Advanced instance.
Solution
Make the mail server available via a different PC in the network.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 73
Simulating
6.1 Simulate CPU

6.1.6.2 Communication between instances

PLCSIM Advanced supports communication between instances. An instance may be a

simulation in PLCSIM Advanced V2.0 or a simulation in WinCC Runtime as of V14.
You can run two instances of PLCSIM Advanced, which then communicate with each other.
To enable instances to communicate with each other, they must have a unique IP address.

Each simulated CPU requires a unique IP address

If the CPUs have the same IP address, you cannot run multiple simulations. Each simulated
CPU requires a unique IP address.
Make sure that the IP addresses in STEP 7 are unique before you start your simulations.

T-block instructions and UDP

PLCSIM Advanced simulates T-block connections for which the UDP protocol is configured
only via the communication interface "PLCSIM Virtual Ethernet Adapter" (TCP/IP).

T-block instructions and data segmentation

PLCSIM Advanced implements T-block instructions with a data segmentation of 4 KB. A real
CPU has data segmentation of 8192 bytes.
If you send more than 4 KB in a single TSEND instruction and receive data in ad hoc mode
with a TRCV instruction, the TRCV instruction generates new data with only 4 KB. You must
perform the TRCV instruction several times to receive additional bytes.

6.1.7 Provide project data offline for simulation

Simulations regardless of STEP 7

To perform simulations independent of STEP 7, you can save the user program and the
hardware configuration in STEP 7 in a folder.

Saving retentive data securely

The retentive data is automatically saved when the virtual controllers are shut down.
To save the retentive data safely in the virtual SIMATIC Memory Card, the instances must be
correctly logged off. Use one of the following functions for this:
• The PowerOff() API function
• In the Control Panel the functions
– "Switch off instance"
– "Log off instance"
– or the Exit function "Log off all instances"

S7-PLCSIM Advanced
74 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.1 Simulate CPU

Provide project data offline

1. Create a "User-defined Card Reader" for your project data in the "Card Reader/USB storage"
folder in the project tree of STEP 7 for the CPU.
2. In the "Load preview" dialog for the target device, select "PLC Simulation Advanced" as an
action, click in the selection box for this.
→ The project is saved to the <Virtual Memory Card>\SIMATIC.S7S\OMSSTORE folder.

Figure 6-10 Preview of download dialog

3. Save the folder "\SIMATIC.S7S" with the project data to a medium of your choice.

Figure 6-11 Add card reader

Provide project data for simulation

1. On the PC on which PLCSIM Advanced is installed, create the folder "\SIMATIC_MC" in the
folder in which the instance saves its data.
2. Move the "\SIMATIC.S7S" folder to the folder you have created.
→ The instances can be started with the project data.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 75
Simulating
6.2 Simulate CPU with ODK functionality

API functions
The project data can be used for an instance via the user interface. Use one of the following
functions for this:
API functions
• GetStoragePath() (Page 153)
• StoragePath { get; set; } (Page 153)
• ArchiveStorage() (Page 153)
• RetrieveStorage() (Page 153)

6.2 Simulate CPU with ODK functionality

Introduction
The ODK is an engineering tool that allows the creation of high-level language applications
for S7-1500 CPUs. You use it to generate function libraries that are used in the STEP 7 user
program.
The ODK for PLCSIM Advanced V5.0 supports the C++ programming language.
You can find the description of the ODK in the Programming and Operating Manual "S7‑1500
Open Development Kit 1500S", as of V2.5 Edition 12/2017: SIMATIC STEP 7 (TIA Portal)
Options ODK 1500S (https://support.industry.siemens.com/cs/ww/en/ps/13914/man)
Section 6 "Development of a CPU function library for the real-time environment" is relevant
for ODK applications under PLCSIM Advanced.

Supported CPUs
PLCSIM Advanced V5.0 supports the ODK functionality of the following controllers:
• CPU 1518(F)-4 PN/DP ODK
• CPU 1518(F)-4 PN/DP MFP

6.2.1 Special features of ODK

Simulating CPU with ODK functionality with PLCSIM Advanced

The simulation of a CPU with ODK functionality requires a special start procedure.
You have the following options:
• Start the instances of a Virtual SIMATIC memory card that contains the project data for the
CPU with ODK functionality.
• Before starting the instances, select the CPU type via the API, for example, "CPU1518MFP".

S7-PLCSIM Advanced
76 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.2 Simulate CPU with ODK functionality

• After the first download, select the functions "Switch off instance" and "Shutdown
instance" in the Control Panel.

NOTE
When you perform the first download to a CPU of the "S7-1500" family, for example, via
the PLCSIM Advanced Control Panel, no ODK1500S folder is created on the virtual SIMATIC
Memory Card. The CPU cannot be switched to RUN. In this case, you will find messages
about missing ODK blocks (e.g. SFC 2013) in the diagnostics buffer.

Supported function libraries

PLCSIM Advanced V5.0 supports the following function libraries for the real-time
environment:
• CPU function library: Original Shared Object, SO file as for the hardware CPUs
• PLCSIM Advanced function library (Windows Sync):
– a 32-bit Windows DLL for ODK Runtime
– a 64-bit Windows DLL for ODK Runtime

NOTE
Do not mix function libraries
When simulating with PLCSIM Advanced, you cannot load 32-bit and 64-bit function libraries
simultaneously. If you want to use one function library, first remove the function library of
the other type.
If you want to use function libraries with a different binary format, all others must be
unloaded first.

NOTE
Limitations for the execution of CPU function libraries (Windows Sync) with an infinite
loop in the class constructor
When the CPU function library (DLL file) contains an object of a class in whose constructor an
infinite loop is programmed, the corresponding "ODK client" process gets permanently stuck
in this loop when instantiating the object.
Even after reaching the timeout, the infinite loop cannot be interrupted automatically. The
PLCSIM Advanced instance remains in RUN even though the entry "Time error - CPU changes
to STOP mode" is displayed in the diagnostics buffer.

NOTE
Limitations for traces in the execution of CPU function libraries (Windows Sync)
Avoid using traces when developing a CPU function library (DLL file) in the class constructor
(call of the "ODK_TRACE()" function) to prevent trace messages with faulty parameter values.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 77
Simulating
6.2 Simulate CPU with ODK functionality

NOTE
Know-how protection
The SO files for ODK are not know-how-protected.

Debugging a PLCSIM Advanced function library (DLL file)

To debug a function library, attach the Visual Studio Debugger to the corresponding ODK
client process that has loaded the respective function library.
PLCSIM Advanced V5.0 supports versions ≥ Visual Studio 2017.

Simulation of the ODK with PLCSIM Advanced

If you have loaded the TIA project on the PLCSIM Advanced and the instruction
"<STEP7Prefix>_Load" was called for the first time, each PLCSIM Advanced instance starts
another Windows process ("ODK client") in which the ODK application is executed
synchronously with the STEP 7 user program.
Which ODK client is started depends on the function library to be loaded:
• "Siemens.Simatic.PlcSim.Vplc1500.ODKClient.so.exe" for an original Shared Object
• "Siemens.Simatic.PlcSim.Vplc1500.ODKClient.x86.exe" for a 32-bit application
• "Siemens.Simatic.PlcSim.Vplc1500.ODKClient.x64.exe" for a 64-bit application
The executable files of these processes are located in the same folders as those of the
PLCSIM Advanced Instances ("Siemens.SIMATIC.Simulation.Runtime.Instance.exe").

NOTE
PLCSIM Advanced does not support asynchronous ODK functions.

Error codes
The same error codes as described in the Programming and Operating Manual
"S7‑1500 Open Development Kit 1500S" apply to the instructions in the real-time
environment. Error codes are also available for PLCSIM Advanced, because the ODK client
processes can be closed unexpectedly and therefore an error handling is required.

S7-PLCSIM Advanced
78 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.2 Simulate CPU with ODK functionality

Restrictions for stack processing

NOTE
Limitations for stack processing in the version of CPU function libraries for real-time-
environment
PLCSIM Advanced ignores the stack size for a CPU function library that is adjusted via the
parameter <SyncCallStackSize>. PLCSIM Advanced always provides the maximum stack size
of 1 MB.
Additional information may be found in the programming and operating manual
S7‑1500 Open Development Kit 1500S
(https://support.industry.siemens.com/cs/ww/en/view/109783714) in the section "Defining
process properties of a CPU function library".

PLCSIM Advanced cannot catch any Exceptions of the type "Stack Overflow" while
CPU function libraries for the real-time environment (SO files) are being executed.
When developing a CPU function library (SO file), make sure that the maximum stack size of
1 MB is not exceeded. An overflow of the stack leads to an undefined behavior and can lead
to the termination of the ODK client process.

NOTE
Limitations for heap processing in the version of CPU function libraries (Windows Sync)
If a heap corruption occurs when executing a C/C++ function from a CPU function library (DLL
file), then this program error is first ignored and execution of the function continues. Only
after fully processing the function is the corresponding error code returned (0x8090).
When developing a CPU function library (DLL file), make sure to avoid heap corruption. This
way you ensure that after fully processing a C/C++ function no error code is returned.

6.2.2 Loading functions

Loading functions - Instruction "<STEP7Prefix>_Load"

If you have loaded the TIA project on the PLCSIM Advanced and the instruction
"<STEP7Prefix>_Load" was called for the first time, each PLCSIM Advanced instance starts
another Windows process. The ODK client then attempts to load the function library which is
specified in the SCL file. This is in the folder
"<storage path of the instance> \SIMATIC_MC\ODK1500S". See GetStoragePath(),
SetStoragePath() in the section Controller - Information and settings (Page 156).
The ODK client process continues until the instruction "<STEP7Prefix>_Unload" is called to
unload the last loaded function library or until the process of the PLCSIM Advanced instance
ends.
The function call is synchronous and returns after completion of the operation. The output
parameter provides information on the progress status.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 79
Simulating
6.2 Simulate CPU with ODK functionality

ODK error code for PLCSIM Advanced

The following table lists the error codes that apply in addition to the error codes that apply to
the CPU specifically for ODK applications with PLCSIM Advanced:
Table 6-4 ODK: Output parameter - Load functions
DONE BUSY ERROR STATUS Description
0 0 1 0x80A4 • The ODK client process cannot be started.
= -32604 • A connection to the ODK client cannot be established or has been inter­
rupted.
0 0 1 0x8095 The ODK client process that is currently running expects a function library
= -32619 with a different binary format.

6.2.3 Calling functions

Call functions - Instruction "<STEP7Prefix>SampleFunction"

When calling ODK functions, data is exchanged between the virtual controller and the
function library.
The execution of a single function can be interrupted by the execution of higher prioritized
OBs.
Technically, the execution of a function is an asynchronous instruction because it is executed
in another process. However, the processes are synchronized via the virtual controller. This
means that the function call does not return before the function returns or the ODK client
process is closed during the execution.

ODK error code for PLCSIM Advanced

The following table lists the error codes that apply in addition to the error codes that apply to
the CPU specifically for ODK applications with PLCSIM Advanced:
Table 6-5 ODK: Output parameter - Call functions
DONE BUSY ERROR STATUS Description
0 0 1 0x80A4 The connection to the ODK client was interrupted.
= -32604

6.2.4 Unloading functions

Unload functions - Instruction "<STEP7Prefix>_Unload"

The CPU function library is unloaded by calling the instruction "<STEP7Prefix>_Unload". If no
other function library is loaded or if the process of the PLCSIM Advanced instance is closed,
then the ODK client process is shut down.
The function call is asynchronous, the call returns immediately. The output parameter
informs about the progress status.

S7-PLCSIM Advanced
80 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.3 Simulating Motion Control

6.3 Simulating Motion Control

Restrictions
S7-PLCSIM Advanced simulates the real CPU but not configured, connected technology
modules or other I/O devices.
It is possible to download a STEP 7 project with technology modules for operation of motion
control. However, the built-in logic of the technology modules is not part of the simulation.
Therefore, the corresponding motion control instructions are not supported.
In contrast to a real CPU, S7-PLCSIM Advanced does not support isochronous mode for
centralized I/O in S7-1500 with local send clock.

OB MC-Servo [OB91] and OB MC-Interpolator [OB 92]

If you convert a motion control project that contains OB 91 and OB 92 from STEP 7 V13, then
you cannot load this project to a S7-PLCSIM Advanced.
Solution
Delete OB 91 and OB 92 in the project and recompile the project.
The OBs are then created again with the simulation support required for
S7-PLCSIM Advanced.
Compilation resets the properties of the blocks to the default values.
Restore the required settings in the properties.

Diagnostic buffer message "Overflow" for OB MC servo [OB91] of the virtual controller
S7-PLCSIM Advanced provides you with the virtual controller of the S7-1500 hardware CPU.
The virtual controller allows you to run the firmware of the S7-1500 under the Windows
operating system.
The wide-ranging communication options and the functions of the API offer you integration
into existing simulation landscapes or co-simulation with other tools. The virtual controller
runs in the Windows environment with the following restrictions. The real hardware CPUs, on
the other hand, are designed for the maximum possible performance without the
compromises required by a general PC operating system.
If there are overflows of the OB MC-Servo [OB91] in the diagnostic buffer, the time for the
application cycle (ms) has been exceeded, because the calculation of this application cycle
could not be completed within the required time.
Solution
The overflows of OB MC-Servo [OB91] in the diagnostic buffer decrease:
• When fewer additional Windows processes are executed
and
• When the computing power of the CPU is higher

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 81
Simulating
6.3 Simulating Motion Control

Overflow detection is activated for S7-PLCSIM Advanced as of V3.0 for exact simulation of the
technology objects. If diagnostic buffer overflows occur on your PC for OB MC-Servo [OB91]
and your instance goes into the STOP operating state, the following solutions are available to
you:
1. Use the virtual time of S7-PLCSIM Advanced and start with the lowest possible scaling
factor for the virtual clock. Increase the value step-by-step until the first overflows occur in
the diagnostic buffer. Repeat this procedure until you have determined the maximum
scaling factor for which you do not yet get any overflows in the diagnostic buffer.
Information on the scaling factor can be found in section Speed up and slow down
simulation (Page 88).
2. Set a longer application cycle (ms) for the OB MC-Servo [OB91] in STEP 7.

NOTE
Load on a PLCSIM Advanced instance is too high
If the load on a PLCSIM Advanced instance becomes too large, the instance may no longer
switch to the STOP operating state despite numerous diagnostic buffer overflows.
In such a case, shut down the PLCSIM Advanced instance and follow the workarounds
described above.

Simulation with external simulation software

NOTE
In a virtual S7-1500 controller, the technology objects are connected to the process image.
Simulation software can thus access the process image via the user interfaces (API) of
PLCSIM Advanced and simulate the behavior of the other connected axes.

Simulation mode in STEP 7

The simulation mode in STEP 7 is a standard function of the technology objects and is
independent of PLCSIM Advanced.
If you want to move an axis in simulation mode, select the "Activate simulation" check box in
STEP 7 under "Technology Object > Configuration> Basic Parameters > Simulation". No
additional setting is required for a virtual axis.

Feedback of the axis position

The speed setpoint of the simulated drive is integrated into the actual position value with a
time delay (PT1). The result of this calculation is returned to the technology object as position
actual value of the axis.

Reference point approach of the axis

If you selected "Use zero mark via PROFIdrive frame" in STEP 7 for the reference point
approach, PLCSIM Advanced responds immediately to any active (mode 2, 3, 8) or passive
(mode 4, 5) reference point approach command (MC_Home). The actual position is
predefined as the reference point.

S7-PLCSIM Advanced
82 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.4 Simulating the SIMATIC Drive Controller

More information
You can find information on the technology functions of the CPU in the S7-1500/S7-1500T
Motion Control (https://support.industry.siemens.com/cs/ww/en/view/109751049) function
manuals.
For more information, refer to the manuals of the supported SIMATIC controllers.
(https://support.industry.siemens.com/cs/ww/en/view/109744173)

6.4 Simulating the SIMATIC Drive Controller

Introduction
The SIMATIC Drive Controller is a drive-based controller in the SIMATIC S7-1500 range.
A SIMATIC Drive Controller combines the following functionalities in a SINAMICS S120
Booksize Compact housing:
• Fail-safe SIMATIC S7-1500 technology CPU with integrated technology I/Os
• SINAMICS S120 drive control
Both components are called "CPU" and "SINAMICS Integrated" in the documentation.
The SIMATIC Drive Controller supports PROFINET and PROFIBUS DP communication.

Supported SIMATIC Drive Controllers

S7-PLCSIM Advanced V5.0 supports the SIMATIC Drive Controllers as of firmware version
V2.9:
• CPU 1504D TF (6ES7615-4DF10-0AB0)
• CPU 1507D TF (6ES7615-7DF10-0AB0)

Special features
Unlike other SIMATIC S7-1500 technology CPUs, the SIMATIC Drive Controllers also have:
• Integrated inputs/outputs (onboard I/O)
• Integrated drive control SINAMICS Integrated

Restrictions
S7-PLCSIM Advanced only simulates the standard CPU functionality of the SIMATIC Drive
Controller.
Not simulated are:
• the technology functions of the onboard I/O
• the SINAMICS Integrated
• PROFINET IO
• PROFIBUS DP
The integrated inputs/outputs of the X122, X132 and X142 interfaces can only be simulated
as binary inputs/outputs.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 83
Simulating
6.5 Simulating a redundant S7-1500R/H system

Technological functions are not simulated, for example, Timer DI/DQ, Oversampling DI/DQ.
Channel parameter assignments, such as signal inversion, input delay and edge detection are
not possible.
The functionality of the SINAMICS Integrated is not simulated – but the SINAMICS Integrated
is shown as a valid node.
Simulations are possible as with SINAMICS S120 CU320-2 based on the drive telegrams (e.g.
by reading and forcing the telegram addresses).
Coupled isochronous mode
In coupled isochronous mode, the relevant clock systems use a shared system clock, for
example, from PROFINET IO or the local send clock of the technology I/Os. The leading clock
system provides its own system clock to the other clock systems.

NOTE
Leading clock system
Clock synchronization with technology I/Os X142 (local send clock) as leading clock system is
not possible with S7-PLCSIM Advanced. In this case, you configure the PROFINET IO interface
X150 as leading clock system.

The information provided in the section Simulation of Motion Control (Page 80) still applies.

Additional information
The SIMATIC Drive Controller system manual
(https://support.industry.siemens.com/cs/ww/en/view/109766665) describes in detail the
configuration, installation, wiring and commissioning of the SIMATIC Drive Controller. The
STEP 7 online help supports you in the configuration and programming.
The SIMATIC Drive Controller equipment manual
(https://support.industry.siemens.com/cs/ww/en/view/109766666) contains a compact
description of the module-specific information, such as properties, wiring diagrams,
characteristics and technical specifications.

6.5 Simulating a redundant S7-1500R/H system

Introduction
In a redundant S7-1500R/H system, the CPUs are duplicated, in other words, redundant. The
two CPUs process the same project data and the same user program in parallel. The two CPUs
are synchronized over two redundancy connections. If one CPU fails, the other CPU maintains
control of the process.

S7-PLCSIM Advanced
84 Function Manual, 11/2022, A5E37039512-AE
 Simulating
6.5 Simulating a redundant S7-1500R/H system

Supported CPUs
PLCSIM Advanced V5.0 supports the R/H CPUs of the redundant S7-1500R/H system as of
firmware version V2.9 with the following functional restrictions:
CPU Article number
CPU 1513R-1 PN 6ES7513-1RL00-0AB0
CPU 1513R-1 PN 6ES7513-1RM03-0AB0
CPU 1515R-2 PN 6ES7515-2RM00-0AB0
CPU 1515R-2 PN 6ES7515-2RN03-0AB0
CPU 1515R-2 PN SIPLUS RAIL 6AG2 515-2RM00-4AB0
CPU 1515R-2 PN SIPLUS 6AG1 515-2RM00-7AB0
CPU 1517H-3 PN 6ES7517-3HP00-0AB0
CPU 1517H-3 PN SIPLUS 6AG1 517-3HP00-4AB0
CPU 1518HF-4 PN 6ES7518-4JP00-0AB0

Supported operating and system states

Like standard S7-1500 CPUs, the S7-1500R/H CPUs have the operating states STOP, STARTUP
and RUN. For operation as a redundant system, one of the two CPUs can take on an additional
operating state, SYNCUP, for synchronizing the two subsystems. The RUN operating state is
divided into the following states for redundant systems:
• RUN
• RUN-Syncup
• RUN-Redundant
The system states of the redundant S7-1500R/H system result from the combination of the
operating states of the individual CPUs as follows:
• STOP
• STARTUP
• RUN-Solo
• SYNCUP
• RUN-Redundant

NOTE
RUN-Solo system state is supported by PLCSIM Advanced
The simulation of a redundant S7-1500R/H system is possible in the RUN-Solo system state
(RUN operating state of the CPU). In the RUN operating state, the (leading) primary CPU
behaves just like an S7-1500 standard CPU. The MAINT LED on the CPU is always yellow
(maintenance request) because no partner CPU was found for redundant operation.
No simulation is possible with PLCSIM Advanced in redundant system operation.

Unsupported events
The following event is not supported by the R/H CPUs of the redundant S7-1500R/H system:

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 85
Simulating
6.5 Simulating a redundant S7-1500R/H system

RackOrStationFault

NOTE
The occurrence of a RackOrStationFault event does not trigger an OnLedChanged event for
R/H CPUs. The ERROR LED is not flashing even though a corresponding device fault message is
displayed in the diagnostic buffer.

Supported functions as of firmware version V3.0

As of FW version V3.0, the S7-1500H redundant system supports PROFINET system
redundancy R1 with the following devices:
• ET 200SP IM 155-6 PN R1
(6ES7155-6AU00-0HM0)
• ET 200SP HA IM 155-6 PN HA
(6DL1155-6AU00-0PM0)
• ET 200iSP IM 152-1 PN
(6ES7152-1BA00-0AB0)
R1 devices are equipped with two interface modules compared to S2 devices. If one interface
module fails, the R1 device can still be reached by the H-CPUs via the second interface
module.
The redundant S7-1500H system thus supports the following additional setup variants:
• Configuration of PROFINET rings with R1 devices
• Line topology configuration with R1 devices, S2 devices, switched S1 devices
• Combined topology configuration with R1 devices and S2 devices
You can load projects consisting of R1 and/or S2 devices in PLCSIM Advanced and simulate
them. Reading and writing input and output values of simulated R1 and S2 devices via the API
works in the same way as for other simulated IO devices. The simulated R1 and S2 devices
support simulation of external events, such as failure of a redundancy connection. Note the
removal and insertion of R1 devices is not supported by S7-PLCSIM Advanced.

More information
The Redundant system S7-1500R/H System Manual
(https://support.industry.siemens.com/cs/ww/en/view/109754833) describes in detail the
configuration, installation, wiring and commissioning of the redundant S7-1500R/H system.
The STEP 7 online help supports you in the configuration and programming.
The equipment manuals of the R-, H- and HF-CPUs contain a compact description of the
module-specific information, such as properties, wiring diagrams, characteristics and
technical specifications of the CPUs.

S7-PLCSIM Advanced
86 Function Manual, 11/2022, A5E37039512-AE
Virtual time response 7
The virtual controller uses two types of internal clocks for the simulation: A virtual clock and a
real clock. The virtual clock is always the basis for the user program. It is used by components
that are relevant for running the STEP 7 user program, such as cyclic OBs, cycle time
monitoring, minimum cycle time, virtual system time and time calculations. Also, the time
between two cycle control points is measured in virtual time.
The virtual time can be accelerated or slowed for test purposes.
The real clock always runs unchanged. It is used by components that are not subject to
control processes, for example, communication with STEP 7.

Interruption of the process

Since PLCSIM Advanced runs in a Windows environment, Windows might temporarily
suspend the virtual controller process. In such a case, both the virtual and the real clock stop
in the virtual controller. They only continue to run when Windows resumes processing.

Virtual system time

When you start PLCSIM Advanced, the virtual system time of the virtual controller starts with
the system time of Windows.
The virtual system time is based on the virtual clock. If a scaling factor is used, the system
time runs correspondingly faster or slower.
All events that the virtual controller sends to the API provides a time stamp based on the
system time.

NOTE
Difference between system time and local time
• System time: UTC ± 0 with daylight saving / standard time
• Local time: UTC ± time zone with daylight saving time / winter time

API functions
• GetSystemTime() (Page 224)
• SetSystemTime() (Page 224)
• SystemTime { get; set; } (Page 225)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 87
Virtual time response
7.1 Speed up and slow down simulation

Time offset

NOTE
Keep in mind that the time information of virtual system time and real local time differs by
the time offset that is formed in addition to the selected scaling factor from the time zone
offset and the daylight saving time/standard time offset.

Scaling factor
Using a scaling factor, you can speed up or slow down the virtual clock of the virtual
controller for simulations.
To set the required scaling factor, enable the grayed out icon on the control panel to the
right of your PLCSIM Advanced instance. The symbol then becomes active and you can use
the scaling function.
• The default setting is 1, i.e. the virtual time passes the same as the real time.
• Fast forward: A scaling factor greater than 1 accelerates the virtual clock.
Example: Scaling factor 2.0 → The virtual time is running twice as fast.
• Slow motion: A scaling factor less than 1 decelerates the virtual clock.
Example: Scaling factor 0.5 → The progress of the virtual time slows down to 50%.

API functions
• GetScaleFactor() (Page 225)
• SetScaleFactor() (Page 225-226)
• ScaleFactor { get; set; } (Page 226)

See also
Settings for the virtual time (Page 224)

7.1 Speed up and slow down simulation

Influence of fast forward and slow motion

Simulations can be accelerated and slowed down. Fast forward and slow motion only affect
time-based components, for example, cyclic OBs. Compared to the real time, they are
performed more frequently with fast forward and less frequently with slow motion.

S7-PLCSIM Advanced
88 Function Manual, 11/2022, A5E37039512-AE
 Virtual time response
7.1 Speed up and slow down simulation

Fast forward and slow motion do not change the execution speed of the CPU machine codes.
For example, the speed at which all operations of an OB1 cycle are executed does not
change. The execution speed depends on the processor of the PC on which the virtual
controller running. If you change the scaling factor, more or fewer cycle control points are
reached in a given period of virtual time.

NOTE
Performance
The performance depends on the size of your project, among other things.
If the scaling factor is too high and the cycle-time monitoring indicates that the PC was
incapable of calculating the OB1 or cyclic OBs in the specified time, the virtual controller goes
to STOP.
Recommendation: To avoid this, start with a small scaling factor and gradually increase it
step-by-step while keeping the virtual controller in RUN.

If an overflow of events occurs, slow down the speed of the simulation. See Monitoring
overflow (Page 343) and Cycle control (Page 226).

Fast forward
To speed up the virtual time, select a scaling factor greater than 1 in the Control Panel or in
the API.

Slow motion
To slow down the virtual time, select a scaling factor less than 1 in the Control Panel or in the
API.

API functions
• GetScaleFactor() (Page 224)
• SetScaleFactor() (Page 224)
• ScaleFactor { get; set; } (Page 224)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 89
Virtual time response
7.2 Stop simulation

7.2 Stop simulation

Freeze state of the virtual controller

To stop a simulation and synchronize simulation partners, you can set a virtual controller to a
freeze state via the API. When the virtual controller has reached a synchronization point, the
virtual controller sends the event OnSyncPointReached to the API clients.

5HDG 3URFHVV :ULWH

,QSXWV WKH2% 2XWSXWV

)UHH]H 8QIUHH]H
2Q6\QF3RLQW5HDFKHG(YHQW E\$3,

Figure 7-1 Freeze state of the virtual controller

The following occurs in the freeze state:
• The virtual time is stopped.
• The OBs currently being executed are stopped.
The procedure corresponds to the behavior of a program that has reached a breakpoint.
• The user program is no longer executed.
• The virtual controller is still accessible from the TIA Portal.

NOTE
Freeze state during downloading
To complete a download in freeze state, the virtual controller must pass through a suspended
or terminated free state.

NOTE
Freeze-state ≠ operating state
The freeze state is an internal operating state of the virtual controller. It does not correspond
to RUN/STOP mode of a CPU. In the freeze state, the virtual controller maintains the last
operating state.
• The LED display on the Control Panel and on the Web server accordingly shows RUN or
STOP for instance.
• The instance shows the operating state SROS_FREEZE / Freeze, see EOperatingState
(Page 319).

NOTE
Reaction of a PLCSIM Advanced API to a freeze state
If you use a SingleStep operating mode, you must register a callback function for the
OnSyncPointReached event. Calling the mode-specific RunToNextSyncPoint method
ensures that the freeze state of the virtual controller is exited again.

S7-PLCSIM Advanced
90 Function Manual, 11/2022, A5E37039512-AE
 Virtual time response
7.2 Stop simulation

Synchronization points
A synchronization point always exists before inputs are read in, for example at the cycle
control point or at the beginning of a cyclic OB.

&\FOLF
2%

0DLQ
2%

6\QF3RLQW 3, 3, 32 32

&\FOH&RQWURO &\FOLF2% &\FOH&RQWURO &\FOLF2%
3RLQW 3RLQW

Figure 7-2 Overview of the synchronization points

Trigger freeze state

To trigger the freeze state, following modes are available for the virtual controller:
• SingleStep operating modes
See Synchronize simulation partner cycle-controlled (Page 91-92).
• TimespanSynchronized operating modes
See Synchronize simulation partner time-controlled (Page 95).
In Default operating mode, the virtual controller does not change into a freeze state.
API functions
• Settings for the cycle control (Page 226)
• GetOperatingMode() (Page 226)
• SetOperatingMode() (Page 227)
• OperatingMode { get; set; } (Page 227)
• EOperatingMode (Page 320)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 91
Virtual time response
7.3 Synchronize simulation partner

7.3 Synchronize simulation partner

7.3.1 Synchronize simulation partner cycle-controlled

SingleStep operating modes

The SingleStep modes of operation of the virtual controller are used to synchronize multiple
simulation partners (clients) using synchronization points. The operating modes define the
synchronization point at which the virtual controller changes to the freeze state and sends
the OnSyncPointReached event.
Table 7-1 Cycle-controlled operating modes (SingleStep)
Operating mode1 Synchronization point Minimum cycle time2 Send clock "Bus"3
Cycle control point Before reading in the
process image partition
"C" "P" "T"
SingleStep_C ✓
SingleStep_P ✓
SingleStep_CP ✓ ✓
SingleStep_CT ✓ ✓
SingleStep_CPT ✓ ✓ ✓
SingleStep_Bus ✓ ✓
1A change from one SingleStep operating mode to another during operation would result in the input parameter
TimeSinceSameSyncPoint_ns / TimeSinceAnySyncPoint_ns being set to 0 in the first SyncPointReached callback
event in the new operating mode. We recommend that the SingleStep operating mode not be changed during operation.
2 In addition, the minimum scan cycle time of OB 1 is overwritten in this operating mode. When you define a minimum cycle
time of 200 ms, the minimum distance between two cycle control points is 200 virtual milliseconds. The default setting is
100 ms.
3 Send clock of the I/O system (PROFIBUS or PROFINET) that is to be used for the cycle-controlled synchronization of the vir­
tual controller. You set the send clock of the respective I/O system in the STEP 7 properties, for example, in the properties
of the PROFINET interface of the CPU (Advanced options > Real time settings > I/O communication > Send clock).

API functions / events

• GetOverwrittenMinimalCycleTime_ns() (Page 226)
• SetOverwrittenMinimalCycleTime_ns() (Page 226)
• OverwrittenMinimalCycleTime_ns { get; set; } (Page 226)
• RunToNextSyncPoint() (Page 226)
• OnSyncPointReached (Page 255)
• EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32 (Page 284) /
Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32 (Page 292)

S7-PLCSIM Advanced
92 Function Manual, 11/2022, A5E37039512-AE
 Virtual time response
7.3 Synchronize simulation partner

Conditions for the SingleStep_Bus operating mode:

The following conditions must be met for the SingleStep_Bus operating mode:
• You must have configured outputs on the controller.
• To synchronize the process image of the outputs, you must call the SYNC_PO instruction
in the isochronous mode interrupt OB.

NOTE
In addition to the send clock of the bus, the cycle control point is also used as a
synchronization point. In the cycle control point, the transferred ID has the value 0xFFFF. The
in_parameters "in_TimeSinceSameSyncPoint_ns" and "in_TimeSinceAnySyncPoint_ns" have
the value 0.

A synchronization of OBs and process image partitions is only possible if the OBs call the
instructions "SYNC_PI" and "SYNC_PO". To use process image partition 1 (PIP 1) for an F-
runtime group, configure the "Pre/Post processing of the F-runtime group" in the Safety
Administration editor.
To configure the preprocessing and postprocessing of the F-runtime group you need new FCs
for "SYNC_PI" and "SYNC_PO" with the following properties:
• Name of the FC: SYNC_PI
#RET_VAL_PI := SYNC_PI(PART := "PIP 1", FLADDR => #FLADDR_PI);
• Name of the FC: SYNC_PO
#RET_VAL_PO := SYNC_PO(PART := "PIP 1", FLADDR => #FLADDR_PO);
To synchronize the process image partition 1 (PIP 1), add the FCs in the Safety Administration
editor under "Pre/Post processing of the F-runtime group".

Figure 7-3 Safety Administration Editor

After compiling these changes, process image partition 1 (PIP 1) is also available for the fail-
safe organization block (FOB).

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 93
Virtual time response
7.3 Synchronize simulation partner

Note regarding the SingleStep_P and SingleStep_Bus operating mode

NOTE
Loss of a OnSyncPointReached event when downloading a clock-synchronous OB in
RUN mode.
If you are registered for the OnSyncPointReached event in the SingleStep_P and
SingleStep_Bus operating modes, the virtual controller does not send this event to the
API client when downloading a clock-synchronous OB.
Solution:
1. Use the OnSoftwareConfigurationChanged event to determine the start and end of
a download
2. Register and log off the OnSyncPointReached event, or handle the loss of the
OnSyncPointReached event accordingly.

Terminating the freeze state

The RunToNextSyncPoint() function cancels the freeze state and induces the virtual
controller to continue running until the next synchronization point.
Switching to the Default operating mode also terminates the freeze state.

Example
The figure schematically shows the sequence in the SingleStep_CP operating mode.
In addition to the OnSyncPointReached event the virtual controller also sends the virtual
time since the last synchronization point of the same process image partition ID or of any
process image partition ID has been reached (TimeSinceSameSyncPoint_ns /
TimeSinceAnySyncPoint_ns).

S7-PLCSIM Advanced
94 Function Manual, 11/2022, A5E37039512-AE
 Virtual time response
7.3 Synchronize simulation partner

The RunToNextSyncPoint() function cancels the freeze state.

&\FO
2%

0DLQ
2%

7LPH6LQFH6DPH6\QF3RLQWBQV ,'; 

7LPH6LQFH6DPH6\QF3RLQWBQV ,' 

7LPH6LQFH$Q\6\QF3RLQWBQV 7LPH6LQFH$Q\6\QF3RLQWBQV

7LPH6LQFH$Q\6\QF3RLQWBQV

2Q6\QF3RLQW5HDFKHG ,';  2Q6\QF3RLQW5HDFKHG ,'; 

2Q6\QF3RLQW5HDFKHG ,'  2Q6\QF3RLQW5HDFKHG ,' 

5XQ7R1H[W6\QF3RLQW 
5XQ7R1H[W6\QF3RLQW  5XQ7R1H[W6\QF3RLQW 

Figure 7-4 Example: Sequence in the SingleStep_CP operating mode

Changing the settings in the watch table

NOTE
Selecting triggers for monitoring of tags in the SingleStep operating modes
In TIA Portal the watch table in basic mode shows the values for outputs and bit memories
before the processing.
To display the tag values after processing, proceed as follows:
1. Select the extended mode for the watch table.
2. In the "Monitor with trigger" column, select "End of cycle, permanent".

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 95
Virtual time response
7.3 Synchronize simulation partner

7.3.2 Synchronize simulation partner time-controlled

TimespanSynchronized operating modes

Several simulation partners (clients) are synchronized time-controlled with the
TimespanSynchronized operating modes of the virtual controller. The operating modes define
the synchronization point at which the virtual controller changes to the freeze state and
sends the OnSyncPointReached event.
Table 7-2 Time-controlled operating modes (TimespanSynchronized)
Operating mode Synchronization point
Cycle control point Before reading in the process image
partition
"C" "P"
TimespanSynchronized_C ✓
TimespanSynchronized_CP ✓ ✓
TimespanSynchronized_P ✓

API functions / events

• Settings for cycle control (Page 226)
• StartProcessing() (Page 230)
• OnSyncPointReached (Page 255)

Terminating the freeze state

The StartProcessing(t) function cancels the freeze state and induces the virtual
controller to continue running at least as long as required (on the basis of the virtual time)
before it changes back to the freeze state at the next synchronization point.
Switching to the Default operating mode also terminates the freeze state.

Example
The figure schematically shows the sequence in the TimespanSynchronized_CP
operating mode.
In addition to the OnSyncPointReached event the virtual controller also sends the runtime
since the last call of the StartProcessing(t) (TimeSinceSameSyncPoint_ns /
TimeSinceAnySyncPoint_ns) function.

S7-PLCSIM Advanced
96 Function Manual, 11/2022, A5E37039512-AE
 Virtual time response
7.3 Synchronize simulation partner

The StartProcessing() function cancels the freeze state.

7LPH6LQFH6DPH6\QF3RLQWBQV WLPHUXQ 
7LPH6LQFH$Q\6\QF3RLQWBQV WLPHUXQ
6\QF3RLQW&RXQW Q

2Q6\QF3RLQW5HDFKHG ,'  2Q6\QF3RLQW5HDFKHG ,'; 

6WDUW3URFHVVLQJ W  6WDUW3URFHVVLQJ W 

Figure 7-5 Example: Sequence in the TimespanSynchronized_CP operating mode

Description
At least two clients are synchronized on the basis of a virtual period for the time-controlled
operating modes. A client can be an instance of a virtual controller or an application that uses
the Runtime API (API client). The synchronization must be performed by a synchronization
master.
The synchronization master instructs a client to run for a specific period. The time period is
specified by the master in nanoseconds. The client then runs for the expected period before
the client goes into the freeze state at the next synchronization point. Before switching to the
freeze state, the client sends the master the exact amount of time that he currently needed.
Thereafter, the master signals the next client to catch up.
API client as master
The API client as master signals each client when it should start. The master receives events
from every client when they occur.
An API client can only "time manage" instances of a virtual controller. The API client does not
receive events from other API clients. It cannot send messages to other API clients.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 97
User interfaces (API) 8
8.1 Introduction

Components of the Simulation Runtime

The following components are relevant for handling the Simulation Runtime of PLCSIM
Advanced:
Table 8-1 Components of the Simulation Runtime
Components Description
• "Siemens.Simatic.Simulation. Runtime.Man­ A Windows process that runs in the background.
ager.exe" Main component of Runtime that manages all other Runtime compon­
ents.
The process is started automatically as soon as an application attempts to
initialize the Runtime API. It is ended automatically as soon as there is no
longer any application running that initialized the Runtime API.
• "Siemens.Simatic.Simulation. The process of the instance that loads a DLL of a virtual controller. Each
Runtime.Instance.exe" virtual controller generates its own process.
• "Siemens.Simatic.Simulation. API libraries that must load an application to use the Simulation Runtime.
Runtime.Api.x86.dll" The libraries contain interfaces for native code and managed code.
• "Siemens.Simatic.Simulation. The "Runtime.Api.x86.dll" is loaded exclusively by 32-bit applications, and
Runtime.Api.x64.dll" the "Runtime.Api.x64.dll" by 64-bit applications.
• "SimulationRuntimeApi.h" Header file that describes all data types that require a native C++ applica­
tion to use the API library.
• "Siemens.Simatic.PlcSim.Vplc1500. ODKCli­ ODK client process for a CPU function library (original Shared Object)
ent.so.exe"
• "Siemens.Simatic.PlcSim.Vplc1500. ODKCli­ ODK client process for a 32-bit application
ent.x86.exe"
• "Siemens.Simatic.PlcSim.Vplc1500. ODKCli­ ODK client process for a 64-bit application
ent.x64.exe"

External applications and Simulation Runtime

The following figure schematically presents the access of external applications to Simulation
Runtime via the Runtime API. The Simulation Runtime Manager manages the Runtime
instances. These load the libraries of the virtual controllers.

S7-PLCSIM Advanced
98 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.1 Introduction

An external application can be, for example, another simulation software or a graphical user
interface (GUI).

6LPXODWLRQ5XQWLPH

5XQWLPH ([WHUQDO
$3, $SSOLFDWLRQ
6LPXODWLRQ5XQWLPH
0DQDJHU
5XQWLPH ([WHUQDO
$3, $SSOLFDWLRQ

5XQWLPH 5XQWLPH
,QVWDQFH ,QVWDQFH

9LUWXDO 9LUWXDO
&RQWUROOHU &RQWUROOHU

Figure 8-1 External applications and Simulation Runtime

8.1.1 Access to instances

Access via the Control Panel and the API

You can only access a local instance on the PC via the Control Panel. It does not matter on
which PC an instance was created and started. With distributed communication, the Runtime
API accesses the instance of the other PCs via the Simulation Runtime Manager.

3& 3&
&RQWURO &RQWURO
3DQHO 3DQHO

 

5XQWLPH 5XQWLPH
$3, $3,

 

6LPXODWLRQ 6LPXODWLRQ
5XQWLPH 5XQWLPH
0DQDJHU 0DQDJHU

5XQWLPH 5XQWLPH
,QVWDQFH ,QVWDQFH

① Access to a local instance via the Control Panel

② Access to a remote instance on the Runtime API
Figure 8-2 Access to instances with distributed communication

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 99
User interfaces (API)
8.1 Introduction

API functions
• Overview of IInstances functions - Native C++ (Page 103)
• Overview of IInstances functions - .NET (C#) (Page 106)
• Overview of IRemoteRuntimeManager functions - Native C++ (Page 105)
• Overview of IRemoteRuntimeManager functions - .NET (C#) (Page 108)

See also
Overview of user interfaces for managed code (Page 105)

8.1.2 Interfaces of the Simulation Runtime

The user interfaces of Simulation Runtime include functions you use, for example, to create
instances, to change the operating state of a virtual controller, or to exchange I/O data.
Simulation Runtime has the following user interfaces:
• ISimulationRuntimeManager
• IInstances
• IRemoteRuntimeManager

API and external applications

The Runtime API makes the interfaces available to an external application.

([WHUQDO$SSOLFDWLRQ

,,QVWDQFH
5XQWLPH$3, ,6LPXODWLRQ5XQWLPH0DQDJHU 


,,QVWDQFH




① ISimulationRuntimeManager
Interface of the Runtime Manager. It is used to register new Runtime instances, to search
through existing Runtime instances, and to receive an interface of a registered instance. Up to
16 instances can be registered in one Runtime Manager.
② IInstances
Interface of a Runtime instance. It is used to change the operating state of a virtual controller
and to exchange I/O data. Each instance has a unique name and an ID.
Figure 8-3 API and external applications

S7-PLCSIM Advanced
100 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.1 Introduction

Access to API functions and data types

Required functions and data types are available for native C++ and .NET (C#).
• Overview of user interfaces for native C++ (Page 101)
• Overview of data types for native C++ (Page 108)
• Overview of user interfaces for managed code (Page 105)
• Overview of data types for managed code (Page 109)

NOTE

The list of tables in this manual gives you direct access to the description of the individual
functions and data types.

Transfer parameters for API functions

All API functions that return a value using the function parameters expect a user-allocated
memory area as a transfer parameter. Null pointers are not permitted. Exceptions to this are
the functions that return an interface of a virtual controller:
• An ISimulationRuntimeManager interface
• An IRemoteRuntimeManager interface
• An IInstance interface

8.1.3 Overview of user interfaces for native C++

Initializing and shutting down API

Table 8-2 Overview of initializing and shutting down API - Native C++
Actions Functions
Initialize API (Page 111-112) InitializeApi
RuntimeApiEntry_Initialize
Shut down API (Page 114) DestroyInterface
RuntimeApiEntry_DestroyInterface
Logging off API library (Page 116) FreeApi
ShutdownAndFreeApi

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 101
User interfaces (API)
8.1 Introduction

Global functions
Table 8-3 Overview of global functions - Native C++
Actions Functions
Global functions (Page 118) GetNameOfAreaSection()
GetNameOfCPUType()
GetNameOfCommunicationInterface()
GetNameOfDataType()
GetNameOfLEDMode()
GetNameOfLEDType()
GetNameOfOperatingMode()
GetNameOfOperatingState()
GetNameOfPrimitiveDataType()
GetNameOfTagListDetails()
GetNameOfErrorCode()
GetNameOfRuntimeConfigChanged()
GetNameOfInstanceConfigChanged()
GetNameOfDiagSeverity()
GetNameOfDirection()
GetNameOfRackOrStationFaultType()
GetNameOfProcessEventType()
GetNameOfPullOrPlugEventType()
GetNameOfCycleTimeMonitoringMode()
GetNameOfDiagProperty()
GetNameOfAutodiscoverType()
GetNameOfSoftwareConfigChanged()

API ISimulationRuntimeManager
Table 8-4 Overview of API ISimulationRuntimeManager functions - Native C++
Settings Functions
Interface (Page 123) GetVersion()
IsInitialized()
IsRuntimeManagerAvailable()
Shutdown()
GetStrictMotionTiming()
SetStrictMotionTiming()
Simulation Runtime instances (Page GetRegisteredInstancesCount()
132) GetRegisteredInstanceInfoAt()
RegisterInstance()
RegisterCustomInstance()
CreateInterface()
Remote connections (Page 137) OpenPort()
ClosePort()
GetPort()
GetRemoteConnectionsCount()
GetRemoteConnectionInfoAt()
RemoteConnect()
RunAutodiscover()

Table 8-5 Overview of API ISimulationRuntimeManager events - Native C++

Events Functions
OnSoftwareConfigurationChanged RegisterOnSoftwareConfigurationChangedCallback()
UnregisterOnSoftwareConfigurationChangedCallback()
RegisterOnSoftwareConfigurationChangedEvent()
UnregisterOnSoftwareConfigurationChangedEvent()
WaitForOnSoftwareConfigurationChangedEvent()

S7-PLCSIM Advanced
102 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.1 Introduction

Events Functions
OnRuntimeManagerLost (Page 145) RegisterOnRuntimeManagerLostCallback()
UnregisterOnRuntimeManagerLostCallback()
RegisterOnRuntimeManagerLostEvent()
UnregisterOnRuntimeManagerLostEvent()
WaitForOnRuntimeManagerLostEvent()
OnAutodiscover (Page 147) RegisterOnAutodiscoverCallback()
UnregisterOnAutodiscoverCallback()

API IInstances
Table 8-6 Overview of IInstances functions - Native C++
Settings Functions
Interface (Page 148-149) GetID()
GetName()
GetCPUType()
SetCPUType()
GetCommunicationInterface()
SetCommunicationInterface()
GetInfo()
UnregisterInstance()
GetStrictMotionTiming()
SetStrictMotionTiming()
Controller (Page 153) GetControllerName()
GetControllerShortDesignation()
GetControllerIPCount()
GetControllerIP()
GetControllerIPSuite4()
SetIPSuite()
GetStoragePath()
SetStoragePath()
ArchiveStorage()
RetrieveStorage()
CleanupStoragePath()
Operating state (Page 162) PowerOn()
PowerOff()
Run()
Stop()
GetOperatingState()
MemoryReset()
Tag list (Page 172) UpdateTagList()
GetTagListStatus()
GetTagInfoCount()
GetTagInfos()
CreateConfigurationFile()
I/O access via address - Reading (Page GetAreaSize()
177) ReadBit()
ReadByte()
ReadBytes()
ReadSignals()
I/O access via address - Writing (Page WriteBit()
183) WriteByte()
WriteBytes()
WriteSignals()

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 103
User interfaces (API)
8.1 Introduction

Settings Functions
I/O access via tag name - Reading (Page Read()
187) ReadBool()
ReadChar(), ReadWChar()
ReadDouble()
ReadFloat()
ReadInt8(), ReadInt16(), ReadInt32(), ReadInt64()
ReadUInt8(), ReadUInt16(), ReadUInt32(), ReadUInt64()
ReadSignals()
ReadString()
ReadWString()
I/O access via tag name - Writing (Page Write()
206) WriteBool()
WriteChar(), WriteWChar()
WriteDouble()
WriteFloat()
WriteInt8(), WriteInt16(), WriteInt32(), WriteInt64(),
WriteUInt8(), WriteUInt16(), WriteUInt32(), WriteUInt64()
WriteSignals()
WriteString()
WriteWString()
Virtual time (Page 224) GetSystemTime()
SetSystemTime()
GetScaleFactor()
SetScaleFactor()
Cycle control (Page 226) GetOperatingMode()
SetOperatingMode()
SetSendSyncEventInDefaultModeEnabled()
IsSendSyncEventInDefaultModeEnabled
GetOverwrittenMinimalCycleTime_ns()
SetOverwrittenMinimalCycleTime_ns()
RunToNextSyncPoint()
StartProcessing()
SetCycleTimeMonitoringMode()
GetCycleTimeMonitoringMode()
Acyclic services (Page 233)

Table 8-7 Overview of IInstances events - Native C++

Events Functions
OnOperatingStateChanged (Page 247) RegisterOnOperatingStateChangedCallback()
UnregisterOnOperatingStateChangedCallback()
RegisterOnOperatingStateChangedEvent()
UnregisterOnOperatingStateChangedEvent()
WaitForOnOperatingStateChangedEvent()
OnLedChanged (Page 250) RegisterOnLedChangedCallback()
UnregisterOnLedChangedCallback()
RegisterOnLedChangedEvent()
UnregisterOnLedChangedEvent()
WaitForOnLedChangedEvent()
OnSoftwareConfigurationChanged RegisterOnSoftwareConfigurationChangedCallback()
(Page 252) UnregisterOnSoftwareConfigurationChangedCallback()
RegisterOnSoftwareConfigurationChangedEvent()
UnregisterOnSoftwareConfigurationChangedEvent()
WaitForOnSoftwareConfigurationChangedEvent()
OnSyncPointReached (Page 255) RegisterOnSyncPointReachedCallback()
UnregisterOnSyncPointReachedCallback()
RegisterOnSyncPointReachedEvent()
UnregisterOnSyncPointReachedEvent()
WaitForOnSyncPointReachedEvent()

S7-PLCSIM Advanced
104 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.1 Introduction

Events Functions
OnHardwareConfigChanged (Page RegisterOnHardwareConfigChangedCallback()
258) UnregisterOnHardwareConfigChangedCallback()
RegisterOnHardwareConfigChangedEvent()
UnregisterOnHardwareConfigChangedEvent()
WaitForOnHardwareConfigChangedEvent()

API IRemoteRuntimeManager
Table 8-8 Overview of IRemoteRuntimeManager functions - Native C++
Settings Functions
Interface (Page 267) GetVersion()
GetIP()
GetPort()
GetRemoteComputerName()
Disconnect()
GetStrictMotionTiming()
SetStrictMotionTiming()
Simulation Runtime instances (Page GetRegisteredInstancesCount()
272) GetRegisteredInstanceInfoAt()
RegisterInstance()
RegisterCustomInstance()
CreateInterface()

Table 8-9 Overview of IRemoteRuntimeManager events - Native C++

Events Functions
OnConnectionLost (Page 277-278) RegisterOnConnectionLostCallback()
UnregisterOnConnectionLostCallback()
RegisterOnConnectionLostEvent()
UnregisterOnConnectionLostEvent()
WaitForOnConnectionLostEvent()

8.1.4 Overview of user interfaces for managed code

Initializing and shutting down API

Table 8-10 Overview of initializing and shutting down API - .NET (C#)
Actions Functions
Initialize API (Page 114) Siemens.Simatic.Simulation.Runtime.SimulationRuntimeManager
Shut down API (Page 118)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 105
User interfaces (API)
8.1 Introduction

API ISimulationRuntimeManager
Table 8-11 Overview of ISimulationRuntimeManager functions - .NET (C#)
Settings Functions
Interface (Page 123) Version { get; }
IsInitialized { get; }
IsRuntimeManagerAvailable { get; }
Shutdown()
StrictMotionTiming { get; set; }
Simulation Runtime instances (Page RegisterInstanceInfo { get; }
132) RegisterInstance()
RegisterCustomInstance()
CreateInterface()
Remote connections (Page 137) OpenPort()
ClosePort()
Port { get; }
RemoteConnectionInfo { get; }
RemoteConnect()
RunAutodiscover()

Table 8-12 Overview of ISimulationRuntimeManager events - .NET (C#)

Events Functions
OnSoftwareConfigurationChanged UnregisterOnSoftwareConfigurationChangedEvent()
(Page 143) WaitForOnSoftwareConfigurationChangedEvent()

OnRuntimeManagerLost (Page 145) OnRuntimeManagerLost()

RegisterOnRuntimeManagerLostEvent()
UnregisterOnRuntimeManagerLostEvent()
WaitForOnRuntimeManagerLostEvent()
OnAutodiscover (Page 147) OnAutodiscoverData()

API IInstances
Table 8-13 Overview of IInstances functions - .NET (C#)
Settings Functions
Interface (Page 148-149) Dispose ()
ID { get; }
Name { get; }
CPUType { get; set; }
CommunicationInterface { get; }
Info { get; }
UnregisterInstance()
StrictMotionTiming { get; set; }
Controller - Information and settings ControllerName { get; }
(Page 153) ControllerShortDesignation { get; }
ControllerIPSuite4 { get; }
SetIPSuite()
StoragePath { get; set; }
ArchiveStorage()
RetrieveStorage()
CleanupStoragePath()
Operating state (Page 162) PowerOn()
PowerOff()
Run()
Stop()
OperatingState { get; }
MemoryReset()

S7-PLCSIM Advanced
106 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.1 Introduction

Settings Functions
Tag list (Page 172) UpdateTagList()
GetTagListStatus()
TagInfos { get; }
CreateConfigurationFile()
I/O access via address - Reading (Page InputArea | MarkerArea | OutputArea { get; }
177) AreaSize { get; }
ReadBit()
ReadByte()
ReadBytes()
ReadSignals()
I/O access via address - Writing (Page WriteBit()
183) WriteByte()
WriteBytes()
WriteSignals()
I/O access via tag name - Reading (Page Read()
187) ReadBool()
ReadChar(), ReadWChar()
ReadDouble()
ReadFloat()
ReadInt8(), ReadInt16(), ReadInt32(), ReadInt64()
ReadUInt8(), ReadUInt16(), ReadUInt32(), ReadUInt64()
ReadSignals()
ReadString()
ReadWString()
I/O access via tag name - Writing (Page Write()
206) WriteBool()
WriteChar(), WriteWChar()
WriteDouble()
WriteFloat()
WriteInt8(), WriteInt16(), WriteInt32(), WriteInt64(),
WriteUInt8(), WriteUInt16(), WriteUInt32(), WriteUInt64()
WriteSignals()
WriteString()
WriteWString()
Virtual time (Page 224) SystemTime { get; set; }
ScaleFactor { get; set; }
Cycle control (Page 226) OperatingMode { get; set; }
IsSendSyncEventInDefaultModeEnabled { get; set; }
OverwrittenMinimalCycleTime_ns { get; set; }
RunToNextSyncPoint()
StartProcessing()
SetCycleTimeMonitoringMode()
GetCycleTimeMonitoringMode()
Acyclic services (Page 233)

Table 8-14 Overview of IInstances events - .NET (C#)

Events Functions
OnOperatingStateChanged (Page 247) OnOperatingStateChanged()
RegisterOnOperatingStateChangedEvent()
UnregisterOnOperatingStateChangedEvent()
WaitForOnOperatingStateChangedEvent()
OnLedChanged (Page 250) OnLedChanged()
RegisterOnLedChangedEvent()
UnregisterOnLedChangedEvent()
WaitForOnLedChangedEvent()

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 107
User interfaces (API)
8.1 Introduction

Events Functions
OnSoftwareConfigurationChanged UnregisterOnSoftwareConfigurationChangedEvent()
(Page 143) WaitForOnSoftwareConfigurationChangedEvent()

OnSyncPointReached (Page 255) OnSyncPointReached()

RegisterOnSyncPointReachedEvent()
UnregisterOnSyncPointReachedEvent()
WaitForOnSyncPointReachedEvent()
OnHardwareConfigChanged OnHardwareConfigChanged()
RegisterOnHardwareConfigChangedEvent()
UnregisterOnHardwareConfigChangedEvent()
WaitForOnHardwareConfigChangedEvent()

API IRemoteRuntimeManager
Table 8-15 Overview of IRemoteRuntimeManager functions - .NET (C#)
Settings Functions
Interface (Page 267) Dispose()
Version { get; }
IP { get; }
Port { get; }
RemoteComputerName { get; }
Disconnect()
StrictMotionTiming { get; set; }
Simulation Runtime instances (Page RegisterInstanceInfo { get; }
132) RegisterInstance()
RegisterCustomInstance()
CreateInterface()

Table 8-16 Overview IRemoteRuntimeManager events - .NET (C#)

Events Functions
OnConnectionLost() (Page 277-278) OnConnectionLost()
RegisterOnConnectionLostEvent()
UnregisterOnConnectionLostEvent()
WaitForOnConnectionLostEvent()

8.1.5 Overview of data types for native C++

The following table shows which data types are available for the simulation in Runtime
Manager.
Table 8-17 Overview of data types - Native C++
Data type
DLL import functions (Page 280) ApiEntry_Initialize
ApiEntry_DestroyInterface
Event callback functions (Page EventCallback_VOID
281) EventCallback_SRCC_UINT32_UINT32_INT32
EventCallback_SRRSI_AD
EventCallback_IRRTM
EventCallback_II_SREC_ST_SROS_SROS
EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32
EventCallback_II_SREC_ST
EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32
EventCallback_II_SREC_ST_SRLT_SRLM
EventCallback_II_SREC_ST_SDRI
EventCallback_II_SREC_ST_SDRI_BYTE

S7-PLCSIM Advanced
108 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.1 Introduction

Data type
EventCallback_II_SREC_ST_UINT32_UINT32
EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32
EventCallback_II_SREC_ST_UINT32_EPPET_UINT32
EventCallback_II_SREC_ST_UINT32_ERSFET
EventCallback_II_SREC_ST_UINT32
EventCallback_II_SSCCP
Definitions and constants (Page 297)
Unions (Page 298) UIP
UDataValue
Structures (Page 300) SDataValue
SDVBNI
SDataValueByAddress
SDataValueByName
SConnectionInfo
SInstanceInfo
SDimension
STagInfo
SIP
SIPSuite4
SOnSyncPointReachedResult
SDataValueByAddressWithCheck
SDataValueByNameWithCheck
SDataRecordInfo
SDataRecord
SConfiguredProcessEvents
SDiagExtChannelDescription
SAutodiscoverData
SOnSoftwareConfigChangedParameter
Enumerations (Page 316) ERuntimeErrorCode
EArea
EOperatingState
EOperatingMode
ECPUType
ECommunicationInterface
ECommunicationMode
EPLCInterface
ELEDType
ELEDMode
EPrimitiveDataTypes
EDataType
ETagListDetails
ERuntimeConfigChanged
EInstanceConfigChanged
EPullOrPlugEventType
EProcessEventType
EDirection
EDiagProperty
EDiagSeverity
ERackOrStationFaultType
ECycleTimeMonitoringMode
EAutodiscoverType

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 109
User interfaces (API)
8.1 Introduction

8.1.6 Overview of data types for managed code

The following table shows which data types are available for the simulation in Runtime
Manager.
Table 8-18 Overview of data types - .NET (C#)
Data type
Delegate definitions (Page 290) Delegate_Void
- Event handler methods Delegate_SRCC_UINT32_UINT32_INT32
Delegate_SRRSI_AD
Delegate_IRRTM
Delegate_II_EREC_DT_EOS_EOS
Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32
Delegate_II_EREC_DT
Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32
Delegate_II_EREC_DT_ELT_ELM
Delegate_II_EREC_DT_SDRI
Delegate_II_EREC_DT_SDR
Delegate_SREC_ST_UINT32_UINT32
Delegate_SREC_ST_UINT32_UINT32_EPET_UINT32
Delegate_SREC_ST_UINT32_EPPET_UINT32
Delegate_SREC_ST_UINT32_ERSFET
Delegate_SREC_ST_UINT32
Definitions and constants (Page 297)
Structures (Page 300) SDataValue
SDVBNI
SDataValueByAddress
SDataValueByName
SConnectionInfo
SInstanceInfo
SDimension
STagInfo
SIP
SIPSuite4
SOnSyncPointReachedResult
SDataValueByAddressWithCheck
SDataValueByNameWithCheck
SDataRecordInfo
SDataRecord
SConfiguredProcessEvents
SDiagExtChannelDescription
SAutodiscoverData
Enumerations (Page 315) ERuntimeErrorCode
EArea
EOperatingState
EOperatingMode
ECPUType
ECommunicationInterface
ELEDType
ELEDMode
EPrimitiveDataTypes
EDataType
ETagListDetails
ERuntimeConfigChanged
EInstanceConfigChanged
EPullOrPlugEventType
EProcessEventType
EDirection
EDiagProperty
EDiagSeverity
ERackOrStationFaultType
ECycleTimeMonitoringMode
EAutodiscoverType

S7-PLCSIM Advanced
110 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.2 Initialize API

8.2 Initialize API

8.2.1 Load API library

Description
For PLCSIM Advanced, the interfaces of the API V5.0 are not compatible with the interfaces of
previous API versions. However, the Runtime Manager of PLCSIM Advanced V5.0 is
compatible with the API of previous PLCSIM Advanced versions.
Earlier versions of the API are also installed during the installation of PLCSIM Advanced V5.0.
The default path is:
• C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV\API\1.0
• C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV\API\2.0
• C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV\API\2.1
• C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV\API\3.0
• C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV\API\4.0
• C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV\API\4.1
• C:\Program Files (x86)\Common Files\Siemens\PLCSIMADV\API\5.0

NOTE
API versions
To access and use the latest features and bug fixes, use the latest API version.

The installation path of PLCSIM Advanced is contained in the registry:

• Key: "HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Siemens\Shared
Tools\PLCSIMADV_SimRT"
• Value: "Path"
To maintain the path to the API, add the character string of the following subdirectory at the
end: "API\<API version>" (e.g. "API\5.0").
When you use this path the API library (DLL) is loaded directly from the installation directory.

Reference
Additional information can be found in:
• For Native C++ in section InitializeApi() (Page 111-112).
• For .NET via the call of the function "System.Reflection.Assembly.LoadFile(string)" in the
online documentation for MSDN.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 111
User interfaces (API)
8.2 Initialize API

8.2.2 Native C++

8.2.2.1 InitializeApi()

Description
The InitializeApi function loads the API library (DLL) and initializes the API. The function
loads the version of the DLL that is compatible with the architecture of your application and
with the header file of the API ("SimulationRuntimeApi.h").
To load the DLL, the function InitializeApi searches in the following folders one after
the other:
• Folder to which the parameter of the function leads
(in_SimulationRuntimeApiDllPath)
• Folder, which also contains your application that calls this function
• Installation directory of PLCSIM Advanced
If no DLL is available, the function accesses the next folder.
The function returns an interface to the Simulation Runtime Manager. Use this interface to
create a new instance of the virtual controller or to obtain access to an existing instance.
Table 8-19 InitializeApi() - Native C++
Syntax ERuntimeErrorCode InitializeApi(ISimulationRuntimeManager**
out_SimulationRuntimeManagerInterface);
ERuntimeErrorCode InitializeApi(WCHAR*
in_SimulationRuntimeApiDllPath,ISimulationRuntimeManager**
inout_SimulationRuntimeManagerInterface);
Parameters • ISimulationRuntimeManager** out_SimulationRuntimeManagerInterface:
Pointer to a Runtime Manager interface pointer. The pointer must be initialized with NULL. The
interface is created within the function. See Data types (Page 280).
• WCHAR* in_SimulationRuntimeApiDllPath:
The path to the Runtime API library.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The pointer to the Runtime Manager interface does not
equal NULL.
SREC_WRONG_VERSION • The required version of the interface is incompatible
with the version used to compile the API.
• The version of the API is not compatible with
Runtime.
See Compatibility in case of updates (Page 20).
SREC_CONNECTION_ERROR Unable to establish a connection to the Runtime Man­
ager.
SREC_ERROR_LOADING_DLL The API library cannot be loaded.
SREC_RUNTIME_NOT_AVAILABLE No Runtime Manager runs in this Windows user session.
SREC_CONFIG_FILE_ERROR Operation regarding the configuration file "UserInter­
faceConfiguration.xml" has failed, for example, create,
read, write.

S7-PLCSIM Advanced
112 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.2 Initialize API

Example C++ // Include The Headerfile Of The API

#include "SimulationRuntimeApi.h"

// Prepare The Variables

ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;
ISimulationRuntimeManager* api = NULL;

// Initialize The API And Get The RuntimeManager Interface

result = InitializeApi(&api);

NOTE
If you no longer require the interface, delete the interface.
See DestroyInterface() (Page 115).

8.2.2.2 RuntimeApiEntry_Initialize

Description
Use the function RuntimeApiEntry_Initialize only if the API library (DLL) is to be
loaded from a different folder than the folder of your application calling this function.
When the API is initialized, the API library is first loaded and the Initialize function is then
imported and called.
The function returns an interface to the Simulation Runtime Manager. Use this interface to
create a new instance of the virtual controller or to obtain access to an existing instance.
Table 8-20 RuntimeApiEntry_Initialize - Native C++
Syntax __declspec(dllexport) ERuntimeErrorCode
RuntimeApiEntry_Initialize(ISimulationRuntimeManager**
out_SimulationRuntimeManagerInterface,UINT32 in_InterfaceVersion);
Parameters • ISimulationRuntimeManager** out_SimulationRuntimeManagerInterface:
Pointer to a Runtime Manager interface pointer. The pointer must be initialized with NULL. The
interface is created within the function. See Data types (Page 280).
• UINT32 in_InterfaceVersion:
Version of the API interface to be downloaded: DAPI_DLL_INTERFACE_VERSION.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The pointer to the Runtime Manager interface does not
equal NULL.
SREC_WRONG_VERSION • The required version of the interface is incompatible
with the version used to compile the API.
• The version of the API is not compatible with Runtime.
See Compatibility in case of updates (Page 20).
SREC_CONNECTION_ERROR Unable to establish a connection to the Runtime Man­
ager.
SREC_RUNTIME_NOT_AVAILABLE No Runtime Manager runs in this Windows user session.
SREC_CONFIG_FILE_ERROR Operation regarding the configuration file "UserInterface­
Configuration.xml" has failed, for example, create, read,
write.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 113
User interfaces (API)
8.2 Initialize API

Example C++ // Include The Headerfile Of The API

#include "SimulationRuntimeApi.h"

// Prepare The Variables

ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;
HMODULE dllHandle = NULL;
ApiEntry_Initialize Initialize = NULL;
ISimulationRuntimeManager* api = NULL;

// Load The DLL And Import The “Initialize” Function (using the Windows
API)
dllHandle = LoadLibrary(DAPI_DLL_NAME_X86);
if (dllHandle != NULL)
{
Initialize = (ApiEntry_Initialize)GetProcAddress(dllHandle,
DAPI_ENTRY_INITIALIZE);
}

// Initialize The API And Get The RuntimeManager Interface

if ( Initialize != NULL )
{
result = Initialize(&api, DAPI_DLL_INTERFACE_VERSION);
}

NOTE
If you no longer require the interface, delete the interface.
SeeDestroyInterface() (Page 115).

8.2.3 .NET (C#)

8.2.3.1 Initialize

Description
The entry point to the API is the static class
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeManager.
The API is initialized when a function of this class is used for the first time.
Table 8-21 Initialize - .NET (C#)
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationInitializationException
Runtime error code Description
ERuntimeErrorCode. Unable to establish a connection to the Runtime Manager.
ConnectionError
ERuntimeErrorCode. The version of the API is not compatible with Runtime.
WrongVersion See Compatibility during upgrade (Page 20).
ERuntimeErrorCode. No Runtime Manager runs in this Windows user session.
RuntimeNotAvailable
ERuntimeErrorCode. Operation regarding the configuration file "UserInterfaceCon­
ConfigFileError figuration.xml" has failed, for example, create, read, write.

S7-PLCSIM Advanced
114 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.3 Shut down API

8.3 Shut down API

8.3.1 Native C++

Basic procedure for deleting the user interfaces

To delete all user interfaces, generally follow these steps:
1. Delete the interfaces IInstances and IRemoteRuntimeManager.
2. Call the Shutdown() function of the ISimulationRuntimeManager interface.
3. Delete the ISimulationRuntimeManager interface.
4. Unload the API library (DLL) with the Window API function FreeLibrary().

Deleting the user interfaces via functions

Deleting the user interfaces is also possible via functions.
If the API was initialized using the InitializeApi() function, you delete the user
interfaces using the following functions:
• FreeApi() (Page 116)
• ShutdownAndFreeApi() (Page 117)

8.3.1.1 DestroyInterface()

Description
A function pointer to the RuntimeApiEntry_DestroyInterface function. The function
pointer DestoyInterface() is only valid if the InitializeApi function has been
successfully called.
The function unloads the memory of an ISimulationRuntimeManager,
IRemoteRuntimeManager or IInstance interface.
Table 8-22 DestroyInterface() - Native C++
Syntax ERuntimeErrorCode DestroyInterface(IBaseInterface* in_Interface);
Parameters • IBaseInterface* in_Interface:
The interface to be deleted.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The pointer to the interface is NULL.
Example C++ // Include The Headerfile Of The API
#include "SimulationRuntimeApi.h"

// The Interfaces
ERuntimeErrorCode result;
ISimulationRuntimeManager* api = NULL;
IInstance* instance = NULL;

// Init the DLL and create an instance

result = InitializeApi(&api);
result = api->RegisterInstance(&instance);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 115
User interfaces (API)
8.3 Shut down API

// Destroy Instance Interfaces

result = DestroyInterface(instance);
instance = NULL;

8.3.1.2 RuntimeApiEntry_DestroyInterface

Description
Use the RuntimeApiEntry_DestroyInterface function only if the API library (DLL) is to
be loaded from a different directory than the Startup folder of the application calling this
function.
If the API was initialized using the InitializeApi function, you select the
DestroyInterface() (Page 115) function.
The function unloads the memory of an ISimulationRuntimeManager,
IRemoteRuntimeManager or IInstance interface.
Table 8-23 RuntimeApiEntry_DestroyInterface() - Native C++
Syntax __declspec(dllexport) ERuntimeErrorCode
RuntimeApiEntry_DestroyInterface(IBaseInterface* in_Interface);
Parameters • IBaseInterface* in_Interface:
The interface to be deleted.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The pointer to the interface is NULL.
Example C++ // Include The Headerfile Of The API
#include "SimulationRuntimeApi.h"

// Prepare The Variables

ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;
HMODULE dllHandle = NULL;
ApiEntry_DestroyInterface Destroy = NULL;
IInstance* instance = NULL;

// Load The DLL And Import The “DestroyInterface” Function (using the
Windows API)
dllHandle = LoadLibraryA(DAPI_DLL_NAME_X86);
if ( dllHandle != NULL )
{
Destroy = (ApiEntry_ DestroyInterface)GetProcAddress(dllHandle,
DAPI_ENTRY_DESTROY_INTERFACE);
}
…
// Frees the memory of an IInstance interface
result = Destroy(instance);

8.3.1.3 FreeApi()

Description
The FreeApi() function unloads the library of the Runtime API.

S7-PLCSIM Advanced
116 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.3 Shut down API

This function can only be called after the successful call of the InitializeApi If the
InitializeApi function was not called, the library must be unloaded using the Windows
API function FreeLibrary().
Table 8-24 FreeApi() - Native C++
Syntax ERuntimeErrorCode FreeApi();
Parameters None
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_API_NOT_INITIALIZED The InitializeApi function was not called success­
fully.
Example C++ // Include The Headerfile Of The API
#include "SimulationRuntimeApi.h"

// The Interfaces
ERuntimeErrorCode result;
ISimulationRuntimeManager* api = NULL;
IInstance* instance = NULL;

// Init the API

result = InitializeApi(&api);

// Shutdown The API

api->Shutdown();
result = DestroyInterface(api);
api = NULL;
result = FreeApi();

8.3.1.4 ShutdownAndFreeApi()

Description
The ShutdownAndFreeApi() function shuts down the Runtime API, deletes the
IRuntimeManager interface and unloads the library of the Runtime API.
This function can only be called after the successful call of the InitializeApi If the
InitializeApi function was not called, the library must be unloaded using the Windows
API function FreeLibrary().
Table 8-25 ShutdownAndFreeApi() - Native C++
Syntax ERuntimeErrorCode ShutdownAndFreeApi(ISimulationRuntimeManager*
in_SimulationRuntimeManagerInterface);
Parameters • ISimulationRuntimeManager* in_SimulationRuntimeManagerInterface:
The interface of the Runtime Manager to be deleted.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_API_NOT_INITIALIZED The InitializeApi function was not called success­
fully.
SREC_WRONG_ARGUMENT The pointer to the interface is NULL.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 117
User interfaces (API)
8.4 Global functions (Native C++)

Example C++ // Include The Headerfile Of The API

#include "SimulationRuntimeApi.h"

// The Interfaces
ERuntimeErrorCode result;
ISimulationRuntimeManager* api = NULL;
IInstance* instance = NULL;

// Init the API

result = InitializeApi(&api);

// Shutdown The API

result = ShutdownAndFreeApi(api);
api = NULL;

8.3.2 .NET (C#)

8.3.2.1 Shut down API

You can terminate the .NET components of the API for the IInstance and
IRemoteRuntimeManager interfaces by calling the Dispose (Page 149) function.
These interfaces can also be cleared automatically with the .NET Garbage Collector.

Manually clearing the API

To manually clear the API, follow these steps:
1. Delete all interfaces.
You can find more information at Interfaces - Information and settings (Page 148-149).
2. Call the Shutdown() (Page 123) function of the ISimulationRuntimeManager interface.

8.4 Global functions (Native C++)

The global functions GetNameOf... return the name of the enumeration entry
(const WCHAR*).

GetNameOfAreaSection()
Table 8-26 GetNameOfAreaSection() - Native C++
Syntax const WCHAR* GetNameOfAreaSection(EArea in_AreaSection);
Parameters EArea in_AreaSection: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

S7-PLCSIM Advanced
118 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.4 Global functions (Native C++)

GetNameOfCPUType()
Table 8-27 GetNameOfCPUType() - Native C++
Syntax const WCHAR* GetNameOfCPUType(ECPUType in_CPUType);
Parameters ECPUType in_CPUType: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfCommunicationInterface()
Table 8-28 GetNameOfCommunicationInterface() - Native C++
Syntax const WCHAR* GetNameOfCommunicationInterface(ECommunicationInterface
in_CommunicationInterface);
Parameters ECommunicationInterface in_CommunicationInterface:
Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfDataType()
Table 8-29 GetNameOfDataType() - Native C++
Syntax const WCHAR* GetNameOfDataType(EDataType in_DataType);
Parameters EDataType in_DataType: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfErrorCode()
Table 8-30 GetNameOfErrorCode() - Native C++
Syntax const WCHAR* GetNameOfErrorCode(ERuntimeErrorCode in_ErrorCode);
Parameters ERuntimeErrorCode in_ErrorCode: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfLEDMode()
Table 8-31 GetNameOfLEDMode() - Native C++
Syntax const WCHAR* GetNameOfLEDMode(ELEDMode in_LEDMode);
Parameters ELEDMode in_LEDMode: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 119
User interfaces (API)
8.4 Global functions (Native C++)

GetNameOfLEDType()
Table 8-32 GetNameOfLEDType() - Native C++
Syntax const WCHAR* GetNameOfLEDType(ELEDType in_LEDType);
Parameters ELEDType in_LEDType: Enumeration entry.
Return values const WCHAR*: Name of the enumeration entry

GetNameOfOperatingMode()
Table 8-33 GetNameOfOperatingMode() - Native C++
Syntax const WCHAR* GetNameOfOperatingMode(EOperatingMode in_OperatingMode);
Parameters EOperatingMode in_OperatingMode: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfErrorCode()
Table 8-34 GetNameOfErrorCode() - Native C++
Syntax const WCHAR* GetNameOfErrorCode(ERuntimeErrorCode in_ErrorCode);
Parameters ERuntimeErrorCode in_ErrorCode: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfOperatingState
Table 8-35 GetNameOfOperatingState() - Native C++
Syntax const WCHAR* GetNameOfOperatingState(EOperatingState in_OperatingState);
Parameters EOperatingState in_OperatingState: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfPrimitiveDataType
Table 8-36 GetNameOfPrimitiveDataType() - Native C++
Syntax const WCHAR* GetNameOfPrimitiveDataType(EPrimitiveDataType in_DataType);
Parameters EPrimitiveDataType in_DataType: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

S7-PLCSIM Advanced
120 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.4 Global functions (Native C++)

GetNameOfTagListDetails
Table 8-37 GetNameOfTagListDetails() - Native C++
Syntax const WCHAR* GetNameOfTagListDetails(ETagListDetails in_TagListDetails);
Parameters ETagListDetails in_TagListDetails: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfRuntimeConfigChanged()
Table 8-38 GetNameOfRuntimeConfigChanged() - Native C++
Syntax const WCHAR* GetNameOfRuntimeConfigChanged(ERuntimeConfigChanged
in_RuntimeConfigChanged);
Parameters ERuntimeConfigChanged in_RuntimeConfigChanged:
Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfInstanceConfigChanged()
Table 8-39 GetNameOfInstanceConfigChanged() - Native C++
Syntax const WCHAR* GetNameOfInstanceConfigChanged(EInstanceConfigChanged
in_InstanceConfigChanged);
Parameters EInstanceConfigChanged in_InstanceConfigChanged:
Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfDirection()
Table 8-40 GetNameOfDirection() - Native C++
Syntax const WCHAR* GetNameOfDirection(EDirection in_Direction);
Parameter EDirection in_Direction: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfDiagSeverity()
Table 8-41 GetNameOfDiagSeverity() - Native C++
Syntax const WCHAR* GetNameOfDiagSeverity(EDiagSeverity in_DiagSeverity);
Parameter EDiagSeverity in_DiagSeverity: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 121
User interfaces (API)
8.4 Global functions (Native C++)

GetNameOfRackOrStationFaultType()
Table 8-42 GetNameOfRackOrStationFaultType() - Native C++
Syntax const WCHAR* GetNameOfRackOrStationFaultType(ERackOrStationFaultType
in_RackOrStationFaultType);
Parameter ERackOrStationFaultType in_RackOrStationFaultType:
Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfProcessEventType()
Table 8-43 GetNameOfProcessEventType() - Native C++
Syntax const WCHAR*(GetNameOfProcessEventType(EProcessEventType
in_ProcessEventType);
Parameters EProcessEventType in_ProcessEventType: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfPullOrPlugEventType()
Table 8-44 GetNameOfPullOrPlugEventType() - Native C++
Syntax const WCHAR* GetNameOfPullOrPlugEventType(EPullOrPlugEventType
in_PullOrPlugEventType);
Parameters EPullOrPlugEventType in_PullOrPlugEventType:
Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfCycleTimeMonitoringMode()
Table 8-45 GetNameOfCycleTimeMonitoringMode() - Native C++
Syntax const WCHAR* GetNameOfCycleTimeMonitoringMode(ECycleTimeMonitoringMode
in_CycleTimeMonitoringMode);
Parameters ECycleTimeMonitoringMode in_CycleTimeMonitoringMode:
Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfDiagProperty()
Table 8-46 GetNameOfDiagProperty() - Native C++
Syntax const WCHAR* GetNameOfDiagProperty(EDiagProperty in_DiagProperty);
Parameters EDiagProperty in_DiagProperty: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

S7-PLCSIM Advanced
122 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

GetNameOfAutodiscoverType()
Table 8-47 GetNameOfAutodiscoverType() - Native C++
Syntax const WCHAR* GetNameOfAutodiscoverType(EAutodiscoverType
in_AutodiscoverType);
Parameters EAutodiscoverType in_AutodiscoverType: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

GetNameOfSoftwareConfigChanged()
Table 8-48 GetNameOfSoftwareConfigChanged() - Native C++
Syntax const WCHAR* GetNameOfSoftwareConfigChanged(ESoftwareConfigChanged
in_SoftwareConfigChanged);
Parameters ESoftwareConfigChanged in_SoftwareConfigChanged: Enumeration entry
Return values const WCHAR*: Name of the enumeration entry

8.5 API ISimulationRuntimeManager

8.5.1 Interfaces - Information and settings

GetVersion() / Version { get; }

Returns the version of Runtime Manager. If the function fails, version 0.0 is returned.
Table 8-49 GetVersion() - Native C++
Syntax UINT32 GetVersion();
Parameters None
Return values UINT32: Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

Table 8-50 Version { get; } - .NET (C#)

Syntax UInt32 Version { get; }
Parameters None
Return values Uint32: Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

IsInitialized() / IsInitialized { get; }

Returns a value that indicates whether the API was successfully initialized.
Table 8-51 IsInitialized() - Native C++
Syntax bool IsInitialized();
Parameters None
Return values • false: If the API was not initialized.
• true: If the API was initialized.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 123
User interfaces (API)
8.5 API ISimulationRuntimeManager

Table 8-52 IsInitialized { get; } - .NET (C#)

Syntax bool IsInitialized { get; }
Parameters None
Return values • false: If the API was not initialized.
• true: If the API was initialized.

IsRuntimeManagerAvailable() / IsRuntimeManagerAvailable { get; }

The function returns false when the connection to Runtime Manager is interrupted. This
happens only when the Runtime Manager process is closed.
Subscribe to the OnRuntimeManagerLost() event to find out whether the connection is
interrupted. See Events (Page 143).
Table 8-53 IsRuntimeManagerAvailable() - Native C++
Syntax bool IsRuntimeManagerAvailable();
Parameters None
Return values • false: If the connection is interrupted.
• true: If the connection is active.

Table 8-54 IsRuntimeManagerAvailable { get; } - .NET (C#)

Syntax bool IsRuntimeManagerAvailable{ get; }
Parameters None
Return values • false: If the connection is interrupted.
• true: If the connection is active.

Shutdown()
Ends communication with Runtime Manager and clears the interfaces.
Call this function in the following cases:
• Immediately before the API library (DLL) is unregistered (native C++).
• When your application is no longer using Runtime Manager.
Table 8-55 Shutdown() - Native C++
Syntax ERuntimeErrorCode Shutdown()
Parameters None
Return values Runtime error code Description
SREC_OK The function is successful.

Table 8-56 Shutdown() - .NET (C#)

Syntax void Shutdown()
Parameters None
Return values None

S7-PLCSIM Advanced
124 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

GetStrictMotionTiming() / StrictMotionTiming { get; }

Returns the current global setting for the "Strict Motion Timing" feature that has an effect on
newly created instances. The "Strict Motion Timing" feature is located on the S7-PLCSIM
Advanced Control Panel (Page 59).
Table 8-57 GetStrictMotionTiming() - Native C++
Syntax ERuntimeErrorCode GetStrictMotionTiming(bool* enabled);
Parameters bool* enabled:
Receives the current setting.
true: Active
false: Inactive
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_CONFIG_FILE_ERROR The setting could not be read from the configuration
file UserInterfaceConfiguration.xml.

Table 8-58 StrictMotionTiming { get; } - .NET (C#)

Syntax bool StrictMotionTiming { get; }
Parameters None
Return values Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.ConfigFileError The setting could not be read from the configura­
tion file UserInterfaceConfiguration.xml.

SetStrictMotionTiming() / StrictMotionTiming { set; }

Sets the global setting for the "Strict Motion Timing" feature that has an effect on newly
created instances. The "Strict Motion Timing" feature is located on the S7-PLCSIM Advanced
Control Panel (Page 59).
Table 8-59 SetStrictMotionTiming() - Native C++
Syntax ERuntimeErrorCode SetStrictMotionTiming(bool enable);
Parameters bool enable:
The value to be set.
true: Active
false: Inactive
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_ALREADY_EXISTS An instance is registered. No instance must be
registered to change the setting.
SREC_TIMEOUT The function does not return on time.
SREC_ACCESS_DENIED No write rights for the configuration file.
SREC_CONFIG_FILE_ERROR The setting could not be written to the configuration
file UserInterfaceConfiguration.xml.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 125
User interfaces (API)
8.5 API ISimulationRuntimeManager

Table 8-60 StrictMotionTiming { set; } - .NET (C#)

Syntax bool StrictMotionTiming { set; }
Parameters None
Return values Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.AlreadyExists An instance is registered. No instance must be
registered to change the setting.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.AccessDenied No write rights for the configuration file.
ERuntimeErrorCode.ConfigFileError The setting could not be written to the configura­
tion file UserInterfaceConfiguration.xml.

GetNetworkMode()
Returns the current network mode settings that are used in the network adapter for
distributed communication.
Table 8-61 GetNetworkMode() - Native C++
Syntax ERuntimeErrorCode
ISimulationRuntimeManager::GetNetworkMode(ECommunicationMode* out_Mode);
Parameters ECommunicationMode* out_Mode:
Receives the network mode as #ECommunicationMode that is currently set in the driver of the S7-PLC­
SIM Advanced Virtual Switch
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_VIRTUAL_SWITCH_MISCONFIGURED The S7-PLCSIM Advanced Virtual Switch is con­
figured incorrectly.

SetNetworkMode()
Sets the network mode as used in the network adapter for distributed communication.
Check that the binding on the network interfaces is correct.
Table 8-62 SetNetworkMode() - Native C++
Syntax ERuntimeErrorCode
ISimulationRuntimeManager::SetNetworkMode(constECommunicationMode
in_Mode);
Parameters ECommunicationMode in_Mode:
Type of network communication mode to be set
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_VIRTUAL_SWITCH_MISCONFIGURED The driver of the S7-PLCSIM Advanced Virtual
Switch is not running.

S7-PLCSIM Advanced
126 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

NetworkMode { get; set; };

Returns or sets the network mode used on the network adapter for distributed
communication.
Check that the binding on the network interfaces is correct.
Table 8-63 NetworkMode { get; set; } - .NET (C#)
Syntax ECommunicationMode SimulationRuntimeManager::NetworkMode { get; set; }
Return value ECommunicationMode:
Type of network communication mode to be set
Exceptions Runtime error code Description
ERuntimeErrorCode. The driver of the S7-PLCSIM Advanced Virtual
VirtualSwitchMisconfigured Switch is not running.

GetNetInterfaceMapping()
Returns an interface index of the PC interface to which a specific CPU interface is mapped.
Use the GetNetInterfaces() function to get a list of PC interfaces with interface index.
The value 0 means that no mapping has been set.
Note that GetNetInterfaceMapping() only returns a mapping table and not the actual address
while the instance is running.
Table 8-64 GetNetInterfaceMapping() - Native C++ und .NET (C#)
Syntax C++ INT32 IInstance::GetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID);
Syntax .NET (C#) int IInstance::GetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID);
Parameters EPLCInterface in_PLCInterfaceID: ID of the CPU interface for which you want to get the
mapping.
Return values Value Description
Greater than 0 Index of mapped PC interface
0 No mapping was defined for the CPU interface.
-1 The mapping could not be delivered.

SetNetInterfaceMapping()
Sets interface mappings between CPU interface and PC interface. Ethernet packets that a
certain PC interface receives are forwarded to the assigned CPU interface. Use the
GetNetInterfaces() function to get a list of PC interfaces.
Mapping of PLCSIM Virtual Ethernet adapters is not possible.
Table 8-65 SetNetInterfaceMapping() - Native C++
Syntax ERuntimeErrorCode
IInstance::SetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID, DWORD in_PCInterfaceIndex);
ERuntimeErrorCode
IInstance::SetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID, const WCHAR*
in_PCInterfaceName);
ERuntimeErrorCode
IInstance::SetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID, const SMACAddress*
in_MACAddressParam);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 127
User interfaces (API)
8.5 API ISimulationRuntimeManager

Parameters EPLCInterface in_PLCInterfaceID:

ID of the CPU interface for which a MAC address is to be set (EPLCInterface (Page 323)).
DWORD* in_PCInterfaceIndex:
Index of the PC interface; if this value is 0, the mapping is deleted.
const WCHAR* in_PCInterfaceName:
Name of the PC interface
const UMACAddress* in_MACAddressParam:
Hardware MAC address of the PC interface
You get these values with the function GetNetInterfaces().
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_WRONG_COMMUNICATION_INTERFACE The PC interface does not exist or is not compatible
(disabled, not connected, or a PLCSIM Virtual Ether­
net Adapter).
SREC_ALREADY_EXISTS The PC interface has already been assigned to
another CPU interface.
SREC_CONFIG_FILE_ERROR An error occurred when writing the configuration to
the file "sim_hwdb.ini".
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.

Table 8-66 SetNetInterfaceMapping() - .NET (C#)

Syntax IInstance::SetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID, uint
in_PCInterfaceIndex);
IInstance::SetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID, const
String in_PCInterfaceName);
IInstance::SetNetInterfaceMapping(EPLCInterface in_PLCInterfaceID, const
SMACAddress in_MACAddressParam);
Exceptions Runtime error code Description
ERuntimeErrorCode. The PC interface does not exist or is not compatible
WrongCommunicationInterface (disabled, not connected, or a PLCSIM Virtual Ether­
net Adapter).
ERuntimeErrorCode.AlreadyExists The PC interface has already been assigned to
another CPU interface.
ERuntimeErrorCode.ConfigFileError An error occurred when writing the configuration to
the file "sim_hwdb.ini".
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.

GetNetInterfaces()
Provides information on the PC interfaces, which you can use for
SetNetInterfaceMapping.
Table 8-67 GetNetInterfaces() - Native C++
Syntax ERuntimeErrorCode
ISimulationRuntimeManager::GetNetInterfaces(SNetInterfaceInfo*
inout_InterfaceInfo, UINT* inout_InterfaceCount);
Parameters SNetInterfaceInfo* inout_InterfaceInfo:
Address of the first item of the SNetInterfaceInfo array, which contains information about PC network
adapters. If the value is NULL, only the number of network adapters has been requested.
UINT* inout_InterfaceCount:
For the input: Number of SNetInterfaceInfo items assigned by the user.
For the output: Number of network adapters (array items)

S7-PLCSIM Advanced
128 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INDEX_OUT_OF_RANGE The number of array units is lower than the number
of network adapters.
SREC_INTERNAL_ERROR The system call has caused an internal error.
Example C++ #include <iostream>
#include "SimulationRuntimeApi.h"

ISimulationRuntimeManager* rtm = nullptr;

ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;

//init connection
InitializeApi(&rtm);

//get count of network interfaces

UINT count;
result = rtm->GetNetInterfaces(nullptr, &count);

//get actual network interfaces

std::unique_ptr<SNetInterfaceInfo[]> netInterfaces =
std::make_unique<SNetInterfaceInfo[]>(count);
result = rtm->GetNetInterfaces(netInterfaces.get(), &count);

ShutdownAndFreeApi(rtm);

Table 8-68 GetNetInterfaces() - .NET (C#)

Syntax SNetInterfaceInfo[] NetInterfaces { get; }
Return values Runtime error code Description
SNetInterfaceInfo[] Information about the PC network interfaces
Exceptions ERuntimeErrorCode.InternalError The system call has caused an internal error.

CheckNetInterfaceMapping()
The function checks the validity of the interface mapping to be able to start the instance. All
PC instances already running are checked for possible duplicate mappings. The function also
checks whether the binding to the PC network interfaces is valid.
Table 8-69 CheckNetInterfaceMapping() - Native C++
Syntax ERuntimeErrorCode IInstance::CheckNetInterfaceMapping();
Parameters None
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INVALID_CONFIGURATION The configuration is invalid.
Examples:
• The current instance has a mapped PC network
interface that is already in use by another run­
ning instance.
• A mapped PLCSIM Virtual Ethernet Adapter
exists.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 129
User interfaces (API)
8.5 API ISimulationRuntimeManager

Return values SREC_VIRTUAL_SWITCH_MISCONFIGURED The binding of an S7-PLCSIM Advanced Virtual

Switch on a PC network interface is not correct, or
the driver of an S7-PLCSIM Advanced Virtual Switch
is not functioning properly.
If the binding is not correct, call the
SetNetInterfaceBindings() function or set
the binding manually before starting the instance.
SREC_WARNING_NO_EXTERNAL_COMMUNICAT- You have set the Multi-Adapter Network Mode
ION (non-promiscuous mode) without interface map­
ping or Softbus as communication interface.
SREC_INTERNAL_ERROR The system call has caused an internal error.
SREC_WRONG_COMMUNICATION_INTERFACE The PC interface does not exist or is not compatible
(disabled, not connected, or a PLCSIM Virtual Ether­
net Adapter).
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.

Table 8-70 CheckNetInterfaceMapping() - .NET (C#)

Syntax ERuntimeErrorCode IInstance::CheckNetInterfaceMapping()
Return values Runtime error code Description
ERuntimeErrorCode.OK The function is successful.
ERuntimeErrorCode. The configuration is invalid.
InvalidConfiguration Examples:
• The current instance has a mapped PC network
interface that is already in use by another run­
ning instance.
• A mapped PLCSIM Virtual Ethernet Adapter
exists.
ERuntimeErrorCode. The binding of an S7-PLCSIM Advanced Virtual
VirtualSwitchMisconfigured Switch on a PC network interface is not correct, or
the driver of an S7-PLCSIM Advanced Virtual Switch
is not functioning properly.
If the binding is not correct, call the
SetNetInterfaceBindings() function or set
the binding manually before starting the instance.
ERuntimeErrorCode. You have set the Multi-Adapter Network Mode
WarningNoExternalCommunication (non-promiscuous mode) without interface map­
ping or Softbus as communication interface.
ERuntimeErrorCode.InternalError The system call has caused an internal error.
ERuntimeErrorCode. The PC interface does not exist or is not compatible
WrongCommunicationInterface (disabled, not connected, or a PLCSIM Virtual Ether­
net Adapter)
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.

SetNetInterfaceBindings()
Sets the binding of an S7-PLCSIM Advanced Virtual Switch to PC interfaces based on the
network mode and the mapping configuration of the network interfaces for the instance.

S7-PLCSIM Advanced
130 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

You must call the function from a parent session (administrator mode), otherwise you cannot
access it, and the message SREC_ACCESS_DENIED appears.
Table 8-71 SetNetInterfaceBindings() - Native C++
Syntax ERuntimeErrorCode
ISimulationRuntimeManager::SetNetInterfaceBindings(DWORD
in_PCInterfaceIndex = 0);
Parameters DWORD in_PCInterfaceIndex = 0:
• When Single Adapter Network Mode (promiscuous mode) is set, you can specify the index of the
PC interfaces for network communication. To enable only local PC communication, use the value
(0).
• When Multi-Adapter Network Mode (non-promiscuous mode) is set, this parameter is not used and
the binding is set according to the configured mapping of the interfaces.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INVALID_CONFIGURATION The configuration is invalid because, for example, a
non-existent adapter was used.
SREC_ACCESS_DENIED You do not have authorization to connect to the PC
network interfaces.
SREC_WRONG_COMMUNICATION_INTERFACE The PC interface does not exist.
SREC_INTERNAL_ERROR The system call has caused an internal error.
Enable the traces to obtain detailed information.
SREC_NOT_ALLOWED In Single Adapter Network Mode (promiscuous
mode), it is not permitted to change the binding
while an instance is running.
SREC_VIRTUAL_SWITCH_MISCONFIGURED The configuration of an S7-PLCSIM Advanced Virtual
Switch is not correct or the driver is not functioning
properly.

Table 8-72 SetNetInterfaceBindings() - .NET (C#)

Syntax void ISimulationRuntimeManager::SetNetInterfaceBindings();
void ISimulationRuntimeManager::SetNetInterfaceBindings(DWORD
in_PCInterfaceIndex);
Exceptions Runtime error code Description
ERuntimeErrorCode. The configuration is invalid because, for example, a
InvalidConfiguration non-existent adapter was used.
ERuntimeErrorCode.AccessDenied You do not have authorization to connect to the PC
network interfaces.
ERuntimeErrorCode. The PC interface does not exist.
WrongCommunicationInterface
ERuntimeErrorCode.InternalError The system call has caused an internal error.
Enable the traces to obtain detailed information.
ERuntimeErrorCode.NotAllowed In Single Adapter Network Mode (promiscuous
mode), it is not permitted to change the binding
while an instance is running.
ERuntimeErrorCode. The configuration of an S7-PLCSIM Advanced Virtual
VirtualSwitchMisconfigured Switch is not correct or the driver is not functioning
properly.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 131
User interfaces (API)
8.5 API ISimulationRuntimeManager

ResetNetInterfaceBindings()
Deactivates the binding of an S7-PLCSIM Advanced Virtual Switch to PC interfaces. The
binding on the Siemens PLCSIM Virtual Ethernet Adapter remains.
You must call the function from a parent session (administrator mode), otherwise you cannot
access it, and the message SREC_ACCESS_DENIED appears.
Table 8-73 ResetNetInterfaceBindings() - Native C++
Syntax ERuntimeErrorCode
ISimulationRuntimeManager::ResetNetInterfaceBindings();
Parameters None
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_ACCESS_DENIED You do not have authorization to connect to the PC
network interfaces.
SREC_NOT_ALLOWED In Single Adapter Network Mode (promiscuous
mode), it is not permitted to change the binding
while an instance is running.
SREC_INTERNAL_ERROR The system call has caused an internal error.
Enable the traces to obtain detailed information.

ResetNetInterfaceBindings() - .NET (C#)

Syntax void ISimulationRuntimeManager::ResetNetInterfaceBindings();
Exceptions Runtime error code Description
ERuntimeErrorCode.AccessDenied You do not have authorization to connect to the PC
network interfaces.
ERuntimeErrorCode.InternalError The system call has caused an internal error.
Enable the traces to obtain detailed information.
ERuntimeErrorCode.NotAllowed In Single Adapter Network Mode (promiscuous
mode), it is not permitted to change the binding
while an instance is running.

8.5.2 Simulation Runtime instances

GetRegisteredInstancesCount()
Returns the number of instances that are registered in Runtime Manager. If the function fails,
the return value is 0.
Table 8-74 GetRegisteredInstancesCount() - Native C++
Syntax UINT32 GetRegisteredInstancesCount();
Parameters None
Return values UINT32: Number of available instances.

S7-PLCSIM Advanced
132 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

GetRegisteredInstanceInfoAt()
Returns information about an already registered instance. You can use the ID or name to
create an interface of this instance, see CreateInterface().
Table 8-75 GetRegisteredInstanceInfoAt() - Native C++
Syntax ERuntimeErrorCode GetRegisteredInstanceInfoAt(UINT32 in_Index,
SInstanceInfo* out_InstanceInfo);
Parameters • UINT32 in_Index:
Index of the created instance from which you want to receive the information. The index must be
less than the value you receive when you call GetRegisteredInstanceCount().
• SInstanceInfo* out_InstanceInfo:
The information with name and ID of the instance. See Data types (Page 297).
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_DOES_NOT_EXIST There is no instance information for this index.
SREC_INDEX OUT_OF_RANGE The index is greater than 15.

RegisteredInstanceInfo { get; }
Returns information about all already registered instances. Use the ID or name of this
instance to create an interface of this instance; see CreateInterface().
Table 8-76 RegisteredInstanceInfo { get; } - .NET (C#)
Syntax SInstanceInfo[] RegisteredInstanceInfo { get; }
Parameters None
Return values SInstanceInfo[]: An array of information about all registered instances.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.

RegisterInstance()
Registers a new instance of a virtual controller in Runtime Manager. Creates and returns an
interface of this instance.
Table 8-77 RegisterInstance() - Native C++
Syntax ERuntimeErrorCode RegisterInstance(IInstance** out_InstanceInterface);
ERuntimeErrorCode RegisterInstance(WCHAR* in_InstanceName, IInstance**
out_InstanceInterface);
ERuntimeErrorCode RegisterInstance(ECPUType in_CPUType, IInstance**
out_InstanceInterface);
ERuntimeErrorCode RegisterInstance(ECPUType in_CPUType,WCHAR*
in_InstanceName, IInstance** out_InstanceInterface);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 133
User interfaces (API)
8.5 API ISimulationRuntimeManager

Parameters • ECPUType in_CPUType:

Defines which CPU type is simulated at the start of the instance. The default setting is
"SRCT_1500_Unspecified".
When a different CPU type is loaded via STEP 7 or from the Virtual SIMATIC Memory Card, this CPU
type applies.
• WCHAR* in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which
the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
• IInstance** out_InstanceInterface:
Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The
interface is created within the function.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The name or the IInstance pointer is invalid.
SREC_LIMIT_REACHED There are already 16 instances registered in
Runtime Manager.
SREC_ALREADY_EXISTS An instance with this name already exists.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

// Example: How To Create And Register An Instance

IInstance* psa = NULL;
if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}

NOTE
Native C++
If you no longer require the interface, delete the interface (Page 115).

Table 8-78 RegisterInstance() - .NET (C#)

Syntax IInstance RegisterInstance();
IInstance RegisterInstance(string in_InstanceName);
IInstance RegisterInstance(ECPUType in_CPUType);
IInstance RegisterInstance(ECPUType in_CPUTypestring in_InstanceName);
Parameters • ECPUType in_CPUType:
Defines which CPU type is simulated at the start of the instance. The default setting is
"ECPUType.Unspecified".
When a different CPU type is loaded via STEP 7 or from the Virtual SIMATIC Memory Card, this CPU
type applies.
• string in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which
the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
Return values If the function is successful it returns an interface of a virtual controller; otherwise, the function
returns a Null pointer.

S7-PLCSIM Advanced
134 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The name is invalid.
ERuntimeErrorCode.LimitReached There are already 16 instances registered in
Runtime Manager.
ERuntimeErrorCode.AlreadyExists An instance with this name already exists.

RegisterCustomInstance()
Registers a new instance of a virtual controller in Runtime Manager. Creates and returns an
interface of this instance.
Table 8-79 RegisterCustomInstance() - Native C++
Syntax ERuntimeErrorCode RegisterCustomInstance(WCHAR* in_VplcDll, IInstance**
out_InstanceInterface);
ERuntimeErrorCode RegisterCustomInstance(WCHAR* in_VplcDll, WCHAR*
in_InstanceName, IInstance** out_InstanceInterface);
Parameters • WCHAR* in_VplcDll:
The complete path to the DLL of the virtual controller that "Siemens.Simatic.Simula­
tion.Runtime.Instance.exe" loads at PowerOn.
• WCHAR* in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which
the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
• IInstance** out_InstanceInterface:
Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The
interface is created within the function.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The DLL name, the instance name or the IInstance
pointer is invalid.
SREC_LIMIT_REACHED There are already 16 instances registered in
Runtime Manager.
SREC_ALREADY_EXISTS An instance with this name already exists.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

// Example: How To Create And Register An Instance

IInstance* psa = NULL;
if (result == SREC_OK)
{
result = api->RegisterCustomInstance(L"C:\\Temp\\vplc.dll");
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 135
User interfaces (API)
8.5 API ISimulationRuntimeManager

NOTE
Native C++
If you no longer require the interface, delete the interface.
For information on how to delete an interface, see DestroyInterface() (Page 115).

Table 8-80 RegisterCustomInstance() - .NET (C#)

Syntax IInstance RegisterCustomInstance(string in_VplcDll);
IInstance RegisterCustomInstance(string in_VplcDll, string
in_InstanceName);
Parameters • string in_VplcDll:
The complete path to the DLL of the virtual controller that "Siemens.Simatic.Simula­
tion.Runtime.Instance.exe" loads at PowerOn.
• string in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which
the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
Return values If the function is successful it returns an interface of a virtual controller; otherwise, the function
returns a Null pointer.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The name or the ID is invalid.
ERuntimeErrorCode.LimitReached There are already 16 instances registered in
Runtime Manager.
ERuntimeErrorCode.AlreadyExists An instance with this name already exists.

CreateInterface()
Creates and returns an interface of an already registered instance of a virtual controller.
The instance could have been registered via the application or another application that uses
the Simulation Runtime API.
Table 8-81 CreateInterface() - Native C++
Syntax ERuntimeErrorCode CreateInterface(WCHAR* in_InstanceName, IInstance**
out_InstanceInterface);
ERuntimeErrorCode CreateInterface(INT32 in_InstanceID, IInstance**
out_InstanceInterface);
Parameters • INT32 in_InstanceID:
The ID of the registered instance from which you want to receive the interface.
• WCHAR* in_InstanceName:
The name of the registered instance from which you want to receive the interface.
• IInstance** out_InstanceInterface:
Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The
interface is created within the function.

S7-PLCSIM Advanced
136 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The ID or the IInstance pointer is invalid.
SREC_DOES_NOT_EXIST The instance is not registered in Runtime Manager.
SREC_INDEX_OUT_OF_RANGE The ID is outside the valid limit. The maximum value
is 127.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IInstance* psa1 = NULL;

IInstance* psa2 = NULL;
if (result == SREC_OK)
{
result = api->CreateInterface(0, &psa1);
result = api->CreateInterface(0, &psa2); // psa2 will be the same as psa1
}
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IInstance* psa = NULL;

if (result == SREC_OK)
{
result = api->CreateInterface(L"My SimulationRuntime Instance", &psa);
}

NOTE
Native C++
If you no longer require the interface, delete the interface (Page 115).

Table 8-82 CreateInterface() - .NET (C#)

Syntax IInstance CreateInterface(string in_InstanceName);
IInstance CreateInterface(INT32 in_InstanceID);
Parameters • INT32 in_InstanceID:
The ID of the registered instance from which you want to receive the interface.
• string in_InstanceName:
The name of the registered instance from which you want to receive the interface.
Return values If the function is successful it returns an interface of a virtual controller; otherwise, the function
returns a Null pointer.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The ID is invalid.
ERuntimeErrorCode.DoesNotExists The instance is not registered in Runtime Manager.
IndexOutOfRange The ID is outside the valid limit. The maximum value
is 127.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 137
User interfaces (API)
8.5 API ISimulationRuntimeManager

8.5.3 Remote connections

OpenPort()
Opens a port to which another Runtime Manager can connect.
Table 8-83 OpenPort() - Native C++
Syntax ERuntimeErrorCode OpenPort(UINT16 in_Port);
Parameters • UINT16 in_Port:
The port. The value must be greater than 1024.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_ALREADY_EXISTS A port is already open.
SREC_WRONG_ARGUMENT The port is invalid.
SREC_CONNECTION_ERROR The port cannot be opened.

Table 8-84 OpenPort() - .NET (C#)

Syntax void OpenPort(UInt16 in_Port);
Parameters • UInt16 in_Port:
The port. The value must be greater than 1024.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.AlreadyExists A port is already open.
ERuntimeErrorCode.WrongArgument The port is invalid.
ERuntimeErrorCode.ConnectionError The port cannot be opened.

ClosePort()
Closes an open port and all open connections that another Runtime Manager has created to
this open port.
Table 8-85 ClosePort() - Native C++
Syntax ERuntimeErrorCode ClosePort();
Parameters None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_WARNING_INVALID_CALL No port is open.

S7-PLCSIM Advanced
138 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

Table 8-86 ClosePort() - .NET (C#)

Syntax void ClosePort(UInt16 in_Port);
Parameters None
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.

GetPort() / Port { get; }

Returns the open port. If no port is open or the function fails, the return value is 0.
Table 8-87 GetPort() - Native C++
Syntax UINT16 GetPort();
Parameters None
Return values UINT16: The open port. 0, if no port is open.

Table 8-88 Port { get; } - .NET (C#)

Syntax UInt16 Port { get; }
Parameters None
Return values UInt16: The open port. 0, if no port is open.
Exceptions None

GetRemoteConnectionsCount()
Supplies the number of open remote connections.
Table 8-89 GetRemoteConnectionsCount() - Native C++
Syntax UINT32 GetRemoteConnectionsCount();
Parameters None
Return values UINT32: Number of open remote connections.

GetRemoteConnectionInfoAt()
Returns information about an open connection.
Table 8-90 GetRemoteConnectionInfoAt()- Native C++
Syntax ERuntimeErrorCode GetRemoteConnectionInfoAt(UINT32 in_Index,
SConnectionInfo* out_ConnectionInfo);
Parameters • UINT32 in_Index:
Index of the connection information that is expected.
• SConnectionInfo* out_ConnectionInfo:
The connection information for this index.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 139
User interfaces (API)
8.5 API ISimulationRuntimeManager

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_INDEX_OUT_OF_RANGE Connection information for this index does not
exist.

RemoteConnectionInfo { get; }
Returns an array of information about all open connections.
Table 8-91 RemoteConnectionInfo { get; } - .NET (C#)
Syntax SConnectionInfo[] RemoteConnectionInfo { get; }
Parameters None
Return values SConnectionInfo[]: An array of information about all open connections.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.

RemoteConnect()
Creates a new connection to a remote Runtime Manager or uses an existing connection to
create an IRemoteRuntimeManager interface.
Table 8-92 RemoteConnect() - Native C++
Syntax ERuntimeErrorCode RemoteConnect(UINT8 in_IP3, UINT8 in_IP2, UINT8 in_IP1,
UINT8 in_IP0, UINT16 in_Port,
IRemoteRuntimeManager**out_RemoteRuntimeManagerInterface);
ERuntimeErrorCode RemoteConnect(UIP in_IP, UINT16 in_Port,
IRemoteRuntimeManager** out_RunTimeManagerInterface);
Parameters • UINT8 in_IP3:
First part of the IP address of the remote PC.
• UINT8 in_IP2:
Second part of the IP address of the remote PC.
• UINT8 in_IP1:
Third part of the IP address of the remote PC.
UINT8 in_IP0:
Last part of the IP address of the remote PC.
• UIP in_IP:
IP address of the remote PC.
• UINT16 in_Port:
The port that is open on the remote PC.
• IRemoteRuntimeManager** out_RemoteRuntimeManagerInterface:
Pointer to a remote Runtime Manager interface pointer. The pointer must be initialized with NULL.
The interface is created in the function.

S7-PLCSIM Advanced
140 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_CONNECTION_ERROR The connection to the remote Runtime Manager
cannot be established.
SREC_WRONG_ARGUMENT IP, port or IInstance pointer is invalid.
SREC_WRONG_VERSION The version of the API is not compatible with
Runtime.
See Compatibility in case of updates (Page 20).
Example C++ ISimulationRuntimeManager* api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IRemoteRuntimeManager * client = NULL;

if (result == SREC_OK)
{
result = api->RemoteConnect(192,203,145,144, 4444, &client);
}

NOTE
Native C++
If you no longer require the interface, delete the interface.
See DestroyInterface() (Page 115).

Table 8-93 RemoteConnect() - .NET (C#)

Syntax IRemoteRuntimeManager RemoteConnect(string in_ConnectionString);
IRemoteRuntimeManager RemoteConnect(SIP in_IP, UInt16 in_Port);
IRemoteRuntimeManager RemoteConnect(Byte in_IP3, Byte in_IP2, Byte in_IP1,
Byte in_IP0, UInt16 in_Port);
Parameters • Byte in_IP3:
First part of the IP address of the remote PC.
• Byte in_IP2:
Second part of the IP address of the remote PC.
• Byte in_IP1:
Third part of the IP address of the remote PC.
• Byte in_IP0:
Last part of the IP address of the remote PC.
• string in_ConnectionString:
A string in the form of "<IP3>.<IP2>.<IP1>.<IP0>:<Port>"
Example: "182.203.145.144:4444".
• SIP in_IP:
IP address of the remote PC.
• UInt16 in_Port:
The port that is open on the remote PC.
Return values IRemoteRuntimeManager: Interface to the remote Runtime Manager.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.ConnectionError Connection to the remote Runtime Manager cannot
be established.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument IP or port is invalid.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 141
User interfaces (API)
8.5 API ISimulationRuntimeManager

Exceptions ERuntimeErrorCode.WrongVersion The version of the API is not compatible with

Runtime.
See Compatibility in case of updates (Page 20).

8.5.3.1 RunAutodiscover()

Description
This function identifies all Runtime Managers that are on the network and that are ready to
establish a remote connection.

NOTE

The function identifies Runtime Managers as of PLCSIM Advanced V5.0.

Requirements
• The Runtime Manager must be running and allowing remote connections.
• The firewall of the remote PC must not block traffic on the selected UDP port.
• Devices in the local network (such as routers, switches, firewalls) must not block multicast
packets of the selected class.

RunAutodiscover()
The function starts the identification of the Runtime Manager in the network.
Table 8-94 RunAutodiscover() - Native C++
Syntax ERuntimeErrorCode RunAutodiscover(UINT32 in_Timeout = 2000);
Parameters • UINT32 in_Timeout
A timeout value in milliseconds that defines how long the local Runtime Manager waits for
responses from the Remote Manager.
A value between 500 ms and 30000 ms is valid.
Default: 2000 ms.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The timeout value is outside the permissible range.
SREC_AUTODISCOVER_ALREADY_RUNNING A RunAutodiscover() call is already running in
the background. Wait for the message
SRRSI_DISCOVER_FINISHED in the callback func­
tion.
See EAutodiscoverType (Page 334).
SREC_TIMEOUT Communication errors in the local Runtime Man­
ager.

S7-PLCSIM Advanced
142 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

Table 8-95 RunAutodiscover() - .NET (C#)

Syntax void RunAutodiscover(UInt32 in_Timeout = 2000);
Parameters • UInt32 in_Timeout
A timeout value in milliseconds that defines how long the local Runtime Manager waits for
responses from the Remote Manager.
A value between 500 ms and 30000 ms is valid.
Default: 2000 ms.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.WrongArgument The timeout value is outside the permissible range.
ERuntimeErrorCode. A RunAutodiscover() call is already running in
AutodiscoverAlreadyRunning the background. Wait for the message
AutodiscoverFinished in the callback function.
See EAutodiscoverType (Page 334).
ERuntimeErrorCode.Timeout Communication errors in the local Runtime Man­
ager.

8.5.4 Events for ISimulationRuntimeManager

Events for runtime instances and remote connections

The following events are triggered for the ISimulationRuntimeManager interface:
Table 8-96 Events for ISimulationRuntimeManager
Event Cause
OnSoftwareConfigurationChanged The Runtime Manager configuration has changed:
events (Page 143) • A new instance is registered.
• An instance is removed.
• A connection to a client is established.
The Control Panel uses such an event to update the list of available instances.
OnRuntimeManagerLost (Page 145) The connection to the Runtime Manager is interrupted.
OnAutodiscoverData events (Page The network searches for Runtime Managers which are ready to establish a remote con­
147) nection.

8.5.4.1 OnSoftwareConfigurationChanged events

OnSoftwareConfigurationChanged
Reports software changes in STOP and RUN modes.
Table 8-97 OnSoftwareConfigurationChanged
Syntax event Delegate_SRSCC OnSoftwareConfigurationChanged();
Parameters IInstance, ERuntimeErrorCode, SYSTEMTIME, ESoftwareConfigChanged

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 143
User interfaces (API)
8.5 API ISimulationRuntimeManager

Return values None

Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnSoftwareConfigurationChangedCallback()
When the event occurs, the registered callback function is called. Only one callback function
can be registered for the event. The registration of a new callback function causes the
previous callback function to be deleted.
Table 8-98 RegisterOnSoftwareConfigurationChangedCallback() - Native C++
Syntax void RegisterOnSoftwareConfigurationChangedCallback();
Parameters CallbackFunction
Return values None
Note The event handler method runs in a separate thread.

RegisterOnSoftwareConfigurationChangedEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registration of a new event object causes the
previous event object to be deleted.
Table 8-99 RegisterOnSoftwareConfigurationChangedEvent() - Native C++
Syntax void RegisterOnSoftwareConfigurationChangedEvent();
Parameters • None
An internal event object is registered.
• HANDLE*
A handle for a user-specific event object. The event object is registered.
Return values None

UnregisterOnSoftwareConfigurationChangedCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 8-100 UnregisterOnSoftwareConfigurationChangedCallback() - Native C++
Syntax void UnregisterOnSoftwareConfigurationChangedCallback();
Parameters None
Return values None

S7-PLCSIM Advanced
144 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

UnregisterOnSoftwareConfigurationChangedEvent()
Unregisters the event object.
Table 8-101 UnregisterOnSoftwareConfigurationChangedEvent() - Native C++
Syntax void UnregisterOnSoftwareConfigurationChangedEvent();
Parameters None
Return values None

Table 8-102 UnregisterOnSoftwareConfigurationChangedEvent() - .NET (C#)

Syntax void UnregisterOnSoftwareConfigurationChangedEvent();
Parameters None
Return values None

WaitForOnSoftwareConfigurationChangedEvent()
The function blocks the program until the registered event object is set to the signaled state
or the timeout interval is exceeded.
Table 8-103 WaitForOnSoftwareConfigurationChangedEvent() - Native C++
Syntax void WaitForOnSoftwareConfigurationChangedEvent();
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.
Note The function blocks the CoSimulation program until a software download is set to the signaled state
or the timeout interval is exceeded.

Table 8-104 WaitForOnSoftwareConfigurationChangedEvent() - .NET (C#)

Syntax void WaitForOnSoftwareConfigurationChangedEvent();
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.
Note The function blocks the CoSimulation program until a software download is set to the signaled state
or the timeout interval is exceeded.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 145
User interfaces (API)
8.5 API ISimulationRuntimeManager

8.5.4.2 OnRuntimeManagerLost events

OnRuntimeManagerLost
Registers or unregisters an event handler method.
Table 8-105 OnRuntimeManagerLost - .NET (C#)
Syntax event Delegate_Void OnRuntimeManagerLost;
Parameters None. See Delegate_Void (Page 290).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnRuntimeManagerLostCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-106 RegisterOnRuntimeManagerLostCallback() - Native C++
Syntax void RegisterOnRuntimeManagerLostCallback(EventCallback_VOID
in_CallbackFunction);
Parameters • EventCallback_VOID in_CallbackFunction:
A callback function that subscribes to the event.
See EventCallback_VOID (Page 281-282).
Return values None
Note The event handler method runs in a separate thread.

RegisterOnRuntimeManagerLostEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registration of a new event object causes the
previous event object to be deleted.
Table 8-107 RegisterOnRuntimeManagerLostEvent() - Native C++
Syntax void RegisterOnRuntimeManagerLostEvent();
void RegisterOnRuntimeManagerLostEvent(HANDLE* in_Event);
Parameters • None:
An internal event handle is registered.
• HANDLE* in_Event:
A user-specific event handle is registered.
Return values None

Table 8-108 RegisterOnRuntimeManagerLostEvent() - .NET (C#)

Syntax void RegisterOnRuntimeManagerLostEvent();
Parameters None
Return values None

S7-PLCSIM Advanced
146 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.5 API ISimulationRuntimeManager

UnregisterOnRuntimeManagerLostCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 8-109 UnregisterOnRuntimeManagerLostCallback() - Native C++
Syntax void UnregisterOnRuntimeManagerLostCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

UnregisterOnRuntimeManagerLostEvent()
Unregisters the event object.
Table 8-110 UnregisterOnRuntimeManagerLostEvent() - Native C++
Syntax void UnregisterOnRuntimeManagerLostEvent();
Parameters None
Return values None

Table 8-111 UnregisterOnRuntimeManagerLostEvent() - .NET (C#)

Syntax void UnregisterOnRuntimeManagerLostEvent();
Parameters None
Return values None

WaitForOnRuntimeManagerLostEvent()
The function will block the program until the registered event object is set to the signaled
state or the timeout interval is exceeded.
Table 8-112 WaitForOnRuntimeManagerLostEvent() - Native C++
Syntax bool WaitForOnRuntimeManagerLostEvent();
bool WaitForOnRuntimeManagerLostEvent(UINT32 in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined timeout interval.

Table 8-113 WaitForOnRuntimeManagerLostEvent() - .NET (C#)

Syntax bool WaitForOnRuntimeManagerLostEvent();
bool WaitForOnRuntimeManagerLostEvent(UInt32 in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UInt32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined timeout interval.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 147
User interfaces (API)
8.5 API ISimulationRuntimeManager

8.5.4.3 OnAutodiscoverData events

OnAutodiscoverData
Registers or unregisters an event handler method.
Table 8-114 OnAutodiscoverData - .NET (C#)
Syntax event Delegate_SRRSI_AD OnAutodiscoverData
Parameters None. See Delegate_SRRSI_AD (Page 290).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnAutodiscoverCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-115 RegisterOnAutodiscoverCallback() - Native C++
Syntax void RegisterOnAutodiscoverCallback(EventCallback_SRRSI_AD
in_CallbackFunction);
Parameters • EventCallback_SRRSI_AD in_CallbackFunction:
Pointer to a user-defined callback function.
See EventCallback_SRRSI_AD (Page 282).
Return values None

UnregisterOnAutodiscoverCallback()
Unregisters the callback function.
Table 8-116 UnregisterOnAutodiscoverCallback() - Native C++
Syntax void UnregisterOnAutodiscoverCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

S7-PLCSIM Advanced
148 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

8.6 API IInstances

8.6.1 Interfaces - Information and settings

Dispose()
Deletes the managed interface and unloads the native components of the user interfaces.
Table 8-117 Dispose() - .NET (C#)
Syntax void Dispose()
Parameters None
Return values None

GetID() / ID { get; }
Returns the instance ID. The ID is assigned by Runtime Manager when the instance is
registered.
Table 8-118 GetID() - Native C++
Syntax INT32 GetID();
Parameters None
Return values INT32: Instance ID

Table 8-119 ID { get; } - .NET (C#)

Syntax UInt32 ID { get; }
Parameters None
Return values Uint32: Instance ID
Exceptions None

GetName() / Name { get; }

Returns the name of the instance.
Table 8-120 GetName() - Native C++
Syntax ERuntimeErrorCode GetName(WCHAR inout_Name[], UINT32 in_ArrayLength);
Parameters • WCHAR inout_Name[]:
A user-allocated storage for the name of the instance. The field length should be at least as long as
DINSTANCE_NAME_MAX_LENGTH.
See Definitions and constants (Page 297).
• UINT32 in_ArrayLength:
Field length (Wide character)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 149
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_ARGUMENT The name does not fit in the storage.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);
IInstance* psa = NULL;
if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}

WCHAR name[DINSTANCE_NAME_MAX_LENGTH];
if (result == SREC_OK)
{
result = psa->GetName(name, DINSTANCE_NAME_MAX_LENGTH);
}

Table 8-121 Name { get; } - .NET (C#)

Syntax string Name { get; }
Parameters None
Return values Name of the instance.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.

GetCPUType()
Returns the CPU type of the virtual controller.
Table 8-122 GetCPUType() - Native C++
Syntax ECPUType GetCPUType();
Parameters None
Return values An enumeration element that defines the CPU type.
See ECPUType (Page 320).

SetCPUType()
Sets the CPU type of the virtual controller. A change of CPU type occurs only when the
controller is restarted.
Table 8-123 SetCPUType() - Native C++
Syntax void SetCPUType(ECPUType in_Value);
Parameters • ECPUType in_Value:
Defines which CPU type is simulated at the start of the instance.
When a different CPU type is loaded via STEP 7 or from the Virtual Memory Card, this CPU type
applies.
Return values None

S7-PLCSIM Advanced
150 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

CPUType { get; set; }

Returns or sets the CPU type of the virtual controller. A change of CPU type occurs only when
the controller is restarted.
When a different CPU type is loaded via STEP 7 or from the Virtual Memory Card, this CPU
type applies.
Table 8-124 CPUType { get; set; } - .NET (C#)
Syntax ECPUType CPUType { get; set; }
Parameters None
Return values An enumeration element that defines the CPU type.
Exceptions None

GetCommunicationInterface()
Returns the communication interface of the virtual controller: Local communication (Softbus)
or TCPIP. A change of communication interface occurs only when the controller is restarted.
All instances that are started must use the same communication interface.
PowerOn is prevented if a communication interface that is not used by the started instances
is selected.
Table 8-125 GetCommunicationInterface() - Native C++
Syntax ECommunicationInterface GetCommunicationInterface();
Parameters None
Return values • SRCI_NONE
Cannot be selected. Is returned if the instance interface is no longer valid.
• SRCI_SOFTBUS
Is returned if the virtual controller uses the Softbus.
• SRCI_TCPIP
Is returned if the virtual controller communicates over the virtual adapter.

SetCommunicationInterface()
Sets the communication interface of the virtual controller: Local communication (Softbus) or
TCPIP. A change of communication interface occurs only when the controller is restarted. All
instances that are started must use the same communication interface.
PowerOn is prevented if a communication interface that is not used by the started instances
is selected.
Table 8-126 SetCommunicationInterface() - Native C++
Syntax void SetCommunicationInterface(ECommunicationInterface in_Value);
Parameters • SRCI_NONE
Cannot be selected.
• SRCI_SOFTBUS
Is set to activate communication via Softbus.
• SRCI_TCPIP
Is set to activate communication over the virtual adapter.
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 151
User interfaces (API)
8.6 API IInstances

CommunicationInterface { get; set; }

Sets or returns the communication interface of the virtual controller: Local communication
(Softbus) or TCPIP. A change of communication interface occurs only when the controller is
restarted. All instances that are started must use the same communication interface.
PowerOn is prevented if a communication interface that is not used by the started instances
is selected.
Table 8-127 CommunicationInterface { get; set; } - .NET (C#)
Syntax ECommunicationInterface CommunicationInterface { get; set; }
Parameters None
Return values • ECommunicationInterface.None
Cannot be selected. Is returned if the instance interface is no longer valid.
• ECommunicationInterface.Softbus
Is returned if the virtual controller uses the Softbus.
• ECommunicationInterface.TCPIP
Is returned if the virtual controller communicates over the virtual adapter.
Exceptions None

GetInfo() / Info { get; }

Returns a structure that provides information about the instance.
Table 8-128 GetInfo() - Native C++
Syntax SInstanceInfo GetInfo();
Parameters None
Return values SInstanceInfo: A structure that provides information about the instance. See SInstanceInfo
(Page 305).

Table 8-129 Info { get; } - .NET (C#)

Syntax SInstanceInfo Info { get; }
Parameters None
Return values SInstanceInfo: A structure that provides information about the instance.
Exceptions None

UnregisterInstance()
Unregisters this instance from Runtime Manager.

NOTE
Loss of the interfaces
Other applications that are connected to this instance will lose their interface to this instance.

Table 8-130 UnregisterInstance() - Native C++

Syntax ERuntimeErrorCode UnregisterInstance();
Parameters None

S7-PLCSIM Advanced
152 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.

Table 8-131 UnregisterInstance() - .NET (C#)

Syntax void UnregisterInstance();
Parameters None
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.2 Controller - Information and settings

GetControllerName() / ControllerName { get; }

Returns the downloaded name of the virtual controller.
Table 8-132 GetControllerName() - Native C++
Syntax ERuntimeErrorCode GetControllerName(WCHAR inout_Name[], UINT32
in_ArrayLength);
Parameters • WCHAR inout_Name[]:
A user-allocated storage for the name.
• UINT32 in_ArrayLength:
The length of the storage.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INDEX_OUT_OF_RANGE The name does not fit in the storage.

Table 8-133 ControllerName { get; } - .NET (C#)

Syntax string ControllerName { get; }
Parameters None
Return values string:
The downloaded name of the virtual controller.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 153
User interfaces (API)
8.6 API IInstances

GetControllerShortDesignation() / ControllerShortDesignation { get; }

Returns the downloaded short designation of the virtual controller.
Table 8-134 GetControllerShortDesignation() - Native C++
Syntax ERuntimeErrorCode GetControllerShortDesignation(WCHAR
inout_ShortDesignation[], UINT32 in_ArrayLength);
Parameters • WCHAR inout_ShortDesignation[]:
A user-allocated storage for the short designation.
• UINT32 in_ArrayLength:
The length of the storage.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INDEX_OUT_OF_RANGE The name does not fit in the storage.

Table 8-135 ControllerShortDesignation { get; } - .NET (C#)

Syntax string ControllerShortDesignation { get; }
Parameters None
Return values string:
The downloaded short designation of the virtual controller.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

GetControllerIPCount()
Returns the number of configured IP addresses of the virtual controller. If the function fails,
the return value is 0.
Table 8-136 GetControllerIPCount() - Native C++
Syntax UINT32 GetControllerIPCount();
Parameters None
Return values INT32: Number of configured IP addresses of the virtual controller.

GetControllerIP() / ControllerIP { get; }

Returns a configured IP address of the instance.
Table 8-137 GetControllerIP() - Native C++
Syntax UIP GetControllerIP();
UIP GetControllerIP(UINT32 in_Index);
Parameters • WCHAR in_Index:
The index of the IP address you want to receive. The index must be less than the value you
receive from GetControllerIPCount(). The default setting is 0.

S7-PLCSIM Advanced
154 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values UIP: IP address of the virtual controller. If the function fails, the return value is 0.

Table 8-138 ControllerIP { get; } - .NET (C#)

Syntax string[] ControllerIP { get; }
Parameters None
Return values string: All downloaded IP addresses of the virtual controller. If the function fails, the field is
empty.
Exceptions None

GetControllerIPSuite4() / ControllerIPSuite4 { get; }

Returns the IP suite instance. If the "Softbus" communication interface is used, the subnet
mask and default gateway are 0.
Table 8-139 GetControllerIPSuite4() Native C++
Syntax SIPSuite4 GetControllerIPSuite4();
SIPSuite4 GetControllerIPSuite4(UINT32 in_Index);
Parameters • WCHAR in_Index:
The index of the IP address you want to receive. The index must be less than the value you receive
from GetControllerIPCount(). The default setting is 0.
Return values SIPSuite4: The IP suite of the virtual controller. If the function fails, the return values are 0.

Table 8-140 ControllerIPSuite4 { get; } - .NET (#)

Syntax SIPSuite4[] ControllerIPSuite4 { get; };
Parameters None
Return values SIPSuite4[]: All downloaded IP suites of the virtual controller. If the function fails, the field is
empty.
Exceptions None

SetIPSuite()
Sets the IP suite of the network interface of a virtual controller.
Table 8-141 SetIPSuite() - Native C++
Syntax ERuntimeErrorCode SetIPSuite(UINT32 in_InterfaceID, SIPSuite4 in_IPSuite,
bool in_IsRemanent);
Parameters • UINT32 in_InterfaceID:
The ID of the network interface.
• SIPSuite4 in_IPSuite:
The IP suite that is to be assigned to the network interface. The IP suite contains the IP address, the
subnet mask and the standard gateway.
If the communication interface is "Softbus", the subnet mask and standard gateway are ignored.
• bool in_IsRemanent:
If true, the IP suite is saved after restart of the virtual controller.
If the communication interface is "Softbus", this flag is ignored.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 155
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_DOES_NOT_EXIST There is no network interface with this ID.
SREC_INVALID_OPERATING_STATE The virtual controller has not yet completed the
boot process or is already in the shutdown phase.

Table 8-142 SetIPSuite() - .NET (C#)

Syntax void SetIPSuite(UInt32 in_InterfaceID, SIPSuite4 in_IPSuite, bool
in_IsRemanent);
Parameters • UInt32 in_InterfaceID:
The ID of the network interface.
• SIPSuite4 in_IPSuite:
If the communication interface is "Softbus", the subnet mask and standard gateway are ignored.
• bool in_IsRemanent:
If true, the IP suite is saved after restart of the virtual controller.
If the communication interface is "Softbus", this flag is ignored.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.DoesNotExist There is no network interface with this ID.
ERuntimeErrorCode. The virtual controller has not yet completed the
InvalidOperatingState boot process or is already in the shutdown phase.

GetStoragePath()
Returns the full path of the folder in which the instance stores its data.
Table 8-143 GetStoragePath() - Native C++
Syntax ERuntimeErrorCode GetStoragePath(WCHAR inout_StoragePath[], UINT32
in_ArrayLength);
Parameters • WCHAR inout_StoragePath[]:
A user-allocated storage for the storage path. The length of the array should be at least as long as
DSTORAGE_PATH_MAX_LENGTH. See Data types (Page 280).
• UINT32 in_ArrayLength:
Length of the array (Wide character)
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INDEX_OUT_OF_RANGE The path does not fit in the storage.

S7-PLCSIM Advanced
156 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

SetStoragePath()
Sets the full path of the folder in which the instance stores its data. This can also be a
network share.
Set the path before you start the instance. A change to the path takes effect only when the
controller is restarted.
If no path is set, the default setting:
<My Documents>\Siemens\Simatic\Simulation\Runtime\Persistence\<Instance Name> is used.
Table 8-144 SetStoragePath() - Native C++
Syntax ERuntimeErrorCode SetStoragePath(WCHAR* in_StoragePath);
Parameters • WCHAR* in_StoragePath:
Full name of the storage path. The length of the name must be less than
DSTORAGE_PATH_MAX_LENGTH. See Data types (Page 280).
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INDEX_OUT_OF_RANGE The length of the path exceeds the limit.
SREC_WRONG_ARGUMENT The path contains invalid characters.

StoragePath { get; set; }

Returns or sets the full path of the folder in which the instance stores its retentive data. This
can also be a network share.
Set the path before you start the instance. A change to the path takes effect only when the
controller is restarted.
If no path is set, the default setting:
<My Documents>\Siemens\Simatic\Simulation\Runtime\Persistence\<Instance Name> is used.
Table 8-145 StoragePath { get; set; } - .NET (C#)
Syntax string StoragePath { get; set; }
Parameters None
Return values string: The configured storage path.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.IndexOutOfRange The length of the path exceeds the limit.
ERuntimeErrorCode.WrongArgument The path contains invalid characters.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 157
User interfaces (API)
8.6 API IInstances

GetDefaultStoragePath()
Returns the full path of the default folder in which the instance stores its data.
Table 8-146 GetDefaultStoragePath() - Native C++
Syntax ERuntimeErrorCode ISimulationRuntimeManager::GetDefaultStoragePath(WCHAR*
out_DefaultStoragePath);
Parameters • WCHAR* out_DefaultStoragePath
Output parameter that is filled with the path of the default folder.
Return values Runtime error code Description
SREC_OK The function is successful.

SetDefaultStoragePath()
Sets the full path of the default folder in which the instance stores its data.
Table 8-147 SetDefaultStoragePath() - Native C++
Syntax ERuntimeErrorCode ISimulationRuntimeManager::SetDefaultStoragePath(const
WCHAR* in_DefaultStoragePath);
Parameters • const WCHAR* in_DefaultStoragePath
Input parameter that specifies the path of the default folder.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The path contains invalid characters.
SREC_CONFIG_FILE_ERROR The configuration file
UserInterfaceConfiguration.xml could not be read.

DefaultStoragePath { get; set; }

Returns or sets the full path of the default folder in which the instance stores its data.
Table 8-148 DefaultStoragePath { get; set; } - .NET (C#)
Syntax System::String^ SimulationRuntimeManager::DefaultStoragePath {
System::String^ get(); void set(System::String^); }
Return values Runtime error code Description
OK The function is successful.
WrongArgument The path contains invalid characters.
ConfigFileError The configuration file
UserInterfaceConfiguration.xml could not be read.

S7-PLCSIM Advanced
158 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

ArchiveStorage()
The user program, the hardware configuration and the retentive data is stored in a file. The
Virtual SIMATIC Memory Card. ArchiveStorage() stores this file as a ZIP file. The virtual
controller must be in OFF operating state for this.
Table 8-149 ArchiveStorage() - Native C++
Syntax ERuntimeErrorCode ArchiveStorage(WCHAR* in_FullFileName);
Parameters • WCHAR in_FullFileName:
The full path to the ZIP file. The path relates to directories of the computer where the API is being
called.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INVALID_OPERATING_STATE The instance is not in OFF operating state.
SREC_INVALID_ARCHIVE_PATH The archive path is invalid.
SREC_CREATE_DIRECTORIES_FAILED The folder for the ZIP file could not be created.
SREC_ARCHIVE_STORAGE_FAILED The ZIP file could not be created.
SREC_STORAGE_TRANSFER_ERROR Error during network data transfer. Memory data
between client and server computers do not match.
SREC_NO_STORAGE_PATH_SET No storage path is set. The user has to execute the
SetStoragePath() function beforehand.

Table 8-150 ArchiveStorage() - .NET (C#)

Syntax void ArchiveStorage(string in_FullFileName);
Parameters • string in_FullFileName:
The full path to the ZIP file. The path relates to folders of the computer where the API is being
called.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode. The instance is not in OFF operating state.
InvalidOperatingState
ERuntimeErrorCode.InvalidArchivePath The archive path is invalid.
ERuntimeErrorCode. The folder for the ZIP file could not be created.
CreateDirectoriesFailed
ERuntimeErrorCode. The ZIP file could not be created.
ArchiveStorageNotCreated
ERuntimeErrorCode. Error during network data transfer. Memory data
StorageTransferError between client and server computers do not match.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 159
User interfaces (API)
8.6 API IInstances

RetrieveStorage()
RetrieveStorage() creates a Virtual SIMATIC Memory Card from the archived ZIP file. The
virtual controller must be in OFF operating state for this.
Table 8-151 RetrieveStorage() - Native C++
Syntax ERuntimeErrorCode RetrieveStorage(WCHAR* in_FullFileName);
Parameters • WCHAR* in_FullFileName:
The full path to the ZIP file. The path relates to folders of the computer where the API is being
called.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INVALID_OPERATING_STATE The instance is not in OFF operating state.
SREC_INVALID_ARCHIVE_PATH The archive path is invalid.
SREC_DELETE_EXISTING_STORAGE_FAILED The old storage cannot be deleted.
SREC_RETRIEVE_STORAGE_FAILURE The ZIP file cannot be unzipped.
SREC_STORAGE_TRANSFER_ERROR Error during network data transfer. Memory data
between client and server computers do not match.
SREC_NO_STORAGE_PATH_SET No storage path is set. The user has to execute the
SetStoragePath() function beforehand.

Table 8-152 RetrieveStorage() - .NET (C#)

Syntax void RetrieveStorage(string in_FullFileName);
Parameters • string in_FullFileName:
The full path to the ZIP file. The path relates to folders of the computer where the API is being
called.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode. The instance is not in OFF operating state.
InvalidOperatingState
ERuntimeErrorCode.InvalidArchivePath The archive path is invalid.
ERuntimeErrorCode. The old storage cannot be deleted.
DeleteExistingStorageFailed
ERuntimeErrorCode. The ZIP file cannot be unzipped.
RetrieveStorageFailure
ERuntimeErrorCode. Error during network data transfer. Memory data
StorageTransferError between client and server computers do not match.

CleanupStoragePath()
The function deletes the folder with the Virtual SIMATIC Memory Card of a local instance or a
remote instance. To do this, the function checks whether required and invalid files are
available. Even if the folder is missing, the function is considered successful.

S7-PLCSIM Advanced
160 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

To make sure that the correct folder is deleted, the function checks whether there are any
files that need to be present in the Virtual SIMATIC Memory Card:
• ".\sim_hwdb.ini"
• ".\SIMATIC_MC\SIMATIC.S7S\"
• ".\SIMATIC_MC\RData\"
To permanently delete the folder, only the following folders with files are also allowed:
• ".\CrashDump\"
• ".\Traces\"
• ".\retain.pms"
The instance must be in OFF operating state ("PowerOff").
Table 8-153 CleanupStoragePath() - Native C++
Syntax ERuntimeErrorCode CleanupStoragePath();
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INVALID_OPERATING_STATE The instance is not in OFF operating state.
SREC_DELETE_EXISTING_STORAGE_FAILED The folder with the memory cannot be deleted.
SREC_INVALID_STORAGE The memory is invalid. It contains files or folders
that are not permitted.

Table 8-154 CleanupStoragePath() - .NET (C#)

Syntax void CleanupStoragePath();
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode. The instance is not in OFF operating state.
InvalidOperatingState
ERuntimeErrorCode. The folder with the memory cannot be deleted.
DeleteExistingStorageFailed
SREC_INVALID_STORAGE The memory is invalid. It contains files or folders
that are not permitted.

GetStrictMotionTiming() / StrictMotionTiming { get; }

Returns the current instance setting for the "Strict Motion Timing" feature. The "Strict Motion
Timing" feature is located on the S7-PLCSIM Advanced Control Panel (Page 59).
Table 8-155 GetStrictMotionTiming() - Native C++
Syntax ERuntimeErrorCode GetStrictMotionTiming(bool* enabled);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 161
User interfaces (API)
8.6 API IInstances

Parameters bool* enabled:

Receives the current setting.
true: Active
false: Inactive
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.

Table 8-156 StrictMotionTiming { get; } - .NET (C#)

Syntax bool StrictMotionTiming { get; }
Parameters None
Return values Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode. The instance is in Power On. The instance must not
InvalidOperatingState be in Power On to change the setting.

SetStrictMotionTiming() / StrictMotionTiming { set; }

Sets the instance setting for the "Strict Motion Timing" feature. The "Strict Motion Timing"
feature is located on the S7-PLCSIM Advanced Control Panel (Page 59).
Table 8-157 SetStrictMotionTiming() - Native C++
Syntax ERuntimeErrorCode GetStrictMotionTiming(bool* enabled);
Parameters bool enabled:
The value to be set.
true: Active
false: Inactive
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_INVALID_OPERATING_STATE The instance is in Power On. The instance must not
be in Power On to change the setting.

Table 8-158 StrictMotionTiming { set; } - .NET (C#)

Syntax bool StrictMotionTiming { set; }
Parameters None
Return values Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode. The instance is in Power On. The instance must not
InvalidOperatingState be in Power On to change the setting.

S7-PLCSIM Advanced
162 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

8.6.3 Operating state

PowerOn()
The function creates the process for the Simulation Runtime instance and starts the firmware
of the virtual controller.
The PowerOn() state is reached without a timeout value:
1. As soon as an instance was created
2. Before the user program has been started on the CPU
Table 8-159 PowerOn() - Native C++
Syntax ERuntimeErrorCode PowerOn();
ERuntimeErrorCode PowerOn(UINT32 in_Timeout_ms);
Parameters • UInt32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns as soon as an instance is created and before the
user program has been started on the CPU. Subscribe to the OnOperatingStateChanged()
event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 8500 ms is recommended), the func­
tion returns when the operation has been completed or after a timeout.
– Expected operating states when this function is successful:
{ SROS_STOP or SROS_RUN, SROS_FREEZE, SROS_HOLD }
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The expected operating state does not occur on
time.
SREC_ERROR_LOADING_DLL The "Siemens.Simatic.Simula­
tion.Runtime.Instance.exe" cannot load the
"Siemens.Simatic.PlcSim.Vplc1500.dll".
SREC_STORAGE_PATH_ALREADY_IN_USE The selected path for this instance is already being
used by another instance.
SREC_NO_STORAGE_PATH_SET No storage path is set. The user has to execute the
SetStoragePath() function beforehand.
SREC_WARNING_ALREADY_EXISTS Warning: The instance is started.
SREC_VIRTUAL_SWITCH_MISCONFIGURED • The S7-PLCSIM Advanced Virtual Switch is con­
figured incorrectly.
• The binding of an S7-PLCSIM Advanced Virtual
Switch on a PC network interface is not correct,
or the driver of an S7-PLCSIM Advanced Virtual
Switch is not functioning properly.
If the binding is not correct, call the
SetNetInterfaceBindings() function or
set the binding manually before starting the
instance.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is no longer
running.
SREC_UNSUPPORTED_PCAP_DRIVER The PCAP driver used is not supported. PLCSIM
Advanced supports Npcap as of V0.9995.
TCP/IP communication is not possible.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 163
User interfaces (API)
8.6 API IInstances

Return values SREC_WARNING_TRIAL_MODE_ACTIVE Warning: No license available. You can use the
instance without restrictions with the Trial License.
Afterwards, the instance is shut down.
SREC_WARNING_RUNNING_ON_TIA_PORTAL_- Warning: No valid license is available, but a
TEST_SUITE "TIA Portal Test Suite" license.
PLCSIM Advanced starts with this license. A down­
load from the TIA Portal is possible, but the instance
terminates without feedback if the download was
not made from the TIA Portal Test Suite.
SREC_NOT_EMPTY Warning: No valid license for PLCSIM Advanced is
available, but a "TIA Portal Test Suite" license.
If this is the case, power-up from the Virtual SIMAT­
IC Memory Card is not supported.
SREC_COMMUNICATION_INTERFACE_NOT_AV- For local communication via Softbus
AILABLE PLCSIM Advanced cannot connect to the Softbus.
Solution
• Try again to establish the connection.
• Close PLCSIM Advanced and the TIA Portal and
restart the applications.
• Reboot the PC.
• Repair the PLCSIM Advanced installation.
For TCP/IP communication
Another application is connected to the Softbus on
your PC.
Solution
• Close all SIMATIC applications, e.g. TIA Portal,
WinCC, PLCSIM.
• Reboot the PC.
• Repair the PLCSIM Advanced installation.
SREC_ACCESS_DENIED No write access in the Storage Directory.
SREC_PCAP_DRIVER_NOT_RUNNING The Nmap Packet Capture Driver (Npcap) is not act­
ive on the system.
Remedy
1. Start the command line in administrator mode.
2. Execute the command "net start npcap".
SREC_WRONG_COMMUNICATION_INTERFACE • You have tried to supply the second instance
with the communication interface that is differ­
ent from the first instance that is already
switched on.
– Example:
1. PowerOn() of the first instance with Soft­
bus is successful.
2. PowerOn() of the second instance with
TCP/IP; the error code is returned.
• The PC interface does not exist or is not compat­
ible (disabled, not connected, or a PLCSIM Virtu­
al Ethernet Adapter).
SREC_WARNING_PASSWORD_PROTECTION_ER- The password protection prevented the memory
ROR from being opened. View the restrictions with activ­
ated password protection.

S7-PLCSIM Advanced
164 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values SREC_INVALID_CONFIGURATION The configuration is invalid because, for example,

the current instance has a mapped PC network
interface that is already being used by another run­
ning instance.
SREC_WARNING_NO_EXTERNAL_COMMUNICAT- You have set the Multi-Adapter Network Mode
ION (non-promiscuous mode) without interface map­
ping or Softbus as communication interface.
SREC_INTERNAL_ERROR The system call has caused an internal error.

Table 8-160 PowerOn() - .NET (C#)

Syntax ERuntimeErrorCode PowerOn();
ERuntimeErrorCode PowerOn(UInt32 in_Timeout_ms);
Parameters • UInt32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns as soon as an instance is created and before the
user program has been started on the CPU. Subscribe to the OnOperatingStateChanged()
event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 8500 ms is recommended), the func­
tion returns when the operation has been completed or after a timeout.
– Expected operating states when this function is successful:
{ EOperatingState.Run
or EOperatingState.Stop, EOperatingState.Freeze, EOperatingState.Hold }
Return values Runtime error code Description
ERuntimeErrorCode.OK The function is successful.
ERuntimeErrorCode. Warning: The instance is started.
WarningAlreadyExists
ERuntimeErrorCode. The PCAP driver used is not supported. PLCSIM
UnsupportedPcapDriver Advanced supports Npcap as of V0.9995.
TCP/IP communication is not possible.
ERuntimeErrorCode. Warning: No license available. You can use the
WarningTrialModeActive instance without restrictions with the Trial License.
Afterwards, the instance is shut down.
ERuntimeErrorCode. Warning: No valid license is available, but a
WarningRunningOnTiaPortalTestSuite "TIA Portal Test Suite" license.
PLCSIM Advanced starts with this license. A down­
load from the TIA Portal is possible, but the instance
terminates without feedback if the download was
not made from the TIA Portal Test Suite.
ERuntimeErrorCode.NotEmpty Warning: No valid license for PLCSIM Advanced is
available, but a "TIA Portal Test Suite" license.
If this is the case, power-up from the Virtual SIMAT­
IC Memory Card is not supported.
ERuntimeErrorCode. For local communication via Softbus
CommunicationInterfaceNotAvailable PLCSIM Advanced cannot connect to the Softbus.
Solution
• Try again to establish the connection.
• Close PLCSIM Advanced and the TIA Portal and
restart the applications.
• Reboot the PC.
• Repair the PLCSIM Advanced installation.
For TCP/IP communication

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 165
User interfaces (API)
8.6 API IInstances

Return values Another application is connected to the Softbus on

your PC.
Solution
• Close all SIMATIC applications, e.g. TIA Portal,
WinCC, PLCSIM.
• Reboot the PC.
• Repair the PLCSIM Advanced installation.
ERuntimeErrorCode.AccessDenied No write access in the Storage Directory.
ERuntimeErrorCode.PCAPDriverNotRunning The Nmap Packet Capture Driver (Npcap) is not act­
ive on the system.
Remedy
1. Start the command line in administrator mode.
2. Execute the command "net start npcap".
ERuntimeErrorCode. • You have tried to supply the second instance
WrongCommunicationInterface with the communication interface that is differ­
ent from the first instance that is already
switched on.
– Example:
1. PowerOn() of the first instance with Soft­
bus is successful.
2. PowerOn() of the second instance with
TCP/IP; the error code is returned.
• The PC interface does not exist or is not compat­
ible (disabled, not connected, or a PLCSIM Virtu­
al Ethernet Adapter).
ERuntimeErrorCode.WarningPasswordFor- The password protection prevented the memory
ProtectionError from being opened. View the restrictions with activ­
ated password protection.
ERuntimeErrorCode. You have set the Multi-Adapter Network Mode
WarningNoExternalCommunication (non-promiscuous mode) without interface map­
ping or Softbus as communication interface.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The expected operating state does not occur on
time.
ERuntimeErrorCode.ErrorLoadingDll The "Siemens.Simatic.Simulation.
Runtime.Instance.exe" cannot load the
"Siemens.Simatic.PlcSim.Vplc1500.dll".
ERuntimeErrorCode. The selected path for this instance is already being
StoragePathAlreadyInUse used by another instance.
ERuntimeErrorCode.NoStoragePathSet The path could not be created. The length of the
DSTORAGE_PATH_MAX_LENGTH characters might
be exceeded.
ERuntimeErrorCode. • The S7-PLCSIM Advanced Virtual Switch is con­
VirtualSwitchMisconfigured figured incorrectly.

S7-PLCSIM Advanced
166 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions • The binding of an S7-PLCSIM Advanced Virtual

Switch on a PC network interface is not correct,
or the driver of an S7-PLCSIM Advanced Virtual
Switch is not functioning properly.
If the binding is not correct, call the
SetNetInterfaceBindings() function or
set the binding manually before starting the
instance.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is no longer
running.
ERuntimeErrorCode. The configuration is invalid because, for example,
InvalidConfiguration the current instance has a mapped PC network
interface that is already being used by another run­
ning instance.
ERuntimeErrorCode.InternalError The system call has caused an internal error.

PowerOff()
Shuts down the Simulation Runtime and closes its process.
Table 8-161 PowerOff() - Native C++
Syntax ERuntimeErrorCode PowerOff();
ERuntimeErrorCode PowerOff(UINT32 in_Timeout_ms);
Parameters • UINT32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 800 ms is recommended), the function
returns when the operation has been completed or after a timeout.
Expected operating state when this function is successful:
{ SROS_OFF }
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The expected operating state does not occur on
time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.

Table 8-162 PowerOff() - .NET (C#)

Syntax void PowerOff();
void PowerOff(UInt32 in_Timeout_ms);
Parameters • UInt32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 800 ms is recommended), the function
returns when the operation has been completed or after a timeout.
Expected operating state when this function is successful:
{ EOperatingState.Stop }
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 167
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The expected operating state does not occur on
time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.

Executing PowerOff()
After its start, the API function PowerOff() returns the error code "-39
InvalidOperatingState".
Remedy
Before you execute the API function PowerOff(), you must cancel the subscriptions to all
events; otherwise, you will receive unexpected exceptions.

Run()
Calls on the virtual controller to change to RUN operating state.
Table 8-163 Run() - Native C++
Syntax ERuntimeErrorCode Run();
ERuntimeErrorCode Run(UINT32 in_Timeout_ms);
Parameters • UINT32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 20 ms is recommended), the function
returns when the operation has been completed or after a timeout.
Expected operating states if this function is successful:
{ SROS_STOP , SROS_RUN }
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The expected operating state does not occur on
time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_IS_EMPTY One of the following two conditions applies here:
Condition: After creating and starting an instance,
you have tried to switch the virtual controller to the
RUN operating state without downloading a STEP 7
project.
Condition: After creating and enabling an instance
with download of a STEP 7 project with enabled
password for the protection of confidential config­
uration data, you have moved the virtual memory
card from one system to another. You have tried to
start the instance on the new system. The following
error code is returned after the start:
"SREC_WARNING_PASSWORD_PROTECTION_ERROR"
Afterwards, you have tried to switch the virtual con­
troller to the RUN operating state.

S7-PLCSIM Advanced
168 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Table 8-164 Run() - .NET (C#)

Syntax void Run();
void Run(Uint32 in_Timeout_ms);
Parameters • UInt32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 20 ms is recommended), the function
returns when the operation has been completed or after a timeout.
Expected operating states when this function is successful:
{ EOperatingState.Run }
Return values Runtime error code Description
SREC_IS_EMPTY One of the following two conditions applies here:
Condition: After creating and starting an instance,
you have tried to switch the virtual controller to
the RUN operating state without downloading a
STEP 7 project.
Condition: After creating and enabling an instance
with download of a STEP 7 project with enabled
password for the protection of confidential config­
uration data, you have moved the virtual memory
card from one system to another. You have tried
to start the instance on the new system. The fol­
lowing error code is returned after the start:
"SREC_WARNING_PASSWORD_PROTECTION_ERRO­
R"
Afterwards, you have tried to switch the virtual
controller to the RUN operating state.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The expected operating state does not occur on
time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.

RUN operating state after enabling an instance

When you expect the RUN operating state after enabling an instance, check whether the
instance is already in RUN by subscribing to the event OnOperatingStateChanged(). As
an alternative, call Run() immediately after enabling the API function to switch the instance
to the RUN operating state.

Stop()
Calls on the virtual controller to change to STOP operating state.
Table 8-165 Stop() - Native C++
Syntax ERuntimeErrorCode Stop();
ERuntimeErrorCode Stop(UINT32 in_Timeout_ms);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 169
User interfaces (API)
8.6 API IInstances

Parameters • UINT32 in_Timeout_ms:

A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 200 ms is recommended), the function
returns when the operation has been completed or after a timeout.
Expected operating state when this function is successful:
{ SROS_STOP }
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The expected operating state does not occur on
time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.

Table 8-166 Stop() - .NET (C#)

Syntax void Stop();
void Stop(UInt32 in_Timeout_ms:);
Parameters • UInt32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a timeout value of at least 200 ms is recommended), the function
returns when the operation has been completed or after a timeout.
Expected operating state if this function is successful:
{ EOperatingState.Stop }
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The expected operating state does not occur on
time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.

GetOperatingState() / OperatingState { get; }

Returns the operating state of the virtual controller. When the operating state changes, the
OnOperatingStateChanged() (Page 247) event is triggered. For details about the operating
state, see Data types (Page 319).
Table 8-167 GetOperatingState() - Native C++
Syntax EOperatingState GetOperatingState();
Parameters None

S7-PLCSIM Advanced
170 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values • SROS_INVALID_OPERATING_STATE:

If the function fails.
• SROS_OFF:
If the Simulation Runtime instance is not running.
• SROS_BOOTING:
If PowerOn() was called while in this state and the virtual controller is not yet ready to start the
user program.
• SROS_STOP:
If the virtual controller is in STOP state.
• SROS_STARTUP:
If the user program is currently changing from STOP to RUN.
• SROS_RUN:
If the user program is running.
• SROS_FREEZE:
If the user program is being stopped (Freeze status).
• SROS_HOLD:
If the user program is set to HOLD when the breakpoint is reached.
• SROS_SHUTTING_DOWN:
If PowerOff() was called but the virtual controller is still in the Shutdown phase.

Table 8-168 OperatingState { get; } - .NET (C#)

Syntax EOperatingState OperatingState { get; }
Parameters None
Return values • EOperatingState.InvalidOperatingState:
If the function fails.
• EOperatingState.Off:
If the Simulation Runtime instance is not running.
• EOperatingState.Booting:
If PowerOn() was called while in this state and the virtual controller is not yet ready to start the
user program.
• EOperatingState.Stop:
If the virtual controller is in STOP state.
• EOperatingState.Startup:
If the user program is currently changing from STOP to RUN.
• EOperatingState.Run:
If the user program is running.
• EOperatingState.Freeze:
If the user program is being stopped (Freeze status).
• EOperatingState.Hold:
If the user program is set to HOLD when the breakpoint is reached.
• EOperatingState.ShuttingDown:
If PowerOff() was called but the virtual controller is still in the Shutdown phase.

MemoryReset()
Shuts down the virtual controller, closes its processes and performs a restart.
Closing the processes automatically performs an general reset.
Table 8-169 MemoryReset() - Native C++
Syntax ERuntimeErrorCode MemoryReset();
ERuntimeErrorCode MemoryReset(UINT32 in_Timeout_ms);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 171
User interfaces (API)
8.6 API IInstances

Parameters • UINT32 in_Timeout_ms:

A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a value of 60000 is recommended), the function returns when
the operation has been completed or after a timeout.
Expected operating states if this function is successful:
{ SROS_STOP , SROS_RUN }
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The expected operating state does not occur on
time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.

Table 8-170 MemoryReset() - .NET (C#)

Syntax void MemoryReset();
void MemoryReset(UInt32 in_Timeout_ms);
Parameters • UInt32 in_Timeout_ms:
A timeout value in milliseconds.
– If no timeout value is set, the function returns immediately. Subscribe to the
OnOperatingStateChanged() event to find out when the operation has been completed.
– If the value is greater than 0 (a value of 60000 is recommended), the function returns when
the operation has been completed or after a timeout.
Expected operating states when this function is successful:
{ EOperatingState.Run, EOperatingState.Stop }
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The expected operating state does not occur on
time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.

8.6.4 Tag list

NOTE

Elements with data types not known to the API (EDataType.Unknown) are not included in
the tag list.

UpdateTagList()
The function reads the tags from the virtual controller and writes them to the shared storage
arranged by name.

S7-PLCSIM Advanced
172 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

If the tag is an array or a structure, there are multiple entries.

In the case of a structure, there is an entry for the structure itself and an additional entry for
each structure element.
Entry_1: "StructName"
Entry_2: "StructName.ElementName_1"
..
Entry_N: "StructName.ElementName_n"

In the case of an array, in this example a two-dimensional array, there is an entry for the array
itself and an additional entry for each array element.
Entry_1: "ArrayName"
Entry_2: "ArrayName[a,b]", {a} and {b} correspond to the first index of the respective
dimension)
..
Entry_N: "ArrayName[x,y]", {x} and {y} correspond to the last index of the respective
dimension)

Memory for up to 500000 entries (not PLC tags) is reserved for the list. If the list becomes too
large, the function returns the error/exception "NOT_ENOUGH_MEMORY".
If there are problems with the maximum number of entries and not all tags are needed, two
filters can be used when refreshing the tag table.
Table 8-171 UpdateTagList() - Native C++
Syntax ERuntimeErrorCode UpdateTagList();
ERuntimeErrorCode UpdateTagList(ETagListDetails in_TagListDetails);
ERuntimeErrorCode UpdateTagList(ETagListDetails in_TagListDetails, bool
in_IsHMIVisibleOnly);
ERuntimeErrorCode UpdateTagList(ETagListDetails in_TagListDetails, bool
in_IsHMIVisibleOnly, WCHAR* in_DataBlockFilterList);
Parameters • ETagListDetails in_TagListDetails:
Every combination of the following four areas:
IO: Inputs and Outputs
M: Bit memory
CT: Counters and Timers
DB: Data Blocks
The default setting is IOMCTDB.
Example: IOM reads only the tags from the area Inputs / Outputs and Bit memory.
• bool in_IsHMIVisibleOnly:
If true, only tags marked with "HMI Visible" are read. The default setting is true.
• WCHAR* in_DataBlockFilterList:
A string that includes the name of all data blocks that are supposed to be available in the tag table.
The string must be in quotation marks.
Example: ""\"DB_1\", \"DB_2\" \"DB_3\"|\"DB_4\"\"DB_5\""
All characters within the quotation marks are interpreted as a DB name. If the data block does not
exist in the PLC program, it is not added to the tag table memory. No error is triggered in the pro­
cess.
For this list to be taken into consideration, in_DataBlockFilterList has to be unequal to
NULL and in_TagListDetails has to contain "DB".

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 173
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_NOT_ENOUGH_MEMORY More than 500000 entries are requested.
SREC_WARNING_ALREADY_EXISTS The tag table is current.
SREC_WRONG_ARGUMENT The syntax of in_DataBlockFilterList is inval­
id. The list has to be 3 characters long; the first and
last character have to be a quotation mark.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IInstance* psa = NULL;

if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}

if (result == SREC_OK)
{
// Example: How to filter data blocks
// DB Name: TEST_DB, DB Number: 2
result = psa->UpdateTagList(SRTLD_MDB, false, L"\"TEST_DB\"");
}

Table 8-172 UpdateTagList() - .NET (C#)

Syntax void UpdateTagList();
void UpdateTagList(
ETagListDetails in_TagListDetails
);
void UpdateTagList(
ETagListDetails in_TagListDetails,
bool in_IsHMIVisibleOnly
);
ERuntimeErrorCode UpdateTagList(
ETagListDetails in_TagListDetails,
bool in_IsHMIVisibleOnly,
string in_DataBlockFilterList
);
Parameters • ETagListDetails in_TagListDetails:
Every combination of the following four areas:
IO: Inputs and Outputs
M: Bit memory
CT: Counters and Timers
DB: Data Blocks
The default setting is IOMCTDB.
Example: IOM reads only the tags from the area Inputs / Outputs and Bit memory.
• bool in_IsHMIVisibleOnly:
If true, only tags marked with "HMI Visible" are read. The default setting is true.
• string in_DataBlockFilterList:
A string that includes the name of all data blocks that are supposed to be available in the tag table.
The string must be in quotation marks.
Example: ""\"DB_1\", \"DB_2\" \"DB_3\"|\"DB_4\"\"DB_5\""

S7-PLCSIM Advanced
174 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

All characters within the quotation marks are interpreted as a DB name. If the data block does not
exist in the PLC program, it is not added to the tag table memory. No error is triggered in the pro­
cess.
For this list to be taken into consideration, in_DataBlockFilterList has to be unequal to
NULL and in_TagListDetails has to contain "DB".
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.NotEnoughMemory More than 500000 entries are requested.
ERuntimeErrorCode.WrongArgument The syntax of in_DataBlockFilterList is inval­
id. The list has to be 3 characters long; the first and
last character have to be a quotation mark.

GetTagListStatus()
Returns the current update status of the tag list storage.
"inout_TagListDetails" is NONE, if the list needs to be updated.
Table 8-173 GetTagListStatus() - Native C++
Syntax ERuntimeErrorCode GetTagListStatus(ETagListDetails* out_TagListDetails,
bool* out_IsHMIVisibleOnly);
Parameters • ETagListDetails out_TagListDetails:
Status of the tag list details. SRTLD_NONE when an update of the list is required.
• bool out_IsHMIVisibleOnly:
If true, only tags marked with "HMI Visible" are available in the list.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.

Table 8-174 GetTagListStatus() - .NET (C#)

Syntax void GetTagListStatus(out ETagListDetails out_TagListDetails, out bool
out_IsHMIVisibleOnly);
Parameters • out ETagListDetails out_TagListDetails:
Status of the tag list details. ETagListDetails.None when an update of the list is required.
• out bool out_IsHMIVisibleOnly:
If true, only tags marked with "HMI Visible" are available in the list.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 175
User interfaces (API)
8.6 API IInstances

GetTagInfoCount()
Returns the number of entries in the tag list storage. If the function fails, the return value is 0.
Table 8-175 GetTagInfoCount() - Native C++
Syntax UINT32 GetTagInfoCount();
Parameters None
Return values Number of entries in the tag list storage.

GetTagInfos() / TagInfos { get; }

Returns a list of all tags.
Table 8-176 GetTagInfos() - Native C++
Syntax ERuntimeErrorCode GetTagInfos(UINT32 in_BufferLength, STagInfo*
inout_TagInfos, UINT32* out_TagCount);
Parameters • UINT32 in_BufferLength:
The number of elements that the storage can accommodate.
• STagInfo* inout_TagInfos:
The user-allocated storage that accommodates the tags.
• UINT32* out_TagCount:
Returns the number of tags that were written to the storage.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The elements do not fit in the storage.

Table 8-177 TagInfos { get; } - .NET (C#)

Syntax STagInfo[] TagInfos { get; }
Parameters None
Return values An array that contains all available entries of the storage.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.

CreateConfigurationFile()
Writes all entries from the tag list to an XML file.
Table 8-178 CreateConfigurationFile() - Native C++
Syntax ERuntimeErrorCode CreateConfigurationFile(WCHAR* in_FullFileName);

S7-PLCSIM Advanced
176 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Parameters • WCHAR* in_FullFileName:

Full file name of the XML file:
<Path> + <File name> + <File extension>.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The file name is invalid.

Table 8-179 CreateConfigurationFile() - .NET (C#)

Syntax void CreateConfigurationFile(string in_FullFileName);
Parameters None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The file name is invalid.

8.6.5 I/O access

8.6.5.1 Synchronizing inputs and outputs

Description
In PLCSIM Advanced the complete scope of the input and output area is used (see
GetAreaSize/AreaSize (Page 177)). This is also possible when no I/O module is configured.
Inputs and outputs which are defined via configured I/O modules are synchronized to the
defined update of the process image partition (PIP).
Inputs and outputs which are not assigned to an I/O module are synchronized in the cycle
control point.
Note the following when synchronizing these inputs and outputs:
• Inputs can only be used as inputs.
You can write values via the API. However, values that are written via the STEP 7 user
program are not visible in the API.
• Outputs can be used as output and as input.
You can write values via the API and via the CPU / STEP 7 user program. If API and user
program write to the same area, the values from the API will overwrite the values from the
user program.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 177
User interfaces (API)
8.6 API IInstances

8.6.5.2 I/O access via address - Reading

InputArea { get; }, MarkerArea { get; }, OutputArea { get; }

Returns an interface that you use to call the .NET functions in this section.
Table 8-180 InputArea { get; } MarkerArea { get; } OutputArea { get; } - .NET (C#)
Syntax IIOArea InputArea { get; }
IIOArea MarkerArea { get; }
IIOArea OutputArea { get; }
Parameters None
Return values IIOArea: The interface is used to call the "I/O access via address" functions.

GetAreaSize() / AreaSize { get; }

Returns the size of the area in bytes.
Table 8-181 GetAreaSize() - Native C++
Syntax UINT32 GetAreaSize(EArea in_Area);
Parameters • EArea in_Area:
The area whose size you want to receive. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 318).
Return values UINT32: Size of the area in bytes. If the function was successful, the value is not equal to 0.

Table 8-182 AreaSize { get; } - .NET (C#)

Syntax UInt32 InputArea.AreaSize { get; }
UInt32 MarkerArea.AreaSize { get; }
UInt32 OutputArea.AreaSize { get; }
Parameters None
Return values Uint32: Size of the area in bytes. If the function was successful, the value is not equal to 0.

ReadBit()
Reads an individual bit from the area.

NOTE
The function allows access to the entire storage area of the virtual controller.
Therefore, use access via the tag name (Page 187) and not via the address areas.

Table 8-183 ReadBit() - Native C++

Syntax ERuntimeErrorCode ReadBit(EArea in_Area, UINT32 in_Offset, UINT8 in_Bit,
bool* out_Value);

S7-PLCSIM Advanced
178 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Parameters • EArea in_Area:

The area to be read from. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 318).
• UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that GetAreaSize()
returns.
• UINT8 in_Bit:
The bit offset within the byte. The value must be between 0 and 7.
• bool* out_Value:
Returns the bit value.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE Offset or bits are invalid.
SREC_WRONG_ARGUMENT The area is invalid.

Table 8-184 ReadBit() - .NET (C#)

Syntax bool InputArea.ReadBit(UInt32 in_Offset, Byte in_Bit);
bool MarkerArea.ReadBit(UInt32 in_Offset, Byte in_Bit);
bool OutputArea.ReadBit(UInt32 in_Offset, Byte in_Bit);
Parameters • UInt32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that AreaSize
returns.
• Byte in_Bit:
The bit offset within the byte. The value must be between 0 and 7.
Return values bool: Bit value
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange Offset or bits are invalid.

ReadByte()
Reads an individual bit from the area.

NOTE
The function allows access to the entire storage area of the virtual controller.
Therefore, use access via the tag name and not via the address areas.

Table 8-185 ReadByte() - Native C++

Syntax ERuntimeErrorCode ReadByte(EArea in_Area, UINT32 in_Offset, BYTE*
out_Value);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 179
User interfaces (API)
8.6 API IInstances

Parameters • EArea in_Area:

The area from which you want to read. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 318).
• UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that GetAreaSize()
returns.
• BYTE* out_Value:
Returns the byte value.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE Offset is invalid.
SREC_WRONG_ARGUMENT The area is invalid.

Table 8-186 ReadByte() - .NET (C#)

Syntax Byte InputArea.ReadByte(UInt32 in_Offset);
Byte MarkerArea.ReadByte(UInt32 in_Offset);
Byte OutputArea.ReadByte(UInt32 in_Offset);
Parameters • UInt32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that AreaSize
returns.
Return values Byte: Byte value.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange Offset is invalid.

ReadBytes()
Reads a byte array from the area.

NOTE
The function allows access to the entire storage area of the virtual controller.
Therefore, use access via the tag name and not via the address areas.

Table 8-187 ReadByte() - Native C++

Syntax ERuntimeErrorCode ReadBytes(EArea in_Area, UINT32 in_Offset, UINT32
in_BytesToRead, UINT32* out_BytesRead, BYTE inout_Values[]);

S7-PLCSIM Advanced
180 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Parameters • EArea in_Area:

The area from which you want to read. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 318).
• UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that GetAreaSize()
returns.
• UINT32 in_BytesToRead:
Contains the size of the value storage.
• UINT32* out_BytesRead:
Returns the number of bytes that were just written to the value storage.
• BYTE inout_Values[]:
The storage for the bytes that are read from the area.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No byte could
be read.
SREC_WRONG_ARGUMENT The area is invalid.

Table 8-188 ReadBytes() - .NET (C#)

Syntax Byte[] InputArea.ReadBytes(UInt32 in_Offset, UInt32 in_BytesToRead);
Byte[] MarkerArea.ReadBytes(UInt32 in_Offset,UInt32 in_BytesToRead);
Byte[] OutputArea.ReadBytes(UInt32 in_Offset,UInt32 in_BytesToRead);
Parameters • UInt32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that AreaSize
returns.
• UInt32 in_BytesToRead:
The number of bytes to be read.
Return values Byte[]: The read bytes.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No byte could
be read.

ReadSignals()
Structures and fields can be emulated through signal lists and be read by using the
ReadSignals() function.
The function also takes into consideration the byte order (Endianness).

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 181
User interfaces (API)
8.6 API IInstances

Only primitive data type signals are supported, but the function is not type-safe.

NOTE
The function allows access to the entire storage area of the virtual controller.
Therefore, use access via the tag name (Page 187) and not via the address areas.

Table 8-189 ReadSignals() - Native C++

Syntax ERuntimeErrorCode ReadSignals(EArea in_Area, SDataValueByAddress*
inout_Signals, UINT32 in_SignalCount);
ERuntimeErrorCode ReadSignals(EArea in_Area, SDataValueByAddressWithCheck*
inout_Signals, UINT32 in_SignalCount, bool* out_SignalsHaveChanged);
Parameters • EArea in_Area:
The area from which you want to read. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 318).
• SDataValueByAddress* inout_Signals:
The signal list that is read. The result is stored in the structure.
• SDataValueByAddressWithCheck* inout_Signals:
The signal list that is read. The result is stored in the structure. "ValueHasChanged" is set to
true if the value of the signal has changed since the preceding call.
• UINT32 in_SignalCount:
Number of signals in the list.
• bool* out_SignalsHaveChanged:
Returns true if the value of at least one signal has changed since the preceding call.
Signal error Error code Description
SREC_OK The signal operation is successful.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not supported.
SREC_TYPE_MISMATCH The expected type does not match the stored type. See
Compatible primitive data types (Page 325).
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_WRONG_ARGUMENT The area is invalid.
SREC_SIGNAL_CONFIGURATION_ERROR At least one signal error is in the list.

Table 8-190 ReadSignals() - .NET (C#)

Syntax void ReadSignals(ref SDataValueByAddress[] inout_Signals);
void ReadSignals(ref SDataValueByAddressWithCheck[] inout_Signals out bool
out_SignalsHaveChanged);
Parameters • ref SDataValueByAddress[] inout_Signals:
The signal list that is read.
• ref SDataValueByAddressWithCheck[] inout_Signals:
The signal list that is read. The result is stored in the structure. "ValueHasChanged" is set to
true if the value of the signal has changed since the preceding call.
• out bool out_SignalsHaveChanged:
Returns true if the value of at least one signal has changed since the preceding call.

S7-PLCSIM Advanced
182 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Signal error Runtime error code Description

ERuntimeErrorCode.OK The signal operation is successful.
ERuntimeErrorCode.IndexOutOfRange Offset or bits are invalid.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode. At least one signal error is in the list.
SignalConfigurationError

8.6.5.3 I/O access via address - Writing

WriteBit()
Writes an individual bit to the area.

NOTE
Data can be overwritten
The function allows access to the entire storage area of the virtual controller.
Therefore, use access via the tag name (Page 206) and not via the address areas.

Table 8-191 WriteBit() - Native C++

Syntax ERuntimeErrorCode WriteBit(EArea in_Area, UINT32 in_Offset, UINT8 in_Bit,
bool in_Value);
Parameters • EArea in_Area:
The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 318).
• UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that GetAreaSize()
returns.
• UINT8 in_Bit:
The bit offset within the byte. The value must be between 0 and 7.
• bool in_Value:
Bit value.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE Offset or bits are invalid.
SREC_WRONG_ARGUMENT Area is invalid.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 183
User interfaces (API)
8.6 API IInstances

Table 8-192 WriteBit() - .NET (C#)

Syntax void InputArea WriteBit(UInt32 in_Offset, Byte in_Bit, bool in_Value);
void MarkerArea WriteBit(UInt32 in_Offset, Byte in_Bit, bool in_Value);
void OutputArea WriteBit(UInt32 in_Offset, Byte in_Bit, bool in_Value);
Parameters • UInt32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that AreaSize
returns.
• Byte in_Bit:
The bit offset within the byte. The value must be between 0 and 7.
• bool in_Value:
Bit value.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange Offset or bits are invalid.

WriteByte()
Writes an individual byte to the area.

NOTE
Data can be overwritten
The function allows access to the entire storage area of the virtual controller.
Therefore, use access via the tag name (Page 206) and not via the address areas.

Table 8-193 WriteByte() - Native C++

Syntax ERuntimeErrorCode WriteByte(EArea in_Area, UINT32 in_Offset, BYTE
in_Value);
Parameters • EArea in_Area:
The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 318).
• UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that GetAreaSize()
returns.
• BYTE in_Value:
Byte value.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE Offset is invalid.
SREC_WRONG_ARGUMENT Area is invalid.

S7-PLCSIM Advanced
184 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Table 8-194 WriteByte() - .NET (C#)

Syntax void InputArea.WriteByte(UInt32 in_Offset, Byte in_Value);
void MarkerArea.WriteByte(UInt32 in_Offset, Byte in_Value);
void OutputArea.WriteByte(UInt32 in_Offset, Byte in_Value);
Parameters • UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that AreaSize
returns.
• BYTE in_Value:
Byte value.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange Offset is invalid.

WriteBytes()
Writes a byte array to the area.

NOTE
Data can be overwritten
The function allows access to the entire storage area of the virtual controller.
In particular, do not write to bytes that belong to other applications or contain internal data,
for example, qualifier bits for fail-safe I/O modules.
Therefore, use access via the tag name (Page 206) and not via the address areas.

Table 8-195 WriteBytes() - Native C++

Syntax ERuntimeErrorCode WriteBytes(EArea in_Area, UINT32 in_Offset, UINT32
in_BytesToWrite, UINT32* out_BytesWritten, BYTE in_Values[]);
Parameters • EArea in_Area:
The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 318).
• UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that GetAreaSize()
returns.
• UINT32 in_BytesToWrite:
Contains the size of the array value to be written.
• UINT32* out_BytesWritten:
Contains the number of bytes that were just written.
• BYTE in_Values[]:
Byte array that is to be written to the area.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 185
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No byte could
be written.
SREC_WRONG_ARGUMENT The area is invalid.

Table 8-196 WriteBytes() - .NET (C#)

Syntax UInt32 InputArea.WriteBytes(UInt32 in_Offset, Byte[] in_Values);
UInt32 InputArea.WriteBytes(UInt32 in_Offset, UInt32 in_BytesToWrite,
Byte[] in_Values);
UInt32 MarkerArea.WriteBytes(UInt32 in_Offset, Byte[] in_Values);
UInt32 MarkerArea.WriteBytes(UInt32 in_Offset, UInt32 in_BytesToWrite,
Byte[] in_Values);
UInt32 OutputArea.WriteBytes(UInt32 in_Offset, Byte[] in_Values);
UInt32 OutputArea.WriteBytes(UInt32 in_Offset, UInt32 in_BytesToWrite,
Byte[] in_Values);
Parameters • UINT32 in_Offset:
The byte offset within the area. The value must be between 0 and the value that AreaSize
returns.
• UInt32 in_BytesToWrite:
Contains the number of bytes to be written. The value must be between 1 and the size of the array
value.
• BYTE in_Value:
Byte value.
Return values Uint32: Contains the number of bytes that were just written.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No byte could
be written.

WriteSignals()
Writes multiple signals within an API call.
The function also takes into consideration the byte order (Endianness).
The function supports only primitive data type signals, but it is not typical.

NOTE
Data can be overwritten
The function allows access to the entire storage area of the virtual controller.
Therefore, use access via the tag name (Page 206) and not via the address areas.

S7-PLCSIM Advanced
186 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Table 8-197 WriteSignals() - Native C++

Syntax ERuntimeErrorCode WriteSignals(EArea in_Area, SDataValueByAddress*
in_Signals, UINT32 in_SignalCount);
Parameters • EArea in_Area:
The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 318).
• SDataValueByAddress* inout_Signals:
The signal list to be written.
• UINT32 in_SignalCount:
Number of signals in the list.
Signal error Error code Description
SREC_OK The signal operation is successful.
SREC_INDEX_OUT_OF_RANGE Offset or bits are invalid.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_SIGNAL_CONFIGURATION_ERROR At least one signal error is in the list.
SREC_WRONG_ARGUMENT The area is invalid.

Table 8-198 WriteSignals() - .NET (C#)

Syntax void InputArea.WriteSignals(SDataValueByAddress[] in_Signals);
void MarkerArea.WriteSignals(SDataValueByAddress[] in_Signals);
void OutputArea.WriteSignals(SDataValueByAddress[] in_Signals);
Parameters • SDataValueByAddress[] in_Signals:
The signal list to be written.
Return values None
Signal error Error code Description
ERuntimeErrorCode.OK The signal operation is successful.
ERuntimeError-Code.IndexOutOfRange Offset or bits are invalid.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode. At least one signal error is in the list.
SignalConfigurationError

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 187
User interfaces (API)
8.6 API IInstances

8.6.5.4 I/O access via tag name - Reading

Individual access to I/O data is used for displaying and writing values which are not refreshed
regularly in a graphical user interface (GUI).

NOTE
To simulate a regular exchange of signals, create a signal list for each set of signals. Use this
signal list for all further accesses. Create a new list as soon as the set of signals changes.
For the signal lists use the functions ReadSignals() and WriteSignals().

Read()
Reads the value of a PLC tag.
Table 8-199 Read() - Native C++
Syntax ERuntimeErrorCode Read(WCHAR* in_Tag, SDataValue* inout_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• SDataValue* inout_Value:
Contains the value and the expected type of the PLC tag. If the expected type is UNSPECIFIC, it is
set to the stored type when the function was successful. The STRUCT type is not supported.
Structures and fields can be emulated through signal lists and be read by using the
ReadSignals() function.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-200 Read() - .NET (C#)

Syntax SDataValue Read(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values SDataValue: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
188 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 326).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadBool()
Reads the value of a PLC tag.
Table 8-201 ReadBool() - Native C++
Syntax ERuntimeErrorCode ReadBool(WCHAR* in_Tag, bool* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• bool* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-202 ReadBool() - .NET (C#)

Syntax bool ReadBool(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values bool: Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 189
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadInt8()
Reads the value of a PLC tag.
Table 8-203 ReadInt8() - Native C++
Syntax ERuntimeErrorCode ReadInt8(WCHAR* in_Tag, INT8* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• INT8* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-204 ReadInt8() - .NET (C#)

Syntax Int8 ReadInt8(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values Int8: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
190 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadInt16()
Reads the value of a PLC tag.
Table 8-205 ReadInt16() - Native C++
Syntax ERuntimeErrorCode ReadInt16(WCHAR* in_Tag, INT16* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• INT16* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-206 ReadInt16() - .NET (C#)

Syntax Int16 ReadInt16(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values Int16: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 191
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadInt32()
Reads the value of a PLC tag.
Table 8-207 ReadInt32() - Native C++
Syntax ERuntimeErrorCode ReadInt32(WCHAR* in_Tag, INT32* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• INT32* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-208 ReadInt32() - .NET (C#)

Syntax Int32 ReadInt32(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values Int32: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
192 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadInt64()
Reads the value of a PLC tag.
Table 8-209 ReadInt64() - Native C++
Syntax ERuntimeErrorCode ReadInt64(WCHAR* in_Tag, INT64* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• INT64* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-210 ReadInt64() - .NET (C#)

Syntax Int64 ReadInt64(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values Int64: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 193
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadUInt8()
Reads the value of a PLC tag.
Table 8-211 ReadUInt8() - Native C++
Syntax ERuntimeErrorCode ReadUInt8(WCHAR* in_Tag, UINT8* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• UINT8* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-212 ReadUInt8() - .NET (C#)

Syntax UInt8 ReadUInt8(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values UInt8: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
194 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadUInt16()
Reads the value of a PLC tag.
Table 8-213 ReadUInt16() - Native C++
Syntax ERuntimeErrorCode ReadUInt16(WCHAR* in_Tag, UINT16* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• UINT16* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-214 ReadUInt16() - .NET (C#)

Syntax UInt16 ReadUInt16(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values UInt16: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 195
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadUInt32()
Reads the value of a PLC tag.
Table 8-215 ReadUInt32() - Native C++
Syntax ERuntimeErrorCode ReadUInt32(WCHAR* in_Tag, UINT32* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• UINT32* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-216 ReadUInt32() - .NET (C#)

Syntax UInt32 ReadUInt32(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values Uint32: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
196 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadUInt64()
Reads the value of a PLC tag.
Table 8-217 ReadInt64() - Native C++
Syntax ERuntimeErrorCode ReadUInt64(WCHAR* in_Tag, UINT64* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• UINT64* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-218 ReadUInt64() - .NET (C#)

Syntax UInt64 ReadUInt64(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values UInt64: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 197
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadFloat()
Reads the value of a PLC tag.
Table 8-219 ReadFloat() - Native C++
Syntax ERuntimeErrorCode ReadFloat(WCHAR* in_Tag, float* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• float* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-220 ReadFloat() - .NET (C#)

Syntax float ReadFloat(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values float: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
198 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadDouble()
Reads the value of a PLC tag.
Table 8-221 ReadDouble() - Native C++
Syntax ERuntimeErrorCode ReadDouble(WCHAR* in_Tag, double* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• double* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-222 ReadDouble() - .NET (C#)

Syntax double ReadDouble(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values double: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 199
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadChar()
Reads the value of a PLC tag.
Table 8-223 ReadChar() - Native C++
Syntax ERuntimeErrorCode ReadChar(WCHAR* in_Tag, char* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• char* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-224 ReadChar() - .NET (C#)

Syntax sbyte ReadChar(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values sbyte: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
200 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadWChar()
Reads the value of a PLC tag.
Table 8-225 ReadWChar() - Native C++
Syntax ERuntimeErrorCode ReadWChar(WCHAR* in_Tag, WCHAR* out_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• WCHAR* out_Value:
Contains the value of the PLC tag.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-226 ReadWChar() - .NET (C#)

Syntax char ReadWChar(string in_Tag)
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values char: Contains the value and the type of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 201
User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

ReadSignals()
Reads multiple signals within an API call.
When the function is called for the first time, it stores internal information in the structures
SDataValueByName* to improve the performance of the subsequent calls.

NOTE
To simulate a regular exchange of signals, create a signal list for each set of signals. Use this
signal list for all further accesses. Create a new list as soon as the set of signals changes.

Table 8-227 ReadSignals() - Native C++

Syntax ERuntimeErrorCode ReadSignals(SDataValueByName* inout_Signals, UINT32
in_SignalCount);
ERuntimeErrorCode ReadSignals(SDataValueByNameWithCheck* inout_Signals,
UINT32 in_SignalCount bool* out_SignalsHaveChanged);
Parameters • SDataValueByName* inout_Signals:
Contains the name, the value and the expected type of the PLC tag. If the expected type is
UNSPECIFIC, it is set to the stored type when the function was successful. The STRUCT type is
not supported.
• SDataValueByNameWithCheck* inout_Signals:
Contains the name, the value and the expected type of the PLC tag. If the expected type is
UNSPECIFIC, it is set to the stored type when the function was successful. The STRUCT type is
not supported. "ValueHasChanged" is set to true if the value of the signal has changed since
the preceding call.
• UINT32 in_SignalCount:
The number of signals to be read.
• bool* out_SignalsHaveChanged:
Returns true if the value of at least one signal has changed since the preceding call.

S7-PLCSIM Advanced
202 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Signal error Runtime error code Description

SREC_OK The signal operation is successful.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_INDEX_OUT_OF_RANGE Offset or bits are invalid.
Return values Runtime error code Condition
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_NOT_UP_TO_DATE The stored tag list must be updated.
SREC_SIGNAL_CONFIGURATION_ERROR At least one signal error is in the list.

Table 8-228 ReadSignals() - .NET (C#)

Syntax void ReadSignals(ref SDataValueByName[] inout_Signals)
void ReadSignals(ref SDataValueByNameWithCheck[] inout_Signals out bool
out_SignalsHaveChanged);
Parameters • ref SDataValueByName[] inout_Signals:
Contains the name, the value and the expected type of the PLC tag. If the expected type is
UNSPECIFIC, it is set to the stored type when the function was successful. The STRUCT type is
not supported.
• ref SDataValueByNameWithCheck[] inout_Signals:
Contains the name, the value and the expected type of the PLC tag. If the expected type is
UNSPECIFIC, it is set to the stored type when the function was successful. The STRUCT type is
not supported. "ValueHasChanged" is set to true if the value of the signal has changed since
the preceding call.
• out bool out_SignalsHaveChanged:
Returns true if the value of at least one signal has changed since the preceding call.
Return values SDataValue: Contains the value and the type of the PLC tag.
Signal error Runtime error code Description
ERuntimeErrorCode.OK The signal operation is successful.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.IndexOutOfRange Offset or bits are invalid.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 203
User interfaces (API)
8.6 API IInstances

ReadString()
Reads the value of a PLC tag.
Table 8-229 ReadString() - Native C++
Syntax ERuntimeErrorCode IInstance::ReadString(
const WCHAR* in_Tag,
CHAR* out_Value,
const UINT32 in_BufferSize,
UINT32* out_CharsRead
);
Parameters • const WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• CHAR* out_Value:
Contains the value of the PLC tag
• const UINT32 in_BufferSize:
Size of the buffer provided
• UINT32* out_CharsRead:
Number of characters read
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.
SREC_BUFFER_OVERFLOW The buffer provided is too small.

Table 8-230 ReadString() - .NET (C#)

Syntax string ReadString(
string in_Tag
);
Parameters • string in_Tag:
The name of the PLC tag that is to be read.
Return values string: Contains the value of the PLC tag.
Exceptions Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.

S7-PLCSIM Advanced
204 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToDate The stored tag list must be updated.
ERuntimeErrorCode.BufferOverflow The buffer provided is too small.

ReadWString()
Reads the value of a PLC tag.
Table 8-231 ReadWString() - Native C++
Syntax ERuntimeErrorCode IInstance::ReadWString(
const WCHAR* in_Tag,
WCHAR* out_Value,
const UINT32 in_BufferSize,
UINT32* out_CharsRead
);
Parameters • const WCHAR* in_Tag:
The name of the PLC tag that is to be read.
• WCHAR* out_Value:
Contains the value of the PLC tag
• const UINT32 in_BufferSize:
Size of the buffer provided
• UINT32* out_CharsRead:
Number of characters read
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be read.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.
SREC_BUFFER_OVERFLOW The buffer provided is too small.

Table 8-232 ReadWString() - .NET (C#)

Syntax wstring ReadWString(
wstring in_Tag
);
Parameters • wstring in_Tag:
The name of the PLC tag that is to be read.
Return values wstring: Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 205
User interfaces (API)
8.6 API IInstances

Exceptions Runtime error code Description

ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be read.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToDate The stored tag list must be updated.
ERuntimeErrorCode.BufferOverflow The buffer provided is too small.

8.6.5.5 I/O access via tag name - Writing

Individual access to I/O data is used for displaying and writing values that are not refreshed
regularly in a graphical user interface (GUI).

NOTE
To simulate a regular exchange of signals, create a signal list for each set of signals. Use this
signal list for all further accesses. Create a new list as soon as the set of signals changes.
For the signal lists use the functions ReadSignals() and WriteSignals().

Write()
Writes the value of a PLC tag.
Table 8-233 Write() - Native C++
Syntax ERuntimeErrorCode Write(WCHAR* in_Tag, SDataValue* in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• SDataValue* in_Value:
Contains the value and the expected type of the PLC tag. The UNSPECIFIC and STRUCT types are
not supported.
Structures and fields can be emulated through signal lists and then be read by using the
ReadSignals() function and written by using the WriteSignals() function.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.

S7-PLCSIM Advanced
206 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.
SREC_WRONG_ARGUMENT The expected type is UNSPECIFIC.

Table 8-234 Write() - .NET (C#)

Syntax void Write(string in_Tag SDataValue in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• SDataValue in_Value:
Contains the value and the expected type of the PLC tag. The UNSPECIFIC and STRUCT types are
not supported.
Structures and fields can be emulated through signal lists and then be written by using the
WriteSignals() function.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.
ERuntimeErrorCode.WrongArgument The expected type is UNSPECIFIC.

WriteBool()
Writes the value of a PLC tag.
Table 8-235 WriteBool() - Native C++
Syntax ERuntimeErrorCode WriteBool(WCHAR* in_Tag, bool in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• bool in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 207
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-236 WriteBool() - .NET (C#)

Syntax void WriteBool(string in_Tag bool in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• bool in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 326).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteInt8()
Writes the value of a PLC tag.
Table 8-237 WriteInt8() - Native C++
Syntax ERuntimeErrorCode WriteInt8(WCHAR* in_Tag, INT8 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• INT8 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
208 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-238 WriteInt8() - .NET (C#)

Syntax void WriteInt8(string in_Tag Int8 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• Int8 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteInt16()
Writes the value of a PLC tag.
Table 8-239 WriteInt16() - Native C++
Syntax ERuntimeErrorCode WriteInt16(WCHAR* in_Tag, INT16 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• INT16 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 209
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-240 WriteInt16() - .NET (C#)

Syntax void WriteInt16(string in_Tag Int16 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• Int16 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteInt32()
Writes the value of a PLC tag.
Table 8-241 WriteInt32() - Native C++
Syntax ERuntimeErrorCode WriteInt32(WCHAR* in_Tag, INT32 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• INT32 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
210 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-242 WriteInt32() - .NET (C#)

Syntax void WriteInt32(string in_Tag Int32 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• Int32 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteInt64()
Writes the value of a PLC tag.
Table 8-243 WriteInt64() - Native C++
Syntax ERuntimeErrorCode WriteInt64(WCHAR* in_Tag, INT64 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• INT64 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 211
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-244 WriteInt64() - .NET (C#)

Syntax void WriteInt64(string in_Tag Int64 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• Int64 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteInt8()
Writes the value of a PLC tag.
Table 8-245 WriteUInt8() - Native C++
Syntax ERuntimeErrorCode WriteUInt8(WCHAR* in_Tag, UINT8 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• UINT8 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
212 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-246 WriteUInt8() - .NET (C#)

Syntax void WriteUInt8(string in_Tag UInt8 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• UInt8 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteUInt16()
Reads the value of a PLC tag.
Table 8-247 WriteUInt16() - Native C++
Syntax ERuntimeErrorCode WriteUInt16(WCHAR* in_Tag, UINT16 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• UINT16 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 213
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-248 WriteUInt16() - .NET (C#)

Syntax void WriteUInt16(string in_Tag UInt16 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• UInt16 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteUInt32()
Writes the value of a PLC tag.
Table 8-249 WriteUInt32() - Native C++
Syntax ERuntimeErrorCode WriteUInt32(WCHAR* in_Tag, UINT32 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• UINT32 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
214 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-250 WriteUInt32() - .NET (C#)

Syntax void WriteUInt32(string in_Tag UInt32 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• UInt32 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteUInt64()
Writes the value of a PLC tag.
Table 8-251 WriteUInt64() - Native C++
Syntax ERuntimeErrorCode WriteUInt64(WCHAR* in_Tag, UINT64 in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• UINT64 in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 215
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-252 WriteUInt64() - .NET (C#)

Syntax void WriteUInt64(string in_Tag UInt64 in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• UInt64 in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteFloat()
Writes the value of a PLC tag.
Table 8-253 WriteFloat() - Native C++
Syntax ERuntimeErrorCode WriteFloat(WCHAR* in_Tag, float in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• float in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
216 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-254 WriteFloat() - .NET (C#)

Syntax void WriteFloat(string in_Tag float in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• float in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteDouble()
Writes the value of a PLC tag.
Table 8-255 WriteDouble() - Native C++
Syntax ERuntimeErrorCode WriteDouble(WCHAR* in_Tag, double in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• double in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 217
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-256 WriteDouble() - .NET (C#)

Syntax void WriteDouble(string in_Tag double in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• double in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteChar()
Writes the value of a PLC tag.
Table 8-257 WriteChar() - Native C++
Syntax ERuntimeErrorCode WriteChar(WCHAR* in_Tag, char in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• char in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
218 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-258 WriteChar() - .NET (C#)

Syntax void WriteChar(string in_Tag sbyte in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• sbyte in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteWChar()
Writes the value of a PLC tag.
Table 8-259 WriteWChar() - Native C++
Syntax ERuntimeErrorCode WriteWChar(WCHAR* in_Tag, WCHAR in_Value);
Parameters • WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• WCHAR in_Value:
Contains the value of the PLC tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 219
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.

Table 8-260 WriteWChar() - .NET (C#)

Syntax void WriteWChar(string in_Tag char in_Value)
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• char in_Value:
Contains the value of the PLC tag.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMissmatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.

WriteSignals()
Writes multiple signals within an API call.

S7-PLCSIM Advanced
220 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

When the function is called for the first time, it stores internal information in the structures
SDataValueByName* to improve the performance of the subsequent calls.

NOTE
To simulate a regular exchange of signals, create a signal list for each set of signals. Use this
signal list for all further accesses. Create a new list as soon as the set of signals changes.

Table 8-261 WriteSignals() - Native C++

Syntax ERuntimeErrorCode WriteSignals(SDataValueByName* inout_Signals, UINT32
in_SignalCount);
Parameters • SDataValueByName* inout_Signals:
Contains the name, the value and the expected type of the PLC tag. The UNSPECIFIC and
STRUCT types are not supported.
• UINT32 in_SignalCount:
Number of signals.
Signal error Error code Description
SREC_INDEX_OUT_OF_RANGE Offset or bits are invalid.
Return values Runtime error code Condition
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.
SREC_WRONG_ARGUMENT The expected type is UNSPECIFIC.

Table 8-262 WriteSignals() - .NET (C#)

Syntax void WriteSignals(SDataValueByName[] in_Signals)
Parameters • SDataValueByName:
Contains the name, the value and the expected type of the PLC tag. The UNSPECIFIC and
STRUCT types are not supported.
Return values None
Signal error Error code Description
ERuntimeErrorCode.IndexOutOfRange Offset or bits are invalid.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 221
User interfaces (API)
8.6 API IInstances

Exceptions ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­

ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 326).
ERuntimeErrorCode.NotUpToData The stored tag list must be updated.
ERuntimeErrorCode.WrongArgument The expected type is UNSPECIFIC.

WriteString()
Writes the value of a PLC tag.
Table 8-263 WriteString() - Native C++
Syntax ERuntimeErrorCode IInstance::WriteString(
const WCHAR* in_Tag,
const CHAR* in_Value,
const UINT32 in_CharsToWrite
);
Parameters • const WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• CHAR* in_Value:
Contains the value of the PLC tag
• const UINT32 in_CharsToWrite:
Number of characters read
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.
SREC_BUFFER_OVERFLOW The characters to be written are greater than the
maximum value of the tag.

Table 8-264 WriteString() - .NET (C#)

Syntax void WriteString(
string in_Tag,
string in_Value
);
Parameters • string in_Tag:
The name of the PLC tag that is to be written.
• string in_Value:
The value to be written to the PLC tag.
Return values None

S7-PLCSIM Advanced
222 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Runtime error code Description

ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToDate The stored tag list must be updated.
ERuntimeErrorCode.BufferOverflow The characters to be written are greater than the
maximum value of the tag.

WriteWString()
Writes the value of a PLC tag.
Table 8-265 WriteWString() - Native C++
Syntax ERuntimeErrorCode IInstance::WriteWString(
const WCHAR* in_Tag,
const WCHAR* in_Value,
const UINT32 in_CharsToWrite,
);
Parameters • const WCHAR* in_Tag:
The name of the PLC tag that is to be written.
• const WCHAR* in_Value:
Contains the value of the PLC tag
• const UINT32 in_CharsToWrite:
Number of characters that are to be written.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_INDEX_OUT_OF_RANGE The offset lies outside the area range. No value
could be written.
SREC_DOES_NOT_EXIST The entry does not exist in the stored tag list.
SREC_NOT_SUPPORTED Access to entire structures or arrays is not suppor­
ted.
SREC_TYPE_MISMATCH The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
SREC_NOT_UP_TO_DATE The stored tag list must be updated.
SREC_BUFFER_OVERFLOW The characters to be written are greater than the
maximum value of the tag.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 223
User interfaces (API)
8.6 API IInstances

Table 8-266 WriteWString() - .NET (C#)

Syntax void WriteWString(
wstring in_Tag,
wstring in_Value
);
Parameters • wstring in_Tag:
The name of the PLC tag that is to be written.
• wstring in_Value:
The value to be written to the PLC tag.
Return values None
Exceptions Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.IndexOutOfRange The offset lies outside the area range. No value
could be written.
ERuntimeErrorCode.DoesNotExist The entry does not exist in the stored tag list.
ERuntimeErrorCode.NotSupported Access to entire structures or arrays is not suppor­
ted.
ERuntimeErrorCode.TypeMismatch The expected type does not match the stored type.
See Compatible primitive data types (Page 325).
ERuntimeErrorCode.NotUpToDate The stored tag list must be updated.
ERuntimeErrorCode.BufferOverflow The characters to be written are greater than the
maximum value of the tag.

8.6.6 Settings for the virtual time

GetSystemTime()
Returns the virtual system time of the virtual controller. Returns an empty structure when the
function fails.
Table 8-267 GetSystemTime() - Native C++
Syntax SYSTEMTIME GetSystemTime();
Parameters None
Return values SYSTEMTIME: System time of the virtual controller.

SetSystemTime()
Sets the virtual system time of the virtual controller. A system time between
"Jan 1 1970 00:00:00:000" and "Dec 31 2200 23:59:59:999" is valid.
Table 8-268 SetSystemTime() - Native C++
Syntax ERuntimeErrorCode SetSystemTime(SYSTEMTIME in_SystemTime);

S7-PLCSIM Advanced
224 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Parameters • SYSTEMTIME in_SystemTime:

System time that is to be set for the virtual controller.
Return values Runtime error code Condition
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The value is outside the limits.

SystemTime { get; set; }

Sets or returns the virtual system time of the virtual controller. A system time between
"Jan 1 1970 00:00:00:000" and "Dec 31 2200 23:59:59:999" is valid.
Table 8-269 SystemTime { get; set; } - .NET (C#)
Syntax DateTime SystemTime { get; set; }
Parameters None
Return values Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Condition
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The value is outside the limits.

GetScaleFactor()
Returns the scaling factor with which the virtual time advances.
Table 8-270 GetScaleFactor() - Native C++
Syntax double GetScaleFactor();
Parameters None
Return values double: Scaling factor of the virtual time.

SetScaleFactor()
Sets the scaling factor with which the virtual time advances.
We recommend that you start with a small scaling factor and gradually work your way up to a
scaling factor where the virtual controller remains in RUN.
A value between 0.01 and 100 is valid. The default setting is 1.
• If the value is less than 1, the virtual time of the virtual controller runs X-times slower than
the real time.
• If the value is greater than 1, the virtual time of the virtual controller runs X-times faster
than the real time.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 225
User interfaces (API)
8.6 API IInstances

A change in the value during runtime only takes effect at the cycle control point.
Table 8-271 SetScaleFactor() - Native C++
Syntax ERuntimeErrorCode SetScaleFactor (double in_Value);
Parameters • double in_Value:
Scaling factor of the virtual time.
Return values Runtime error code Condition
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The value is outside the limits.

ScaleFactor { get; set; }

Sets or returns the scaling factor with which the virtual time advances.
Start with a small scaling factor and incrementally approach a scaling factor at which the
virtual controller remains in RUN.
A value between 0.01 and 100 is valid. The default setting is 1.
• If the value is less than 1, the virtual time of the virtual controller runs X-times slower than
the real time.
• If the value is greater than 1, the virtual time of the virtual controller runs X-times faster
than the real time.
A change in the value during runtime only takes effect at the cycle control point.
Table 8-272 ScaleFactor { get; set; } - .NET (C#)
Syntax double ScaleFactor { get; set; }
Parameters None
Return values double: Scaling factor of the virtual time.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Condition
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The value is outside the limits.

8.6.7 Cycle control

GetOperatingMode()
Returns the operating mode (Page 320) of the virtual controller.
Table 8-273 GetOperatingMode() - Native C++
Syntax EOperatingMode GetOperatingMode();
Parameters None

S7-PLCSIM Advanced
226 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values EOperatingMode: Operating mode of the virtual controller

SetOperatingMode()
Sets the operating mode of the virtual controller.
A change in the value during runtime only takes effect at the synchronization point.
Table 8-274 SetOperatingMode() - Native C++
Syntax void SetOperatingMode(EOperatingMode in_OperatingMode);
Parameters • EOperatingMode in_OperatingMode:
Operating mode of the virtual controller

OperatingMode { get; set; }

Returns or sets the operating mode of the virtual controller.
A change in the value during runtime only takes effect at the synchronization point.
Table 8-275 OperatingMode { get; set; } - .NET (C#)
Syntax EOperatingMode OperatingMode { get; set; }
Parameters None
Return values EOperatingMode: Operating mode of the virtual controller
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

SetSendSyncEventInDefaultModeEnabled()
Sets the SendSyncEventInDefault mode. In this mode the OnSyncPointReached
event is triggered after each cycle end in the Default operating mode. See
OnSyncPointReached (Page 255).
Table 8-276 SetSendSyncEventInDefaultModeEnabled() - Native C++
Syntax ERuntimeErrorCode SetSendSyncEventInDefaultModeEnabled(bool in_Enable);
Parameters • bool in_Enable:
If true, the OnSyncPointReached event is triggered after each cycle in the Default operating
mode.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 227
User interfaces (API)
8.6 API IInstances

IsSendSyncEventInDefaultModeEnabled()
Returns the SendSyncEventInDefaultMode mode. When the function fails, the return
value is false.
Table 8-277 IsSendSyncEventInDefaultModeEnabled() - Native C++
Syntax bool IsSendSyncEventInDefaultModeEnabled();
Parameters None
Return values • false: The event is not triggered (unless the Sync-Freeze mode is active).
• true: The event is triggered after every cycle.

IsSendSyncEventInDefaultModeEnabled { get; set; }

Returns or sets the SendSyncEventInDefaultMode mode. In this mode the
OnSyncPointReached event is triggered after each cycle end for every operating mode. If
the event is also to be received in the Default operating mode, set the return value to true.
See OnSyncPointReached (Page 255).
Table 8-278 IsSendSyncEventInDefaultModeEnabled { get; set; } - .NET (C#)
Syntax bool IsSendSyncEventInDefaultModeEnabled { get; set;}
Parameters None
Return values • false: The event is not triggered (unless the Sync-Freeze mode is active).
• true: The event is triggered after every cycle.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

GetOverwrittenMinimalCycleTime_ns()
Returns the overwritten minimum cycle time (in nanoseconds) that is used in the
SingleStep_CT and SingleStep_CPT operating modes.
Table 8-279 GetOverwrittenMinimalCycleTime_ns() - Native C++
Syntax INT64 GetOverwrittenMinimalCycleTime_ns();
Parameters None
Return values INT64: The overwritten minimum cycle time in nanoseconds.

SetOverwrittenMinimalCycleTime_ns()
Sets the overwritten minimum cycle time (in nanoseconds) that is used in the
SingleStep_CT and SingleStep_CPT operating modes.
A value between 0 and 6000000000 is valid. The default setting is 100 ms.

S7-PLCSIM Advanced
228 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

A change in the value during runtime only takes effect at the cycle control point.
Table 8-280 SetOverwrittenMinimalCycleTime_ns() - Native C++
Syntax ERuntimeErrorCode SetOverwrittenMinimalCycleTime_ns(INT64
in_CycleTime_ns);
Parameters • INT64 in_CycleTime_ns:
The overwritten minimum cycle time in nanoseconds.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The value is outside the limits.

OverwrittenMinimalCycleTime_ns { get; set; }

Returns or sets the overwritten minimum cycle time in nanoseconds that is used in the
SingleStep_CT and SingleStep_CPT operating modes.
A value between 0 and 6000000000 is valid. The default setting is 100 ms.
A change in the value during runtime only takes effect at the cycle control point.
Table 8-281 OverwrittenMinimalCycleTime_ns { get; set; } - .NET (C#)
Syntax Int64 OverwrittenMinimalCycleTime_ns { get; set; }
Parameters None
Return values Int64: The overwritten minimum cycle time in nanoseconds.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The value is outside the limits.

RunToNextSyncPoint()
If the virtual controller is running in a SingleStep operating mode, it is stopped at the
synchronization point (Freeze state). The RunToNextSyncPoint() function cancels the
freeze state. The virtual controller continues to run until the next synchronization point.
Table 8-282 RunToNextSyncPoint() - Native C++
Syntax ERuntimeErrorCode RunToNextSyncPoint();
ERuntimeErrorCode RunToNextSyncPoint(UINT32 in_IoSystemId, UINT64
in_BusTimeStamp_ns);
Parameters The call with parameters is only valid for the SingleStep_Bus operating mode.
• UINT32 in_IoSystemId:
Number of the I/O system (PROFIBUS 1..32, PROFINET 100..115) that is to be used for the cycle-
controlled synchronization of the virtual controller.
• UINT64 in_BusTimeStamp_ns:
Time stamp in nanoseconds of the respective I/O system at the start of each cycle.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 229
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INVALID_OPERATING_STATE The instance is in an invalid operating state for pro­
cessing the call (BOOTING, SHUTTING_DOWN, OFF)
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_WRONG_ARGUMENT For the SingleStep_Bus operating mode:
The ID of the I/O system is invalid.
For all other operating modes:
The function call with parameters is invalid.

Table 8-283 RunToNextSyncPoint() - .NET (C#)

Syntax void RunToNextSyncPoint();
void RunToNextSyncPoint(UINT32 in_IoSystemId, UINT64 in_BusTimeStamp_ns);
Parameters The call with parameters is only valid for the SingleStep_Bus operating mode.
• UINT32 in_IoSystemId:
Number of the I/O system (PROFIBUS 1..32, PROFINET 100..115) that is to be used for the cycle-
controlled synchronization of the virtual controller.
• UINT64 in_BusTimeStamp_ns:
Time stamp in nanoseconds of the respective I/O system at the start of each cycle.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InvalidOperatingS The instance is in an invalid operating state for pro­
tate cessing the call (BOOTING, SHUTTING_DOWN, OFF)
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.WrongArgument For the SingleStep_Bus operating mode:
The ID of the I/O system is invalid.
For all other operating modes:
The function call with parameters is invalid.

StartProcessing()
If the virtual controller is running in a TimespanSynchronized operating mode, it is stopped at
the synchronization point (Freeze state). The StartProcessing() function cancels the
freeze state. The virtual controller will now run for at least the requested time before it
changes to Freeze state at the next synchronization point.
Table 8-284 StartProcessing() - Native C++
Syntax ERuntimeErrorCode StartProcessing(INT64 in_MinimalTimeToRun_ns);
Parameters • INT64 in_MinimalTimeToRun_ns:
The minimum virtual time (in nanoseconds) that the virtual controller runs before it changes to
Freeze state.

S7-PLCSIM Advanced
230 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INSTANCE_NOT_RUNNING The process of the virtual controller is not running.
SREC_WRONG_ARGUMENT The value is less than 0.

Table 8-285 StartProcessing() - .NET (C#)

Syntax void StartProcessing(Int64 in_MinimalTimeToRun_ns);
Parameters • Int64 in_MinimalTimeToRun_ns:
The minimum virtual time (in nanoseconds) that the virtual controller runs before it changes to
Freeze state.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.InstanceNotRunning The process of the virtual controller is not running.
ERuntimeErrorCode.WrongArgument The value is less than 0.

More information
For more information, see sections Virtual time response (Page 87), Stop simulation (Page
89).

SetCycleTimeMonitoringMode()
With this function the source of the timer for the maximum cycle time monitoring can be
changed.
Table 8-286 SetCycleTimeMonitoringMode() - Native C++
Syntax ERuntimeErrorCode SetCycleTimeMonitoringMode(ECycleTimeMonitoringMode
in_CycleTimeMonitoringMode)
ERuntimeErrorCode SetCycleTimeMonitoringMode(ECycleTimeMonitoringMode
in_CycleTimeMonitoringMode, INT64 in_MaxCycleTime_ns)
Parameters • ECycleTimeMonitoringMode in_CycleTimeMonitoringMode:
Select one of the following options for the maximum cycle time monitoring:
– SRCTMM_DOWNLOADED:
The maximum cycle time from the project that was downloaded from STEP 7 is used as maxim­
um cycle time monitoring.
– SRCTMM_IGNORED (default):
A timer value of one minute is used as maximum cycle time monitoring to prevent a potential
error in case of an overflow of cyclic events.
See Monitoring overflow (Page 343).
– SRCTMM_SPECIFIED:
A value that is specified with the in_MaxCycleTime_ns parameter is used as maximum cycle
time monitoring.
Default: 150 ms.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 231
User interfaces (API)
8.6 API IInstances

• INT64 in_MaxCycleTime_ns:
The user-specific value for the maximum cycle time monitoring.
A value between 1000000 and 60000000000 ns (1 millisecond to 1 minute) is valid. If no value is
specified in the API, the default value of 150 ms applies.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The cycle time monitoring mode is invalid.
SREC_INDEX_OUT_OF_RANGE The user-specific value for the maximum cycle time
monitoring is outside the limits.

Table 8-287 SetCycleTimeMonitoringMode() - .NET (C#)

Syntax void SetCycleTimeMonitoringMode(ECycleTimeMonitoringMode
in_CycleTimeMonitoringMode)
void SetCycleTimeMonitoringMode(ECycleTimeMonitoringMode
in_CycleTimeMonitoringMode, Int64 in_MaxCycleTime_ns)
Parameters • ECycleTimeMonitoringMode in_CycleTimeMonitoringMode:
Select one of the following options for the maximum cycle time monitoring:
– ECycleTimeMonitoringMode.Downloaded:
The maximum cycle time from the project that was downloaded from STEP 7 is used as maxim­
um cycle time monitoring.
– ECycleTimeMonitoringMode.Ignored (default):
A timer value of one minute is used as maximum cycle time monitoring to prevent a potential
error in case of an overflow of cyclic events.
See Monitoring overflow (Page 343).
– ECycleTimeMonitoringMode.Specified:
A value that is specified with the in_MaxCycleTime_ns parameter is used as maximum cycle
time monitoring.
Default: 150 ms.
• Int64 in_MaxCycleTime_ns:
The user-specific value for the maximum cycle time monitoring.
A value between 1000000 and 60000000000 ns (1 millisecond to 1 minute) is valid. If no value is
specified in the API, the default value of 150 ms applies.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The cycle time monitoring mode is invalid.
ERuntimeErrorCode.IndexOutOfRange The user-specific value for the maximum cycle time
monitoring is outside the limits.

S7-PLCSIM Advanced
232 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

GetCycleTimeMonitoringMode()
This function returns information on the source of the timer for the maximum cycle time
monitoring.
Table 8-288 GetCycleTimeMonitoringMode() - Native C++
Syntax ERuntimeErrorCode GetCycleTimeMonitoringMode(ECycleTimeMonitoringMode*
out_CycleTimeMonitoringMode, INT64* out_MaxCycleTime_ns)
Parameters • ECycleTimeMonitoringMode* out_CycleTimeMonitoringMode:
The configured mode for cycle time monitoring. The default setting is SRCTM_IGNORED.
• INT64 in_MaxCycleTime_ns:
The user-specific value for the maximum cycle time monitoring. If no value is specified in the API,
the default value of 150 ms is returned.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.

Table 8-289 GetCycleTimeMonitoringMode() - .NET (C#)

Syntax void GetCycleTimeMonitoringMode(out ECycleTimeMonitoringMode
out_CycleTimeMonitoringMode, out Int64 out_MaxCycleTime_ns)
Parameters • ECycleTimeMonitoringMode out_CycleTimeMonitoringMode:
The configured mode for cycle time monitoring. The default setting is
ECycleTimeMonitoringMode.Ignored.
• Int64 in_MaxCycleTime_ns:
The user-specific value for the maximum cycle time monitoring. If no value is specified in the API,
the default value of 150 ms is returned.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.8 Acyclic services

8.6.8.1 Overview

The acyclic services of PLCSIM Advanced include:

• Read and write processes of parameter and status data from the user program of the PLC
to the I/O modules
• Interrupt and event information which the I/O modules send to the CPU.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 233
User interfaces (API)
8.6 API IInstances

Read and write operations

Events triggered by the STEP 7 user program that have logged on for the notification:
Table 8-290 Events: Read and write operations
SFB Name API method (alarm) API event for triggering the SFB
52 RDREC ReadRecordDone (Page 235) OnDataRecordRead (Page 260)
53 WRREC WriteRecordDone (Page 235) OnDataRecordWrite (Page 260)

Flowchart

8VHU 3/&6,0 3/&6,0 $SSOLFDWLRQ

SURJUDP $GYDQFHG $GYDQFHG
$3,
&DOOEDFN0HWKRG
FunctionPointer
Callback Method
5HJLVWHUB(YHQW!BFEN ,QLWLDOL]DWLRQ3KDVH

2SHUDWLRQDO3KDVH
2%7ULJJHU

&DOOEDFN0HWKRG
2%LQ%XV\6WDWH

$3,0HWKRG

2%LQ'RQH6WDWH

Figure 8-4 Read and write operations flowchart

API methods and associated events

Events which are triggered by the I/O modules and associated API methods:
Table 8-291 API methods and associated events
OB Name API methods for triggering the OB API event after OB execution (alarm)
(query)
82 Diagnostic error Interrupt AlarmNotification (Page 237) OnAlarmNotificationDone (Page 261)
4x Hardware Interrupt ProcessEvent (Page 239) OnProcessEventDone (Page 262)
83 Pull or Plug of module PullOrPlugEvent (Page 240) OnPullOrPlugEventDone (Page 263)
55 Status StatusEvent (Page 241) OnStatusEventDone (Page 264)
57 Profile ProfileEvent (Page 242) OnProfileEventDone (Page 264)
56 Update UpdateEvent (Page 243) OnUpdateEventDone (Page 265)
86 Rack or station failure RackOrStationFaultEvent (Page 245) OnRackOrStationFaultEventDone (Page
266)

S7-PLCSIM Advanced
234 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Flowchart
Flowchart for the simulation of events which are triggered by the I/O modules.
8VHU 3/&6,0 3/&6,0 $SSOLFDWLRQ
SURJUDPP $GYDQFHG $GYDQFHG
$3,
&DOOEDFN0HWKRG
FunctionPointer
Callback Method
5HJLVWHUB(YHQW!BFEN ,QLWLDOL]DWLRQ3KDVH

2SHUDWLRQDO3KDVH
Input Parameters
$3,0HWKRG

2%([HFXWLRQ
Hardware ID
Status
&DOOEDFN0HWKRG

Figure 8-5 Flowchart for the simulation of events

8.6.8.2 ReadRecordDone/WriteRecordDone

ReadRecordDone()
With this API method, the simulation of an I/O module signals to the CPU that the
asynchronous reading of a data record has been completed. The simulation hereby makes the
read information available.
Table 8-292 ReadRecordDone() - Native C++
Syntax ERuntimeErrorCode ReadRecordDone(SDataRecordInfo in_RecordInfo, BYTE*
in_Data, UINT32 in_Status);
Parameters • SDataRecordInfo in_RecordInfo:
Structure which contains the data record information.
See SDataRecordInfo (Page 311).
• BYTE* in_Data:
Byte array of the read data record with the length defined by DataSize in the structure
SDataRecordInfo.
• UINT32 in_Status:
Status of the job execution
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_INDEX_OUT_OF_RANGE The byte array of the read data record exceeds the
length DDATARECORD_MAX_SIZE = 64000.
SREC_TIMEOUT The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 235
User interfaces (API)
8.6 API IInstances

Table 8-293 ReadRecordDone() - .NET (C#)

Syntax void ReadRecordDone(SDataRecordInfo in_RecordInfo, BYTE[] in_Data, UInt32
in_Status);
Parameters • SDataRecordInfo in_RecordInfo:
Structure which contains the data record information.
See SDataRecordInfo (Page 311).
• BYTE[] in_Data:
Byte array of the read data record with the length defined by DataSize in the structure
SDataRecordInfo.
• UInt32 in_Status:
Status of the job execution
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode.IndexOutOfRange The byte array of the read data record exceeds the
length DataRecordMaxSize = 64000.
ERuntimeErrorCode.Timeout The function does not return on time.

WriteRecordDone()
With this API method, the simulation of an I/O module signals to the CPU that the
asynchronous writing of a data record has been completed.
Table 8-294 WriteRecordDone() - Native C++
Syntax ERuntimeErrorCode WriteRecordDone(SDataRecordInfo in_RecordInfo, UINT32
in_Status);
Parameters • SDataRecordInfo in_RecordInfo:
Structure which contains the data record information.
See SDataRecordInfo (Page 311).
• UINT32 in_Status:
Status of the job execution
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_TIMEOUT The function does not return on time.

Table 8-295 WriteRecordDone() - .NET (C#)

Syntax void WriteRecordDone(SDataRecordInfo in_RecordInfo, UInt32 in_Status);
Parameters • SDataRecordInfo in_RecordInfo:
Structure which contains the data record information.
See SDataRecordInfo (Page 311).
• UInt32 in_Status:
Status of the job execution
Return values None

S7-PLCSIM Advanced
236 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode.Timeout The function does not return on time.

NOTE
Return values of a written data record
The return values of the status of a written data record in S7-PLCSIM Advanced can differ
from the return values of a real hardware CPU.

8.6.8.3 AlarmNotification

AlarmNotification()
This function triggers diagnostic alarms according to the PROFINET standard.
Each call of this function calls the diagnostic interrupt OB (OB 82) once, regardless of the
number and the severity level of the transferred diagnostic entries.
Table 8-296 AlarmNotification() - Native C++
Syntax ERuntimeErrorCode AlarmNotification(UINT16 in_HardwareIdentifier, UINT16
in_ModuleState, UINT16 in_NumberOfDiagnosisEvents,
SDiagExtChannelDescription* in_ArrayOfDiagnosisEvents, UINT16*
out_SequenceNumber);
Parameters • UINT16 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the diagnostics entry.
The identifier must belong to a hardware component in the currently loaded project.
• UINT16 in_ModuleState:
Module status. The following statuses are valid:
DMODULE_STATE_OK = 0,
DMODULE_STATE_ERROR = 1,
DMODULE_STATE_MAINT_DEMANDED = 2,
DMODULE_STATE_MAINT_REQUIRED = 4
The in_ModuleState parameter is derived from the sum (ORed) of the severity level in the
SDiagExtChannelDescription field. If a diagnostic interrupt should be generated for both
"Maintenance demanded" as well as "Maintenance required", select "6" as the module status.
• UINT16 in_NumberOfDiagnosisEvents:
Multiple diagnostic entries can be sent to the CPU with a single API call.
Valid range: 0 to 16. 0 means that no diagnostics entry should appear for the submodule or the
channel.
• SDiagExtChannelDescription* in_ArrayOfDiagnosisEvents:
Pointer to a field with diagnostic entries. The field must match the number of diagnostic entries. It
can also be a null pointer. For definitions, see SDiagExtChannelDescription (Page 312).
• UINT16* out_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 237
User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_MODULE_STATE The module is currently unplugged.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_WRONG_MODULE_TYPE The channel number does not exist for the module.
SREC_WRONG_ARGUMENT The value for the module status is invalid.
SREC_TIMEOUT The function does not return on time.

Table 8-297 AlarmNotification() - .NET (C#)

Syntax void AlarmNotification(ushort in_HardwareIdentifier, ushort
in_ModuleState, ushort in_NumberOfDiagnosisEvents,
SDiagExtChannelDescription [] in_ArrayOfDiagnosisEvents, Out ushort
out_SequenceNumber);
Parameters • ushort in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the diagnostics entry.
The identifier must belong to a hardware component in the currently loaded project.
• ushort in_ModuleState:
Module status. The following statuses are valid:
ModuleState.Ok = 0,
ModuleState.Error = 1,
ModuleState.MaintenanceDemanded = 2,
ModuleState.MaintenanceRequired = 4
The in_ModuleState parameter is derived from the sum (ORed) of the severity level in the
SDiagExtChannelDescription field.
If a diagnostic interrupt should be generated for both "Maintenance demanded" as well as "Main­
tenance required", select "6" as the module status.
• ushort in_NumberOfDiagnosisEvents
Multiple diagnostic entries can be sent to the CPU with a single API call.
Valid range: 0 to 16. 0 means that no diagnostics entry should appear for the submodule or the
channel.
• SDiagExtChannelDescription [] in_ArrayOfDiagnosisEvents:
Pointer to a field with diagnostic entries. The field must match the number of diagnostic entries. It
can also be a null pointer. For definitions, see SDiagExtChannelDescription (Page 312).
• Out ushort out_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each alarm event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.WrongModuleState The module is currently unplugged.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode.WrongArgument The value for the module status is invalid.
ERuntimeErrorCode.WrongModuleType The channel number does not exist for the module.
ERuntimeErrorCode.Timeout The function does not return on time.

S7-PLCSIM Advanced
238 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Example ushort seqNumber;

var In_ArrayOfDiagnosisEvent = new SDiagExtChannelDescription[] {
new SDiagExtChannelDescription() {ChannelNumber = 0x8000, ErrorType =
0x0001,
ExtErrorType = 0, Direction = EDiagProperty.Appear,Severity
=EDiagSeverity.MaintDemanded},

new SDiagExtChannelDescription() {ChannelNumber = 0x8000, ErrorType =

0x0002,
ExtErrorType = 0, Direction = EDiagProperty.Appear,Severity
=EDiagSeverity.Failure},

new SDiagExtChannelDescription() {ChannelNumber = 0x8000, ErrorType =

0x0003,
ExtErrorType = 0, Direction = EDiagProperty.Appear,Severity
=EDiagSeverity.MaintRequired},

Instance.AlarmNotification(269, 7, 3, In_ArrayOfDiagnosisEvent, out

seqNumber);
//ModuleState parameter is sum of the severities in the
SDiagExtChannelDescription array above: 4+2+1

8.6.8.4 ProcessEvent

ProcessEvent()
Process events from central and distributed input modules can be simulated with this
function.
Table 8-298 ProcessEvent() - Native C++
Syntax ERuntimeErrorCode ProcessEvent(UINT16 in_HardwareIdentifier, UINT16
in_Channel, EProcessEventType in_ProcessEventType, UINT16*
out_SequenceNumber);
Parameters • UINT16 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the process event.
The identifier must belong to a hardware component in the currently loaded project.
• UINT16 in_Channel:
The channel of the I/O module which sends the process event.
• EProcessEventType in_ProcessEventType:
A value from the list of predefined types of events for S7 modules, see EProcessEventType (Page
331).
• UINT16* out_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_MODULE_STATE The module is currently unplugged.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_NOT_SUPPORTED_BY_MODULE The module is not supported by this user action.
SREC_TIMEOUT The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 239
User interfaces (API)
8.6 API IInstances

Table 8-299 ProcessEvent() - .NET (C#)

Syntax void ProcessEvent(ushort in_HardwareIdentifier, ushort in_Channel,
EProcessEventType in_ProcessEventType, Out ushort out_SequenceNumber);
Parameters • ushort in_HardwareIdentifier:
The hardware identifier of the module or submodule which generates the process event.
The identifier must belong to a hardware component in the currently loaded project.
• ushort in_Channel:
The channel of the I/O module which generates the process event.
• EProcessEventType in_ProcessEventType:
A value from the list of predefined types of events for S7 modules, see EProcessEventType (Page
331).
• Out ushort out_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.WrongModuleState The module is currently unplugged.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode. The module is not supported by this user action.
NotSupportedByModule
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.8.5 PullOrPlugEvent

PullOrPlugEvent()
This function triggers pull/plug events. The interrupt OB (OB 83) "Pull or plug of modules" is
executed for these events.

NOTE
Removing and inserting head modules of distributed I/O systems
In contrast to real systems, S7-PLCSIM Advanced allows the removal and insertion of head
modules in distributed I/O systems.

Table 8-300 PullOrPlugEvent() - Native C++

Syntax ERuntimeErrorCode PullOrPlugEvent(UINT16 in_HardwareIdentifier,
EPullOrPlugEventType in_PullOrPlugEventType, UINT16* out_SequenceNumber);
Parameters • UINT16 in_HardwareIdentifier:
The hardware identifier of the module or submodule which generates the pull/plug event.
The identifier must belong to a hardware component in the currently loaded project.
• EPullOrPlugEventType in_PullOrPlugEventType:
A value from the list of predefined types of pull/plug events, see EPullOrPlugEventType (Page 331).
• UINT16* out_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.

S7-PLCSIM Advanced
240 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_MODULE_STATE The module is currently unplugged.
SREC_WRONG_MODULE_TYPE The wrong module type was selected, e.g. if an
onboard I/O of a compact CPU is to be pulled.
SREC_NOT_SUPPORTED_BY_MODULE The module is not supported by this user action.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_TIMEOUT The function does not return on time.

Table 8-301 PullOrPlugEvent() - .NET (C#)

Syntax void PullOrPlugEvent(ushort in_HardwareIdentifier, EPullOrPlugEventType
in_PullOrPlugEventType, Out ushort out_SequenceNumber);
Parameters • ushort in_HardwareIdentifier:
The hardware identifier of the module or submodule which generates the pull/plug event.
The identifier must belong to a hardware component in the currently loaded project.
• EPullOrPlugEventType in_PullOrPlugEventType:
A value from the list of predefined types of pull/plug events, see EPullOrPlugEventType (Page 331).
• Out ushort out_SequenceNumber
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.WrongModuleState The module is currently unplugged.
ERuntimeErrorCode.WrongModuleType The wrong module type was selected, e.g. if an
onboard I/O of a compact CPU is to be pulled.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode. The module is not supported by this user action.
NotSupportedByModule
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.8.6 StatusEvent

StatusEvent()
This function is used to trigger the status event OB (OB 55). Status events are only supported
for modules in a distributed I/O system.
Table 8-302 StatusEvent() - Native C++
Syntax ERuntimeErrorCode StatusEvent(UINT16 in_HardwareIdentifier, UINT16
in_Specifier);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 241
User interfaces (API)
8.6 API IInstances

Parameters • UINT16 in_HardwareIdentifier:

The hardware identifier of the module that generates the status event.
The identifier must belong to a hardware component in the currently loaded project.
• UINT16 in_Specifier:
The parameter is transferred to the interrupt frame as interrupt specifier. It is available as input
parameter of the OB 55 call.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_MODULE_STATE The module is currently unplugged.
SREC_NOT_SUPPORTED_BY_MODULE The module is not supported by this user action.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_TIMEOUT The function does not return on time.

Table 8-303 StatusEvent() - .NET (C#)

Syntax void StatusEvent(ushort in_HardwareIdentifier, ushort in_Specifier);
Parameters • ushort in_HardwareIdentifier:
The hardware identifier of the module that generates the status event.
The identifier must belong to a hardware component in the currently loaded project.
• ushort in_Specifier:
The parameter is transferred to the interrupt frame as interrupt specifier. It is available as input
parameter of the OB 55 call.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.WrongModuleState The module is currently unplugged.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode. The module is not supported by this user action.
NotSupportedByModule
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.8.7 ProfileEvent

ProfileEvent()
This function is used to trigger the Profile event OB (OB 57). Profile events are only supported
for modules in a distributed I/O system.
Table 8-304 ProfileEvent() - Native C++
Syntax ERuntimeErrorCode ProfileEvent(UINT16 in_HardwareIdentifier, UINT16
in_Specifier);

S7-PLCSIM Advanced
242 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Parameters • UINT16 in_HardwareIdentifier:

The hardware identifier of the module that generates the profile event.
The identifier must belong to a hardware component in the currently loaded project.
• UINT16 in_Specifier:
The parameter is transferred to the interrupt frame as interrupt specifier. It is available as input
parameter of the OB 57 call.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_MODULE_STATE The module is currently unplugged.
SREC_NOT_SUPPORTED_BY_MODULE The module is not supported by this user action.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_TIMEOUT The function does not return on time.

Table 8-305 ProfileEvent() - .NET (C#)

Syntax void ProfileEvent(ushort in_HardwareIdentifier, ushort in_Specifier);
Parameters • ushort in_HardwareIdentifier:
The hardware identifier of the module that generates the profile event.
The identifier must belong to a hardware component in the currently loaded project.
• ushort in_Specifier:
The parameter is transferred to the interrupt frame as interrupt specifier. It is available as input
parameter of the OB 57 call.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.WrongModuleState The module is currently unplugged.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode. The module is not supported by this user action.
NotSupportedByModule
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.8.8 UpdateEvent

UpdateEvent()
This function is used to trigger the Update event OB (OB 56). Update events are only
supported for modules in a distributed I/O system.
Table 8-306 UpdateEvent() - Native C++
Syntax ERuntimeErrorCode UpdateEvent(UINT16 in_HardwareIdentifier, UINT16
in_Specifier);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 243
User interfaces (API)
8.6 API IInstances

Parameters • UINT16 in_HardwareIdentifier:

The hardware identifier of the module that triggers the update event.
The identifier must belong to a hardware component in the currently loaded project.
• UINT16 in_Specifier:
The parameter is transferred to the interrupt frame as interrupt specifier. It is available as input
parameter of the OB 56 call.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_MODULE_STATE The module is currently unplugged.
SREC_NOT_SUPPORTED_BY_MODULE The module is not supported by this user action.
SREC_DOES_NOT_EXIST No hardware identifier of the module.
SREC_TIMEOUT The function does not return on time.

Table 8-307 UpdateEvent() - .NET (C#)

Syntax void UpdateEvent(ushort in_HardwareIdentifier, ushort in_Specifier);
Parameters • ushort in_HardwareIdentifier:
The hardware identifier of the module that triggers the update event.
The identifier must belong to a hardware component in the currently loaded project.
• ushort in_Specifier:
The parameter is transferred to the interrupt frame as interrupt specifier. It is available as input
parameter of the OB 56 call.
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.WrongModuleState The module is currently unplugged.
ERuntimeErrorCode.DoesNotExist No hardware identifier of the module.
ERuntimeErrorCode. The module is not supported by this user action.
NotSupportedByModule
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.8.9 GetConfiguredProcessEvent

GetConfiguredProcessEvents()
With this API method, the process events configured in the TIA Portal can be read out during
runtime.
If no process events are present, SREC_OK is returned. The value for EventsCount is then 0.
Table 8-308 GetConfiguredProcessEvents() - Native C++
Syntax ERuntimeErrorCode GetConfiguredProcessEvents(UINT16* out_EventsCount,);

S7-PLCSIM Advanced
244 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Parameters • SConfiguredProcessEvents* inout_ProcessEvents:

Pointer or reference to a user-defined memory which contains the field with the downloaded con­
figured process events. The structure SConfiguredProcessEvents (Page 312) contains information
about these process events.
• UINT16* out_EventsCount:
Pointer or reference to a tag which contains the number of configured process events.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_TIMEOUT The function does not return on time.

Table 8-309 GetConfiguredProcessEvents() - .NET (C#)

Syntax SConfiguredProcessEvents [] GetConfiguredProcessEvents();
Parameters None
Return values Field with configured process events and field size provide the number of configured process events.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

8.6.8.10 RackOrStationFaultEvent

Description
This function is used to trigger the RackOrStationFault event OB (OB 86). These events are
only supported for distributed devices.
Table 8-310 RackOrStationFaultEvent() - Native C++
Syntax ERuntimeErrorCode RackOrStationFaultEvent(UINT16 in_HardwareIdentifier,
ERackOrStationFaultType in_EventType);
Parameter • UINT16 in_HardwareIdentifier:
The hardware identifier of the device that sends the event. Use the hardware identifier of the
Hw_Device type.
• ERackOrStationFaultType in_EventType:
A value from the list of predefined types of events, see ERackOrStationFaultType (Page 333).
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The instance is not registered in Runtime Manager.
SREC_WRONG_MODULE_TYPE The specified HW identifier is not that of a distrib­
uted device.
SREC_WRONG_MODULE_STATE The device with the specified HW identifier already
reports the status Fault/Return.
SREC_DOES_NOT_EXIST The specified HW identifier of the device does not
exist.
SREC_TIMEOUT The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 245
User interfaces (API)
8.6 API IInstances

Table 8-311 RackOrStationFaultEvent() - .NET (C#)

Syntax void RackOrStationFaultEvent(ushort in_HardwareIdentifier,
ERackOrStationFaultType in_EventType);
Parameter • ushort in_HardwareIdentifier:
The hardware identifier of the device that sends the event. Use the hardware identifier of the
Hw_Device type.
• ERackOrStationFaultType in_EventType:
A value from the list of predefined types of events, see ERackOrStationFaultType (Page 333).
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The instance is not registered in Runtime Manager.
ERuntimeErrorCode.DoesNotExist The specified HW identifier of the device does not
exist.
ERuntimeErrorCode.WrongModuleType The specified HW identifier is not that of a distrib­
uted device.
ERuntimeErrorCode.WrongModuleState The device with the specified HW identifier already
reports the status Fault/Return.
ERuntimeErrorCode.Timeout The function does not return on time.

More information
You can find more information on the HW identifier in the STEP 7 online help.

8.6.9 Events for IInstances

8.6.9.1 Events for operating state and cycle control

The following events are triggered for the IInstances interface:

Table 8-312 Events for IInstances
Event Cause
OnOperatingStateChanged (Page The operating state of the virtual controller has changed.
247)
OnLedChanged (Page 250) The LED display of the virtual controller has changed.
OnSoftwareConfigurationChanged The configuration of the virtual controller changes:
(Page 252) • During power up from the Virtual SIMATIC Memory Card
• At the start of a download
When this event is triggered, the stored tag list is reset.
The configuration of the virtual controller has changed:
• After power up from the Virtual SIMATIC Memory Card
• At the end of a download
• When the IP address changes
OnSyncPointReached (Page 255) The virtual controller has reached a synchronization point.
If the virtual controller is being operated in Default mode, the
SendSyncEventInDefaultMode flag must be set to receive the event. See Send­
SyncEventInDefaultMode (Page 226).

S7-PLCSIM Advanced
246 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Event Cause
OnHardwareConfigChanged (Page When the hardware configuration of the virtual controller has changed, the event is
258) triggered at the following times:
• After power up from the Virtual SIMATIC Memory Card
• During the Hardware Config download

OnOperatingStateChanged
Registers or unregisters an event handler method.
Table 8-313 OnOperatingStateChanged - .NET (C#)
Syntax event Delegate_II_EREC_DT_EOS_EOS OnOperatingStateChanged;
Parameters None. See Delegate_II_EREC_DT_EOS_EOS (Page 291).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnOperatingStateChangedCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-314 RegisterOnOperatingStateChangedCallback() - Native C++
Syntax void
RegisterOnOperatingStateChangedCallback
(EventCallback_II_SREC_ST_SROS_SROS in_CallbackFunction);
Parameters • EventCallback_II_SREC_ST_SROS_SROS in_CallbackFunction:
A callback function that subscribes to the event.
See EventCallback_II_SREC_ST_SROS_SROS (Page 283).
Return values None
Note The callback function runs in a separate thread.

RegisterOnOperatingStateChangedEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registering a new event object causes the
previous event object to be deleted.
Table 8-315 RegisterOnOperatingStateChangedEvent() - Native C++
Syntax void RegisterOnOperatingStateChangedEvent();
void RegisterOnOperatingStateChangedEvent(HANDLE* in_Event);
Parameters • None:
An internal event object is registered.
• HANDLE* in_Event:
A handle for a user-specific event object. The event object is registered.
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 247
User interfaces (API)
8.6 API IInstances

Example C++ // Thread 1 --------------------------------------------------

ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IInstance* psa = NULL;

if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}

// Register the internal event object

psa->RegisterOnOperatingStateChangedEvent();

// Thread 2 --------------------------------------------------
while (condition)
{
// Wait for the event to be set (timeout after 10s)
bool isEventSet = psa->WaitForOnOperatingStateChangedEvent(10000);
if (isEventSet)
{
// Do Something
…
}
}
Example C++ // Thread 1 --------------------------------------------------
ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IInstance* psa = NULL;

if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}

// Create an event object

HANDLE eventHandle = CreateEvent(NULL, FALSE, FALSE, NULL);

// Register the user created event object

psa->RegisterOnOperatingStateChangedEvent(&eventHandle);

// Do Something
…
// Clean up the handle
CloseHandle(eventHandle);

// Thread 2 --------------------------------------------------
while (condition)
{
// Wait for the event to be set //OR:
WaitForSingleObject(eventHandle, INFINITE); //psa-
>WaitForOnOperatingStateChangedEvent();

// Do Something
…
}

Table 8-316 RegisterOnOperatingStateChangedEvent() – .NET (C#)

Syntax void RegisterOnOperatingStateChangedEvent();
Parameters None
Return values None

S7-PLCSIM Advanced
248 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

UnregisterOnOperatingStateChangedCallback()
Unregisters the callback function.
Table 8-317 UnregisterOnOperatingStateChangedCallback() - Native C++
Syntax void
UnregisterOnOperatingStateChangedCallback
(EventCallback_II_SREC_ST_SROS_SROS in_CallbackFunction = nullptr);
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

UnregisterOnOperatingStateChangedEvent()
Unregisters the event object.
Table 8-318 UnregisterOnOperatingStateChangedEvent() - Native C++
Syntax void UnregisterOnOperatingStateChangedEvent();
Parameters None
Return values None

Table 8-319 UnregisterOnOperatingStateChangedEvent() - .NET (C#)

Syntax void UnregisterOnOperatingStateChangedEvent();
Parameters None
Return values None

WaitForOnOperatingStateChangedEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 8-320 WaitForOnOperatingStateChangedEvent() - Native C++
Syntax bool WaitForOnOperatingStateChangedEvent();
bool WaitForOnOperatingStateChangedEvent(UINT32 in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

Table 8-321 WaitForOnOperatingStateChangedEvent() - .NET (C#)

Syntax bool WaitForOnOperatingStateChangedEvent();
bool WaitForOnOperatingStateChangedEvent(UInt32 in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UInt32 in_Time_ms:
Value for the time limit in milliseconds.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 249
User interfaces (API)
8.6 API IInstances

Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

OnLedChanged
Registers or unregisters an event handler method.
Table 8-322 OnLedChanged - .NET (C#)
Syntax event Delegate_II_EREC_DT_ELT_ELM OnLedChanged;
Parameters None. See Delegate_II_EREC_DT_ELT_ELM (Page 292).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnLedChangedCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-323 RegisterOnLedChangedCallback() - Native C++
Syntax void RegisterOnLedChangedCallback(EventCallback_II_SREC_ST_SRLT_SRLM
in_CallbackFunction);
Parameters • EventCallback_II_SREC_ST_SRLT_SRLM in_CallbackFunction:
A callback function that subscribes to an event.
See EventCallback_II_SREC_ST_SRLT_SRLM (Page 285).
Return values None
Note The callback function runs in a separate thread.

RegisterOnLedChangedEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registering a new event object causes the
previous event object to be deleted.
Table 8-324 RegisterOnLedChangedEvent() - Native C++
Syntax void RegisterOnLedChangedEvent();
void RegisterOnLedChangedEvent(HANDLE* in_Event);
Parameters • None:
An internal event object is registered.
• HANDLE* in_Event:
A handle for a user-specific event object. The event object is registered.
Return values None

Table 8-325 RegisterOnLedChangedEvent() – .NET (C#)

Syntax void RegisterOnLedChangedEvent();
Parameters None

S7-PLCSIM Advanced
250 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values None

UnregisterOnLedChangedCallback()
Unregisters the callback function.
Table 8-326 UnregisterOnLedChangedCallback() - Native C++
Syntax void UnregisterOnLedChangedCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

UnregisterOnLedChangedEvent()
Unregisters the event object.
Table 8-327 UnregisterOnLedChangedEvent() - Native C++
Syntax void UnregisterOnLedChangedEvent();
Parameters None
Return values None

Table 8-328 UnregisterOnLedChangedEvent() - .NET (C#)

Syntax void UnregisterOnLedChangedEvent();
Parameters None
Return values None

WaitForOnLedChangedEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 8-329 WaitForOnLedChangedEvent() - Native C++
Syntax bool WaitForOnLedChangedEvent();
bool WaitForOnLedChangedEvent(UINT32 in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

Table 8-330 WaitForOnLedChangedEvent() - .NET (C#)

Syntax bool WaitForOnLedChangedEvent();
bool WaitForOnLedChangedEvent(UInt32 in_Time_ms);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 251
User interfaces (API)
8.6 API IInstances

Parameters • None:
The time limit is set to INFINITE.
• UInt32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

OnSoftwareConfigurationChanged()
Reports software changes in STOP and RUN modes.
Table 8-331 OnSoftwareConfigurationChanged
Syntax event Delegate_SRSCC OnSoftwareConfigurationChanged();
Parameters IInstance, ERuntimeErrorCode, SYSTEMTIME, ESoftwareConfigChanged
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnSoftwareConfigurationChangedCallback()
When the event occurs, the registered callback function is called. Only one callback function
can be registered for the event. The registration of a new callback function causes the
previous callback function to be deleted.
Table 8-332 RegisterOnSoftwareConfigurationChangedCallback() - Native C++
Syntax void RegisterOnSoftwareConfigurationChangedCallback();
Parameters CallbackFunction
Return values None
Note The event handler method runs in a separate thread.

RegisterOnSoftwareConfigurationChangedEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registration of a new event object causes the
previous event object to be deleted.
Table 8-333 RegisterOnSoftwareConfigurationChangedEvent() - Native C++
Syntax void RegisterOnSoftwareConfigurationChangedEvent();
Parameters • None
An internal event object is registered.
• HANDLE*
A handle for a user-specific event object. The event object is registered.
Return values None

S7-PLCSIM Advanced
252 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

UnregisterOnSoftwareConfigurationChangedCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 8-334 UnregisterOnSoftwareConfigurationChangedCallback() - Native C++
Syntax void UnregisterOnSoftwareConfigurationChangedCallback();
Parameters None
Return values None

UnregisterOnConfigurationChangedEvent()
Unregisters the event object.
Table 8-335 UnregisterOnConfigurationChangedEvent() - Native C++
Syntax void UnregisterOnSoftwareConfigurationChangedEvent();
Parameters None
Return values None

Table 8-336 UnregisterOnConfigurationChangedEvent() - .NET (C#)

Syntax void UnregisterOnSoftwareConfigurationChangedEvent();
Parameters None
Return values None

WaitForOnConfigurationChangedEvent()
The function blocks the program until the registered event object is set to the signaled state
or the timeout interval is exceeded.
Table 8-337 WaitForOnSoftwareConfigurationChangedEvent() - Native C++
Syntax void WaitForOnSoftwareConfigurationChangedEvent();
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.
Note The function blocks the CoSimulation program until a software download is set to the signaled state
or the timeout interval is exceeded.

Table 8-338 WaitForOnSoftwareConfigurationChangedEvent() - .NET (C#)

Syntax void WaitForOnSoftwareConfigurationChangedEvent();
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 253
User interfaces (API)
8.6 API IInstances

Note The function blocks the CoSimulation program until a software download is set to the signaled state
or the timeout interval is exceeded.

RegisterOnIPAddressChangedCallback()
Register function for receiving callback functions when an IP address has changed.
Table 8-339 RegisterOnIPAddressChangedCallback() - Native C++
Syntax RegisterOnIPAddressChangedCallback();
Parameters • IInstance* in_Sender Instance object
in_CallbackFuncti- • ERuntimeErrorCode in_ErrorCode Result of operation
on • SYSTEMTIME in_SystemTime CPU system time of the event
• UINT8 in_InterfaceId ID of the CPU interface involved
• const SIPSuite4& in_SIP Reference of the SIPSuite4 structure
Return values None
Note The event handler method runs in a separate thread.

UnregisterOnIPAddressChangedCallback()
Unregister function for receiving callback functions when an IP address has changed.
Table 8-340 UnregisterOnIPAddressChangedCallback() - Native C++
Syntax void UnregisterOnIPAddressChangedCallback();
Parameters Address of the specific function or nullptr for removing the last registered callback function
in_CallbackFuncti-
on
Return values None

RegisterOnIPAddressChangedEvent()
Register function for receiving events when an IP address has changed.
Table 8-341 RegisterOnIPAddressChangedEvent() - Native C++
Syntax void IInstance::RegisterOnIPAddressChangedEvent()
void IInstance::RegisterOnIPAddressChangedEvent(HANDLE* in_Event);
Parameters HANDLE* (a user-specific event object is registered)
in_Event
Return values None

UnregisterOnIPAddressChangedEvent()
Unregister function for receiving events when an IP address has changed.
Table 8-342 UnregisterOnIPAddressChangedEvent() - Native C++
Syntax void IInstance::UnregisterOnIPAddressChangedEvent();
Parameters None

S7-PLCSIM Advanced
254 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values None

OnIPAddressChanged()
The event is called when the IP configuration of the CPU interface has changed.
Table 8-343 OnIPAddressChanged() - .NET (C#)
Syntax void IInstance::OnIPAddressChanged();
Parameters • IInstance in_Sender Instance object
• ERuntimeErrorCode in_ErrorCode Result of operation
• DateTime in_SystemTime CPU system time of the event
• UINT8 in_InterfaceId ID of the CPU interface involved
• SIPSuite4 in_SIP IP address of the interface
Return values None
Note The event handler method runs in a separate thread.

WaitForOnIPAddressChangedEvent()
Blocking function up to the change of the IP address.
Table 8-344 WaitForOnIPAddressChangedEvent() - Native C++
Syntax bool IInstance::WaitForOnIPAddressChangedEvent();
bool IInstance::WaitForOnIPAddressChangedEvent(UINT32 in_Time_ms)
Parameters Time in milliseconds
in_Time_ms
Return values Returns True if the change was made within a set period, otherwise False
Note None

Table 8-345 WaitForOnIPAddressChangedEvent() - .NET (C#)

Syntax bool IInstance::WaitForOnIPAddressChangedEvent();
bool IInstance::WaitForOnIPAddressChangedEvent(uint in_Time_ms);
Parameters Time in milliseconds
in_Time_ms
Return values Returns True if the change was made within a set period, otherwise False
Note The event handler method runs in a separate thread.

OnSyncPointReached
Registers or unregisters an event handler method.
Table 8-346 OnSyncPointReached - .NET (C#)
Syntax event Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32 OnSyncPointReached;
Parameters None. See Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32 (Page 292).

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 255
User interfaces (API)
8.6 API IInstances

Return values None

Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnSyncPointReachedCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-347 RegisterOnSyncPointReachedCallback() - Native C++
Syntax void
RegisterOnSyncPointReachedCallback
(EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32
in_CallbackFunction);
Parameters • EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32
in_CallbackFunction:
A callback function that subscribes to an event.
See EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32 (Page 284).
Return values None
Note The callback function runs in a separate thread.

RegisterOnSyncPointReachedEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registering a new event object causes the
previous event object to be deleted.
Table 8-348 RegisterOnSyncPointReachedEvent() - Native C++
Syntax void RegisterOnSyncPointReachedEvent();
void RegisterOnSyncPointReachedEvent(HANDLE* in_Event);
Parameters • None:
An internal event object is registered.
• HANDLE* in_Event:
A handle for a user-specific event object. The event object is registered.
Return values None

Table 8-349 RegisterOnSyncPointReachedEvent() – .NET (C#)

Syntax RegisterOnSyncPointReachedEvent() – .NET (C#)
Parameters None
Return values None

S7-PLCSIM Advanced
256 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

UnregisterOnSyncPointReachedCallback()
Unregisters the callback function.
Table 8-350 UnregisterOnSyncPointReachedCallback() - Native C++
Syntax void UnregisterOnSyncPointReachedCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

UnregisterOnSyncPointReachedEvent()
Unregisters the event object.
Table 8-351 UnregisterOnSyncPointReachedEvent() - Native C++
Syntax void UnregisterOnSyncPointReachedEvent();
Parameters None
Return values None

Table 8-352 UnregisterOnSyncPointReachedEvent() - .NET (C#)

Syntax void UnregisterOnSyncPointReachedEvent();
Parameters None
Return values None

WaitForOnSyncPointReachedEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 8-353 WaitForOnSyncPointReachedEvent() - Native C++
Syntax SOnSyncPointReachedResult WaitForOnSyncPointReachedEvent();
SOnSyncPointReachedResult WaitForOnSyncPointReachedEvent(UINT32
in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • SOnSyncPointReachedResult:
A structure that supplies information about the event.
See SOnSyncPointReachedResult (Page 309).

Table 8-354 WaitForOnSyncPointReachedEvent() - .NET (C#)

Syntax SOnSyncPointReachedResult WaitForOnSyncPointReachedEvent();
SOnSyncPointReachedResult WaitForOnSyncPointReachedEvent(UInt32
in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UInt32 in_Time_ms:
Value for the time limit in milliseconds.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 257
User interfaces (API)
8.6 API IInstances

Return values • SOnSyncPointReachedResult:

A structure that supplies information about the event.
See SOnSyncPointReachedResult (Page 309).

OnHardwareConfigChanged
Registers or unregisters an event handler method.
Table 8-355 OnHardwareConfigChanged - .NET (C#)
Syntax event Delegate_II_EREC_DT OnHardwareConfigChanged;
Parameters None; see Delegate_II_EREC_DT
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnHardwareConfigChangedCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-356 Table: RegisterOnHardwareConfigChangedCallback() – Native C++
Syntax void RegisterOnHardwareConfigChangedCallback(EventCallback_II_SREC_ST
in_CallbackFunction);
Parameters EventCallback_II_SREC_ST in_CallbackFunction
A callback function that subscribes to an event; see EventCallback_II_SREC_ST()
Return values None
Note The callback function runs in a separate thread.

RegisterOnHardwareConfigChangedEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registration of a new event object causes the
previous event object to be deleted.
Table 8-357 RegisterOnHardwareConfigChangedEvent() – Native C++
Syntax void RegisterOnHardwareConfigChangedEvent();
void RegisterOnHardwareConfigChangedEvent(Handle* in_Event);
Parameters • None:
An internal event object is registered.
• Handle* in_Event
A handle for a user-specific event object. The event object is registered.
Return values None

Table 8-358 RegisterOnHardwareConfigChangedEvent() – .NET (C#)

Syntax void RegisterOnHardwareConfigChangedEvent();
Parameters None

S7-PLCSIM Advanced
258 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Return values None

UnregisterOnHardwareConfigChangedCallback()
UnregisterOnHardwareConfigChangedCallback()Unregisters the callback function.
Table 8-359 UnregisterOnHardwareConfigChangedCallback() – Native C++
Syntax void UnregisterOnHardwareConfigChangedCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

UnregisterOnHardwareConfigChangedEvent()
Unregisters the event object.
Table 8-360 UnregisterOnHardwareConfigurationChangedEvent() – Native C++
Syntax void UnregisterOnHardwareConfigChangedEvent();
Parameters None
Return values None

Table 8-361 UnregisterOnHardwareConfigurationChangedEvent() – .NET (C#)

Syntax void UnregisterOnHardwareConfigChangedEvent();
Parameters None
Return values None

WaitForOnHardwareConfigurationChangedEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 8-362 WaitForOnHardwareConfigChangedEvent() – Native C++
Syntax bool WaitForOnHardwareConfigChangedEvent();
bool WaitForOnHardwareConfigChangedEvent (in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

Table 8-363 WaitForOnHardwareConfigChangedEvent() – .NET (C#)

Syntax bool WaitForOnHardwareConfigChangedEvent();
bool WaitForOnHardwareConfigChangedEvent (UINT32 in_Time_ms);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 259
User interfaces (API)
8.6 API IInstances

Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

8.6.9.2 Events for acyclic services

OnDataRecordRead
Registers or unregisters an event handler method.
Table 8-364 OnDataRecordRead - .NET (C#)
Syntax event Delegate_II_EREC_DT_SDRI OnDataRecordRead;
Parameter None. See Delegate_II_EREC_DT_SDRI (Page 294).
Return values None
Exceptions None
Note The Event-Handler Methode runs in a separate thread.

OnDataRecordWrite
Registers or unregisters an event handler method.
Table 8-365 OnDataRecordWrite - .NET (C#)
Syntax event Delegate_II_EREC_DT_SDR OnDataRecordWrite;
Parameter None. See Delegate_II_EREC_DT_SDR (Page 294).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnDataRecordReadCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-366 RegisterOnDataRecordReadCallback() - Native C++
Syntax void RegisterOnDataRecordReadCallback (Event Callback_II_SREC_ST_SDRI
in_CallbackFunction);
Parameters • EventCallback_II_SREC_ST_SDRI in_CallbackFunction:
A callback function that subscribes to the event.
See EventCallback_II_SREC_ST_SDRI.
Return values None
Note The callback function runs in a separate thread.

S7-PLCSIM Advanced
260 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

UnregisterOnDataRecordReadCallback()
Unregisters the callback function.
Table 8-367 UnregisterOnDataRecordReadCallback() - Native C++
Syntax void UnregisterOnDataRecordReadCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

RegisterOnDataRecordWriteCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-368 RegisterOnDataRecordWriteCallback() - Native C++
Syntax void RegisterOnDataRecordWriteCallback
(EventCallback_II_SREC_ST_SDRI_BYTE in_CallbackFunction);
Parameters • EventCallback_II_SREC_ST_SDRI_BYTE in_CallbackFunction:
A callback function that subscribes to the event.
See EventCallback_II_SREC_ST_SDRI_BYTE.
Return values None
Note The callback function runs in a separate thread.

UnregisterOnDataRecordWriteCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 8-369 UnregisterOnDataRecordWriteCallback() - Native C++
Syntax void UnregisterOnDataRecordWriteCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

OnAlarmNotificationDone()
Registers or unregisters an event handler method.
Table 8-370 OnAlarmNotificationDone() - .NET (C#)
Syntax event Delegate_SREC_ST_UINT32_UINT32 OnAlarmNotificationDone;
Parameters None. See Delegate_SREC_ST_UINT32_UINT32 (Page 296).
Return values None
Exceptions None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 261
User interfaces (API)
8.6 API IInstances

Note The event handler method runs in a separate thread.

RegisterOnAlarmNotificationDoneCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-371 RegisterOnAlarmNotificationDoneCallback() - Native C++
Syntax void RegisterOnAlarmNotificationDoneCallback (Event
Callback_II_SREC_ST_SDRI in_CallbackFunction);
Parameters • EventCallback_II_SREC_ST_UINT32_UINT32 in_CallbackFunction:
A callback function that subscribes to the event.
See EventCallback_II_SREC_ST_UINT32_UINT32 (Page 287).
Return values None
Note The callback function runs in a separate thread.

UnregisterOnAlarmNotificationDoneCallback()
Unregisters the callback function.
Table 8-372 UnregisterOnAlarmNotificationDoneCallback() - Native C++
Syntax void UnregisterOnAlarmNotificationDoneCallback ();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

OnProcessEventDone()
Registers or unregisters an event handler method.
Table 8-373 OnProcessEventDone() - .NET (C#)
Syntax event Delegate_SREC_ST_UINT32_UINT32_EPET_UINT32 OnProcessEventDone;
Parameters None. See Delegate_SREC_ST_UINT32_UINT32_EPET_UINT32. (Page 295)
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnProcessEventDoneCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-374 RegisterOnProcessEventDoneCallback() - Native C++
Syntax void RegisterOnProcessEventDoneCallback
(EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32
in_CallbackFunction);

S7-PLCSIM Advanced
262 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

Parameters EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32 in_CallbackFunction:

A callback function that subscribes to the event.
See EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32 (Page 287)
Return values None
Note The callback function runs in a separate thread.

UnregisterOnProcessEventDoneCallback()
Unregisters the callback function.
Table 8-375 UnregisterOnProcessEventDoneCallback() - Native C++
Syntax void UnregisterOnProcessEventDoneCallback ();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

OnPullOrPlugEventDone()
Registers or unregisters an event handler method.
Table 8-376 OnPullOrPlugEventDone() - .NET (C#)
Syntax event Delegate_SREC_ST_UINT32_EPPET_UINT32 OnPullOrPlugEventDone;
Parameters None. See Delegate_SREC_ST_UINT32_EPPET_UINT32 (Page 295).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnPullOrPlugEventDoneCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-377 RegisterOnPullOrPlugEventDoneCallback() - Native C++
Syntax void RegisterOnPullOrPlugEventDoneCallback
(EventCallback_II_SREC_ST_UINT32_EPPET_UINT32 in_CallbackFunction);
Parameters EventCallback_II_SREC_ST_UINT32_EPPET_UINT32 in_CallbackFunction:
A callback function that subscribes to the event.
See EventCallback_II_SREC_ST_UINT32_EPPET_UINT32 (Page 288).
Return values None
Note The callback function runs in a separate thread.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 263
User interfaces (API)
8.6 API IInstances

UnregisterOnPullOrPlugEventDoneCallback()
Unregisters the callback function.
Table 8-378 UnregisterOnPullOrPlugEventDoneCallback() - Native C++
Syntax void UnregisterOnPullOrPlugEventDoneCallback ();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

OnStatusEventDone()
Registers or unregisters an event handler method.
Table 8-379 OnStatusEventDone() - .NET (C#)
Syntax event Delegate_SREC_ST_UINT32 OnStatusEventDone;
Parameters None. See Delegate_SREC_ST_UINT32 (Page 296).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnStatusEventDoneCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-380 RegisterOnStatusEventDoneCallback() - Native C++
Syntax void RegisterOnStatusEventDoneCallback (EventCallback_II_SREC_ST_UINT32
in_CallbackFunction);
Parameters EventCallback_II_SREC_ST_UINT32 in_CallbackFunction:
A callback function that subscribes to the event. See EventCallback_II_SREC_ST_UINT32 (Page 289).
Return values None
Note The callback function runs in a separate thread.

UnregisterOnStatusEventDoneCallback()
Unregisters the callback function.
Table 8-381 UnregisterOnStatusEventDoneCallback() - Native C++
Syntax void UnregisterOnStatusEventDoneCallback ();
Parameters Optional parameter of the same type as for the Register*()function. If you use the parameter, it
uninstalls the specific function; otherwise, the last registered callback function is unregistered.
Return values None

S7-PLCSIM Advanced
264 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.6 API IInstances

OnProfileEventDone()
Registers or unregisters an event handler method.
Table 8-382 OnProfileEventDone() - .NET (C#)
Syntax event Delegate_SREC_ST_UINT32 OnProfileEventDone;
Parameters None. See Delegate_SREC_ST_UINT32 (Page 296).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnProfileEventDoneCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-383 RegisterOnProfileEventDoneCallback() - Native C++
Syntax void RegisterOnProfileEventDoneCallback (EventCallback_II_SREC_ST_UINT32
in_CallbackFunction);
Parameters EventCallback_II_SREC_ST_UINT32 in_CallbackFunction:
A callback function that subscribes to the event. See EventCallback_II_SREC_ST_UINT32 (Page 289).
Return values None
Note The callback function runs in a separate thread.

UnregisterOnProfileEventDoneCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 8-384 UnregisterOnProfileEventDoneCallback() - Native C++
Syntax void UnregisterOnProfileEventDoneCallback ();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

OnUpdateEventDone()
Registers or unregisters an event handler method.
Table 8-385 OnUpdateEventDone() - .NET (C#)
Syntax event Delegate_SREC_ST_UINT32 OnUpdateEventDone;
Parameters None. See Delegate_SREC_ST_UINT32 (Page 296).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 265
User interfaces (API)
8.6 API IInstances

RegisterOnUpdateEventDoneCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-386 RegisterOnUpdateEventDoneCallback() - Native C++
Syntax void RegisterOnUpdateEventDoneCallback (EventCallback_II_SREC_ST_UINT32
in_CallbackFunction);
Parameters EventCallback_II_SREC_ST_UINT32 in_CallbackFunction:
A callback function that subscribes to the event. See EventCallback_II_SREC_ST_UINT32 (Page 289).
Return values None
Note The callback function runs in a separate thread.

UnregisterOnUpdateEventDoneCallback()
Unregisters the callback function.
Table 8-387 UnregisterOnUpdateEventDoneCallback() - Native C++
Syntax void UnregisterOnUpdateEventDoneCallback ();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

OnRackOrStationFaultEvent
Registers or unregisters an event handler method.
Table 8-388 OnRackOrStationFaultEvent - .NET (C#)
Syntax event Delegate_SREC_ST_UINT32_ERSFET OnRackOrStationFault;
Parameter None. See Delegate_SREC_ST_UINT32_ERSFET (Page 297).
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnRackOrStationFaultEventCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-389 RegisterOnRackOrStationFaultEventCallback() - Native C++
Syntax void RegisterOnRackOrStationFaultEventCallback (
EventCallback_II_SREC_ST_UINT32_ERSFET in_CallbackFunction );
Parameter EventCallback_II_ SREC_ST_UINT32_ERSFET in_CallbackFunction.
A callback function that subscribes to the event. See EventCallback_II_SREC_ST_UINT32_ERSFET
(Page 289)
Return values None

S7-PLCSIM Advanced
266 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.7 API IRemoteRuntimeManager

Note The callback function runs in a separate thread.

UnregisterOnRackOrStationFaultEventCallback()
Unregisters the callback function.
Table 8-390 UnregisterOnRackOrStationFaultEventCallback() - Native C++
Syntax void UnregisterOnRackOrStationFaultEventCallback ();
Parameter Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

8.7 API IRemoteRuntimeManager

8.7.1 Interfaces - Information and settings

Dispose()
Deletes the managed interface and unloads the native components of the user interfaces.

NOTE
When the interface of the Remote Runtime Manager is deleted, no IInstance interface which
was generated by the IRemoteRuntimeManager interface can be used.
The .NET Garbage Collector clears its IRemoteRuntimeManager interface when no active
references are present.

Table 8-391 Dispose() - .NET (C#)

Syntax void Dispose()
Parameters None
Return values None

GetVersion()
Returns the version of the remote Runtime Manager. If the function fails, version 0.0 is
returned.
Table 8-392 GetVersion() - Native C++
Syntax UINT32 GetVersion();
Parameters None
Return values UINT32: Remote Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 267
User interfaces (API)
8.7 API IRemoteRuntimeManager

Table 8-393 Version { get; } - .NET (C#)

Syntax UInt32 Version { get; }
Parameters None
Return values Uint32: Remote Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

GetIP() / IP { get; }
Returns the IP address of the PC on which the remote Runtime Manager is running. If the
function fails, the return value is 0.
Table 8-394 GetIP() - Native C++
Syntax UIP GetIP();
Parameters None
Return values UIP: Returns the IP address of the PC on which the Runtime Manager is running.

Table 8-395 IP { get; } - .NET (C#)

Syntax SIP IP { get; }
Parameters None
Return values SIP: Returns the IP address of the PC on which the Runtime Manager is running.

GetPort() / Port { get; }

Returns the open port of the PC on which the remote Runtime Manager is running. If the
function fails, the return value is 0.
Table 8-396 GetPort() - Native C++
Syntax UINT16 GetPort();
Parameters None
Return values UINT16: Open port of the PC on which the remote Runtime Manager is running.

Table 8-397 Port { get; } - .NET (C#)

Syntax UInt16 Port { get; }
Parameters None
Return values UInt16: Open port of the PC on which the remote Runtime Manager is running.

GetRemoteComputerName() / RemoteComputerName { get; }

Returns the name of the PC on which the remote Runtime Manager is running.
When the name of the PC on which the remote Runtime Manager is running cannot be
identified on the local PC, the IP address is returned.
Table 8-398 GetRemoteComputerName() - Native C++
Syntax ERuntimeErrorCode GetRemoteComputerName(WCHAR* inout_Name,UINT32
in_ArrayLength);

S7-PLCSIM Advanced
268 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.7 API IRemoteRuntimeManager

Parameters • WCHAR* inout_Name:

A user-allocated array for the computer name.
• UINT32 in_ArrayLength:
The array length. The array should be longer than MAX_COMPUTERNAME_LENGTH.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The interface is disconnected from the remote
Runtime Manager.
SREC_INDEX_OUT_OF_RANGE The array is too small to accommodate the com­
puter name.

Table 8-399 RemoteComputerName { get; } - .NET (C#)

Syntax string RemoteComputerName { get; }
Parameters None
Return values string: Name of the PC on which the remote Runtime Manager is running.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The interface is disconnected from the remote
Runtime Manager.
ERuntimeErrorCode.IndexOutOfRange The array is too small to accommodate the com­
puter name.

Disconnect()
Closes the connection to the remote Runtime Manager.

NOTE
All applications that are connected to the remote Runtime Manager lose this connection.

Table 8-400 Disconnect() - Native C++

Syntax ERuntimeErrorCode Disconnect();
Parameters None
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The interface is disconnected from the remote
Runtime Manager.
SREC_TIMEOUT The function does not return on time.

Table 8-401 Disconnect() - .NET (C#)

Syntax void Disconnect();
Parameters None
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 269
User interfaces (API)
8.7 API IRemoteRuntimeManager

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The interface is disconnected from the remote
Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

GetStrictMotionTiming() / StrictMotionTiming { get; }

Returns the current global setting for the "Strict Motion Timing" feature that has an effect on
newly created instances. The "Strict Motion Timing" feature is located on the S7-PLCSIM
Advanced Control Panel (Page 59).
Table 8-402 GetStrictMotionTiming() - Native C++
Syntax ERuntimeErrorCode GetStrictMotionTiming(bool* enabled);
Parameters bool* enabled:
Receives the current setting.
true: Active
false: Inactive
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_TIMEOUT The function does not return on time.
SREC_CONFIG_FILE_ERROR The setting could not be read from the configuration
file UserInterfaceConfiguration.xml.

Table 8-403 StrictMotionTiming { get; } - .NET (C#)

Syntax bool StrictMotionTiming { get; }
Parameters None
Return values Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.ConfigFileError The setting could not be read from the configura­
tion file UserInterfaceConfiguration.xml.

SetStrictMotionTiming() / StrictMotionTiming { set; }

Sets the global setting for the "Strict Motion Timing" feature that has an effect on newly
created instances. The "Strict Motion Timing" feature is located on the S7-PLCSIM Advanced
Control Panel (Page 59).
Table 8-404 SetStrictMotionTiming() - Native C++
Syntax ERuntimeErrorCode SetStrictMotionTiming(bool enable);
Parameters bool enable:
The value to be set.
true: Active
false: Inactive

S7-PLCSIM Advanced
270 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.7 API IRemoteRuntimeManager

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_ALREADY_EXISTS An instance is registered. No instance must be
registered to change the setting.
SREC_TIMEOUT The function does not return on time.
SREC_ACCESS_DENIED No write rights for the configuration file.
SREC_CONFIG_FILE_ERROR The setting could not be written to the configuration
file UserInterfaceConfiguration.xml.

Table 8-405 StrictMotionTiming { set; } - .NET (C#)

Syntax bool StrictMotionTiming { set; }
Parameters None
Return values Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.AlreadyExists An instance is registered. No instance must be
registered to change the setting.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.AccessDenied No write rights for the configuration file.
ERuntimeErrorCode.ConfigFileError The setting could not be written to the configura­
tion file UserInterfaceConfiguration.xml.

GetNetworkMode()
Returns the current settings of the network mode, which are used in the network adapter for
distributed communication.
Table 8-406 GetNetworkMode() - Native C++
Syntax ERuntimeErrorCode
IRemoteRuntimeManager::GetNetworkMode(ECommunicationMode* out_Mode);
Parameters ECommunicationMode* out_Mode:
Receives the network mode as #ECommunicationMode that is currently set in the driver of the S7-PLC­
SIM Advanced Virtual Switch
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_VIRTUAL_SWITCH_MISCONFIGURED The S7-PLCSIM Advanced Virtual Switch is con­
figured incorrectly.

SetNetworkMode()
Sets the network mode as used in the network adapter for distributed communication.
Check that the binding on the network interfaces is correct.
Table 8-407 SetNetworkMode() - Native C++
Syntax ERuntimeErrorCode IRemoteRuntimeManager::SetNetworkMode(const
ECommunicationMode in_Mode);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 271
User interfaces (API)
8.7 API IRemoteRuntimeManager

Parameters ECommunicationMode in_Mode:

Type of communication mode to be set in the network
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_VIRTUAL_SWITCH_MISCONFIGURED The driver of the S7-PLCSIM Advanced Virtual
Switch is not running.

NetworkMode { get; set; };

Returns or sets the network mode used on the network adapter for distributed
communication.
Check that the binding on the network interfaces is correct.
Table 8-408 NetworkMode { get; set; } - .NET (C#)
Syntax ECommunicationMode IRemoteRuntimeManager::NetworkMode { get; set; }
Return value ECommunicationMode:
Type of communication mode to be set in the network
Exceptions Runtime error code Description
ERuntimeErrorCode. The driver of the S7-PLCSIM Advanced Virtual
VirtualSwitchMisconfigured Switch is not running.

8.7.2 Simulation Runtime instances

8.7.2.1 Simulation Runtime instances (remote)

GetRegisteredInstancesCount()
Returns the number of instances that are registered in Runtime Manager. If the function fails,
the return value is 0.
Table 8-409 GetRegisteredInstancesCount() - Native C++
Syntax UINT32 GetRegisteredInstancesCount();
Parameters None
Return values UINT32: Number of available instances.

GetRegisteredInstanceInfoAt()
Returns information about an already registered instance.
You can use the ID or name to create an interface of this instance (see
CreateInterface()).
Table 8-410 GetRegisteredInstanceInfoAt() - Native C++
Syntax ERuntimeErrorCode GetRegisteredInstanceInfoAt(UINT32 in_Index,
SInstanceInfo* out_InstanceInfo);

S7-PLCSIM Advanced
272 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.7 API IRemoteRuntimeManager

Parameters • UINT32 in_Index:

Index of the created instance from which you want to receive the information. The index must be
less than the value you receive when you call GetRegisteredInstanceCount().
• SInstanceInfo* out_InstanceInfo:
The information with name and ID of the instance. See SInstanceInfo (Page 305).
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The interface is disconnected from the remote
Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_INDEX OUT_OF_RANGE There is no instance information for this index.

RegisteredInstanceInfo { get; }
Returns information about an already registered instance. You can use the ID or name of this
instance to create an interface of this instance, see CreateInterface().
Table 8-411 RegisterInstanceInfo { get; } - .NET (C#)
Syntax SInstanceInfo[] RegisteredInstanceInfo { get; }
Parameters None
Return values None
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The interface is disconnected from the remote
Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.

RegisterInstance()
Registers a new instance of a virtual controller in Runtime Manager. Creates and returns an
interface of this instance.
Table 8-412 RegisterInstance() - Native C++
Syntax ERuntimeErrorCode RegisterInstance(IInstance** out_InstanceInterface);
ERuntimeErrorCode RegisterInstance(WCHAR* in_InstanceName, IInstance**
out_InstanceInterface);
ERuntimeErrorCode RegisterInstance(ECPUType in_CPUType, IInstance**
out_InstanceInterface);
ERuntimeErrorCode RegisterInstance(ECPUType in_CPUType, WCHAR*
in_InstanceName, IInstance** out_InstanceInterface);
Parameters • ECPUType in_CPUType:
Defines which CPU type is simulated at the start of the instance. The default setting is
"SRCT_1500_Unspecified".
When a different CPU type is loaded via STEP 7 or from the Virtual SIMATIC Memory Card, this CPU
type applies.
• WCHAR* in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 273
User interfaces (API)
8.7 API IRemoteRuntimeManager

the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
• IInstance** out_InstanceInterface:
Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The
interface is created within the function.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The interface is disconnected from the remote
Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The name or the IInstance pointer is invalid.
SREC_LIMIT_REACHED There are already 16 instances registered in
Runtime Manager.
SREC_ALREADY_EXISTS An instance with this name already exists.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

// Example: How To Create And Register An Instance

// And To Get An Interface Of The Instance The Same Time
IInstance* psa = NULL;
if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}

NOTE
Native C++
If you no longer require the interface, delete the interface.
See DestroyInterface() (Page 115).

Table 8-413 RegisterInstance() - .NET (C#)

Syntax IInstance RegisterInstance();
IInstance RegisterInstance(string in_InstanceName);
IInstance RegisterInstance(ECPUType in_CPUType);
IInstance RegisterInstance(ECPUType in_CPUType string in_InstanceName);
Parameters • ECPUType in_CPUType:
Defines which CPU type is simulated at the start of the instance. The default setting is
"ECPUType.Unspecified".
When a different CPU type is loaded via STEP 7 or from the Virtual SIMATIC Memory Card, this CPU
type applies.
• string in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which
the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
Return values If the function is successful, an interface of a virtual controller. Otherwise, a Null pointer.

S7-PLCSIM Advanced
274 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.7 API IRemoteRuntimeManager

Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The interface is disconnected from the remote
Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The name is invalid.
ERuntimeErrorCode.LimitReached There are already 16 instances registered in
Runtime Manager.
ERuntimeErrorCode.AlreadyExists An instance with this name already exists.

RegisterCustomInstance()
Registers a new instance of a virtual controller in Runtime Manager. Creates and returns an
interface of this instance.
Table 8-414 RegisterCustomInstance() - Native C++
Syntax ERuntimeErrorCode RegisterCustomInstance(WCHAR* in_VplcDll, IInstance**
out_InstanceInterface);
ERuntimeErrorCode RegisterCustomInstance(WCHAR* in_VplcDll, WCHAR*
in_InstanceName, IInstance** out_InstanceInterface);
Parameters • WCHAR* in_VplcDll:
The complete path to the DLL of the virtual controller that Siemens.Simatic.Simula­
tion.Runtime.Instance.exe loads at PowerOn.
• WCHAR* in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which
the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
• IInstance** out_InstanceInterface:
Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The
interface is created within the function.
Return values Runtime error code Description
SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The interface is disconnected from the remote
Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The DLL name, the instance name or the IInstance
pointer is invalid.
SREC_LIMIT_REACHED There are already 16 instances registered in
Runtime Manager.
SREC_ALREADY_EXISTS An instance with this name already exists.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

// Example: How To Create And Register An Instance

// And To Get An Interface Of The Instance The Same Time
IInstance* psa = NULL;
if (result == SREC_OK)
{
result = api->RegisterCustomInstance(L"C:\\Temp\\vplc.dll", &psa);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 275
User interfaces (API)
8.7 API IRemoteRuntimeManager

NOTE
Native C++
If you no longer require the interface, delete the interface.
See DestroyInterface() (Page 115).

Table 8-415 RegisterCustomInstance() - .NET (C#)

Syntax IInstance RegisterCustomInstance(string in_VplcDll);
IInstance RegisterCustomInstance(string in_VplcDll, string
in_InstanceName);
Parameters • string in_VplcDll:
The complete path to the DLL of the virtual controller that Siemens.Simatic.Simula­
tion.Runtime.Instance.exe loads at PowerOn.
• string in_InstanceName:
Name to be assigned to the instance. Every instance must have a unique name. If no name is
assigned when registering a new instance, the instance is given the name "Instance_#" (# is
the ID of the instance). If this name already exists, the name "Instance_#.#" is used, in which
the second # is a counter that is incremented until the name is unique. The length of the name
must be less than DINSTANCE_NAME_LENGTH. See Data types (Page 297).
Return values If the function is successful, an interface of a virtual controller; otherwise, a Null pointer.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The interface is disconnected from the remote
Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The name or the ID is invalid.
ERuntimeErrorCode.LimitReached There are already 16 instances registered in
Runtime Manager.
ERuntimeErrorCode.AlreadyExists An instance with this name already exists.

CreateInterface()
Creates and returns an interface of an already registered instance of a virtual controller.
The instance could have been registered via the application or another application that uses
the Simulation Runtime API.
Table 8-416 CreateInterface() - Native C++
Syntax ERuntimeErrorCode CreateInterface(WCHAR* in_InstanceName, IInstance**
out_InstanceInterface);
ERuntimeErrorCode CreateInterface(INT32 in_InstanceID, IInstance**
out_InstanceInterface);
Parameters • INT32 in_InstanceID:
The ID of the registered instance from which you want to receive the interface.
• WCHAR* in_InstanceName:
The name of the registered instance from which you want to receive the interface.
• IInstance** out_InstanceInterface:
Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The
interface is created within the function.

S7-PLCSIM Advanced
276 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.7 API IRemoteRuntimeManager

Return values Runtime error code Description

SREC_OK The function is successful.
SREC_INTERFACE_REMOVED The interface is disconnected from the remote
Runtime Manager.
SREC_TIMEOUT The function does not return on time.
SREC_WRONG_ARGUMENT The name, the ID or the IInstance- pointer is invalid.
SREC_DOES_NOT_EXIST The instance is not registered in Runtime Manager.
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IInstance* psa1 = NULL;

IInstance* psa2 = NULL;
if (result == SREC_OK)
{
result = api->CreateInterface(0, &psa1);
result = api->CreateInterface(0, &psa2); // psa2 will be the same as psa1
}
Example C++ ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = InitializeApi(&api);

IInstance* psa = NULL;

if (result == SREC_OK)
{
result = api->CreateInterface(L"My SimulationRuntime Instance", &psa);
}

NOTE
Native C++
If you no longer require the interface, delete the interface.
See DestroyInterface() (Page 115)

Table 8-417 CreateInterface() - .NET (C#)

Syntax IInstance CreateInterface(string in_InstanceName);
IInstance CreateInterface(INT32 in_InstanceID);
Parameters • INT32 in_InstanceID:
The ID of the registered instance from which you want to receive the interface.
• string in_InstanceName:
The name of the registered instance from which you want to receive the interface.
Return values If the function is successful, an interface of a virtual controller; otherwise, a Null pointer.
Exceptions Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException
Runtime error code Description
ERuntimeErrorCode.InterfaceRemoved The interface is disconnected from the remote
Runtime Manager.
ERuntimeErrorCode.Timeout The function does not return on time.
ERuntimeErrorCode.WrongArgument The name or the ID is invalid.
ERuntimeErrorCode.DoesNotExists The instance is not registered in Runtime Manager.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 277
User interfaces (API)
8.7 API IRemoteRuntimeManager

8.7.3 Events for IRemoteRuntimeManager

8.7.3.1 OnConnectionLost events

Description
The event is triggered when the connection to the Remote Runtime Manager has been
terminated.

OnConnectionLost
Registers or unregisters an event handler method.
Table 8-418 OnConnectionLost - .NET (C#)
Syntax event Delegate_IRRTM OnConnectionLost;
Parameters None. See Delegate_IRRTM (Page 293)
Return values None
Exceptions None
Note The event handler method runs in a separate thread.

RegisterOnConnectionLostCallback()
When the event occurs, the registered callback function is called. Multiple callback functions
can be registered for the event.
Table 8-419 RegisterOnConnectionLostCallback() - Native C++
Syntax void RegisterOnConnectionLostCallback(EventCallback_IRRTM
in_CallbackFunction);
Parameters EventCallback_IRRTM in_CallbackFunction:
A callback function that subscribes to an event. See EventCallback_IRRTM (Page 283).
Return values None
Note The callback function runs in a separate thread.

RegisterOnConnectionLostEvent()
When the event occurs, the registered event object is set to the signaled state. Only one
event object can be registered for the event. Registration of a new event object causes the
previous event object to be deleted.
Table 8-420 RegisterOnConnectionLostEvent() - Native C++
Syntax void RegisterOnConnectionLostEvent();
void RegisterOnConnectionLostEvent(HANDLE* in_Event);
Parameters • None:
An internal event object is registered.
• HANDLE* in_Event:
A handle for a user-specific event object. The event object is registered.

S7-PLCSIM Advanced
278 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.7 API IRemoteRuntimeManager

Return values None

Table 8-421 RegisterOnConnectionLostEvent() - .NET (C#)

Syntax void RegisterOnConnectionLostEvent();
Parameters None
Return values None

UnregisterOnConnectionLostCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 8-422 UnregisterOnConnectionLostCallback() - Native C++
Syntax void UnregisterOnConnectionLostCallback();
Parameters Optional parameter of the same type as for the Register*() function
If you use the parameter, it uninstalls the specific function; otherwise, the last registered callback
function is unregistered.
Return values None

UnregisterOnConnectionLostEvent()
Unregisters the event object.
Table 8-423 UnregisterOnConnectionLostEvent() - Native C++
Syntax void UnregisterOnConnectionLostEvent();
Parameters None
Return values None

Table 8-424 UnregisterOnConnectionLostEvent() - .NET (C#)

Syntax void UnregisterOnConnectionLostEvent();
Parameters None
Return values None

WaitForOnConnectionLostEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 8-425 WaitForOnConnectionLostEvent() - Native C++
Syntax bool WaitForOnConnectionLostEvent();
bool WaitForOnConnectionLostEvent(UINT32 in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UINT32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 279
User interfaces (API)
8.8 Data types

Table 8-426 WaitForOnConnectionLostEvent() - .NET (C#)

Syntax bool WaitForOnConnectionLostEvent();
bool WaitForOnConnectionLostEvent(UInt32 in_Time_ms);
Parameters • None:
The time limit is set to INFINITE.
• UInt32 in_Time_ms:
Value for the time limit in milliseconds.
Return values • true: If the event object was set to the signaled state.
• false: If no event was received during the defined time limit.

8.8 Data types

Supported data types

In PLCSIM Advanced V5.0, the Runtime API supports the data types of the S7‑1500 CPUs.

Converting data types

When writing, data types are not transferred BCD-coded but mapped onto primitive data
types.
The data types Counter, Date and Time must be transferred to the API BCD-coded so that the
values are written to the counter and no incorrect values are returned when reading.
For these data types, you must perform a BCD conversion before writing and a BCD back-
conversion after reading.
Example:
If the value 999 is transferred to the API as 2457H, then Write modifies the value 2457H to
999. Without BCD conversion, there is no UInt16 value and Write writes no value at all.

Additional information
For information on data types and conversion, refer to section "Data types" in the SIMATIC
STEP 7 Basic/Professional (https://support.industry.siemens.com/cs/ww/en/view/109755202)
System Manual.

S7-PLCSIM Advanced
280 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.1 DLL import functions (Native C++)

8.8.1.1 ApiEntry_Initialize

Description
Type of the central entry point for the API library (DLL).
Table 8-427 ApiEntry_Initialize - Native C++
Syntax typedef
ERuntimeErrorCode(*ApiEntry_Initialize)(ISimulationRuntimeManager**
out_RuntimeManagerInterface);
Parameters • ISimulationRuntimeManager** out_SimulationRuntimeManagerInterface:
Pointer to a Runtime Manager interface pointer. The pointer must be initialized with NULL. The
interface is created within the function.
• UINT32 in_InterfaceVersion:
Version of the API interface to be downloaded: API_DLL_INTERFACE_VERSION.
Return values Runtime error code Condition
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The pointer to the Runtime Manager interface is
NULL.
SREC_WRONG_VERSION The version of the interface in use does not
match the version of the API library (DLL).
SREC_CONNECTION_ERROR Unable to establish a connection to the Runtime
Manager.
SREC_CONFIG_FILE_ERROR Operation regarding the configuration file "User­
InterfaceConfiguration.xml" has failed, for
example, create, read, write.

8.8.1.2 ApiEntry_DestroyInterface

Description
Type of the entry point for DestroyInterface (Page 115).
Table 8-428 ApiEntry_DestroyInterface - Native C++
Syntax typedef ERuntimeErrorCode(*ApiEntry_DestroyInterface)(IBaseInterface*
in_Interface);
Parameters IBaseInterface* in_Interface:
The interface to be deleted.
Return values Runtime error code Condition
SREC_OK The function is successful.
SREC_WRONG_ARGUMENT The pointer to the interface is NULL.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 281
User interfaces (API)
8.8 Data types

8.8.2 Event callback functions (Native C++)

8.8.2.1 EventCallback_VOID

Description
Table 8-429 EventCallback_VOID - Native C++
Syntax typedef void (*EventCallback_VOID)();
Parameters None
Return values None

8.8.2.2 EventCallback_SRCC_UINT32_UINT32_INT32

Description
Table 8-430 EventCallback_SRCC_UINT32_UINT32_INT32 - Native C++
Syntax ERuntimeConfigChanged in_RuntimeConfigChanged, UINT32 in_Param1, UINT32
in_Param2, INT32 in_Param3);
Parameters ERuntimeCon- UInt32 in_Param1 UInt32 in_Param2 Int32 in_Param3
figChanged
in_RuntimeConfig-
Changed
SRCC_INSTANCE_RE- - - ID of the registered
GISTERED instance
SRCC_INSTANCE_UN- - - ID of the unregistered
REGISTERED instance
SRCC_CONNECTION_- IP of the remote Port of the remote -
OPENED Runtime Manager Runtime Manager
SRCC_CONNECTION_- IP of the remote Port of the remote -
CLOSED Runtime Manager Runtime Manager
SRCC_PORT_OPENED The open port - -
SRCC_PORT_CLOSED - - -
Return values None

8.8.2.3 EventCallback_SRRSI_AD

Description
Table 8-431 EventCallback_SRRSI_AD - Native C++
Syntax typedef void (*EventCallback_SRRSI_AD)(EAutodiscoverType
in_AutodiscoverMsg, SAutodiscoverData in_AutodiscoverData);

S7-PLCSIM Advanced
282 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

Parameters • in_AutodiscoverMsg:
A value from the list of predefined types of events, see EAutodiscoverType (Page 314).
– SRRSI_DISCOVER_STARTED, if the identification process was started by successfully call­
ing the function RunAutodisover().
– SRRSI_DISCOVER_DATA, if a Runtime Manager in the network was determined by the
identification process. For detailed information about the found Runtime Manager, see para­
meter in_AutodiscoverData.
– SRRSI_DISCOVER_FINISHED, if the identification process was completed after the time
defined by the "in_Timeout" parameter had elapsed.
– SRRSI_DISCOVER_STARTED and SRRSI_DISCOVER_FINISHED are always triggered,
even if no data is received.
• in_AutodiscoverData:
Data from the Remote Runtime Manager. The parameter contains valid data only if
in_AutodiscoverMsg = SRRSI_DISCOVER_DATA. Otherwise it is initialized with 0. See
SAutodiscoverData (Page 334).
Return values None

8.8.2.4 EventCallback_IRRTM

Description
Table 8-432 EventCallback_IRRTM - Native C++
Syntax typedef void (*EventCallback_IRRTM)(IRemoteRuntimeManager* in_Sender);
Parameters • IRemoteRuntimeManager* in_Sender:
An interface of the remote Runtime Manager that receives this event.
Return values None

8.8.2.5 EventCallback_II_SREC_ST_SROS_SROS

Description
Table 8-433 EventCallback_II_SREC_ST_SROS_SROS - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_SROS_SROS)(IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime, EOperatingState
in_PrevState, EOperatingState in_OperatingState);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• EOperatingState in_PrevState:
The operating state before the change.
• EOperatingState in_OperatingState:
The current operating state.
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 283
User interfaces (API)
8.8 Data types

Error codes Runtime error code Condition

SREC_OK The function is successful.
SREC_WARNING_TRIAL_MODE_ACTIVE No license available. You can use the instance
without restrictions with the Trial License. After­
wards, the instance is shut down.
SREC_LICENSE_NOT_FOUND Test mode has expired.
SREC_COMMUNICATION_INTERFACE_NOT_AV- A problem has occurred with the selected com­
AILABLE munication interface. Check your settings.

8.8.2.6 EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32

Description
Table 8-434 EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32 - Native C++
Syntax typedef void
(*EventCallback_II_SREC_ST_UINT32_INT64_INT64_UINT32)(IInstance*
in_Sender, ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime,
UINT32 in_Id, INT64 in_TimeSinceSameSyncPoint_ns, INT64
in_TimeSinceAnySyncPoint_ns, UINT32 in_SyncPointCount);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UINT32 in_Id:
For the SingleStep_Bus operating mode:
The ID of the I/O system that is used for cycle-controlled synchronization of the virtual control­
ler.
For all other operating modes:
The ID of the process image partition (PIP) that triggers this event.
0 for the cycle control point (End of cycle).
• INT64 in_TimeSinceSameSyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of the same process
image partition ID was reached.
For the time-controlled operating modes:
The runtime since the last call of the StartProcessing() function.
• INT64 in_TimeSinceAnySyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of any process image par­
tition ID was reached.
For the time-controlled operating modes:
The runtime since the last call of the StartProcessing() function.
• UINT32 in_SyncPointCount:
The number of synchronization points since the last event. If the events are triggered faster
than they are received, multiple events are combined into one event. In this case, this value
contains the number of cycles since the last event was received.
Return values None

S7-PLCSIM Advanced
284 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.2.7 EventCallback_II_SREC_ST

Description
Table 8-435 EventCallback_II_SREC_ST - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST)(IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
Return values None

8.8.2.8 EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32

Description
Table 8-436 EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32 - Native C++
Syntax typedef void
(*EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32)(IInstance*
in_Sender, ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime,
EInstanceConfigChanged in_InstanceConfigChanged, UINT32 in_Param1, UINT32
in_Param2, UINT32 in_Param3, UINT32 in_Param4);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
EInstanceCon- UINT32 UINT32 UINT32 UINT32
figChanged in_Param1 in_Param2 in_Param3 in_Param4
in_InstanceC-
onfigChanged
SRICC_HARDWA- - - - -
RE_SOFTWARE_-
CHANGED
SRICC_IP_CHA- The ID of the inter­ The new IP The new subnet The new standard
NGED face mask gateway
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 285
User interfaces (API)
8.8 Data types

8.8.2.9 EventCallback_II_SREC_ST_SRLT_SRLM

Description
Table 8-437 EventCallback_II_SREC_ST_SRLT_SRLM - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_SRLT_SRLM)(IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime, ELEDType
in_LEDType, ELEDMode in_LEDMode);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• ELEDType in_LEDType:
The LED type that changed its state.
• ELEDMode in_LEDMode:
The new state of the LED display.
Return values None

8.8.2.10 EventCallback_II_SREC_ST_SDRI

Description
Table 8-438 EventCallback_II_SREC_ST_SDRI - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_SDRI)(IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime, SDataRecordInfo
in_DataRecordInfo);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• SDataRecordInfo in_DataRecordInfo:
The structure SDataRecordInfo contains the following information:
– The HW identifier from which the CPU wants to read the data record
– The index of the collected data record
– The maximum size of the data record which the IO device can transfer.
Return values None

8.8.2.11 EventCallback_II_SREC_ST_SDRI_BYTE

Description
Table 8-439 EventCallback_II_SREC_ST_SDRI_BYTE - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_SDRI_BYTE)(IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime, SDataRecordInfo
in_DataRecordInfoconst BYTE* in_Data);

S7-PLCSIM Advanced
286 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

Parameters • IInstance* in_Sender:

An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• SDataRecordInfo in_DataRecordInfo:
The structure SDataRecordInfo contains the following information:
– The HW identifier to which the CPU wants to write the data record
– The index of the supplied data record
– Size of data record
• const BYTE* in_Data:
The data record. This pointer becomes invalid after the callback function has returned.
Return values None

8.8.2.12 EventCallback_II_SREC_ST_UINT32_UINT32

Description
Table 8-440 EventCallback_II_SREC_ST_UINT32_UINT32 - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_UINT32_UINT32)(IInstance*
in_Sender, ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime,
UINT32 in_HardwareIdentifier), UINT32 in_SequenceNumber);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SYSTEMTIME:
The virtual system time of the virtual controller at the time when this event was triggered.
• UINT32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the diagnostics event.
• UINT32 in_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Note
In a real hardware system the IO controller uses the sequence number to check if it has lost a
hardware interrupt.
During the simulation, the sequence number creates the relation between interrupt request and
the associated acyclic alarm.
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 287
User interfaces (API)
8.8 Data types

8.8.2.13 EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32

Description
Table 8-441 EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32 - Native C++
Syntax typedef void
(*EventCallback_II_SREC_ST_UINT32_UINT32_EPET_UINT32)(IInstance*
in_Sender, ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime,
UINT32 in_HardwareIdentifier, UINT32 in_Channel, EProcessEventType
in_ProcessEventType, UINT32 in_SequenceNumber);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UINT32 in_HardwareIdentifier:
The hardware identifier of the I/O module that sends the process event.
• UINT32 in_Channel:
The channel of the I/O module which sends the process event.
• EProcessEventType in_ProcessEventType:
A value from the list of predefined types of events for S7 modules, see EProcessEventType (Page
331).
• UINT32 in_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Note
In a real hardware system the I/O controller uses the sequence number to check if it has lost a
hardware interrupt.
During the simulation, the sequence number creates the relation between interrupt request and
the associated acyclic alarm.
Return values None

8.8.2.14 EventCallback_II_SREC_ST_UINT32_EPPET_UINT32

Description
Table 8-442 EventCallback_II_SREC_ST_UINT32_EPPET_UINT32 - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_UINT32_EPPET_UINT32)(IInstance*
in_Sender, ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SYSTEMTIME,
UINT32 in_HardwareIdentifier, EPullOrPlugEventType
in_PullOrPlugEventType, UINT32 in_SequenceNumber);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SYSTEMTIME:
The virtual system time of the virtual controller at the time when this event was triggered.
• UINT32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the pull/plug event.
• EPullOrPlugEventType in_PullOrPlugEventType:
A value from the list of predefined types of events for S7 modules, see EPullOrPlugEventType
(Page 331).

S7-PLCSIM Advanced
288 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

• UINT32 in_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Note
In a real hardware system the IO controller uses the sequence number to check if it has lost a
hardware interrupt.
During the simulation, the sequence number creates the relation between interrupt request and
the associated acyclic alarm.
Return values None

8.8.2.15 EventCallback_II_SREC_ST_UINT32_ERSFET

Description
Table 8-443 EventCallback_II_SREC_ST_UINT32_ERSFET - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_UINT32_ERSFET)(IInstance*
in_Sender, ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime,
UINT32 in_HardwareIdentifier, ERackOrStationFaultType in_EventType);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SYSTEMTIME:
The virtual system time of the virtual controller at the time when this event was triggered.
• UINT32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the diagnostics event.
• ERackOrStationFaultType in_EventType:
A value from the list of predefined RackOrStationFault event types.
See ERackOrStationFaultType (Page 333).
Return values None

8.8.2.16 EventCallback_II_SREC_ST_UINT32

Description
Table 8-444 EventCallback_II_SREC_ST_UINT32 - Native C++
Syntax typedef void (*EventCallback_II_SREC_ST_UINT32)(IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime, UINT32
in_HardwareIdentifier);
Parameters • IInstance* in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• SYSTEMTIME in_SYSTEMTIME:
The virtual system time of the virtual controller at the time when this event was triggered.
• UINT32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which generates the status, update or Pro­
file event.
The identifier must belong to a hardware component in the currently loaded project.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 289
User interfaces (API)
8.8 Data types

Return values None

8.8.3 Delegate definitions (managed code)

8.8.3.1 Delegate_Void

Description
Table 8-445 Delegate_Void - .NET (C#)
Syntax delegate void Delegate_Void();
Parameters None
Return values None

8.8.3.2 Delegate_SRCC_UINT32_UINT32_INT32

Description
Table 8-446 Delegate_SRCC_UINT32_UINT32_INT32 - .NET (C#)
Syntax delegate void Delegate_SRCC_UINT32_UINT32_INT32(ERuntimeConfigChanged
in_RuntimeConfigChanged, UInt32 in_Param1, UInt32 in_Param2, Int32
in_Param3);
Parameters ERuntimeCon- UInt32 in_Param1 UInt32 in_Param2 Int32 in_Param3
figChanged
in_RuntimeConfig-
Changed
InstanceRe- - - ID of the registered
gistered instance
InstanceUnre- - - ID of the unregistered
gistered instance
ConnectionOpened IP of the Remote Port of the remote -
Runtime Manager Runtime Manager
ConnectionClosed IP of the Remote Port of the remote -
Runtime Manager Runtime Manager
PortOpened The open port - -
PortClosed - - -
Return values None

S7-PLCSIM Advanced
290 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.3.3 Delegate_SRRSI_AD

Description
Table 8-447 Delegate_SRRSI_AD - .NET (C#)
Syntax delegate void Delegate_SRRSI_AD(EAutodiscoverType in_AutodiscoverType,
SAutodiscoverData in_AutodiscoverData);
Parameters • in_AutodiscoverType
A value from the list of predefined types of events, see EAutodiscoverType (Page 334).
– AutodiscoverStarted, if the identification process was started by successfully calling
the function RunAutodisover().
– AutodiscoverData, if a Runtime Manager in the network was determined by the identi­
fication process. For detailed information about the found Runtime Manager, see parameter
in_AutodiscoverData.
– AutodiscoverFinished, if the identification process is completed after the time defined
by the parameter "in_Timeout" has elapsed.
– AutodiscoverStarted and AutodiscoverFinished are always triggered, even if no
data is received.
• in_AutodiscoverData
Data from the Remote Runtime Manager. The parameter contains valid data only if
in_AutodiscoverType = AutodiscoverData. Otherwise it is initialized with 0. See
SAutodiscoverData (Page 314).
Return values None

8.8.3.4 Delegate_II_EREC_DT

Description
Table 8-448 Delegate_II_EREC_DT - .NET (C#)
Syntax delegate void Delegate_II_EREC_DT (IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
Return values None

8.8.3.5 Delegate_II_EREC_DT_EOS_EOS

Description
Table 8-449 Delegate_II_EREC_DT_EOS_EOS - .NET (C#)
Syntax delegate void Delegate_II_EREC_DT_EOS_EOS(IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, EOperatingState
in_PrevState, EOperatingState in_OperatingState);

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 291
User interfaces (API)
8.8 Data types

Parameters • IInstance in_Sender:

An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• EOperatingState in_PrevState:
The operating state before the change.
• EOperatingState in_OperatingState:
The current operating state.
Return values None
Error codes Runtime error code Condition
ERuntimeErrorCode.OK The function is successful.
ERuntimeErrorCode. No license available. You can use the instance
WarningTrialModeActive without restrictions with the Trial License. After­
wards, the instance is shut down.
ERuntimeErrorCode.LicenseNotFound Test mode has expired.
ERuntimeErrorCode. A problem has occurred with the selected com­
CommunicationInterfaceNotAvailable munication interface. Check your settings.

8.8.3.6 Delegate_II_EREC_DT_ELT_ELM

Description
Table 8-450 Delegate_II_EREC_DT_ELT_ELM - .NET (C#)
Syntax delegate void Delegate_II_EREC_DT_ELT_ELM(IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, ELEDType
in_LEDType, ELEDMode in_LEDMode);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• ELEDType in_LEDType:
The LED type that changed its state.
• ELEDMode in_LEDMode:
The new state of the LED display.
Return values None

S7-PLCSIM Advanced
292 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.3.7 Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32

Description
Table 8-451 Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32 - .NET (C#)
Syntax delegate void Delegate_II_EREC_DT_UINT32_INT64_INT64_UINT32 (IInstance
in_Sender, ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, UInt32
in_Id, Int64 in_TimeSinceSameSyncPoint_ns, Int64
in_TimeSinceAnySyncPoint_ns, UInt32 in_SyncPointCount);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UInt32 in_Id:
For the SingleStep_Bus operating mode:
The ID of the I/O system that is used for cycle-controlled synchronization of the virtual control­
ler.
For all other operating modes:
The ID of the process image partition (PIP) that triggers this event.
0 for the cycle control point (End of cycle).
Note: In the SingleStep operating modes, the transferred ID "in_Id" for the cycle control point
has the value 0xFFFF. In this case, the time values are set to 0.
• Int64 in_TimeSinceSameSyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of the same process
image partition ID was reached.
Or the process time for the time-controlled operating modes.
• Int64 in_TimeSinceAnySyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of any process image par­
tition ID was reached.
Or the process time for the time-controlled operating modes.
• UInt32 in_SyncPointCount:
The number of synchronization points since the last event. If the events are triggered faster
than they are received, multiple events are combined into one event. In this case, this value
contains the number of cycles since the last event was received.
Return values None

8.8.3.8 Delegate_IRRTM

Description
Table 8-452 Delegate_IRRTM - .NET (C#)
Syntax delegate void Delegate_IRRTM(IRemoteRuntimeManager in_Sender);
Parameters • IRemoteRuntimeManager in_Sender:
An interface of the remote Runtime Manager that receives this event.
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 293
User interfaces (API)
8.8 Data types

8.8.3.9 Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32

Description
Table 8-453 Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32 - .NET (C#)
Syntax delegate void
Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32(IInstance
in_Sender, ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime,
EInstanceConfigChanged in_InstanceConfigChanged, UInt32 in_Param1,
UInt32 in_Param2, UInt32 in_Param3, UInt32 in_Param4);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
EInstanceCon- UInt32 UInt32 UInt32 UInt32
figChanged in_Param1 in_Param2 in_Param3 in_Param4
in_InstanceC-
onfigChanged
HardwareSoft- - - - -
wareChanged
IPChanged The ID of the The new IP The new subnet The new standard
interface mask gateway
Return values None

8.8.3.10 Delegate_II_EREC_DT_SDRI

Description
Table 8-454 Delegate_II_EREC_DT_SDRI - .NET (C#)
Syntax delegate void Delegate_II_EREC_DT_SDRI (IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, SDataRecordInfo
in_DataRecordInfo);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• SDataRecordInfo in_DataRecordInfo:
The structure SDataRecordInfo contains the following information:
– The HW identifier to which the CPU wants to write the data record
– The index of the supplied data record
– Size of data record
– The data record
Return values None

S7-PLCSIM Advanced
294 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.3.11 Delegate_II_EREC_DT_SDR

Description
Table 8-455 Delegate_II_EREC_DT_SDR - .NET (C#)
Syntax delegate void Delegate_II_EREC_DT_SDR (IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, SDataRecord
in_DataRecord);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• SDataRecord in_DataRecord:
The structure SDataRecord contains the following information:
– The HW identifier to which the CPU wants to write the data record
– The index of the supplied data record
– Size of data record
– The data record
Return values None

8.8.3.12 Delegate_SREC_ST_UINT32_EPPET_UINT32

Description
Table 8-456 Delegate_SREC_ST_UINT32_EPPET_UINT32 - .NET (C#)
Syntax delegate void Delegate_SREC_ST_UINT32 (IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, UInt32
in_HardwareIdentifier, EPullOrPlugEventType in_PullOrPlugEventType,
UInt32 in_SequenceNumber);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UInt32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the pull/plug event.
• EPullOrPlugEventType in_PullOrPlugEventType:
A value from the list of predefined types of events for S7 modules, see EPullOrPlugEventType
(Page 331).
• UInt32 in_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to the PROFINET standard, the sequence number is only 10 bits wide, from 1 to
0x7FF. When the highest number is reached the numbering starts again at 1.
Note
In a real hardware system the IO controller uses the sequence number to check if it has lost a
hardware interrupt.
During the simulation, the sequence number creates the relation between interrupt request and
the associated acyclic alarm.
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 295
User interfaces (API)
8.8 Data types

8.8.3.13 Delegate_SREC_ST_UINT32_UINT32_EPET_UINT32

Description
Table 8-457 Delegate_SREC_ST_UINT32_UINT32_EPET_UINT32 - Native C++
Syntax delegate void Delegate_SREC_ST_UINT32_UINT32_EPET_UINT32(IInstance
in_Sender, ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, UInt32
in_HardwareIdentifier, UInt32 in_Channel, EProcessEventType
in_ProcessEventType, UInt32 in_SequenceNumber);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UInt32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the process event.
• UInt32 in_Channel:
The channel of the I/O module which sends the process event.
• EProcessEventType in_ProcessEventType:
A value from the list of predefined types of events for S7 modules, see EProcessEventType (Page
331).
• UInt32 in_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Note
In a real hardware system the I/O controller uses the sequence number to check if it has lost a
hardware interrupt.
During the simulation, the sequence number creates the relation between interrupt request and
the associated acyclic alarm.
Return values None

8.8.3.14 Delegate_SREC_ST_UINT32

Description
Table 8-458 Delegate_SREC_ST_UINT32 - .NET (C#)
Syntax delegate void Delegate_SREC_ST_UINT32 (IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, UInt32
in_HardwareIdentifier);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UInt32 in_HardwareIdentifier:
The ID of the module which generates the status event, update event or profile event.
Return values None

S7-PLCSIM Advanced
296 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.3.15 Delegate_SREC_ST_UINT32_UINT32

Description
Table 8-459 Delegate_SREC_ST_UINT32_UINT32 - .NET (C#)
Syntax delegate void Delegate_SREC_ST_UINT32 (IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, UInt32
in_HardwareIdentifier, UInt32 in_SequenceNumber);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UInt32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the diagnostics entry.
• UInt32 in_SequenceNumber:
PLCSIM Advanced assigns a unique consecutive number to each interrupt event.
According to PROFINET standard the sequence number is 10 bits wide (1 to 7FFH). When the
highest number is reached the numbering starts again at 1.
Note
In a real hardware system the IO controller uses the sequence number to check if it has lost a
hardware interrupt.
During the simulation, the sequence number creates the relation between interrupt request and
the associated acyclic alarm.
Return values None

8.8.3.16 Delegate_SREC_ST_UINT32_ERSFET

Description
Table 8-460 Delegate_SREC_ST_UINT32_ERSFET - .NET (C#)
Syntax delegate void Delegate_SREC_ST_UINT32_ERSFET(IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode, DateTime in_DateTime, UInt32
in_HardwareIdentifier, ERackOrStationFaultType in_EventType);
Parameters • IInstance in_Sender:
An interface of the instance that receives this event.
• ERuntimeErrorCode in_ErrorCode:
A possible error code.
• DateTime in_DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UInt32 in_HardwareIdentifier:
The hardware identifier of the module or submodule which sends the diagnostics entry.
• ERackOrStationFaultType in_EventType:
A value from the list of predefined RackOrStationFault event types.
See ERackOrStationFaultType (Page 333).
Return values None

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 297
User interfaces (API)
8.8 Data types

8.8.4 Definitions and constants

The following identifiers are used in the API:
Table 8-461 Definitions - Native C++
Identifier Value Description
DINSTANCE_NAME_MAX_LENGTH 64 The unique name of an instance must be less than this value.
DSTORAGE_PATH_MAX_LENGTH 130 The maximum path length to the virtual memory card. Includ­
ing NULL termination.
DTAG_NAME_MAX_LENGTH 300 The maximum length of the name of a PLC tag. Including NULL
termination.
DTAG_ARRAY_DIMENSION 6 The maximum number of dimension for a multi-dimensional
field.
DCONTROLLER_NAME_MAX_LENGTH 128 The maximum length of the controller name. Including NULL
termination.
DCONTROLLER_SHORT_DESIGNATION_MAX_L- 32 The maximum length of the abbreviation of the controller (CPU
ENGTH type). Including NULL termination.
DALARM_NOTIFICATION_MAX_DIAG_EVENTS 100 The maximum number of diagnostic events that are sent in a
diagnostic alarm.
DPROCESS_EVENT_NAME_MAX_LENGTH 123 The maximum length of the name for the process event.
Including NULL termination.
DPROCESS_EVENTS_MAX_ITEMS 256 The maximum number of configurable process events.
DMODULE_STATE_OK 0 AlarmNotification: Module status OK
DMODULE_STATE_ERROR 1 AlarmNotification: Module status faulty
DMODULE_STATE_MAINT_DEMANDED 2 AlarmNotification: Maintenance demanded
DMODULE_STATE_MAINT_REQUIRED 4 AlarmNotification: Maintenance required

Table 8-462 Constants - .NET (C#)

Identifier Value Description
RuntimeConstants.InstanceNameLength 64 The unique name of an instance must be less than this value.
RuntimeConstants. 130 The maximum path length to the virtual memory card. Includ­
StoragePathMaxLength ing NULL termination.
RuntimeConstants.TagNameMaxLength 300 The maximum length of the name of a PLC tag. Including NULL
termination.
RuntimeConstants.TagArrayDimension 6 The maximum number of dimension for a multi-dimensional
field.
RuntimeConstants. 128 The maximum length of the controller name. Including NULL
ControllerNameMaxLength termination.
RuntimeConstants. 32 The maximum length of the abbreviation of the controller (CPU
ControllerShortDesignationMaxLength type). Including NULL termination.
ModuleState.Ok 0 AlarmNotification: Module status OK
ModuleState.Error 1 AlarmNotification: Module status faulty
ModuleState. MaintenanceDemanded 2 AlarmNotification: Maintenance demanded
ModuleState. MaintenanceRequired 4 AlarmNotification: Maintenance required

S7-PLCSIM Advanced
298 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.5 Unions (Native C++)

8.8.5.1 UIP

Description
Contains an IPv4 address.
Table 8-463 UIP - Native C++
Syntax union UIP
{
DWORD IP;
BYTE IPs[4];
};
Member • DWORD IP:
The IP address in a single DWORD
• BYTE IPs[4]:
The four elements of IP in descending order
Example Example for an IP address: 192.168.0.1
UIP.IP = 0xC0A80001
UIP.IPs[3] = 192, UIP.IPs[2] = 168, UIP.IPs[1] = 0, UIP.IPs[0] = 1

8.8.5.2 UDataValue

Description
Contains the value of a PLC tag.
Table 8-464 UDataValue - Native C++
Syntax union UDataValue
{
bool Bool;
INT8 Int8;
INT16 Int16;
INT32 Int32;
INT64 Int64;
UINT8 UInt8;
UINT16 UInt16;
UINT32 UInt32;
UINT64 UInt64;
float Float;
double Double;
CHAR Char;
WCHAR WChar;
};
Member • bool Bool:
1 byte boolean value
• INT8 Int8:
1 byte integer with sign
• INT16 Int16:
2 byte integer with sign
• INT32 Int32:
4 byte integer with sign
• INT64 Int64:
8 byte integer with sign

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 299
User interfaces (API)
8.8 Data types

• UINT8 UInt8:
1 byte integer without sign
• UINT16 UInt16:
2 byte integer without sign
• UINT32 UInt32:
4 byte integer without sign
• UINT64 UInt64:
8 byte integer without sign
• float Float:
4 byte floating-point value
• double Double:
8 byte floating-point value
• CHAR Char:
1 byte value character
• WCHAR WChar:
2 byte value character

8.8.6 Structures
The following structures are available:
• SDataValue (Page 300)
• SDVBNI (Page 302)
• SDataValueByAddress (Page 302)
• SDataValueByAddressWithCheck (Page 303)
• SDataValueByName (Page 304)
• SDataValueByNameWithCheck (Page 304)
• SConnectionInfo (Page 305)
• SInstanceInfo (Page 305)
• SDimension (Page 306)
• STagInfo (Page 306)
• SIP (Page 308)
• SIPSuite4 (Page 308)
• SOnSyncPointReachedResult (Page 309)
• SDataRecordInfo (Page 311)
• SDataRecord (Page 311)
• SConfiguredProcessEvents (Page 312)
• SDiagExtChannelDescription (Page 312)
• SAutodiscoverData (Page 314)

S7-PLCSIM Advanced
300 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.6.1 SDataValue

Description
The structure contains the value and type of a PLC tag.
Table 8-465 SDataValue - Native C++
Syntax struct SDataValue
{
UDataValue Value;
EPrimitiveDataType Type;
};
Member • UDataValue Value:
The value of the PLC tags
• EPrimitiveDataType Type:
Type of PLC tag

Table 8-466 SDataValue - .NET (C#)

Syntax struct SDataValue
{
bool Bool { get; set; }
Int8 Int8 { get; set; }
Int16 Int16 { get; set; }
Int32 Int32 { get; set; }
Int64 Int64 { get; set; }
UInt8 UInt8 { get; set; }
UInt16 UInt16 { get; set; }
UInt32 UInt32 { get; set; }
UInt64 UInt64 { get; set; }
float Float { get; set; }
double Double { get; set; }
sbyte Char { get; set; }
char WChar { get; set; }
EPrimitiveDataType Type { get; set; }
}
Member • bool Bool:
1 byte boolean value
• Int8 Int8:
1 byte integer with sign
• Int16 Int16:
2 byte integer with sign
• Int32 Int32:
4 byte integer with sign
• Int64 Int64:
8 byte integer with sign
• UntT8 UInt8:
1 byte integer without sign
• UInt16 UInt16:
2 byte integer without sign
• UInt32 UInt32:
4 byte integer without sign
• UInt64 UInt64:
8 byte integer without sign
• float Float:
4 byte floating-point value
• double Double:
8 byte floating-point value
• sbyte Char:
1 byte value character

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 301
User interfaces (API)
8.8 Data types

• char WChar:
2 byte value character
• EPrimitiveDataType Type:
Type of PLC tag

8.8.6.2 SDVBNI

Description
This structure is for internal use only. Do not change this structure.
Table 8-467 SDVBNI - Native C++
Syntax struct SDVBNI

Table 8-468 SDVBNI - .NET (C#)

Syntax struct SDVBNI

8.8.6.3 SDataValueByAddress

Description
This structure represents a PLC tag that is accessed via its address.
Table 8-469 SDataValueByAddress - Native C++
Syntax struct SDataValueByAddress
{
UINT32 Offset;
UINT8 Bit;
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
}
Member • UINT32 Offset
The byte offset of the tag if it is not located in a data block.
• UINT8 Bit
The bit offset of the tag if it is not located in a data block.
• SDataValue DataValue
The value of the PLC tags
• ERuntimeErrorCode ErrorCode
– SREC_TIMEOUT if no event was triggered during the defined time interval.
– SREC_WARNING_INVALID_CALL if no function RegisterOnSyncPointReachedEvent was
called before, see ERuntimeErrorCode.

Table 8-470 SDataValueByAddress - .NET (C#)

Syntax struct SDataValueByAddress
{
UInt32 Offset;
UInt8 Bit;
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
}

S7-PLCSIM Advanced
302 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

Member • UINT32 Offset

The byte offset of the tag if it is not located in a data block.
• UINT8 Bit
The bit offset of the tag if it is not located in a data block.
• SDataValue DataValue
The value of the PLC tags
• ERuntimeErrorCode ErrorCode
– SREC_TIMEOUT if no event was triggered during the defined time interval.
– SREC_WARNING_INVALID_CALL if no function RegisterOnSyncPointReachedEvent was
called before, see ERuntimeErrorCode.

8.8.6.4 SDataValueByAddressWithCheck

Description
This structure represents a PLC tag that is accessed via its address.
Table 8-471 SDataValueByAddressWithCheck - Native C++
Syntax struct SDataValueByAddressWithCheck
{
UINT32 Offset;
UINT8 Bit;
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
bool ValueHasChanged;
}
Member • UINT32 Offset
The byte offset of the tag if it is not located in a data block.
• UINT8 Bit
The bit offset of the tag if it is not located in a data block.
• SDataValue DataValue
The value of the PLC tags
• ERuntimeErrorCode ErrorCode
– SREC_TIMEOUT if no event was triggered during the defined time interval.
– SREC_WARNING_INVALID_CALL if no function RegisterOnSyncPointReachedEvent was
called before, see ERuntimeErrorCode.
• bool ValueHasChanged
____________

Table 8-472 SDataValueByAddressWithCheck - .NET (C#)

Syntax struct SDataValueByAddressWithCheck
{
UInt32 Offset;
UInt8 Bit;
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
bool ValueHasChanged;
}
Member • UINT32 Offset
The byte offset of the tag if it is not located in a data block.
• UINT8 Bit
The bit offset of the tag if it is not located in a data block.
• SDataValue DataValue
The value of the PLC tags

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 303
User interfaces (API)
8.8 Data types

• ERuntimeErrorCode ErrorCode
– SREC_TIMEOUT if no event was triggered during the defined time interval.
– SREC_WARNING_INVALID_CALL if no function RegisterOnSyncPointReachedEvent was
called before, see ERuntimeErrorCode.
• bool ValueHasChanged
____________

8.8.6.5 SDataValueByName

Description
This structure represents a PLC tag that is called by its name.
Table 8-473 SDataValueByName - Native C++
Syntax struct SDataValueByName
{
WCHAR Name[DTAG_NAME_MAX_LENGTH];
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
SDVBNI Internal;
}
Member • WCHAR Name[DTAG_NAME_MAX_LENGTH]
The name of the tag
• SDataValue DataValue
The value of the PLC tags
• ERuntimeErrorCode ErrorCode
– SREC_TIMEOUT if no event was triggered during the defined time interval.
– SREC_WARNING_INVALID_CALL if no function RegisterOnSyncPointReachedEvent was
called before, see ERuntimeErrorCode.
• SDVBNI Internal
__________________

Table 8-474 SDataValueByName - .NET (C#)

Syntax struct SDataValueByName
{
String Name;
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
SDVBNI Internal;
}
Member • String Name
The name of the tag
• SDataValue DataValue
The value of the PLC tags
• ERuntimeErrorCode ErrorCode
– SREC_TIMEOUT if no event was triggered during the defined time interval.
– SREC_WARNING_INVALID_CALL if no function RegisterOnSyncPointReachedEvent was
called before, see ERuntimeErrorCode.
• SDVBNI Internal
__________________

S7-PLCSIM Advanced
304 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.6.6 SDataValueByNameWithCheck

Description
This structure represents a PLC tag that is called by its name.
Table 8-475 SDataValueByNameWithCheck - Native C++
Syntax struct SDataValueByNameWithCheck
{
WCHAR Name[DTAG_NAME_MAX_LENGTH];
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
SDVBNI Internal;
bool ValueHasChanged;
};

Table 8-476 SDataValueByNameWithCheck - .NET (C#)

Syntax struct SDataValueByNameWithCheck
{
String Name;
SDataValue DataValue;
ERuntimeErrorCode ErrorCode;
SDVBNI Internal;
bool ValueHasChanged;
}

8.8.6.7 SConnectionInfo

Description
This structure contains the IP address and port of a TCP/IP connection.
Table 8-477 SConnectionInfo - Native C++
Syntax struct SConnectionInfo
{
UIP IP;
UINT16 Port;
};

Table 8-478 SConnectionInfo - .NET (C#)

Syntax struct SConnectionInfo
{
SIP IP;
UInt16 Port;
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 305
User interfaces (API)
8.8 Data types

8.8.6.8 SInstanceInfo

Description
This structure contains an IPv4 address.
Table 8-479 SInstanceInfo - Native C++
Syntax struct SInstanceInfo
{
INT32 ID;
WCHAR Name[DINSTANCE_NAME_MAX_LENGTH];
};
Member • INT32 ID:
The ID of the instance
• WCHAR Name[DINSTANCE_NAME_MAX_LENGTH]:
The name of the instance

Table 8-480 SInstanceInfo - .NET (C#)

Syntax struct SInstanceInfo
{
Int32 ID;
String Name;
}
Member • Int32 ID:
The ID of the instance
• String name:
The name of the instance

8.8.6.9 SDimension

Description
This structure contains information about the dimension of a field.
Table 8-481 SDimension - Native C++
Syntax struct SDimension
{
INT32 StartIndex;
UINT32 Count;
};

Table 8-482 SDimension - .NET (C#)

Syntax struct SDimension
{
Int32 StartIndex;
UInt32 Count;
}

S7-PLCSIM Advanced
306 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.6.10 STagInfo

Description
This structure contains information about a PLC tag.
Table 8-483 STagInfo - Native C++
Syntax struct STagInfo
{
WCHAR Name[DTAG_NAME_MAX_LENGTH];
EArea Area;
EDataType DataType;
EPrimitiveDataType PrimitiveDataType;
UINT16 Size;
UINT32 Offset;
UINT8 Bit;
UINT8 DimensionCount;
UINT32 Index;
UINT32 ParentIndex;
SDimension Dimension[DTAG_ARRAY_DIMENSION];
};
Member • WCHAR Name[DTAG_NAME_MAX_LENGTH]:
The name of the tag
• EArea area:
The CPU area where the tag is located.
• EDataType DataType:
The CPU data type of the tag
• EPrimitiveDataType PrimitiveDataType:
The primitive data type of the tag
• UINT16 size:
The size of the tag in bytes
• UINT32 offset:
The byte offset of the tag if it is not located in a data block.
• UINT8 bit:
The bit offset of the tag if it is not located in a data block.
• UINT8 DimensionCount:
The number of dimensions of the array. 0 if the tag is not a field.
• UINT32 index:
The index of the tag
• UINT32 ParentIndex:
If this tag is embedded in another tag (for example, an element of a structure), this value then dis­
plays the index of the parent tag. The value is 0 if the tag has no parent tag.
• SDimension Dimension[DTAG_ARRAY_DIMENSION]:
Information about each dimension of the field

Table 8-484 STagInfo - .NET (C#)

Syntax public struct STagInfo
{
String Name;
EArea Area;
EDataType DataType;
EPrimitiveDataType PrimitiveDataType;
UInt16 Size;
UInt32 Offset;
UInt8 Bit;
UInt32 Index;
UInt32 ParentIndex;
SDimension[] Dimension;
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 307
User interfaces (API)
8.8 Data types

Member • String name:

The name of the tag
• EArea area:
The CPU area where the tag is located.
• EDataType DataType:
The CPU data type of the tag
• EPrimitiveDataType PrimitiveDataType:
The primitive data type of the tag
• UInt16 size:
The size of the tag in bytes.
• UInt32 offset:
The byte offset of the tag if it is not located in a data block.
• UInt8 bit:
The bit offset of the tag if it is not located in a data block.
• UInt32 index:
The index of the tag
• UInt32 ParentIndex:
If this tag is embedded in another tag (for example, an element of a structure), this value then dis­
plays the index of the parent tag. The value is 0 if the tag has no parent tag.
• SDimension[] Dimension:
Information about each dimension of the field. Empty, if the tag is not an array.

8.8.6.11 SIP

Description
This structure contains an IPv4 address.
Table 8-485 SIP - .NET (C#)
Syntax struct SIP
{
byte[] IPArray { get; set; }
UInt32 IPDWord { get; set; }
string IPString { get; set; }
}
Member • UInt32 IPDWord:
The IP address in a single DWORD
• byte[] IPArray:
The four elements of IP in descending order
• string IPString:
The IPv4 address as a string
Example Example for an IP address: 192.168.0.1
SIP.IPDWord = 0xC0A80001
SIP.IPArray[3] = 192, SIP.IPArray[2] = 168, SIP.IPArray[1] = 0, SIP.IPArray[0] = 1
SIP.IPString = "192.168.0.1"

S7-PLCSIM Advanced
308 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.6.12 SIPSuite4

Description
This structure contains an IPv4 suite.
Table 8-486 SIPSuite4 - Native C++
Syntax struct SIPSuite4
{
UIP IPAddress;
UIP SubnetMask;
UIP DefaultGateway;
};
Member • UIP IPAddress:
The IP address
• UIP SubnetMask:
The subnet mask
• UIP DefaultGateway:
The standard gateway

Table 8-487 SIPSuite4 - .NET (C#)

Syntax struct SIPSuite4
{
SIP IPAddress;
SIP SubnetMask;
SIP DefaultGateway;
}
Member • SIP IPAddress:
The IP address
• SIP SubnetMask:
The subnet mask
• SIP DefaultGateway:
The standard gateway

8.8.6.13 SOnSyncPointReachedResult

Description
This structure contains the results of the OnSyncPointReached event.
Table 8-488 SOnSyncPointReachedResult - Native C++
Syntax struct SOnSyncPointReachedResult
{
ERuntimeErrorCode ErrorCode;
SYSTEMTIME SystemTime;
UINT32 Id;
INT64 TimeSinceSameSyncPoint_ns;
INT64 TimeSinceAnySyncPoint_ns;
UINT32 SyncPointCount;
};

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 309
User interfaces (API)
8.8 Data types

Member • ERuntimeErrorCode ErrorCode:

– SREC_TIMEOUT if no event was triggered during the defined time interval.
In such a case, the struct values are not used.
– SREC_WARNING_INVALID_CALL, if no function RegisterOnSyncPointReachedEvent
was called before.
See ERuntimeErrorCode.
• SYSTEMTIME SystemTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UINT32 Id:
For the SingleStep_Bus operating mode:
The ID of the I/O system that is used for cycle-controlled synchronization of the virtual control­
ler.
For all other operating modes:
The ID of the process image partition (PIP) that triggers this event.
0 for the cycle control point (End of cycle).
Note: In the SingleStep operating modes, the transferred ID for the cycle control point has the
value 0xFFFF. In this case, the time values are set to 0.
• INT64 TimeSinceSameSyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of the same process
image partition ID was reached.
For the time-controlled operating modes:
The runtime since the last call of the StartProcessing() function.
• INT64 TimeSinceAnySyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of any process image par­
tition ID was reached.
For the time-controlled operating modes:
The runtime since the last call of the StartProcessing() function.
• UINT32 SyncPointCount:
The number of synchronization points since the last event. If the events are triggered faster
than they are received, multiple events are combined into one event. In this case, this value
contains the number of cycles since the last event was received.

Table 8-489 SOnSyncPointReachedResult - .NET (C#)

Syntax struct SOnSyncPointReachedResult
{
ERuntimeErrorCode ErrorCode;
DateTime SystemTime;
UInt32 Id;
Int64 TimeSinceSameSyncPoint_ns;
Int64 TimeSinceAnySyncPoint_ns;
UInt32 SyncPointCount;
}
Member • ERuntimeErrorCode ErrorCode:
– ERuntimeErrorCode.Timeout, if no event was triggered during the defined time inter­
val.
– WarningInvalidCall, if no function RegisterOnSyncPointReachedEvent was
called before.
See ERuntimeErrorCode.
• DateTime DateTime:
The virtual system time of the virtual controller at the time when this event was triggered.
• UInt32 Id:
For the SingleStep_Bus operating mode:
The ID of the I/O system that is used for cycle-controlled synchronization of the virtual control­
ler.
For all other operating modes:
The ID of the process image partition (PIP) that triggers this event.
0 for the cycle control point (End of cycle).

S7-PLCSIM Advanced
310 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

• Int64 TimeSinceSameSyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of the same process
image partition ID was reached.
For the time-controlled operating modes:
The runtime since the last call of the StartProcessing() function.
• Int64 TimeSinceAnySyncPoint_ns:
The virtual time (in nanoseconds) since the last synchronization point of any process image par­
tition ID was reached.
For the time-controlled operating modes:
The runtime since the last call of the StartProcessing() function.
• UInt32 SyncPointCount:
The number of synchronization points since the last event. If the events are triggered faster
than they are received, multiple events are combined into one event. In this case, this value
contains the number of cycles since the last event was received.

8.8.6.14 SDataRecordInfo

Description
This structure contains read/write data record information.
Table 8-490 SDataRecordInfo - Native C++
Syntax struct SDataRecordInfo
{
UINT32 HardwareId;
UINT32 RecordIdx;
UINT32 DataSize;
};
Member • UINT32 HardwareId:
The ID of the hardware module (hardware identifier)
• UINT32 RecordIdx:
The data record number
• UINT32 DataSize:
The data record size

Table 8-491 SDataRecordInfo - .NET (C#)

Syntax struct SDataRecordInfo
{
UInt32 HardwareId;
UInt32 RecordIdx;
UInt32 DataSize;
}
Member • UInt32 ID:
The ID of the hardware module
• UInt32 RecordIdx:
The data record number
• UInt32 DataSize:
The data record size

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 311
User interfaces (API)
8.8 Data types

8.8.6.15 SDataRecord

Description
This structure contains read/write data record information and data records.
Table 8-492 SDataRecord - .NET (C#)
Syntax struct SDataRecord
{
UInt32 HardwareId;
byte[] Data
}
Member • SDataRecordInfo Info:
The data record information, see SDataRecordInfo (Page 311)
• byte[] Data:
The array length

8.8.6.16 SConfiguredProcessEvents

Description
This structure contains information about the configured process events.
Table 8-493 SConfiguredProcessEvents - Native C++
Syntax struct SConfiguredProcessEvents
{
UINT16 HardwareIdentifier;
UINT16 Channel;
EProcessEventType ProcessEventType;
WCHAR Name[DPROCESS_EVENT_NAME_MAX_LENGTH];
};
Member • UINT16 HardwareIdentifier:
The HW identifier
• UINT16 Channel:
The channel of the I/O module which generates the process event.
• EProcessEventType ProcessEventType:
The type of the configured process event
• WCHAR Name[DPROCESS_EVENT_NAME_MAX_LENGTH]:
The name of the process event

Table 8-494 SConfiguredProcessEvents - .NET (C#)

Syntax public struct SConfiguredProcessEvents
{
ushort HardwareIdentifier;
ushort Channel;
EProcessEventType ProcessEventType;
string Name;
}
Member • ushort HardwareIdentifier:
The HW identifier
• ushort Channel:
The channel of the I/O module which generates the process event.
• EProcessEventType ProcessEventType:
The type of the configured process event
• String name:
The name of the process event

S7-PLCSIM Advanced
312 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.6.17 SDiagExtChannelDescription

Description
This structure contains read/write data record information and data records.
Table 8-495 SDiagExtChannelDescription - Native C++
Syntax struct SDiagExtChannelDescription
{
UINT16 ChannelNumber;
UINT16 ErrorType;
UINT16 ExtErrorType;
EDiagSeverity Severity;
EDiagProperty Direction;
};
Member • UINT16 ChannelNumber:
If the interrupt relates to a specific channel of the IO device (e.g. short circuit), this parameter must
contain the number of the faulty channel.
If the interrupt was generated by a module or submodule, the number of the channel must be set
to 0x8000.
• UINT16 ErrorType:
The parameter defines error types according to PROFINET standard, see "Error types" section.
• EDiagSeverity Severity:
The value of the severity for the diagnostics, see EDiagSeverity (Page 333).
• EDiagProperty Direction:
The value for the incoming/outgoing information, see EDiagProperty (Page 332).
• UINT16 ExtErrorType:
This parameter provides the option of defining more details for the diagnostic interrupt. This is
helpful in combination with PDEV error types which are generated for CPU-internal modules.
Should be 0 by default.

Table 8-496 SDiagExtChannelDescription - .NET (C#)

Syntax struct SDiagExtChannelDescription
{
UInt16 ChannelNumber;
UInt16 ErrorType;
UInt16 ExtErrorType;
EDiagSeverity Severity;
EDiagProperty Direction;
};
Member • UInt16 ChannelNumber:
If the interrupt relates to a specific channel of the IO device (e.g. short circuit), this parameter must
contain the number of the faulty channel.
If the interrupt was generated by a module or submodule, the number of the channel must be set
to 0x8000.
• UInt16 ErrorType:
The parameter defines error types according to PROFINET standard, see "Error types" section.
• EDiagSeverity Severity:
The value of the severity for the diagnostics, see EDiagSeverity (Page 333).
• EDiagProperty Direction:
The value for the incoming/outgoing information, see EDiagProperty (Page 332).
• UInt16 ExtErrorType:
This parameter provides the option of defining more details for the diagnostic interrupt. This is
helpful in combination with PDEV error types which are generated for CPU-internal modules.
Should be 0 by default.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 313
User interfaces (API)
8.8 Data types

Error types
The following table contains important error types (ErrorType) according to PROFINET
standard:
Table 8-497 Error types according to PROFINET standard
Value Meaning
0x0000 Reserved / unknown error
0x0001 Short-circuit
0x0002 Undervoltage
0x0003 Overvoltage
0x0004 Overload
0x0005 Overtemperature
0x0006 Wire break
0x0007 High limit violated
0x0008: Low limit violated
0x0009 Error

The following table contains error types ExtChannelErrorType for ChannelErrorType

"Remote mismatch":
Table 8-498 ExtChannelErrType error types
Value Meaning Use
0x0000 Reserved -
0x0001 to 0x7FFF Manufacturer ID Interrupt/diagnostics
0x8000 Peer name of station mismatch Interrupt/diagnostics
0x8001 Peer name of port mismatch Interrupt/diagnostics
0x8002 Peer RT_CLASS_3 mismatch Interrupt/diagnostics
0x8003 Peer MAU Type mismatch Interrupt/diagnostics

8.8.6.18 SAutodiscoverData

Description
This structure contains the IP address, the port, the Runtime version, and the name of the
computer that has a Runtime Manager ready to make a remote connection.
Table 8-499 SAutodiscoverData - Native C++
Syntax public struct SAutodiscoverData
{
UIP IP;
UINT16 Port;
DWORD RuntimeVersion;
WCHAR ComputerName[MAX_COMPUTERNAME_LENGTH + 1];
};

S7-PLCSIM Advanced
314 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

Table 8-500 SAutodiscoverData - .NET (C#)

Syntax public struct SAutodiscoverData
{
public SIP IP;
public ushort Port;
public uint RuntimeVersion;
public string ComputerName;
}

8.8.6.19 SMAC address

Description
Defines the structure of a MAC address.
Table 8-501 SMACAddress - Native C++
Syntax #define DMAC_ADDRESS_LEN 6

struct SMACAddress
{
BYTE Octets[DMAC_ADDRESS_LEN];
};

8.8.6.20 SNetInterfaceInfo

Description
Describes the structure of a network interface.
Table 8-502 SNetInterfaceInfo - Native C++
Syntax struct SNetInterfaceInfo
{
DWORD interfaceIndex;
UMACAddress MACAddress;
WCHAR interfaceName[64];
WCHAR interfaceDescription[64];
};

8.8.7 Enumerations
The following enumerations are available:
• ERuntimeErrorCode (Page 316)
• EArea (Page 318)
• EOperatingState (Page 319)
• EOperatingMode (Page 320)
• ECPUType (Page 320)
• ECommunicationInterface (Page 322)
• ECommunicationMode (Page 323)
• EPLCInterface (Page 323)

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 315
User interfaces (API)
8.8 Data types

• ELEDType (Page 323)

• ELEDMode (Page 324)
• EPrimitiveDataType (Page 325)
• EDataType (Page 326)
• ETagListDetails (Page 329)
• ERuntimeConfigChanged (Page 330)
• EInstanceConfigChanged (Page 330)
• EPullOrPlugEventType (Page 331)
• EProcessEventType (Page 331)
• EDirection (Page 332)
• EDiagProperty (Page 332)
• EDiagSeverity (Page 333)
• ERackOrStationFaultType (Page 333)
• ECycleTimeMonitoringMode (Page 334)
• EAutodiscoverType (Page 334)

8.8.7.1 ERuntimeErrorCode

Description
This enumeration contains all error codes that are used by the Simulation Runtime API. Most
API functions return one of these error codes. If the function is successful, the return value is
always SREC_OK / OK. Errors are returned with negative values, warnings with positive
values.
Table 8-503 ERuntimeErrorCode - Native C++
Syntax enum ERuntimeErrorCode
{
SREC_OK = 0,
SREC_INVALID_ERROR_CODE = -1,
SREC_NOT_IMPLEMENTED = -2,
SREC_INDEX_OUT_OF_RANGE = -3,
SREC_DOES_NOT_EXIST = -4,
SREC_ALREADY_EXISTS = -5,
SREC_UNKNOWN_MESSAGE_TYPE = -6,
SREC_INVALID_MESSAGE_ID = -7,
SREC_WRONG_ARGUMENT = -8,
SREC_WRONG_PIPE = -9,
SREC_CONNECTION_ERROR = -10,
SREC_TIMEOUT = -11,
SREC_MESSAGE_CORRUPT = -12,
SREC_WRONG_VERSION = -13,
SREC_INSTANCE_NOT_RUNNING = -14,
SREC_INTERFACE_REMOVED = -15,
SREC_SHARED_MEMORY_NOT_INITIALIZED = -16,
SREC_API_NOT_INITIALIZED = -17,
SREC_WARNING_ALREADY_EXISTS = 18,
SREC_NOT_SUPPORTED = -19,
SREC_WARNING_INVALID_CALL = 20,
SREC_ERROR_LOADING_DLL = -21,
SREC_SIGNAL_NAME_DOES_NOT_EXIST = -22,
SREC_SIGNAL_TYPE_MISMATCH = -23,
SREC_SIGNAL_CONFIGURATION_ERROR = -24,
SREC_NO_SIGNAL_CONFIGURATION_LOADED = -25,
SREC_CONFIGURED_CONNECTION_NOT_FOUND = -26,

S7-PLCSIM Advanced
316 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

SREC_CONFIGURED_DEVICE_NOT_FOUND = -27,
SREC_INVALID_CONFIGURATION = -28,
SREC_TYPE_MISMATCH = -29,
SREC_LICENSE_NOT_FOUND = -30,
SREC_NO_LICENSE_AVAILABLE = -31,
SREC_WRONG_COMMUNICATION_INTERFACE = -32,
SREC_LIMIT_REACHED = -33,
SREC_NO_STORAGE_PATH_SET = -34,
SREC_STORAGE_PATH_ALREADY_IN_USE = -35,
SREC_MESSAGE_INCOMPLETE = -36,
SREC_ARCHIVE_STORAGE_NOT_CREATED = -37,
SREC_RETRIEVE_STORAGE_FAILURE = -38,
SREC_INVALID_OPERATING_STATE = -39,
SREC_INVALID_ARCHIVE_PATH = -40,
SREC_DELETE_EXISTING_STORAGE_FAILED = -41,
SREC_CREATE_DIRECTORIES_FAILED = -42,
SREC_NOT_ENOUGH_MEMORY = -43,
SREC_WARNING_TRIAL_MODE_ACTIVE = 44,
SREC_NOT_RUNNING = -45,
SREC_NOT_EMPTY = -46,
SREC_NOT_UP_TO_DATE = -47,
SREC_COMMUNICATION_INTERFACE_NOT_AVAILABLE = -48,
SREC_WARNING_NOT_COMPLETE = 49,
SREC_VIRTUAL_SWITCH_MISCONFIGURED = -50,
SREC_RUNTIME_NOT_AVAILABLE = -51,
SREC_IS_EMPTY = -52,
SREC_WRONG_MODULE_STATE = -53,
SREC_WRONG_MODULE_TYPE = -54,
SREC_NOT_SUPPORTED_BY_MODULE = -55,
SREC_INTERNAL_ERROR = -56,
SREC_STORAGE_TRANSFER_ERROR = -57,
SREC_ANOTHER_VARIANT_OF_PLCSIM_RUNNING = -58,
SREC_ACCESS_DENIED = -59,
SREC_NOT_ALLOWED_DURING_DOWNLOAD = -60,
SREC_AUTODISCOVER_ALREADY_RUNNING = -61,
SREC_INVALID_STORAGE = -62,
SREC_WARNING_UNSUPPORTED_PCAP_DRIVER = 63, //
(Deprecated since V4)
SREC_WARNING_RUNNING_ON_TIA_PORTAL_TEST_SUITE = 64,
SREC_PCAP_DRIVER_NOT_RUNNING = -65,
SREC_UNSUPPORTED_PCAP_DRIVER = -66,
SREC_CONFIG_FILE_ERROR = -67,
SREC_WARNING_PASSWORD_PROTECTION_ERROR = 68,
SREC_BUFFER_OVERFLOW = -69,
SREC_NOT_ALLOWED = -70,
SREC_WARNING_NO_EXTERNAL_COMMUNICATION = 71
};

Table 8-504 ERuntimeErrorCode - .NET (C#)

Syntax enum ERuntimeErrorCode
{
OK = 0,
InvalidErrorCode = -1,
NotImplemented = -2,
IndexOutOfRange = -3,
DoesNotExist = -4,
AlreadyExists = -5,
UnknownMessageType = -6,
InvalidMessageId = -7,
WrongArgument = -8,
WrongPipe = -9,
ConnectionError = -10,
Timeout = -11,
MessageCorrupt = -12,
WrongVersion = -13,
InstanceNotRunning = -14,
InterfaceRemoved = -15,
SharedMemoryNotInitialized = -16,

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 317
User interfaces (API)
8.8 Data types

ApiNotInitialized = -17,
WarningAlreadyExists = 18,
NotSupported = -19,
WarningInvalidCall = 20,
ErrorLoadingDll = -21,
SignalNameDoesNotExist = -22,
SignalTypeMismatch = -23,
SignalConfigurationError = -24,
NoSignalConfigurationLoaded = -25,
ConfiguredConnectionNotFound = -26,
ConfiguredDeviceNotFound = -27,
InvalidConfiguration = -28,
TypeMismatch = -29,
LicenseNotFound = -30,
NoLicenseAvailable = -31,
WrongCommunicationInterface = -32,
LimitReached = -33,
NoStartupPathSet = -34,
StartupPathAlreadyInUse = -35,
MessageIncomplete = -36,
ArchiveStorageNotCreated = -37,
RetrieveStorageFailure = -38,
InvalidOperatingState = -39,
InvalidArchivePath = -40,
DeleteExistingStorageFailed = -41,
CreateDirectoriesFailed = -42,
NotEnoughMemory = -43,
WarningTrialModeActive = 44,
NotRunning = -45,
NotEmpty = -46,
NotUpToDate = -47,
CommunicationInterfaceNotAvailable = -48,
WarningNotComplete = 49,
VirtualSwitchMisconfigured = -50,
RuntimeNotAvailable = -51,
IsEmpty = -52,
WrongModuleState = -53,
WrongModuleType = -54,
NotSupportedByModule = -55,
InternalError = -56,
StorageTransferError = -57,
AnotherVariantOfPlcsimRunning = -58,
AccessDenied = -59,
NotAllowedDuringDownload = -60,
AutodiscoverAlreadyRunning = -61,
InvalidStorage = -62,
WarningUnsupportedPcapDriver = 63, //
(Deprecated since V4)
WarningRunningOnTiaPortalTestSuite = 64,
PCAPDriverNotRunning = -65,
UnsupportedPcapDriver = -66,
ConfigFileError = -67,
WarningPasswordForProtectionError = 68,
BufferOverflow = - 69,
NotAllowed = -70,
WarningNoExternalCommunication = 71
}

S7-PLCSIM Advanced
318 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.7.2 EArea

Description
This enumeration contains all PLC areas that contain the available PLC tags.
Table 8-505 EArea - Native C++
Syntax enum EArea
{
SRA_INVALID_AREA = 0,
SRA_INPUT = 1,
SRA_MARKER = 2,
SRA_OUTPUT = 3,
SRA_COUNTER = 4,
SRA_TIMER = 5,
SRA_DATABLOCK = 6,
SRA_ENUMERATION_SIZE = 7
};

Table 8-506 EArea - .NET (C#)

Syntax public enum EArea
{
InvalidArea = 0,
Input = 1,
Marker = 2,
Output = 3,
Counter = 4,
Timer = 5,
DataBlock = 6,
}

8.8.7.3 EOperatingState

Description
This enumeration contains all the operating states of a virtual controller.
Table 8-507 EOperatingState - Native C++
Syntax enum EOperatingState
{
SROS_INVALID_OPERATING_STATE = 0,
SROS_OFF = 1,
SROS_BOOTING = 2,
SROS_STOP = 3,
SROS_STARTUP = 4,
SROS_RUN = 5,
SROS_FREEZE = 6,
SROS_SHUTTING_DOWN = 7,
SROS_HOLD = 8,

SROS_ENUMERATION_SIZE = 9
};

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 319
User interfaces (API)
8.8 Data types

Table 8-508 EOperatingState - .NET (C#)

Syntax enum EOperatingState
{
InvalidOperatingState = 0,
Off = 1,
Booting = 2,
Stop = 3,
Startup = 4,
Run = 5,
Freeze = 6,
ShuttingDown = 7,
Hold = 8
}

8.8.7.4 EOperatingMode

Description
This enumeration contains all the operating modes of a virtual controller.
Table 8-509 EOperatingMode - Native C++
Syntax enum EOperatingMode
{
SROM_DEFAULT = 0,
SROM_SINGLE_STEP_C = 1,
SROM_SINGLE_STEP_CT = 2,
SROM_TIMESPAN_SYNCHNRONIZED_C = 3,
SROM_SINGLE_STEP_P = 4,
SROM_TIMESPAN_SYNCHNRONIZED_P = 5,
SROM_SINGLE_STEP_CP = 6,
SROM_SINGLE_STEP_CPT = 7,
SROM_TIMESPAN_SYNCHNRONIZED_CP = 8
SROM_SINGLE_STEP_BUS = 9
};

Table 8-510 EOperatingMode - .NET (C#)

Syntax public enum EOperatingMode
{
Default = 0,
SingleStep_C = 1,
SingleStep_CT = 2,
TimespanSynchronized_C = 3,
SingleStep_P = 4,
TimespanSynchronized_P = 5,
SingleStep_CP = 6,
SingleStep_CPT = 7,
TimespanSynchronized_CP = 8
SingleStep_BUS = 9
}

S7-PLCSIM Advanced
320 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.7.5 ECPUType

Description
This enumeration contains all CPU types that can be loaded in a virtual controller.
Table 8-511 ECPUType - Native C++
Syntax enum ECPUType
{
SRCT_1500_Unspecified = 0x000005DC,
SRCT_1511 = 0x000005E7,
SRCT_1513 = 0x000005E9,
SRCT_1515 = 0x000005EB,
SRCT_1516 = 0x000005EC,
SRCT_1517 = 0x000005ED,
SRCT_1518 = 0x000005EE,
SRCT_1511C = 0x000405E7,
SRCT_1512C = 0x000405E8,
SRCT_1511F = 0x000105E7,
SRCT_1513F = 0x000105E9,
SRCT_1515F = 0x000105EB,
SRCT_1516F = 0x000105EC,
SRCT_1517F = 0x000105ED,
SRCT_1518F = 0x000105EE,
SRCT_1511T = 0x000805E7,
SRCT_1515T = 0x000805EB,
SRCT_1516T = 0x000805EC,
SRCT_1517T = 0x000805ED,
SRCT_1511TF = 0x000905E7,
SRCT_1515TF = 0x000905EB,
SRCT_1516TF = 0x000905EC,
SRCT_1517TF = 0x000905ED,
SRCT_1518ODK = 0x001005EE,
SRCT_1518FODK = 0x001105EE,
SRCT_1518MFP = 0x004005EE,
SRCT_1518FMFP = 0x004105EE,
SRCT_1518T = 0x000805EE,
SRCT_1518TF = 0x000905EE,
SRCT_1504DTF = 0x000905E0,
SRCT_1507DTF = 0x000905E3,
SRCT_ET200SP_Unspecified = 0x000205DC,
SRCT_1510SP = 0x000205E6,
SRCT_1512SP = 0x000205E8,
SRCT_1510SPF = 0x000305E6,
SRCT_1512SPF = 0x000305E8,
SRCT_1514SP = 0x000205E7,
SRCT_1514SPT = 0x000205E9,
SRCT_1514SPF = 0x000305E7,
SRCT_1514SPTF = 0x000305E9,
SRCT_1500_RH_Unspecified = 0x008005DC,
SRCT_1513R = 0x008005E9,
SRCT_1515R = 0x008005EB,
SRCT_1517H = 0x008005ED,
SRCT_1518HF = 0x008105EE,
SRCT_ET200PRO_Unspecified = 0x002005DC,
SRCT_1513PRO = 0x002005E9,
SRCT_1513PROF = 0x002105E9,
SRCT_1516PRO = 0x002005EC,
SRCT_1516PROF = 0x002105EC
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 321
User interfaces (API)
8.8 Data types

Table 8-512 ECPUType - .NET (C#)

Syntax enum ECPUType
{
CPU1500_Unspecified = 0x000005DC,
CPU1511 = 0x000005E7,
CPU1513 = 0x000005E9,
CPU1515 = 0x000005EB,
CPU1516 = 0x000005EC,
CPU1517 = 0x000005ED,
CPU1518 = 0x000005EE,
CPU1511C = 0x000405E7,
CPU1512C = 0x000405E8,
CPU1511F = 0x000105E7,
CPU1513F = 0x000105E9,
CPU1515F = 0x000105EB,
CPU1516F = 0x000105EC,
CPU1517F = 0x000105ED,
CPU1518F = 0x000105EE,
CPU1511T = 0x000805E7,
CPU1515T = 0x000805EB,
CPU1516T = 0x000805EC,
CPU1517T = 0x000805ED,
CPU1511TF = 0x000905E7,
CPU1515TF = 0x000905EB,
CPU1516TF = 0x000905EC,
CPU1517TF = 0x000905ED,
CPU1518ODK = 0x001005EE,
CPU1518FODK = 0x001105EE,
CPU1518MFP = 0x004005EE,
CPU1518FMFP = 0x004105EE,
CPU1518T = 0x000805EE,
CPU1518TF = 0x000905EE,
CPU1504DTF = 0x000905E0,
CPU1507DTF = 0x000905E3,
CPUET200SP_Unspecified = 0x000205DC,
CPU1510SP = 0x000205E6,
CPU1512SP = 0x000205E8,
CPU1510SPF = 0x000305E6,
CPU1512SPF = 0x000305E8,
CPU1514SP = 0x000205E7,
CPU1514SPT = 0x000205E9,
CPU1514SPF = 0x000305E7,
CPU1514SPTF = 0x000305E9,
CPU1500_RH_Unspecified = 0x008005DC,
CPU1513R = 0x008005E9,
CPU1515R = 0x008005EB,
CPU1517H = 0x008005ED,
CPU1518HF = 0x008105EE,
CPUET200PRO_Unspecified = 0x002005DC,
CPU1513PRO = 0x002005E9,
CPU1513PROF = 0x002105E9,
CPU1516PRO = 0x002005EC,
CPU1516PROF = 0x002105EC
}

S7-PLCSIM Advanced
322 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.7.6 ECommunicationInterface

Description
This enumeration contains the available communication interfaces of a virtual controller.
Table 8-513 ECommunicationInterface - Native C++
Syntax enum ECommunicationInterface
{
SRCI_NONE = 0,
SRCI_SOFTBUS = 1,
SRCI_TCPIP = 2,
SRCI_ENUMERATION_SIZE = 3
};

Table 8-514 ECommunicationInterface - .NET (C#)

Syntax enum ECommunicationInterface
{
None = 0,
Softbus = 1,
TCPIP = 2,
}

8.8.7.7 ECommunicationMode

Description
This enumeration contains all the communication modes of a virtual controller.
Table 8-515 ECommunicationMode - Native C++
Syntax enum class ECommunicationMode
{
VSWITCH_STATE_UNKNOWN = -1,
VSWITCH_NON_PROMISCUOUS = 0,
VSWITCH_PROMISCUOUS = 1
};

8.8.7.8 EPLCInterface

Description
This enumeration includes the available interfaces of a virtual controller.
Table 8-516 EPLCInterface - Native C++
Syntax enum class EPLCInterface
{
IE1 = 0,
IE2,
IE3
};

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 323
User interfaces (API)
8.8 Data types

8.8.7.9 ELEDType

Description
This list includes all types of LEDs of a virtual controller.
Table 8-517 ELEDType - Native C++
Syntax enum ELEDType
{
SRLT_STOP = 0,
SRLT_RUN = 1,
SRLT_ERROR = 2,
SRLT_MAINT = 3,
SRLT_REDUND = 4,
SRLT_FORCE = 5,
SRLT_BUSF1 = 6,
SRLT_BUSF2 = 7,
SRLT_BUSF3 = 8,
SRLT_BUSF4 = 9,
SRLT_ENUMERATION_SIZE = 10
};

Table 8-518 ELEDType - .NET (C#)

Syntax enum ELEDType
{
Stop = 0,
Run = 1,
Error = 2
Maint = 3,
Redund = 4,
Force = 5,
Busf1 = 6,
Busf2 = 7,
Busf3 = 8,
Busf4 = 9
}

8.8.7.10 ELEDMode

Description
This list contains all the LED states of a virtual controller.
Table 8-519 ELEDMode - Native C++
Syntax enum ELEDMode
{
SRLM_OFF = 0,
SRLM_ON = 1,
SRLM_FLASH_FAST = 2,
SRLM_FLASH_SLOW = 3,
SRLM_INVALID = 4
};

S7-PLCSIM Advanced
324 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

Table 8-520 ELEDMode - .NET (C#)

Syntax enum ELEDMode
{
Off = 0,
On = 1,
FlashFast = 2,
FlashSlow = 3,
Invalid = 4
}

8.8.7.11 EPrimitiveDataType

Description
This list contains all the primitive data types that are used by the I/O access functions.
Table 8-521 EPrimitiveDataType - Native C++
Syntax enum EPrimitiveDataType
{
SRPDT_UNSPECIFIC = 0,
SRPDT_STRUCT = 1,
SRPDT_BOOL = 2,
SRPDT_INT8 = 3,
SRPDT_INT16 = 4,
SRPDT_INT32 = 5,
SRPDT_INT64 = 6,
SRPDT_UINT8 = 7,
SRPDT_UINT16 = 8,
SRPDT_UINT32 = 9,
SRPDT_UINT64 = 10,
SRPDT_FLOAT = 11,
SRPDT_DOUBLE = 12,
SRPDT_CHAR = 13,
SRPDT_WCHAR = 14
};

Table 8-522 EPrimitiveDataType - .NET (C#)

Syntax enum EPrimitiveDataType
{
Unspecific = 0,
Struct = 1,
Bool = 2,
Int8 = 3,
Int16 = 4,
Int32 = 5,
Int64 = 6,
UInt8 = 7,
UInt16 = 8,
UInt32 = 9,
UInt64 = 10,
Float = 11,
Double = 12,
Char = 13,
WChar = 14
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 325
User interfaces (API)
8.8 Data types

Compatible primitive data types

The following tables shows the primitive data types of the user interface (API) and the data
types of the PLCSIM Advanced instance that are configured in the stored tag list. The
compatible data types are marked with "X".
Table 8-523 Compatible primitive data types - Reading
API PLCSIM Advanced instance
Bool INT UINT Float Double Char WChar
8 16 32 64 8 16 32 64
Bool X
INT8 X
INT16 X X X
INT32 X X X X X
INT64 X X X X X X X
UINT8 X
UINT16 X X
UINT32 X X X
UINT64 X X X X
Float X
Double X
Char X
WChar X

Table 8-524 Compatible primitive data types - Write

API PLCSIM Advanced instance
Bool INT UINT Float Double Char WChar
8 16 32 64 8 16 32 64
Bool X
INT8 X X X X
INT16 X X X
INT32 X X
INT64 X
UINT8 X X X X X X X
UINT16 X X X X X
UINT32 X X X
UINT64 X
Float X
Double X
Char X
WChar X

S7-PLCSIM Advanced
326 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.7.12 EDataType

Description
This enumeration contains all the PLC data types (STEP 7).
Table 8-525 EDataType - Native C++
Syntax enum EDataType
{
SRDT_UNKNOWN = 0,
SRDT_BOOL = 1,
SRDT_BYTE = 2,
SRDT_CHAR = 3,
SRDT_WORD = 4,
SRDT_INT = 5,
SRDT_DWORD = 6,
SRDT_DINT = 7,
SRDT_REAL = 8,
SRDT_DATE = 9,
SRDT_TIME_OF_DAY = 10,
SRDT_TIME = 11,
SRDT_S5TIME = 12,
SRDT_DATE_AND_TIME = 14,
SRDT_STRUCT = 17,
SRDT_STRING = 19,
SRDT_COUNTER = 28,
SRDT_TIMER = 29,
SRDT_IEC_Counter = 30,
SRDT_IEC_Timer = 31,
SRDT_LREAL = 48,
SRDT_ULINT = 49,
SRDT_LINT = 50,
SRDT_LWORD = 51,
SRDT_USINT = 52,
SRDT_UINT = 53,
SRDT_UDINT = 54,
SRDT_SINT = 55,
SRDT_WCHAR = 61,
SRDT_WSTRING = 62,
SRDT_LTIME = 64,
SRDT_LTIME_OF_DAY = 65,
SRDT_LDT = 66,
SRDT_DTL = 67,
SRDT_IEC_LTimer = 68,
SRDT_IEC_SCounter = 69,
SRDT_IEC_DCounter = 70,
SRDT_IEC_LCounter = 71,
SRDT_IEC_UCounter = 72,
SRDT_IEC_USCounter = 73,
SRDT_IEC_UDCounter = 74,
SRDT_IEC_ULCounter = 75,
SRDT_ERROR_STRUCT = 97,
SRDT_NREF = 98,
SRDT_CREF = 101,
SRDT_AOM_IDENT = 128,
SRDT_EVENT_ANY = 129,
SRDT_EVENT_ATT = 130,
SRDT_EVENT_HWINT = 131,
SRDT_HW_ANY = 144,
SRDT_HW_IOSYSTEM = 145,
SRDT_HW_DPMASTER = 146,
SRDT_HW_DEVICE = 147,
SRDT_HW_DPSLAVE = 148,
SRDT_HW_IO = 149,
SRDT_HW_MODULE = 150,
SRDT_HW_SUBMODULE = 151,
SRDT_HW_HSC = 152,

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 327
User interfaces (API)
8.8 Data types

SRDT_HW_PWM = 153,
SRDT_HW_PTO = 154,
SRDT_HW_INTERFACE = 155,
SRDT_HW_IEPORT = 156,
SRDT_OB_ANY = 160,
SRDT_OB_DELAY = 161,
SRDT_OB_TOD = 162,
SRDT_OB_CYCLIC = 163,
SRDT_OB_ATT = 164,
SRDT_CONN_ANY = 168,
SRDT_CONN_PRG = 169,
SRDT_CONN_OUC = 170,
SRDT_CONN_R_ID = 171,
SRDT_PORT = 173,
SRDT_RTM = 174,
SRDT_PIP = 175,
SRDT_OB_PCYCLE = 192,
SRDT_OB_HWINT = 193,
SRDT_OB_DIAG = 195,
SRDT_OB_TIMEERROR = 196,
SRDT_OB_STARTUP = 197,
SRDT_DB_ANY = 208,
SRDT_DB_WWW = 209,
SRDT_DB_DYN = 210,
SRDT_DB = 257
};

Table 8-526 EDataType - .NET (C#)

Syntax public enum EDataType
{
Unknown = 0,
Bool = 1,
Byte = 2,
Char = 3,
Word = 4,
Int = 5,
DWord = 6,
DInt = 7,
Real = 8,
Date = 9,
TimeOfDay = 10,
Time = 11,
S5Time = 12,
DateAndTime = 14,
Struct = 17,
String = 19,
Counter = 28,
Timer = 29,
IEC_Counter = 30,
IEC_Timer = 31,
LReal = 48,
ULInt = 49,
LInt = 50,
LWord = 51,
USInt = 52,
UInt = 53,
UDInt = 54,
SInt = 55,
WChar = 61,
WString = 62,
LTime = 64,
LTimeOfDay = 65,
LDT = 66,
DTL = 67,
IEC_LTimer = 68,
IEC_SCounter = 69,
IEC_DCounter = 70,
IEC_LCounter = 71,

S7-PLCSIM Advanced
328 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

IEC_UCounter = 72,
IEC_USCounter = 73,
IEC_UDCounte = 74,
IEC_ULCounter = 75,
ErrorStruct = 97,
NREF = 98,
CREF = 101,
Aom_Ident = 128,
Event_Any = 129,
Event_Att = 130,
Event_HwInt = 131,
Hw_Any = 144,
Hw_IoSystem = 145,
Hw_DpMaster = 146,
Hw_Device = 147,
Hw_DpSlave = 148,
Hw_Io = 149,
Hw_Module = 150,
Hw_SubModule = 151,
Hw_Hsc = 152,
Hw_Pwm = 153,
Hw_Pto = 154,
Hw_Interface = 155,
Hw_IEPort = 156,
OB_Any = 160,
OB_Delay = 161,
OB_Tod = 162,
OB_Cyclic = 163,
OB_Att = 164,
Conn_Any = 168,
Conn_Prg = 169,
Conn_Ouc = 170,
Conn_R_ID = 171,
Port = 173,
Rtm = 174,
Pip = 175,
OB_PCycle = 192,
OB_HwInt = 193,
OB_Diag = 195,
OB_TimeError = 196,
OB_Startup = 197,
DB_Any = 208,
DB_WWW = 209,
DB_Dyn = 210,
DB = 257
}

8.8.7.13 ETagListDetails

Description
This list contains all PLC areas that can be used as a filter to update the tag table.
Table 8-527 ETagListDetails - Native C++
Syntax enum ETagListDetails
{
SRTLD_NONE = 0,
SRTLD_IO = 1,
SRTLD_M = 2,
SRTLD_IOM = 3,
SRTLD_CT = 4,
SRTLD_IOCT = 5,
SRTLD_MCT = 6,
SRTLD_IOMCT = 7,

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 329
User interfaces (API)
8.8 Data types

SRTLD_DB = 8,
SRTLD_IODB = 9,
SRTLD_MDB = 10,
SRTLD_IOMDB = 11,
SRTLD_CTDB = 12,
SRTLD_IOCTDB = 13,
SRTLD_MCTDB = 14,
SRTLD_IOMCTDB = 15
};

Table 8-528 ETagListDetails - .NET (C#)

Syntax enum ETagListDetails
{
None = 0,
IO = 1,
M = 2,
IOM = 3,
CT = 4,
IOCT = 5,
MCT = 6,
IOMCT = 7,
DB = 8,
IODB = 9,
MDB = 10,
IOMDB = 11,
CTDB = 12,
IOCTDB = 13,
MCTDB = 14,
IOMCTDB = 15
}

8.8.7.14 ERuntimeConfigChanged

Description
This list contains all possible causes of an OnSoftwareConfigurationChanged event that the
Runtime Manager sends.
Table 8-529 ERuntimeConfigChanged - Native C++
Syntax enum ERuntimeConfigChanged
{
SRCC_INSTANCE_REGISTERED = 0,
SRCC_INSTANCE_UNREGISTERED = 1
SRCC_CONNECTION_OPENED = 2,
SRCC_CONNECTION_CLOSED = 3,
SRCC_PORT_OPENED = 4,
SRCC_PORT_CLOSED = 5
};

Table 8-530 ERuntimeConfigChanged - .NET (C#)

Syntax enum ERuntimeConfigChanged
{
InstanceRegistered = 0,
InstanceUnregistered = 1,
ConnectionOpened = 2,
ConnectionClosed = 3,
PortOpened = 4,
PortClosed = 5
}

S7-PLCSIM Advanced
330 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.7.15 EInstanceConfigChanged

Description
This list contains all possible causes for an OnSoftwareConfigurationChang event that the
virtual controller sends.
Table 8-531 EInstanceConfigChanged - Native C++
Syntax enum EInstanceConfigChanged
{
SRICC_HARDWARE_SOFTWARE_CHANGED = 0,
SRICC_IP_CHANGED = 1
};

Table 8-532 EInstanceConfigChanged - .NET (C#)

Syntax enum EInstanceConfigChanged
{
HardwareSoftwareChanged = 0,
IPChanged = 1
}

8.8.7.16 EPullOrPlugEventType

Description
This enumeration contains predefined types of pull/plug events for S7 modules.
Table 8-533 EPullOrPlugEventType - Native C++
Syntax enum EPullOrPlugEventType
{
SR_PPE_UNDEFINED = 0,
SR_PPE_PULL_EVENT = 1,
SR_PPE_PLUG_EVENT = 2,
SR_PPE_PLUG_EVENT_ERROR_REMAINS = 3,
SR_PPE_PLUG_WRONG_MODULE_EVENT = 4
};

Table 8-534 EPullOrPlugEventType - .NET (C#)

Syntax enum EPullOrPlugEventType
{
Undefined = 0,
Pull = 1,
Plug = 2,
PlugErrorRemains = 3,
PlugWrongModule = 4
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 331
User interfaces (API)
8.8 Data types

8.8.7.17 EProcessEventType

Description
This enumeration contains predefined types of process events for S7 modules.
Table 8-535 EProcessEventType - Native C++
Syntax enum EProcessEventType
{
SR_PET_UNDEFINED = 0,
SR_PET_RISING_EDGE = 1,
SR_PET_FALLING_EDGE = 2,
SR_PET_LIMIT1_UNDERRUN = 3,
SR_PET_LIMIT1_OVERRUN = 4,
SR_PET_LIMIT2_UNDERRUN = 5,
SR_PET_LIMIT2_OVERRUN = 6
};

Table 8-536 EProcessEventType - .NET (C#)

Syntax enum EProcessEventType
{
Undefined = 0,
RisingEdge = 1,
FallingEdge = 2,
Limit_1_Underrun = 3,
Limit_1_Overrun = 4,
Limit_2_Underrun = 5,
Limit_2_Overrun = 6
}

8.8.7.18 EDirection

Description
This enumeration contains properties of the diagnostic alarm.
Table 8-537 EDirection - Native C++
Syntax enum EDirection
{
SRD_DIRECTION_INPUT = 0,
SRD_DIRECTION_OUTPUT = 1
};

Table 8-538 EDirection - .NET (C#)

Syntax enum EDirection
{
Input = 0,
Output = 1
}

S7-PLCSIM Advanced
332 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.7.19 EDiagProperty

Description
This enumeration contains the incoming/outgoing information of the diagnostic alarm.
Table 8-539 EDiagProperty - Native C++
Syntax enum EDiagProperty
{
SRP_DIAG_APPEAR = 1,
SRP_DIAG_DISAPPEAR = 2
};

Table 8-540 EDiagProperty - .NET (C#)

Syntax enum EDiagProperty
{
Appear = 1,
Disappear = 2
}

8.8.7.20 EDiagSeverity

Description
This enumeration contains the severity of the diagnostic alarm (error, maintenance
demanded, maintenance required).
Table 8-541 EDiagSeverity - Native C++
Syntax enum EDiagSeverity
{
SRDS_SEVERITY_FAILURE = 0,
SRDS_SEVERITY_MAINTENANCE_DEMANDED = 1,
SRDS_SEVERITY_MAINTENANCE_REQUIRED = 2
};

Table 8-542 EDiagSeverity - .NET (C#)

Syntax enum EDiagSeverity
{
Failure = 0,
MaintDemanded = 1,
MaintRequired = 2
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 333
User interfaces (API)
8.8 Data types

8.8.7.21 ERackOrStationFaultType

Description
This enumeration contains the types of the RackOrStationFault event.
Table 8-543 ERackOrStationFaultType - Native C++
Syntax enum ERackOrStationFaultType
{
SR_RSF_FAULT = 0,
SR_RSF_RETURN = 1
};

Table 8-544 ERackOrStationFaultType - .NET (C#)

Syntax enum ERackOrStationFaultType
{
Fault = 0,
Return = 1
}

8.8.7.22 ECycleTimeMonitoringMode

Description
This enumeration contains the sources of the timer for the maximum cycle time monitoring.
Table 8-545 ECycleTimeMonitoringMode - Native C++
Syntax enum ECycleTimeMonitoringMode
{
SRCTMM_DOWNLOADED = 0,
SRCTMM_IGNORED = 1,
SRCTMM_SPECIFIED = 2
};

Table 8-546 ECycleTimeMonitoringMode - .NET (C#)

Syntax enum ECycleTimeMonitoringMode
{
Downloaded = 0,
Ignored = 1,
Specified = 2
}

S7-PLCSIM Advanced
334 Function Manual, 11/2022, A5E37039512-AE
 User interfaces (API)
8.8 Data types

8.8.7.23 EAutodiscoverType

Description
This enumeration is used in the Autodiscover Callback function.
Table 8-547 EAutodiscoverType - Native C++
Syntax enum EAutodiscoverType
{
SRRSI_DISCOVER_STARTED = 0,
SRRSI_DISCOVER_DATA = 1,
SRRSI_DISCOVER_FINISHED = 2
};

Table 8-548 EAutodiscoverType - .NET (C#)

Syntax public enum EAutodiscoverType
{
AutodiscoverStarted = 0,
AutodiscoverData = 1,
AutodiscoverFinished = 2
}

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 335
Restrictions, messages and solution 9
9.1 Overview
Certain actions or events can lead to behavior in PLCSIM Advanced or in STEP 7 which
deviates from that of a hardware CPU. Messages and possible solutions can be found in the
following sections:
• OPC UA server (Page 336)
• Web server (Page 336)
• Backing up and restoring the configuration of a PLCSIM Advanced instance (Page 337)
• Restrictions for file paths (Page 338)
• Restrictions for communications services (Page 339)
• Restrictions for instructions (Page 339)
• Restrictions to local communication via Softbus (Page 339)
• Messages for communication via TCP/IP (Page 340)
• Restrictions of security with VMware vSphere Hypervisor (ESXi) (Page 342)
• Restrictions for Hyper-V (Page 343)
• Monitoring overflow (Page 343)
• Deviating I/O values in the STEP 7 user program (Page 344)
• Multiple simulations and possible collision of IP addresses (Page 344)
• Lacking access to an IP address (Page 344)
• Simulation in standby mode (Page 344)
• ET 200SP CPUs: Use of BusAdapters with fiber-optic interface (Page 346)
• Installing SIMATIC NET (Page 346)

9.2 OPC UA server

With OPC UA, data exchange is performed through an open, standardized and manufacturer-
independent communication protocol. The CPU as OPC UA server can communicate with OPC
UA clients, for example, with HMI panels and SCADA systems.

Configuring an OPC UA server

Start the instances via the communication interface "PLCSIM Virtual Ethernet Adapter"
(TCP/IP) to use the OPC UA server.
The OPC UA server functionality is not available if communication takes place via the Softbus.

User authorization for OPC UA

The PLCSIM Advanced license also contains the user authorization for OPC UA.
The user authorization applies for two instances.

S7-PLCSIM Advanced
336 Function Manual, 11/2022, A5E37039512-AE
 Restrictions, messages and solution
9.4 Backing up and restoring the configuration of a PLCSIM Advanced instance

9.3 Web server

The web server integrated in a CPU enables authorized users to monitor and manage the CPU
via a network. This permits evaluation and diagnostics over long distances.
Each PLCSIM Advanced instance can simulate its own Web server.
The simulation of the Web server is restricted under S7‑PLCSIM Advanced V5.0. The freeze
state of a virtual controller is not shown as an internal operating state.

Configuring the Web server

S7-PLCSIM Advanced
Start the instances via the communication interface "PLCSIM Virtual Ethernet Adapter"
(TCP/IP) to use the Web server.
The Web server functionality is not available if the communication is performed via the
Softbus.
STEP 7
Configure the Web server in STEP 7 in the CPU properties.

Restricted Web server functionality

• The information may not be fully displayed on some websites due to different data
handling.
• There is no topology information.
• FW updates are not supported.

9.4 Backing up and restoring the configuration of a

PLCSIM Advanced instance

Backing up and restoring the configuration

You can backup and restore a PLCSIM Advanced instance.
You can create as many backups as you want and store a variety of configurations for a
PLCSIM Advanced instance.
You perform the backup and restore in the TIA Portal as you would in a real CPU.
PLCSIM Advanced supports backup and restore via web servers.
A backup that was created with PLCSIM Advanced can only be used with PLCSIM Advanced.
It is not possible to restore the configuration of a real CPU with a backup from
PLCSIM Advanced.

Requirements
• The configuration of a PLCSIM Advanced instance is backed up and restored over the
TCP/IP protocol. Softbus is not supported.
• It is only possible to restore the configuration of a PLCSIM Advanced instance with the
corresponding backup from PLCSIM Advanced.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 337
Restrictions, messages and solution
9.7 Restrictions for file paths

9.5 Loading project data of an F-CPU to a standard CPU

You have created an instance using the Control Panel. You have not assigned a password to
protect confidential configuration data in STEP 7.
In addition to a standard CPU, you also want to load an F-CPU via Softbus or TCP/IP to an
instance.
When you load project data of an F-CPU to a standard CPU, a window is displayed in the "Load
preview" dialog with the query of a password for access to the CPU.

NOTE
Loading the project data of an F-CPU to a standard CPU
Loading project data of an F-CPU to a standard CPU is not possible.
To download project data to an F-CPU, you have the following options:
• Select an unspecified CPU as a new device.
• Start a new instance with an F-CPU.

9.6 Update of a TIA Portal project to a new CPU firmware

NOTE
Password encryption in case of updates
When a TIA Portal project is updated from CPU firmware version < V2.0 to CPU firmware
version ≥ V2.0, the following error message is displayed during a download of the project to
SIMATIC S7-PLCSIM Advanced ≥ V4.0:
"Loading of hardware configuration failed (0020 -3 2 0). Please check the diagnostic buffer of
the target hardware."
To successfully download such a project to SIMATIC S7-PLCSIM Advanced ≥ V4.0, click on the
"Update password encryption" button while updating the project.

9.7 Restrictions for file paths

The following restrictions apply for user interfaces which expect a path or a complete file
name as the transfer parameter:
Restrictions for local paths Write permissions to system-critical folders such as the Windows folder (%Windows%) or the
program folders (%Program Files%, %Program Files (x86)%) are not allowed.
In this case the C++ user interface returns the error code SREC_WRONG_ARGUMENT. In this
case the managed user interface returns an exception with the error code
RuntimeErrorCode.WrongArgument.
Restrictions for network In order to be able to use network paths, you must incorporate them as a network drive.
paths Otherwise, the C++ user interface returns the error code SREC_WRONG_ARGUMENT. The man­
aged user interface returns an exception with the error code
RuntimeErrorCode.WrongArgument.

S7-PLCSIM Advanced
338 Function Manual, 11/2022, A5E37039512-AE
 Restrictions, messages and solution
9.10 Restrictions for instructions

9.8 Restrictions for storage paths

Synchronization of the storage path in cloud memory

If the Persistence folder (<...\Persistence\<Instance Name>) is in a path that is synchronized to
a cloud storage, this can lead to the following undesirable behavior:
• Instability or disconnection of active TIA Portal online connections
• Problems with TIA Portal downloads
To prevent this behavior from occurring, you have the following options:
• Do not place the folder of the Virtual SIMATIC Memory Card in a path that is synchronized
to a memory on the cloud.
• Turn off the synchronization of such a folder

9.9 Restrictions for communications services

TUSEND / TURCV
When you run the UDP blocks TUSEND and TURCV via the "PLCSIM" communication interface
(Softbus), you get error code 0x80C4 at the transmission end and receiving end:
Temporary communications error. The specified connection is temporarily down.
Solution
Set "PLCSIM Virtual Ethernet Adapter" (TCP/IP) as the communication interface in PLCSIM
Advanced.

9.10 Restrictions for instructions

PLCSIM Advanced simulates instructions for CPUs S7‑1500 and ET 200SP as close to reality as
possible. PLCSIM Advanced checks the input parameters for validity and returns outputs that
are valid but do not necessarily correspond to those that a real CPU with physical
inputs/outputs would return.

Instructions not supported

Unsupported instructions are treated as non-operational. The value of unsupported
instructions is always "OK". PLCSIM Advanced does not support the following instructions:
• DP_TOPOL
• PORT_CFG

T_CONFIG instruction
The instruction T_CONFIG works in S7-PLCSIM Advanced via TCP/IP, but not via Softbus.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 339
Restrictions, messages and solution
9.12 Unknown data records

9.11 Restrictions to local communication via Softbus

Identical IP addresses for instances

If the "PLCSIM" communication interface (Softbus) is set, then identical IP addresses are
created automatically for all instances when creating the instances through the Control Panel.
In STEP 7, therefore, only one instance is displayed in the dialog.
Solution
Use the API function SetIPSuite() to assign a unique address for each instance, then all
instances are displayed in STEP 7 with their IP addresses.
API function
SetIPSuite() (Page 153)

Working with multiple instances

When you are working with instances without unique IP addresses, note the following
procedure for downloading from TIA Portal via "PLCSIM" (Softbus):

1. Start only one instance with the symbol in the Control Panel.
2. In TIA Portal, download the program to this instance.
3. Repeat the steps until you have created all instances and downloaded all projects.

Online and diagnostics

If the "PLCSIM" (Softbus) communication interface is set, no details are displayed for the
"Online and Diagnostics" function under the PROFINET interface (IP address, MAC address,
etc.).

9.12 Unknown data records

Support of unknown data records

The S7-1500 hardware CPUs return an error code in case of an unknown data record. The
behavior of PLCSIM Advanced differs from the behavior of an S7-1500 hardware CPU. To
enable simulation of the program flow, PLCSIM Advanced does not return an error code for
an unknown data record (e.g. ID 0x9999), but acknowledges the unknown data record with
"OK".

S7-PLCSIM Advanced
340 Function Manual, 11/2022, A5E37039512-AE
 Restrictions, messages and solution
9.13 Messages for communication via TCP/IP

9.13 Messages for communication via TCP/IP

Error codes
If an error occurs, an ID with error designation appears in the taskbar. You will find an
overview of possible error messages and their associated error codes in section
ERuntimeErrorCode (Page 316).

Figure 9-1 Example: Error code -66

Messages and remedy

The settings for TCP/IP communication are checked in the S7-PLCSIM Advanced Control Panel.
The messages and the corresponding remedies are listed below:
Message
"Siemens PLCSIM Virtual Ethernet Adapter was not found. Please reinstall PLCSIM Advanced."
Remedy
The PLCSIM Virtual Ethernet Adapter cannot be found on the system.
Run PLCSIM Advanced Setup again:
1. Double-click the download package or insert the installation medium into the drive. The
setup program starts up automatically, provided you have not disabled the Autostart
function on the computer. If the setup program does not start up automatically, start it
manually by double-clicking the "Start.exe" file.
2. Follow the prompts until you reach the "Configuration" window. Select the "Repair" check
box.
3. Follow the remaining prompts to repair your installation.
4. Complete the repair operation by restarting your computer.

Message
"Siemens PLCSIM Virtual Ethernet Adapter is disabled. Please enable it."
Remedy
The PLCSIM Virtual Ethernet Adapter is deactivated on the system. In the Control Panel, under
"Network and Sharing Center" > "Change Adapter Settings" and activate the network adapter.

Message
"Npcap service is not running. When installed start it from elevated command prompt with
'net start npcap'."

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 341
Restrictions, messages and solution
9.15 Restrictions of security with VMware vSphere Hypervisor (ESXi)

Remedy
The Npcap is not active on the system. Open a command line in administrator mode and
enter the command "net start npcap".
Message
"You have to set a valid IP address for the Siemens PLCSIM Virtual Ethernet Adapter."
Remedy
Assign a static IP address to the Siemens PLCSIM Virtual Ethernet Adapter or obtain an IP
address via DHCP (default setting).

9.14 Time synchronization via NTP mode

Time synchronization via NTP mode with PLCSIM Advanced

You can simulate time synchronization using NTP methods.

9.15 Restrictions of security with VMware vSphere Hypervisor (ESXi)

The following information is only important if you want to communicate with the "outside
world". This means when you access a VM on which the TIA Portal is running from another
virtualization platform on which an instance is running. The following changes are only
necessary if you are not using TCP/IP on the local PC.
• When you use the virtualization platform VMware vSphere Hypervisor (ESXi), you must
change the policy exception to communicate over TCP/IP.
• Accept the "Promiscuous mode" and "Forged transmit" options for the Virtual Switch of the
ESXi.

Promiscuous mode
In promiscuous mode, the network adapter reads all incoming telegrams, including those
that are not intended for the network adapter, and forwards the data to the operating system
for processing.
The promiscuous mode is necessary for the simulation with PLCSIM Advanced so that
telegrams can be forwarded by the Ethernet adapter to the PC or the VM for processing, for
example, data for additional PLCSIM Advanced instances in the network.

NOTICE
Restrictions of security
For security reasons, Promiscuous mode is disabled by default.
If you accept the Promiscuous mode, the real Ethernet adapter even receives telegrams that
are not addressed to it.

S7-PLCSIM Advanced
342 Function Manual, 11/2022, A5E37039512-AE
 Restrictions, messages and solution
9.17 Monitoring overflow

The following figure shows the "Security" category for selecting the security settings for the
virtual switch in VMware vSphere Hypervisor (ESXi).

Figure 9-2 Policy exceptions for VMware vSphere Hypervisor (ESXi)

9.16 Restrictions for Hyper-V

The following information is only important if you want to communicate with the "outside
world". Communication with the "outside world" means that you access another VM running
TIA Portal from a virtualization platform running an instance. When you are using TCP/IP on
the local PC, the following settings are not necessary.
When you use the virtualization platform Hyper-V, you must change the following setting to
be able to use the communication over TCP/IP.
1. In the Hyper-V Manager, select the Hyper-V server.
2. Select the VM and its settings via "Settings...".
3. In the "Extended Functions", select "MAC Address Spoofing".
This setting is necessary for the simulation with PLCSIM Advanced so that telegrams can be
forwarded by the Ethernet adapter to the PC or the VM for processing, for example, data for
additional PLCSIM Advanced instances in the network.

NOTICE
Restrictions of security
For security reasons, Promiscuous mode is disabled by default.
If you accept the Promiscuous mode, the real Ethernet adapter even receives telegrams that
are not addressed to it.

9.17 Monitoring overflow

Monitoring of main cycle

The maximum cycle time monitoring for PLCSIM Advanced is one minute.
If you want to use the values that are configured in the TIA Portal, set them using the
following API function: SetCycleTimeMonitoringMode(). You can find more information
at Cycle control (Page 226).

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 343
Restrictions, messages and solution
9.21 Simulation in standby mode

Monitoring of cyclical events

If your simulation contains cyclic interrupts, the queue of PLCSIM Advanced may overflow for
cyclic events. Due to the runtime speed of PLCSIM Advanced compared to real hardware, the
time needed to create the diagnostic buffer entry may be longer than the time until the next
cyclic interrupt.
In this case, an additional entry is placed in the queue, causing another overflow. In the event
of an overflow, PLCSIM Advanced provides visual information in the form of diagnostics
buffer messages and a red error icon in the project tree.

9.18 Deviating I/O values in the STEP 7 user program

Updated values
Each value that a STEP 7 user program changes in the I/O address ranges receives the
updated value in the cycle control point that was written via the API functions Write...
(). The API functions Read...() only return this updated value and not the value from
STEP 7 for the input range.
Non-updated values
If the value was not updated via the API functions Write...(), the API functions
Read...() return the value from STEP 7 for the output range.

9.19 Multiple simulations and possible collision of IP addresses

You can simultaneously simulate multiple CPUs, but each simulated CPU interface requires a
unique IP address.
Make sure your CPUs have different IP addresses before starting the simulation.

9.20 Lacking access to an IP address

Special feature of distributed communication

If you use multiple network nodes on the same subnet through different virtual or real
adapters, the operating system may search for the node on the wrong adapter.
Remedy
Repeat your requests or enter "arp ‑d <IP address>" in the command line editor of Windows.

9.21 Simulation in standby mode

When your computer or programming device goes into standby or sleep mode, the
simulation may stop. In this case, communication between STEP 7 and PLCSIM Advanced is
stopped. When your computer or programming device starts up again, the communication
may need to be reestablished. In some cases, it may also be necessary to open the simulation
project again.

S7-PLCSIM Advanced
344 Function Manual, 11/2022, A5E37039512-AE
 Restrictions, messages and solution
9.24 Known restrictions when operating with a co-simulation (e.g. SIMIT).

To prevent this situation, disable the standby mode on your computer or programming
device.

9.22 Time response of PLCSIM Advanced in connection with I/O

systems
The SingleStep_P operating mode triggers a SyncPointReached event for each imported
process image partition and I/O system.
Example:
If you have defined a process image partition consisting of input addresses of a centralized
and distributed I/O system, the firmware reads the process image partition of the inputs for
each I/O system and sends a SyncPointReached event each time.
The number of SyncPointReached events sent for a process image partition thus depends
on how many different I/O systems the process image partition contains.

9.23 Simulation start of SIMIT with S7-PLCSIM Advanced

Error message during simulation start of SIMIT with S7-PLCSIM Advanced

You have configured a S7-PLCSIM Advanced connection in SIMIT. When starting the
simulation, SIMIT aborts and the following error message is returned: "-14
InstanceNotRunning"
When the error has occurred, you can also no longer open the S7-PLCSIM Advanced instance
using the virtual Ethernet adapter.
Solution
You have the following solution options:
• Repair your S7-PLCSIM Advanced installation.
• Install S7-PLCSIM Advanced once again.
The procedures are described in the section Installing (Page 31).
A repair or new installation will install the Npcap program library once again. This solves the
problem.

9.24 Known restrictions when operating with a co-simulation (e.g.

SIMIT).
1. In case of a simulation in PLCSIM Advanced in connection with SIMIT, a TIA Portal
download in RUN may result in an MC error (MC message 431: Communication to the
device under logical address [...] is disturbed. Sign of life of drive faulty).
This error can occur with the following project settings:
– Bus-synchronous operating mode in SIMIT or event-synchronous operating mode to
MC servo process image partition (PIP)
– the PLCSIM Advanced feature "Strict Motion Timing" = true
The error causes the activated axes to be switched off. You can acknowledge the error via
an MC_Reset or via the TIA Portal. After that, the axis can be switched on again.

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 345
Restrictions, messages and solution
9.26 Installing SIMATIC NET

9.25 ET 200SP CPUs: Use of BusAdapters with fiber-optic interface

ET 200SP CPUs: Use of BusAdapters with fiber-optic interface

If you use BusAdapters with fiber-optic interface for connecting fiber-optic cables (e.g. BA
2xLC), then download via TCP/IP is not possible.
Remedy
Use the communication interface "PLCSIM" (Softbus) in PLCSIM Advanced.

9.26 Installing SIMATIC NET

Problems after installing SIMATIC NET PC software products

If you are using one of the following operating systems with S7 PLCSIM Advanced on your PC,
problems may arise with the PLCSIM Advanced instances via TCP/IP if you have installed
SIMATIC NET PC software products on your PC:
• Windows 10 Pro, Version 1809
• Windows Server 2019
After installing the SIMATIC NET PC software products, you may no longer be able to start the
PLCSIM Advanced instances via TCP/IP.
Remedy
Update the operating system on your PC:
• Windows 10, Version ≥ 1903 or
• Windows Server version > 2019

S7-PLCSIM Advanced
346 Function Manual, 11/2022, A5E37039512-AE
List of abbreviations A
Abbreviation Term
ALM Automation License Manager
Tool for managing license keys in STEP 7
API Application Programming Interface user interface
arp Address resolution protocol
BCD Binary Coded Decimal
CPU Central Processing Unit (Synonym for PLC)
DLL Dynamic Link Library
HMI Human Machine Interface user interface
I-device Intelligent IO device
IE Industrial Ethernet
GUI Graphical User Interface
LAN Local Area Network
Computer network that is limited to a local area.
MFP Multifunctional platform
OB Organization Block
ODK Open Development Kit
OPC UA Open Platform Communications Unified Architecture
PA Process image output (PIQ)
PE Process image input (PII)
PG Programming device
PLC Programmable Logic Controller
PN PROFINET
RAM Random Access Memory
RT Runtime
SO Shared Object
TCP/IP Transmission Control Protocol/Internet Protocol
TIA Totally Integrated Automation
PIP Process Image Partition
UTC Coordinated Universal Time
VM Virtual Machine
VPLC Virtual Programmable Logic Controller
WinCC Windows Control Center

S7-PLCSIM Advanced
Function Manual, 11/2022, A5E37039512-AE 347