S7 PLCSIM Advanced Function Manual En US

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 312

DownloadS7-PLCSIM Advanced Function Manual En-US
Open PDF In BrowserView PDF
S7-PLCSIM Advanced

___________________
Preface
1
___________________
Guide

SIMATIC
S7-1500
S7-PLCSIM Advanced
Function Manual

2
___________________
Product overview
3
___________________
Installing
4
___________________
Communication paths
5
___________________
Simulate CPU
6
___________________
Virtual time response

___________________
7
User interfaces (API)
___________________
8
Restrictions
___________________
A
List of abbreviations

09/2016

A5E37039512-AA

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
Division Digital Factory
Postfach 48 48
90026 NÜRNBERG
GERMANY

A5E37039512-AA
Ⓟ 08/2016 Subject to change

Copyright © Siemens AG 2016.
All rights reserved

Preface
Purpose of the documentation
This function manual describes the simulation software, S7-PLCSIM Advanced V1.0. It
enables you to test your CPU programs on a simulated, virtual S7-1500 controller.
You can obtain updates to the function manual as downloads on the Internet
(https://support.industry.siemens.com/cs/us/en/view/109739154).

Scope
This function manual is valid for the following order versions
● 6ES7823-1FA00-0YA5 - S7-PLCSIM Advanced V1.0 DVD
● 6ES7823-1FE00-0YA5 - S7-PLCSIM Advanced V1.0 Download
The articles each contain one license for one instance.

Basic knowledge required
The system may 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
● Development of software in C++ and C#
● PC technology
● Windows operating system

Conventions
Conventions STEP 7: In this documentation, "STEP 7" is used as a synonym for all versions
of the configuration and programming software "STEP 7 (TIA Portal)".
We also use abbreviate SIMATIC S7-PLCSIM Advanced V1.0 as "PLCSIM Advanced".
Please 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.

S7-PLCSIM Advanced

4

Function Manual, 09/2016, A5E37039512-AA

Preface

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 only form one element of such a concept.
Customer is responsible to prevent unauthorized access to its plants, systems, machines
and networks. Systems, machines and components should only be connected to the
enterprise network or the internet if and to the extent necessary and with appropriate security
measures (e.g. use of firewalls and network segmentation) in place.
Additionally, Siemens’ guidance on appropriate security measures should be taken into
account. For more information about industrial security, please visit
(http://www.siemens.com/industrialsecurity).
Siemens’ products and solutions undergo continuous development to make them more
secure. Siemens strongly recommends to apply product updates as soon as available and to
always use the latest product versions. Use of product versions that are no longer supported,
and failure to apply latest updates may increase customer’s exposure to cyber threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS
Feed under (http://www.siemens.com/industrialsecurity).

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

5

Table of contents
Preface ................................................................................................................................................... 4
1

2

3

4

5

Guide .................................................................................................................................................... 22
1.1

Documentation Guide S7 PLCSIM Advanced ....................................................................... 22

1.2

S7 PLCSIM products ............................................................................................................. 24

Product overview .................................................................................................................................. 25
2.1

What is PLCSIM Advanced?.................................................................................................. 25

2.2

Security for PLCSIM Advanced ............................................................................................. 26

2.3

Simulations support ........................................................................................................... 27

2.4

Supported CPUs .................................................................................................................... 28

2.5

Differences between a simulated and a real CPU ................................................................. 29

2.5.1

Restrictions for all supported CPUs ....................................................................................... 29

2.6

Simulating Motion Control ...................................................................................................... 31

Installing ............................................................................................................................................... 32
3.1
3.1.1
3.1.2
3.1.3

Introduction ............................................................................................................................ 32
System requirements ............................................................................................................. 32
Licenses ................................................................................................................................. 33
Installation log ........................................................................................................................ 34

3.2

Installation medium ................................................................................................................ 35

3.3

Installing PLCSIM Advanced ................................................................................................. 35

3.4

Changing PLCSIM Advanced ................................................................................................ 37

3.5

Repairing PLCSIM Advanced ................................................................................................ 38

3.6

Uninstalling PLCSIM Advanced ............................................................................................. 39

Communication paths ........................................................................................................................... 40
4.1

Local communication ............................................................................................................. 41

4.2

Communication via TCP / IP .................................................................................................. 42

4.3

Enable distributed communication ......................................................................................... 43

Simulate CPU ....................................................................................................................................... 45
5.1

Basic procedure for the simulation......................................................................................... 45

5.2
5.2.1
5.2.2

User interface ......................................................................................................................... 46
S7 PLCSIM Advanced Symbol .............................................................................................. 46
S7 PLCSIM Advanced Control Panel .................................................................................... 46

5.3

Download ............................................................................................................................... 50

5.4

MAC address of the instances ............................................................................................... 52

5.5

Simulate peripheral I/O .......................................................................................................... 53

5.6
5.6.1
5.6.2

Simulate communication ........................................................................................................ 54
Communication services that can be simulated .................................................................... 54
Communication between instances ....................................................................................... 55

5.7

Provide project data offline for simulation .............................................................................. 56
S7-PLCSIM Advanced

6

Function Manual, 09/2016, A5E37039512-AA

Table of contents

6

7

Virtual time response ............................................................................................................................ 58
6.1

Speed up and slow down simulation ......................................................................................60

6.2

Stop simulation .......................................................................................................................61

6.3
6.3.1
6.3.2

Synchronize simulation partner ..............................................................................................62
Synchronize simulation partner cycle-controlled ....................................................................62
Synchronize simulation partner time-controlled ......................................................................64

User interfaces (API) ............................................................................................................................. 65
7.1
7.1.1
7.1.2
7.1.3
7.1.4
7.1.5
7.1.6

Introduction .............................................................................................................................65
Access to instances ................................................................................................................67
User interfaces (API)...............................................................................................................68
Overview of user interfaces for native C++ ............................................................................69
Overview of user interfaces for managed code ......................................................................73
Overview of data types for native C++....................................................................................76
Overview of data types for managed code .............................................................................77

7.2
7.2.1
7.2.1.1
7.2.1.2
7.2.2
7.2.2.1

Initialize API ............................................................................................................................78
Native C++ ..............................................................................................................................78
InitializeApi() ...........................................................................................................................78
RuntimeApiEntry_Initialize ......................................................................................................79
.NET (C#) ................................................................................................................................80
Initialize ...................................................................................................................................80

7.3
7.3.1
7.3.1.1
7.3.1.2
7.3.1.3
7.3.1.4
7.3.2
7.3.2.1

Shut down API ........................................................................................................................81
Native C++ ..............................................................................................................................81
DestroyInterface() ...................................................................................................................82
RuntimeApiEntry_DestroyInterface .........................................................................................83
FreeApi() .................................................................................................................................84
ShutdownAndFreeApi()...........................................................................................................85
.NET (C#) ................................................................................................................................86
Shut down API ........................................................................................................................86

7.4

Global functions (Native C++) .................................................................................................86

7.5
7.5.1
7.5.2
7.5.3
7.5.4
7.5.4.1
7.5.4.2

API ISimulationRuntimeManager ............................................................................................90
Interfaces - Information and settings ......................................................................................90
Simulation Runtime instances ................................................................................................93
Remote connections .............................................................................................................101
Events ...................................................................................................................................106
OnConfigurationChanged .....................................................................................................106
OnRuntimeManagerLost .......................................................................................................110

7.6
7.6.1
7.6.2
7.6.3
7.6.4
7.6.5
7.6.5.1
7.6.5.2
7.6.5.3
7.6.5.4

API IInstances .......................................................................................................................113
Interfaces - Information and settings ....................................................................................113
Controller - Information and settings .....................................................................................119
Operating state .....................................................................................................................127
Tag list ..................................................................................................................................135
I/O access .............................................................................................................................141
I/O access via address - Reading .........................................................................................141
I/O access via address - Writing ...........................................................................................150
I/O access via tag name - Reading .......................................................................................158
I/O access via tag name - Writing .........................................................................................188

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

7

Table of contents

7.6.6
7.6.7
7.6.8
7.6.8.1
7.6.8.2
7.6.8.3
7.6.8.4
7.6.8.5

Settings for the virtual time .................................................................................................. 218
Cycle control ........................................................................................................................ 221
Events .................................................................................................................................. 227
OnOperatingStateChanged ................................................................................................. 228
OnEndOfCycle ..................................................................................................................... 232
OnConfigurationChanging ................................................................................................... 234
OnConfigurationChanged .................................................................................................... 237
OnLedChanged .................................................................................................................... 239

7.7
7.7.1
7.7.2
7.7.2.1
7.7.3
7.7.3.1

API IRemoteRuntimeManager ............................................................................................. 242
Interfaces - Information and settings.................................................................................... 242
Simulation Runtime instances.............................................................................................. 246
Simulation Runtime instances (remote) ............................................................................... 246
Events .................................................................................................................................. 254
OnConnectionLost ............................................................................................................... 254

7.8
7.8.1
7.8.1.1
7.8.1.2
7.8.2
7.8.2.1
7.8.2.2
7.8.2.3
7.8.2.4
7.8.2.5
7.8.2.6
7.8.2.7
7.8.2.8
7.8.3
7.8.3.1
7.8.3.2
7.8.3.3
7.8.3.4
7.8.3.5
7.8.3.6
7.8.3.7
7.8.3.8
7.8.4
7.8.5
7.8.5.1
7.8.5.2
7.8.6
7.8.6.1
7.8.6.2
7.8.6.3
7.8.6.4
7.8.6.5
7.8.6.6
7.8.6.7
7.8.6.8
7.8.6.9

Data types ............................................................................................................................ 257
DLL import functions (Native C++)....................................................................................... 258
ApiEntry_Initialize ................................................................................................................. 258
ApiEntry_DestroyInterface ................................................................................................... 258
Event callback functions (Native C++) ................................................................................. 259
EventCallback_VOID ........................................................................................................... 259
EventCallback_II_SREC_ST ................................................................................................ 259
EventCallback_II_SREC_ST_SROS_SROS ........................................................................ 260
EventCallback_II_SREC_ST_SRLT_SRLM ......................................................................... 261
EventCallback_II_SREC_ST_INT64_UINT32 ...................................................................... 262
EventCallback_IRRTM ......................................................................................................... 263
EventCallback_SRCC_UINT32_UINT32_INT32 .................................................................. 263
EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32 .......................... 264
Delegate definitions (managed code) .................................................................................. 265
Delegate_Void ...................................................................................................................... 265
Delegate_II_EREC_DT ........................................................................................................ 265
Delegate_II_EREC_DT_EOS_EOS...................................................................................... 266
Delegate_II_EREC_DT_ELT_ELM ....................................................................................... 267
Delegate_II_EREC_DT_INT64_UINT32 .............................................................................. 268
Delegate_IRRTM.................................................................................................................. 269
Delegate_SRCC_UINT32_UINT32_INT32 .......................................................................... 269
Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32 .................................. 270
Definitions and constants ..................................................................................................... 271
Unions (Native C++) ............................................................................................................ 272
UIP ....................................................................................................................................... 272
UDataValue .......................................................................................................................... 272
Structures ............................................................................................................................. 274
SDataValue .......................................................................................................................... 274
SDataValueByAddress ........................................................................................................ 276
SDataValueByName ............................................................................................................ 276
SConnectionInfo................................................................................................................... 277
SInstanceInfo ....................................................................................................................... 278
SDimension .......................................................................................................................... 279
STagInfo ............................................................................................................................... 280
SIP ....................................................................................................................................... 282
SIPSuite4 ............................................................................................................................. 283

S7-PLCSIM Advanced

8

Function Manual, 09/2016, A5E37039512-AA

Table of contents

7.8.7
7.8.7.1
7.8.7.2
7.8.7.3
7.8.7.4
7.8.7.5
7.8.7.6
7.8.7.7
7.8.7.8
7.8.7.9
7.8.7.10
7.8.7.11
7.8.7.12
7.8.7.13
8

A

Enumerations ........................................................................................................................284
ERuntimeErrorCode..............................................................................................................284
EArea ....................................................................................................................................286
EOperatingState ...................................................................................................................287
EOperatingMode ...................................................................................................................288
ECPUType ............................................................................................................................289
ECommunicationInterface ....................................................................................................291
ELEDType .............................................................................................................................292
ELEDMode ............................................................................................................................293
EPrimitiveDataType ..............................................................................................................294
EDataType ............................................................................................................................296
ETagListDetails .....................................................................................................................299
ERuntimeConfigChanged .....................................................................................................300
EInstanceConfigChanged .....................................................................................................300

Restrictions ......................................................................................................................................... 302
8.1

Overview ...............................................................................................................................302

8.2

OPC UA server .....................................................................................................................302

8.3

Web server ............................................................................................................................304

8.4

Restrictions for communications services.............................................................................305

8.5

Restrictions for instructions ...................................................................................................306

8.6
8.6.1
8.6.2

Restrictions with Motion Control ...........................................................................................307
Motion Control resources ......................................................................................................307
Technology modules .............................................................................................................308

8.7

Restrictions to local communication via Softbus ..................................................................308

8.8

Restrictions of security with VMware vSphere Hypervisor (ESXi) ........................................309

8.9

Error with overflow cyclical events ........................................................................................309

8.10

Deviating I/O values in the STEP 7 user program ................................................................310

8.11

Multiple simulations and possible collision of IP addresses .................................................310

8.12

Lacking access to an IP address ..........................................................................................310

8.13

Simulation in standby mode ..................................................................................................310

8.14

Error installing the antivirus software from Kaspersky ..........................................................311

List of abbreviations ............................................................................................................................ 312

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

9

Table of contents

Tables
Table 3- 1

Minimum requirements for hardware and software ..................................................................... 32

Table 5- 1

Assignment of the Ethernet interfaces, for example, a CPU 1518-4 PN/DP ............................... 52

Table 5- 2

Supported communication options ............................................................................................... 54

Table 7- 1

Overview of initializing and shutting down API - Native C++ ....................................................... 69

Table 7- 2

Overview of global functions - Native C++ ................................................................................... 69

Table 7- 3

Overview of API ISimulationRuntimeManager functions - Native C++ ........................................ 70

Table 7- 4

Overview of IInstances functions - Native C++ ............................................................................ 70

Table 7- 5

Overview of IRemoteRuntimeManager functions - Native C++ ................................................... 72

Table 7- 6

Overview of initializing and shutting down API - .NET (C#) ......................................................... 73

Table 7- 7

Overview of ISimulationRuntimeManager functions - .NET (C#)................................................. 73

Table 7- 8

Overview of IInstances functions - .NET (C#) .............................................................................. 74

Table 7- 9

Overview of IRemoteRuntimeManager functions - .NET (C#) ..................................................... 75

Table 7- 10

Overview of data types - Native C++ ........................................................................................... 76

Table 7- 11

Overview of data types - .NET (C#) ............................................................................................. 77

Table 7- 12

InitializeApi() - Native C++ ........................................................................................................... 78

Table 7- 13

RuntimeApiEntry_Initialize - Native C++ ...................................................................................... 79

Table 7- 14

Initialize - .NET (C#) ..................................................................................................................... 80

Table 7- 15

DestroyInterface() - Native C++ ................................................................................................... 82

Table 7- 16

RuntimeApiEntry_DestroyInterface() - Native C++ ...................................................................... 83

Table 7- 17

FreeApi() - Native C++ ................................................................................................................. 84

Table 7- 18

ShutdownAndFreeApi() - Native C++ .......................................................................................... 85

Table 7- 19

GetNameOfAreaSection() - Native C++ ....................................................................................... 86

Table 7- 20

GetNameOfCPUType() - Native C++ ........................................................................................... 86

Table 7- 21

GetNameOfCommunicationInterface() - Native C++ ................................................................... 87

Table 7- 22

GetNameOfDataType() - Native C++ ........................................................................................... 87

Table 7- 23

GetNameOfErrorCode() - Native C++ .......................................................................................... 87

Table 7- 24

GetNameOfLEDMode() - Native C++ .......................................................................................... 87

Table 7- 25

GetNameOfLEDType() - Native C++ ........................................................................................... 88

Table 7- 26

GetNameOfOperatingMode() - Native C++ ................................................................................. 88

Table 7- 27

GetNameOfErrorCode() - Native C++ .......................................................................................... 88

Table 7- 28

GetNameOfOperatingState() - Native C++ .................................................................................. 88

Table 7- 29

GetNameOfPrimitiveDataType() - Native C++ ............................................................................. 89

Table 7- 30

GetNameOfTagListDetails() - Native C++ ................................................................................... 89

Table 7- 31

GetNameOfRuntimeConfigChanged() - Native C++ .................................................................... 89

Table 7- 32

GetNameOfInstanceConfigChanged() - Native C++ ................................................................... 89
S7-PLCSIM Advanced

10

Function Manual, 09/2016, A5E37039512-AA

Table of contents

Table 7- 33

GetVersion() - Native C++ ........................................................................................................... 90

Table 7- 34

Version { get; } - .NET (C#) .......................................................................................................... 90

Table 7- 35

IsInitialized() - Native C++ ............................................................................................................ 91

Table 7- 36

IsInitialized { get; } - .NET (C#) .................................................................................................... 91

Table 7- 37

IsRuntimeManagerAvailable() - Native C++ ................................................................................ 91

Table 7- 38

IsRuntimeManagerAvailable { get; } - .NET (C#) ......................................................................... 91

Table 7- 39

Shutdown() - Native C++ ............................................................................................................. 92

Table 7- 40

Shutdown() - .NET (C#) ............................................................................................................... 92

Table 7- 41

GetRegisteredInstancesCount() - Native C++ ............................................................................. 93

Table 7- 42

GetRegisteredInstanceInfoAt() - Native C++ ............................................................................... 93

Table 7- 43

RegisteredInstanceInfo { get; } - .NET (C#) ................................................................................. 94

Table 7- 44

RegisterInstance() - Native C++ .................................................................................................. 95

Table 7- 45

RegisterInstance() - .NET (C#) .................................................................................................... 96

Table 7- 46

RegisterCustomInstance() - Native C++ ...................................................................................... 97

Table 7- 47

RegisterCustomInstance() - .NET (C#) ........................................................................................ 98

Table 7- 48

CreateInterface() - Native C++..................................................................................................... 99

Table 7- 49

CreateInterface() - .NET (C#) .................................................................................................... 100

Table 7- 50

OpenPort() - Native C++ ............................................................................................................ 101

Table 7- 51

OpenPort() - .NET (C#) .............................................................................................................. 101

Table 7- 52

ClosePort() - Native C++ ............................................................................................................ 102

Table 7- 53

ClosePort() - .NET (C#) ............................................................................................................. 102

Table 7- 54

GetPort() - Native C++ ............................................................................................................... 102

Table 7- 55

Port { get; } - .NET (C#) .............................................................................................................. 102

Table 7- 56

GetRemoteConnectionsCount() - Native C++ ........................................................................... 103

Table 7- 57

GetRemoteConnectionInfoAt()- Native C++ .............................................................................. 103

Table 7- 58

RemoteConnectionInfo { get; } - .NET (C#) ............................................................................... 103

Table 7- 59

RemoteConnect() - Native C++ ................................................................................................. 104

Table 7- 60

RemoteConnect() - .NET (C#) ................................................................................................... 105

Table 7- 61

Events for the ISimulationRuntimeManager interface ............................................................... 106

Table 7- 62

OnConfigurationChanged - .NET (C#) ....................................................................................... 106

Table 7- 63

RegisterOnConfigurationChangedCallback() - Native C++ ....................................................... 107

Table 7- 64

RegisterOnConfigurationChangedEvent() - Native C++ ............................................................ 107

Table 7- 65

RegisterOnConfigurationChangedEvent() - .NET (C#).............................................................. 107

Table 7- 66

UnregisterOnConfigurationChangedCallback() - Native C++ .................................................... 108

Table 7- 67

UnregisterOnConfigurationChangedEvent() - Native C++ ........................................................ 108

Table 7- 68

UnregisterOnConfigurationChangedEvent() - .NET (C#) .......................................................... 108

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

11

Table of contents

Table 7- 69

WaitForOnConfigurationChangedEvent() - Native C++ ............................................................. 109

Table 7- 70

WaitForOnConfigurationChangedEvent - .NET (C#) ................................................................. 109

Table 7- 71

OnRuntimeManagerLost - .NET (C#) ........................................................................................ 110

Table 7- 72

RegisterOnRuntimeManagerLostCallback() - Native C++ ......................................................... 110

Table 7- 73

RegisterOnRuntimeManagerLostEvent() - Native C++ ............................................................. 111

Table 7- 74

RegisterOnRuntimeManagerLostEvent() - .NET (C#) ............................................................... 111

Table 7- 75

UnregisterOnRuntimeManagerLostCallback() - Native C++...................................................... 111

Table 7- 76

UnregisterOnRuntimeManagerLostEvent() - Native C++ .......................................................... 112

Table 7- 77

UnregisterOnRuntimeManagerLostEvent() - .NET (C#) ............................................................ 112

Table 7- 78

WaitForOnRuntimeManagerLostEvent() - Native C++ .............................................................. 112

Table 7- 79

WaitForOnRuntimeManagerLostEvent() - .NET (C#) ................................................................ 112

Table 7- 80

Dispose() - .NET (C#) ................................................................................................................ 113

Table 7- 81

GetID() - Native C++ .................................................................................................................. 113

Table 7- 82

ID { get; } - .NET (C#) ................................................................................................................. 113

Table 7- 83

GetName() - Native C++ ............................................................................................................ 114

Table 7- 84

Name { get; } - .NET (C#) ........................................................................................................... 114

Table 7- 85

GetCPUType() - Native C++ ...................................................................................................... 115

Table 7- 86

SetCPUType() - Native C++....................................................................................................... 115

Table 7- 87

CPUType { get; set; } - .NET (C#) .............................................................................................. 115

Table 7- 88

GetCommunicationInterface() - Native C++............................................................................... 116

Table 7- 89

SetCommunicationInterface() - Native C++ ............................................................................... 116

Table 7- 90

CommunicationInterface { get; set; } - .NET (C#) ...................................................................... 117

Table 7- 91

GetInfo() - Native C++ ................................................................................................................ 117

Table 7- 92

Info { get; } - .NET (C#) .............................................................................................................. 117

Table 7- 93

UnregisterInstance() - Native C++ ............................................................................................. 118

Table 7- 94

UnregisterInstance() - .NET (C#) ............................................................................................... 118

Table 7- 95

GetControllerName() - Native C++ ............................................................................................ 119

Table 7- 96

ControllerName { get; } - .NET (C#) ........................................................................................... 119

Table 7- 97

GetControllerShortDesignation() - Native C++ .......................................................................... 120

Table 7- 98

ControllerShortDesignation { get; } - .NET (C#) ......................................................................... 120

Table 7- 99

GetControllerIPCount() - Native C++ ......................................................................................... 120

Table 7- 100

GetControllerIP() - Native C++ ................................................................................................... 121

Table 7- 101

ControllerIP { get; } - .NET (C#) ................................................................................................. 121

Table 7- 102

GetControllerIPSuite4() Native C++ ........................................................................................... 121

Table 7- 103

ControllerIPSuite4 { get; } - .NET (#) .......................................................................................... 121

Table 7- 104

SetIPSuite() - Native C++........................................................................................................... 122
S7-PLCSIM Advanced

12

Function Manual, 09/2016, A5E37039512-AA

Table of contents

Table 7- 105

SetIPSuite() - .NET (C#) ............................................................................................................ 122

Table 7- 106

GetStoragePath() - Native C++.................................................................................................. 123

Table 7- 107

SetStoragePath() - Native C++ .................................................................................................. 124

Table 7- 108

StoragePath { get; set; } - .NET (C#) ......................................................................................... 124

Table 7- 109

ArchiveStorage() - Native C++ ................................................................................................... 125

Table 7- 110

ArchiveStorage() - .NET (C#)..................................................................................................... 125

Table 7- 111

RetrieveStorage() - Native C++ ................................................................................................. 126

Table 7- 112

RetrieveStorage() - .NET (C#) ................................................................................................... 126

Table 7- 113

GetOperatingState() - Native C++ ............................................................................................. 127

Table 7- 114

OperatingState { get; } - .NET (C#) ............................................................................................ 128

Table 7- 115

PowerOn() - Native C++ ............................................................................................................ 129

Table 7- 116

PowerOn() - .NET (C#) .............................................................................................................. 130

Table 7- 117

PowerOff() - Native C++ ............................................................................................................ 131

Table 7- 118

PowerOff() - .NET (C#) .............................................................................................................. 131

Table 7- 119

MemoryReset() - Native C++ ..................................................................................................... 132

Table 7- 120

MemoryReset() - .NET (C#) ....................................................................................................... 132

Table 7- 121

Run() - Native C++ ..................................................................................................................... 133

Table 7- 122

Run() - .NET (C#) ....................................................................................................................... 133

Table 7- 123

Stop() - Native C++ .................................................................................................................... 134

Table 7- 124

Stop() - .NET (C#) ...................................................................................................................... 134

Table 7- 125

UpdateTagList() - Native C++ .................................................................................................... 136

Table 7- 126

UpdateTagList() - .NET (C#) ...................................................................................................... 137

Table 7- 127

GetTagListStatus() - Native C++................................................................................................ 138

Table 7- 128

GetTagListStatus() - .NET (C#) ................................................................................................. 138

Table 7- 129

GetTagInfoCount() - Native C++ ................................................................................................ 138

Table 7- 130

GetTagInfos() - Native C++ ........................................................................................................ 139

Table 7- 131

TagInfos { get; } - .NET (C#) ...................................................................................................... 139

Table 7- 132

CreateConfigurationFile() - Native C++ ..................................................................................... 140

Table 7- 133

CreateConfigurationFile() - .NET (C#) ....................................................................................... 140

Table 7- 134

InputArea { get; } MarkerArea { get; } OutputArea { get; } - .NET (C#) ...................................... 141

Table 7- 135

GetAreaSize() - Native C++ ....................................................................................................... 141

Table 7- 136

AreaSize { get; } - .NET (C#)...................................................................................................... 141

Table 7- 137

ReadBit() - Native C++ ............................................................................................................... 142

Table 7- 138

ReadBit() - .NET (C#) ................................................................................................................ 143

Table 7- 139

ReadByte() - Native C++ ............................................................................................................ 144

Table 7- 140

ReadByte() - .NET (C#) ............................................................................................................. 145

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

13

Table of contents

Table 7- 141

ReadByte() - Native C++ ............................................................................................................ 146

Table 7- 142

ReadBytes() - .NET (C#) ............................................................................................................ 147

Table 7- 143

ReadSignals() - Native C++ ....................................................................................................... 148

Table 7- 144

ReadSignals() - .NET (C#) ......................................................................................................... 149

Table 7- 145

WriteBit() - Native C++ ............................................................................................................... 150

Table 7- 146

WriteBit() - .NET (C#) ................................................................................................................. 151

Table 7- 147

WriteByte() - Native C++ ............................................................................................................ 152

Table 7- 148

WriteByte() - .NET (C#) .............................................................................................................. 153

Table 7- 149

WriteBytes() - Native C++ .......................................................................................................... 154

Table 7- 150

WriteBytes() - .NET (C#) ............................................................................................................ 155

Table 7- 151

WriteSignals() - Native C++ ....................................................................................................... 156

Table 7- 152

WriteSignals() - .NET (C#) ......................................................................................................... 157

Table 7- 153

Read() - Native C++ ................................................................................................................... 158

Table 7- 154

Read() - .NET (C#) ..................................................................................................................... 159

Table 7- 155

ReadBool() - Native C++ ............................................................................................................ 160

Table 7- 156

ReadBool() - .NET (C#).............................................................................................................. 161

Table 7- 157

ReadInt8() - Native C++ ............................................................................................................. 162

Table 7- 158

ReadInt8() - .NET (C#) ............................................................................................................... 163

Table 7- 159

ReadInt16() - Native C++ ........................................................................................................... 164

Table 7- 160

ReadInt16() - .NET (C#) ............................................................................................................. 165

Table 7- 161

ReadInt32() - Native C++ ........................................................................................................... 166

Table 7- 162

ReadInt32() - .NET (C#) ............................................................................................................. 167

Table 7- 163

ReadInt64() - Native C++ ........................................................................................................... 168

Table 7- 164

ReadInt64() - .NET (C#) ............................................................................................................. 169

Table 7- 165

ReadUInt8() - Native C++ .......................................................................................................... 170

Table 7- 166

ReadUInt8() - .NET (C#) ............................................................................................................ 171

Table 7- 167

ReadUInt16() - Native C++ ........................................................................................................ 172

Table 7- 168

ReadUInt16() - .NET (C#) .......................................................................................................... 173

Table 7- 169

ReadUInt32() - Native C++ ........................................................................................................ 174

Table 7- 170

ReadUInt32() - .NET (C#) .......................................................................................................... 175

Table 7- 171

ReadInt64() - Native C++ ........................................................................................................... 176

Table 7- 172

ReadUInt64() - .NET (C#) .......................................................................................................... 177

Table 7- 173

ReadFloat() - Native C++ ........................................................................................................... 178

Table 7- 174

ReadFloat() - .NET (C#) ............................................................................................................. 179

Table 7- 175

ReadDouble() - Native C++........................................................................................................ 180

Table 7- 176

ReadDouble() - .NET (C#) ......................................................................................................... 181
S7-PLCSIM Advanced

14

Function Manual, 09/2016, A5E37039512-AA

Table of contents

Table 7- 177

ReadChar() - Native C++ ........................................................................................................... 182

Table 7- 178

ReadChar() - .NET (C#) ............................................................................................................. 183

Table 7- 179

ReadWChar() - Native C++ ........................................................................................................ 184

Table 7- 180

ReadWChar() - .NET (C#) ......................................................................................................... 185

Table 7- 181

ReadSignals() - Native C++ ....................................................................................................... 186

Table 7- 182

ReadSignals() - .NET (C#) ......................................................................................................... 187

Table 7- 183

Write() - Native C++ ................................................................................................................... 188

Table 7- 184

Write() - .NET (C#) ..................................................................................................................... 189

Table 7- 185

WriteBool() - Native C++ ............................................................................................................ 190

Table 7- 186

WriteBool() - .NET (C#) .............................................................................................................. 191

Table 7- 187

WriteInt8() - Native C++ ............................................................................................................. 192

Table 7- 188

WriteInt8() - .NET (C#) ............................................................................................................... 193

Table 7- 189

WriteInt16() - Native C++ ........................................................................................................... 194

Table 7- 190

WriteInt16() - .NET (C#) ............................................................................................................. 195

Table 7- 191

WriteInt32() - Native C++ ........................................................................................................... 196

Table 7- 192

WriteInt32() - .NET (C#) ............................................................................................................. 197

Table 7- 193

WriteInt64() - Native C++ ........................................................................................................... 198

Table 7- 194

WriteInt64() - .NET (C#) ............................................................................................................. 199

Table 7- 195

WriteUInt8() - Native C++ .......................................................................................................... 200

Table 7- 196

WriteUInt8() - .NET (C#) ............................................................................................................ 201

Table 7- 197

WriteUInt16() - Native C++ ........................................................................................................ 202

Table 7- 198

WriteUInt16() - .NET (C#) .......................................................................................................... 203

Table 7- 199

WriteUInt32() - Native C++ ........................................................................................................ 204

Table 7- 200

WriteUInt32() - .NET (C#) .......................................................................................................... 205

Table 7- 201

WriteUInt64() - Native C++ ........................................................................................................ 206

Table 7- 202

WriteUInt64() - .NET (C#) .......................................................................................................... 207

Table 7- 203

WriteFloat() - Native C++ ........................................................................................................... 208

Table 7- 204

WriteFloat() - .NET (C#) ............................................................................................................. 209

Table 7- 205

WriteDouble() - Native C++ ........................................................................................................ 210

Table 7- 206

WriteDouble() - .NET (C#) ......................................................................................................... 211

Table 7- 207

WriteChar() - Native C++ ........................................................................................................... 212

Table 7- 208

WriteChar() - .NET (C#) ............................................................................................................. 213

Table 7- 209

WriteWChar() - Native C++ ........................................................................................................ 214

Table 7- 210

WriteWChar() - .NET (C#) .......................................................................................................... 215

Table 7- 211

WriteSignals() - Native C++ ....................................................................................................... 216

Table 7- 212

WriteSignals() - .NET (C#) ......................................................................................................... 217

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

15

Table of contents

Table 7- 213

GetSystemTime() - Native C++ .................................................................................................. 218

Table 7- 214

SetSystemTime() - Native C++ .................................................................................................. 218

Table 7- 215

SystemTime { get; set; } - .NET (C#) ......................................................................................... 218

Table 7- 216

GetScaleFactor() - Native C++ .................................................................................................. 219

Table 7- 217

SetScaleFactor() - Native C++ ................................................................................................... 219

Table 7- 218

ScaleFactor { get; set; } - .NET (C#) .......................................................................................... 220

Table 7- 219

GetOperatingMode() - Native C++ ............................................................................................. 221

Table 7- 220

SetOperatingMode() - Native C++ ............................................................................................. 221

Table 7- 221

OperatingMode { get; set; } - .NET (C#) ..................................................................................... 221

Table 7- 222

SetAlwaysSendOnEndOfCycleEnabled() - Native C++ ............................................................. 222

Table 7- 223

IsAlwaysSendOnEndOfCycleEnabled() - Native C++ ............................................................... 222

Table 7- 224

IsAlwaysSendOnEndOfCycleEnabled { get; set; } - .NET (C#) ................................................. 222

Table 7- 225

GetOverwrittenMinimalCycleTime_ns() - Native C++ ................................................................ 223

Table 7- 226

SetOverwrittenMinimalCycleTime_ns() - Native C++ ................................................................ 223

Table 7- 227

OverwrittenMinimalCycleTime_ns { get; set; } - .NET (C#) ........................................................ 224

Table 7- 228

RunNextCycle() - Native C++..................................................................................................... 225

Table 7- 229

RunNextCycle() - .NET (C#) ...................................................................................................... 225

Table 7- 230

StartProcessing() - Native C++ .................................................................................................. 226

Table 7- 231

StartProcessing() - .NET (C#) .................................................................................................... 226

Table 7- 232

Events for the IInstances interface ............................................................................................. 227

Table 7- 233

OnOperatingStateChanged - .NET (C#) .................................................................................... 228

Table 7- 234

RegisterOnOperatingStateChangedCallback() - Native C++ .................................................... 228

Table 7- 235

RegisterOnOperatingStateChangedEvent() - Native C++ ......................................................... 229

Table 7- 236

UnregisterOnOperatingStateChangedCallback() - Native C++ ................................................. 230

Table 7- 237

UnregisterOnOperatingStateChangedEvent() - Native C++ ...................................................... 231

Table 7- 238

UnregisterOnOperatingStateChangedEvent() - .NET (C#)........................................................ 231

Table 7- 239

WaitForOnOperatingStateChangedEvent() - Native C++ .......................................................... 231

Table 7- 240

WaitForOnOperatingStateChangedEvent() - .NET (C#) ............................................................ 231

Table 7- 241

OnEndOfCycle - .NET (C#) ........................................................................................................ 232

Table 7- 242

RegisterOnEndOfCycleCallback() - Native C++ ........................................................................ 232

Table 7- 243

RegisterOnEndOfCycleEvent() - Native C++ ............................................................................. 232

Table 7- 244

UnregisterOnEndOfCycleCallback() - Native C++ ..................................................................... 233

Table 7- 245

RegisterOnEndOfCycleEvent() - Native C++ ............................................................................. 233

Table 7- 246

UnregisterOnEndOfCycleEvent() - .NET (C#) ........................................................................... 233

Table 7- 247

WaitForOnEndOfCycleEvent() - Native C++.............................................................................. 234

Table 7- 248

WaitForOnEndOfCycleEvent() - .NET (C#) ............................................................................... 234
S7-PLCSIM Advanced

16

Function Manual, 09/2016, A5E37039512-AA

Table of contents

Table 7- 249

OnConfigurationChanging - .NET (C#) ...................................................................................... 234

Table 7- 250

RegisterOnConfigurationChangingCallback() - Native C++ ...................................................... 235

Table 7- 251

RegisterOnConfigurationChangingEvent() - Native C++ ........................................................... 235

Table 7- 252

UnregisterOnConfigurationChangingCallback() - Native C++ ................................................... 235

Table 7- 253

UnregisterOnConfigurationChangingEvent() - Native C++ ........................................................ 236

Table 7- 254

UnregisterOnConfigurationChangingEvent() - .NET (C#).......................................................... 236

Table 7- 255

WaitForOnConfigurationChangingEvent() - Native C++ ............................................................ 236

Table 7- 256

WaitForOnConfigurationChangingEvent() - .NET (C#).............................................................. 236

Table 7- 257

OnConfigurationChanged - .NET (C#) ....................................................................................... 237

Table 7- 258

RegisterOnConfigurationChangedCallback() - Native C++ ....................................................... 237

Table 7- 259

RegisterOnConfigurationChangedEvent() - Native C++ ............................................................ 237

Table 7- 260

UnregisterOnConfigurationChangedCallback() - Native C++ .................................................... 238

Table 7- 261

UnregisterOnConfigurationChangedEvent() - Native C++ ........................................................ 238

Table 7- 262

UnregisterOnConfigurationChangedEvent() - .NET (C#) .......................................................... 238

Table 7- 263

WaitForOnConfigurationChangedEvent() - Native C++............................................................. 239

Table 7- 264

WaitForOnConfigurationChangedEvent() - .NET (C#) .............................................................. 239

Table 7- 265

OnLedChanged - .NET (C#) ...................................................................................................... 239

Table 7- 266

RegisterOnLedChangedCallback() - Native C++....................................................................... 240

Table 7- 267

RegisterOnLedChangedEvent() - Native C++ ........................................................................... 240

Table 7- 268

UnregisterOnLedChangedCallback() - Native C++ ................................................................... 240

Table 7- 269

UnregisterOnLedChangedEvent() - Native C++ ........................................................................ 241

Table 7- 270

UnregisterOnLedChangedEvent() - .NET (C#) .......................................................................... 241

Table 7- 271

WaitForOnLedChangedEvent() - Native C++ ............................................................................ 241

Table 7- 272

WaitForOnLedChangedEvent() - .NET (C#) .............................................................................. 241

Table 7- 273

Dispose() - .NET (C#) ................................................................................................................ 242

Table 7- 274

GetVersion() - Native C++ ......................................................................................................... 242

Table 7- 275

Version { get; } - .NET (C#) ........................................................................................................ 242

Table 7- 276

GetIP() - Native C++ .................................................................................................................. 243

Table 7- 277

IP { get; } - .NET (C#) ................................................................................................................. 243

Table 7- 278

GetPort() - Native C++ ............................................................................................................... 243

Table 7- 279

Port { get; } - .NET (C#) .............................................................................................................. 243

Table 7- 280

GetRemoteComputerName() - Native C++ ............................................................................... 244

Table 7- 281

RemoteComputerName { get; } - .NET (C#) .............................................................................. 244

Table 7- 282

Disconnect() - Native C++ .......................................................................................................... 245

Table 7- 283

Disconnect() - .NET (C#) ........................................................................................................... 245

Table 7- 284

GetRegisteredInstancesCount() - Native C++ ........................................................................... 246

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

17

Table of contents

Table 7- 285

GetRegisteredInstanceInfoAt() - Native C++ ............................................................................. 246

Table 7- 286

RegisterInstanceInfo { get; } - .NET (C#) ................................................................................... 247

Table 7- 287

RegisterInstance() - Native C++ ................................................................................................ 248

Table 7- 288

RegisterInstance() - .NET (C#) .................................................................................................. 249

Table 7- 289

RegisterCustomInstance() - Native C++ .................................................................................... 250

Table 7- 290

RegisterCustomInstance() - .NET (C#) ...................................................................................... 251

Table 7- 291

CreateInterface() - Native C++ ................................................................................................... 252

Table 7- 292

CreateInterface() - .NET (C#)..................................................................................................... 253

Table 7- 293

OnConnectionLost - .NET (C#) .................................................................................................. 254

Table 7- 294

RegisterOnConnectionLostCallback() - Native C++ .................................................................. 254

Table 7- 295

RegisterOnConnectionLostEvent() - Native C++ ....................................................................... 255

Table 7- 296

RegisterOnConnectionLostEvent() - .NET (C#) ......................................................................... 255

Table 7- 297

UnregisterOnConnectionLostCallback() - Native C++ ............................................................... 255

Table 7- 298

UnregisterOnConnectionLostEvent() - Native C++ .................................................................... 256

Table 7- 299

UnregisterOnConnectionLostEvent() - .NET (C#) ..................................................................... 256

Table 7- 300

WaitForOnConnectionLostEvent() - Native C++ ........................................................................ 256

Table 7- 301

WaitForOnConnectionLostEvent() - .NET (C#).......................................................................... 256

Table 7- 302

ApiEntry_Initialize - Native C++ ................................................................................................. 258

Table 7- 303

ApiEntry_DestroyInterface - Native C++ .................................................................................... 258

Table 7- 304

EventCallback_VOID - Native C++ ............................................................................................ 259

Table 7- 305

EventCallback_II_SREC_ST - Native C++ ................................................................................. 259

Table 7- 306

EventCallback_II_SREC_ST_SROS_SROS - Native C++ ......................................................... 260

Table 7- 307

EventCallback_II_SREC_ST_SRLT_SRLM - Native C++ .......................................................... 261

Table 7- 308

EventCallback_II_SREC_ST_INT64_UINT32 - Native C++ ....................................................... 262

Table 7- 309

EventCallback_IRRTM - Native C++ .......................................................................................... 263

Table 7- 310

EventCallback_SRCC_UINT32_UINT32_INT32 - Native C++................................................... 263

Table 7- 311

EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32 - Native C++........... 264

Table 7- 312

Delegate_Void - .NET (C#) ........................................................................................................ 265

Table 7- 313

Delegate_II_EREC_DT - .NET (C#) ........................................................................................... 265

Table 7- 314

Delegate_II_EREC_DT_EOS_EOS - .NET (C#) ........................................................................ 266

Table 7- 315

Delegate_II_EREC_DT_ELT_ELM - .NET (C#) ......................................................................... 267

Table 7- 316

Delegate_II_EREC_DT_INT64_UINT32 - .NET (C#) ................................................................. 268

Table 7- 317

Delegate_IRRTM - .NET (C#) .................................................................................................... 269

Table 7- 318

Delegate_SRCC_UINT32_UINT32_INT32 - .NET (C#) ............................................................. 269

Table 7- 319

Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32 - .NET (C#) ..................... 270

Table 7- 320

Definitions and constants - Native C++ ...................................................................................... 271
S7-PLCSIM Advanced

18

Function Manual, 09/2016, A5E37039512-AA

Table of contents

Table 7- 321

Definitions and constants - .NET (C#) ....................................................................................... 271

Table 7- 322

UIP - Native C++ ........................................................................................................................ 272

Table 7- 323

UDataValue - Native C++ .......................................................................................................... 272

Table 7- 324

SDataValue - Native C++ ........................................................................................................... 274

Table 7- 325

SDataValue - .NET (C#) ............................................................................................................ 274

Table 7- 326

SDataValueByAddress - Native C++ ......................................................................................... 276

Table 7- 327

SDataValueByAddress - .NET (C#) ........................................................................................... 276

Table 7- 328

SDataValueByName - Native C++ ............................................................................................. 276

Table 7- 329

SDataValueByName - .NET (C#)............................................................................................... 276

Table 7- 330

SConnectionInfo - Native C++ ................................................................................................... 277

Table 7- 331

SConnectionInfo - .NET (C#) ..................................................................................................... 277

Table 7- 332

SInstanceInfo - Native C++ ........................................................................................................ 278

Table 7- 333

SInstanceInfo - .NET (C#) .......................................................................................................... 278

Table 7- 334

SDimension - Native C++ .......................................................................................................... 279

Table 7- 335

SDimension - .NET (C#) ............................................................................................................ 279

Table 7- 336

STagInfo - Native C++ ............................................................................................................... 280

Table 7- 337

STagInfo - .NET (C#) ................................................................................................................. 281

Table 7- 338

SIP - .NET (C#) .......................................................................................................................... 282

Table 7- 339

SIPSuite4 - Native C++ .............................................................................................................. 283

Table 7- 340

SIPSuite4 - .NET (C#) ................................................................................................................ 283

Table 7- 341

ERuntimeErrorCode - Native C++ ............................................................................................. 284

Table 7- 342

ERuntimeErrorCode - .NET (C#) ............................................................................................... 285

Table 7- 343

EArea - Native C++ .................................................................................................................... 286

Table 7- 344

EArea - .NET (C#) ...................................................................................................................... 286

Table 7- 345

EOperatingState - Native C++ ................................................................................................... 287

Table 7- 346

EOperatingState - .NET (C#) ..................................................................................................... 287

Table 7- 347

EOperatingMode - Native C++................................................................................................... 288

Table 7- 348

EOperatingMode - .NET (C#) .................................................................................................... 288

Table 7- 349

ECPUType - Native C++ ............................................................................................................ 289

Table 7- 350

ECPUType - .NET (C#) .............................................................................................................. 290

Table 7- 351

ECommunicationInterface - Native C++ .................................................................................... 291

Table 7- 352

ECommunicationInterface - .NET (C#) ...................................................................................... 291

Table 7- 353

ELEDType - Native C++ ............................................................................................................ 292

Table 7- 354

ELEDType - .NET (C#) .............................................................................................................. 292

Table 7- 355

ELEDMode - Native C++ ........................................................................................................... 293

Table 7- 356

ELEDMode - .NET (C#) ............................................................................................................. 293

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

19

Table of contents

Table 7- 357

EPrimitiveDataType - Native C++ .............................................................................................. 294

Table 7- 358

EPrimitiveDataType - .NET (C#) ................................................................................................ 294

Table 7- 359

Compatible primitive data types - Reading ................................................................................ 295

Table 7- 360

Compatible primitive data types - Write ..................................................................................... 295

Table 7- 361

EDataType - Native C++ ............................................................................................................ 297

Table 7- 362

EDataType - .NET (C#) .............................................................................................................. 298

Table 7- 363

ETagListDetails - Native C++ ..................................................................................................... 299

Table 7- 364

ETagListDetails - .NET (C#)....................................................................................................... 299

Table 7- 365

ERuntimeConfigChanged - Native C++ ..................................................................................... 300

Table 7- 366

ERuntimeConfigChanged - .NET (C#) ....................................................................................... 300

Table 7- 367

EInstanceConfigChanged - Native C++ ..................................................................................... 300

Table 7- 368

EInstanceConfigChanged - .NET (C#) ....................................................................................... 300

Table 8- 1

Instructions not supported .......................................................................................................... 306

Table 8- 2

CPUs with limited Motion Control resources.............................................................................. 307

Figures
Figure 2-1

Enable simulation capability ......................................................................................................... 27

Figure 4-1

Local communication via Softbus ................................................................................................ 41

Figure 4-2

Local communication via TCP/IP ................................................................................................. 42

Figure 4-3

Distributed communication via Ethernet ...................................................................................... 42

Figure 4-4

Distributed communication via network adapters ........................................................................ 43

Figure 4-5

Activate PLCSIM Virtual Switch ................................................................................................... 44

Figure 4-6

Accessible devices on the Virtual Ethernet Adapter .................................................................... 44

Figure 5-1

PLCSIM Advanced Symbol .......................................................................................................... 46

Figure 5-2

Example: Message in the taskbar ................................................................................................ 46

Figure 5-3

Control Panel ............................................................................................................................... 48

Figure 5-4

Example: Download via the "PLCSIM Virtual Ethernet Adapter" (TCP/IP) after naming............. 51

Figure 5-5

Structure of the MAC address for an instance ............................................................................. 52

Figure 5-6

Add card reader ........................................................................................................................... 56

Figure 5-7

Preview of download dialog ......................................................................................................... 57

Figure 7-1

External applications and Simulation Runtime............................................................................. 66

Figure 7-2

Access to instances with distributed communication ................................................................... 67

Figure 7-3

API and external applications....................................................................................................... 68

Figure 8-1

Policy exceptions for VMware vSphere Hypervisor (ESXi) ........................................................ 309

S7-PLCSIM Advanced

20

Function Manual, 09/2016, A5E37039512-AA

Table of contents

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

21

1

Guide
1.1

Documentation Guide S7 PLCSIM Advanced
The documentation for the SIMATIC S7-1500 automation system and the SIMATIC
ET 200SP distributed I/O system is arranged into three areas.
Basic information
System manuals and Getting Started describe in detail the configuration, installation, wiring
and commissioning of the SIMATIC S7-1500 and ET 200SP systems. The STEP 7 online
help supports you in configuration and programming.
Device information
Product manuals contain a compact description of the module-specific information, such as
properties, terminal diagrams, characteristics and technical specifications.
General information
The function manuals contain detailed descriptions on general topics such as diagnostics,
communication, Motion Control, Web server, OPC UA.
You can download the documentation free of charge from the Internet
(http://w3.siemens.com/mcms/industrial-automation-systems-simatic/en/manualoverview/Pages/Default.aspx).
Changes and additions to the manuals are documented in product information sheets.
You will find the product information on the Internet:
● S7-1500 (https://support.industry.siemens.com/cs/us/en/view/68052815)
● ET 200SP (https://support.industry.siemens.com/cs/us/en/view/73021864)

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 (https://support.industry.siemens.com/cs/ww/en/view/86140384)
● ET 200SP (https://support.industry.siemens.com/cs/ww/en/view/84133942)

S7-PLCSIM Advanced

22

Function Manual, 09/2016, A5E37039512-AA

Guide
1.1 Documentation Guide S7 PLCSIM Advanced

"mySupport"
With "mySupport", your personal workspace, you make the best out of your Industry Online
Support.
In "mySupport", you can save filters, favorites and tags, request CAx data and compile your
personal library in the Documentation area. In addition, your data is already filled out in
support requests and you can get an overview of your current requests at any time.
You must register once to use the full functionality of "mySupport".
You can find "mySupport" on the Internet
(http://support.industry.siemens.com/My/ww/en/documentation).

"mySupport" - Documentation
In the Documentation area in "mySupport" you can combine entire manuals or only parts of
these to your own manual.
You can export the manual as PDF file or in a format that can be edited later.
You can find "mySupport" - Documentation 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 will find the application examples on the Internet
(https://support.industry.siemens.com/sc/ww/en/sc/2054).

TIA Selection Tool
The TIA Selection Tool can be used to select, configure and order devices for Totally
Integrated Automation (TIA). It assembles the configuration editors for automation
technology already familiar into a single tool.
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
(http://w3.siemens.com/mcms/topics/en/simatic/tia-selection-tool).

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

23

Guide
1.2 S7 PLCSIM products

1.2

S7 PLCSIM products

S7 PLCSIM Advanced
The version of S7-PLCSIM Advanced supports the following SIMATIC CPU series:
● S7-1500, S7-1500F, S7-1500C, S7-1500T and S7-1500TF
● ET 200SP and ET 200SP F
Communication
S7-PLCSIM Advanced supports communication via Softbus or TCP/IP.
S7 PLCSIM Advanced enables C++ and C# programs and simulation software to access
SIMATIC CPU series supported by S7-PLCSIM Advanced via the user interface (API).
S7-PLCSIM Advanced and S7-PLCSIM V12 cannot be installed on the same PC or the
same virtual machine. The communication between the two applications cannot be
simulated.
S7-PLCSIM V5.4 SP7 is automatically installed with S7-PLCSIM Advanced. The
communication between the two applications can be simulated.

S7-PLCSIM V14
The version of S7-PLCSIM supports the following SIMATIC CPU series:
● S7-1200 and S7-1200F
● S7-1500, S7-1500F, S7-1500C, S7-1500T and S7-1500TF
● ET 200SP and ET 200SP F
Communication
S7-PLCSIM V14 supports communication via Softbus.

S7-PLCSIM V5.x
S7-PLCSIM V5.x simulates the following SIMATIC CPU series:
● S7-300 and S7-300F
● S7-400 and S7-400F
S7-PLCSIM V5.x cannot be installed on the same PC or the same virtual machine
S7-PLCSIM as of V12.
S7-PLCSIM V5.4 SP7 is automatically installed with S7-PLCSIM Advanced.
Communication
S7 PLCSIM V5.x can communicate via Softbus with instances of S7-PLCSIM as of V12.
S7-PLCSIM V5.4 SP7 can communicate via Softbus with instances of S7-PLCSIM
Advanced.

S7-PLCSIM Advanced

24

Function Manual, 09/2016, A5E37039512-AA

Product overview
2.1

2

What is PLCSIM Advanced?
Simulation systems support the development of programs and the deployment in production
that follows. In the automation world, a simulated test environment shortens commissioning
times. It is possible to test the program after program changes in the virtual controller before
it is loaded into the corresponding real controller and the plant is put into operation.

S7 PLCSIM Advanced
Using S7-PLCSIM Advanced, you can simulate your CPU programs on a virtual controller.
You do not need a real controller for this. You can configure your CPU in STEP 7 V14,
program your application logic and then load the hardware configuration and the program
into the virtual controller. From there you can run your program logic, observe the effects of
simulated inputs and outputs and adapt your programs.
In addition to communicating via Softbus, S7-PLCSIM Advanced provides a full Ethernet
connection and can thus also communicate distributed.
User interface (API)
S7 PLCSIM Advanced enables interaction with native C++/C# programs or software via the
user interface.

Application areas
● Software in the Loop-Simulation for virtual commissioning of machine tools
● In combination with third-party software:
– Simulation of production machines and plants
– Combined simulation of automation and mechanics

Advantages
The use of S7 PLCSIM Advanced offers numerous advantages:
● Improve quality of automation projects
● Accelerate time to market
● Reduce production times
● Reduce risk for commissioning
● Avoid costs for hardware in simulation environments
● Increase efficiency in maintenance

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

25

Product overview
2.2 Security for PLCSIM Advanced

2.2

Security for PLCSIM Advanced

Restrictions for security
Note the following restrictions when using 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 WinPCap component provides access to TCP/IP network communication.
Note
For cross-computer communication, it is recommended to use a closed simulation network
that is not connected to a production network.
Know-how protection
Note
If know-how-protected blocks for the simulation support are enabled, the know-how
protection is limited.

S7-PLCSIM Advanced

26

Function Manual, 09/2016, A5E37039512-AA

Product overview
2.3 Simulations support

2.3

Simulations support

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 project properties.

Figure 2-1

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, to enable the "Simulation with SIMATIC S7-PLCSIM Advanced" option
to be unlocked in the properties of the block in the tab "General > Compilation".

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

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

27

Product overview
2.4 Supported CPUs

2.4

Supported CPUs

Supported CPUs from the S7-1500 family
S7-PLCSIM Advanced V1.0 supports the simulation of the following CPUs (all firmware
versions, V2.0 recommended):
Type
Standard CPUs

Fail-safe CPUs

Compact CPUs1
ET 200SP CPUs

Technology CPUs

CPU 1511-1 PN
CPU 1513-1 PN
CPU 1515-2 PN
CPU 1516-3 PN/DP
CPU 1517-3 PN/DP3
CPU 1518-4 PN/DP3
CPU 1518-4 PN/DP ODK2, 3
CPU 1511F-1 PN
CPU 1513F-1 PN
CPU 1515F-2 PN
CPU 1516F-3 PN/DP
CPU 1517F-3 PN/DP3
CPU 1518F-4 PN/DP3
CPU 1518F-4 PN/DP ODK2, 3
CPU 1511C-1 PN
CPU 1512C-1 PN
CPU 1510SP-1 PN
CPU 1510SP F-1 PN
CPU 1512SP-1 PN
CPU 1512SP F-1 PN
CPU 1511T-1 PN
CPU 1515T-2 PN
CPU 1517T-3 PN/DP3, 4
CPU 1517TF-3 PN/DP3, 4

Article number
6ES7511-1AK01-0AB0
6ES7513-1AL01-0AB0
6ES7515-2AM01-0AB0
6ES7516-3AN01-0AB0
6ES7517-3AP00-0AB0
6ES7518-4AP00-0AB0
6ES7518-4AP00-3AB0
6ES7511-1FK01-0AB0
6ES7513-1FL01-0AB0
6ES7515-2FM01-0AB0
6ES7516-3FN01-0AB0
6ES7517-3FP00-0AB0
6ES7518-4FP00-0AB0
6ES7518-4FP00-3AB0
6ES7511-1CK00-0AB0
6ES7512-1CK00-0AB0
6ES7510-1DJ01-0AB0
6ES7512-1SJ01-0AB0
6ES7512-1DK01-0AB0
6ES7512-1SK01-0AB0
6ES7511-1TK01-0AB0
6ES7515-2TM01-0AB0
6ES7517-3TP00-0AB0
6ES7517-3UP00-0AB0

1

The on-board I/O within the compact CPUs is not simulated. The simulation interface corresponds
to the process image.

2

The ODK functionality of this CPU is not simulated.

3

The simulation of this CPU only supports 5120 Motion Control resources.

4

The simulation of this CPU supports only 64 cams.

Unsupported CPUs
S7-PLCSIM Advanced V1.0 does not support the simulation of the following CPUs:
● S7-1200 CPUs
● ET 200pro, ET 200pro F CPUs
● ET 200SP Open Controller CPU 1515SP PC
● Software Controller

S7-PLCSIM Advanced

28

Function Manual, 09/2016, A5E37039512-AA

Product overview
2.5 Differences between a simulated and a real CPU

2.5

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. Therefore, 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 that several programs share
the processing resources on your PC.
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 protected blocks can only be simulated when they are enabled for
simulation. You need the block password for this purpose.

Instructions
Instructions are simulated with a few exceptions, for example, interrupts. Programs that are
based on the instructions behave different than real CPUs in the simulation.

See also
Restrictions for instructions (Page 306)

2.5.1

Restrictions for all supported CPUs

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

Bus systems
S7-PLCSIM Advanced does not simulate bus systems (PROFINET IO, PROFIBUS DP,
backplane bus).

Process image partitions
S7-PLCSIM Advanced always updates the address areas of the process image at the cycle
control point. Process image partitions between two cycle control points are not updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

29

Product overview
2.5 Differences between a simulated and a real CPU

Diagnostics
S7-PLCSIM Advanced cannot simulate the complete range of all the possible diagnostic
buffer entries, for example, no entries that affect the real hardware. Most I/O and program
errors are simulated.

Online and diagnostic functions
Some online and diagnostic functions are not very useful in the simulation and are therefore
not supported. These include, for example, the functions "Format memory card" and
"Firmware update".

Status indicators LED flashing
In STEP 7, you can have the LED displayed on an CPU flash using the "Extended download
to device" dialog. S7-PLCSIM Advanced does not simulate this function.

Data logging
S7-PLCSIM Advanced does not simulated data logging, because this function writes all
output to the SD memory card and S7-PLCSIM Advanced does not support the use of an SD
memory card.

Recipes
S7-PLCSIM Advanced does not simulate the use of recipes.

Backup and Restore
S7-PLCSIM Advanced does not simulate the product property "Backup and Restore".

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

S7-PLCSIM Advanced

30

Function Manual, 09/2016, A5E37039512-AA

Product overview
2.6 Simulating Motion Control

2.6

Simulating Motion Control

Restrictions
PLCSIM Advanced supports STEP 7 projects with configurations and functions for motion
control for the CPUs S7-1500, S7-1500F, S7-1500C, S7-1500T, S7-1500T F, ET 200SP and
ET 200SP F.
PLCSIM Advanced provides only limited support for technology objects in some CPUs, see
Restrictions with Motion Control (Page 307).

Simulation with external simulation software
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 S7PLCSIM Advanced and simulate the behavior of the other connected axes.

Simulation mode in STEP 7
The simulation mode is a standard function of the technology objects.
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.

Additional information
Information on "Setting in the drive and encoder connection" for actual value calculation of a
virtual axis and on the topic "Virtual axis/Simulation" is available in the S7-1500T Motion
Control (https://support.industry.siemens.com/cs/ww/en/view/109481326) function manual.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

31

3

Installing
3.1

Introduction

3.1.1

System requirements
You need high-performance computer hardware if you intend to run multiple instances of
PLCSIM Advanced at the same time or to simulate communication between PLCSIM
Advanced V1.0 and HMI devices as of version 14.0.

Minimum requirements for hardware and software
Preferably, you should install PLCSIM Advanced on a stand-alone PC, independent of
STEP 7. Alternatively, you can install PLCSIM Advanced on the configuration PC on which
STEP 7 is already installed.
For PLCSIM Advanced to operate efficiently, the computer hardware and software must
meet minimum requirements.
Table 3- 1

Minimum requirements for hardware and software

Hardware / software

Requirement

Processor

2.2 GHz Intel® Celeron® Dual Core

RAM

•

4 GB for one instance

•

8 GB for 4 instances

Free hard disk space

5 GB

Operating system

•

64-bit version

Windows 7 Home Premium SP1

•

Windows 7 Professional SP1

•

Windows 7 Enterprise SP1

•

Windows 7 Ultimate SP1

•

Windows Server 2012 R2 StdE (full installation)

Screen resolution

1024 x 768

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

S7-PLCSIM Advanced

32

Function Manual, 09/2016, A5E37039512-AA

Installing
3.1 Introduction

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.0
● VMware Workstation 12 Pro
● VMware Workstation Player 12
● Microsoft Windows Server 2012 R2 Hyper-V
Guest operating systems
You can use the following guest operating systems on the selected virtualization platform for
the installation of STEP 7 V14 and PLCSIM Advanced:
● Windows 7 Professional SP1 / Ultimate SP1 / Enterprise SP1 (64-Bit)
● Windows Server 2012 R2 (64-Bit)

3.1.2

Licenses

Floating license
S7 PLCSIM Advanced is supplied with a floating type license. These can be stored locally
and shared for a network.
Note
A floating license is valid for one instance of a virtual controller within a PLCSIM Advanced
installation.

Handling licenses
You can learn how to handle the licenses for S7 PLCSIM Advanced instances on the DVD in
the description of the SIMATIC Automation License Manager (ALM).

API functions for licenses
● Return values for API function PowerOn() (Page 127) and callback function
OnOperatingStateChanged (Page 228)
– SREC_OK when a license is available.
– SREC_WARNING_TRIAL_MODE_ACTIVE when no license is available, and an instance is
started in a mode that allows unrestricted use of the instance for one hour.
● Return value for callback function OnOperatingStateChanged
– SREC_LICENSE_NOT_FOUND when the instance is automatically shut down after expiration
of the Trial mode.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

33

Installing
3.1 Introduction

Warning in spite of existing license
Note
A check is made for the presence of a license at power-up and after one hour during which
you can test an instance without restriction (Trial Mode). When you import a license in the
meantime, SREC_WARNING_TRIAL_MODE_ACTIVE is returned nevertheless.

3.1.3

Installation log
The log files contains 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 directory by entering "cd %autinstlog%" in
the command line.
The log files are named as follows:
● SIA_S7-PLCSIM_Advanced_V01@.log
● SIA_S7-PLCSIM_Advanced_V01@_summary.log

Setup_Report (CAB file)
An archive file with the installation log and all other required files is stored in CAB format.
This archive file can be found at "%autinstlog%\Reports\Setup_report.cab".
If you need help during installation, send this CAB file to SIEMENS Technical Support.
Technical Support personnel can troubleshoot your installation based on the information in
the CAB file.
A separate CAB file with a date ID is saved for each installation.

S7-PLCSIM Advanced

34

Function Manual, 09/2016, A5E37039512-AA

Installing
3.2 Installation medium

3.2

Installation medium
After installing S7-PLCSIM Advanced, keep the installation medium in a secure, easily
accessible place.
You can use the installation medium to change, repair or uninstall, if necessary.

3.3

Installing PLCSIM Advanced
S7-PLCSIM Advanced starts the installation automatically when you insert the installation
medium in your DVD drive.

Installation requirements
Make sure that the following conditions are met before you begin the installation process:
● The hardware and software of the PC or Siemens Field PG meet the system
requirements.
● The person who performs the installation has administrator rights on the respective
computer.
● No other programs are active. This also applies to the Siemens Automation License
Manager and other Siemens applications.
● All S7-PLCSIM versions V12 and higher are uninstalled.
Note
Security settings
For licensing via the ALM, when installing PLCSIM Advanced you must agree that port 4410
for TCP can be entered as an exception in the Windows Firewall (procedure step 7).

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

35

Installing
3.3 Installing PLCSIM Advanced

Installing S7-PLCSIM Advanced
To install PLCSIM Advanced, follow these steps:
1. Insert the installation medium into the DVD drive of your computer. The setup program is
automatically started, provided you have not deactivated the Autostart function on the
Field PG or PC. 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. The check box for the English is selected.
3. Click the "Read installation notes" button to display installation information. After you
have read the notes, close the file.
4. Click the "Read Product Information" button to display the "Readme file". After you have
read the information, close the file.
5. 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.
6. 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.
7. 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".
8. Your installation details are displayed in the overview screen. Click the "Install" button.
The installation is then started and PLCSIM Advanced is installed on your computer.
9. 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.
10.Click "Restart". If the computer is not restarted, click "Finish".

Error during installation of S7-PLCSIM Advanced
When S7-PLCSIM Advanced is installed, any existing installation of S7-PLCSIM is
displayed.
A requirement for installation of S7-PLCSIM Advanced is that no other S7-PLCSIM
installation 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 V12 or V12 SP1 and uninstall the program.
When the setup is not available, download the setup files for S7-PLCSIM via Siemens Mall
(https://support.industry.siemens.com/cs/document/65601780).

S7-PLCSIM Advanced

36

Function Manual, 09/2016, A5E37039512-AA

Installing
3.4 Changing PLCSIM Advanced

3.4

Changing PLCSIM Advanced

Requirements for changing the installation
The following conditions must be met before you can start changing 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 for changing the installation
To change your PLCSIM Advanced installation, follow these steps:
1. Insert the installation medium into the drive. The setup program starts up automatically,
provided you have not deactivated the Autostart function on the Field PG or PC.
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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

37

Installing
3.5 Repairing PLCSIM Advanced

3.5

Repairing PLCSIM Advanced
If your installation becomes damaged, you can repair it with the PLCSIM Advanced data
storage medium.

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

Procedure for repairing the installation
To repair your installation, follow these steps:
1. Insert the installation medium into the drive. The setup program is automatically started,
provided you have not deactivated the Autostart function on the Field PG or PC. 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.

S7-PLCSIM Advanced

38

Function Manual, 09/2016, A5E37039512-AA

Installing
3.6 Uninstalling PLCSIM Advanced

3.6

Uninstalling PLCSIM Advanced
You have two options for uninstalling S7-PLCSIM Advanced on your computer:
● You uninstall the program using the Windows Control Panel.
● You uninstall the full product using the installation medium.

Uninstalling PLCSIM Advanced using the Windows Control Panel
To uninstall PLCSIM Advanced using the Windows Control Panel, follow these steps:
1. Double-click the "Programs and Features" option in the Windows Control Panel.
2. Right-click on "Siemens S7-PLCSIM Advanced V1.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 PLCSIM Advanced using the installation medium
To uninstall PLCSIM Advanced using the installation medium, follow these steps:
1. Insert the installation medium into the drive. The setup program is started automatically,
provided you have not deactivated the Autostart function on the programming device or
PC. If the setup program does not start up automatically, start it manually by doubleclicking 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 to uninstall PLCSIM Advanced.
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 PLCSIM Advanced is uninstalled, the following software remains installed:
● Automation License Manager
● S7-PLCSIM V5.4
● .NET Framework
● WinPcap
If you also want to uninstall this software, use the Windows Control Panel.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

39

4

Communication paths

Local and distributed communication
The following paths are open for communication between STEP 7 V14 and the instances of
PLCSIM Advanced user interfaces:
Communication paths

Local

Local

Distributed

Protocol

Softbus

TCP/IP

TCP/IP

Communication interface in
PLCSIM Advanced

PLCSIM

PLCSIM Virtual
PLCSIM Virtual
Ethernet Adapter Ethernet Adapter

STEP 7 and instances

on a PC / VM

on a PC / VM

distributed

between STEP 7 and instances

Yes

Yes

Yes

among instances

Yes

Yes

Yes

possible via OPC UA server and Web serv- No
er

Yes

Yes

between an instance and a real hardware
CPU

No

No

Yes

between an instance and a real HMI V14

No

No

Yes

between an instance and a simulated HMI
V14

Yes

Yes

No

Communication...

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.

Select communication interface
You program the communication interface via the user interface (API) or select it 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).

S7-PLCSIM Advanced

40

Function Manual, 09/2016, A5E37039512-AA

Communication paths
4.1 Local communication

API functions for selecting the communication interface
● GetCommunicationInterface() (Page 116)
● SetCommunicationInterface() (Page 116)
● CommunicationInterface { get; set; } (Page 117)

See also
Interfaces - Information and settings (Page 113)
S7 PLCSIM Advanced Control Panel (Page 46)

4.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 (VMware) as STEP 7 or another communication partner.

Local communication via Softbus
For security reasons, the local communication is performed via Softbus in PLCSIM
Advanced by default.

Figure 4-1

Local communication via Softbus

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

41

Communication paths
4.2 Communication via TCP / IP

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.

Figure 4-2

4.2

Local communication via TCP/IP

Communication via TCP / IP

Distributed communication
Distributed communication via TCP/IP means that the PLCSIM Advanced instances
communicate with the other devices via the Virtual Switch . Communication is possible with
real or simulated CPUs, real or simulated HMIs.
The PLCSIM Virtual Switch must be activated on the PLCSIM Virtual Ethernet Adapter for
instances on the network to be visible.

Example 1: Distributed communication
In the following example, STEP 7 is on a PC and the PLCSIM Advanced instances are on
another PC. The PCs are connected via the Ethernet adapter.

Figure 4-3

Distributed communication via Ethernet

S7-PLCSIM Advanced

42

Function Manual, 09/2016, A5E37039512-AA

Communication paths
4.3 Enable distributed communication

Example 2: Distributed communication
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 network
adapters.
Recommendation
Use to ensure the VMware settings as the network adapter type for the Bridged Mode to
ensure error-free operation.

Figure 4-4

4.3

Distributed communication via network adapters

Enable distributed communication
By default, the PLCSIM Virtual Switch can only communicate locally. For a distributed, i.e.
multi-computer, communication to be possible, you must activate the PLCSIM Virtual Switch
for a real network adapter.
Note
Network adapter
Make sure that only one network adapter of the PLCSIM Virtual Switch is activated.
The Control Panel of PLCSIM Advanced checks the activation and may report an incorrect
configuration (error code -50).

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

43

Communication paths
4.3 Enable distributed communication

Activate PLCSIM Virtual Switch
To make the PLCSIM instances visible on the network and to reach other devices, activate
the PLCSIM 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 "Siemens PLCSIM Virtual Switch" and confirm with OK.

Figure 4-5

Activate PLCSIM Virtual Switch

Accessible devices
When the PLCSIM Virtual Switch is activated, STEP 7 shows the devices available on the
Virtual Ethernet Adapter in the project tree.

Figure 4-6

Accessible devices on the Virtual Ethernet Adapter

S7-PLCSIM Advanced

44

Function Manual, 09/2016, A5E37039512-AA

Simulate CPU
5.1

5

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 V14 and S7 PLCSIM V1.0 Advanced 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".

Create and activate an instance via the Control Panel
● Open PLCSIM Advanced Control Panel
● Open the "Start Virtual S7-1500 PLC" options
● Enter a name for an instance
● Select CPU type
● Create an instance using the "Start" button

In STEP 7, perform the download and start the simulation
● Download the program to the virtual controller
● Switch the controller to RUN to start the simulation
● Perform diagnostics
● ...

See also
Simulations support (Page 27)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

45

Simulate CPU
5.2 User interface

5.2

User interface

5.2.1

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

Figure 5-1

PLCSIM Advanced Symbol

After double-clicking the icon, the icon appears in the taskbar of the information area.
You can use Windows functions to permanently display the icon in the information area of
the taskbar.

Opening a graphical interface
Right-clicking on the icon in the taskbar opens the graphical interface of PLCSIM Advanced,
the Control Panel.
If the Control Panel is open, you can use the mouse-over function to display messages
about the current status of the instances.

Figure 5-2

5.2.2

Example: Message in the taskbar

S7 PLCSIM Advanced Control Panel

Control Panel
The Control Panel is optional and is not needed to use PLCSIM Advanced via the API. It is
available in English in version 1.0.

S7-PLCSIM Advanced

46

Function Manual, 09/2016, A5E37039512-AA

Simulate CPU
5.2 User interface

①
②
③
④

Online access

Switch to select the communication interface

TCP/IP communication

Selection of network adapter for distributed communication

Virtual time

Slider to adjust the scaling factor

Start Virtual S7-1500 PLC
Name of the instance

⑤

⑥
⑦
⑧
⑨

•

IP address

•

Subnet mask

•

Standard gateway

Here you enter a unique name for the instance. Enter a minimum of
3, a maximum of 64 characters. If the name is unique in the network, the "Start" button is enabled.
The input boxes are visible when you switch the communication
interface to "PLCSIM Virtual Ethernet Adapter".

CPU type

Here you select the type of CPU to be simulated.

"Start" button

Create with the button and start an instance with the entered name.

Instance list

The list shows the available local instances.

LED displays

The meaning of the LED is displayed when you move the mouse
over it.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

47

Simulate CPU
5.2 User interface

⑩
⑪

Runtime Manager Port

Here you open a port on the local PC.

Virtual SIMATIC Memory
Card

Open an Explorer window here with the path to the virtual memory
card.

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 switches all instances off and closes the Control Panel.

⑫

Figure 5-3

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.
Change communication interface
To change the communication interface, switch off all instances and enable the other
interface.

TCP/IP communication
You can select a real network adapter from the drop-down list during operation. You thus
activate the PLCSIM Virtual Switch and establish TCP/IP communication between the
instances and the real network.
The  setting disables the PLCSIM 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
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, seeVirtual time
response (Page 58).

S7-PLCSIM Advanced

48

Function Manual, 09/2016, A5E37039512-AA

Simulate CPU
5.2 User interface

Create instance (local)
To create an instance, enter a unique name under "Instance Name". If the name already
exists in the directory of the Virtual SIMATIC Memory Card, the existing instance is started.
In the "PLC-Type" drop-down list, select the Unspecified CPU 1500 or Unspecified
ET 200SP CPU type. The CPU is named with the first download of the TIA Portal.
Recommendation: Create up to 4 local instances on your PC or visualization platform.
Remote instances cannot be created through the Control Panel.

Instance list
The instance list contains the instances that are started locally on the PC or virtualization
platform. Instances that have already been started on the runtime API are detected and
displayed in the list.
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:
Apply scaling factor for the virtual time,
Switch on instance,

disable virtual time,

Switch off instance,

Switch off instance and log out of the Runtime Manager

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 are stored on the
Virtual SIMATIC Memory Card. Click the link to open the directory.
Default path: ...\Documents\Siemens\Simatic\Simulation\Runtime\Persistence

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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

49

Simulate CPU
5.3 Download

Exit
● The command switches off all local instances on the PC or the VM and logs them off from
the Runtime Manager.
● This command closes the Runtime Manager if there is 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.

Minimize Control Panel
Clicking on an empty area on the desktop minimizes the Control Panel. The instances are
not affected.

5.3

Download

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.

Select 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

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 my the
number the CPU type has.
The lifelist shows the interfaces of an instance with their IP addresses.

S7-PLCSIM Advanced

50

Function Manual, 09/2016, A5E37039512-AA

Simulate CPU
5.3 Download

Perform download
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.

Figure 5-4

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

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

51

Simulate CPU
5.4 MAC address of the instances

5.4

MAC address of the instances

Detect CPUs and instances
If Ethernet interfaces of CPUs and PLCSIM Advanced instances are mixed in a network, the
instances can be recognized by the "PLCSIM" suffix on the station type.

Structure of the MAC address for an instance
The following figure shows the structure of the dynamically generated, locally managed MAC
address:

Figure 5-5

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
V1.0. Topological interconnection is not supported. A MAC address for a port is reserved
internally for each Ethernet interface.
Table 5- 1

Assignment of the Ethernet interfaces, for example, a CPU 1518-4 PN/DP

Ethernet interface

Last digit of the MAC Address

IE 1
IE 1 / Port 1

...........0
...........1

IE 2
IE 2 / Port 1

...........2
...........3

IE 3
IE 3 / Port 1

...........4
...........5

S7-PLCSIM Advanced

52

Function Manual, 09/2016, A5E37039512-AA

Simulate CPU
5.5 Simulate peripheral I/O

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.

5.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.
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 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.

See also
Deviating I/O values in the STEP 7 user program (Page 310)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

53

Simulate CPU
5.6 Simulate communication

5.6

Simulate communication

5.6.1

Communication services that can be simulated
S7-PLCSIM Advanced V1.0 supports the following communication options:
Table 5- 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

•

TSEND_C / TRCV_C

•

TSEND / TRCV

•

TCON

•

T_DISCON

•

TUSEND / TURCV

•

TCON

•

T_DISCON

•

MB_CLIENT

•

MB_SERVER

E-mail2

•

TMAIL_C

S7 communication

•

PUT / GET

•

BSEND / BRCV

•

USEND / URCV

Open communication using ISO-onTCP

Open communication via

UDP2

Communication via Modbus TCP

OPC UA Server2
Web

server2

Data exchange with OPC UA clients
Data exchange via HTTP

1

When the "PLCSIM" interface (Softbus) is set, communication is performed internally via ISO-onTCP.

2

Only via the communication interface "PLCSIM Virtual Ethernet Adapter" (TCP/IP)

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

S7-PLCSIM Advanced

54

Function Manual, 09/2016, A5E37039512-AA

Simulate CPU
5.6 Simulate communication

5.6.2

Communication between instances
PLCSIM Advanced supports communication between instances. An instance may be a
simulation in PLCSIM Advanced V1.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
S7-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
S7-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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

55

Simulate CPU
5.7 Provide project data offline for simulation

5.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 directory.

Provide project data offline
1. Create a "User-defined Card Reader" for your project data under Card Reader/USB
storage 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 field for this.
→ The project is saved to the \SIMATIC.S7S\OMSSTORE
directory.
3. Save the folder \SIMATIC.S7S with the project data to a medium of your choice.

Figure 5-6

Add card reader

S7-PLCSIM Advanced

56

Function Manual, 09/2016, A5E37039512-AA

Simulate CPU
5.7 Provide project data offline for simulation

Figure 5-7

Preview of download dialog

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

API functions
The project data can be used for an instance via the user interface. Use of the following
functions for this:
API functions
● GetStoragePath() (Page 123)
● StoragePath { get; set; } (Page 124)

See also
Controller - Information and settings (Page 119)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

57

6

Virtual time response

The virtual controller uses internally two types of clocks for 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.

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, i.e. 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 218)
● SetSystemTime() (Page 218)
● SystemTime { get; set; } (Page 218)

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.

S7-PLCSIM Advanced

58

Function Manual, 09/2016, A5E37039512-AA

Virtual time response

Scaling factor
Using a scaling factor, you can speed up or slow down the virtual clock of the virtual
controller for simulations.
● The default is 1, i.e. the course of the virtual time corresponds to the course of 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 219)
● SetScaleFactor() (Page 219)
● ScaleFactor { get; set; } (Page 220)

See also
Settings for the virtual time (Page 218)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

59

Virtual time response
6.1 Speed up and slow down simulation

6.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 affects
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.
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.

Fast forward
To speed up the virtual time, select a scaling factor greater than 1 in the Control Panel or in
the API.
Note
CPU load of the PC
If the scaling factor is greater than 1, the CPU load of the PC on which the virtual controller is
simulated increases considerably.
Note
Performance
The performance is 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.

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 219)
● SetScaleFactor() (Page 219)
● ScaleFactor { get; set; } (Page 220)

S7-PLCSIM Advanced

60

Function Manual, 09/2016, A5E37039512-AA

Virtual time response
6.2 Stop simulation

See also
Cycle control (Page 221)
Settings for the virtual time (Page 218)
Error with overflow cyclical events (Page 309)

6.2

Stop simulation

Freeze state of the virtual controller
To stop a simulation and to synchronize a simulation partner, a virtual controller can be set
to a freeze state via the user interface.
A triggered freeze state stops the virtual controller on the next cycle control point. The
following occurs:
● The virtual time is stopped.
● No OBs running, not counters.
● The user program is no longer executed.
● The virtual controller is still accessible from the TIA Portal.
● The virtual controller is in a state consistent with input and output data.
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 SROS_FREEZE / Freeze, see EOperatingState (Page 288).

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

61

Virtual time response
6.3 Synchronize simulation partner

Trigger freeze state
To trigger the freeze state, following modes are available for the virtual controller:
● Cycle-controlled operating mode SingleStep and ExtendedSingleStep
See Synchronize simulation partner cycle-controlled (Page 62).
● Time-controlled mode TimespanSynchronized
See Synchronize simulation partner time-controlled (Page 64).
In Default mode, the virtual controller does not go into a freeze state.
API functions
● Settings for the cycle control (Page 221)
● GetOperatingMode() (Page 221)
● SetOperatingMode() (Page 221)
● OperatingMode { get; set; } (Page 221)

6.3

Synchronize simulation partner

6.3.1

Synchronize simulation partner cycle-controlled

Introduction
The virtual controller must be set to the freeze state for synchronization.
The SingleStep and ExtendedSingleStep modes of the virtual controller provides one way to
synchronize several simulation partners (clients).

SingleStep operating mode
In this operating mode, the virtual controller at the cycle control point goes into a freeze state
and sends an event to the API clients.
The freeze state is terminated when the virtual controller issues an API command, performs
the next step or changes to the default mode.
API functions
● RunNextCycle() (Page 225)

S7-PLCSIM Advanced

62

Function Manual, 09/2016, A5E37039512-AA

Virtual time response
6.3 Synchronize simulation partner

ExtendedSingleStep operating mode
In this operating mode, the virtual controller at the cycle control point goes into a freeze state
and sends an event to the API clients.
Compared to the SingleStep operating mode, an API function in this mode also overwrites
the minimum cycle time of the OB1 cycle. When you define a minimum cycle time of 200 ms,
the minimum distance between two cycle control points is 200 virtual milliseconds. The
default mode is 100 ms.
The freeze state is terminated when the virtual controller issues an API command, performs
the next step or changes to the default mode.
API functions
● GetOverwrittenMinimalCycleTime_ns() (Page 223)
● SetOverwrittenMinimalCycleTime_ns() (Page 223)
● OverwrittenMinimalCycleTime_ns { get; set; } (Page 224)
● RunNextCycle() (Page 225)

See also
Cycle control (Page 221)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

63

Virtual time response
6.3 Synchronize simulation partner

6.3.2

Synchronize simulation partner time-controlled

Introduction
The TimespanSynchronized mode of the virtual controller provides one way to synchronize
several simulation partners (clients).

TimespanSynchronized operating mode
At least two simulation clients synchronize based on a virtual time period for this mode. A
simulation client can be an instance of a virtual controller or an API client (an application that
uses the Runtime API). The synchronization must be performed by a synchronization
master.
The synchronization master signals a simulation client that it is his turn to run over certain
time period. The time period is specified by the master in nanoseconds. The client then runs
for the expected length of time before he goes into the freeze state at the next cycle control
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 the clients 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.

API functions
● Settings for cycle control (Page 221)
● StartProcessing() (Page 226)
● RunNextCycle() (Page 225)

S7-PLCSIM Advanced

64

Function Manual, 09/2016, A5E37039512-AA

7

User interfaces (API)
7.1

Introduction

Components of the Simulation Runtime
The following components are relevant for handling the Simulation Runtime of PLCSIM
Advanced:
● Runtime
– Siemens.Simatic.Simulation.Runtime.Manager.exe
– Siemens.Simatic.Simulation.Runtime.Instance.exe
● Libraries
– Siemens.Simatic.Simulation.Runtime.Api.x86.dll
– Siemens.Simatic.Simulation.Runtime.Api.x64.dll
– SimulationRuntimeApi.h
● Documentation of interfaces with examples in native C++ and .NET (Managed Code)

Description
Runtime and libraries

Description

Siemens.Simatic.Simulation.
Runtime.Manager.exe

A Windows process that runs in the background.
Main component of Runtime that manages all other Runtime
components.
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.
Runtime.Instance.exe

The process of the instance that loads a DLL of a virtual controller. Each virtual controller generates its own process.

Siemens.Simatic.Simulation.
Runtime.Api.x86.dll

API libraries that must load an application to use the Simulation
Runtime. The libraries contain interfaces for native code and
managed code.

Siemens.Simatic.Simulation.
Runtime.Api.x64.dll
SimulationRuntimeApi.h

The "Runtime.Api.x86.dll" is loaded exclusively by 32-bit applications, and the "Runtime.Api.x64.dll" by 64-bit applications.
Header file that describes all data types that require a native C++
application to use the API library.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

65

User interfaces (API)
7.1 Introduction

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.
An external application can be other simulation software or a GUI, for example.

Figure 7-1

External applications and Simulation Runtime

S7-PLCSIM Advanced

66

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.1 Introduction

7.1.1

Access to instances

Access via the Control Panel and the API
You can access only one instance that is available locally 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.

①
②

Access to a local instance via the Control Panel
Access to a remote instance on the Runtime API

Figure 7-2

Access to instances with distributed communication

API functions
● Table 7-5 Overview of IRemoteRuntimeManager functions - Native C++ (Page 72)
● Table 7-9 Overview of IRemoteRuntimeManager functions - .NET (C#) (Page 75)
● Table 7-4 Overview of IInstances functions - Native C++ (Page 70)
● Table 7-8 Overview of IInstances functions - .NET (C#) (Page 74)

See also
Overview of user interfaces for managed code (Page 73)
S7 PLCSIM Advanced Control Panel (Page 46)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

67

User interfaces (API)
7.1 Introduction

7.1.2

User interfaces (API)
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.

①

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 7-3

API and external applications

S7-PLCSIM Advanced

68

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.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 69)
● Overview of data types for native C++ (Page 76)
● Overview of user interfaces for managed code (Page 73)
● Overview of data types for managed code (Page 77)
Note
The list of tables in this manual gives you direct access to the description of the individual
functions and data types.

7.1.3

Overview of user interfaces for native C++

Initializing and shutting down API
The following table shows which functions are available for initializing and shutting down the
API for native C++.
Table 7- 1

Overview of initializing and shutting down API - Native C++

Actions

Functions

Initialize API

InitializeApi (Page 78)
RuntimeApiEntry_Initialize (Page 79)

Shut down API (Page 81)
Unregister DLL API (Page 84)

DestroyInterface
RuntimeApiEntry DestroyInterface
FreeApi
ShutdownAndFreeApi

Global functions
Table 7- 2

Overview of global functions - Native C++

Actions
Global functions (Page 86)

Functions

GetNameOfAreaSection()
GetNameOfCPUType()
GetNameOfCommunicationInterface()
GetNameOfDataType()
GetNameOfLEDMode()
GetNameOfLEDType()
GetNameOfOperatingMode()
GetNameOfOperatingState()
GetNameOfPrimitiveDataType()
GetNameOfTagListDetails()
GetNameOfErrorCode()
GetNameOfRuntimeConfigChanged()
GetNameOfInstanceConfigChanged()

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

69

User interfaces (API)
7.1 Introduction

API ISimulationRuntimeManager
The following table shows which functions are available for the API
ISimulationRuntimeManager.
Table 7- 3

Overview of API ISimulationRuntimeManager functions - Native C++

Settings and information
Interface (Page 90)

Simulation Runtime instances
(Page 93)

Remote connections
(Page 101)

Events
OnConfigurationChanged
(Page 106)

OnRuntimeManagerLost
(Page 110)

Functions

GetVersion()
IsInitialized()
IsRuntimeManagerAvailable()
Shutdown()
GetRegisteredInstancesCount()
GetRegisteredInstanceInfoAt()
RegisterInstance()
RegisterCustomInstance()
CreateInterface()
OpenPort()
ClosePort()
GetPort()
GetRemoteConnectionsCount()
GetRemoteConnectionInfoAt()
RemoteConnect()
RegisterOnConfigurationChangedCallback()
UnregisterOnConfigurationChangedCallback()
RegisterOnConfigurationChangedEvent()
UnregisterOnConfigurationChangedEvent()
WaitForOnConfigurationChangedEvent()
RegisterOnRuntimeManagerLostCallback()
UnregisterOnRuntimeManagerLostCallback()
RegisterOnRuntimeManagerLostEvent()
UnregisterOnRuntimeManagerLostEvent()
WaitForOnRuntimeManagerLostEvent()

API IInstances
The following table shows which functions are available for the API IInstances.
Table 7- 4

Overview of IInstances functions - Native C++

Settings and information
Interface (Page 113)

Controller (Page 119)

Functions

GetID()
GetName()
GetCPUType()
SetCPUType()
GetCommunicationInterface()
SetCommunicationInterface()
GetInfo()
UnregisterInstance()
GetControllerName()
GetControllerShortDesignation()
GetControllerIPCount()
GetControllerIP()
GetControllerIPSuite4()
SetIPSuite()
GetStoragePath()
SetStoragePath()
ArchiveStorage()
RetrieveStorage()

S7-PLCSIM Advanced

70

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.1 Introduction

Settings and information
Operating state (Page 127)

Tag list (Page 135)

I/O access via address - Reading (Page 141)

I/O access via address - Writing (Page 150)
I/O access via tag name Reading (Page 158)

I/O access via tag name Writing (Page 188)

Virtual time (Page 218)

Cycle control (Page 221)

Events
OnOperatingStateChanged
(Page 228)

OnEndOfCycle (Page 232)

OnConfigurationChanging
(Page 234)

Functions

GetOperatingState()
PowerOn()
PowerOff()
MemoryReset()
Run()
Stop()
UpdateTagList()
GetTagListStatus()
GetTagInfoCount()
GetTagInfos()
CreateConfigurationFile()
GetAreaSize()
ReadBit()
ReadByte()
ReadBytes()
ReadSignals()
WriteBit()
WriteByte()
WriteBytes()
WriteSignals()
Read()
ReadBool()
ReadChar(), ReadWChar()
ReadDouble()
ReadFloat()
ReadInt8(), ReadInt16(), ReadInt32(), ReadInt64()
ReadUInt8(), ReadUInt16(), ReadUInt32(), ReadUInt64()
ReadSignals()
Write()
WriteBool()
WriteChar(), WriteWChar()
WriteDouble()
WriteFloat()
WriteInt8(), WriteInt16(), WriteInt32(), WriteInt64(),
WriteUInt8(),WriteUInt16(), WriteUInt32(), WriteUInt64()
WriteSignals()
GetSystemTime()
SetSystemTime()
GetScaleFactor()
SetScaleFactor()
GetOperatingMode()
SetOperatingMode()
SetAlwaysSendOnEndOfCycleEnabled()
IsAlwaysSendOnEndOfCycleEnabled()
GetOverwrittenMinimalCycleTime_ns()
SetOverwrittenMinimalCycleTime_ns()
RunNextCycle()
StartProcessing()
RegisterOnOperatingStateChangedCallback()
UnregisterOnOperatingStateChangedCallback()
RegisterOnOperatingStateChangedEvent()
UnregisterOnOperatingStateChangedEvent()
WaitForOnOperatingStateChangedEvent()
RegisterOnEndOfCycleCallback()
UnregisterOnEndOfCycleCallback()
RegisterOnEndOfCycleEvent()
UnregisterOnEndOfCycleEvent()
WaitForOnEndOfCycleEvent()
RegisterOnConfigurationChangingCallback()
UnregisterOnConfigurationChangingCallback()
RegisterOnConfigurationChangingEvent()
UnregisterOnConfigurationChangingEvent()
WaitForOnConfigurationChangingEvent()

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

71

User interfaces (API)
7.1 Introduction

Settings and information
OnConfigurationChanged
(Page 237)

OnLedChanged (Page 239)

Functions

RegisterOnConfigurationChangedCallback()
UnregisterOnConfigurationChangedCallback()
RegisterOnConfigurationChangedEvent()
UnregisterOnConfigurationChangedEvent()
WaitForOnConfigurationChangedEvent()
RegisterOnLedChangedCallback()
UnregisterOnLedChangedCallback()
RegisterOnLedChangedEvent()
UnregisterOnLedChangedEvent()
WaitForOnLedChangedEvent()

API IRemoteRuntimeManager
The following table shows which functions are available for the API
IRemoteRuntimeManager (remote connections):
Table 7- 5

Overview of IRemoteRuntimeManager functions - Native C++

Settings and information
Interface (Page 242)

Simulation Runtime instances
(Page 246)

Events
OnConnectionLost (Page 254)

Functions

GetVersion()
GetIP()
GetPort()
GetRemoteComputerName()
Disconnect()
GetRegisteredInstancesCount()
GetRegisteredInstanceInfoAt()
RegisterInstance()
RegisterCustomInstance()
CreateInterface()
RegisterOnConnectionLostCallback()
UnregisterOnConnectionLostCallback()
RegisterOnConnectionLostEvent()
UnregisterOnConnectionLostEvent()
WaitForOnConnectionLostEvent()

S7-PLCSIM Advanced

72

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.1 Introduction

7.1.4

Overview of user interfaces for managed code

Initializing and shutting down API
Table 7- 6

Overview of initializing and shutting down API - .NET (C#)

Actions

Functions

Initialize API (Page 80)
Shut down API (Page 86)

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeManager

API ISimulationRuntimeManager
The following table shows which functions are available for the API
ISimulationRuntimeManager.
Table 7- 7

Overview of ISimulationRuntimeManager functions - .NET (C#)

Settings and information
Interface (Page 90)

Simulation Runtime instances
(Page 93)
Remote connections
(Page 101)

Events
OnConfigurationChanged
(Page 106)
OnRuntimeManagerLost
(Page 110)

Functions

Version { get; }
IsInitialized { get; }
IsRuntimeManagerAvailable { get; }
Shutdown()
RegisterInstanceInfo { get; }
RegisterInstance()
RegisterCustomInstance()
CreateInterface()
OpenPort()
ClosePort()
Port { get; }
RemoteConnectionInfo { get; }
RemoteConnect()
OnConfigurationChanged
RegisterOnConfigurationChangedEvent()
UnregisterOnConfigurationChangedEvent()
WaitForOnConfigurationChangedEvent()
OnRuntimeManagerLost()
RegisterOnRuntimeManagerLostEvent()
UnregisterOnRuntimeManagerLostEvent()
WaitForOnRuntimeManagerLostEvent()

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

73

User interfaces (API)
7.1 Introduction

API IInstances
The following table shows which functions are available for the API IInstances.
Table 7- 8

Overview of IInstances functions - .NET (C#)

Settings and information

Functions

Dispose ()
ID { get; }
Name { get; }
CPUType { get; set; }
CommunicationInterface { get; }
Info { get; }
UnregisterInstance()
ControllerName { get; }
Controller - Information and
ControllerShortDesignation { get; }
settings (Page 119)
ControllerIPSuite4 { get; }
SetIPSuite()
StoragePath { get; set; }
ArchiveStorage()
RetrieveStorage()
OperatingState { get; }
Operating state (Page 127)
PowerOn()
PowerOff()
MemoryReset()
Run()
Stop()
UpdateTagList()
Tag list (Page 135)
GetTagListStatus()
TagInfos { get; }
CreateConfigurationFile()
I/O access via address - Read- InputArea | MarkerArea | OutputArea { get; }
AreaSize { get; }
ing (Page 141)
ReadBit()
ReadByte()
ReadBytes()
ReadSignals()
I/O access via address - Writ- WriteBit()
WriteByte()
ing (Page 150)
WriteBytes()
WriteSignals()
Read()
I/O access via tag name ReadBool()
Reading (Page 158)
ReadChar(), ReadWChar()
ReadDouble()
ReadFloat()
ReadInt8(), ReadInt16(), ReadInt32(), ReadInt64()
ReadUInt8(), ReadUInt16(), ReadUInt32(), ReadUInt64()
ReadSignals()
Write()
I/O access via tag name WriteBool()
Writing (Page 188)
WriteChar(), WriteWChar()
WriteDouble()
WriteFloat()
WriteInt8(), WriteInt16(), WriteInt32(), WriteInt64(),
WriteUInt8(),WriteUInt16(), WriteUInt32(), WriteUInt64()
WriteSignals()
SystemTime { get; set; }
Virtual time (Page 218)
ScaleFactor { get; set; }
OperatingMode { get; set; }
Cycle control (Page 221)
IsAlwaysSendOnEndOfCycleEnabled { get; set; }
OverwrittenMinimalCycleTime_ns { get; set; }
RunNextCycle()
StartProcessing()

Interface (Page 113)

S7-PLCSIM Advanced

74

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.1 Introduction

Settings and information
Events
OnOperatingStateChanged
(Page 228)
OnEndOfCycle (Page 232)

OnConfigurationChanging
(Page 234)
OnConfigurationChanged
(Page 106)
OnLedChanged (Page 239)

Functions
OnOperatingStateChanged
RegisterOnOperatingStateChangedEvent()
UnregisterOnOperatingStateChangedEvent()
WaitForOnOperatingStateChangedEvent()
OnEndOfCycle
RegisterOnEndOfCycleEvent()
UnregisterOnEndOfCycleEvent()
WaitForOnEndOfCycleEvent()
OnConfigurationChanging
RegisterOnConfigurationChangingEvent()
UnregisterOnConfigurationChangingEvent()
WaitForOnConfigurationChangingEvent()
OnConfigurationChanged
RegisterOnConfigurationChangedEvent()
UnregisterOnConfigurationChangedEvent()
WaitForOnConfigurationChangedEvent()
OnLedChanged
RegisterOnLedChangedEvent()
UnregisterOnLedChangedEvent()
WaitForOnLedChangedEvent()

API IRemoteRuntimeManager
The following table shows which functions are available for the API
IRemoteRuntimeManager.
Table 7- 9

Overview of IRemoteRuntimeManager functions - .NET (C#)

Settings and information
Interface (Page 242)

Simulation Runtime instances
(Page 93)
Events
OnConnectionLost()
(Page 254)

Functions

Dispose()
Version { get; }
IP { get; }
Port { get; }
RemoteComputerName { get; }
Disconnect()
RegisterInstanceInfo { get; }
RegisterInstance()
RegisterCustomInstance()
CreateInterface()
OnConnectionLost()
RegisterOnConnectionLostEvent()
UnregisterOnConnectionLostEvent()
WaitForOnConnectionLostEvent()

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

75

User interfaces (API)
7.1 Introduction

7.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 7- 10

Overview of data types - Native C++

Data type
DLL import functions
(Page 258)

ApiEntry_Initialize
ApiEntry_DestroyInterface

Event callback functions
(Page 259)

EventCallback_VOID
EventCallback_II_SREC_ST
EventCallback_II_SREC_ST_SROS_SROS
EventCallback_II_SREC_ST_SRLT_SRLM
EventCallback_II_SREC_ST_INT64_UINT32
EventCallback_IRRTM
EventCallback_SRCC_UINT32_UINT32_INT32
EventCallback II SREC ST SRICC UINT32 UINT32 UINT32 UINT32

Definitions and constants (Page 271)
Unions (Page 272)
Structures (Page 274)

Enumerations (Page 284)

UIP
UDataValue
SDataValue
SDataValueByAddress
SDataValueByName
SConnectionInfo
SInstanceInfo
SDimension
STagInfo
SIP
SIPSuite4
ERuntimeErrorCode
EArea
EOperatingState
EOperatingMode
ECPUType
ECommunicationInterface
ELEDType
ELEDMode
EPrimitiveDataTypes
EDataType
ETagListDetails
ERuntimeConfigChanged
EInstanceConfigChanged

S7-PLCSIM Advanced

76

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.1 Introduction

7.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 7- 11

Overview of data types - .NET (C#)

Data type
Delegate definitions
(Page 265)
- Event handler methods

Delegate_Void
Delegate_II_EREC_DT
Delegate_II_EREC_DT_EOS_EOS
Delegate_II_EREC_DT_ELT_ELM
Delegate_II_EREC_DT_INT64_UINT32
Delegate_IRRTM
Delegate_SRCC_UINT32_UINT32_INT32
Delegate II EREC DT SRICC UINT32 UINT32 UINT32 UINT32

Definitions and constants (Page 271)
Structures (Page 274)

Enumerations (Page 284)

SDataValue
SDataValueByAddress
SDataValueByName
SConnectionInfo
SInstanceInfo
SDimension
STagInfo
SIP
SIPSuite4
ERuntimeErrorCode
EArea
EOperatingState
EOperatingMode
ECPUType
ECommunicationInterface
ELEDType
ELEDMode
EPrimitiveDataTypes
EDataType
ETagListDetails
ERuntimeConfigChanged
EInstanceConfigChanged

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

77

User interfaces (API)
7.2 Initialize API

7.2

Initialize API

7.2.1

Native C++

7.2.1.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. The
DLL is loaded from the Startup directory of each application that calls this function or from
the directory that provides the path parameter.
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 7- 12

InitializeApi() - Native C++

Syntax

Parameters

ERuntimeErrorCode InitializeApi(
ISimulationRuntimeManager** out_SimulationRuntimeManagerInterface
);
ERuntimeErrorCode InitializeApi(
WCHAR* in_SimulationRuntimeApiDllPath,
ISimulationRuntimeManager** inout_SimulationRuntimeManagerInterface
);

•

ISimulationRuntimeManager**
out_SimulationRuntimeManagerInterface:

Pointer to a Runtime Manager interface pointer. The pointer must be initialized with ZERO. The interface is created within the function. See Data types
(Page 257).
•

WCHAR* in_SimulationRuntimeApiDllPath:

The path to the Runtime API library (DLL).
Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT

The pointer to the Runtime Manager interface
does not equal ZERO.

SREC_WRONG_VERSION

SREC_CONNECTION_ERROR
SREC_ERROR_LOADING_DLL

The required version of the interface is incompatible with the version used to compile
the API.
Unable to establish a connection to the
Runtime Manager.
The API library (DLL) cannot be loaded.

S7-PLCSIM Advanced

78

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.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 = ZERO;
// Initialize The API And Get The RuntimeManager Interface
result = InitializeApi(&api);

Note
If you no longer require the interface, delete it.
See DestroyInterface() (Page 82).

7.2.1.2

RuntimeApiEntry_Initialize

Description
Use the RuntimeApiEntry_Initialize function only if the API library (DLL) is to be loaded
from a different directory than the Startup directory of the application that calls 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 7- 13

RuntimeApiEntry_Initialize - Native C++

Syntax
Parameters

__declspec(dllexport) ERuntimeErrorCode RuntimeApiEntry_Initialize(
ISimulationRuntimeManager** out_SimulationRuntimeManagerInterface,
UINT32 in_InterfaceVersion
);

•

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 257).
•

UINT32 in_InterfaceVersion:

Version of the API interface to be downloaded:

Return values

DAPI_DLL_INTERFACE_VERSION.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT
SREC_WRONG_VERSION

The pointer to the Runtime Manager interface
does not equal NULL.
The required version of the interface is incompatible with the version used to compile
the API.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

79

User interfaces (API)
7.2 Initialize API
SREC_CONNECTION_ERROR

Example C++

Unable to establish a connection to the
Runtime Manager.

// 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
Win32 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 it.
See DestroyInterface() (Page 82).

7.2.2

.NET (C#)

7.2.2.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 the first time.
Table 7- 14
Exceptions

Initialize - .NET (C#)
Siemens.Simatic.Simulation.Runtime.SimulationInitializationException

Runtime error code

Condition

ERuntimeErrorCode.ConnectionError

Unable to establish a connection to the Runtime
Manager.

S7-PLCSIM Advanced

80

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.3 Shut down API

7.3

Shut down API

7.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 Win32 API-Funktion 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 84)
● ShutdownAndFreeApi() (Page 85)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

81

User interfaces (API)
7.3 Shut down API

7.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 7- 15

DestroyInterface() - Native C++

Syntax

ERuntimeErrorCode DestroyInterface(
IBaseInterface* in_Interface
);

Parameters

•

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

IBaseInterface* in_Interface:

The interface to be deleted.

SREC_WRONG_ARGUMENT

Example C++

The pointer to the interface is NULL.

// 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);
// Destroy Instance Interfaces

result = DestroyInterface(instance);
instance = NULL;

S7-PLCSIM Advanced

82

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.3 Shut down API

7.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 directory of the application that calls this
function.
If the API was initialized using the InitializeApi function, you select the DestroyInterface()
(Page 82) function.
The function unloads the memory of an ISimulationRuntimeManager,
IRemoteRuntimeManager or IInstance interface.
Table 7- 16

RuntimeApiEntry_DestroyInterface() - Native C++

Syntax
Parameters

__declspec(dllexport) ERuntimeErrorCode RuntimeApiEntry_DestroyInterface(
IBaseInterface* in_Interface
);

•

IBaseInterface* in_Interface:

The interface to be deleted.
Return values

Runtime error code
SREC_OK

SREC_WRONG_ARGUMENT

Example C++

Condition
The function is successful.
The pointer to the interface is NULL.

// 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 Win32 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);

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

83

User interfaces (API)
7.3 Shut down API

7.3.1.3

FreeApi()

Description
The FreeApi() function unloads the library of the Runtime API.
This function can only be called after the successful call of the InitializeApi function. If the
not called, the library must be unloaded using the Win32 API

InitializeApi function was
function FreeLibrary().

Table 7- 17

FreeApi() - Native C++

Syntax

ERuntimeErrorCode FreeApi();

Parameters

None

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_API_NOT_INITIALIZED

The InitializeApi function was not called
successfully.

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();

S7-PLCSIM Advanced

84

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.3 Shut down API

7.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 function. If the
InitializeApi function was not called, the library must be unloaded using the Win32 APIFunktion FreeLibrary().
Table 7- 18

ShutdownAndFreeApi() - Native C++

Syntax

ERuntimeErrorCode ShutdownAndFreeApi(
ISimulationRuntimeManager* in_SimulationRuntimeManagerInterface
);

Parameters

•

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

ISimulationRuntimeManager* in_SimulationRuntimeManagerInterface:

The interface of the Runtime Manager to be deleted.

SREC_API_NOT_INITIALIZED
SREC_WRONG_ARGUMENT

Example C++

The InitializeApi function was not called
successfully.
The pointer to the interface is NULL.

// 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;

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

85

User interfaces (API)
7.4 Global functions (Native C++)

7.3.2

.NET (C#)

7.3.2.1

Shut down API
You can end the .NET components of the API in the following ways:
● By a clearing operation using the .NET Garbage Collector.
● For the IInstance and IRemoteRuntimeManager interfaces, by calling the Dispose
(Page 113) function.

Manually clearing the API
To manually clear the API, follow these steps:
1. Delete all interfaces. Interfaces - Information and settings (Page 113)
2. Call the Shutdown() (Page 90) function of the ISimulationRuntimeManager interface.

7.4

Global functions (Native C++)

GetNameOfAreaSection()
Returns the name of the enumeration entry.
Table 7- 19

GetNameOfAreaSection() - Native C++
const WCHAR* GetNameOfAreaSection(
EArea in_AreaSection
);

Syntax
Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

EArea in_AreaSection:

Enumeration entry

GetNameOfCPUType()
Returns the name of the enumeration entry.
Table 7- 20

GetNameOfCPUType() - Native C++

Syntax

const WCHAR* GetNameOfCPUType(
ECPUType in_CPUType
);

Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

ECPUType in_CPUType:

Enumeration entry

S7-PLCSIM Advanced

86

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.4 Global functions (Native C++)

GetNameOfCommunicationInterface()
Returns the name of the enumeration entry.
Table 7- 21

GetNameOfCommunicationInterface() - Native C++
const WCHAR* GetNameOfCommunicationInterface(
ECommunicationInterface in_CommunicationInterface
);

Syntax
Parameters

•

ECommunicationInterface in_CommunicationInterface:

Enumeration entry
Return values

const WCHAR*: Name of the enumeration entry

GetNameOfDataType()
Returns the name of the enumeration entry.
Table 7- 22

GetNameOfDataType() - Native C++
const WCHAR* GetNameOfDataType(
EDataType in_DataType
);

Syntax
Parameters

•

EDataType in_DataType:

Enumeration entry
Return values

const WCHAR*: Name of the enumeration entry

GetNameOfErrorCode()
Returns the name of the enumeration entry.
Table 7- 23

GetNameOfErrorCode() - Native C++
const WCHAR* GetNameOfErrorCode(
ERuntimeErrorCode in_ErrorCode
);

Syntax
Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

ERuntimeErrorCode in_ErrorCode:

Enumeration entry

GetNameOfLEDMode()
Returns the name of the enumeration entry.
Table 7- 24

GetNameOfLEDMode() - Native C++

Syntax

const WCHAR* GetNameOfLEDMode(
ELEDMode in_LEDMode
);

Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

ELEDMode in_LEDMode:

Enumeration entry

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

87

User interfaces (API)
7.4 Global functions (Native C++)

GetNameOfLEDType()
Returns the name of the enumeration entry.
Table 7- 25

GetNameOfLEDType() - Native C++
const WCHAR* GetNameOfLEDType(
ELEDType in_LEDType
);

Syntax
Parameters

•

ELEDType in_LEDType:

Enumeration entry.
Return values

const WCHAR*: Name of the enumeration entry

GetNameOfOperatingMode()
Returns the name of the enumeration entry.
Table 7- 26

GetNameOfOperatingMode() - Native C++
const WCHAR* GetNameOfOperatingMode(
EOperatingMode in_OperatingMode
);

Syntax
Parameters

•

EOperatingMode in_OperatingMode:

Enumeration entry
Return values

const WCHAR*: Name of the enumeration entry

GetNameOfErrorCode()
Returns the name of the enumeration entry.
Table 7- 27

GetNameOfErrorCode() - Native C++
const WCHAR* GetNameOfErrorCode(
ERuntimeErrorCode in_ErrorCode
);

Syntax
Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

ERuntimeErrorCode in_ErrorCode:

Enumeration entry

GetNameOfOperatingState
Returns the name of the enumeration entry.
Table 7- 28

GetNameOfOperatingState() - Native C++

Syntax

const WCHAR* GetNameOfOperatingState(
EOperatingState in_OperatingState
);

Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

EOperatingState in_OperatingState:

Enumeration entry

S7-PLCSIM Advanced

88

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.4 Global functions (Native C++)

GetNameOfPrimitiveDataType
Returns the name of the enumeration entry.
Table 7- 29

GetNameOfPrimitiveDataType() - Native C++
const WCHAR* GetNameOfPrimitiveDataType(
EPrimitiveDataType in_DataType
);

Syntax
Parameters

•

EPrimitiveDataType in_DataType:

Enumeration entry
Return values

const WCHAR*: Name of the enumeration entry

GetNameOfTagListDetails
Returns the name of the enumeration entry.
Table 7- 30

GetNameOfTagListDetails() - Native C++
const WCHAR* GetNameOfTagListDetails(
ETagListDetails in_TagListDetails
);

Syntax
Parameters

•

ETagListDetails in_TagListDetails:

Enumeration entry
Return values

const WCHAR*: Name of the enumeration entry

GetNameOfRuntimeConfigChanged()
Returns the name of the enumeration entry.
Table 7- 31

GetNameOfRuntimeConfigChanged() - Native C++
const WCHAR* GetNameOfRuntimeConfigChanged( ERuntimeConfigChanged
in_RuntimeConfigChanged);
);

Syntax
Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

ERuntimeConfigChanged in_RuntimeConfigChanged:

Enumeration entry

GetNameOfInstanceConfigChanged()
Returns the name of the enumeration entry.
Table 7- 32

GetNameOfInstanceConfigChanged() - Native C++

Syntax

const WCHAR* GetNameOfInstanceConfigChanged( EInstanceConfigChanged in_InstanceConfigChanged);
);

Parameters

•

Return values

const WCHAR*: Name of the enumeration entry

EInstanceConfigChanged in_InstanceConfigChanged:

Enumeration entry

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

89

User interfaces (API)
7.5 API ISimulationRuntimeManager

See also
EPrimitiveDataType (Page 294)
EDataType (Page 296)

7.5

API ISimulationRuntimeManager

7.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 7- 33

GetVersion() - Native C++

Syntax

UINT32 GetVersion();

Parameters

None

Return values

UINT32: Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

Table 7- 34

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

Syntax

UInt32 Version { get; }

Parameters

None

Return values

Uint32: Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

S7-PLCSIM Advanced

90

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

IsInitialized() / IsInitialized { get; }
Returns a value that indicates whether the API was successfully initialized.
Table 7- 35

IsInitialized() - Native C++

Syntax

bool IsInitialized();

Parameters

None

Return values

•
•

Table 7- 36

false: If the API was not initialized.
true: If the API was initialized.

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 106).
Table 7- 37

IsRuntimeManagerAvailable() - Native C++

Syntax

bool IsRuntimeManagerAvailable();

Parameters

None

Return values

•
•

Table 7- 38

false: If the connection is interrupted.
true: If the connection is active.

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

Syntax

bool IsRuntimeManagerAvailable{ get; }

Parameters

None

Return values

•
•

false: If the connection is interrupted.
true: If the connection is active.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

91

User interfaces (API)
7.5 API ISimulationRuntimeManager

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 7- 39

Shutdown() - Native C++
ERuntimeErrorCode Shutdown()

Syntax
Parameters

None

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

Table 7- 40

Shutdown() - .NET (C#)

Syntax

void Shutdown()

Parameters

None

Return values

None

S7-PLCSIM Advanced

92

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

7.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 7- 41

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 7- 42

GetRegisteredInstanceInfoAt() - Native C++

Syntax
Parameters

ERuntimeErrorCode GetRegisteredInstanceInfoAt(
UINT32 in_Index,
SInstanceInfo* out_InstanceInfo
);

•

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 271).
Return values

Runtime error code
SREC_OK

SREC_TIMEOUT
SREC_INDEX OUT_OF_RANGE

Condition
The function is successful.
The function does not return on time.
There is no instance information for this
index.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

93

User interfaces (API)
7.5 API ISimulationRuntimeManager

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 7- 43

RegisteredInstanceInfo { get; } - .NET (C#)

Syntax
Parameters
Return values
Exceptions

SInstanceInfo[] RegisteredInstanceInfo { get; }

None

SInstanceInfo[]: An array of information about all registered instances.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.Timeout

Condition

The function does not return on time.

S7-PLCSIM Advanced

94

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

RegisterInstance()
Registers a new instance of a virtual controller in Runtime Manager. Creates and returns an
interface of this instance.
Table 7- 44

RegisterInstance() - Native C++

Syntax

Parameters

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
);

•

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 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 271).
•

Return values

Example C++

IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with ZERO. The interface is created within the function.

Runtime error code
SREC_OK

Condition

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.

ISimulationRuntimeManager * api = ZERO;
ERuntimeErrorCode result = Initialize(&api);
// Example: How To Create And Register An Instance
IInstance* psa = ZERO;
if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

95

User interfaces (API)
7.5 API ISimulationRuntimeManager

Note
Native C++
If you no longer require the interface, delete it.
See DestroyInterface() (Page 82).

Table 7- 45

RegisterInstance() - .NET (C#)

Syntax

Parameters

IInstance RegisterInstance();
IInstance RegisterInstance(
string in_InstanceName
);
IInstance RegisterInstance(
ECPUType in_CPUType
);
IInstance RegisterInstance(
ECPUType in_CPUType
string in_InstanceName
);

•

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 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 271).

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

ERuntimeErrorCode.Timeout

Condition

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.

S7-PLCSIM Advanced

96

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

RegisterCustomInstance()
Registers a new instance of a virtual controller in Runtime Manager. Creates and returns an
interface of this instance.
Table 7- 46

RegisterCustomInstance() - Native C++

Syntax

Parameters

ERuntimeErrorCode RegisterCustomInstance(
WCHAR* in_VplcDll,
IInstance** out_InstanceInterface
);
ERuntimeErrorCode RegisterCustomInstance(
WCHAR* in_VplcDll,
WCHAR* in_InstanceName,
IInstance** out_InstanceInterface
);

•

WCHAR* in_VplcDll:

The complete path to the DLL of the virtual controller that Siemens.Simatic.Simulation.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 271).
•

Return values

Example C++

IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with ZERO. The interface is created within the function.

Runtime error code
SREC_OK

Condition

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.

ISimulationRuntimeManager * api = ZERO;
ERuntimeErrorCode result = Initialize(&api);
// Example: How To Create And Register An Instance
IInstance* psa = ZERO;
if (result == SREC_OK)
{
result = api->RegisterCustomInstance("C:\\Temp\\vplc.dll");
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

97

User interfaces (API)
7.5 API ISimulationRuntimeManager

Note
Native C++
If you no longer require the interface, delete it.
See DestroyInterface() (Page 82).

Table 7- 47

RegisterCustomInstance() - .NET (C#)

Syntax

Parameters

IInstance RegisterCustomInstance(
string in_VplcDll
);
IInstance RegisterCustomInstance(
string in_VplcDll,
string in_InstanceName
);

•

string in_VplcDll:

The complete path to the DLL of the virtual controller that Siemens.Simatic.Simulation.Runtime.Instance.exe loads at PowerOn.
•

Return values
Exceptions

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 271).

If the function is successful, an interface of a virtual controller; otherwise a Null
pointer.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The name or the ID is invalid.

ERuntimeErrorCode.LimitReached
ERuntimeErrorCode.AlreadyExists

There are already 16 instances registered in Runtime Manager.
An instance with this name already exists.

S7-PLCSIM Advanced

98

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

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 7- 48

CreateInterface() - Native C++

Syntax

Parameters

ERuntimeErrorCode CreateInterface(
WCHAR* in_InstanceName,
IInstance** out_InstanceInterface
);
ERuntimeErrorCode CreateInterface(
INT32 in_InstanceID,
IInstance** out_InstanceInterface
);

•

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.
•

Return values

IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with ZERO. The interface is created within the function.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

Example C++

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.

ISimulationRuntimeManager * api = ZERO;
ERuntimeErrorCode result = Initialize(&api);
IInstance* psa1 = ZERO;
IInstance* psa2 = ZERO;
if (result == SREC_OK)
{
result = api->CreateInterface(0, &psa1);

Example C++

result = api->CreateInterface(0, &psa2); // psa2 will be the same as
psa1
}
ISimulationRuntimeManager * api = ZERO;
ERuntimeErrorCode result = Initialize(&api);
IInstance* psa = ZERO;
if (result == SREC_OK)
{
result = api->CreateInterface(L"My SimulationRuntime Instance",
&psa);
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

99

User interfaces (API)
7.5 API ISimulationRuntimeManager

Note
Native C++
If you no longer require the interface, delete it.
See DestroyInterface() (Page 82).

Table 7- 49

CreateInterface() - .NET (C#)

Syntax

Parameters

IInstance CreateInterface(
string in_InstanceName
);
IInstance CreateInterface(
INT32 in_InstanceID
);

•

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
Exceptions

If the function is successful, an interface of a virtual controller; otherwise a Null
pointer.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

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

100

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

7.5.3

Remote connections

OpenPort()
Opens a port to which another Runtime Manager can connect.
Table 7- 50

OpenPort() - Native C++
ERuntimeErrorCode OpenPort(
UINT16 in_Port
);

Syntax
Parameters

•

Return values

Runtime error code

UINT16 in_Port:

The port. The value must be greater than 1024.
SREC_OK

SREC_TIMEOUT
SREC_ALREADY_EXISTS

Table 7- 51

Condition
The function is successful.
The function does not return on time.
A port is already open.

SREC_WRONG_ARGUMENT

The port is invalid.

SREC_CONNECTION_ERROR

The port cannot be opened.

OpenPort() - .NET (C#)

Syntax

void OpenPort(
UInt16 in_Port
);

Parameters

•

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

UInt16 in_Port:

The port. The value must be greater than 1024.

Runtime error code

Condition

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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

101

User interfaces (API)
7.5 API ISimulationRuntimeManager

ClosePort()
Closes an open port and all open connections that another Runtime Manager has created to
this open port.
Table 7- 52

ClosePort() - Native C++

Syntax

ERuntimeErrorCode ClosePort();

Parameters

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT
SREC_WARNING_INVALID_CALL

Table 7- 53

The function does not return on time.
No port is open.

ClosePort() - .NET (C#)
void ClosePort(
UInt16 in_Port
);

Syntax
Parameters

None

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.Timeout

Condition

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 7- 54

GetPort() - Native C++

Syntax

UINT16 GetPort();

Parameters

None

Return values

UINT16: The open port. 0, if no port is open.

Table 7- 55

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

Syntax

UInt16 Port { get; }

Parameters

None

Return values

UInt16: The open port. 0, if no port is open.

Exceptions

None

S7-PLCSIM Advanced

102

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

GetRemoteConnectionsCount()
Supplies the number of open remote connections.
Table 7- 56

GetRemoteConnectionsCount() - Native C++

Syntax

UINT32 GetRemoteConnectionsCount();

Parameters

None

Return values

UINT32: Number of open remote connections.

GetRemoteConnectionInfoAt()
Returns information about an open connection.
Table 7- 57

GetRemoteConnectionInfoAt()- Native C++
ERuntimeErrorCode GetRemoteConnectionInfoAt(
UINT32 in_Index,
SConnectionInfo* out_ConnectionInfo
);

Syntax
Parameters

•

UINT32 in_Index:

Index of the connection information that is expected.
•

SConnectionInfo* out_ConnectionInfo:

The connection information for this index.
Return values

Runtime error code
SREC_OK

SREC_TIMEOUT
SREC_INDEX_OUT_OF_RANGE

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

RemoteConnectionInfo { get; }
Returns an array of information about all open connections.
Table 7- 58

RemoteConnectionInfo { get; } - .NET (C#)

Syntax

SConnectionInfo[] RemoteConnectionInfo { get; }

Parameters

None

Return values

SConnectionInfo[]: An array of information about all open connections.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Exceptions

Runtime error code

ERuntimeErrorCode.Timeout

Condition

The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

103

User interfaces (API)
7.5 API ISimulationRuntimeManager

RemoteConnect()
Creates a new connection to a remote Runtime Manager or uses an existing connection to
create an IRemoteRuntimeManager interface.
Table 7- 59

RemoteConnect() - Native C++

Syntax

Parameters

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
);

•

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:

•

IRemoteRuntimeManager** out_RemoteRuntimeManagerInterface:

The port that is open on the remote PC.

Return values

Pointer to a remote Runtime Manager interface pointer. The pointer must be initialized with ZERO. The interface is created in the function.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_CONNECTION_ERROR
SREC_WRONG_ARGUMENT

Example C++

The connection to the remote Runtime
Manager cannot be established.
IP, port or IInstance pointer is invalid.

ISimulationRuntimeManager* api = ZERO;
ERuntimeErrorCode result = Initialize(&api);
IRemoteRuntimeManager * client = ZERO;
if (result == SREC_OK)
{
result = api->RemoteConnect(192,203,145,144, 4444, &client);
}

S7-PLCSIM Advanced

104

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

Note
Native C++
If you no longer require the interface, delete it.
See DestroyInterface() (Page 82).

Table 7- 60

RemoteConnect() - .NET (C#)

Syntax

Parameters

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
);

•

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 "...:"
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
Exceptions

IRemoteRuntimeManager: Interface to the remote Runtime Manager.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

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, 09/2016, A5E37039512-AA

105

User interfaces (API)
7.5 API ISimulationRuntimeManager

See also
Data types (Page 257)
Tag list (Page 135)

7.5.4

Events

Events for the ISimulationRuntimeManager interface
The following events are differentiated in the API:
Table 7- 61

Events for the ISimulationRuntimeManager interface

Event

Cause

OnConfigurationChanged
(Page 106)

This event is triggered at a change of the Runtime Manager configuration. For example, when a new instance is registered, an instance is
removed or a connection to a client is established.
The Control Panel uses such an event to update the list of available
instances.

OnRuntimeManagerLost
(Page 110)

7.5.4.1

The event is triggered when the connection to Runtime Manager is
interrupted.

OnConfigurationChanged

OnConfigurationChanged
Registers or unregisters an event handler method.
Table 7- 62

OnConfigurationChanged - .NET (C#)

Syntax

event Delegate_SRCC_UINT32_UINT32_INT32 OnConfigurationChanged;

Parameters

None. See Delegate_SRCC_UINT32_UINT32_INT32 (Page 269).

Return values

None

Exceptions

None

Note

The event handler method runs in a separate thread.

S7-PLCSIM Advanced

106

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

RegisterOnConfigurationChangedCallback()
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 7- 63

RegisterOnConfigurationChangedCallback() - Native C++
void RegisterOnConfigurationChangedCallback(
EventCallback_SRCC_UINT32_UINT32_INT32 in_CallbackFunction
);

Syntax
Parameters

•

EventCallback_SRCC_UINT32_UINT32_INT32 in_CallbackFunction:

A callback function to subscribe to an event.
See EventCallback_SRCC_UINT32_UINT32_INT32 (Page 263).
Return values

None

Note

The event handler method runs in a separate thread.

RegisterOnConfigurationChangedEvent()
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 7- 64

RegisterOnConfigurationChangedEvent() - Native C++
void RegisterOnConfigurationChangedEvent();
void RegisterOnConfigurationChangedEvent(
HANDLE* in_Event
);

Syntax
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

Table 7- 65

None

RegisterOnConfigurationChangedEvent() - .NET (C#)

Syntax

void RegisterOnConfigurationChangedEvent();

Parameters

None

Return values

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

107

User interfaces (API)
7.5 API ISimulationRuntimeManager

UnregisterOnConfigurationChangedCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 7- 66

UnregisterOnConfigurationChangedCallback() - Native C++

Syntax

void UnregisterOnConfigurationChangedCallback();

Parameters

None

Return values

None

UnregisterOnConfigurationChangedEvent()
Unregisters the event object.
Table 7- 67

UnregisterOnConfigurationChangedEvent() - Native C++

Syntax

void UnregisterOnConfigurationChangedEvent();

Parameters

None

Return values

None

Table 7- 68

UnregisterOnConfigurationChangedEvent() - .NET (C#)

Syntax

void UnregisterOnConfigurationChangedEvent();

Parameters

None

Return values

None

S7-PLCSIM Advanced

108

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

WaitForOnConfigurationChangedEvent()
The function blocks the program until the registered event object is set to the signaled state
or the timeout interval is exceeded.
Table 7- 69

WaitForOnConfigurationChangedEvent() - Native C++
bool WaitForOnConfigurationChangedEvent();
bool WaitForOnConfigurationChangedEvent(
UINT32 in_Time_ms
);

Syntax
Parameters

•

None:

The time limit is set to INFINITE.
•

UINT32 in_Time_ms:

Value for the time limit in milliseconds.
Return values

•
•

Table 7- 70

true: If the event object was set to the signaled state.

false: If no event was received during the defined time limit.

WaitForOnConfigurationChangedEvent - .NET (C#)

Syntax
Parameters

bool WaitForOnConfigurationChangedEvent();
bool WaitForOnConfigurationChangedEvent(
UInt32 in_Time_ms
);

•

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, 09/2016, A5E37039512-AA

109

User interfaces (API)
7.5 API ISimulationRuntimeManager

7.5.4.2

OnRuntimeManagerLost

OnRuntimeManagerLost
Registers or unregisters an event handler method.
Table 7- 71

OnRuntimeManagerLost - .NET (C#)
event Delegate_Void OnRuntimeManagerLost;

Syntax
Parameters

None. See Delegate_Void (Page 265).

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. 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 7- 72

RegisterOnRuntimeManagerLostCallback() - Native C++

Syntax
Parameters

void RegisterOnRuntimeManagerLostCallback(
EventCallback_VOID in_CallbackFunction
);

•

EventCallback_VOID in_CallbackFunction:

A callback function that subscribes to the event.
See EventCallback_VOID (Page 259).
Return values

None

Note

The event handler method runs in a separate thread.

S7-PLCSIM Advanced

110

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.5 API ISimulationRuntimeManager

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 7- 73

RegisterOnRuntimeManagerLostEvent() - Native C++
void RegisterOnRuntimeManagerLostEvent();
void RegisterOnRuntimeManagerLostEvent(
HANDLE* in_Event
);

Syntax
Parameters

•

None:

An internal event handle is registered.
•

HANDLE* in_Event:

A user-specific event handle is registered.
Return values

Table 7- 74

None

RegisterOnRuntimeManagerLostEvent() - .NET (C#)

Syntax

void RegisterOnRuntimeManagerLostEvent();

Parameters

None

Return values

None

UnregisterOnRuntimeManagerLostCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 7- 75

UnregisterOnRuntimeManagerLostCallback() - Native C++

Syntax

void UnregisterOnRuntimeManagerLostCallback();

Parameters

None

Return values

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

111

User interfaces (API)
7.5 API ISimulationRuntimeManager

UnregisterOnRuntimeManagerLostEvent()
Unregisters the event object.
Table 7- 76

UnregisterOnRuntimeManagerLostEvent() - Native C++

Syntax

void UnregisterOnRuntimeManagerLostEvent();

Parameters

None

Return values

None

Table 7- 77

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 7- 78

WaitForOnRuntimeManagerLostEvent() - Native C++
bool WaitForOnRuntimeManagerLostEvent();
bool WaitForOnRuntimeManagerLostEvent(
UINT32 in_Time_ms
);

Syntax
Parameters

•

None:

The time limit is set to INFINITE.
•

UINT32 in_Time_ms:

Value for the time limit in milliseconds.
Return values

•
•

Table 7- 79

true: If the event object was set to the signaled state.

false: If no event was received during the defined timeout interval.

WaitForOnRuntimeManagerLostEvent() - .NET (C#)

Syntax
Parameters

bool WaitForOnRuntimeManagerLostEvent();
bool WaitForOnRuntimeManagerLostEvent(
UInt32 in_Time_ms
);

•

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

112

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

7.6

API IInstances

7.6.1

Interfaces - Information and settings

Dispose()
Deletes the managed interface and unloads the native components of the user interfaces.
Table 7- 80

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 7- 81

GetID() - Native C++

Syntax

INT32 GetID();

Parameters

None

Return values

INT32: Instance ID

Table 7- 82

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

Syntax

UInt32 ID { get; }

Parameters

None

Return values

Uint32: Instance ID

Exceptions

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

113

User interfaces (API)
7.6 API IInstances

GetName() / Name { get; }
Returns the name of the instance.
Table 7- 83

GetName() - Native C++
ERuntimeErrorCode GetName(
WCHAR inout_Name[],
UINT32 in_ArrayLength
);

Syntax
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 271).
•

UINT32 in_ArrayLength:

Field length (Wide character)
Return values

Example C++

Runtime error code

Condition

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.

ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = Initialize(&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 7- 84

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

ERuntimeErrorCode.InterfaceRemoved

Condition

The instance is not registered in Runtime
Manager.

S7-PLCSIM Advanced

114

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

GetCPUType()
Returns the CPU type of the virtual controller.
Table 7- 85

GetCPUType() - Native C++

Syntax

ECPUType GetCPUType();

Parameters

None

Return values

An enumeration element that defines the CPU type.
See ECPUType (Page 289).

SetCPUType()
Sets the CPU type of the virtual controller. A change of CPU type occurs only when the
controller is restarted.
Table 7- 86

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

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 7- 87

CPUType { get; set; } - .NET (C#)

Syntax

ECPUType CPUType { get; set; }

Parameters

None

Return values

An enumeration element that defines the CPU type.

Exceptions

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

115

User interfaces (API)
7.6 API IInstances

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 7- 88

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

•

SRCI_TCPIP

Is returned if the virtual controller uses the Softbus.
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 7- 89

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

116

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.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 7- 90

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

•

ECommunicationInterface.TCPIP

Is returned if the virtual controller uses the Softbus.
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 7- 91

GetInfo() - Native C++

Syntax

SInstanceInfo GetInfo();

Parameters

None

Return values

SInstanceInfo: A structure that provides information about the instance. See

Table 7- 92

SInstanceInfo (Page 278).

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

Syntax

SInstanceInfo Info { get; }

Parameters

None

Return values

SInstanceInfo: A structure that provides information about the instance.

Exceptions

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

117

User interfaces (API)
7.6 API IInstances

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 7- 93

UnregisterInstance() - Native C++

Syntax

ERuntimeErrorCode UnregisterInstance();

Parameters

None

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

Table 7- 94

The function does not return on time.

UnregisterInstance() - .NET (C#)

Syntax

void UnregisterInstance();

Parameters

None

Return values

None

Exceptions

The instance is not registered in Runtime
Manager.

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.

S7-PLCSIM Advanced

118

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

7.6.2

Controller - Information and settings

GetControllerName() / ControllerName { get; }
Returns the downloaded name of the virtual controller.
Table 7- 95

GetControllerName() - Native C++
ERuntimeErrorCode GetControllerName(
WCHAR inout_Name[],
UINT32 in_ArrayLength
);

Syntax
Parameters

•

WCHAR inout_Name[]:

A user-allocated storage for the name.
•

UINT32 in_ArrayLength:

The length of the storage.
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_INDEX_OUT_OF_RANGE

Table 7- 96

The name does not fit in the storage.

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

Syntax

string ControllerName { get; }

Parameters

None

Return values

string:

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

The downloaded name of the virtual controller.
Runtime error code

Condition

ERuntimeErrorCode.InterfaceRemoved

The instance is not registered in Runtime
Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

119

User interfaces (API)
7.6 API IInstances

GetControllerShortDesignation() / ControllerShortDesignation { get; }
Returns the downloaded short designation of the virtual controller.
Table 7- 97

GetControllerShortDesignation() - Native C++
ERuntimeErrorCode GetControllerShortDesignation(
WCHAR inout_ShortDesignation[],
UINT32 in_ArrayLength
);

Syntax
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

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_INDEX_OUT_OF_RANGE

Table 7- 98

The name does not fit in the storage.

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

Syntax

string ControllerShortDesignation { get; }

Parameters

None

Return values

string:

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

The downloaded short designation of the virtual controller.
Runtime error code

Condition

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 7- 99

GetControllerIPCount() - Native C++

Syntax

UINT32 GetControllerIPCount();

Parameters

None

Return values

INT32: Number of configured IP addresses of the virtual controller.

S7-PLCSIM Advanced

120

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

GetControllerIP() / ControllerIP { get; }
Returns a configured IP address of the instance.
Table 7- 100 GetControllerIP() - Native C++
UIP GetControllerIP();
UIP GetControllerIP(
UINT32 in_Index
);

Syntax
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

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

Table 7- 101 ControllerIP { get; } - .NET (C#)
Syntax

string[] ControllerIP { get; }

Parameters

None

Return values

string: All downloaded IP addresses of the virtual controller. If the function

Exceptions

None

fails, the field is empty.

GetControllerIPSuite4() / ControllerIPSuite4 { get; }
Returns the IP suite instance. If the "Softbus" communication interface is used, the subnet
mask and default gateway are 0.
Table 7- 102 GetControllerIPSuite4() Native C++
Syntax
Parameters

Return values

SIPSuite4 GetControllerIPSuite4();
SIPSuite4 GetControllerIPSuite4(
UINT32 in_Index
);

•

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.

SIPSuite4: The IP suite of the virtual controller. If the function fails, the return

values are 0.

Table 7- 103 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

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

121

User interfaces (API)
7.6 API IInstances

SetIPSuite()
Sets the IP suite of the network interface of a virtual controller.
Table 7- 104 SetIPSuite() - Native C++
Syntax
Parameters

ERuntimeErrorCode SetIPSuite(
UINT32 in_InterfaceID,
SIPSuite4 in_IPSuite,
bool in_IsRemanent
);

•

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.
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
SREC_DOES_NOT_EXIST
SREC_INVALID_OPERATING_STATE

The process of the virtual controller is not
running.
There is no network interface with this ID.
The virtual controller has not yet completed the boot process or is already in
the shutdown phase.

Table 7- 105 SetIPSuite() - .NET (C#)
Syntax
Parameters

void SetIPSuite(
UInt32 in_InterfaceID,
SIPSuite4 in_IPSuite,
bool in IsRemanent );

•

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.

S7-PLCSIM Advanced

122

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Return values
Exceptions

None

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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

There is no network interface with this ID.

ERuntimeErrorCode.InvalidOperatingState

The virtual controller has not yet completed the boot process or is already in
the shutdown phase.

GetStoragePath()
Returns the full directory in which the instance stores its data.
Table 7- 106 GetStoragePath() - Native C++
Syntax
Parameters

ERuntimeErrorCode GetStoragePath(
WCHAR inout_StoragePath[],
UINT32 in_ArrayLength
);

•

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 257).
•

UINT32 in_ArrayLength:

Length of the array (Wide character)
Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INDEX_OUT_OF_RANGE

The instance is not registered in Runtime
Manager.
The function does not return on time.
The path does not fit in the storage.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

123

User interfaces (API)
7.6 API IInstances

SetStoragePath()
Sets the full path of the directory 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:
>\Siemens\Simatic\Simulation\Runtime\Persistence\ is
used.
Table 7- 107 SetStoragePath() - Native C++
Syntax
Parameters

Return values

ERuntimeErrorCode SetStoragePath(
WCHAR* in_StoragePath
);

•

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 257).

Runtime error code
SREC_OK

Condition

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 directory 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:
>\Siemens\Simatic\Simulation\Runtime\Persistence\ is
used.
Table 7- 108 StoragePath { get; set; } - .NET (C#)
Syntax

string StoragePath { get; set; }

Parameters

None

Return values

string: The configured storage path.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Exceptions

Runtime error code

Condition

ERuntimeErrorCode.InterfaceRemoved

The instance is not registered in Runtime
Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.IndexOutOfRange
ERuntimeErrorCode.WrongArgument

The length of the path exceeds the limit.
The path contains invalid characters.
S7-PLCSIM Advanced

124

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

ArchiveStorage()
The user program, the hardware configuration and the retentive data are stored in a file, the
Virtual SIMATIC Memory Card. ArchiveStorage() stores this file as a ZIP file. The instance
of the virtual controller must be in OFF operating state for this.
Table 7- 109 ArchiveStorage() - Native C++
Syntax
Parameters

ERuntimeErrorCode ArchiveStorage(
WCHAR* in_FullFileName
);

•

WCHAR in_FullFileName:

The full path to the ZIP file.
Return values

Runtime error code
SREC_OK

Condition
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
SREC_ARCHIVE_STORAGE_FAILED

The directory for the ZIP file could not be
created.
The ZIP file could not be created.

Table 7- 110 ArchiveStorage() - .NET (C#)
Syntax
Parameters

void ArchiveStorage(
string in_ArchiveStorageFile
);

•

string in_ArchiveStorageFile:

The full path to the ZIP file. The path relates to directories of the computer on
which the instance runs.
Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout
ERuntimeErrorCode.InvalidOperatingState
ERuntimeErrorCode.InvalidArchivePath
ERuntimeErrorCode.CreateDirectoriesFailed
ERuntimeErrorCode.ArchiveStorageNotCreated

Condition

The instance is not registered in Runtime
Manager.
The function does not return on time.
The instance is not in OFF operating
state.
The archive path is invalid.
The directory for the ZIP file could not be
created.
The ZIP file could not be created.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

125

User interfaces (API)
7.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 7- 111 RetrieveStorage() - Native C++
Syntax
Parameters

ERuntimeErrorCode RetrieveStorage(
WCHAR* in_FullFileName
);

•

WCHAR* in_FullFileName:

The full path to the ZIP file. The path relates to directories of the computer on
which the instance runs.
Return values

Runtime error code
SREC_OK

Condition
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_FAI
LED
SREC_RETRIEVE_STORAGE_FAILURE

The old storage cannot be deleted.
The ZIP file cannot be unzipped.

Table 7- 112 RetrieveStorage() - .NET (C#)
Syntax
Parameters

void RetrieveStorage(
string in_ArchiveStorageFile
);

•

string in_ArchiveStorageFile:

The full path to the ZIP file.
Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout

Condition

The instance is not registered in Runtime
Manager.
The function does not return on time.

ERuntimeErrorCode.InvalidOperatingState

The instance is not in OFF operating
state.

ERuntimeErrorCode.InvalidArchivePath
ERuntimeErrorCode.DeleteExistingStorageFailed
ERuntimeErrorCode.RetrieveStorageFailure

The archive path is invalid.
The old storage cannot be deleted.
The ZIP file cannot be unzipped.

S7-PLCSIM Advanced

126

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

7.6.3

Operating state

GetOperatingState() / OperatingState { get; }
Returns the operating state of the virtual controller. If the operating state changes, the event
OnOperatingStateChanged() (Page 228) is triggered. For details about the operating state,
see Data types (Page 287).
Table 7- 113 GetOperatingState() - Native C++
Syntax

EOperatingState GetOperatingState();

Parameters

None

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

•

SROS_STOP:

ready to start the user program.

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_SHUTTING_DOWN:
If PowerOff() was called but the virtual controller is still in the Shutdown
phase.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

127

User interfaces (API)
7.6 API IInstances
Table 7- 114 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.ShuttingDown:
If PowerOff() was called but the virtual controller is still in the Shutdown

phase.

S7-PLCSIM Advanced

128

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

PowerOn()
The function creates the process for the Simulation Runtime instance and starts the firmware
of the virtual controller.
Table 7- 115 PowerOn() - Native C++
Syntax
Parameters

ERuntimeErrorCode PowerOn();
ERuntimeErrorCode PowerOn(
UINT32 in_Timeout_ms
);

•

UINT32 in_Timeout_ms:

A timeout value in milliseconds.

Return values

–

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 }

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

The instance is not registered in Runtime
Manager.
The expected operating state does not
occur on time.

SREC_ERROR_LOADING_DLL

The Siemens.Simatic.Simulation.Runtime.Instan
ce.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

The path could not be created. The
length of the
DSTORAGE_PATH_MAX_LENGTH characters
may be exceeded.

SREC_WARNING_ALREADY_EXISTS

Only one warning. The instance is started.

SREC_WARNING_TRIAL_MODE_ACTIVE

No license available. You can use the
instance without restrictions for a period
of one hour. Afterwards, the instance is
shut down.

SREC_VIRTUAL_SWITCH_MISCONFIGURE
D
SREC_INSTANCE_NOT_RUNNING

The warning occurs even when you import a license within this hour. The instance is then not shut down.
The virtual switch is configured incorrectly.
The process of the virtual controller is no
longer running.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

129

User interfaces (API)
7.6 API IInstances
Table 7- 116 PowerOn() - .NET (C#)
Syntax
Parameters

ERuntimeErrorCode PowerOn();
ERuntimeErrorCode PowerOn(
UInt32 in_Timeout_ms
);

•

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:

Return values

{ EOperatingState.Run, EOperatingState.Stop }

Runtime error code

Condition

ERuntimeErrorCode.WarningAlreadyExists

Only one warning. The instance is started.

ERuntimeErrorCode.OK

ERuntimeErrorCode.WarningTrialModeActive

The function is successful.

No license available. You can use the
instance without restrictions for a period
of one hour. Afterwards, the instance is
shut down.
The warning occurs even when you import a license within this hour. The instance is then not shut down.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout
ERuntimeErrorCode.ErrorLoadingDll

Condition

The instance is not registered in Runtime
Manager.
The expected operating state does not
occur on time.
The Siemens.Simatic.Simulation.
Runtime.Instance.exe cannot load the
Siemens.Simatic.PlcSim.Vplc1500.dll.

ERuntimeErrorCode.StoragePathAlreadyInUse

The selected path for this instance is
already being used by another instance.

ERuntimeErrorCode.NoStoragePathSet

The path could not be created. The
length of the
DSTORAGE_PATH_MAX_LENGTH characters
may be exceeded.

ERuntimeErrorCode.VirtualSwitchMisconfigured

The virtual switch is configured incorrectly.

ERuntimeErrorCode.InstanceNotRunning

The process of the virtual controller is no
longer running.

S7-PLCSIM Advanced

130

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

PowerOff()
Shuts down the Simulation Runtime and closes its process.
Table 7- 117 PowerOff() - Native C++
Syntax
Parameters

ERuntimeErrorCode PowerOff();
ERuntimeErrorCode PowerOff(
UINT32 in_Timeout_ms
);

•

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:

Return values

{ SROS_OFF }

Runtime error code

Condition

SREC_INTERFACE_REMOVED

The function is successful.
The instance is not registered in Runtime
Manager.

SREC_OK

SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING

The expected operating state does not
occur on time.
The process of the virtual controller is not
running.

Table 7- 118 PowerOff() - .NET (C#)
Syntax
Parameters

void PowerOff();
void PowerOff(
UInt32 in_Timeout_ms
);

•

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:

Return values
Exceptions

None

{ EOperatingState.Off }

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

131

User interfaces (API)
7.6 API IInstances

MemoryReset()
Shuts down the virtual controller, closes its processes and performs a restart.
Table 7- 119 MemoryReset() - Native C++
Syntax
Parameters

ERuntimeErrorCode MemoryReset();
ERuntimeErrorCode MemoryReset(
UINT32 in_Timeout_ms
);

•

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:

Return values

{ SROS_STOP , SROS_RUN }

Runtime error code

Condition

SREC_INTERFACE_REMOVED

The function is successful.
The instance is not registered in Runtime
Manager.

SREC_OK

SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING

The expected operating state does not
occur on time.
The process of the virtual controller is not
running.

Table 7- 120 MemoryReset() - .NET (C#)
Syntax
Parameters

void MemoryReset();
void MemoryReset(
UInt32 in_Timeout_ms
);

•

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:

Return values
Exceptions

None

{ EOperatingState.Run, EOperatingState.Stop }

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

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.

S7-PLCSIM Advanced

132

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

Run()
Calls on the virtual controller to change to RUN operating state.
Table 7- 121 Run() - Native C++
Syntax
Parameters

ERuntimeErrorCode Run();
ERuntimeErrorCode Run(
UINT32 in_Timeout_ms
);

•

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:

Return values

{ SROS_STOP , SROS_RUN }

Runtime error code
SREC_OK

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING

Condition
The function is successful.
The instance is not registered in Runtime
Manager.
The expected operating state does not
occur on time.
The process of the virtual controller is not
running.

Table 7- 122 Run() - .NET (C#)
Syntax
Parameters

void Run();
void Run(
Uint32 in_Timeout_ms
);

•

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 }

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout
ERuntimeErrorCode.InstanceNotRunning

Condition

The instance is not registered in Runtime
Manager.
The expected operating state does not
occur on time.
The process of the virtual controller is not
running.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

133

User interfaces (API)
7.6 API IInstances

Stop()
Calls on the virtual controller to change to STOP operating state.
Table 7- 123 Stop() - Native C++
Syntax
Parameters

ERuntimeErrorCode Stop();
ERuntimeErrorCode Stop(
UINT32 in_Timeout_ms
);

•

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:

Return values

{ SROS_STOP }

Runtime error code
SREC_OK

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING

Condition
The function is successful.
The instance is not registered in Runtime
Manager.
The expected operating state does not
occur on time.
The process of the virtual controller is not
running.

Table 7- 124 Stop() - .NET (C#)
Syntax
Parameters

void Stop();
void Stop(
bool in_IsSynchronous
);

•

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:

Return values
Exceptions

None

{ EOperatingState.Stop }

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

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.
S7-PLCSIM Advanced

134

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

7.6.4

Tag list

UpdateTagList()
The function reads the tags from the virtual controller and writes them to the shared storage
arranged by name.
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]", where {a} and {b} correspond to the first index of the
respective dimension
..
Entry_N: "ArrayName[x,y]", where {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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

135

User interfaces (API)
7.6 API IInstances
Table 7- 125 UpdateTagList() - Native C++
Syntax

Parameters

ERuntimeErrorCode UpdateTagList();
ERuntimeErrorCode UpdateTagList(
ETagListDetails in_TagListDetails
);
ERuntimeErrorCode UpdateTagList(
ETagListDetails in_TagListDetails,
bool in_IsHMIVisibleOnly
);

•

ETagListDetails in_TagListDetails:

Every combination of the following four areas:
IO: Inputs and Outputs
M: Bit memory
CT: Counters and Timers
DB: Data Blocks
Example: IOM reads only the tags from the area Inputs / Outputs and Bit
memory. The default setting is IOMCTDB.
•

Return values

bool in_IsHMIVisibleOnly:

If true, only tags marked with "HMI Visible" are read. The default setting is
true.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

The instance is not registered in Runtime
Manager.
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.

S7-PLCSIM Advanced

136

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 126 UpdateTagList() - .NET (C#)
Syntax

Parameters

void UpdateTagList();
void UpdateTagList(
ETagListDetails in_TagListDetails
);
void UpdateTagList(
ETagListDetails in_TagListDetails,
bool in_IsHMIVisibleOnly
);

•

ETagListDetails in_TagListDetails:

Every combination of the following four areas:
IO: Inputs and Outputs
M: Bit memory
CT: Counters and Timers
DB: Data Blocks
Example: IOM reads only the tags from the area Inputs / Outputs and Bit
memory.
The default setting is IOMCTDB.
•

bool in_IsHMIVisibleOnly:

If true, only tags marked with "HMI Visible" are read. The default setting is
true.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout

Condition

The instance is not registered in Runtime
Manager.
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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

137

User interfaces (API)
7.6 API IInstances

GetTagListStatus()
Returns the current update status of the tag list storage.
"inout_TagListDetails" is NONE, if the list needs to be updated.
Table 7- 127 GetTagListStatus() - Native C++
Syntax
Parameters

ERuntimeErrorCode GetTagListStatus(
ETagListDetails* out_TagListDetails,
bool* out_IsHMIVisibleOnly
);

•

ETagListDetails out_TagListDetails:

Status of the tag list details. SRTLD_NONE when an update of the list is required.
•
Return values

bool out_IsHMIVisibleOnly:

If true, only tags marked with "HMI Visible" are available in the list.

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.

Table 7- 128 GetTagListStatus() - .NET (C#)
Syntax
Parameters

void GetTagListStatus(
out ETagListDetails out_TagListDetails,
out bool out_IsHMIVisibleOnly
);

•

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

Condition

ERuntimeErrorCode.InterfaceRemoved

The instance is not registered in Runtime
Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

GetTagInfoCount()
Returns the number of entries in the tag list storage. If the function fails, the return value is 0.
Table 7- 129 GetTagInfoCount() - Native C++
Syntax

UINT32 GetTagInfoCount();

Parameters

None

Return values

Number of entries in the tag list storage.

S7-PLCSIM Advanced

138

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

GetTagInfos() / TagInfos { get; }
Returns a list of all tags.
Table 7- 130 GetTagInfos() - Native C++
Syntax
Parameters

ERuntimeErrorCode GetTagInfos(
UINT32 in_BufferLength,
STagInfo* inout_TagInfos,
UINT32* out_TagCount
);

•

UINT32 in_BufferLength:

The number of elements that the storage can accommodate.
•

STagInfo* inout_TagInfos:

•

UINT32* out_TagCount:

The user-allocated storage that accommodates the tags.
Returns the number of tags that were written to the storage.
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
SREC_INDEX_OUT_OF_RANGE

The process of the virtual controller is not
running.
The elements do not fit in the storage.

Table 7- 131 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

Condition

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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

139

User interfaces (API)
7.6 API IInstances

CreateConfigurationFile()
Writes all entries from the tag list to an XML file.
Table 7- 132 CreateConfigurationFile() - Native C++
Syntax
Parameters

ERuntimeErrorCode CreateConfigurationFile(
WCHAR* in_FullFileName
);

•

WCHAR* in_FullFileName:

Full file name of the XML file:
 +  + .
Return values

Runtime error code
SREC_OK

Condition
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 7- 133 CreateConfigurationFile() - .NET (C#)
Syntax
Parameters
Return values

void CreateConfigurationFile(
string in_FullFileName
);

None
•

string in_FullFileName:

File name of the XML file that is to be written to:
 +  + .

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 file name is invalid.

S7-PLCSIM Advanced

140

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

7.6.5

I/O access

7.6.5.1

I/O access via address - Reading

InputArea { get; }, MarkerArea { get; }, OutputArea { get; }
Returns an interface that you use to call the following .NET functions of section "I/O access
via address".
Table 7- 134 InputArea { get; } MarkerArea { get; } OutputArea { get; } - .NET (C#)
Syntax
Parameters
Return values

IIOArea InputArea { get; }
IIOArea MarkerArea { get; }
IIOArea OutputArea { get; }

None

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 7- 135 GetAreaSize() - Native C++
Syntax
Parameters

Return values

UINT32 GetAreaSize(
EArea in_Area
);

•

EArea in_Area:

The area whose size you want to receive. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 286).

UINT32: Size of the area in bytes. If the function was successful, the value is

not equal to 0.

Table 7- 136 AreaSize { get; } - .NET (C#)
Syntax
Parameters
Return values

UInt32 InputArea.AreaSize { get; }
UInt32 MarkerArea.AreaSize { get; }
UInt32 OutputArea.AreaSize { get; }

None

Uint32: Size of the area in bytes. If the function was successful, the value is
not equal to 0.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

141

User interfaces (API)
7.6 API IInstances

ReadBit()
Reads an individual bit from the area.
Note
The function allows access to the entire storage area of the virtual controller.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 137 ReadBit() - Native C++
Syntax

Parameters

ERuntimeErrorCode ReadBit(
EArea in_Area,
UINT32 in_Offset,
UINT8 in_Bit,
bool* out_Value
);

•

EArea in_Area:

The area from which you want to read. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 286).
•

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

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
SREC_INDEX_OUT_OF_RANGE
SREC_WRONG_ARGUMENT

The process of the virtual controller is not
running.
Offset or bits are invaid.
The area is invalid.

S7-PLCSIM Advanced

142

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 138 ReadBit() - .NET (C#)
Syntax

Parameters

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
);

•

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
Exceptions

bool: Bit value
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.InstanceNotRunning
ERuntimeErrorCode.IndexOutOfRange

The process of the virtual controller is not
running.
Offset or bits are invaid.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

143

User interfaces (API)
7.6 API IInstances

ReadByte()
Reads an individual bit from the area.
Note
The function allows access to the entire storage area of the virtual controller.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 139 ReadByte() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadByte(
EArea in_Area,
UINT32 in_Offset,
BYTE* out Value);

•

EArea in_Area:

The area from which you want to read. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 286).
•

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
SREC_OK

Condition
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.

S7-PLCSIM Advanced

144

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 140 ReadByte() - .NET (C#)
Syntax

Parameters

Return values
Exceptions

Byte InputArea.ReadByte(
UInt32 in_Offset
);
Byte MarkerArea.ReadByte(
UInt32 in_Offset
);
Byte OutputArea.ReadByte(
UInt32 in_Offset
);

•

UInt32 in_Offset:

The byte offset within the area. The value must be between 0 and the value
that AreaSize returns.

Byte: Byte value.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.IndexOutOfRange

Offset is invalid.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

145

User interfaces (API)
7.6 API IInstances

ReadBytes()
Reads a byte array from the area.
Note
The function allows access to the entire storage area of the virtual controller.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 141 ReadByte() - Native C++
Syntax

Parameters

ERuntimeErrorCode ReadBytes(
EArea in_Area,
UINT32 in_Offset,
UINT32 in_BytesToRead,
UINT32* out_BytesRead,
BYTE inout_Values[]
);

•

EArea in_Area:

The area from which you want to read. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 286).
•

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

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING
SREC_INDEX_OUT_OF_RANGE
SREC_WRONG_ARGUMENT

The instance is not registered in Runtime
Manager.
The function does not return on time.
The process of the virtual controller is not
running.
The offset is outside the area size. No
byte could be read.
The area is invalid.

S7-PLCSIM Advanced

146

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 142 ReadBytes() - .NET (C#)
Syntax

Parameters

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
);

•

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
Exceptions

Byte[]: The read bytes.
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.InstanceNotRunning
ERuntimeErrorCode.IndexOutOfRange

The process of the virtual controller is not
running.
The offset is outside the area size. No
byte could be read.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

147

User interfaces (API)
7.6 API IInstances

ReadSignals()
Reads a signal list altogether (structures and arrays). The function also takes into
consideration the byte order (Endianness).
Only primitive data type signals are supported, but the function is not typical.
Note
The function allows access to the entire storage area of the virtual controller.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 143 ReadSignals() - Native C++
Syntax

Parameters

ERuntimeErrorCode ReadSignals(
EArea in_Area,
SDataValueByAddress* inout_Signals,
UINT32 in_SignalCount
);

•

EArea in_Area:

The area from which you want to read. Permissible values:
{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 286).
•

SDataValueByAddress* inout_Signals:

The signal list to be read. The result is stored in the structure.
•

UINT32 in_SignalCount:

Number of signals in the list.
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
SREC_INDEX_OUT_OF_RANGE
SREC_WRONG_ARGUMENT

The process of the virtual controller is not
running.
Offset or bits are invaid.
The area is invalid.

S7-PLCSIM Advanced

148

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 144 ReadSignals() - .NET (C#)
Syntax
Parameters

void ReadSignals(
ref SDataValueByAddress[] inout_Signals
);

•

ref SDataValueByAddress[] inout_Signals:

The signal list to be read.
Return values
Exceptions

None

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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.IndexOutOfRange

Offset or bits are invaid.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

149

User interfaces (API)
7.6 API IInstances

7.6.5.2

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.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 145 WriteBit() - Native C++
Syntax

Parameters

ERuntimeErrorCode WriteBit(
EArea in_Area,
UINT32 in_Offset,
UINT8 in_Bit,
bool in_Value
);

•

EArea in_Area:

The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 286).
•

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
SREC_OK

Condition
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 invaid.

SREC_WRONG_ARGUMENT

Area is invalid.

S7-PLCSIM Advanced

150

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 146 WriteBit() - .NET (C#)
Syntax

Parameters

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
);

•

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

ERuntimeErrorCode.InterfaceRemoved

Condition

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 invaid.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

151

User interfaces (API)
7.6 API IInstances

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.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 147 WriteByte() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteByte(
EArea in_Area,
UINT32 in_Offset,
BYTE in Value);

•

EArea in_Area:

The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 286).
•

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
SREC_OK

Condition
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

152

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 148 WriteByte() - .NET (C#)
Syntax

Parameters

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
);

•

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

Condition

ERuntimeErrorCode.InterfaceRemoved

The instance is not registered in Runtime
Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.InstanceNotRunning
ERuntimeErrorCode.IndexOutOfRange

The process of the virtual controller is not
running.
Offset is invalid.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

153

User interfaces (API)
7.6 API IInstances

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.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 149 WriteBytes() - Native C++
Syntax

Parameters

ERuntimeErrorCode WriteBytes(
EArea in_Area,
UINT32 in_Offset,
UINT32 in_BytesToWrite,
UINT32* out_BytesWritten,
BYTE in_Values[])
;

•

EArea in_Area:

The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 286).
•

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.
Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING
SREC_INDEX_OUT_OF_RANGE
SREC_WRONG_ARGUMENT

The instance is not registered in Runtime
Manager.
The function does not return on time.
The process of the virtual controller is not
running.
The offset is outside the area size. No
byte could be written.
The area is invalid.

S7-PLCSIM Advanced

154

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 150 WriteBytes() - .NET (C#)
Syntax

Parameters

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
);

•

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
Exceptions

Uint32: Contains the number of bytes that were just written.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.IndexOutOfRange

The offset is outside the area size. No
byte could be written.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

155

User interfaces (API)
7.6 API IInstances

WriteSignals()
Writes a signal list altogether (structures and arrays). The function also takes into
consideration the byte order (Endianness).
The function supports only primitive data type signals. The function is not typical, however.
Note
Data can be overwritten
The function allows access to the entire storage area of the virtual controller.
Recommendation: Therefore, use access via the tag name and not via the address areas.

Table 7- 151 WriteSignals() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteSignals(
EArea in_Area,
SDataValueByAddress* in_Signals,
UINT32 in_SignalCount
);

•

EArea in_Area:

The area that is to be written.
Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.
See EArea (Page 286).
•

SDataValueByAddress* inout_Signals:

The signal list to be written.
•

UINT32 in_SignalCount:

Number of signals in the list.
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
SREC_INDEX_OUT_OF_RANGE
SREC_WRONG_ARGUMENT

The process of the virtual controller is not
running.
Offset or bits are invaid.
The area is invalid.

S7-PLCSIM Advanced

156

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 152 WriteSignals() - .NET (C#)
Syntax

Parameters

void InputArea.WriteSignals(
SDataValueByAddress[] in_Signals
);
void MarkerArea.WriteSignals(
SDataValueByAddress[] in_Signals
);
void OutputArea.WriteSignals(
SDataValueByAddress[] in_Signals
);

•

SDataValueByAddress[] in_Signals:

The signal list to be written.
Return values
Exceptions

None

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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.IndexOutOfRange

Offset or bits are invaid.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

157

User interfaces (API)
7.6 API IInstances

7.6.5.3

I/O access via tag name - Reading

Read()
Reads the value of a PLC tag.
Table 7- 153 Read() - Native C++
Syntax
Parameters

ERuntimeErrorCode Read(
WCHAR* in_Tag,
SDataValue* inout_Value
);

•

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 arrays can be read altogether with ReadSignals().
Return values

Runtime error code
SREC_OK

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

Condition
The function is successful.
The instance is not registered in Runtime
Manager.
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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

158

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 154 Read() - .NET (C#)
Syntax
Parameters

SDataValue Read(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

SDataValue: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types.

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

159

User interfaces (API)
7.6 API IInstances

ReadBool()
Reads the value of a PLC tag.
Table 7- 155 ReadBool() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadBool(
WCHAR* in_Tag,
bool* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

160

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 156 ReadBool() - .NET (C#)
Syntax
Parameters

bool ReadBool(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

bool: Contains the value of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

161

User interfaces (API)
7.6 API IInstances

ReadInt8()
Reads the value of a PLC tag.
Table 7- 157 ReadInt8() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadInt8(
WCHAR* in_Tag,
INT8* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

162

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 158 ReadInt8() - .NET (C#)
Syntax
Parameters

Int8 ReadInt8(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

Int8: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

163

User interfaces (API)
7.6 API IInstances

ReadInt16()
Reads the value of a PLC tag.
Table 7- 159 ReadInt16() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadInt16(
WCHAR* in_Tag,
INT16* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

164

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 160 ReadInt16() - .NET (C#)
Syntax
Parameters

Int16 ReadInt16(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

Int16: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

165

User interfaces (API)
7.6 API IInstances

ReadInt32()
Reads the value of a PLC tag.
Table 7- 161 ReadInt32() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadInt32(
WCHAR* in_Tag,
INT32* out_Value
);

•

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

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

166

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 162 ReadInt32() - .NET (C#)
Syntax
Parameters

Int32 ReadInt32(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

Int32: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

167

User interfaces (API)
7.6 API IInstances

ReadInt64()
Reads the value of a PLC tag.
Table 7- 163 ReadInt64() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadInt64(
WCHAR* in_Tag,
INT64* out_Value
);

•

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

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

168

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 164 ReadInt64() - .NET (C#)
Syntax
Parameters

Int64 ReadInt64(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

Int64: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

169

User interfaces (API)
7.6 API IInstances

ReadUInt8()
Reads the value of a PLC tag.
Table 7- 165 ReadUInt8() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadUInt8(
WCHAR* in_Tag,
UINT8* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

170

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 166 ReadUInt8() - .NET (C#)
Syntax
Parameters

UInt8 ReadUInt8(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

UInt8: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

171

User interfaces (API)
7.6 API IInstances

ReadUInt16()
Reads the value of a PLC tag.
Table 7- 167 ReadUInt16() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadUInt16(
WCHAR* in_Tag,
UINT16* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

172

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 168 ReadUInt16() - .NET (C#)
Syntax
Parameters

UInt16 ReadUInt16(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

UInt16: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

173

User interfaces (API)
7.6 API IInstances

ReadUInt32()
Reads the value of a PLC tag.
Table 7- 169 ReadUInt32() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadUInt32(
WCHAR* in_Tag,
UINT32* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

174

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 170 ReadUInt32() - .NET (C#)
Syntax
Parameters

UInt32 ReadUInt32(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

Uint32: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

175

User interfaces (API)
7.6 API IInstances

ReadUInt64()
Reads the value of a PLC tag.
Table 7- 171 ReadInt64() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadUInt64(
WCHAR* in_Tag,
UINT64* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

176

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 172 ReadUInt64() - .NET (C#)
Syntax
Parameters

UInt64 ReadUInt64(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

UInt64: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

177

User interfaces (API)
7.6 API IInstances

ReadFloat()
Reads the value of a PLC tag.
Table 7- 173 ReadFloat() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadFloat(
WCHAR* in_Tag,
float* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

178

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 174 ReadFloat() - .NET (C#)
Syntax
Parameters

float ReadFloat(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

float: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

179

User interfaces (API)
7.6 API IInstances

ReadDouble()
Reads the value of a PLC tag.
Table 7- 175 ReadDouble() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadDouble(
WCHAR* in_Tag,
double* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

180

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 176 ReadDouble() - .NET (C#)
Syntax
Parameters

double ReadDouble(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

double: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

181

User interfaces (API)
7.6 API IInstances

ReadChar()
Reads the value of a PLC tag.
Table 7- 177 ReadChar() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadChar(
WCHAR* in_Tag,
char* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

182

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 178 ReadChar() - .NET (C#)
Syntax
Parameters

sbyte ReadChar(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

sbyte: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

183

User interfaces (API)
7.6 API IInstances

ReadWChar()
Reads the value of a PLC tag.
Table 7- 179 ReadWChar() - Native C++
Syntax
Parameters

ERuntimeErrorCode ReadWChar(
WCHAR* in_Tag,
WCHAR* out_Value
);

•

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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

184

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 180 ReadWChar() - .NET (C#)
Syntax
Parameters

char ReadWChar(
string in_Tag
)

•

string in_Tag:

The name of the PLC tag that is to be read.
Return values
Exceptions

char: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

185

User interfaces (API)
7.6 API IInstances

ReadSignals()
Reads multiple signals within an API call.

Reads multiple signals within a single API call.
Table 7- 181 ReadSignals() - Native C++
Syntax

ERuntimeErrorCode ReadSignals(
SDataValueByName* inout_Signals,
UINT32 in_SignalCount

);
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.
•

UINT32 in_SignalCount:

The number of signals to be read.
Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING
SREC_DOES_NOT_EXIST
SREC_NOT_SUPPORTED
SREC_TYPE_MISMATCH

SREC_NOT_UP_TO_DATE

The instance is not registered in Runtime
Manager.
The function does not return on time.
The process of the virtual controller is not
running.
The entry does not exist in the stored tag
list.
Access to entire structures or arrays is
not supported.
The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).
The stored tag list must be updated.

S7-PLCSIM Advanced

186

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 182 ReadSignals() - .NET (C#)
Syntax
Parameters

Return values
Exceptions

void ReadSignals(
ref SDataValueByName[] inout_Signals
)

•

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.

SDataValue: Contains the value and the type of the PLC tag.
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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

187

User interfaces (API)
7.6 API IInstances

7.6.5.4

I/O access via tag name - Writing

Write()
Writes the value of a PLC tag.
Table 7- 183 Write() - Native C++
Syntax
Parameters

ERuntimeErrorCode Write(
WCHAR* in_Tag,
SDataValue* in_Value
);

•

WCHAR* in_Tag:

The name of the PLC tag that is to be written.
•

Return values

SDataValue* in_Value:

Contains the value and the expected type of the PLC tag.
The UNSPECIFIC and STRUCT types are not supported. Structures and arrays
can be written altogether with WriteSignals().

Runtime error code
SREC_OK

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

Condition

The function is successful.
The instance is not registered in Runtime
Manager.
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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

SREC_WRONG_ARGUMENT

The expected type is UNSPECIFIC.

S7-PLCSIM Advanced

188

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 184 Write() - .NET (C#)
Syntax
Parameters

void Write(
string in_Tag
SDataValue in_Value
)

•

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 arrays
can be written altogether with WriteSignals().

Return values

None

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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData
ERuntimeErrorCode.WrongArgument

The stored tag list must be updated.
The expected type is UNSPECIFIC.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

189

User interfaces (API)
7.6 API IInstances

WriteBool()
Writes the value of a PLC tag.
Table 7- 185 WriteBool() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteBool(
WCHAR* in_Tag,
bool in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

190

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 186 WriteBool() - .NET (C#)
Syntax
Parameters

void WriteBool(
string in_Tag
bool in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types.

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

191

User interfaces (API)
7.6 API IInstances

WriteInt8()
Writes the value of a PLC tag.
Table 7- 187 WriteInt8() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteInt8(
WCHAR* in_Tag,
INT8 in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

192

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 188 WriteInt8() - .NET (C#)
Syntax
Parameters

void WriteInt8(
string in_Tag
Int8 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

193

User interfaces (API)
7.6 API IInstances

WriteInt16()
Writes the value of a PLC tag.
Table 7- 189 WriteInt16() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteInt16(
WCHAR* in_Tag,
INT16 in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

194

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 190 WriteInt16() - .NET (C#)
Syntax
Parameters

void WriteInt16(
string in_Tag
Int16 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

195

User interfaces (API)
7.6 API IInstances

WriteInt32()
Writes the value of a PLC tag.
Table 7- 191 WriteInt32() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteInt32(
WCHAR* in_Tag,
INT32 in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

196

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 192 WriteInt32() - .NET (C#)
Syntax
Parameters

void WriteInt32(
string in_Tag
Int32 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

197

User interfaces (API)
7.6 API IInstances

WriteInt64()
Writes the value of a PLC tag.
Table 7- 193 WriteInt64() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteInt64(
WCHAR* in_Tag,
INT64 in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

198

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 194 WriteInt64() - .NET (C#)
Syntax
Parameters

void WriteInt64(
string in_Tag
Int64 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

199

User interfaces (API)
7.6 API IInstances

WriteInt8()
Writes the value of a PLC tag.
Table 7- 195 WriteUInt8() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteUInt8(
WCHAR* in_Tag,
UINT8 in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

200

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 196 WriteUInt8() - .NET (C#)
Syntax
Parameters

void WriteUInt8(
string in_Tag
UInt8 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

201

User interfaces (API)
7.6 API IInstances

WriteUInt16()
Reads the value of a PLC tag.
Table 7- 197 WriteUInt16() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteUInt16(
WCHAR* in_Tag,
UINT16 in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

202

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 198 WriteUInt16() - .NET (C#)
Syntax
Parameters

void WriteUInt16(
string in_Tag
UInt16 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

203

User interfaces (API)
7.6 API IInstances

WriteUInt32()
Writes the value of a PLC tag.
Table 7- 199 WriteUInt32() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteUInt32(
WCHAR* in_Tag,
UINT32 in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

204

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 200 WriteUInt32() - .NET (C#)
Syntax
Parameters

void WriteUInt32(
string in_Tag
UInt32 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

205

User interfaces (API)
7.6 API IInstances

WriteUInt64()
Writes the value of a PLC tag.
Table 7- 201 WriteUInt64() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteUInt64(
WCHAR* in_Tag,
UINT64 in_Value
);

•

WCHAR* in_Tag:

•

UINT64 in_Value:

The name of the PLC tag that is to be written.
Contains the value of the PLC tag.
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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

206

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 202 WriteUInt64() - .NET (C#)
Syntax
Parameters

void WriteUInt64(
string in_Tag
UInt64 in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

207

User interfaces (API)
7.6 API IInstances

WriteFloat()
Writes the value of a PLC tag.
Table 7- 203 WriteFloat() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteFloat(
WCHAR* in_Tag,
float in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

208

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 204 WriteFloat() - .NET (C#)
Syntax
Parameters

void WriteFloat(
string in_Tag
float in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

209

User interfaces (API)
7.6 API IInstances

WriteDouble()
Writes the value of a PLC tag.
Table 7- 205 WriteDouble() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteDouble(
WCHAR* in_Tag,
double in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

210

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 206 WriteDouble() - .NET (C#)
Syntax
Parameters

void WriteDouble(
string in_Tag
double in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

211

User interfaces (API)
7.6 API IInstances

WriteChar()
Writes the value of a PLC tag.
Table 7- 207 WriteChar() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteChar(
WCHAR* in_Tag,
char in_Value
);

•

WCHAR* 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

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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

212

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 208 WriteChar() - .NET (C#)
Syntax
Parameters

void WriteChar(
string in_Tag
sbyte in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

213

User interfaces (API)
7.6 API IInstances

WriteWChar()
Writes the value of a PLC tag.
Table 7- 209 WriteWChar() - Native C++
Syntax
Parameters

ERuntimeErrorCode WriteWChar(
WCHAR* in_Tag,
WCHAR in_Value
);

•

WCHAR* in_Tag:

The name of the PLC tag that is to be written.
•

WCHAR in_Value:

Contains the value of the PLC tag.
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 supported.

SREC_TYPE_MISMATCH

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

S7-PLCSIM Advanced

214

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 210 WriteWChar() - .NET (C#)
Syntax
Parameters

void WriteWChar(
string in_Tag
char in_Value
)

•

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

Condition

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.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMissmatch

The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

ERuntimeErrorCode.NotUpToData

The stored tag list must be updated.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

215

User interfaces (API)
7.6 API IInstances

WriteSignals()
Writes multiple signals within an API call.
Table 7- 211 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.
Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING
SREC_DOES_NOT_EXIST
SREC_NOT_SUPPORTED
SREC_TYPE_MISMATCH

The instance is not registered in Runtime
Manager.
The function does not return on time.
The process of the virtual controller is not
running.
The entry does not exist in the stored tag
list.
Access to entire structures or arrays is
not supported.
The expected type does not match the
stored type. See Compatible primitive
data types (Page 294).

SREC_NOT_UP_TO_DATE

The stored tag list must be updated.

SREC_WRONG_ARGUMENT

The expected type is UNSPECIFIC.

S7-PLCSIM Advanced

216

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances
Table 7- 212 WriteSignals() - .NET (C#)
Syntax
Parameters

Return values
Exceptions

void WriteSignals(
SDataValueByName[] in_Signals
)

•

SDataValueByName:

Contains the name, the value and the expected type of the PLC tag. The
UNSPECIFIC and STRUCT types are not supported.

None

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.InstanceNotRunning

The process of the virtual controller is not
running.

ERuntimeErrorCode.DoesNotExist

The entry does not exist in the stored tag
list.

ERuntimeErrorCode.NotSupported

Access to entire structures or arrays is
not supported.

ERuntimeErrorCode.TypeMismatch

The expected type does not match the
stored type. See Compatible primitive
data types.

ERuntimeErrorCode.NotUpToData
ERuntimeErrorCode.WrongArgument

The stored tag list must be updated.
The expected type is UNSPECIFIC.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

217

User interfaces (API)
7.6 API IInstances

7.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 7- 213 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 7- 214 SetSystemTime() - Native C++
Syntax
Parameters

ERuntimeErrorCode SetSystemTime(
SYSTEMTIME in_SystemTime
);

•

SYSTEMTIME in_SystemTime:

System time that is to be set for the virtual controller.
Return values

Runtime error code
SREC_OK

Condition
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 7- 215 SystemTime { get; set; } - .NET (C#)
Syntax

DateTime SystemTime { get; set; }

Parameters

None

Return values

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout
ERuntimeErrorCode.WrongArgument

Condition

The instance is not registered in Runtime
Manager.
The function does not return on time.
The value is outside the limits.

S7-PLCSIM Advanced

218

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

GetScaleFactor()
Returns the scaling factor with which the virtual time advances.
Table 7- 216 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.
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 7- 217 SetScaleFactor() - Native C++
Syntax
Parameters

ERuntimeErrorCode SetScaleFactor (
double in_Value
);

•

double in_Value:

Scaling factor of the virtual time.
Return values

Runtime error code
SREC_OK

Condition
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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

219

User interfaces (API)
7.6 API IInstances

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 7- 218 ScaleFactor { get; set; } - .NET (C#)
Syntax

double ScaleFactor { get; set; }

Parameters

None

Return values

double: Scaling factor of the virtual time.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Exceptions

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout
ERuntimeErrorCode.WrongArgument

Condition

The instance is not registered in Runtime
Manager.
The function does not return on time.
The value is outside the limits.

S7-PLCSIM Advanced

220

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

7.6.7

Cycle control

GetOperatingMode()
Returns the operating mode of the virtual controller.
Table 7- 219 GetOperatingMode() - Native C++
Syntax

EOperatingMode GetOperatingMode();

Parameters

None

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 cycle control point.
Table 7- 220 SetOperatingMode() - Native C++
Syntax

void SetOperatingMode(
EOperatingMode in_OperatingMode
);

Parameters

•

Return values

Runtime error code

EOperatingMode in_OperatingMode:

Operating mode of the virtual controller
SREC_OK

Condition
The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime
Manager.

SREC_TIMEOUT

The function does not return on time.

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 cycle control point.
Table 7- 221 OperatingMode { get; set; } - .NET (C#)
Syntax

EOperatingMode OperatingMode { get; set; }

Parameters

None

Return values

EOperatingMode: Operating mode of the virtual controller
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Exceptions

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout

Condition

The instance is not registered in Runtime
Manager.
The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

221

User interfaces (API)
7.6 API IInstances

SetAlwaysSendOnEndOfCycleEnabled()
Sets the AlwaysSendOnEndOfCycle mode. If the mode is set, the OnEndOfCycle event is
triggered after every cycle end for each operating mode. If the event is also to be received in
Default operating mode, set the return value to true. See OnEndOfCycle (Page 232).
Table 7- 222 SetAlwaysSendOnEndOfCycleEnabled() - Native C++
Syntax
Parameters
Return values

ERuntimeErrorCode SetAlwaysSendOnEndOfCycleEnabled(
bool in_Enable
);

•

bool in_Enable:

If true, the OnEndOfCycle event is triggered after every cycle.

Runtime error code
SREC_OK

Condition

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime
Manager.

SREC_TIMEOUT

The function does not return on time.

IsAlwaysSendOnEndOfCycleEnabled()
Returns the AlwaysSendOnEndOfCycle mode. When the function fails, the return value is false.
Table 7- 223 IsAlwaysSendOnEndOfCycleEnabled() - Native C++
Syntax

bool IsAlwaysSendOnEndOfCycleEnabled();

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.

IsAlwaysSendOnEndOfCycleEnabled { get; set; }
Returns or sets the AlwaysSendOnEndOfCycle mode. If the mode is set, the OnEndOfCycle event
is triggered after every cycle end for each operating mode. If the event is also to be received
in Default operating mode, set the return value to true. See OnEndOfCycle (Page 232).
Table 7- 224 IsAlwaysSendOnEndOfCycleEnabled { get; set; } - .NET (C#)
Syntax

bool IsAlwaysSendOnEndOfCycleEnabled { get; set;}

Parameters

None

Return values

•
•

Exceptions

false: The event is not triggered (unless the Sync-Freeze mode is active).
true: The event is triggered after every cycle.

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout

Condition

The instance is not registered in Runtime
Manager.
The function does not return on time.

S7-PLCSIM Advanced

222

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

GetOverwrittenMinimalCycleTime_ns()
Returns the overwritten minimum cycle time (in nanoseconds) that is used in the
ExtendedSingleStep operating mode.
Table 7- 225 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
ExtendedSingleStep operating mode.
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 7- 226 SetOverwrittenMinimalCycleTime_ns() - Native C++
Syntax

ERuntimeErrorCode SetOverwrittenMinimalCycleTime_ns(
INT64 in_CycleTime_ns
);

Parameters

•

Return values

Runtime error code

INT64 in_CycleTime_ns:

The overwritten minimum cycle time in nanoseconds.
SREC_OK

Condition
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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

223

User interfaces (API)
7.6 API IInstances

OverwrittenMinimalCycleTime_ns { get; set; }
Returns or sets the overwritten minimum cycle time in nanoseconds that is used in the
ExtendedSingleStep operating mode.
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 7- 227 OverwrittenMinimalCycleTime_ns { get; set; } - .NET (C#)
Syntax

Int64 OverwrittenMinimalCycleTime_ns { get; set; }

Parameters

None

Return values

Int64: The overwritten minimum cycle time in nanoseconds.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Exceptions

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout
ERuntimeErrorCode.WrongArgument

Condition

The instance is not registered in Runtime
Manager.
The function does not return on time.
The value is outside the limits.

S7-PLCSIM Advanced

224

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

RunNextCycle()
If the virtual controller is being operated in SingleStep or ExtendedSingleStep operating
mode, it is stopped at the cycle control point (Freeze state). The RunNextCycle() function is
used to trigger the next cycle.
Table 7- 228 RunNextCycle() - Native C++
Syntax

ERuntimeErrorCode RunNextCycle();

Parameters

None

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INSTANCE_NOT_RUNNING

The instance is not registered in Runtime
Manager.
The function does not return on time.
The process of the virtual controller is not
running.

Table 7- 229 RunNextCycle() - .NET (C#)
Syntax

void RunNextCycle();

Parameters

None

Return values

None

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.InstanceNotRunning

The process of the virtual controller is not
running.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

225

User interfaces (API)
7.6 API IInstances

StartProcessing()
If the virtual controller is running in TimespanSynchronized operating mode, it is stopped at the
cycle control point (Freeze state). The StartProcessing() function wakes up the virtual
controller from the Freeze state. The virtual controller will now run for at least the requested
time before it changes to Freeze state (stops) at the next cycle control point.
Table 7- 230 StartProcessing() - Native C++
Syntax
Parameters

ERuntimeErrorCode StartProcessing(
INT64 in_MinimalTimeToRun_ns
);

•

INT64 in_CycleTime_ns:

The minimum virtual time (in nanoseconds) that the virtual controller runs before it changes to Freeze state.
Return values

Runtime error code
SREC_OK

Condition
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 7- 231 StartProcessing() - .NET (C#)
Syntax
Parameters

void StartProcessing(
Int64 in_MinimalTimeToRun_ns
);

•

Int64 in_CycleTime_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

Condition

ERuntimeErrorCode.InterfaceRemoved

The instance is not registered in Runtime
Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.InstanceNotRunning
ERuntimeErrorCode.WrongArgument

The process of the virtual controller is not
running.
The value is less than 0.

Additional information
For more information, please refer to the section titled Time response (Page 58), Stopping
the simulation (Page 61)

S7-PLCSIM Advanced

226

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

See also
OnOperatingStateChanged (Page 228)

7.6.8

Events

Events for IInstances
The following events are differentiated in the API:
Table 7- 232 Events for the IInstances interface
Event

Cause

OnOperatingStateChanged
(Page 228)

This event is always triggered when the operating state of the virtual
controller has changed.

OnEndOfCycle (Page 232)

This event is triggered when the virtual controller reaches the end of
the main cycle.
If the virtual controller is being operated in Default operating mode,
the AlwaysSendOnEndOfCycle flag must be set to receive the event.
See AlwaysSendOnEndOfCycle (Page 221).

OnConfigurationChanging
(Page 234)

This event is triggered when changing of the configuration of the virtual controller starts.
•

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.
OnConfigurationChanged
(Page 237)

OnLedChanged (Page 239)

This event is triggered when 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

This event is triggered when the LED display of the virtual controller
has changed.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

227

User interfaces (API)
7.6 API IInstances

7.6.8.1

OnOperatingStateChanged

OnOperatingStateChanged
Registers or unregisters an event handler method.
Table 7- 233 OnOperatingStateChanged - .NET (C#)
Syntax

event Delegate_II_EREC_DT_EOS_EOS OnOperatingStateChanged;

Parameters

None. See Delegate_II_EREC_DT_EOS_EOS (Page 266).

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. Only one callback function
can be registered for the event. Registering a new callback function causes the previous
callback function to be deleted.
Table 7- 234 RegisterOnOperatingStateChangedCallback() - Native C++
Syntax
Parameters

void RegisterOnOperatingStateChangedCallback(
EventCallback_II_SREC_ST_SROS_SROS in_CallbackFunction
);

•

EventCallback_II_SREC_ST_SROS_SROS in_CallbackFunction:

A callback function that subscribes to the event.
See EventCallback_II_SREC_ST_SROS_SROS (Page 260).
Return values

None

Note

The callback function runs in a separate thread.

S7-PLCSIM Advanced

228

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

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 7- 235 RegisterOnOperatingStateChangedEvent() - Native C++
Syntax
Parameters

void RegisterOnOperatingStateChangedEvent();
void RegisterOnOperatingStateChangedEvent(
HANDLE* in_Event
);

•

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

Example C++

// Thread 1 -------------------------------------------------ISimulationRuntimeManager * api = ZERO;
ERuntimeErrorCode result = Initialize(&api);
IInstance* psa = ZERO;
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
…
}
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

229

User interfaces (API)
7.6 API IInstances
Example C++

// Thread 1 -------------------------------------------------ISimulationRuntimeManager * api = ZERO;
ERuntimeErrorCode result = Initialize(&api);
IInstance* psa = ZERO;
if (result == SREC_OK)
{
result = api->RegisterInstance(&psa);
}
// Create an event object
HANDLE eventHandle = CreateEvent(ZERO, FALSE, FALSE, ZERO);
// 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
…
}

UnregisterOnOperatingStateChangedCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 7- 236 UnregisterOnOperatingStateChangedCallback() - Native C++
Syntax

void UnregisterOnOperatingStateChangedCallback();

Parameters

None

Return values

None

S7-PLCSIM Advanced

230

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

UnregisterOnOperatingStateChangedEvent()
Unregisters the event object.
Table 7- 237 UnregisterOnOperatingStateChangedEvent() - Native C++
Syntax

void UnregisterOnOperatingStateChangedEvent();

Parameters

None

Return values

None

Table 7- 238 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 7- 239 WaitForOnOperatingStateChangedEvent() - Native C++
Syntax
Parameters

bool WaitForOnOperatingStateChangedEvent();
bool WaitForOnOperatingStateChangedEvent(
UINT32 in_Time_ms
);

•

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 7- 240 WaitForOnOperatingStateChangedEvent() - .NET (C#)
Syntax
Parameters

bool WaitForOnOperatingStateChangedEvent();
bool WaitForOnOperatingStateChangedEvent(
UInt32 in_Time_ms
);

•

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, 09/2016, A5E37039512-AA

231

User interfaces (API)
7.6 API IInstances

7.6.8.2

OnEndOfCycle

OnEndOfCycle
Registers or unregisters an event handler method.
Table 7- 241 OnEndOfCycle - .NET (C#)
Syntax

event Delegate_II_EREC_DT OnEndOfCycle;

Parameters

None. See Delegate_II_EREC_DT (Page 265).

Return values

None

Exceptions

None

Note

The event handler method runs in a separate thread.

RegisterOnEndOfCycleCallback()
When the event occurs, the registered callback function is called. Only one callback function
can be registered for the event. Registering a new callback function causes the previous
callback function to be deleted.
Table 7- 242 RegisterOnEndOfCycleCallback() - Native C++
Syntax
Parameters

void RegisterOnEndOfCycleCallback(
EventCallback_II_SREC_ST in_CallbackFunction
);

•

EventCallback_II_SREC_ST in_CallbackFunction:

A callback function that subscribes to an event.
See EventCallback_II_SREC_ST (Page 259).
Return values

None

Note

The callback function runs in a separate thread.

RegisterOnEndOfCycleEvent()
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 7- 243 RegisterOnEndOfCycleEvent() - Native C++
Syntax
Parameters

void RegisterOnEndOfCycleEvent();
void RegisterOnEndOfCycleEvent(
HANDLE* in_Event
);

•

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

232

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

UnregisterOnEndOfCycleCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 7- 244 UnregisterOnEndOfCycleCallback() - Native C++
Syntax

void UnregisterOnEndOfCycleCallback();

Parameters

None

Return values

None

UnregisterOnEndOfCycleEvent()
Unregisters the event object.
Table 7- 245 RegisterOnEndOfCycleEvent() - Native C++
Syntax

void UnregisterOnEndOfCycleEvent();

Parameters

None

Return values

None

Table 7- 246 UnregisterOnEndOfCycleEvent() - .NET (C#)
Syntax

void UnregisterOnEndOfCycleEvent();

Parameters

None

Return values

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

233

User interfaces (API)
7.6 API IInstances

WaitForOnEndOfCycleEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 7- 247 WaitForOnEndOfCycleEvent() - Native C++
Syntax
Parameters

bool WaitForOnEndOfCycleEvent();
bool WaitForOnEndOfCycleEvent(
UINT32 in_Time_ms
);

•

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 7- 248 WaitForOnEndOfCycleEvent() - .NET (C#)
Syntax
Parameters

bool WaitForOnEndOfCycleEvent();
bool WaitForOnEndOfCycleEvent(
UInt32 in_Time_ms
);

•

None:

The time limit is set to INFINITE.
•

UInt32 in_Time_ms:

Value for the time limit in milliseconds.
Return values

•
•

7.6.8.3

true: If the event object was set to the signaled state.

false: If no event was received during the defined time limit.

OnConfigurationChanging

OnConfigurationChanging
Registers or unregisters an event handler method.
Table 7- 249 OnConfigurationChanging - .NET (C#)
Syntax

event Delegate_II_EREC_DT OnConfigurationChanging;

Parameters

None. See Delegate_II_EREC_DT (Page 265).

Return values

None

Exceptions

None

Note

The event handler method runs in a separate thread.

S7-PLCSIM Advanced

234

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

RegisterOnConfigurationChangingCallback()
When the event occurs, the registered callback function is called. Only one callback function
can be registered for the event. Registering a new callback function causes the previous
callback function to be deleted.
Table 7- 250 RegisterOnConfigurationChangingCallback() - Native C++
Syntax
Parameters

void RegisterOnConfigurationChangingCallback(
EventCallback_II_SREC_ST in_CallbackFunction
);

•

EventCallback_II_SREC_ST in_CallbackFunction:

A callback function that subscribes to an event.
See EventCallback_II_SREC_ST (Page 259).
Return values

None

Note

The callback function runs in a separate thread.

RegisterOnConfigurationChangingEvent()
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 7- 251 RegisterOnConfigurationChangingEvent() - Native C++
Syntax
Parameters

void RegisterOnConfigurationChangingEvent();
void RegisterOnConfigurationChangingEvent(
HANDLE* in_Event
);

•

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

UnregisterOnConfigurationChangingCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 7- 252 UnregisterOnConfigurationChangingCallback() - Native C++
Syntax

void UnregisterOnConfigurationChangingCallback();

Parameters

None

Return values

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

235

User interfaces (API)
7.6 API IInstances

UnregisterOnConfigurationChangingEvent()
Unregisters the event object.
Table 7- 253 UnregisterOnConfigurationChangingEvent() - Native C++
Syntax

void UnregisterOnConfigurationChangingEvent();

Parameters

None

Return values

None

Table 7- 254 UnregisterOnConfigurationChangingEvent() - .NET (C#)
Syntax

void UnregisterOnConfigurationChangingEvent();

Parameters

None

Return values

None

WaitForOnConfigurationChangingEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 7- 255 WaitForOnConfigurationChangingEvent() - Native C++
Syntax
Parameters

bool WaitForOnConfigurationChangingEvent();
bool WaitForOnConfigurationChangingEvent(
UINT32 in_Time_ms
);

•

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 7- 256 WaitForOnConfigurationChangingEvent() - .NET (C#)
Syntax
Parameters

bool WaitForOnConfigurationChangingEvent();
bool WaitForOnConfigurationChangingEvent(
UInt32 in_Time_ms
);

•

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

236

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

7.6.8.4

OnConfigurationChanged

OnConfigurationChanged
Registers or unregisters an event handler method.
Table 7- 257 OnConfigurationChanged - .NET (C#)
Syntax

event Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32 OnConfigurationChanged;

Parameters

None. See Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32
(Page 270).

Return values

None

Exceptions

None

Note

The event handler method runs in a separate thread.

RegisterOnConfigurationChangedCallback()
When the event occurs, the registered callback function is called. Only one callback function
can be registered for the event. Registering a new callback function causes the previous
callback function to be deleted.
Table 7- 258 RegisterOnConfigurationChangedCallback() - Native C++
Syntax
Parameters

void RegisterOnConfigurationChangedCallback(
EventCallback_SRCC_UINT32_UINT32_INT32 in_CallbackFunction
);

•

EventCallback_SRCC_UINT32_UINT32_INT32 in_CallbackFunction:

A callback function that subscribes to an event.
See EventCallback_SRCC_UINT32_UINT32_INT32 (Page 263).
Return values

None

Note

The callback function runs in a separate thread.

RegisterOnConfigurationChangedEvent()
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 7- 259 RegisterOnConfigurationChangedEvent() - Native C++
Syntax
Parameters

void RegisterOnConfigurationChangedEvent();
void RegisterOnConfigurationChangedEvent(
HANDLE* in_Event
);

•

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, 09/2016, A5E37039512-AA

237

User interfaces (API)
7.6 API IInstances

UnregisterOnConfigurationChangedCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 7- 260 UnregisterOnConfigurationChangedCallback() - Native C++
Syntax

void UnregisterOnConfigurationChangedCallback();

Parameters

None

Return values

None

UnregisterOnConfigurationChangedEvent()
Unregisters the event object.
Table 7- 261 UnregisterOnConfigurationChangedEvent() - Native C++
Syntax

void UnregisterOnConfigurationChangedEvent();

Parameters

None

Return values

None

Table 7- 262 UnregisterOnConfigurationChangedEvent() - .NET (C#)
Syntax

void UnregisterOnConfigurationChangedEvent();

Parameters

None

Return values

None

S7-PLCSIM Advanced

238

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

WaitForOnConfigurationChangedEvent()
The function blocks the program until the registered event object is in the signaled state or
the timeout interval is exceeded.
Table 7- 263 WaitForOnConfigurationChangedEvent() - Native C++
Syntax
Parameters

bool WaitForOnConfigurationChangedEvent();
bool WaitForOnConfigurationChangedEvent(
UINT32 in_Time_ms
);

•

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 7- 264 WaitForOnConfigurationChangedEvent() - .NET (C#)
Syntax
Parameters

bool WaitForOnConfigurationChangedEvent();
bool WaitForOnConfigurationChangedEvent(
UInt32 in_Time_ms
);

•

None:

The time limit is set to INFINITE.
•

UInt32 in_Time_ms:

Value for the time limit in milliseconds.
Return values

•
•

7.6.8.5

true: If the event object was set to the signaled state.

false: If no event was received during the defined time limit.

OnLedChanged

OnLedChanged
Registers or unregisters an event handler method.
Table 7- 265 OnLedChanged - .NET (C#)
Syntax

event Delegate_II_EREC_DT_ELT_ELM OnLedChanged;

Parameters

None. See Delegate_II_EREC_DT_ELT_ELM (Page 267).

Return values

None

Exceptions

None

Note

The event handler method runs in a separate thread.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

239

User interfaces (API)
7.6 API IInstances

RegisterOnLedChangedCallback()
When the event occurs, the registered callback function is called. Only one callback function
can be registered for the event. Registering a new callback function causes the previous
callback function to be deleted.
Table 7- 266 RegisterOnLedChangedCallback() - Native C++
Syntax
Parameters

void RegisterOnLedChangedCallback(
EventCallback_II_SREC_ST_SRLT_SRLM in_CallbackFunction
);

•

EventCallback_II_SREC_ST_SRLT_SRLM in_CallbackFunction:

A callback function that subscribes to an event.
See EventCallback_II_SREC_ST_SRLT_SRLM (Page 261).
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 7- 267 RegisterOnLedChangedEvent() - Native C++
Syntax
Parameters

void RegisterOnLedChangedEvent();
void RegisterOnLedChangedEvent(
HANDLE* in_Event
);

•

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

UnregisterOnLedChangedCallback()
Unregisters the callback function. When the event occurs, no callback function is called.
Table 7- 268 UnregisterOnLedChangedCallback() - Native C++
Syntax

void UnregisterOnLedChangedCallback();

Parameters

None

Return values

None

S7-PLCSIM Advanced

240

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.6 API IInstances

UnregisterOnLedChangedEvent()
Unregisters the event object.
Table 7- 269 UnregisterOnLedChangedEvent() - Native C++
Syntax

void UnregisterOnLedChangedEvent();

Parameters

None

Return values

None

Table 7- 270 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 7- 271 WaitForOnLedChangedEvent() - Native C++
Syntax
Parameters

bool WaitForOnLedChangedEvent();
bool WaitForOnLedChangedEvent(
UINT32 in_Time_ms
);

•

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 7- 272 WaitForOnLedChangedEvent() - .NET (C#)
Syntax
Parameters

bool WaitForOnLedChangedEvent();
bool WaitForOnLedChangedEvent(
UInt32 in_Time_ms
);

•

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, 09/2016, A5E37039512-AA

241

User interfaces (API)
7.7 API IRemoteRuntimeManager

7.7

API IRemoteRuntimeManager

7.7.1

Interfaces - Information and settings

Dispose()
Deletes the managed interface and unloads the native components of the user interfaces.
Table 7- 273 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 7- 274 GetVersion() - Native C++
Syntax

UINT32 GetVersion();

Parameters

None

Return values

UINT32: Remote Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

Table 7- 275 Version { get; } - .NET (C#)
Syntax

UInt32 Version { get; }

Parameters

None

Return values

Uint32: Remote Runtime Manager Version (HIWORD = Major, LOWORD = Minor)

S7-PLCSIM Advanced

242

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.7 API IRemoteRuntimeManager

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 7- 276 GetIP() - Native C++
Syntax

UIP GetIP();

Parameters

None

Return values

UIP: Returns the IP address of the PC on which the Runtime Manager is run-

ning.

Table 7- 277 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 run-

ning.

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 7- 278 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 7- 279 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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

243

User interfaces (API)
7.7 API IRemoteRuntimeManager

GetRemoteComputerName() / RemoteComputerName { get; }
Returns the name of the PC on which the remote Runtime Manager is running.
Table 7- 280 GetRemoteComputerName() - Native C++
Syntax
Parameters

ERuntimeErrorCode GetRemoteComputerName(
WCHAR* inout_Name,
UINT32 in_ArrayLength
);

•

WCHAR* inout_Name:

A user-allocated array for the computer name.
•
Return values

UINT32 in_ArrayLength:

The array length. The array should be longer than MAX_COMPUTERNAME_LENGTH.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The interface is disconnected from the
remote Runtime Manager.

SREC_INDEX_OT_OF_RANGE

The array is too small to accommodate
the computer name.

Table 7- 281 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.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Exceptions

Runtime error code

Condition

ERuntimeErrorCode.InterfaceRemoved

The interface is disconnected from the
remote Runtime Manager.

ERuntimeErrorCode.IndexOutOfRange

The array is too small to accommodate
the computer name.

S7-PLCSIM Advanced

244

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.7 API IRemoteRuntimeManager

Disconnect()
Closes the connection to the remote Runtime Manager.
Note
All applications that are connected to the remote Runtime Manager lose this connection.

Table 7- 282 Disconnect() - Native C++
Syntax

ERuntimeErrorCode Disconnect();

Parameters

None

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

The interface is disconnected from the
remote Runtime Manager.
The function does not return on time.

Table 7- 283 Disconnect() - .NET (C#)
Syntax

void Disconnect();

Parameters

None

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeErrorCode.InterfaceRemoved

The interface is disconnected from the
remote Runtime Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

245

User interfaces (API)
7.7 API IRemoteRuntimeManager

7.7.2

Simulation Runtime instances

7.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 7- 284 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 7- 285 GetRegisteredInstanceInfoAt() - Native C++
Syntax
Parameters

ERuntimeErrorCode GetRegisteredInstanceInfoAt(
UINT32 in_Index,
SInstanceInfo* out_InstanceInfo
);

•

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 278).
Return values

Runtime error code
SREC_OK

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_INDEX OUT_OF_RANGE

Condition
The function is successful.
The interface is disconnected from the
remote Runtime Manager.
The function does not return on time.
There is no instance information for this
index.

S7-PLCSIM Advanced

246

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.7 API IRemoteRuntimeManager

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 7- 286 RegisterInstanceInfo { get; } - .NET (C#)
Syntax
Parameters

SInstanceInfo[] RegisteredInstanceInfo { get; }

None

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout

Condition

The interface is disconnected from the
remote Runtime Manager.
The function does not return on time.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

247

User interfaces (API)
7.7 API IRemoteRuntimeManager

RegisterInstance()
Registers a new instance of a virtual controller in Runtime Manager. Creates and returns an
interface of this instance.
Table 7- 287 RegisterInstance() - Native C++
Syntax

Parameters

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
);

•

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 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 271).
•

Return values

IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The interface is created within the function.

Runtime error code
SREC_OK

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

Condition

The function is successful.
The interface is disconnected from the
remote Runtime Manager.
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.

S7-PLCSIM Advanced

248

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.7 API IRemoteRuntimeManager
Example C++

ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = Initialize(&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 it.
See DestroyInterface() (Page 82).

Table 7- 288 RegisterInstance() - .NET (C#)
Syntax

Parameters

IInstance RegisterInstance();
IInstance RegisterInstance(
string in_InstanceName
);
IInstance RegisterInstance(
ECPUType in_CPUType
);
IInstance RegisterInstance(
ECPUType in_CPUType
string in_InstanceName
);

•

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 Memory
Card, this CPU type applies.
•

Return values

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 271).

If the function is successful, an interface of a virtual controller. Otherwise, a Null
pointer.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

249

User interfaces (API)
7.7 API IRemoteRuntimeManager
Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout

Condition

The interface is disconnected from the
remote Runtime Manager.
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 7- 289 RegisterCustomInstance() - Native C++
Syntax

Parameters

ERuntimeErrorCode RegisterCustomInstance(
WCHAR* in_VplcDll,
IInstance** out_InstanceInterface
);
ERuntimeErrorCode RegisterCustomInstance(
WCHAR* in_VplcDll,
WCHAR* in_InstanceName,
IInstance** out_InstanceInterface
);

•

WCHAR* in_VplcDll:

The complete path to the DLL of the virtual controller that Siemens.Simatic.Simulation.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 271).
•

Return values

IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The interface is created within the function.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT
SREC_WRONG_ARGUMENT
SREC_LIMIT_REACHED
SREC_ALREADY_EXISTS

The interface is disconnected from the
remote Runtime Manager.
The function does not return on time.
The DLL name, the instance name or the
IInstance pointer is invalid.
There are already 16 instances registered in Runtime Manager.
An instance with this name already exists.

S7-PLCSIM Advanced

250

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.7 API IRemoteRuntimeManager
Example C++

ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = Initialize(&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("C:\\Temp\\vplc.dll");
}

Note
Native C++
If you no longer require the interface, delete it.
See DestroyInterface() (Page 82).

Table 7- 290 RegisterCustomInstance() - .NET (C#)
Syntax

Parameters

IInstance RegisterCustomInstance(
string in_VplcDll
);
IInstance RegisterCustomInstance(
string in_VplcDll,
string in_InstanceName
);

•

string in_VplcDll:

The complete path to the DLL of the virtual controller that Siemens.Simatic.Simulation.Runtime.Instance.exe loads at PowerOn.
•

Return values
Exceptions

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 271).

If the function is successful, an interface of a virtual controller; otherwise a Null
pointer.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

ERuntimeErrorCode.InterfaceRemoved
ERuntimeErrorCode.Timeout

Condition

The interface is disconnected from the
remote Runtime Manager.
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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

251

User interfaces (API)
7.7 API IRemoteRuntimeManager

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 7- 291 CreateInterface() - Native C++
Syntax

Parameters

ERuntimeErrorCode CreateInterface(
WCHAR* in_InstanceName,
IInstance** out_InstanceInterface
);
ERuntimeErrorCode CreateInterface(
INT32 in_InstanceID,
IInstance** out_InstanceInterface
);

•

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.
•

Return values

IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initialized with NULL. The interface is created within the function.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED
SREC_TIMEOUT

Example C++

The interface is disconnected from the
remote Runtime Manager.
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.

ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = Initialize(&api);
IInstance* psa1 = NULL;
IInstance* psa2 = NULL;
if (result == SREC_OK)
{
result = api->CreateInterface(0, &psa1);

Example C++

result = api->CreateInterface(0, &psa2); // psa2 will be the same as
psa1
}
ISimulationRuntimeManager * api = NULL;
ERuntimeErrorCode result = Initialize(&api);
IInstance* psa = NULL;
if (result == SREC_OK)
{
result = api->CreateInterface(L"My SimulationRuntime Instance",
&psa);
}

S7-PLCSIM Advanced

252

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.7 API IRemoteRuntimeManager

Note
Native C++
If you no longer require the interface, delete it.
See DestroyInterface() (Page 82)

Table 7- 292 CreateInterface() - .NET (C#)
Syntax

Parameters

IInstance CreateInterface(
string in_InstanceName
);
IInstance CreateInterface(
INT32 in_InstanceID
);

•

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
Exceptions

If the function is successful, an interface of a virtual controller; otherwise a Null
pointer.
Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeErrorCode.InterfaceRemoved

The interface is disconnected from the
remote Runtime Manager.

ERuntimeErrorCode.Timeout
ERuntimeErrorCode.WrongArgument
ERuntimeErrorCode.DoesNotExists

The function does not return on time.
The name or the ID is invalid.
The instance is not registered in Runtime
Manager.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

253

User interfaces (API)
7.7 API IRemoteRuntimeManager

7.7.3

Events

7.7.3.1

OnConnectionLost

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 7- 293 OnConnectionLost - .NET (C#)
Syntax

event Delegate_IRRTM OnConnectionLost;

Parameters

None. See Delegate_IRRTM (Page 269)

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. Only one callback function
can be registered for the event. Registering a new callback function causes the previous
callback function to be unregistered.
Table 7- 294 RegisterOnConnectionLostCallback() - Native C++
Syntax
Parameters

void RegisterOnConnectionLostCallback(
EventCallback_IRRTM in_CallbackFunction
);

•

EventCallback_IRRTM in_CallbackFunction:

A callback function that subscribes to an event. See EventCallback_IRRTM
(Page 263).
Return values

None

Note

The callback function runs in a separate thread.

S7-PLCSIM Advanced

254

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.7 API IRemoteRuntimeManager

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 7- 295 RegisterOnConnectionLostEvent() - Native C++
Syntax
Parameters

void RegisterOnConnectionLostEvent();
void RegisterOnConnectionLostEvent(
HANDLE* in_Event
);

•

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 7- 296 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 7- 297 UnregisterOnConnectionLostCallback() - Native C++
Syntax

void UnregisterOnConnectionLostCallback();

Parameters

None

Return values

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

255

User interfaces (API)
7.7 API IRemoteRuntimeManager

UnregisterOnConnectionLostEvent()
Unregisters the event object.
Table 7- 298 UnregisterOnConnectionLostEvent() - Native C++
Syntax

void UnregisterOnConnectionLostEvent();

Parameters

None

Return values

None

Table 7- 299 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 7- 300 WaitForOnConnectionLostEvent() - Native C++
Syntax
Parameters

bool WaitForOnConnectionLostEvent();
bool WaitForOnConnectionLostEvent(
UINT32 in_Time_ms )
;

•

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 7- 301 WaitForOnConnectionLostEvent() - .NET (C#)
Syntax
Parameters

bool WaitForOnConnectionLostEvent();
bool WaitForOnConnectionLostEvent(
UInt32 in_Time_ms )
;

•

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

256

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8

Data types
Note
Unsupported data types
The Runtime API does not support the STRING and WSTRING data types.

Supported data types
In S7-PLCSIM Advanced V1.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 BDC-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 backconversion 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
STEP 7 V14 System Manual
(https://support.industry.siemens.com/cs/document/109011420/step-7-professional-v131?dti=0&lc=en-WW // XmlEditor.InternalXmlClipboard:d59d29c4-ec28-6b28-3f63754735fb2e2a).

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

257

User interfaces (API)
7.8 Data types

7.8.1

DLL import functions (Native C++)

7.8.1.1

ApiEntry_Initialize

Description
Type of the central entry point for the API DLL.
Table 7- 302 ApiEntry_Initialize - Native C++
Syntax
Parameters

typedef ERuntimeErrorCode(*ApiEntry_Initialize)(
ISimulationRuntimeManager** out_RuntimeManagerInterface
);

•

ISimulationRuntimeManager**
out_SimulationRuntimeManagerInterface:

Pointer to a Runtime Manager interface pointer. The pointer must be initialized with ZERO. The interface is created within the function.
•

UINT32 in_InterfaceVersion:

Version of the API interface to be downloaded:

Return values

API_DLL_INTERFACE_VERSION.

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT
SREC_WRONG_VERSION

SREC_CONNECTION_ERROR

7.8.1.2

The pointer to the Runtime Manager
interface is ZERO.
The version of the interface in use
does not match the version of the API
DLL.
Unable to establish a connection to the
Runtime Manager.

ApiEntry_DestroyInterface

Description
Type of the entry point for DestroyInterface (Page 82).
Table 7- 303 ApiEntry_DestroyInterface - Native C++
Syntax
Parameters

typedef ERuntimeErrorCode(*ApiEntry_DestroyInterface)(
IBaseInterface* in_Interface
);

•

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 ZERO.

S7-PLCSIM Advanced

258

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.2

Event callback functions (Native C++)

7.8.2.1

EventCallback_VOID

Description
Table 7- 304 EventCallback_VOID - Native C++
Syntax

7.8.2.2

typedef void (*EventCallback_VOID)();

Parameters

None

Return values

None

EventCallback_II_SREC_ST

Description
Table 7- 305 EventCallback_II_SREC_ST - Native C++
Syntax

Parameters

typedef void (*EventCallback_II_SREC_ST)(
IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode,
SYSTEMTIME in_SystemTime
);

•

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

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

259

User interfaces (API)
7.8 Data types

7.8.2.3

EventCallback_II_SREC_ST_SROS_SROS

Description
Table 7- 306 EventCallback_II_SREC_ST_SROS_SROS - Native C++
Syntax

Parameters

typedef void (*EventCallback_II_SREC_ST_SROS_SROS)(
IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode,
SYSTEMTIME in_SystemTime,
EOperatingState in_PrevState,
EOperatingState in_OperatingState
);

•

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

Error codes

Runntime error code

Condition

SREC_OK

The function is successful.

SREC_WARNING_TRIAL_MODE_ACTIVE

SREC_LICENSE_NOT_FOUND
SREC_COMMUNICATION_INTERFACE_NOT
_AVAILABLE

No license available. You can use the
instance without restrictions for a period of one hour. Afterwards, the instance is shut down.
Test mode has expired.
A problem has occurred with the selected communication interface. Check
your settings.

S7-PLCSIM Advanced

260

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.2.4

EventCallback_II_SREC_ST_SRLT_SRLM

Description
Table 7- 307 EventCallback_II_SREC_ST_SRLT_SRLM - Native C++
Syntax

Parameters

typedef void (*EventCallback_II_SREC_ST_SRLT_SRLM)(
IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode,
SYSTEMTIME in_SystemTime,
ELEDType in_LEDType,
ELEDMode in_LEDMode,
);

•

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

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

261

User interfaces (API)
7.8 Data types

7.8.2.5

EventCallback_II_SREC_ST_INT64_UINT32

Description
Table 7- 308 EventCallback_II_SREC_ST_INT64_UINT32 - Native C++
Syntax

Parameters

typedef void (*EventCallback_II_SREC_ST_INT64_UINT32)(
IInstance* in_Sender,
ERuntimeErrorCode in_ErrorCode,
SYSTEMTIME in_SystemTime,
INT64 in_CycleTime_ns,
UINT32 in_CycleCount,
);

•

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.
•

INT64 in_CycleTime_ns:

The virtual time (in nanoseconds) since the last cycle control point. If the
events are triggered faster than they are received, multiple events are combined into one event. In this case, the value contains the virtual time (in nanoseconds) since the last event was received.
•

UINT32 in_CycleCount:

The number of cycles since the last cycle control point. 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

262

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.2.6

EventCallback_IRRTM

Description
Table 7- 309 EventCallback_IRRTM - Native C++
Syntax

typedef void (*EventCallback_IRRTM)(
IRemoteRuntimeManager* in_Sender
);

Parameters

•

Return values

None

IRemoteRuntimeManager* in_Sender:

An interface of the remote Runtime Manager that receives this event.

7.8.2.7

EventCallback_SRCC_UINT32_UINT32_INT32

Description
Table 7- 310 EventCallback_SRCC_UINT32_UINT32_INT32 - Native C++
Syntax

Parameters

ERuntimeConfigChanged in_RuntimeConfigChanged,
UINT32 in_Param1,
UINT32 in_Param2,
INT32 in_Param3
);
ERuntimeConUInt32
UInt32
figChanged
in_Param1
in_Param2
in_RuntimeConfi
gChanged
SRCC_INSTANCE_R EGISTERED

Int32 in_Param3

SRCC_INSTANCE_U
NREGISTERED

-

-

SRCC_CONNECTION
_OPENED

ID of the unregistered instance

IP of the remote
Runtime Manager

Port of the remote
Runtime Manager

IP of the remote
Runtime Manager

Port of the remote
Runtime Manager

-

The open port

-

-

-

-

-

SRCC_CONNECTION
_CLOSED

Return values

SRCC_PORT_OPENE
D
SRCC_PORT_CLOSE
D

ID of the registered instance

-

None

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

263

User interfaces (API)
7.8 Data types

7.8.2.8

EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32

Description
Table 7- 311 EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32 - Native C++
Syntax

Parameters

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
);

•

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.

EInstanceConfigChanged
in_Instance
ConfigChanged
SRICC_HARDW
ARE_SOFTWAR
E CHANGED
SRICC_IP_CH
ANGED

Return values

UINT32
in_Param1

UINT32
in_Param2

UINT32
in_Param3

UINT32
in_Param4

-

-

-

-

The ID of the
interface

The new IP

The new subnet mask

The new
standard
gateway

None

S7-PLCSIM Advanced

264

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.3

Delegate definitions (managed code)

7.8.3.1

Delegate_Void

Description
Table 7- 312 Delegate_Void - .NET (C#)
Syntax

7.8.3.2

delegate void Delegate_Void();

Parameters

None

Return values

None

Delegate_II_EREC_DT

Description
Table 7- 313 Delegate_II_EREC_DT - .NET (C#)
Syntax

Parameters

delegate void Delegate_II_EREC_DT (
IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode,
DateTime in_DateTime
);

•

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

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

265

User interfaces (API)
7.8 Data types

7.8.3.3

Delegate_II_EREC_DT_EOS_EOS

Description
Table 7- 314 Delegate_II_EREC_DT_EOS_EOS - .NET (C#)
Syntax

Parameters

delegate void Delegate_II_EREC_DT_EOS_EOS(
IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode,
DateTime in_DateTime,
EOperatingState in_PrevState,
EOperatingState in_OperatingState
);

•

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

Runntime error code
ERuntimeErrorCode.OK
ERuntimeErrorCode.WarningTrialModeActive

ERuntimeErrorCode.LicenseNotFound
ERuntimeErrorCode.CommunicationInterfaceNotAv
ailable

Condition
The function is successful.
No license available. You can use the
instance without restrictions for a period of one hour. Afterwards, the instance is shut down.
Test mode has expired.
A problem has occurred with the selected communication interface. Check
your settings.

S7-PLCSIM Advanced

266

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.3.4

Delegate_II_EREC_DT_ELT_ELM

Description
Table 7- 315 Delegate_II_EREC_DT_ELT_ELM - .NET (C#)
Syntax

Parameters

delegate void Delegate_II_EREC_DT_ELT_ELM(
IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode,
DateTime in_DateTime,
ELEDType in_LEDType,
ELEDMode in_LEDMode,
);

•

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
Function Manual, 09/2016, A5E37039512-AA

267

User interfaces (API)
7.8 Data types

7.8.3.5

Delegate_II_EREC_DT_INT64_UINT32

Description
Table 7- 316 Delegate_II_EREC_DT_INT64_UINT32 - .NET (C#)
Syntax

Parameters

delegate void Delegate_II_EREC_DT_INT64_UINT32(
IInstance in_Sender,
ERuntimeErrorCode in_ErrorCode,
DateTime in_DateTime,
Int64 in_CycleTime_ns,
UInt32 in_CycleCount,
);

•

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.
•

Int64 in_CycleTime_ns:

The virtual time (in nanoseconds) since the last cycle control point. If the
events are triggered faster than they are received, multiple events are combined into one event. In this case, the value contains the virtual time (in nanoseconds) since the last event was received.
•

UInt32 in_CycleCount:

The number of cycles since the last cycle control point. 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

268

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.3.6

Delegate_IRRTM

Description
Table 7- 317 Delegate_IRRTM - .NET (C#)
Syntax
Parameters

delegate void Delegate_IRRTM(
IRemoteRuntimeManager in_Sender,
);

•

IRemoteRuntimeManager in_Sender:

An interface of the remote Runtime Manager that receives this event.
Return values

7.8.3.7

None

Delegate_SRCC_UINT32_UINT32_INT32

Description
Table 7- 318 Delegate_SRCC_UINT32_UINT32_INT32 - .NET (C#)
Syntax

Parameters

delegate void Delegate_SRCC_UINT32_UINT32_INT32(
ERuntimeConfigChanged in_RuntimeConfigChanged,
UInt32 in_Param1,
UInt32 in_Param2,
Int32 in_Param3
);
ERuntimeConUInt32
UInt32
figChanged
in_Param1
in_Param2
in_RuntimeConfi
gChanged
InstanceRegistered

ID of the registered instance

InstanceUnregistered

-

-

ConnectionOpened

IP of the Remote
Runtime Manager

Port of the remote
Runtime Manager

IP of the Remote
Runtime Manager

Port of the remote
Runtime Manager

-

The open port

-

-

-

-

-

ConnectionClosed
PortOpened

Return values

Int32 in_Param3

PortClosed

None

ID of the unregistered instance
-

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

269

User interfaces (API)
7.8 Data types

7.8.3.8

Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32

Description
Table 7- 319 Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32 - .NET (C#)
Syntax

Parameters

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
);

•

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.

EInstanceConfigChanged
in_Instance
ConfigChanged
HardwareSoftwareChanged
IPChanged

Return values

UInt32
in_Param1

UInt32
in_Param2

UInt32
in_Param3

UInt32
in_Param4

-

-

-

-

The ID of the
interface

The new IP

The new subnet mask

The new
standard
gateway

None

S7-PLCSIM Advanced

270

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.4

Definitions and constants
The following identifiers are used in the API:
Table 7- 320 Definitions and constants - Native C++
Identifier

DINSTANCE_NAME_MAX_LENGTH

Value

Description

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. Including ZERO termination.

DTAG_NAME_MAX_LENGTH

300

The maximum length of the name of a PLC tag.
Including ZERO termination.

DTAG_ARRAY_DIMENSION

6

The maximum number of dimension for a multidimensional field.

128

The maximum length of the controller name. Including ZERO termination.

32

The maximum length of the abbreviation of the
controller (CPU type). Including ZERO termination.

DCONTROLLER_NAME_MAX_LENGTH
DCONTROLLER_SHORT_DESIGNATION_MA
X_LENGTH

Table 7- 321 Definitions and constants - .NET (C#)
Identifier

RuntimeConstants.InstanceNameLength

Value

Description

64

The unique name of an instance must be less than
this value.

RuntimeConstants.StoragePathMaxLength

130

The maximum path length to the virtual memory
card. Including ZERO termination.

RuntimeConstants.TagNameMaxLength

300

The maximum length of the name of a PLC tag.
Including ZERO termination.

RuntimeConstants.TagArrayDimension

6

The maximum number of dimension for a multidimensional field.

128

The maximum length of the controller name. Including ZERO termination.

32

The maximum length of the abbreviation of the
controller (CPU type). Including ZERO termination.

RuntimeConstants.ControllerNameMaxLength
RuntimeConstants.ControllerShortDesignatio
nMaxLength

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

271

User interfaces (API)
7.8 Data types

7.8.5

Unions (Native C++)

7.8.5.1

UIP

Description
Contains an IPv4 address.
Table 7- 322 UIP - Native C++
Syntax

Member

union UIP
{
DWORD IP;
BYTE IPs[4];
};

•

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

7.8.5.2

UDataValue

Description
Contains the value of a PLC tag.
Table 7- 323 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;
};

S7-PLCSIM Advanced

272

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types
Member

•

bool Bool:

1 byte boolean value
•

INT8 Int8:

1 byte integer with sign
•

INT16 Int16:

•

INT32 Int32:

2 byte integer with sign
4 byte integer with sign
•

INT64 Int64:

8 byte integer with sign
•

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

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

273

User interfaces (API)
7.8 Data types

7.8.6

Structures

7.8.6.1

SDataValue

Description
The structure contains the value and type of a PLC tag.
Table 7- 324 SDataValue - Native C++
Syntax

Member

struct SDataValue
{
UDataValue Value;
EDataType Type;
};

•

UDataValue Value:

The value of the PLC tags
•

EPrimitiveDataType Type:

Type of PLC tag

Table 7- 325 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; }
}

S7-PLCSIM Advanced

274

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types
Member

•

bool Bool:

•

Int8 Int8:

•

Int16 Int16:

•

Int32 Int32:

•

Int64 Int64:

•

UntT8 UInt8:

•

UInt16 UInt16:

1 byte boolean value
1 byte integer with sign

2 byte integer with sign
4 byte integer with sign
8 byte integer with sign
1 byte integer without sign

2 byte integer without sign
•

UInt32 UInt32:

4 byte integer without sign
•

UInt64 UInt64:

8 byte integer without sign
•

float Float:

•

double Double:

4 byte floating-point value

8 byte floating-point value
•

sbyte Char:

1 byte value character
•

char WChar:

2 byte value character
•

EPrimitiveDataType Type:

Type of PLC tag

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

275

User interfaces (API)
7.8 Data types

7.8.6.2

SDataValueByAddress

Description
This structure represents a PLC tag that can be accessed via its address.
Table 7- 326 SDataValueByAddress - Native C++
Syntax

struct SDataValueByAddress
{
UINT32 Offset;
UINT8 Bit;
SDataValue DataValue;
};

Table 7- 327 SDataValueByAddress - .NET (C#)
Syntax

7.8.6.3

struct SDataValueByAddress
{
UInt32 Offset;
UInt8 Bit;
SDataValue DataValue;
}

SDataValueByName

Description
This structure represents a PLC tag that can be called by name.
Table 7- 328 SDataValueByName - Native C++
Syntax

struct SDataValueByName
{
WCHAR Name[DTAG_NAME_MAX_LENGTH];
SDataValue DataValue;
};

Table 7- 329 SDataValueByName - .NET (C#)
Syntax

struct SDataValueByName
{
String Name;
SDataValue DataValue;
}

S7-PLCSIM Advanced

276

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.6.4

SConnectionInfo

Description
This structure contains the IP address and port of a TCP/IP connection.
Table 7- 330 SConnectionInfo - Native C++
Syntax

struct SConnectionInfo
{
UIP IP;
WORD Port;
};

Table 7- 331 SConnectionInfo - .NET (C#)
Syntax

struct SConnectionInfo
{
SIP IP;
UInt16 Port;
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

277

User interfaces (API)
7.8 Data types

7.8.6.5

SInstanceInfo

Description
This structure contains an IPv4 address.
Table 7- 332 SInstanceInfo - Native C++
Syntax

Member

struct SInstanceInfo
{
INT32 ID;
WCHAR Name[DINSTANCE_NAME_MAX_LENGTH];
};

•

INT32 ID:

The ID of the instance
•

WCHAR Name[DINSTANCE_NAME_MAX_LENGTH]:

The name of the instance

Table 7- 333 SInstanceInfo - .NET (C#)
Syntax

Member

struct SInstanceInfo
{
Int32 ID;
String Name;
}

•

Int32 ID:

The ID of the instance
•

String name:

The name of the instance

S7-PLCSIM Advanced

278

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.6.6

SDimension

Description
This structure contains information about the dimension of a field.
Table 7- 334 SDimension - Native C++
Syntax

struct SDimension
{
INT32 StartIndex;
UINT32 Count;
};

Table 7- 335 SDimension - .NET (C#)
Syntax

struct SDimension
{
Int32 StartIndex;
UInt32 Count;
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

279

User interfaces (API)
7.8 Data types

7.8.6.7

STagInfo

Description
This structure contains information about a PLC tag.
Table 7- 336 STagInfo - Native C++
Syntax

Member

struct STagInfo
{
WCHAR Name[DTAG_NAME_MAX_LENGTH];
EArea Area;
EDataType DataType;
PrimitiveDataType PrimitiveDataType;
UINT16 Size;
UINT32 Offset;
UINT8 Bit;
UINT8 DimensionCount;
UINT32 Index;
UINT32 ParentIndex;
SDimension Dimension[DTAG_ARRAY_DIMENSION];
};

•

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 it is not a field for the tag.
•

UINT32 index:

•

UINT32 ParentIndex:

The index of the tag
If this tag is embedded in another tag (for example, an element of a structure),
this value then displays 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

S7-PLCSIM Advanced

280

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

Table 7- 337 STagInfo - .NET (C#)
Syntax

Member

public struct STagInfo
{
String Name;
EArea Area;
EDataType DataType;
EPrimitiveDataType PrimitiveDataType;
UInt16 Size;
UInt32 Offset;
UInt8 Bit;
UInt32 Index;
UInt32 ParentIndex;
SDimension[] Dimension;
}

•

String name:

•

EArea area:

The name of the tag
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:

•

UInt32 offset:

The size of the tag in bytes.
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 displays 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.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

281

User interfaces (API)
7.8 Data types

7.8.6.8

SIP

Description
This structure contains an IPv4 address.
Table 7- 338 SIP - .NET (C#)
Syntax

Member

struct SIP
{
byte[] IPArray { get; set; }
UInt32 IPDWord { get; set; }
string IPString { get; set; }
}

•

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

282

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.6.9

SIPSuite4

Description
This structure contains an IPv4 suite.
Table 7- 339 SIPSuite4 - Native C++
Syntax

Member

struct SIPSuite4
{
UIP IPAddress;
UIP SubnetMask;
UIP DefaultGateway;
};

•

UIP IPAddress:

The IP address
•

UIP SubnetMask:

The subnet mask
•

UIP DefaultGateway:

The standard gateway

Table 7- 340 SIPSuite4 - .NET (C#)
Syntax

Member

struct SIPSuite4
{
SIP IPAddress;
SIP SubnetMask;
SIP DefaultGateway;
}

•

SIP IPAddress:

The IP address
•

SIP SubnetMask:

The subnet mask
•

SIP DefaultGateway:

The standard gateway

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

283

User interfaces (API)
7.8 Data types

7.8.7

Enumerations

7.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. Errors are returned with negative values, and alarms with positive values.
Table 7- 341 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,
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
};

S7-PLCSIM Advanced

284

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types
Table 7- 342 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,
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,

start StartupPathAlreadyInUse = -35,
MesssageIncomplete = -36,

archive ArchiveStorageNotCreated = -37,

RetrieveStorageFailure = -38,
InvalidOperatingState = -39,
InvalidArchivePath = -40,
DeleteExistingStorageFailed = -41,
CreateDirectoriesFailed = -42,
NotEnoughMemory = -43,
WarningTrialModeActive = 44,
NotRunning = -45,
NotEmpty = -46,
NotUpToData = -47,
CommunicationInterfaceNotAvailable = -48,
WarningNotComplete = 49,
VirtualSwitchMisconfigured = -50
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

285

User interfaces (API)
7.8 Data types

7.8.7.2

EArea

Description
This list contains all PLC areas that contain the available PLC tags.
Table 7- 343 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 7- 344 EArea - .NET (C#)
Syntax

public enum EArea
{
InvalidArea = 0,
Input = 1,
Marker = 2,
Output = 3,
Counter = 4,
Timer = 5,
DataBlock = 6,
}

S7-PLCSIM Advanced

286

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.7.3

EOperatingState

Description
This list contains all the operating states of a virtual controller.
Table 7- 345 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_ENUMERATION_SIZE = 8
};

Table 7- 346 EOperatingState - .NET (C#)
Syntax

enum EOperatingState
{
InvalidOperatingState = 0,
Off = 1,
Booting = 2,
Stop = 3,
Startup = 4,
Run = 5,
Freeze = 6,
ShuttingDown = 7
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

287

User interfaces (API)
7.8 Data types

7.8.7.4

EOperatingMode

Description
This list contains all the operating modes of a virtual controller.
Table 7- 347 EOperatingMode - Native C++
Syntax

enum EOperatingMode
{
SROM_DEFAULT = 0,
SROM_SINGLE_STEP = 1,
SROM_EXTENDED_SINGLE_STEP = 2,
SROM_TIMESPAN_SYNCHNRONIZED = 3
};

Table 7- 348 EOperatingMode - .NET (C#)
Syntax

enum EOperatingMode
{
Default = 0,
SingleStep = 1,
ExtendedSingleStep = 2,
TimespanSynchronized = 3
}

S7-PLCSIM Advanced

288

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.7.5

ECPUType

Description
This list contains all CPU types that can be loaded in a virtual controller.
Table 7- 349 ECPUType - Native C++
Syntax

enum ECPUType
{
SRCT_1500_Unspecified = 0x000005DC,
SRCT_1511 = 0x000005E7,
SRCT_1511v2 = 0x010005E7,
SRCT_1513 = 0x000005E9,
SRCT_1513v2 = 0x010005E9,
SRCT_1515 = 0x000005EB,
SRCT_1515v2 = 0x010005EB,
SRCT_1516 = 0x000005EC,
SRCT_1516v2 = 0x010005EC,
SRCT_1517 = 0x000005ED,
SRCT_1518 = 0x000005EE,
SRCT_1511C = 0x000405E7,
SRCT_1512C = 0x000405E8,
SRCT_1511F = 0x000105E7,
SRCT_1511Fv2 = 0x010105E7,
SRCT_1513F = 0x000105E9,
SRCT_1513Fv2 = 0x010105E9,
SRCT_1515F = 0x000105EB,
SRCT_1515Fv2 = 0x010105EB,
SRCT_1516F = 0x000105EC,
SRCT_1516Fv2 = 0x010105EC,
SRCT_1517F = 0x000105ED,
SRCT_1518F = 0x000105EE,
SRCT_1511T = 0x000805E7,
SRCT_1515T = 0x000805EB,
SRCT_1517T = 0x000805ED,
SRCT_1517TF = 0x000905ED,
SRCT_1518ODK = 0x001005EE,
SRCT_1518FODK = 0x001105EE,
SRCT_ET200SP_Unspecified = 0x000205DC,
SRCT_1510SP = 0x000205E6,
SRCT_1510SPv2 = 0x010205E6,
SRCT_1512SP = 0x000205E8,
SRCT_1512SPv2 = 0x010205E8,
SRCT_1510SPF = 0x000305E6,
SRCT_1510SPFv2 = 0x010305E6,
SRCT_1512SPF = 0x000305E8,
SRCT_1512SPFv2 = 0x010305E8
};

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

289

User interfaces (API)
7.8 Data types
Table 7- 350 ECPUType - .NET (C#)
Syntax

enum ECPUType
{
CPU1500_Unspecified = 0x000005DC,
CPU1511 = 0x000005E7,
CPU1511v2 = 0x010005E7,
CPU1513 = 0x000005E9,
CPU1513v2 = 0x010005E9,
CPU1515 = 0x000005EB,
CPU1515v2 = 0x010005EB,
CPU1516 = 0x000005EC,
CPU1516v2 = 0x010005EC,
CPU1517 = 0x000005ED,
CPU1518 = 0x000005EE,
CPU1511C = 0x000405E7,
CPU1512C = 0x000405E8,
CPU1511F = 0x000105E7,
CPU1511Fv2 = 0x010105E7,
CPU1513F = 0x000105E9,
CPU1513Fv2 = 0x010105E9,
CPU1515F = 0x000105EB,
CPU1515Fv2 = 0x010105EB,
CPU1516F = 0x000105EC,
CPU1516Fv2 = 0x010105EC,
CPU1517F = 0x000105ED,
CPU1518F = 0x000105EE,
CPU1511T = 0x000805E7,
CPU1515T = 0x000805EB,
CPU1517T = 0x000805ED,
CPU1517TF = 0x000905ED,
CPU1518ODK = 0x001005EE,
CPU1518FODK = 0x001105EE,
CPUET200SP_Unspecified = 0x000205DC,
CPU1510SP = 0x000205E6,
CPU1510SPv2 = 0x010205E6,
CPU1512SP = 0x000205E8,
CPU1512SPv2 = 0x010205E8,
CPU1510SPF = 0x000305E6,
CPU1510SPFv2 = 0x010305E6,
CPU1512SPF = 0x000305E8,
CPU1512SPFv2 = 0x010305E8
}

S7-PLCSIM Advanced

290

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.7.6

ECommunicationInterface

Description
This list shows the available communication interfaces of a virtual controller.
Table 7- 351 ECommunicationInterface - Native C++
Syntax

enum ECommunicationInterface
{
SRCI_NONE = 0,
SRCI_SOFTBUS = 1,
SRCI_TCPIP = 2,
SRCI_ENUMERATION_SIZE = 3
};

Table 7- 352 ECommunicationInterface - .NET (C#)
Syntax

enum ECommunicationInterface
{
None = 0,
Softbus = 1,
TCPIP = 2,
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

291

User interfaces (API)
7.8 Data types

7.8.7.7

ELEDType

Description
This list includes all types of LEDs of a virtual controller.
Table 7- 353 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 7- 354 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
}

S7-PLCSIM Advanced

292

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.7.8

ELEDMode

Description
This list contains all the LED states of a virtual controller.
Table 7- 355 ELEDMode - Native C++
Syntax

enum ELEDMode
{
SRLM_OFF = 0,
SRLM_ON = 1,
SRLM_FLASH_FAST = 2,
SRLM_FLASH_SLOW = 3,
SRLM_INVALID = 4
};

Table 7- 356 ELEDMode - .NET (C#)
Syntax

enum ELEDMode
{
Off = 0,
On = 1,
FlashFast = 2,
FlashSlow = 3,
Invalid = 4
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

293

User interfaces (API)
7.8 Data types

7.8.7.9

EPrimitiveDataType

Description
This list contains all the primitive data types that are used by the I/O access functions.
Table 7- 357 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 7- 358 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

294

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.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 data
types that can be used as compatible are marked with "X".
Table 7- 359 Compatible primitive data types - Reading
API

PLCSIM Advanced instance
Bool

Bool

INT8

INT16

INT32

INT64

UINT8

UINT16

UINT32

UINT6
4

Float

Double

Char WChar

X

INT8

X

INT16

X

X

INT32

X

X

X

INT64

X

X

X

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 7- 360 Compatible primitive data types - Write
API

PLCSIM Advanced instance
Bool

Bool

INT8

INT16

INT32

INT64

X

X

X

X

X

X

X

X

X

UINT8

UINT16

UINT32

UINT6
4

X

X

X

X

X

X

X

X

X

Float

Double

Char WChar

X

INT8
INT16
INT32
INT64
UINT8

X
X

X

UINT16
UINT32
UINT64
Float
Double
Char
WChar

X

X
X
X
X
X

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

295

User interfaces (API)
7.8 Data types

7.8.7.10

EDataType

Description
This list contains all the CPU data types (STEP 7).

S7-PLCSIM Advanced

296

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types
Table 7- 361 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,
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
};

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

297

User interfaces (API)
7.8 Data types
Table 7- 362 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,
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
}

S7-PLCSIM Advanced

298

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

7.8.7.11

ETagListDetails

Description
This list contains all PLC areas that can be used as a filter to update the tag table.
Table 7- 363 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,
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 7- 364 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
}

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

299

User interfaces (API)
7.8 Data types

7.8.7.12

ERuntimeConfigChanged

Description
This list contains all possible causes of a OnConfigurationChanged event that the Runtime
Manager sends.
Table 7- 365 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 7- 366 ERuntimeConfigChanged - .NET (C#)
Syntax

enum ERuntimeConfigChanged

{

InstanceRegistered = 0,
InstanceUnregistered = 1,
ConnectionOpened = 2,
ConnectionClosed = 3,
PortOpened = 4,
PortClosed = 5
}

7.8.7.13

EInstanceConfigChanged

Description
This list contains all possible causes for a OnConfigurationChanged event that the virtual
controller sends.
Table 7- 367 EInstanceConfigChanged - Native C++
Syntax

enum EInstanceConfigChanged
{
SRICC_HARDWARE_SOFTWARE_CHANGED = 0,
SRICC_IP_CHANGED = 1
};

Table 7- 368 EInstanceConfigChanged - .NET (C#)
Syntax

enum EInstanceConfigChanged
{
HardwareSoftwareChanged = 0,
IPChanged = 1
}

S7-PLCSIM Advanced

300

Function Manual, 09/2016, A5E37039512-AA

User interfaces (API)
7.8 Data types

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

301

8

Restrictions
8.1

Overview
Certain actions or events may lead to behavior in S7-PLCSIM Advanced or in STEP 7 which
deviates from that of a hardware CPU. Restrictions and possible remedies can be found in
the following sections:
● OPC UA server (Page 302)
● Web server (Page 304)
● Restrictions for communications services (Page 305)
● Restrictions for instructions (Page 306)
● Restrictions with Motion Control (Page 307)
● Restrictions to local communication via Softbus (Page 308)
● Error with overflow cyclical events (Page 309)
● Deviating I/O values in the STEP 7 user program (Page 310)
● Multiple simulations and possible collision of IP addresses (Page 310)
● Simulation in standby mode (Page 310)
● Error installing the antivirus software from Kaspersky (Page 311)

8.2

OPC UA server
With OPC UA, data exchange is performed through an open, standardized and
manufacturer-independent communication protocol. The CPU acting as the OPC UA server
can communicate with OPC UA clients, for example, with HMI panels V14 and SCADA
systems.
For technical reasons, the security settings in PLCSIM Advanced differ from a hardware
CPU. Some features are disabled for simulations or are available to a limited extent.

Configuring 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.

S7-PLCSIM Advanced

302

Function Manual, 09/2016, A5E37039512-AA

Restrictions
8.2 OPC UA server

OPC UA security settings
Based on the OPC UA security settings, the same settings can be made in STEP 7 for the
hardware CPU. The data is not further processed by PLCSIM Advanced. This ensures that
the user does not have his project change to perform a simulation.

Certificate
● Server certificate
PLCSIM Advanced uses its own certificate in the firmware and not that of STEP 7. The
certificate need not be changed for simulations. However, it does not have the same
security level as a downloaded server certificate and cannot be used for secure
connections!
● Server Security Endpoints
PLCSIM Advanced only supports Security Endpoint "none".
● Client certificate
PLCSIM Advanced does not evaluate certificates the imported and configured in STEP 7
. PLCSIM Advanced accepts all client certificates automatically. This setting cannot be
changed.
● User authentication
PLCSIM Advanced does not use the user name configured in STEP 7.
Only one logon is possible as "guest" or "anonymous".

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

303

Restrictions
8.3 Web server

8.3

Web server
The Web server integrated in a CPU enables monitoring and administering of the CPU by
authorized users over a network. This permits evaluation and diagnostics over long
distances.
The simulation of the Web server is restricted under S7-PLCSIM V1.0 Advanced.
Each PLCSIM Advanced instance can simulate its own Web server.
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
● Logon
"PLCSIM" is preset as the user. There is no logon for users.
A user configured in STEP 7 and his rights have no effect on the "PLCSIM" user.
● There is no access via the secure transmission protocol "HTTPS".
● The information may not be fully displayed on some websites due to different data
handling.
● There is no topology information.
● "Online Backup&Restore" is not available.
● FW updates are not supported.

S7-PLCSIM Advanced

304

Function Manual, 09/2016, A5E37039512-AA

Restrictions
8.4 Restrictions for communications services

8.4

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.
Remedy
Set "PLCSIM Virtual Ethernet Adapter" (TCP/IP) as the communication interface in PLCSIM
Advanced.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

305

Restrictions
8.5 Restrictions for instructions

8.5

Restrictions for instructions
S7-PLCSIM Advanced simulates instructions for CPUs S7-1500 and ET 200SP with a few
exceptions, such as interrupts.
Some instructions are partially supported. For these, S7-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 handled as not ready by S7-PLCSIM Advanced, their value is
always "OK".
S7PLCSIM Advanced does not support the following instructions:
Table 8- 1

Instructions not supported

Instruction

Description

DIS_AIRT

Delay interrupts with higher priority and asynchronous errors

EN_AIRT

Activate interrupts with higher priority and asynchronous errors

DIS_IRT

Call new interrupts and disable asynchronous error

RE_TRIGR

Start time monitoring

WR_DPARM

Transfer data record

GETIO

Read process image

SETIO

Transfer process image

GETIO_PART

Read a part of the outputs of a DP standard slave / PROFINET IO device

SETIO_PART

Write a part of the outputs of a DP standard slave / PROFINET IO device

DPRD_DAT

Read consistent data of a standard DP slave

DPWR_DAT

Write consistent data to a standard DP slave

RD_OBINF

Read OB start information

DP_TOPOL

DP bus topology

PORT_CFG

Safety function

ATTACH

Assigning a hardware interrupt to an OB

DETACH

Removing the mapping between hardware interrupt and OB

S7-PLCSIM Advanced

306

Function Manual, 09/2016, A5E37039512-AA

Restrictions
8.6 Restrictions with Motion Control

8.6

Restrictions with Motion Control

8.6.1

Motion Control resources
There are motion control resources on each CPU that can be distributed to the technology
objects.
Note
Maximum 5120 Motion Control resources
PLCSIM Advanced supports a maximum of 5120 motion control resources. The simulation of
motion control is therefore restricted for the following CPUs:

Table 8- 2

CPUs with limited Motion Control resources

Type
Standard CPUs

Fail-safe CPUs

Article number
CPU 1517-3 PN/DP

6ES7517-3AP00-0AB0

CPU 1518-4 PN/DP

6ES7518-4AP00-0AB0

CPU 1518-4 PN/DP ODK1

6ES7518-4AP00-3AB0

CPU 1517F-3 PN/DP

6ES7517-3FP00-0AB0

CPU 1518F-4 PN/DP
CPU 1518F-4 PN/DP
Technology CPUs

CPU 1517T-3

6ES7518-4FP00-0AB0
ODK1

PN/DP2

CPU 1517TF-3 PN/DP2
1

The ODK functionality of this CPU is not simulated.

2

The simulation of this CPU supports only 64 cams.

6ES7518-4FP00-3AB0
6ES7517-3TP00-0AB0
6ES7517-3UP00-0AB0

Exceeding the quantity structure
STEP 7 checks whether the quantity structure for a configured CPU is complied with, and
alerts you when it is exceeded. When you load a project into a CPU, another message
appears.
Note
A project that uses more than 5120 motion control resources can be downloaded to a virtual
controller. However, there is no message indicating that the quantity structure has been
exceeded.
Only when the user program accesses the technology objects do you recognize by the error
message at the block and the value 0 of the object that motion control objects cannot be
used due to an overrun of the quantity structure.

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

307

Restrictions
8.7 Restrictions to local communication via Softbus

8.6.2

Technology modules
PLCSIM Advanced simulates the real CPU, but not configured, connected technology
modules or other I/O devices.
It is possible to download a project with technology modules for operation of motion control.
However, the built-in logic of the technology modules is not part of the simulation, which is
why the associated Motion Control instructions are not supported.

Additional information
For more information on Motion Control, refer to the following manuals:
● Device manuals to support SIMATIC controllers (http://w3.siemens.com/mcms/industrialautomation-systems-simatic/en/manual-overview/Pages/Default.aspx)
● Function manual S7-1500 Motion Control
(https://support.industry.siemens.com/cs/ww/en/view/109739589)
● Function manual S7-1500T Motion Control
(https://support.industry.siemens.com/cs/ww/en/view/109481326)

8.7

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, only one instance is therefore displayed in the lifelist.
Remedy
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 122)

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.).

See also
Controller - Information and settings (Page 119)
S7-PLCSIM Advanced

308

Function Manual, 09/2016, A5E37039512-AA

Restrictions
8.8 Restrictions of security with VMware vSphere Hypervisor (ESXi)

8.8

Restrictions of security with VMware vSphere Hypervisor (ESXi)
When you use the virtualization platform VMware vSphere Hypervisor (ESXi), you must
change the policy exception to communicate over TCP/IP.
Remedy
Accept the "Promiscuous mode and "Forged transmit" options for the Virtual Switch of the
ESXi.
NOTICE
Restrictions of security
For security reasons, Promiscuous mode is disabled by default.
If you accept the Promiscuousmode, the real Ethernet adapter even receives telegrams
that are not addressed to it.

Figure 8-1

8.9

Policy exceptions for VMware vSphere Hypervisor (ESXi)

Error with overflow cyclical events
If your simulation contains cyclic interrupts, the queue of PLCSIM Advanced may overflow
for cyclic events. Due to the execution speed of PLCSIM Advanced compared to real
hardware, the time required to create the diagnostics 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.

See also
Speed up and slow down simulation (Page 60)

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

309

Restrictions
8.10 Deviating I/O values in the STEP 7 user program

8.10

Deviating I/O values in the STEP 7 user program
Updated values
Each value change made by a STEP 7 user program in the I/O address areas is overwritten
in the cycle control point with the updated value 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.

See also
Simulate peripheral I/O (Page 53)

8.11

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.

8.12

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 " in the command line editor of Windows.

8.13

Simulation in standby mode
If your computer or programming device goes into standby or hibernation mode, the
simulation may be stopped. In this case, the communication between STEP 7 and
S7-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.
To prevent this situation, disable the standby mode on your computer or programming
device.

S7-PLCSIM Advanced

310

Function Manual, 09/2016, A5E37039512-AA

Restrictions
8.14 Error installing the antivirus software from Kaspersky

8.14

Error installing the antivirus software from Kaspersky
When using the Anti-Virus virus scanner from Kaspersky, network settings may not be
correctly during installation of PLCSIM Advanced. The result is that communication via
TCP/IP cannot be used (error code -50 in the Control Panel).
Remedy
Check your network settings as described in the sectionEnable distributed communication
(Page 43).

S7-PLCSIM Advanced
Function Manual, 09/2016, A5E37039512-AA

311

A

List of abbreviations

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)

ES

Engineering System

HMI

Human Machine Interface user interface

IE

Industrial Ethernet

GUI

Graphical User Interface

LAN

Local Area Network
Computer network that is limited to a local area.

OB

Organization Block

ODK

Open Development Kit

OPC UA

Open Platform Communications Unified Architecture

PG

Programming device

PLC

Programmable Logic Controller

PN

PROFINET

RAM

Random Access Memory

RT

Runtime

TIA

Totally Integrated Automation

UTC

Coordinated Universal Time

VM

Virtual Machine

VPLC

Virtual Programmable Logic Controller

WinCC

Windows Control Center

S7-PLCSIM Advanced

312

Function Manual, 09/2016, A5E37039512-AA
Source Exif Data: 
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.6
Linearized                      : Yes
Author                          : DF FA AS E&C-PRM
Comments                        : 
Company                         : Siemens AG
Create Date                     : 2016:08:11 13:34:03+02:00
Keywords                        : A5E37039512-AA;, 09/2016
Modify Date                     : 2016:08:12 11:07:46+02:00
Source Modified                 : D:20160811113223
Subject                         : Function Manual
Company-long                    : Siemens AG
Company-short                   : Siemens
Document-class                  : Function Manual
Document-class-mrl              : 
Edition                         : 09/2016
Ident-nr                        : 
Order-nr                        : A5E37039512-AA
Print-year                      : 2016
Product-group                   : S7-1500
System                          : SIMATIC
XMP Toolkit                     : Adobe XMP Core 5.4-c005 78.147326, 2012/08/23-13:03:03
Metadata Date                   : 2016:08:12 11:07:46+02:00
Creator Tool                    : Acrobat PDFMaker 11 für Word
Document ID                     : uuid:1372316c-9ef4-4701-a198-fe26d62c3bb7
Instance ID                     : uuid:146ca74e-a1ce-4c07-882c-9c7f403fb72e
Format                          : application/pdf
Title                           : S7-PLCSIM Advanced
Description                     : Function Manual
Creator                         : DF FA AS E&C-PRM
Producer                        : Adobe PDF Library 11.0
Headline                        : Function Manual
Page Mode                       : UseOutlines
Page Count                      : 312
EXIF Metadata provided by EXIF.tools

Navigation menu