S7 PLCSIM Advanced Function Manual En US

User Manual:

Open the PDF directly: View PDF .
Page Count: 312 [warning: Documents this large are best viewed by clicking the View PDF Link!]

S7-PLCSIM Advanced
Legal information
Preface
Table of contents
1 Guide
- 1.1 Documentation Guide S7 PLCSIM Advanced
- 1.2 S7 PLCSIM products
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

S7-PLCSIM Advanced

___________________

SIMATIC

S7-1500

S7-PLCSIM Advanced

Function Manual

09/2016

A5E37039512

-AA

Preface

Guide

Product overview

Installing

Communication paths

Simulate CPU

Virtual time response

User interfaces (API)

Restrictions

List of abbreviations

Siemens AG

Division Digital Factory

Postfach 48 48

90026 NÜRNBERG

GERMANY

A5E37039512-AA

Ⓟ

08/2016 Subject to change

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.

S7-PLCSIM Advanced

4 Function Manual, 09/2016, A5E37039512-AA

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.

Preface

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 5

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

6 Function Manual, 09/2016, A5E37039512-AA

Table of contents

Preface ................................................................................................................................................... 4

1 Guide .................................................................................................................................................... 22

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

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

2 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

3 Installing ............................................................................................................................................... 32

3.1 Introduction ............................................................................................................................ 32

3.1.1 System requirements ............................................................................................................. 32

3.1.2 Licenses ................................................................................................................................. 33

3.1.3 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

4 Communication paths ........................................................................................................................... 40

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

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

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

5 Simulate CPU ....................................................................................................................................... 45

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

5.2 User interface ......................................................................................................................... 46

5.2.1 S7 PLCSIM Advanced Symbol .............................................................................................. 46

5.2.2 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 Simulate communication ........................................................................................................ 54

5.6.1 Communication services that can be simulated .................................................................... 54

5.6.2 Communication between instances ....................................................................................... 55

5.7 Provide project data offline for simulation .............................................................................. 56

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 7

6 Virtual time response ............................................................................................................................ 58

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

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

6.3 Synchronize simulation partner .............................................................................................. 62

6.3.1 Synchronize simulation partner cycle-controlled .................................................................... 62

6.3.2 Synchronize simulation partner time-controlled ...................................................................... 64

7 User interfaces (API) ............................................................................................................................. 65

7.1 Introduction ............................................................................................................................. 65

7.1.1 Access to instances ................................................................................................................ 67

7.1.2 User interfaces (API) ............................................................................................................... 68

7.1.3 Overview of user interfaces for native C++ ............................................................................ 69

7.1.4 Overview of user interfaces for managed code ...................................................................... 73

7.1.5 Overview of data types for native C++ .................................................................................... 76

7.1.6 Overview of data types for managed code ............................................................................. 77

7.2 Initialize API ............................................................................................................................ 78

7.2.1 Native C++ .............................................................................................................................. 78

7.2.1.1 InitializeApi() ........................................................................................................................... 78

7.2.1.2 RuntimeApiEntry_Initialize ...................................................................................................... 79

7.2.2 .NET (C#) ................................................................................................................................ 80

7.2.2.1 Initialize ................................................................................................................................... 80

7.3 Shut down API ........................................................................................................................ 81

7.3.1 Native C++ .............................................................................................................................. 81

7.3.1.1 DestroyInterface() ................................................................................................................... 82

7.3.1.2 RuntimeApiEntry_DestroyInterface ......................................................................................... 83

7.3.1.3 FreeApi() ................................................................................................................................. 84

7.3.1.4 ShutdownAndFreeApi()........................................................................................................... 85

7.3.2 .NET (C#) ................................................................................................................................ 86

7.3.2.1 Shut down API ........................................................................................................................ 86

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

7.5 API ISimulationRuntimeManager ............................................................................................ 90

7.5.1 Interfaces - Information and settings ...................................................................................... 90

7.5.2 Simulation Runtime instances ................................................................................................ 93

7.5.3 Remote connections ............................................................................................................. 101

7.5.4 Events ................................................................................................................................... 106

7.5.4.1 OnConfigurationChanged ..................................................................................................... 106

7.5.4.2 OnRuntimeManagerLost ....................................................................................................... 110

7.6 API IInstances ....................................................................................................................... 113

7.6.1 Interfaces - Information and settings .................................................................................... 113

7.6.2 Controller - Information and settings ..................................................................................... 119

7.6.3 Operating state ..................................................................................................................... 127

7.6.4 Tag list .................................................................................................................................. 135

7.6.5 I/O access ............................................................................................................................. 141

7.6.5.1 I/O access via address - Reading ......................................................................................... 141

7.6.5.2 I/O access via address - Writing ........................................................................................... 150

7.6.5.3 I/O access via tag name - Reading ....................................................................................... 158

7.6.5.4 I/O access via tag name - Writing ......................................................................................... 188

Table of contents

S7-PLCSIM Advanced

8 Function Manual, 09/2016, A5E37039512-AA

7.6.6 Settings for the virtual time .................................................................................................. 218

7.6.7 Cycle control ........................................................................................................................ 221

7.6.8 Events .................................................................................................................................. 227

7.6.8.1 OnOperatingStateChanged ................................................................................................. 228

7.6.8.2 OnEndOfCycle ..................................................................................................................... 232

7.6.8.3 OnConfigurationChanging ................................................................................................... 234

7.6.8.4 OnConfigurationChanged .................................................................................................... 237

7.6.8.5 OnLedChanged .................................................................................................................... 239

7.7 API IRemoteRuntimeManager ............................................................................................. 242

7.7.1 Interfaces - Information and settings.................................................................................... 242

7.7.2 Simulation Runtime instances .............................................................................................. 246

7.7.2.1 Simulation Runtime instances (remote) ............................................................................... 246

7.7.3 Events .................................................................................................................................. 254

7.7.3.1 OnConnectionLost ............................................................................................................... 254

7.8 Data types ............................................................................................................................ 257

7.8.1 DLL import functions (Native C++)....................................................................................... 258

7.8.1.1 ApiEntry_Initialize ................................................................................................................. 258

7.8.1.2 ApiEntry_DestroyInterface ................................................................................................... 258

7.8.2 Event callback functions (Native C++) ................................................................................. 259

7.8.2.1 EventCallback_VOID ........................................................................................................... 259

7.8.2.2 EventCallback_II_SREC_ST ................................................................................................ 259

7.8.2.3 EventCallback_II_SREC_ST_SROS_SROS ........................................................................ 260

7.8.2.4 EventCallback_II_SREC_ST_SRLT_SRLM ......................................................................... 261

7.8.2.5 EventCallback_II_SREC_ST_INT64_UINT32 ...................................................................... 262

7.8.2.6 EventCallback_IRRTM ......................................................................................................... 263

7.8.2.7 EventCallback_SRCC_UINT32_UINT32_INT32 .................................................................. 263

7.8.2.8 EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32 .......................... 264

7.8.3 Delegate definitions (managed code) .................................................................................. 265

7.8.3.1 Delegate_Void ...................................................................................................................... 265

7.8.3.2 Delegate_II_EREC_DT ........................................................................................................ 265

7.8.3.3 Delegate_II_EREC_DT_EOS_EOS...................................................................................... 266

7.8.3.4 Delegate_II_EREC_DT_ELT_ELM ....................................................................................... 267

7.8.3.5 Delegate_II_EREC_DT_INT64_UINT32 .............................................................................. 268

7.8.3.6 Delegate_IRRTM.................................................................................................................. 269

7.8.3.7 Delegate_SRCC_UINT32_UINT32_INT32 .......................................................................... 269

7.8.3.8 Delegate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32 .................................. 270

7.8.4 Definitions and constants ..................................................................................................... 271

7.8.5 Unions (Native C++) ............................................................................................................ 272

7.8.5.1 UIP ....................................................................................................................................... 272

7.8.5.2 UDataValue .......................................................................................................................... 272

7.8.6 Structures ............................................................................................................................. 274

7.8.6.1 SDataValue .......................................................................................................................... 274

7.8.6.2 SDataValueByAddress ........................................................................................................ 276

7.8.6.3 SDataValueByName ............................................................................................................ 276

7.8.6.4 SConnectionInfo................................................................................................................... 277

7.8.6.5 SInstanceInfo ....................................................................................................................... 278

7.8.6.6 SDimension .......................................................................................................................... 279

7.8.6.7 STagInfo ............................................................................................................................... 280

7.8.6.8 SIP ....................................................................................................................................... 282

7.8.6.9 SIPSuite4 ............................................................................................................................. 283

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 9

7.8.7 Enumerations ........................................................................................................................ 284

7.8.7.1 ERuntimeErrorCode .............................................................................................................. 284

7.8.7.2 EArea .................................................................................................................................... 286

7.8.7.3 EOperatingState ................................................................................................................... 287

7.8.7.4 EOperatingMode ................................................................................................................... 288

7.8.7.5 ECPUType ............................................................................................................................ 289

7.8.7.6 ECommunicationInterface .................................................................................................... 291

7.8.7.7 ELEDType ............................................................................................................................. 292

7.8.7.8 ELEDMode ............................................................................................................................ 293

7.8.7.9 EPrimitiveDataType .............................................................................................................. 294

7.8.7.10 EDataType ............................................................................................................................ 296

7.8.7.11 ETagListDetails ..................................................................................................................... 299

7.8.7.12 ERuntimeConfigChanged ..................................................................................................... 300

7.8.7.13 EInstanceConfigChanged ..................................................................................................... 300

8 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 Restrictions with Motion Control ........................................................................................... 307

8.6.1 Motion Control resources ...................................................................................................... 307

8.6.2 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

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

Table of contents

S7-PLCSIM Advanced

10 Function Manual, 09/2016, A5E37039512-AA

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

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 11

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

Table of contents

S7-PLCSIM Advanced

12 Function Manual, 09/2016, A5E37039512-AA

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

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 13

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

Table of contents

S7-PLCSIM Advanced

14 Function Manual, 09/2016, A5E37039512-AA

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

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 15

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

Table of contents

S7-PLCSIM Advanced

16 Function Manual, 09/2016, A5E37039512-AA

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

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 17

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

Table of contents

S7-PLCSIM Advanced

18 Function Manual, 09/2016, A5E37039512-AA

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

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 19

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

Table of contents

S7-PLCSIM Advanced

20 Function Manual, 09/2016, A5E37039512-AA

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

Table of contents

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 21

S7-PLCSIM Advanced

22 Function Manual, 09/2016, A5E37039512-AA

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

overview/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)

Guide

1.1 Documentation Guide S7 PLCSIM Advanced

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 23

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

Guide

1.2 S7 PLCSIM products

S7-PLCSIM Advanced

24 Function Manual, 09/2016, A5E37039512-AA

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

Function Manual, 09/2016, A5E37039512-AA 25

Product overview

2.1

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

Product overview

2.2 Security for PLCSIM Advanced

S7-PLCSIM Advanced

26 Function Manual, 09/2016, A5E37039512-AA

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 lim

ited.

Product overview

2.3 Simulations support

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 27

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 properti

es.

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

protected.

The "Simulation with SIMATIC S7-PLCSIM Advanced" option must be set when generating

the blocks (source of the blocks).

Product overview

2.4 Supported CPUs

S7-PLCSIM Advanced

28 Function Manual, 09/2016, A5E37039512-AA

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

Article number

Standard 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 ODK

2, 3

6ES7511-1AK01-0AB0

6ES7513-1AL01-0AB0

6ES7515-2AM01-0AB0

6ES7516-3AN01-0AB0

6ES7517-3AP00-0AB0

6ES7518-4AP00-0AB0

6ES7518-4AP00-3AB0

Fail-safe CPUs

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 ODK

2, 3

6ES7511-1FK01-0AB0

6ES7513-1FL01-0AB0

6ES7515-2FM01-0AB0

6ES7516-3FN01-0AB0

6ES7517-3FP00-0AB0

6ES7518-4FP00-0AB0

6ES7518-4FP00-3AB0

Compact CPUs1

CPU 1511C-1 PN

CPU 1512C-1 PN

6ES7511-1CK00-0AB0

6ES7512-1CK00-0AB0

ET 200SP CPUs

CPU 1510SP-1 PN

CPU 1510SP F-1 PN

CPU 1512SP-1 PN

CPU 1512SP F-1 PN

6ES7510-1DJ01-0AB0

6ES7512-1SJ01-0AB0

6ES7512-1DK01-0AB0

6ES7512-1SK01-0AB0

Technology CPUs

CPU 1511T-1 PN

CPU 1515T-2 PN

CPU 1517T-3 PN/DP3, 4

CPU 1517TF-3 PN/DP3, 4

6ES7511-1TK01-0AB0

6ES7515-2TM01-0AB0

6ES7517-3TP00-0AB0

6ES7517-3UP00-0AB0

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

to the process image.

The ODK functionality of this CPU is not simulated.

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

Product overview

2.5 Differences between a simulated and a real CPU

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 29

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

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

Product overview

2.5 Differences between a simulated and a real CPU

S7-PLCSIM Advanced

30 Function Manual, 09/2016, A5E37039512-AA

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

Product overview

2.6 Simulating Motion Control

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 31

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

PLCSIM 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

32 Function Manual, 09/2016, A5E37039512-AA

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.

Installing

3.1 Introduction

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 33

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.

Installing

3.1 Introduction

S7-PLCSIM Advanced

34 Function Manual, 09/2016, A5E37039512-AA

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@<DATE_TIME>.log

● SIA_S7-PLCSIM_Advanced_V01@<DATE_TIME>_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.

Installing

3.2 Installation medium

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 35

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

Installing

3.3 Installing PLCSIM Advanced

S7-PLCSIM Advanced

36 Function Manual, 09/2016, A5E37039512-AA

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

Installing

3.4 Changing PLCSIM Advanced

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 37

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.

Installing

3.5 Repairing PLCSIM Advanced

S7-PLCSIM Advanced

38 Function Manual, 09/2016, A5E37039512-AA

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.

Installing

3.6 Uninstalling PLCSIM Advanced

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 39

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

clicking the "Start.exe" file.

If you do not perform a restart, the Runtime Manager continues running.

2. Follow the prompts until you reach the "Configuration" window. Your previous installation

is detected. Select the "Uninstall" check box.

3. Follow the prompts 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

40 Function Manual, 09/2016, A5E37039512-AA

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

Distributed

Protocol

Softbus

TCP/IP

Communication interface in

PLCSIM Advanced

PLCSIM PLCSIM Virtual

Ethernet Adapter

PLCSIM Virtual

Ethernet Adapter

STEP 7 and instances

on a PC / VM

distributed

Communication...

between STEP 7 and instances

Yes

among instances

Yes

possible via OPC UA server and Web serv-

No Yes Yes

between an instance and a real hardware

CPU

No No Yes

between an instance and a real HMI V14

Yes

between an instance and a simulated HMI

V14

Yes Yes No

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

Communication paths

4.1 Local communication

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 41

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

Communication paths

4.2 Communication via TCP / IP

S7-PLCSIM Advanced

42 Function Manual, 09/2016, A5E37039512-AA

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 Local communication via TCP/IP

4.2

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

Communication paths

4.3 Enable distributed communication

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 43

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 Distributed communication via network adapters

4.3

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 netwo

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

Communication paths

4.3 Enable distributed communication

S7-PLCSIM Advanced

44 Function Manual, 09/2016, A5E37039512-AA

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

Function Manual, 09/2016, A5E37039512-AA 45

Simulate CPU

5.1

Basic procedure for the simulation

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

virtual controller.

Requirements

The following requirements must be met for starting simulation via local communication:

● STEP 7 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)

Simulate CPU

5.2 User interface

S7-PLCSIM Advanced

46 Function Manual, 09/2016, A5E37039512-AA

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 Example: Message in the taskbar

5.2.2

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.

Simulate CPU

5.2 User interface

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 47

①

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

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

work, the "Start" button is enabled.

⑤

• IP address

• Subnet mask

• Standard gateway

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.

Simulate CPU

5.2 User interface

S7-PLCSIM Advanced

48 Function Manual, 09/2016, A5E37039512-AA

⑩

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

Simulate CPU

5.2 User interface

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 49

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, disable virtual time,

Switch on instance, 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.

Simulate CPU

5.3 Download

S7-PLCSIM Advanced

50 Function Manual, 09/2016, A5E37039512-AA

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.

Simulate CPU

5.3 Download

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 51

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

Simulate CPU

5.4 MAC address of the instances

S7-PLCSIM Advanced

52 Function Manual, 09/2016, A5E37039512-AA

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

Simulate CPU

5.5 Simulate peripheral I/O

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 53

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)

Simulate CPU

5.6 Simulate communication

S7-PLCSIM Advanced

54 Function Manual, 09/2016, A5E37039512-AA

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

Open communication using ISO-on-

TCP

• TSEND_C / TRCV_C

• TSEND / TRCV

• TCON

• T_DISCON

Open communication via UDP2 • TUSEND / TURCV

• TCON

• T_DISCON

Communication via Modbus TCP • MB_CLIENT

• MB_SERVER

E-mail2 • TMAIL_C

S7 communication • PUT / GET

• BSEND / BRCV

• USEND / URCV

OPC UA Server2 Data exchange with OPC UA clients

Web server

Data exchange via HTTP

When the "PLCSIM" interface (Softbus) is set, communication is performed

internally

via ISO-on-

TCP.

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

Simulate CPU

5.6 Simulate communication

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 55

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.

Simulate CPU

5.7 Provide project data offline for simulation

S7-PLCSIM Advanced

56 Function Manual, 09/2016, A5E37039512-AA

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 <Virtual Memory Card>\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

Simulate CPU

5.7 Provide project data offline for simulation

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 57

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

58 Function Manual, 09/2016, A5E37039512-AA

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.

Virtual time response

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 59

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)

Virtual time response

6.1 Speed up and slow down simulation

S7-PLCSIM Advanced

60 Function Manual, 09/2016, A5E37039512-AA

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 co

nsiderably.

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 sp

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

Virtual time response

6.2 Stop simulation

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 61

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

Virtual time response

6.3 Synchronize simulation partner

S7-PLCSIM Advanced

62 Function Manual, 09/2016, A5E37039512-AA

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

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)

Virtual time response

6.3 Synchronize simulation partner

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 63

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)

Virtual time response

6.3 Synchronize simulation partner

S7-PLCSIM Advanced

64 Function Manual, 09/2016, A5E37039512-AA

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

Function Manual, 09/2016, A5E37039512-AA 65

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

ler. Each virtual controller generates its own process.

Siemens.Simatic.Simulation.

Runtime.Api.x86.dll

Siemens.Simatic.Simulation.

Runtime.Api.x64.dll

API libraries that must load an application to use the Simulation

Runtime. The libraries contain interfaces for native code and

managed code.

The "Runtime.Api.x86.dll" is loaded exclusively by 32-bit applica-

tions, and the "Runtime.Api.x64.dll" by 64-bit applications.

SimulationRuntimeApi.h Header file that describes all data types that require a native C++

application to use the API library.

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

66 Function Manual, 09/2016, A5E37039512-AA

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

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 67

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)

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

68 Function Manual, 09/2016, A5E37039512-AA

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

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 69

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)

DestroyInterface

RuntimeApiEntry DestroyInterface

Unregister DLL API (Page 84)

FreeApi

ShutdownAndFreeApi

Global functions

Table 7- 2 Overview of global functions - Native C++

Actions

Functions

Global functions (Page 86)

GetNameOfAreaSection()

GetNameOfCPUType()

GetNameOfCommunicationInterface()

GetNameOfDataType()

GetNameOfLEDMode()

GetNameOfLEDType()

GetNameOfOperatingMode()

GetNameOfOperatingState()

GetNameOfPrimitiveDataType()

GetNameOfTagListDetails()

GetNameOfErrorCode()

GetNameOfRuntimeConfigChanged()

GetNameOfInstanceConfigChanged()

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

70 Function Manual, 09/2016, A5E37039512-AA

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

Functions

Interface (Page 90)

GetVersion()

IsInitialized()

IsRuntimeManagerAvailable()

Shutdown()

Simulation Runtime instances

(Page 93)

GetRegisteredInstancesCount()

GetRegisteredInstanceInfoAt()

RegisterInstance()

RegisterCustomInstance()

CreateInterface()

Remote connections

(Page 101)

OpenPort()

ClosePort()

GetPort()

GetRemoteConnectionsCount()

GetRemoteConnectionInfoAt()

RemoteConnect()

Events

OnConfigurationChanged

(Page 106)

RegisterOnConfigurationChangedCallback()

UnregisterOnConfigurationChangedCallback()

RegisterOnConfigurationChangedEvent()

UnregisterOnConfigurationChangedEvent()

WaitForOnConfigurationChangedEvent()

OnRuntimeManagerLost

(Page 110)

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

Functions

Interface (Page 113)

GetID()

GetName()

GetCPUType()

SetCPUType()

GetCommunicationInterface()

SetCommunicationInterface()

GetInfo()

UnregisterInstance()

Controller (Page 119)

GetControllerName()

GetControllerShortDesignation()

GetControllerIPCount()

GetControllerIP()

GetControllerIPSuite4()

SetIPSuite()

GetStoragePath()

SetStoragePath()

ArchiveStorage()

RetrieveStorage()

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 71

Settings and information

Functions

Operating state (Page 127)

GetOperatingState()

PowerOn()

PowerOff()

MemoryReset()

Run()

Stop()

Tag list (Page 135)

UpdateTagList()

GetTagListStatus()

GetTagInfoCount()

GetTagInfos()

CreateConfigurationFile()

I/O access via address - Read-

ing (Page 141)

GetAreaSize()

ReadBit()

ReadByte()

ReadBytes()

ReadSignals()

I/O access via address - Writ-

ing (Page 150)

WriteBit()

WriteByte()

WriteBytes()

WriteSignals()

I/O access via tag name -

Reading (Page 158)

Read()

ReadBool()

ReadChar(), ReadWChar()

ReadDouble()

ReadFloat()

ReadInt8(), ReadInt16(), ReadInt32(), ReadInt64()

ReadUInt8(), ReadUInt16(), ReadUInt32(), ReadUInt64()

ReadSignals()

I/O access via tag name -

Writing (Page 188)

Write()

WriteBool()

WriteChar(), WriteWChar()

WriteDouble()

WriteFloat()

WriteInt8(), WriteInt16(), WriteInt32(), WriteInt64(),

WriteUInt8(),WriteUInt16(), WriteUInt32(), WriteUInt64()

WriteSignals()

Virtual time (Page 218)

GetSystemTime()

SetSystemTime()

GetScaleFactor()

SetScaleFactor()

Cycle control (Page 221)

GetOperatingMode()

SetOperatingMode()

SetAlwaysSendOnEndOfCycleEnabled()

IsAlwaysSendOnEndOfCycleEnabled()

GetOverwrittenMinimalCycleTime_ns()

SetOverwrittenMinimalCycleTime_ns()

RunNextCycle()

StartProcessing()

Events

OnOperatingStateChanged

(Page 228)

RegisterOnOperatingStateChangedCallback()

UnregisterOnOperatingStateChangedCallback()

RegisterOnOperatingStateChangedEvent()

UnregisterOnOperatingStateChangedEvent()

WaitForOnOperatingStateChangedEvent()

OnEndOfCycle (Page 232)

RegisterOnEndOfCycleCallback()

UnregisterOnEndOfCycleCallback()

RegisterOnEndOfCycleEvent()

UnregisterOnEndOfCycleEvent()

WaitForOnEndOfCycleEvent()

OnConfigurationChanging

(Page 234)

RegisterOnConfigurationChangingCallback()

UnregisterOnConfigurationChangingCallback()

RegisterOnConfigurationChangingEvent()

UnregisterOnConfigurationChangingEvent()

WaitForOnConfigurationChangingEvent()

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

72 Function Manual, 09/2016, A5E37039512-AA

Settings and information

Functions

OnConfigurationChanged

(Page 237)

RegisterOnConfigurationChangedCallback()

UnregisterOnConfigurationChangedCallback()

RegisterOnConfigurationChangedEvent()

UnregisterOnConfigurationChangedEvent()

WaitForOnConfigurationChangedEvent()

OnLedChanged (Page 239)

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

Functions

Interface (Page 242)

GetVersion()

GetIP()

GetPort()

GetRemoteComputerName()

Disconnect()

Simulation Runtime instances

(Page 246)

GetRegisteredInstancesCount()

GetRegisteredInstanceInfoAt()

RegisterInstance()

RegisterCustomInstance()

CreateInterface()

Events

OnConnectionLost (Page 254)

RegisterOnConnectionLostCallback()

UnregisterOnConnectionLostCallback()

RegisterOnConnectionLostEvent()

UnregisterOnConnectionLostEvent()

WaitForOnConnectionLostEvent()

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 73

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)

Sie-

mens.Simatic.Simulation.Runtime.SimulationRuntimeManager

Shut down API (Page 86)

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

Functions

Interface (Page 90)

Version { get; }

IsInitialized { get; }

IsRuntimeManagerAvailable { get; }

Shutdown()

Simulation Runtime instances

(Page 93)

RegisterInstanceInfo { get; }

RegisterInstance()

RegisterCustomInstance()

CreateInterface()

Remote connections

(Page 101)

OpenPort()

ClosePort()

Port { get; }

RemoteConnectionInfo { get; }

RemoteConnect()

Events

OnConfigurationChanged

(Page 106)

OnConfigurationChanged

RegisterOnConfigurationChangedEvent()

UnregisterOnConfigurationChangedEvent()

WaitForOnConfigurationChangedEvent()

OnRuntimeManagerLost

(Page 110)

OnRuntimeManagerLost()

RegisterOnRuntimeManagerLostEvent()

UnregisterOnRuntimeManagerLostEvent()

WaitForOnRuntimeManagerLostEvent()

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

74 Function Manual, 09/2016, A5E37039512-AA

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

Interface (Page 113)

Dispose ()

ID { get; }

Name { get; }

CPUType { get; set; }

CommunicationInterface { get; }

Info { get; }

UnregisterInstance()

Controller - Information and

settings (Page 119)

ControllerName { get; }

ControllerShortDesignation { get; }

ControllerIPSuite4 { get; }

SetIPSuite()

StoragePath { get; set; }

ArchiveStorage()

RetrieveStorage()

Operating state (Page 127)

OperatingState { get; }

PowerOn()

PowerOff()

MemoryReset()

Run()

Stop()

Tag list (Page 135)

UpdateTagList()

GetTagListStatus()

TagInfos { get; }

CreateConfigurationFile()

I/O access via address - Read-

ing (Page 141)

InputArea | MarkerArea | OutputArea { get; }

AreaSize { get; }

ReadBit()

ReadByte()

ReadBytes()

ReadSignals()

I/O access via address - Writ-

ing (Page 150)

WriteBit()

WriteByte()

WriteBytes()

WriteSignals()

I/O access via tag name -

Reading (Page 158)

Read()

ReadBool()

ReadChar(), ReadWChar()

ReadDouble()

ReadFloat()

ReadInt8(), ReadInt16(), ReadInt32(), ReadInt64()

ReadUInt8(), ReadUInt16(), ReadUInt32(), ReadUInt64()

ReadSignals()

I/O access via tag name -

Writing (Page 188)

Write()

WriteBool()

WriteChar(), WriteWChar()

WriteDouble()

WriteFloat()

WriteInt8(), WriteInt16(), WriteInt32(), WriteInt64(),

WriteUInt8(),WriteUInt16(), WriteUInt32(), WriteUInt64()

WriteSignals()

Virtual time (Page 218)

SystemTime { get; set; }

ScaleFactor { get; set; }

Cycle control (Page 221)

OperatingMode { get; set; }

IsAlwaysSendOnEndOfCycleEnabled { get; set; }

OverwrittenMinimalCycleTime_ns { get; set; }

RunNextCycle()

StartProcessing()

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 75

Settings and information

Functions

Events

OnOperatingStateChanged

(Page 228)

OnOperatingStateChanged

RegisterOnOperatingStateChangedEvent()

UnregisterOnOperatingStateChangedEvent()

WaitForOnOperatingStateChangedEvent()

OnEndOfCycle (Page 232)

OnEndOfCycle

RegisterOnEndOfCycleEvent()

UnregisterOnEndOfCycleEvent()

WaitForOnEndOfCycleEvent()

OnConfigurationChanging

(Page 234)

OnConfigurationChanging

RegisterOnConfigurationChangingEvent()

UnregisterOnConfigurationChangingEvent()

WaitForOnConfigurationChangingEvent()

OnConfigurationChanged

(Page 106)

OnConfigurationChanged

RegisterOnConfigurationChangedEvent()

UnregisterOnConfigurationChangedEvent()

WaitForOnConfigurationChangedEvent()

OnLedChanged (Page 239)

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

Functions

Interface (Page 242)

Dispose()

Version { get; }

IP { get; }

Port { get; }

RemoteComputerName { get; }

Disconnect()

Simulation Runtime instances

(Page 93)

RegisterInstanceInfo { get; }

RegisterInstance()

RegisterCustomInstance()

CreateInterface()

Events

OnConnectionLost()

(Page 254)

OnConnectionLost()

RegisterOnConnectionLostEvent()

UnregisterOnConnectionLostEvent()

WaitForOnConnectionLostEvent()

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

76 Function Manual, 09/2016, A5E37039512-AA

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)

UIP

UDataValue

Structures (Page 274)

SDataValue

SDataValueByAddress

SDataValueByName

SConnectionInfo

SInstanceInfo

SDimension

STagInfo

SIP

SIPSuite4

Enumerations (Page 284)

ERuntimeErrorCode

EArea

EOperatingState

EOperatingMode

ECPUType

ECommunicationInterface

ELEDType

ELEDMode

EPrimitiveDataTypes

EDataType

ETagListDetails

ERuntimeConfigChanged

EInstanceConfigChanged

User interfaces (API)

7.1 Introduction

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 77

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)

SDataValue

SDataValueByAddress

SDataValueByName

SConnectionInfo

SInstanceInfo

SDimension

STagInfo

SIP

SIPSuite4

Enumerations (Page 284)

ERuntimeErrorCode

EArea

EOperatingState

EOperatingMode

ECPUType

ECommunicationInterface

ELEDType

ELEDMode

EPrimitiveDataTypes

EDataType

ETagListDetails

ERuntimeConfigChanged

EInstanceConfigChanged

User interfaces (API)

7.2 Initialize API

S7-PLCSIM Advanced

78 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode InitializeApi(

ISimulationRuntimeManager** out_SimulationRuntimeManagerInterface

);

ERuntimeErrorCode InitializeApi(

WCHAR* in_SimulationRuntimeApiDllPath,

ISimulationRuntimeManager** in-

out_SimulationRuntimeManagerInterface

);

Parameters • ISimulationRuntimeManager**

out_SimulationRuntimeManagerInterface:

Pointer to a Runtime Manager interface pointer. The pointer must be initial-

ized 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

The required version of the interface is in-

compatible with the version used to compile

the API.

SREC_CONNECTION_ERROR

Unable to establish a connection to the

Runtime Manager.

SREC_ERROR_LOADING_DLL

The API library (DLL) cannot be loaded.

User interfaces (API)

7.2 Initialize API

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 79

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

__declspec(dllexport) ERuntimeErrorCode RuntimeApiEntry_Initialize(

ISimulationRuntimeManager** out_SimulationRuntimeManagerInterface,

UINT32 in_InterfaceVersion

);

Parameters • ISimulationRuntimeManager**

out_SimulationRuntimeManagerInterface:

Pointer to a Runtime Manager interface pointer. The pointer must be initial-

ized 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:

DAPI_DLL_INTERFACE_VERSION.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT

The pointer to the Runtime Manager interface

does not equal NULL.

SREC_WRONG_VERSION

The required version of the interface is in-

compatible with the version used to compile

the API.

User interfaces (API)

7.2 Initialize API

S7-PLCSIM Advanced

80 Function Manual, 09/2016, A5E37039512-AA

SREC_CONNECTION_ERROR

Unable to establish a connection to the

Runtime Manager.

Example C++

// Include The Headerfile Of The API

#include "SimulationRuntimeApi.h"

// Prepare The Variables

ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;

HMODULE dllHandle = NULL;

ApiEntry_Initialize Initialize = NULL;

ISimulationRuntimeManager* api = NULL;

// Load The DLL And Import The "Initialize" Function (using the

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 Initialize - .NET (C#)

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationInitializationException

Runtime error code

Condition

ERuntimeError-

Code.ConnectionError Unable to establish a connection to the Runtime

Manager.

User interfaces (API)

7.3 Shut down API

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 81

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)

User interfaces (API)

7.3 Shut down API

S7-PLCSIM Advanced

82 Function Manual, 09/2016, A5E37039512-AA

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 • IBaseInterface* in_Interface:

The interface to be deleted.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT

The pointer to the interface is

NULL

Example C++

// Include The Headerfile Of The API

#include "SimulationRuntimeApi.h"

// The Interfaces

ERuntimeErrorCode result;

ISimulationRuntimeManager* api = NULL;

IInstance* instance = NULL;

// Init the DLL and create an instance

result = InitializeApi(&api);

result = api->RegisterInstance(&instance);

// Destroy Instance Interfaces

result =

DestroyInterface

(instance);

instance = NULL;

User interfaces (API)

7.3 Shut down API

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 83

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

__declspec(dllexport) ERuntimeErrorCode RuntimeA-

piEntry_DestroyInterface(

IBaseInterface* in_Interface

);

Parameters • IBaseInterface* in_Interface:

The interface to be deleted.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT

The pointer to the interface is NULL.

Example C++

// Include The Headerfile Of The API

#include "SimulationRuntimeApi.h"

// Prepare The Variables

ERuntimeErrorCode result = SREC_INVALID_ERROR_CODE;

HMODULE dllHandle = NULL;

ApiEntry_DestroyInterface Destroy = NULL;

IInstance* instance = NULL;

// Load The DLL And Import The “DestroyInterface” Function (using

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

User interfaces (API)

7.3 Shut down API

S7-PLCSIM Advanced

84 Function Manual, 09/2016, A5E37039512-AA

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

InitializeApi function was not called, the library must be unloaded using the Win32 API

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

User interfaces (API)

7.3 Shut down API

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 85

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

Funktion FreeLibrary().

Table 7- 18 ShutdownAndFreeApi() - Native C++

Syntax

ERuntimeErrorCode ShutdownAndFreeApi(

ISimulationRuntimeManager* in_SimulationRuntimeManagerInterface

);

Parameters • ISimulationRuntimeManager* in_SimulationRuntimeManagerInterface:

The interface of the Runtime Manager to be deleted.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_API_NOT_INITIALIZED

The InitializeApi function was not called

successfully.

SREC_WRONG_ARGUMENT

The pointer to the interface is NULL.

Example C++

// Include The Headerfile Of The API

#include "SimulationRuntimeApi.h"

// The Interfaces

ERuntimeErrorCode result;

ISimulationRuntimeManager* api = NULL;

IInstance* instance = NULL;

// Init the API

result = InitializeApi(&api);

…

// Shutdown The API

result =

ShutdownAndFreeApi

(api);

api = NULL;

User interfaces (API)

7.4 Global functions (Native C++)

S7-PLCSIM Advanced

86 Function Manual, 09/2016, A5E37039512-AA

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

Syntax

const WCHAR* GetNameOfAreaSection(

EArea in_AreaSection

);

Parameters • EArea in_AreaSection:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfCPUType()

Returns the name of the enumeration entry.

Table 7- 20 GetNameOfCPUType() - Native C++

Syntax

const WCHAR* GetNameOfCPUType(

ECPUType in_CPUType

);

Parameters • ECPUType in_CPUType:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

User interfaces (API)

7.4 Global functions (Native C++)

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 87

GetNameOfCommunicationInterface()

Returns the name of the enumeration entry.

Table 7- 21 GetNameOfCommunicationInterface() - Native C++

Syntax

const WCHAR* GetNameOfCommunicationInterface(

ECommunicationInterface in_CommunicationInterface

);

Parameters • ECommunicationInterface in_CommunicationInterface:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfDataType()

Returns the name of the enumeration entry.

Table 7- 22 GetNameOfDataType() - Native C++

Syntax

const WCHAR* GetNameOfDataType(

EDataType in_DataType

);

Parameters • EDataType in_DataType:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfErrorCode()

Returns the name of the enumeration entry.

Table 7- 23 GetNameOfErrorCode() - Native C++

Syntax

const WCHAR* GetNameOfErrorCode(

ERuntimeErrorCode in_ErrorCode

);

Parameters • ERuntimeErrorCode in_ErrorCode:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfLEDMode()

Returns the name of the enumeration entry.

Table 7- 24 GetNameOfLEDMode() - Native C++

Syntax

const WCHAR* GetNameOfLEDMode(

ELEDMode in_LEDMode

);

Parameters • ELEDMode in_LEDMode:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

User interfaces (API)

7.4 Global functions (Native C++)

S7-PLCSIM Advanced

88 Function Manual, 09/2016, A5E37039512-AA

GetNameOfLEDType()

Returns the name of the enumeration entry.

Table 7- 25 GetNameOfLEDType() - Native C++

Syntax

const WCHAR* GetNameOfLEDType(

ELEDType in_LEDType

);

Parameters • ELEDType in_LEDType:

Enumeration entry.

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfOperatingMode()

Returns the name of the enumeration entry.

Table 7- 26 GetNameOfOperatingMode() - Native C++

Syntax

const WCHAR* GetNameOfOperatingMode(

EOperatingMode in_OperatingMode

);

Parameters • EOperatingMode in_OperatingMode:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfErrorCode()

Returns the name of the enumeration entry.

Table 7- 27 GetNameOfErrorCode() - Native C++

Syntax

const WCHAR* GetNameOfErrorCode(

ERuntimeErrorCode in_ErrorCode

);

Parameters • ERuntimeErrorCode in_ErrorCode:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfOperatingState

Returns the name of the enumeration entry.

Table 7- 28 GetNameOfOperatingState() - Native C++

Syntax

const WCHAR* GetNameOfOperatingState(

EOperatingState in_OperatingState

);

Parameters • EOperatingState in_OperatingState:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

User interfaces (API)

7.4 Global functions (Native C++)

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 89

GetNameOfPrimitiveDataType

Returns the name of the enumeration entry.

Table 7- 29 GetNameOfPrimitiveDataType() - Native C++

Syntax

const WCHAR* GetNameOfPrimitiveDataType(

EPrimitiveDataType in_DataType

);

Parameters • EPrimitiveDataType in_DataType:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfTagListDetails

Returns the name of the enumeration entry.

Table 7- 30 GetNameOfTagListDetails() - Native C++

Syntax

const WCHAR* GetNameOfTagListDetails(

ETagListDetails in_TagListDetails

);

Parameters • ETagListDetails in_TagListDetails:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfRuntimeConfigChanged()

Returns the name of the enumeration entry.

Table 7- 31 GetNameOfRuntimeConfigChanged() - Native C++

Syntax

const WCHAR* GetNameOfRuntimeConfigChanged( ERuntimeConfigChanged

in_RuntimeConfigChanged);

);

Parameters • ERuntimeConfigChanged in_RuntimeConfigChanged:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

GetNameOfInstanceConfigChanged()

Returns the name of the enumeration entry.

Table 7- 32 GetNameOfInstanceConfigChanged() - Native C++

Syntax

const WCHAR* GetNameOfInstanceConfigChanged( EInstanceCon-

figChanged in_InstanceConfigChanged);

);

Parameters • EInstanceConfigChanged in_InstanceConfigChanged:

Enumeration entry

Return values

const WCHAR*: Name of the enumeration entry

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

90 Function Manual, 09/2016, A5E37039512-AA

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)

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 91

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 • false: If the API was not initialized.

•

true:

If the API was initialized.

Table 7- 36 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 • false: If the connection is interrupted.

•

true:

If the connection is active.

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

Syntax

bool IsRuntimeManagerAvailable{ get; }

Parameters

None

Return values • false: If the connection is interrupted.

•

true:

If the connection is active.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

92 Function Manual, 09/2016, A5E37039512-AA

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

Syntax

ERuntimeErrorCode Shutdown()

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

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 93

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

ERuntimeErrorCode GetRegisteredInstanceInfoAt(

UINT32 in_Index,

SInstanceInfo* out_InstanceInfo

);

Parameters • UINT32 in_Index:

Index of the created instance from which you want to receive the information.

The index must be less than the value you receive when you call GetRegis-

teredInstanceCount().

• SInstanceInfo* out_InstanceInfo:

The information with name and ID of the instance. See Data types (Page 271).

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_INDEX OUT_OF_RANGE

There is no instance information for this

index.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

94 Function Manual, 09/2016, A5E37039512-AA

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

SInstanceInfo[] RegisteredInstanceInfo { get; }

Parameters

None

Return values

SInstanceInfo[]: An array of information about all registered instances.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 95

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

ERuntimeErrorCode RegisterInstance(

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterInstance(

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterInstance(

ECPUType in_CPUType,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterInstance(

ECPUType in_CPUType,

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

Parameters • ECPUType in_CPUType:

Defines which CPU type is simulated at the start of the instance. The default

setting is "SRCT_1500_Unspecified".

When a different CPU type is loaded via STEP 7 or from the Virtual 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).

• IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initial-

ized with ZERO. The interface is created within the function.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The name or the IInstance pointer is

invalid.

SREC_LIMIT_REACHED

There are already 16 instances regis-

tered in Runtime Manager.

SREC_ALREADY_EXISTS

An instance with this name already ex-

ists.

Example C++

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

}

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

96 Function Manual, 09/2016, A5E37039512-AA

Note

Native C++

If you no longer require the interface, delete it.

See

DestroyInterface() (Page 82).

Table 7- 45 RegisterInstance() - .NET (C#)

Syntax

IInstance RegisterInstance();

IInstance RegisterInstance(

string in_InstanceName

);

IInstance RegisterInstance(

ECPUType in_CPUType

);

IInstance RegisterInstance(

ECPUType in_CPUType

string in_InstanceName

);

Parameters • ECPUType in_CPUType:

Defines which CPU type is simulated at the start of the instance. The default

setting is "ECPUType.Unspecified".

When a different CPU type is loaded via STEP 7 or from the Virtual 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

Condition

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The name is invalid.

ERuntimeErrorCode.LimitReached

There are already 16 instances regis-

tered in Runtime Manager.

ERuntimeErrorCode.AlreadyExists

An instance with this name already ex-

ists.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 97

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

ERuntimeErrorCode RegisterCustomInstance(

WCHAR* in_VplcDll,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterCustomInstance(

WCHAR* in_VplcDll,

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

Parameters • WCHAR* in_VplcDll:

The complete path to the DLL of the virtual controller that Sie-

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

• IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initial-

ized with ZERO. The interface is created within the function.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The DLL name, the instance name or the

IInstance pointer is invalid.

SREC_LIMIT_REACHED

There are already 16 instances regis-

tered in Runtime Manager.

SREC_ALREADY_EXISTS

An instance with this name already ex-

ists.

Example C++

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

}

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

98 Function Manual, 09/2016, A5E37039512-AA

Note

Native C++

If you no longer require the interface, delete it.

See

DestroyInterface() (Page 82).

Table 7- 47 RegisterCustomInstance() - .NET (C#)

Syntax

IInstance RegisterCustomInstance(

string in_VplcDll

);

IInstance RegisterCustomInstance(

string in_VplcDll,

string in_InstanceName

);

Parameters • string in_VplcDll:

The complete path to the DLL of the virtual controller that Sie-

mens.Simatic.Simulation.Runtime.Instance.exe loads at PowerOn.

• string in_InstanceName:

Name to be assigned to the instance. Every instance must have a unique

name. If no name is assigned when registering a new instance, the instance is

given the name "Instance_#"

(# is the ID of the instance). If this name already

exists, the name "Instance_#.#" is used, in which the second # is a counter

that is incremented until the name is unique. The length of the name must be

less than DINSTANCE_NAME_LENGTH. See Data types (Page 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 Condition

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The name or the ID is invalid.

ERuntimeErrorCode.LimitReached

There are already 16 instances regis-

tered in Runtime Manager.

ERuntimeErrorCode.AlreadyExists

An instance with this name already ex-

ists.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 99

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

ERuntimeErrorCode CreateInterface(

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode CreateInterface(

INT32 in_InstanceID,

IInstance** out_InstanceInterface

);

Parameters • INT32 in_InstanceID:

The ID of the registered instance from which you want to receive the interface.

• WCHAR* in_InstanceName:

The name of the registered instance from which you want to receive the inter-

face.

• IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer

must

be initial-

ized with ZERO. The interface is created within the function.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The name, the ID or the IInstance pointer

is invalid.

SREC_DOES_NOT_EXIST

The instance is not registered in Runtime

Manager.

Example C++

ISimulationRuntimeManager * api = ZERO;

ERuntimeErrorCode result = Initialize(&api);

IInstance* psa1 = ZERO;

IInstance* psa2 = ZERO;

if (result == SREC_OK)

{

result = api->

CreateInterface

(0, &psa1);

result = api->

CreateInterface

(0, &psa2); // psa2 will be the same as

psa1

}

Example C++

ISimulationRuntimeManager * api = ZERO;

ERuntimeErrorCode result = Initialize(&api);

IInstance* psa = ZERO;

if (result == SREC_OK)

{

result = api->

CreateInterface

(L"My SimulationRuntime Instance",

&psa);

}

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

100 Function Manual, 09/2016, A5E37039512-AA

Note

Native C++

If you no longer require the interface, d

elete it.

See

DestroyInterface() (Page 82).

Table 7- 49 CreateInterface() - .NET (C#)

Syntax

IInstance CreateInterface(

string in_InstanceName

);

IInstance CreateInterface(

INT32 in_InstanceID

);

Parameters • INT32 in_InstanceID:

The ID of the registered instance from which you want to receive the interface.

• string in_InstanceName:

The name of the registered instance from which you want to receive the inter-

face.

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

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.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 101

7.5.3

Remote connections

OpenPort()

Opens a port to which another Runtime Manager can connect.

Table 7- 50 OpenPort() - Native C++

Syntax

ERuntimeErrorCode OpenPort(

UINT16 in_Port

);

Parameters • UINT16 in_Port:

The port. The value must be greater than 1024.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_ALREADY_EXISTS

A port is already open.

SREC_WRONG_ARGUMENT

The port is invalid.

SREC_CONNECTION_ERROR

The port cannot be opened.

Table 7- 51 OpenPort() - .NET (C#)

Syntax

void OpenPort(

UInt16 in_Port

);

Parameters • UInt16 in_Port:

The port. The value must be greater than 1024.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.AlreadyExists

A port is already open.

ERuntimeErrorCode.WrongArgument

The port is invalid.

ERuntimeError-

Code.ConnectionError

The port cannot be opened.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

102 Function Manual, 09/2016, A5E37039512-AA

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

The function does not return on time.

SREC_WARNING_INVALID_CALL

No port is open.

Table 7- 53 ClosePort() - .NET (C#)

Syntax

void ClosePort(

UInt16 in_Port

);

Parameters

None

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeErrorCode.Timeout

The function does not return on time.

GetPort() / Port { get; }

Returns the open port. If no port is open or the function fails, the return value is 0.

Table 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

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 103

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

Syntax

ERuntimeErrorCode GetRemoteConnectionInfoAt(

UINT32 in_Index,

SConnectionInfo* out_ConnectionInfo

);

Parameters • UINT32 in_Index:

Index of the connection information that is expected.

• SConnectionInfo* out_ConnectionInfo:

The connection information for this index.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_INDEX_OUT_OF_RANGE

Connection information for this index

does not exist.

RemoteConnectionInfo { get; }

Returns an array of information about all open connections.

Table 7- 58 RemoteConnectionInfo { get; } - .NET (C#)

Syntax

SConnectionInfo[] RemoteConnectionInfo { get; }

Parameters

None

Return values

SConnectionInfo[]: An array of information about all open connections.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

104 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode RemoteConnect(

UINT8 in_IP3,

UINT8 in_IP2,

UINT8 in_IP1,

UINT8 in_IP0,

UINT16 in_Port,

IRemoteRuntimeManager** out_RemoteRuntimeManagerInterface

ERuntimeErrorCode RemoteConnect(

UIP in_IP,

UINT16 in_Port,

IRemoteRuntimeManager** out_RunTimeManagerInterface

);

Parameters • UINT8 in_IP3:

First part of the IP address of the remote PC.

• UINT8 in_IP2:

Second part of the IP address of the remote PC.

• UINT8 in_IP1:

Third part of the IP address of the remote PC.

UINT8 in_IP0:

Last part of the IP address of the remote PC.

• UIP in_IP:

IP address of the remote PC.

• UINT16 in_Port:

The port that is open on the remote PC.

• IRemoteRuntimeManager** out_RemoteRuntimeManagerInterface:

Pointer to a remote Runtime Manager interface pointer. The pointer

must

be in-

itialized with ZERO. The interface is created in the function.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_TIMEOUT

The function does not return on time.

SREC_CONNECTION_ERROR

The connection to the remote Runtime

Manager cannot be established.

SREC_WRONG_ARGUMENT

IP, port or IInstance pointer is invalid.

Example C++

ISimulationRuntimeManager* api = ZERO;

ERuntimeErrorCode result = Initialize(&api);

IRemoteRuntimeManager * client = ZERO;

if (result == SREC_OK)

{

result = api->

RemoteConnect

(192,203,145,144, 4444, &client);

}

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 105

Note

Native C++

If you no longer require the interface, delete it.

See

DestroyInterface() (Page 82).

Table 7- 60 RemoteConnect() - .NET (C#)

Syntax

IRemoteRuntimeManager RemoteConnect(

string in_ConnectionString

);

IRemoteRuntimeManager RemoteConnect(

SIP in_IP,

UInt16 in_Port

);

IRemoteRuntimeManager RemoteConnect(

Byte in_IP3,

Byte in_IP2,

Byte in_IP1,

Byte in_IP0,

UInt16 in_Port

);

Parameters • Byte in_IP3:

First part of the IP address of the remote PC.

• Byte in_IP2:

Second part of the IP address of the remote PC.

• Byte in_IP1:

Third part of the IP address of the remote PC.

• Byte in_IP0:

Last part of the IP address of the remote PC.

• string in_ConnectionString:

A string in the form of "<IP3>.<IP2>.<IP1>.<IP0>:<Port>"

Example: "182.203.145.144:4444".

• SIP in_IP:

IP address of the remote PC.

• UInt16 in_Port:

The port that is open on the remote PC.

Return values

IRemoteRuntimeManager: Interface to the remote Runtime Manager.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.ConnectionError Connection to the remote Runtime Man-

ager cannot be established.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

IP or port is invalid.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

106 Function Manual, 09/2016, A5E37039512-AA

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

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

The event is triggered when the connection to Runtime Manager is

interrupted.

7.5.4.1

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.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 107

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

Syntax

void RegisterOnConfigurationChangedCallback(

EventCallback_SRCC_UINT32_UINT32_INT32 in_CallbackFunction

);

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

Syntax

void RegisterOnConfigurationChangedEvent();

void RegisterOnConfigurationChangedEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event object is registered.

• HANDLE* in_Event:

A handle for a user-specific event object. The event object is registered.

Return values

None

Table 7- 65 RegisterOnConfigurationChangedEvent() - .NET (C#)

Syntax

void RegisterOnConfigurationChangedEvent();

Parameters

None

Return values

None

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

108 Function Manual, 09/2016, A5E37039512-AA

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

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 109

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

Syntax

bool WaitForOnConfigurationChangedEvent();

bool WaitForOnConfigurationChangedEvent(

UINT32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

Table 7- 70 WaitForOnConfigurationChangedEvent - .NET (C#)

Syntax

bool WaitForOnConfigurationChangedEvent();

bool WaitForOnConfigurationChangedEvent(

UInt32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

110 Function Manual, 09/2016, A5E37039512-AA

7.5.4.2

OnRuntimeManagerLost

Registers or unregisters an event handler method.

Table 7- 71 OnRuntimeManagerLost - .NET (C#)

Syntax

event Delegate_Void OnRuntimeManagerLost;

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

void RegisterOnRuntimeManagerLostCallback(

EventCallback_VOID in_CallbackFunction

);

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

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 111

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

Syntax

void RegisterOnRuntimeManagerLostEvent();

void RegisterOnRuntimeManagerLostEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event handle is registered.

• HANDLE* in_Event:

A user-specific event handle is registered.

Return values

None

Table 7- 74 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

User interfaces (API)

7.5 API ISimulationRuntimeManager

S7-PLCSIM Advanced

112 Function Manual, 09/2016, A5E37039512-AA

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

Syntax

bool WaitForOnRuntimeManagerLostEvent();

bool WaitForOnRuntimeManagerLostEvent(

UINT32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined timeout interval.

Table 7- 79 WaitForOnRuntimeManagerLostEvent() - .NET (C#)

Syntax

bool WaitForOnRuntimeManagerLostEvent();

bool WaitForOnRuntimeManagerLostEvent(

UInt32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined timeout interval.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 113

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

114 Function Manual, 09/2016, A5E37039512-AA

GetName() / Name { get; }

Returns the name of the instance.

Table 7- 83 GetName() - Native C++

Syntax

ERuntimeErrorCode GetName(

WCHAR inout_Name[],

UINT32 in_ArrayLength

);

Parameters • WCHAR inout_Name[]:

A user-allocated storage for the name of the instance. The field length should

be at least as long as DINSTANCE_NAME_MAX_LENGTH.

See Definitions and constants (Page 271).

• UINT32 in_ArrayLength:

Field length (Wide character)

Return values

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.

Example C++

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

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 115

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

116 Function Manual, 09/2016, A5E37039512-AA

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

Is returned if the virtual controller uses the Softbus.

• SRCI_TCPIP

Is returned if the virtual controller communicates over the virtual adapter.

SetCommunicationInterface()

Sets the communication interface of the virtual controller: Local communication (Softbus) or

TCPIP. A change of communication interface occurs only when the controller is restarted. All

instances that are started must use the same communication interface.

PowerOn is prevented if a communication interface that is not used by the started instances

is selected.

Table 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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 117

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

Is returned if the virtual controller uses the Softbus.

• ECommunicationInterface.TCPIP

Is returned if the virtual controller communicates over the virtual adapter.

Exceptions

None

GetInfo() / Info { get; }

Returns a structure that provides information about the instance.

Table 7- 91 GetInfo() - Native C++

Syntax

SInstanceInfo GetInfo();

Parameters

None

Return values SInstanceInfo: A structure that provides information about the instance. See

SInstanceInfo (Page 278).

Table 7- 92 Info { get; } - .NET (C#)

Syntax

SInstanceInfo Info { get; }

Parameters

None

Return values

SInstanceInfo: A structure that provides information about the instance.

Exceptions

None

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

118 Function Manual, 09/2016, A5E37039512-AA

UnregisterInstance()

Unregisters this instance from Runtime Manager.

Note

Loss of the interfaces

Other applications t

hat 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

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

Table 7- 94 UnregisterInstance() - .NET (C#)

Syntax

void UnregisterInstance();

Parameters

None

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 119

7.6.2

Controller - Information and settings

GetControllerName() / ControllerName { get; }

Returns the downloaded name of the virtual controller.

Table 7- 95 GetControllerName() - Native C++

Syntax

ERuntimeErrorCode GetControllerName(

WCHAR inout_Name[],

UINT32 in_ArrayLength

);

Parameters • WCHAR inout_Name[]:

A user-allocated storage for the name.

• UINT32 in_ArrayLength:

The length of the storage.

Return values

Runtime error code

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

The name does not fit in the storage.

Table 7- 96 ControllerName { get; } - .NET (C#)

Syntax

string ControllerName { get; }

Parameters

None

Return values

string:

The downloaded name of the virtual controller.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

120 Function Manual, 09/2016, A5E37039512-AA

GetControllerShortDesignation() / ControllerShortDesignation { get; }

Returns the downloaded short designation of the virtual controller.

Table 7- 97 GetControllerShortDesignation() - Native C++

Syntax

ERuntimeErrorCode GetControllerShortDesignation(

WCHAR inout_ShortDesignation[],

UINT32 in_ArrayLength

);

Parameters • WCHAR inout_ShortDesignation[]:

A user-allocated storage for the short designation.

• UINT32 in_ArrayLength:

The length of the storage.

Return values

Runtime error code

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

The name does not fit in the storage.

Table 7- 98 ControllerShortDesignation { get; } - .NET (C#)

Syntax

string ControllerShortDesignation { get; }

Parameters

None

Return values

string:

The downloaded short designation of the virtual controller.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code Condition

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 121

GetControllerIP() / ControllerIP { get; }

Returns a configured IP address of the instance.

Table 7- 100 GetControllerIP() - Native C++

Syntax

UIP GetControllerIP();

UIP GetControllerIP(

UINT32 in_Index

);

Parameters • WCHAR in_Index:

The index of the IP address you want to receive. The index must be less

than the value you receive from GetControllerIPCount(). The default set-

ting 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

fails, the field is empty.

Exceptions

None

GetControllerIPSuite4() / ControllerIPSuite4 { get; }

Returns the IP suite instance. If the "Softbus" communication interface is used, the subnet

mask and default gateway are 0.

Table 7- 102 GetControllerIPSuite4() Native C++

Syntax

SIPSuite4 GetControllerIPSuite4();

SIPSuite4 GetControllerIPSuite4(

UINT32 in_Index

);

Parameters • WCHAR in_Index:

The index of the IP address you want to receive. The index must be less than

the value you receive from GetControllerIPCount(). The default setting is 0.

Return values SIPSuite4: The IP suite of the virtual controller. If the function fails, the return

values are 0.

Table 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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

122 Function Manual, 09/2016, A5E37039512-AA

SetIPSuite()

Sets the IP suite of the network interface of a virtual controller.

Table 7- 104 SetIPSuite() - Native C++

Syntax

ERuntimeErrorCode SetIPSuite(

UINT32 in_InterfaceID,

SIPSuite4 in_IPSuite,

bool in_IsRemanent

);

Parameters • UINT32 in_InterfaceID:

The ID of the network interface.

• SIPSuite4 in_IPSuite:

The IP suite that is to be assigned to the network interface. The IP suite con-

tains 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

The process of the virtual controller is not

running.

SREC_DOES_NOT_EXIST

There is no network interface with this ID.

SREC_INVALID_OPERATING_STATE

The virtual controller has not yet com-

pleted the boot process or is already in

the shutdown phase.

Table 7- 105 SetIPSuite() - .NET (C#)

Syntax

void SetIPSuite(

UInt32 in_InterfaceID,

SIPSuite4 in_IPSuite,

bool in IsRemanent );

Parameters • UInt32 in_InterfaceID:

The ID of the network interface.

• SIPSuite4 in_IPSuite:

If the communication interface is "Softbus", the subnet mask and standard

gateway are ignored.

• bool in_IsRemanent:

If true, the IP suite is saved after restart of the virtual controller.

If the communication interface is "Softbus", this flag is ignored.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 123

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeErrorCode.DoesNotExist

There is no network interface with this ID.

ERuntimeError-

Code.InvalidOperatingState The virtual controller has not yet com-

pleted 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

ERuntimeErrorCode GetStoragePath(

WCHAR inout_StoragePath[],

UINT32 in_ArrayLength

);

Parameters • WCHAR inout_StoragePath[]:

A user-

allocated storage for the storage path. The length of the array should be

at least as long as DSTORAGE_PATH_MAX_LENGTH. See Data types (Page 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

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_INDEX_OUT_OF_RANGE

The path does not fit in the storage.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

124 Function Manual, 09/2016, A5E37039512-AA

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:

<My Documents>>\Siemens\Simatic\Simulation\Runtime\Persistence\<Instance Name> is

used.

Table 7- 107 SetStoragePath() - Native C++

Syntax

ERuntimeErrorCode SetStoragePath(

WCHAR* in_StoragePath

);

Parameters • WCHAR* in_StoragePath:

Full name of the storage path. The length of the name must be less than

DSTORAGE_PATH_MAX_LENGTH. See Data types (Page 257).

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

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:

<My Documents>>\Siemens\Simatic\Simulation\Runtime\Persistence\<Instance Name> is

used.

Table 7- 108 StoragePath { get; set; } - .NET (C#)

Syntax

string StoragePath { get; set; }

Parameters

None

Return values

string: The configured storage path.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.IndexOutOfRange

The length of the path exceeds the limit.

ERuntimeErrorCode.WrongArgument

The path contains invalid characters.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 125

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

ERuntimeErrorCode ArchiveStorage(

WCHAR* in_FullFileName

);

Parameters • WCHAR in_FullFileName:

The full path to the ZIP file.

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_INVALID_OPERATING_STATE

The instance is not in OFF operating

state.

SREC_INVALID_ARCHIVE_PATH

The archive path is invalid.

SREC_CREATE_DIRECTORIES_FAILED

The directory for the ZIP file could not be

created.

SREC_ARCHIVE_STORAGE_FAILED

The ZIP file could not be created.

Table 7- 110 ArchiveStorage() - .NET (C#)

Syntax

void ArchiveStorage(

string in_ArchiveStorageFile

);

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

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InvalidOperatingState The instance is not in OFF operating

state.

ERuntimeError-

Code.InvalidArchivePath

The archive path is invalid.

ERuntimeError-

Code.CreateDirectoriesFailed The directory for the ZIP file could not be

created.

ERuntimeError-

Code.ArchiveStorageNotCreated

The ZIP file could not be created.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

126 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode RetrieveStorage(

WCHAR* in_FullFileName

);

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

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

The old storage cannot be deleted.

SREC_RETRIEVE_STORAGE_FAILURE

The ZIP file cannot be unzipped.

Table 7- 112 RetrieveStorage() - .NET (C#)

Syntax

void RetrieveStorage(

string in_ArchiveStorageFile

);

Parameters • string in_ArchiveStorageFile:

The full path to the ZIP file.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InvalidOperatingState The instance is not in OFF operating

state.

ERuntimeError-

Code.InvalidArchivePath

The archive path is invalid.

ERuntimeError-

Code.DeleteExistingStorageFailed

The old storage cannot be deleted.

ERuntimeError-

Code.RetrieveStorageFailure

The ZIP file cannot be unzipped.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 127

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

ready to start the user program.

• SROS_STOP:

If the virtual controller is in STOP state.

• SROS_STARTUP:

If the user program is currently changing from STOP to RUN.

• SROS_RUN:

If the user program is running.

• SROS_FREEZE:

If the user program is being stopped (Freeze status).

• SROS_SHUTTING_DOWN:

If PowerOff() was called but the virtual controller is still in the Shutdown

phase.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

128 Function Manual, 09/2016, A5E37039512-AA

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 129

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

ERuntimeErrorCode PowerOn();

ERuntimeErrorCode PowerOn(

UINT32 in_Timeout_ms

);

Parameters • UINT32 in_Timeout_ms:

A timeout value in milliseconds.

–

If no timeout value is set, the function returns 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 func-

tion returns when the operation has been completed or after a timeout.

– Expected operating states if this function is successful:

{ SROS_STOP , SROS_RUN }

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The expected operating state does not

occur on time.

SREC_ERROR_LOADING_DLL

The Sie-

mens.Simatic.Simulation.Runtime.Instan

ce.exe cannot load the Sie-

mens.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 start-

ed.

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.

The warning occurs even when you im-

port a license within this hour. The in-

stance is then not shut down.

SREC_VIRTUAL_SWITCH_MISCONFIGURE

D The virtual switch is configured incorrect-

ly.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is no

longer running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

130 Function Manual, 09/2016, A5E37039512-AA

Table 7- 116 PowerOn() - .NET (C#)

Syntax

ERuntimeErrorCode PowerOn();

ERuntimeErrorCode PowerOn(

UInt32 in_Timeout_ms

);

Parameters • UInt32 in_Timeout_ms:

A timeout value in milliseconds.

– If no timeout value is set, the function returns 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 func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ EOperatingState.Run, EOperatingState.Stop }

Return values

Runtime error code

Condition

ERuntimeErrorCode.OK

The function is successful.

ERuntimeError-

Code.WarningAlreadyExists Only one warning. The instance is start-

ed.

ERuntimeError-

Code.WarningTrialModeActive 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 im-

port a license within this hour. The in-

stance is then not shut down.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The expected operating state does not

occur on time.

ERuntimeError-

Code.ErrorLoadingDll The Siemens.Simatic.Simulation.

Runtime.Instance.exe cannot load the

Siemens.Simatic.PlcSim.Vplc1500.dll.

ERuntimeError-

Code.StoragePathAlreadyInUse The selected path for this instance is

already being used by another instance.

ERuntimeError-

Code.NoStoragePathSet The path could not be created. The

length of the

DSTORAGE_PATH_MAX_LENGTH characters

may be exceeded.

ERuntimeError-

Code.VirtualSwitchMisconfigured The virtual switch is configured incorrect-

ly.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is no

longer running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 131

PowerOff()

Shuts down the Simulation Runtime and closes its process.

Table 7- 117 PowerOff() - Native C++

Syntax

ERuntimeErrorCode PowerOff();

ERuntimeErrorCode PowerOff(

UINT32 in_Timeout_ms

);

Parameters

• UINT32 in_Timeout_ms:

A timeout value in milliseconds.

– If no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ SROS_OFF }

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 expected operating state does not

occur on time.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is not

running.

Table 7- 118 PowerOff() - .NET (C#)

Syntax

void PowerOff();

void PowerOff(

UInt32 in_Timeout_ms

);

Parameters • UInt32 in_Timeout_ms:

A timeout value in milliseconds.

–

If no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ EOperatingState.Off }

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The expected operating state does not

occur on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

132 Function Manual, 09/2016, A5E37039512-AA

MemoryReset()

Shuts down the virtual controller, closes its processes and performs a restart.

Table 7- 119 MemoryReset() - Native C++

Syntax

ERuntimeErrorCode MemoryReset();

ERuntimeErrorCode MemoryReset(

UINT32 in_Timeout_ms

);

Parameters

• UINT32 in_Timeout_ms:

A timeout value in milliseconds.

–

If no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ SROS_STOP , SROS_RUN }

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 expected operating state does not

occur on time.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is not

running.

Table 7- 120 MemoryReset() - .NET (C#)

Syntax

void MemoryReset();

void MemoryReset(

UInt32 in_Timeout_ms

);

Parameters • UInt32 in_Timeout_ms:

A timeout value in milliseconds.

–

If no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ EOperatingState.Run, EOperatingState.Stop }

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The expected operating state does not

occur on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 133

Run()

Calls on the virtual controller to change to RUN operating state.

Table 7- 121 Run() - Native C++

Syntax

ERuntimeErrorCode Run();

ERuntimeErrorCode Run(

UINT32 in_Timeout_ms

);

Parameters

• UINT32 in_Timeout_ms:

A timeout value in milliseconds.

–

If no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ SROS_STOP , SROS_RUN }

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 expected operating state does not

occur on time.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is not

running.

Table 7- 122 Run() - .NET (C#)

Syntax

void Run();

void Run(

Uint32 in_Timeout_ms

);

Parameters • UInt32 in_Timeout_ms:

A timeout value in milliseconds.

– If

no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ EOperatingState.Run }

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The expected operating state does not

occur on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

134 Function Manual, 09/2016, A5E37039512-AA

Stop()

Calls on the virtual controller to change to STOP operating state.

Table 7- 123 Stop() - Native C++

Syntax

ERuntimeErrorCode Stop();

ERuntimeErrorCode Stop(

UINT32 in_Timeout_ms

);

Parameters • UINT32 in_Timeout_ms:

A timeout value in milliseconds.

–

If no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ SROS_STOP }

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 expected operating state does not

occur on time.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is not

running.

Table 7- 124 Stop() - .NET (C#)

Syntax

void Stop();

void Stop(

bool in_IsSynchronous

);

Parameters • UInt32 in_Timeout_ms:

A timeout value in milliseconds.

–

If no timeout value is set, the function returns immediately. Subscribe to the

OnOperatingStateChanged() event to find out when the operation has

been completed.

– If the value is greater than 0 (a value of 60000 is recommended), the func-

tion returns when the operation has been completed or after a timeout.

Expected operating states when this function is successful:

{ EOperatingState.Stop }

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The expected operating state does not

occur on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 135

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

136 Function Manual, 09/2016, A5E37039512-AA

Table 7- 125 UpdateTagList() - Native C++

Syntax

ERuntimeErrorCode UpdateTagList();

ERuntimeErrorCode UpdateTagList(

ETagListDetails in_TagListDetails

);

ERuntimeErrorCode UpdateTagList(

ETagListDetails in_TagListDetails,

bool in_IsHMIVisibleOnly

);

Parameters • ETagListDetails in_TagListDetails:

Every combination of the following four areas:

: Inputs and Outputs

: Bit memory

: Counters and Timers

: 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

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is not

running.

SREC_NOT_ENOUGH_MEMORY

More than 500000 entries are requested.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 137

Table 7- 126 UpdateTagList() - .NET (C#)

Syntax

void UpdateTagList();

void UpdateTagList(

ETagListDetails in_TagListDetails

);

void UpdateTagList(

ETagListDetails in_TagListDetails,

bool in_IsHMIVisibleOnly

);

Parameters • ETagListDetails in_TagListDetails:

Every combination of the following four areas:

: Inputs and Outputs

: Bit memory

: Counters and Timers

: 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

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.NotEnoughMemory

More than 500000 entries are requested.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

138 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode GetTagListStatus(

ETagListDetails* out_TagListDetails,

bool* out_IsHMIVisibleOnly

);

Parameters • ETagListDetails out_TagListDetails:

Status of the tag list details. SRTLD_NONE when an update of the list is required.

• bool out_IsHMIVisibleOnly:

If true, only tags marked with "HMI Visible" are available in the list.

Return values

Runtime error code

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

void GetTagListStatus(

out ETagListDetails out_TagListDetails,

out bool out_IsHMIVisibleOnly

);

Parameters • out ETagListDetails out_TagListDetails:

Status of the tag list details. ETagListDetails.None when an update of the list

is required.

• out bool out_IsHMIVisibleOnly:

If true, only tags marked with "HMI Visible" are available in the list.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 139

GetTagInfos() / TagInfos { get; }

Returns a list of all tags.

Table 7- 130 GetTagInfos() - Native C++

Syntax

ERuntimeErrorCode GetTagInfos(

UINT32 in_BufferLength,

STagInfo* inout_TagInfos,

UINT32* out_TagCount

);

Parameters • UINT32 in_BufferLength:

The number of elements that the storage can accommodate.

• STagInfo* inout_TagInfos:

The user-allocated storage that accommodates the tags.

• UINT32* out_TagCount:

Returns the number of tags that were written to the storage.

Return values

Runtime error code

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_INDEX_OUT_OF_RANGE

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

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

140 Function Manual, 09/2016, A5E37039512-AA

CreateConfigurationFile()

Writes all entries from the tag list to an XML file.

Table 7- 132 CreateConfigurationFile() - Native C++

Syntax

ERuntimeErrorCode CreateConfigurationFile(

WCHAR* in_FullFileName

);

Parameters • WCHAR* in_FullFileName:

Full file name of the XML file:

<Path> + <File name> + <File extension>.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The file name is invalid.

Table 7- 133 CreateConfigurationFile() - .NET (C#)

Syntax

void CreateConfigurationFile(

string in_FullFileName

);

Parameters

None

Return values • string in_FullFileName:

File name of the XML file that is to be written to:

<Path> + <File name> + <File extension>.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 141

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

IIOArea InputArea { get; }

IIOArea MarkerArea { get; }

IIOArea OutputArea { get; }

Parameters

None

Return values

IIOArea:

The interface is used to call the "I/O access via address" functions.

GetAreaSize() / AreaSize { get; }

Returns the size of the area in bytes.

Table 7- 135 GetAreaSize() - Native C++

Syntax

UINT32 GetAreaSize(

EArea in_Area

);

Parameters • EArea in_Area:

The area whose size you want to receive. Permissible values:

{SRA_INPUT, SRA_MARKER, SRA_OUTPUT}. See EArea (Page 286).

Return values 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

UInt32 InputArea.AreaSize { get; }

UInt32 MarkerArea.AreaSize { get; }

UInt32 OutputArea.AreaSize { get; }

Parameters

None

Return values Uint32: Size of the area in bytes. If the function was successful, the value is

not equal to 0.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

142 Function Manual, 09/2016, A5E37039512-AA

ReadBit()

Reads an individual bit from the area.

Note

The function allows access to the e

ntire 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

ERuntimeErrorCode ReadBit(

EArea in_Area,

UINT32 in_Offset,

UINT8 in_Bit,

bool* out_Value

);

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

The process of the virtual controller is not

running.

SREC_INDEX_OUT_OF_RANGE

Offset or bits are invaid.

SREC_WRONG_ARGUMENT

The area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 143

Table 7- 138 ReadBit() - .NET (C#)

Syntax

bool InputArea.ReadBit(

UInt32 in_Offset,

Byte in_Bit

);

bool MarkerArea.ReadBit(

UInt32 in_Offset,

Byte in_Bit

);

bool OutputArea.ReadBit(

UInt32 in_Offset,

Byte in_Bit

);

Parameters • UInt32 in_Offset:

The byte offset within the area. The value must be between 0 and the value

that AreaSize returns.

• Byte in_Bit:

The bit offset within the byte. The value must be between 0 and 7.

Return values

bool: Bit value

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange

Offset or bits are invaid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

144 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode ReadByte(

EArea in_Area,

UINT32 in_Offset,

BYTE* out Value);

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

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_INDEX_OUT_OF_RANGE

Offset is invalid.

SREC_WRONG_ARGUMENT

The area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 145

Table 7- 140 ReadByte() - .NET (C#)

Syntax

Byte InputArea.ReadByte(

UInt32 in_Offset

);

Byte MarkerArea.ReadByte(

UInt32 in_Offset

);

Byte OutputArea.ReadByte(

UInt32 in_Offset

);

Parameters • UInt32 in_Offset:

The byte offset within the area. The value must be between 0 and the value

that AreaSize returns.

Return values

Byte: Byte value.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange

Offset is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

146 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode ReadBytes(

EArea in_Area,

UINT32 in_Offset,

UINT32 in_BytesToRead,

UINT32* out_BytesRead,

BYTE inout_Values[]

);

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

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is not

running.

SREC_INDEX_OUT_OF_RANGE

The offset is outside the area size. No

byte could be read.

SREC_WRONG_ARGUMENT

The area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 147

Table 7- 142 ReadBytes() - .NET (C#)

Syntax

Byte[] InputArea.ReadBytes(

UInt32 in_Offset,

UInt32 in_BytesToRead

);

Byte[] MarkerArea.ReadBytes(

UInt32 in_Offset,

UInt32 in_BytesToRead

);

Byte[] OutputArea.ReadBytes(

UInt32 in_Offset,

UInt32 in_BytesToRead

);

Parameters • UInt32 in_Offset:

The byte offset within the area. The value must be between 0 and the value

that AreaSize returns.

• UInt32 in_BytesToRead:

The number of bytes to be read.

Return values

Byte[]: The read bytes.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange The offset is outside the area size. No

byte could be read.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

148 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode ReadSignals(

EArea in_Area,

SDataValueByAddress* inout_Signals,

UINT32 in_SignalCount

);

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

The process of the virtual controller is not

running.

SREC_INDEX_OUT_OF_RANGE

Offset or bits are invaid.

SREC_WRONG_ARGUMENT

The area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 149

Table 7- 144 ReadSignals() - .NET (C#)

Syntax

void ReadSignals(

ref SDataValueByAddress[] inout_Signals

);

Parameters • ref SDataValueByAddress[] inout_Signals:

The signal list to be read.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange

Offset or bits are invaid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

150 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode WriteBit(

EArea in_Area,

UINT32 in_Offset,

UINT8 in_Bit,

bool in_Value

);

Parameters • EArea in_Area:

The area that is to be written.

Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.

See EArea (Page 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

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_INDEX_OUT_OF_RANGE

Offset or bits are invaid.

SREC_WRONG_ARGUMENT

Area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 151

Table 7- 146 WriteBit() - .NET (C#)

Syntax

void InputArea WriteBit(

UInt32 in_Offset,

Byte in_Bit,

bool in_Value

);

void MarkerArea WriteBit(

UInt32 in_Offset,

Byte in_Bit,

bool in_Value

);

void OutputArea WriteBit(

UInt32 in_Offset,

Byte in_Bit,

bool in_Value

);

Parameters • UInt32 in_Offset:

The byte offset within the area. The value must be between 0 and the value

that AreaSize returns.

• Byte in_Bit:

The bit offset within the byte. The value must be between 0 and 7.

• bool in_Value:

Bit value.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange

Offset or bits are invaid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

152 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode WriteByte(

EArea in_Area,

UINT32 in_Offset,

BYTE in Value);

Parameters • EArea in_Area:

The area that is to be written.

Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.

See EArea (Page 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

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_INDEX_OUT_OF_RANGE

Offset is invalid.

SREC_WRONG_ARGUMENT

Area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 153

Table 7- 148 WriteByte() - .NET (C#)

Syntax

void InputArea.WriteByte(

UInt32 in_Offset,

Byte in_Value

);

void MarkerArea.WriteByte(

UInt32 in_Offset,

Byte in_Value

);

void OutputArea.WriteByte(

UInt32 in_Offset,

Byte in_Value

);

Parameters • UINT32 in_Offset:

The byte offset within the area. The value must be between 0 and the value

that AreaSize returns.

• BYTE in_Value:

Byte value.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange

Offset is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

154 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode WriteBytes(

EArea in_Area,

UINT32 in_Offset,

UINT32 in_BytesToWrite,

UINT32* out_BytesWritten,

BYTE in_Values[])

;

Parameters • EArea in_Area:

The area that is to be written.

Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.

See EArea (Page 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

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_INSTANCE_NOT_RUNNING

The process of the virtual controller is not

running.

SREC_INDEX_OUT_OF_RANGE

The offset is outside the area size. No

byte could be written.

SREC_WRONG_ARGUMENT

The area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 155

Table 7- 150 WriteBytes() - .NET (C#)

Syntax

UInt32 InputArea.WriteBytes(

UInt32 in_Offset,

Byte[] in_Values

);

UInt32 InputArea.WriteBytes(

UInt32 in_Offset,

UInt32 in_BytesToWrite,

Byte[] in_Values

);

UInt32 MarkerArea.WriteBytes(

UInt32 in_Offset,

Byte[] in_Values

);

UInt32 MarkerArea.WriteBytes(

UInt32 in_Offset,

UInt32 in_BytesToWrite,

Byte[] in_Values

);

UInt32 OutputArea.WriteBytes(

UInt32 in_Offset,

Byte[] in_Values

);

UInt32 OutputArea.WriteBytes(

UInt32 in_Offset,

UInt32 in_BytesToWrite,

Byte[] in_Values

);

Parameters • UINT32 in_Offset:

The byte offset within the area. The value must be between 0 and the value

that AreaSize returns.

• UInt32 in_BytesToWrite:

Contains the number of bytes to be written. The value must be between 1 and

the size of the array value.

• BYTE in_Value:

Byte value.

Return values

Uint32: Contains the number of bytes that were just written.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange The offset is outside the area size. No

byte could be written.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

156 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode WriteSignals(

EArea in_Area,

SDataValueByAddress* in_Signals,

UINT32 in_SignalCount

);

Parameters • EArea in_Area:

The area that is to be written.

Permissible values: {SRA_INPUT, SRA_MARKER, SRA_OUTPUT}.

See EArea (Page 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

The process of the virtual controller is not

running.

SREC_INDEX_OUT_OF_RANGE

Offset or bits are invaid.

SREC_WRONG_ARGUMENT

The area is invalid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 157

Table 7- 152 WriteSignals() - .NET (C#)

Syntax

void InputArea.WriteSignals(

SDataValueByAddress[] in_Signals

);

void MarkerArea.WriteSignals(

SDataValueByAddress[] in_Signals

);

void OutputArea.WriteSignals(

SDataValueByAddress[] in_Signals

);

Parameters • SDataValueByAddress[] in_Signals:

The signal list to be written.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeError-

Code.IndexOutOfRange

Offset or bits are invaid.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

158 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode Read(

WCHAR* in_Tag,

SDataValue* inout_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• SDataValue* inout_Value:

Contains the value and the expected type of the PLC tag. If the expected type

is UNSPECIFIC, it is set to the stored type when the function was successful.

The STRUCT type is not supported. Structures and arrays can be read altogeth-

er with ReadSignals().

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 159

Table 7- 154 Read() - .NET (C#)

Syntax

SDataValue Read(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

SDataValue: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

160 Function Manual, 09/2016, A5E37039512-AA

ReadBool()

Reads the value of a PLC tag.

Table 7- 155 ReadBool() - Native C++

Syntax

ERuntimeErrorCode ReadBool(

WCHAR* in_Tag,

bool* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• bool* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 161

Table 7- 156 ReadBool() - .NET (C#)

Syntax

bool ReadBool(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

bool: Contains the value of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

162 Function Manual, 09/2016, A5E37039512-AA

ReadInt8()

Reads the value of a PLC tag.

Table 7- 157 ReadInt8() - Native C++

Syntax

ERuntimeErrorCode ReadInt8(

WCHAR* in_Tag,

INT8* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• INT8* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 163

Table 7- 158 ReadInt8() - .NET (C#)

Syntax

Int8 ReadInt8(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

Int8: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

164 Function Manual, 09/2016, A5E37039512-AA

ReadInt16()

Reads the value of a PLC tag.

Table 7- 159 ReadInt16() - Native C++

Syntax

ERuntimeErrorCode ReadInt16(

WCHAR* in_Tag,

INT16* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• INT16* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 165

Table 7- 160 ReadInt16() - .NET (C#)

Syntax

Int16 ReadInt16(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

Int16: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

166 Function Manual, 09/2016, A5E37039512-AA

ReadInt32()

Reads the value of a PLC tag.

Table 7- 161 ReadInt32() - Native C++

Syntax

ERuntimeErrorCode ReadInt32(

WCHAR* in_Tag,

INT32* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• INT32* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 167

Table 7- 162 ReadInt32() - .NET (C#)

Syntax

Int32 ReadInt32(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

Int32: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

168 Function Manual, 09/2016, A5E37039512-AA

ReadInt64()

Reads the value of a PLC tag.

Table 7- 163 ReadInt64() - Native C++

Syntax

ERuntimeErrorCode ReadInt64(

WCHAR* in_Tag,

INT64* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• INT64* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 169

Table 7- 164 ReadInt64() - .NET (C#)

Syntax

Int64 ReadInt64(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

Int64: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

170 Function Manual, 09/2016, A5E37039512-AA

ReadUInt8()

Reads the value of a PLC tag.

Table 7- 165 ReadUInt8() - Native C++

Syntax

ERuntimeErrorCode ReadUInt8(

WCHAR* in_Tag,

UINT8* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• UINT8* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 171

Table 7- 166 ReadUInt8() - .NET (C#)

Syntax

UInt8 ReadUInt8(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

UInt8: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

172 Function Manual, 09/2016, A5E37039512-AA

ReadUInt16()

Reads the value of a PLC tag.

Table 7- 167 ReadUInt16() - Native C++

Syntax

ERuntimeErrorCode ReadUInt16(

WCHAR* in_Tag,

UINT16* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• UINT16* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 173

Table 7- 168 ReadUInt16() - .NET (C#)

Syntax

UInt16 ReadUInt16(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

UInt16: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

174 Function Manual, 09/2016, A5E37039512-AA

ReadUInt32()

Reads the value of a PLC tag.

Table 7- 169 ReadUInt32() - Native C++

Syntax

ERuntimeErrorCode ReadUInt32(

WCHAR* in_Tag,

UINT32* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• UINT32* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 175

Table 7- 170 ReadUInt32() - .NET (C#)

Syntax

UInt32 ReadUInt32(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

Uint32: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

176 Function Manual, 09/2016, A5E37039512-AA

ReadUInt64()

Reads the value of a PLC tag.

Table 7- 171 ReadInt64() - Native C++

Syntax

ERuntimeErrorCode ReadUInt64(

WCHAR* in_Tag,

UINT64* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• UINT64* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 177

Table 7- 172 ReadUInt64() - .NET (C#)

Syntax

UInt64 ReadUInt64(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

UInt64: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

178 Function Manual, 09/2016, A5E37039512-AA

ReadFloat()

Reads the value of a PLC tag.

Table 7- 173 ReadFloat() - Native C++

Syntax

ERuntimeErrorCode ReadFloat(

WCHAR* in_Tag,

float* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• float* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 179

Table 7- 174 ReadFloat() - .NET (C#)

Syntax

float ReadFloat(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

float: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

180 Function Manual, 09/2016, A5E37039512-AA

ReadDouble()

Reads the value of a PLC tag.

Table 7- 175 ReadDouble() - Native C++

Syntax

ERuntimeErrorCode ReadDouble(

WCHAR* in_Tag,

double* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• double* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 181

Table 7- 176 ReadDouble() - .NET (C#)

Syntax

double ReadDouble(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

double: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

182 Function Manual, 09/2016, A5E37039512-AA

ReadChar()

Reads the value of a PLC tag.

Table 7- 177 ReadChar() - Native C++

Syntax

ERuntimeErrorCode ReadChar(

WCHAR* in_Tag,

char* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• char* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 183

Table 7- 178 ReadChar() - .NET (C#)

Syntax

sbyte ReadChar(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

sbyte: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

184 Function Manual, 09/2016, A5E37039512-AA

ReadWChar()

Reads the value of a PLC tag.

Table 7- 179 ReadWChar() - Native C++

Syntax

ERuntimeErrorCode ReadWChar(

WCHAR* in_Tag,

WCHAR* out_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be read.

• WCHAR* out_Value:

Contains the value of the PLC tag.

Return values

Runtime error code

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 185

Table 7- 180 ReadWChar() - .NET (C#)

Syntax

char ReadWChar(

string in_Tag

)

Parameters • string in_Tag:

The name of the PLC tag that is to be read.

Return values

char: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

186 Function Manual, 09/2016, A5E37039512-AA

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

pected 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

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 187

Table 7- 182 ReadSignals() - .NET (C#)

Syntax

void ReadSignals(

ref SDataValueByName[] inout_Signals

)

Parameters • ref SDataValueByName[] inout_Signals:

Contains the name, the value and the expected type of the PLC tag. If the ex-

pected type is UNSPECIFIC, it is set to the stored type when the function was

successful. The STRUCT type is not supported.

Return values

SDataValue: Contains the value and the type of the PLC tag.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

188 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode Write(

WCHAR* in_Tag,

SDataValue* in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• SDataValue* in_Value:

Contains the value and the expected type of the PLC tag.

The UNSPECIFIC and STRUCT types are not supported. Structures and arrays

can be written altogether with WriteSignals().

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.

SREC_WRONG_ARGUMENT

The expected type is UNSPECIFIC.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 189

Table 7- 184 Write() - .NET (C#)

Syntax

void Write(

string in_Tag

SDataValue in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• SDataValue in_Value:

Contains the value and the expected type of the PLC tag.

The UNSPECIFIC and STRUCT types are not supported.

Structures and arrays

can be written altogether with WriteSignals().

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

ERuntimeErrorCode.WrongArgument

The expected type is UNSPECIFIC.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

190 Function Manual, 09/2016, A5E37039512-AA

WriteBool()

Writes the value of a PLC tag.

Table 7- 185 WriteBool() - Native C++

Syntax

ERuntimeErrorCode WriteBool(

WCHAR* in_Tag,

bool in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• bool in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 191

Table 7- 186 WriteBool() - .NET (C#)

Syntax

void WriteBool(

string in_Tag

bool in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• bool in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

192 Function Manual, 09/2016, A5E37039512-AA

WriteInt8()

Writes the value of a PLC tag.

Table 7- 187 WriteInt8() - Native C++

Syntax

ERuntimeErrorCode WriteInt8(

WCHAR* in_Tag,

INT8 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• INT8 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 193

Table 7- 188 WriteInt8() - .NET (C#)

Syntax

void WriteInt8(

string in_Tag

Int8 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• Int8 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

194 Function Manual, 09/2016, A5E37039512-AA

WriteInt16()

Writes the value of a PLC tag.

Table 7- 189 WriteInt16() - Native C++

Syntax

ERuntimeErrorCode WriteInt16(

WCHAR* in_Tag,

INT16 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• INT16 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 195

Table 7- 190 WriteInt16() - .NET (C#)

Syntax

void WriteInt16(

string in_Tag

Int16 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• Int16 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

196 Function Manual, 09/2016, A5E37039512-AA

WriteInt32()

Writes the value of a PLC tag.

Table 7- 191 WriteInt32() - Native C++

Syntax

ERuntimeErrorCode WriteInt32(

WCHAR* in_Tag,

INT32 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• INT32 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 197

Table 7- 192 WriteInt32() - .NET (C#)

Syntax

void WriteInt32(

string in_Tag

Int32 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• Int32 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

198 Function Manual, 09/2016, A5E37039512-AA

WriteInt64()

Writes the value of a PLC tag.

Table 7- 193 WriteInt64() - Native C++

Syntax

ERuntimeErrorCode WriteInt64(

WCHAR* in_Tag,

INT64 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• INT64 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 199

Table 7- 194 WriteInt64() - .NET (C#)

Syntax

void WriteInt64(

string in_Tag

Int64 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• Int64 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

200 Function Manual, 09/2016, A5E37039512-AA

WriteInt8()

Writes the value of a PLC tag.

Table 7- 195 WriteUInt8() - Native C++

Syntax

ERuntimeErrorCode WriteUInt8(

WCHAR* in_Tag,

UINT8 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• UINT8 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 201

Table 7- 196 WriteUInt8() - .NET (C#)

Syntax

void WriteUInt8(

string in_Tag

UInt8 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• UInt8 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

202 Function Manual, 09/2016, A5E37039512-AA

WriteUInt16()

Reads the value of a PLC tag.

Table 7- 197 WriteUInt16() - Native C++

Syntax

ERuntimeErrorCode WriteUInt16(

WCHAR* in_Tag,

UINT16 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• UINT16 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 203

Table 7- 198 WriteUInt16() - .NET (C#)

Syntax

void WriteUInt16(

string in_Tag

UInt16 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• UInt16 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

204 Function Manual, 09/2016, A5E37039512-AA

WriteUInt32()

Writes the value of a PLC tag.

Table 7- 199 WriteUInt32() - Native C++

Syntax

ERuntimeErrorCode WriteUInt32(

WCHAR* in_Tag,

UINT32 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• UINT32 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 205

Table 7- 200 WriteUInt32() - .NET (C#)

Syntax

void WriteUInt32(

string in_Tag

UInt32 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• UInt32 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

206 Function Manual, 09/2016, A5E37039512-AA

WriteUInt64()

Writes the value of a PLC tag.

Table 7- 201 WriteUInt64() - Native C++

Syntax

ERuntimeErrorCode WriteUInt64(

WCHAR* in_Tag,

UINT64 in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• UINT64 in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 207

Table 7- 202 WriteUInt64() - .NET (C#)

Syntax

void WriteUInt64(

string in_Tag

UInt64 in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• UInt64 in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

208 Function Manual, 09/2016, A5E37039512-AA

WriteFloat()

Writes the value of a PLC tag.

Table 7- 203 WriteFloat() - Native C++

Syntax

ERuntimeErrorCode WriteFloat(

WCHAR* in_Tag,

float in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• float in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 209

Table 7- 204 WriteFloat() - .NET (C#)

Syntax

void WriteFloat(

string in_Tag

float in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• float in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

210 Function Manual, 09/2016, A5E37039512-AA

WriteDouble()

Writes the value of a PLC tag.

Table 7- 205 WriteDouble() - Native C++

Syntax

ERuntimeErrorCode WriteDouble(

WCHAR* in_Tag,

double in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• double in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 211

Table 7- 206 WriteDouble() - .NET (C#)

Syntax

void WriteDouble(

string in_Tag

double in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• double in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

212 Function Manual, 09/2016, A5E37039512-AA

WriteChar()

Writes the value of a PLC tag.

Table 7- 207 WriteChar() - Native C++

Syntax

ERuntimeErrorCode WriteChar(

WCHAR* in_Tag,

char in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• char in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 213

Table 7- 208 WriteChar() - .NET (C#)

Syntax

void WriteChar(

string in_Tag

sbyte in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• sbyte in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

214 Function Manual, 09/2016, A5E37039512-AA

WriteWChar()

Writes the value of a PLC tag.

Table 7- 209 WriteWChar() - Native C++

Syntax

ERuntimeErrorCode WriteWChar(

WCHAR* in_Tag,

WCHAR in_Value

);

Parameters • WCHAR* in_Tag:

The name of the PLC tag that is to be written.

• WCHAR in_Value:

Contains the value of the PLC tag.

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 215

Table 7- 210 WriteWChar() - .NET (C#)

Syntax

void WriteWChar(

string in_Tag

char in_Value

)

Parameters • string in_Tag:

The name of the PLC tag that is to be written.

• char in_Value:

Contains the value of the PLC tag.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

216 Function Manual, 09/2016, A5E37039512-AA

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

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.

SREC_WRONG_ARGUMENT

The expected type is UNSPECIFIC.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 217

Table 7- 212 WriteSignals() - .NET (C#)

Syntax

void WriteSignals(

SDataValueByName[] in_Signals

)

Parameters • SDataValueByName:

Contains the name, the value and the expected type of the PLC tag. The

UNSPECIFIC and STRUCT types are not supported.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

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

ERuntimeErrorCode.WrongArgument

The expected type is UNSPECIFIC.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

218 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode SetSystemTime(

SYSTEMTIME in_SystemTime

);

Parameters • SYSTEMTIME in_SystemTime:

System time that is to be set for the virtual controller.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The value is outside the limits.

SystemTime { get; set; }

Sets or returns the virtual system time of the virtual controller. A system time between

"Jan 1 1970 00:00:00:000" and "Dec 31 2200 23:59:59:999" is valid.

Table 7- 215 SystemTime { get; set; } - .NET (C#)

Syntax

DateTime SystemTime { get; set; }

Parameters

None

Return values

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The value is outside the limits.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 219

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

ERuntimeErrorCode SetScaleFactor (

double in_Value

);

Parameters • double in_Value:

Scaling factor of the virtual time.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The value is outside the limits.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

220 Function Manual, 09/2016, A5E37039512-AA

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.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The value is outside the limits.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 221

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 • EOperatingMode in_OperatingMode:

Operating mode of the virtual controller

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

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

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

222 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode SetAlwaysSendOnEndOfCycleEnabled(

bool in_Enable

);

Parameters • bool in_Enable:

If true, the OnEndOfCycle event is triggered after every cycle.

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.

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 • false: The event is not triggered (unless the Sync-Freeze mode is active).

•

true:

The event is triggered after every cycle.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 223

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 • INT64 in_CycleTime_ns:

The overwritten minimum cycle time in nanoseconds.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The instance is not registered in Runtime

Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The value is outside the limits.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

224 Function Manual, 09/2016, A5E37039512-AA

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.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The value is outside the limits.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 225

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

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.

Table 7- 229 RunNextCycle() - .NET (C#)

Syntax

void RunNextCycle();

Parameters

None

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

226 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode StartProcessing(

INT64 in_MinimalTimeToRun_ns

);

Parameters • INT64 in_CycleTime_ns:

The minimum virtual time (in nanoseconds) that the virtual controller runs be-

fore it changes to Freeze state.

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_WRONG_ARGUMENT

The value is less than 0.

Table 7- 231 StartProcessing() - .NET (C#)

Syntax

void StartProcessing(

Int64 in_MinimalTimeToRun_ns

);

Parameters • Int64 in_CycleTime_ns:

The minimum virtual time (in nanoseconds) that the virtual controller runs be-

fore it changes to Freeze state.

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The instance is not registered in Runtime

Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeError-

Code.InstanceNotRunning The process of the virtual controller is not

running.

ERuntimeErrorCode.WrongArgument

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)

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 227

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

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

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

OnLedChanged (Page 239) This event is triggered when the LED display of the virtual controller

has changed.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

228 Function Manual, 09/2016, A5E37039512-AA

7.6.8.1

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

void RegisterOnOperatingStateChangedCallback(

EventCallback_II_SREC_ST_SROS_SROS in_CallbackFunction

);

Parameters • EventCallback_II_SREC_ST_SROS_SROS in_CallbackFunction:

A callback function that subscribes to the event.

See EventCallback_II_SREC_ST_SROS_SROS (Page 260).

Return values None

Note

The callback function runs in a separate thread.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 229

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

void RegisterOnOperatingStateChangedEvent();

void RegisterOnOperatingStateChangedEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event object is registered.

• HANDLE* in_Event:

A handle for a user-specific event object. The event object is registered.

Return values

None

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

…

}

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

230 Function Manual, 09/2016, A5E37039512-AA

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 231

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

bool WaitForOnOperatingStateChangedEvent();

bool WaitForOnOperatingStateChangedEvent(

UINT32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

Table 7- 240 WaitForOnOperatingStateChangedEvent() - .NET (C#)

Syntax

bool WaitForOnOperatingStateChangedEvent();

bool WaitForOnOperatingStateChangedEvent(

UInt32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

232 Function Manual, 09/2016, A5E37039512-AA

7.6.8.2

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

void RegisterOnEndOfCycleCallback(

EventCallback_II_SREC_ST in_CallbackFunction

);

Parameters • EventCallback_II_SREC_ST in_CallbackFunction:

A callback function that subscribes to an event.

See EventCallback_II_SREC_ST (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

void RegisterOnEndOfCycleEvent();

void RegisterOnEndOfCycleEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event object is registered.

• HANDLE* in_Event:

A handle for a user-specific event object. The event object is registered.

Return values

None

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 233

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

234 Function Manual, 09/2016, A5E37039512-AA

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

bool WaitForOnEndOfCycleEvent();

bool WaitForOnEndOfCycleEvent(

UINT32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

Table 7- 248 WaitForOnEndOfCycleEvent() - .NET (C#)

Syntax

bool WaitForOnEndOfCycleEvent();

bool WaitForOnEndOfCycleEvent(

UInt32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

7.6.8.3

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 235

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

void RegisterOnConfigurationChangingCallback(

EventCallback_II_SREC_ST in_CallbackFunction

);

Parameters • EventCallback_II_SREC_ST in_CallbackFunction:

A callback function that subscribes to an event.

See EventCallback_II_SREC_ST (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

void RegisterOnConfigurationChangingEvent();

void RegisterOnConfigurationChangingEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event object is registered.

• HANDLE* in_Event:

A handle for a user-specific event object. The event object is registered.

Return values

None

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

236 Function Manual, 09/2016, A5E37039512-AA

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

bool WaitForOnConfigurationChangingEvent();

bool WaitForOnConfigurationChangingEvent(

UINT32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

Table 7- 256 WaitForOnConfigurationChangingEvent() - .NET (C#)

Syntax

bool WaitForOnConfigurationChangingEvent();

bool WaitForOnConfigurationChangingEvent(

UInt32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 237

7.6.8.4

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

figurationChanged;

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

void RegisterOnConfigurationChangedCallback(

EventCallback_SRCC_UINT32_UINT32_INT32 in_CallbackFunction

);

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

void RegisterOnConfigurationChangedEvent();

void RegisterOnConfigurationChangedEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event object is registered.

• HANDLE* in_Event:

A handle for a user-specific event object. The event object is registered.

Return values

None

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

238 Function Manual, 09/2016, A5E37039512-AA

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 239

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

bool WaitForOnConfigurationChangedEvent();

bool WaitForOnConfigurationChangedEvent(

UINT32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

Table 7- 264 WaitForOnConfigurationChangedEvent() - .NET (C#)

Syntax

bool WaitForOnConfigurationChangedEvent();

bool WaitForOnConfigurationChangedEvent(

UInt32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

7.6.8.5

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.

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

240 Function Manual, 09/2016, A5E37039512-AA

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

void RegisterOnLedChangedCallback(

EventCallback_II_SREC_ST_SRLT_SRLM in_CallbackFunction

);

Parameters • EventCallback_II_SREC_ST_SRLT_SRLM in_CallbackFunction:

A callback function that subscribes to an event.

See EventCallback_II_SREC_ST_SRLT_SRLM (Page 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

void RegisterOnLedChangedEvent();

void RegisterOnLedChangedEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event object is registered.

• HANDLE* in_Event:

A handle for a user-specific event object. The event object is registered.

Return values

None

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

User interfaces (API)

7.6 API IInstances

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 241

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

bool WaitForOnLedChangedEvent();

bool WaitForOnLedChangedEvent(

UINT32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

Table 7- 272 WaitForOnLedChangedEvent() - .NET (C#)

Syntax

bool WaitForOnLedChangedEvent();

bool WaitForOnLedChangedEvent(

UInt32 in_Time_ms

);

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

242 Function Manual, 09/2016, A5E37039512-AA

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)

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 243

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.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

244 Function Manual, 09/2016, A5E37039512-AA

GetRemoteComputerName() / RemoteComputerName { get; }

Returns the name of the PC on which the remote Runtime Manager is running.

Table 7- 280 GetRemoteComputerName() - Native C++

Syntax

ERuntimeErrorCode GetRemoteComputerName(

WCHAR* inout_Name,

UINT32 in_ArrayLength

);

Parameters • WCHAR* inout_Name:

A user-allocated array for the computer name.

• UINT32 in_ArrayLength:

The array length. The array should be longer than MAX_COMPUTERNAME_LENGTH.

Return values

Runtime error code

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.

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The interface is disconnected from the

remote Runtime Manager.

ERuntimeError-

Code.IndexOutOfRange The array is too small to accommodate

the computer name.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 245

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

The interface is disconnected from the

remote Runtime Manager.

SREC_TIMEOUT

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

ERuntimeError-

Code.InterfaceRemoved The interface is disconnected from the

remote Runtime Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

246 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode GetRegisteredInstanceInfoAt(

UINT32 in_Index,

SInstanceInfo* out_InstanceInfo

);

Parameters • UINT32 in_Index:

Index of the created instance from which you want to receive the information.

The index must be less than the value you receive when you call GetRegis-

teredInstanceCount().

• SInstanceInfo* out_InstanceInfo:

The information with name and ID of the instance. See SInstanceInfo

(Page 278).

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The interface is disconnected from the

remote Runtime Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_INDEX OUT_OF_RANGE

There is no instance information for this

index.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 247

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

SInstanceInfo[] RegisteredInstanceInfo { get; }

Parameters

None

Return values

None

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The interface is disconnected from the

remote Runtime Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

248 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode RegisterInstance(

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterInstance(

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterInstance(

ECPUType in_CPUType,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterInstance(

ECPUType in_CPUType,

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

Parameters • ECPUType in_CPUType:

Defines which CPU type is simulated at the start of the instance. The default

setting is "SRCT_1500_Unspecified".

When a different CPU type is loaded via STEP 7 or from the Virtual 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).

• IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer

must

be initial-

ized with NULL. The interface is created within the function.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The interface is disconnected from the

remote Runtime Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The name or the IInstance pointer is

invalid.

SREC_LIMIT_REACHED

There are already 16 instances regis-

tered in Runtime Manager.

SREC_ALREADY_EXISTS

An instance with this name already ex-

ists.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 249

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

IInstance RegisterInstance();

IInstance RegisterInstance(

string in_InstanceName

);

IInstance RegisterInstance(

ECPUType in_CPUType

);

IInstance RegisterInstance(

ECPUType in_CPUType

string in_InstanceName

);

Parameters • ECPUType in_CPUType:

Defines which CPU type is simulated at the start of the instance. The default

setting is "ECPUType.Unspecified".

When a different CPU type is loaded via STEP 7 or from the Virtual 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.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

250 Function Manual, 09/2016, A5E37039512-AA

Exceptions

Siemens.Simatic.Simulation.Runtime.SimulationRuntimeException

Runtime error code

Condition

ERuntimeError-

Code.InterfaceRemoved The interface is disconnected from the

remote Runtime Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The name is invalid.

ERuntimeErrorCode.LimitReached

There are already 16 instances regis-

tered in Runtime Manager.

ERuntimeErrorCode.AlreadyExists

An instance with this name already ex-

ists.

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

ERuntimeErrorCode RegisterCustomInstance(

WCHAR* in_VplcDll,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode RegisterCustomInstance(

WCHAR* in_VplcDll,

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

Parameters • WCHAR* in_VplcDll:

The complete path to the DLL of the virtual controller that Sie-

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

• IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initial-

ized with NULL. The interface is created within the function.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The interface is disconnected from the

remote Runtime Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The DLL name, the instance name or the

IInstance pointer is invalid.

SREC_LIMIT_REACHED

There are already 16 instances regis-

tered in Runtime Manager.

SREC_ALREADY_EXISTS

An instance with this name already ex-

ists.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 251

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

IInstance RegisterCustomInstance(

string in_VplcDll

);

IInstance RegisterCustomInstance(

string in_VplcDll,

string in_InstanceName

);

Parameters • string in_VplcDll:

The complete path to the DLL of the virtual controller that Sie-

mens.Simatic.Simulation.Runtime.Instance.exe loads at PowerOn.

• string in_InstanceName:

Name to be assigned to the instance. Every instance must have a unique

name. If no name is assigned when registering a new instance, the instance is

given the name "Instance_#"

(# is the ID of the instance). If this name already

exists, the name "Instance_#.#" is used, in which the second # is a counter

that is incremented until the name is unique. The length of the name must be

less than DINSTANCE_NAME_LENGTH. See Data types (Page 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

Condition

ERuntimeError-

Code.InterfaceRemoved The interface is disconnected from the

remote Runtime Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The name or the ID is invalid.

ERuntimeErrorCode.LimitReached

There are already 16 instances regis-

tered in Runtime Manager.

ERuntimeErrorCode.AlreadyExists

An instance with this name already ex-

ists.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

252 Function Manual, 09/2016, A5E37039512-AA

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

ERuntimeErrorCode CreateInterface(

WCHAR* in_InstanceName,

IInstance** out_InstanceInterface

);

ERuntimeErrorCode CreateInterface(

INT32 in_InstanceID,

IInstance** out_InstanceInterface

);

Parameters • INT32 in_InstanceID:

The ID of the registered instance from which you want to receive the interface.

• WCHAR* in_InstanceName:

The name of the registered instance from which you want to receive the inter-

face.

• IInstance** out_InstanceInterface:

Pointer to a Simulation Runtime interface pointer. The pointer must be initial-

ized with NULL. The interface is created within the function.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_INTERFACE_REMOVED

The interface is disconnected from the

remote Runtime Manager.

SREC_TIMEOUT

The function does not return on time.

SREC_WRONG_ARGUMENT

The name, the ID or the IInstance- point-

er is invalid.

SREC_DOES_NOT_EXIST

The instance is not registered in Runtime

Manager.

Example C++

ISimulationRuntimeManager * api = NULL;

ERuntimeErrorCode result = Initialize(&api);

IInstance* psa1 = NULL;

IInstance* psa2 = NULL;

if (result == SREC_OK)

{

result = api->

CreateInterface

(0, &psa1);

result = api->

CreateInterface

(0, &psa2); // psa2 will be the same as

psa1

}

Example C++

ISimulationRuntimeManager * api = NULL;

ERuntimeErrorCode result = Initialize(&api);

IInstance* psa = NULL;

if (result == SREC_OK)

{

result = api->

CreateInterface

(L"My SimulationRuntime Instance",

&psa);

}

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 253

Note

Native C++

If you no longer require the interface, delete it.

See

DestroyInterface() (Page 82)

Table 7- 292 CreateInterface() - .NET (C#)

Syntax

IInstance CreateInterface(

string in_InstanceName

);

IInstance CreateInterface(

INT32 in_InstanceID

);

Parameters • INT32 in_InstanceID:

The ID of the registered instance from which you want to receive the interface.

• string in_InstanceName:

The name of the registered instance from which you want to receive the inter-

face.

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

Condition

ERuntimeError-

Code.InterfaceRemoved The interface is disconnected from the

remote Runtime Manager.

ERuntimeErrorCode.Timeout

The function does not return on time.

ERuntimeErrorCode.WrongArgument

The name or the ID is invalid.

ERuntimeErrorCode.DoesNotExists

The instance is not registered in Runtime

Manager.

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

254 Function Manual, 09/2016, A5E37039512-AA

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

void RegisterOnConnectionLostCallback(

EventCallback_IRRTM in_CallbackFunction

);

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

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 255

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

void RegisterOnConnectionLostEvent();

void RegisterOnConnectionLostEvent(

HANDLE* in_Event

);

Parameters • None:

An internal event object is registered.

• HANDLE* in_Event:

A handle for a user-specific event object. The event object is registered.

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

User interfaces (API)

7.7 API IRemoteRuntimeManager

S7-PLCSIM Advanced

256 Function Manual, 09/2016, A5E37039512-AA

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

bool WaitForOnConnectionLostEvent();

bool WaitForOnConnectionLostEvent(

UINT32 in_Time_ms )

;

Parameters • None:

The time limit is set to INFINITE.

• UINT32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

Table 7- 301 WaitForOnConnectionLostEvent() - .NET (C#)

Syntax

bool WaitForOnConnectionLostEvent();

bool WaitForOnConnectionLostEvent(

UInt32 in_Time_ms )

;

Parameters • None:

The time limit is set to INFINITE.

• UInt32 in_Time_ms:

Value for the time limit in milliseconds.

Return values • true: If the event object was set to the signaled state.

•

false:

If no event was received during the defined time limit.

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 257

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

conversion after reading.

Example:

If the value 999 is transferred to the API as 2457H, then Write modifies the value 2457H to

999. Without BCD conversion, there is no UInt16 value and Write writes no value at all.

Additional information

For information on data types and conversion, refer to section "Data types" in the

STEP 7 V14 System Manual

(https://support.industry.siemens.com/cs/document/109011420/step-7-professional-v13-

1?dti=0&lc=en-WW // XmlEditor.InternalXmlClipboard:d59d29c4-ec28-6b28-3f63-

754735fb2e2a).

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

258 Function Manual, 09/2016, A5E37039512-AA

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

typedef ERuntimeErrorCode(*ApiEntry_Initialize)(

ISimulationRuntimeManager** out_RuntimeManagerInterface

);

Parameters • ISimulationRuntimeManager**

out_SimulationRuntimeManagerInterface:

Pointer to a Runtime Manager interface pointer. The pointer must be initial-

ized with ZERO. The interface is created within the function.

• UINT32 in_InterfaceVersion:

Version of the API interface to be downloaded:

API_DLL_INTERFACE_VERSION.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT

The pointer to the Runtime Manager

interface is ZERO.

SREC_WRONG_VERSION

The version of the interface in use

does not match the version of the API

DLL.

SREC_CONNECTION_ERROR

Unable to establish a connection to the

Runtime Manager.

7.8.1.2

ApiEntry_DestroyInterface

Description

Type of the entry point for DestroyInterface (Page 82).

Table 7- 303 ApiEntry_DestroyInterface - Native C++

Syntax

typedef ERuntimeErrorCode(*ApiEntry_DestroyInterface)(

IBaseInterface* in_Interface

);

Parameters • IBaseInterface* in_Interface:

The interface to be deleted.

Return values

Runtime error code

Condition

SREC_OK

The function is successful.

SREC_WRONG_ARGUMENT

The pointer to the interface is ZERO.

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 259

7.8.2

Event callback functions (Native C++)

7.8.2.1

EventCallback_VOID

Description

Table 7- 304 EventCallback_VOID - Native C++

Syntax

typedef void (*EventCallback_VOID)();

Parameters

None

Return values None

7.8.2.2

EventCallback_II_SREC_ST

Description

Table 7- 305 EventCallback_II_SREC_ST - Native C++

Syntax

typedef void (*EventCallback_II_SREC_ST)(

IInstance* in_Sender,

ERuntimeErrorCode in_ErrorCode,

SYSTEMTIME in_SystemTime

);

Parameters • IInstance* in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• SYSTEMTIME in_SystemTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

260 Function Manual, 09/2016, A5E37039512-AA

7.8.2.3

EventCallback_II_SREC_ST_SROS_SROS

Description

Table 7- 306 EventCallback_II_SREC_ST_SROS_SROS - Native C++

Syntax

typedef void (*EventCallback_II_SREC_ST_SROS_SROS)(

IInstance* in_Sender,

ERuntimeErrorCode in_ErrorCode,

SYSTEMTIME in_SystemTime,

EOperatingState in_PrevState,

EOperatingState in_OperatingState

);

Parameters • IInstance* in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• SYSTEMTIME in_SystemTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

• EOperatingState in_PrevState:

The operating state before the change.

• EOperatingState in_OperatingState:

The current operating state.

Return values

None

Error codes

Runntime error code

Condition

SREC_OK

The function is successful.

SREC_WARNING_TRIAL_MODE_ACTIVE

No license available. You can use the

instance without restrictions for a peri-

od of one hour. Afterwards, the in-

stance is shut down.

SREC_LICENSE_NOT_FOUND

Test mode has expired.

SREC_COMMUNICATION_INTERFACE_NOT

_AVAILABLE A problem has occurred with the se-

lected communication interface. Check

your settings.

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 261

7.8.2.4

EventCallback_II_SREC_ST_SRLT_SRLM

Description

Table 7- 307 EventCallback_II_SREC_ST_SRLT_SRLM - Native C++

Syntax

typedef void (*EventCallback_II_SREC_ST_SRLT_SRLM)(

IInstance* in_Sender,

ERuntimeErrorCode in_ErrorCode,

SYSTEMTIME in_SystemTime,

ELEDType in_LEDType,

ELEDMode in_LEDMode,

);

Parameters • IInstance* in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• SYSTEMTIME in_SystemTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

• ELEDType in_LEDType:

The LED type that changed its state.

• ELEDMode in_LEDMode:

The new state of the LED display.

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

262 Function Manual, 09/2016, A5E37039512-AA

7.8.2.5

EventCallback_II_SREC_ST_INT64_UINT32

Description

Table 7- 308 EventCallback_II_SREC_ST_INT64_UINT32 - Native C++

Syntax

typedef void (*EventCallback_II_SREC_ST_INT64_UINT32)(

IInstance* in_Sender,

ERuntimeErrorCode in_ErrorCode,

SYSTEMTIME in_SystemTime,

INT64 in_CycleTime_ns,

UINT32 in_CycleCount,

);

Parameters • IInstance* in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• SYSTEMTIME in_SystemTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

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

bined into one event. In this case, the value contains the virtual time (in na-

noseconds) since the last event was received.

• UINT32 in_CycleCount:

The number of cycles since the last cycle control point. If the events are trig-

gered 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

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 263

7.8.2.6

EventCallback_IRRTM

Description

Table 7- 309 EventCallback_IRRTM - Native C++

Syntax

typedef void (*EventCallback_IRRTM)(

IRemoteRuntimeManager* in_Sender

);

Parameters • IRemoteRuntimeManager* in_Sender:

An interface of the remote Runtime Manager that receives this event.

Return values

None

7.8.2.7

EventCallback_SRCC_UINT32_UINT32_INT32

Description

Table 7- 310 EventCallback_SRCC_UINT32_UINT32_INT32 - Native C++

Syntax

ERuntimeConfigChanged in_RuntimeConfigChanged,

UINT32 in_Param1,

UINT32 in_Param2,

INT32 in_Param3

);

Parameters

ERuntimeCon-

figChanged

in_RuntimeConfi

gChanged

UInt32

in_Param1

UInt32

in_Param2

Int32 in_Param3

SRCC_INSTANCE_R

EGISTERED

ID of the regis-

tered instance

SRCC_INSTANCE_U

NREGISTERED

ID of the unregis-

tered instance

SRCC_CONNECTION

_OPENED IP of the remote

Runtime Manager

Port of the remote

Runtime Manager

SRCC_CONNECTION

_CLOSED IP of the remote

Runtime Manager

Port of the remote

Runtime Manager

SRCC_PORT_OPENE

The open port

SRCC_PORT_CLOSE

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

264 Function Manual, 09/2016, A5E37039512-AA

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

typedef void

(*EventCallback_II_SREC_ST_SRICC_UINT32_UINT32_UINT32_UINT32)(

IInstance* in_Sender,

ERuntimeErrorCode in_ErrorCode, SYSTEMTIME in_SystemTime,

EInstanceConfigChanged in_InstanceConfigChanged,

UINT32 in_Param1,

UINT32 in_Param2,

UINT32 in_Param3,

UINT32 in_Param4

);

Parameters • IInstance in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• SYSTEMTIME in_SystemTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

EIn-

stanceCon-

figChanged

in_Instance

Con-

figChanged

UINT32

in_Param1

UINT32

in_Param2

UINT32

in_Param3

UINT32

in_Param4

SRICC_HARDW

ARE_SOFTWAR

E CHANGED

SRICC_IP_CH

ANGED The ID of the

interface

The new IP The new sub-

net mask

The new

standard

gateway

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 265

7.8.3

Delegate definitions (managed code)

7.8.3.1

Delegate_Void

Description

Table 7- 312 Delegate_Void - .NET (C#)

Syntax

delegate void Delegate_Void();

Parameters

None

Return values None

7.8.3.2

Delegate_II_EREC_DT

Description

Table 7- 313 Delegate_II_EREC_DT - .NET (C#)

Syntax

delegate void Delegate_II_EREC_DT (

IInstance in_Sender,

ERuntimeErrorCode in_ErrorCode,

DateTime in_DateTime

);

Parameters • IInstance in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• DateTime in_DateTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

266 Function Manual, 09/2016, A5E37039512-AA

7.8.3.3

Delegate_II_EREC_DT_EOS_EOS

Description

Table 7- 314 Delegate_II_EREC_DT_EOS_EOS - .NET (C#)

Syntax

delegate void Delegate_II_EREC_DT_EOS_EOS(

IInstance in_Sender,

ERuntimeErrorCode in_ErrorCode,

DateTime in_DateTime,

EOperatingState in_PrevState,

EOperatingState in_OperatingState

);

Parameters • IInstance in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• DateTime in_DateTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

• EOperatingState in_PrevState:

The operating state before the change.

• EOperatingState in_OperatingState:

The current operating state.

Return values

None

Error codes

Runntime error code

Condition

ERuntimeErrorCode.OK

The function is successful.

ERuntimeError-

Code.WarningTrialModeActive No license available. You can use the

instance without restrictions for a peri-

od of one hour. Afterwards, the in-

stance is shut down.

ERuntimeError-

Code.LicenseNotFound

Test mode has expired.

ERuntimeError-

Code.CommunicationInterfaceNotAv

ailable A problem has occurred with the se-

lected communication interface. Check

your settings.

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 267

7.8.3.4

Delegate_II_EREC_DT_ELT_ELM

Description

Table 7- 315 Delegate_II_EREC_DT_ELT_ELM - .NET (C#)

Syntax

delegate void Delegate_II_EREC_DT_ELT_ELM(

IInstance in_Sender,

ERuntimeErrorCode in_ErrorCode,

DateTime in_DateTime,

ELEDType in_LEDType,

ELEDMode in_LEDMode,

);

Parameters • IInstance in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• DateTime in_DateTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

• ELEDType in_LEDType:

The LED type that changed its state.

• ELEDMode in_LEDMode:

The new state of the LED display.

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

268 Function Manual, 09/2016, A5E37039512-AA

7.8.3.5

Delegate_II_EREC_DT_INT64_UINT32

Description

Table 7- 316 Delegate_II_EREC_DT_INT64_UINT32 - .NET (C#)

Syntax

delegate void Delegate_II_EREC_DT_INT64_UINT32(

IInstance in_Sender,

ERuntimeErrorCode in_ErrorCode,

DateTime in_DateTime,

Int64 in_CycleTime_ns,

UInt32 in_CycleCount,

);

Parameters • IInstance in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• DateTime in_DateTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

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

bined into one event. In this case, the value contains the virtual time (in na-

noseconds) since the last event was received.

• UInt32 in_CycleCount:

The number of cycles since the last cycle control point. If the events are trig-

gered 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

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 269

7.8.3.6

Delegate_IRRTM

Description

Table 7- 317 Delegate_IRRTM - .NET (C#)

Syntax

delegate void Delegate_IRRTM(

IRemoteRuntimeManager in_Sender,

);

Parameters • IRemoteRuntimeManager in_Sender:

An interface of the remote Runtime Manager that receives this event.

Return values

None

7.8.3.7

Delegate_SRCC_UINT32_UINT32_INT32

Description

Table 7- 318 Delegate_SRCC_UINT32_UINT32_INT32 - .NET (C#)

Syntax

delegate void Delegate_SRCC_UINT32_UINT32_INT32(

ERuntimeConfigChanged in_RuntimeConfigChanged,

UInt32 in_Param1,

UInt32 in_Param2,

Int32 in_Param3

);

Parameters

ERuntimeCon-

figChanged

in_RuntimeConfi

gChanged

UInt32

in_Param1

UInt32

in_Param2

Int32 in_Param3

InstanceRegis-

tered

ID of the regis-

tered instance

InstanceUnreg-

istered

ID of the unregis-

tered instance

ConnectionO-

pened IP of the Remote

Runtime Manager

Port of the remote

Runtime Manager

Connection-

Closed IP of the Remote

Runtime Manager

Port of the remote

Runtime Manager

PortOpened

The open port

PortClosed

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

270 Function Manual, 09/2016, A5E37039512-AA

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

delegate void Dele-

gate_II_EREC_DT_SRICC_UINT32_UINT32_UINT32_UINT32(

IInstance in_Sender,

ERuntimeErrorCode in_ErrorCode,

DateTime in_DateTime,

EInstanceConfigChanged in_InstanceConfigChanged,

UInt32 in_Param1,

UInt32 in_Param2,

UInt32 in_Param3,

UInt32 in_Param4

);

Parameters • IInstance in_Sender:

An interface of the instance that receives this event.

• ERuntimeErrorCode in_ErrorCode:

A possible error code.

• DateTime in_DateTime:

The virtual system time of the virtual controller at the time when this event

was triggered.

EIn-

stanceCon-

figChanged

in_Instance

Con-

figChanged

UInt32

in_Param1

UInt32

in_Param2

UInt32

in_Param3

UInt32

in_Param4

Hard-

wareSoft-

wareChanged

IPChanged

The ID of the

interface

The new IP The new sub-

net mask

The new

standard

gateway

Return values

None

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 271

7.8.4

Definitions and constants

The following identifiers are used in the API:

Table 7- 320 Definitions and constants - Native C++

Identifier

Value

Description

DINSTANCE_NAME_MAX_LENGTH

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

dimensional field.

DCONTROLLER_NAME_MAX_LENGTH

128 The maximum length of the controller name. In-

cluding ZERO termination.

DCONTROLLER_SHORT_DESIGNATION_MA

X_LENGTH 32 The maximum length of the abbreviation of the

controller (CPU type). Including ZERO termination.

Table 7- 321 Definitions and constants - .NET (C#)

Identifier

Value

Description

RuntimeCon-

stants.InstanceNameLength 64 The unique name of an instance must be less than

this value.

RuntimeCon-

stants.StoragePathMaxLength 130 The maximum path length to the virtual memory

card. Including ZERO termination.

RuntimeCon-

stants.TagNameMaxLength 300 The maximum length of the name of a PLC tag.

Including ZERO termination.

RuntimeCon-

stants.TagArrayDimension 6 The maximum number of dimension for a multi-

dimensional field.

RuntimeCon-

stants.ControllerNameMaxLength 128 The maximum length of the controller name. In-

cluding ZERO termination.

RuntimeCon-

stants.ControllerShortDesignatio

nMaxLength

32 The maximum length of the abbreviation of the

controller (CPU type). Including ZERO termination.

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

272 Function Manual, 09/2016, A5E37039512-AA

7.8.5

Unions (Native C++)

7.8.5.1

UIP

Description

Contains an IPv4 address.

Table 7- 322 UIP - Native C++

Syntax

union UIP

{

DWORD IP;

BYTE IPs[4];

};

Member • DWORD IP:

The IP address in a single DWORD

• BYTE IPs[4]:

The four elements of IP in descending order

Example Example for an IP address: 192.168.0.1

UIP.IP = 0xC0A80001

UIP.IPs[3] = 192, UIP.IPs[2] = 168, UIP.IPs[1] = 0, UIP.IPs[0] = 1

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;

};

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 273

Member • bool Bool:

1 byte boolean value

• INT8 Int8:

1 byte integer with sign

• INT16 Int16:

2 byte integer with sign

• INT32 Int32:

4 byte integer with sign

• INT64 Int64:

8 byte integer with sign

• 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

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

274 Function Manual, 09/2016, A5E37039512-AA

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

struct SDataValue

{

UDataValue Value;

EDataType Type;

};

Member • 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; }

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 275

Member

• bool Bool:

1 byte boolean value

• Int8 Int8:

1 byte integer with sign

• Int16 Int16:

2 byte integer with sign

• Int32 Int32:

4 byte integer with sign

• Int64 Int64:

8 byte integer with sign

• UntT8 UInt8:

1 byte integer without sign

• UInt16 UInt16:

2 byte integer without sign

• UInt32 UInt32:

4 byte integer without sign

• UInt64 UInt64:

8 byte integer without sign

• float Float:

4 byte floating-point value

• double Double:

8 byte floating-point value

• sbyte Char:

1 byte value character

• char WChar:

2 byte value character

• EPrimitiveDataType Type:

Type of PLC tag

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

276 Function Manual, 09/2016, A5E37039512-AA

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

struct SDataValueByAddress

{

UInt32 Offset;

UInt8 Bit;

SDataValue DataValue;

}

7.8.6.3

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;

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 277

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;

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

278 Function Manual, 09/2016, A5E37039512-AA

7.8.6.5

SInstanceInfo

Description

This structure contains an IPv4 address.

Table 7- 332 SInstanceInfo - Native C++

Syntax

struct SInstanceInfo

{

INT32 ID;

WCHAR Name[DINSTANCE_NAME_MAX_LENGTH];

};

Member • INT32 ID:

The ID of the instance

• WCHAR Name[DINSTANCE_NAME_MAX_LENGTH]:

The name of the instance

Table 7- 333 SInstanceInfo - .NET (C#)

Syntax

struct SInstanceInfo

{

Int32 ID;

String Name;

}

Member • Int32 ID:

The ID of the instance

• String name:

The name of the instance

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 279

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;

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

280 Function Manual, 09/2016, A5E37039512-AA

7.8.6.7

STagInfo

Description

This structure contains information about a PLC tag.

Table 7- 336 STagInfo - Native C++

Syntax

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

};

Member • WCHAR Name[DTAG_NAME_MAX_LENGTH]:

The name of the tag

• EArea area:

The CPU area where the tag is located.

• EDataType DataType:

The CPU data type of the tag

• EPrimitiveDataType PrimitiveDataType:

The primitive data type of the tag

• UINT16 size:

The size of the tag in bytes

• UINT32 offset:

The byte offset of the tag if it is not located in a data block.

• UINT8 bit:

The bit offset of the tag if it is not located in a data block.

• UINT8 DimensionCount:

The number of dimensions of the array. 0 if it is not a field for the tag.

• 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[DTAG_ARRAY_DIMENSION]:

Information about each dimension of the field

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 281

Table 7- 337 STagInfo - .NET (C#)

Syntax

public struct STagInfo

{

String Name;

EArea Area;

EDataType DataType;

EPrimitiveDataType PrimitiveDataType;

UInt16 Size;

UInt32 Offset;

UInt8 Bit;

UInt32 Index;

UInt32 ParentIndex;

SDimension[] Dimension;

}

Member • String name:

The name of the tag

• EArea area:

The CPU area where the tag is located.

• EDataType DataType:

The CPU data type of the tag

• EPrimitiveDataType PrimitiveDataType:

The primitive data type of the tag

• UInt16 size:

The size of the tag in bytes.

• UInt32 offset:

The byte offset of the tag if it is not located in a data block.

• UInt8 bit:

The bit offset of the tag if it is not located in a data block.

• UInt32 index:

The index of the tag

• UInt32 ParentIndex:

If this tag is embedded in another tag (for example, an element of a structure),

this value then disp

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

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

282 Function Manual, 09/2016, A5E37039512-AA

7.8.6.8

SIP

Description

This structure contains an IPv4 address.

Table 7- 338 SIP - .NET (C#)

Syntax

struct SIP

{

byte[] IPArray { get; set; }

UInt32 IPDWord { get; set; }

string IPString { get; set; }

}

Member • UInt32 IPDWord:

The IP address in a single DWORD

• byte[] IPArray:

The four elements of IP in descending order

• string IPString:

The IPv4 address as a string

Example Example for an IP address: 192.168.0.1

SIP.IPDWord = 0xC0A80001

SIP.IPArray[3] = 192, SIP.IPArray[2] = 168, SIP.IPArray[1] = 0, SIP.IPArray[0] =

SIP.IPString = "192.168.0.1"

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 283

7.8.6.9

SIPSuite4

Description

This structure contains an IPv4 suite.

Table 7- 339 SIPSuite4 - Native C++

Syntax

struct SIPSuite4

{

UIP IPAddress;

UIP SubnetMask;

UIP DefaultGateway;

};

Member • UIP IPAddress:

The IP address

• UIP SubnetMask:

The subnet mask

• UIP DefaultGateway:

The standard gateway

Table 7- 340 SIPSuite4 - .NET (C#)

Syntax

struct SIPSuite4

{

SIP IPAddress;

SIP SubnetMask;

SIP DefaultGateway;

}

Member • SIP IPAddress:

The IP address

• SIP SubnetMask:

The subnet mask

• SIP DefaultGateway:

The standard gateway

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

284 Function Manual, 09/2016, A5E37039512-AA

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

};

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 285

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

286 Function Manual, 09/2016, A5E37039512-AA

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,

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 287

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

288 Function Manual, 09/2016, A5E37039512-AA

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 289

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

};

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

290 Function Manual, 09/2016, A5E37039512-AA

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 291

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,

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

292 Function Manual, 09/2016, A5E37039512-AA

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 293

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

294 Function Manual, 09/2016, A5E37039512-AA

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 295

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 INT8 INT16 INT32 INT64 UINT8 UINT16 UINT32 UINT6

Float Double Char WChar

Bool X

INT8

INT16

INT32

INT64

UINT8

UINT16

UINT32

UINT64

Float

Double

Char

WChar

Table 7- 360 Compatible primitive data types - Write

API

PLCSIM Advanced instance

Bool INT8 INT16 INT32 INT64 UINT8 UINT16 UINT32 UINT6

Float Double Char WChar

Bool

INT8

INT16

INT32 X X

INT64

UINT8

UINT16

UINT32

UINT64

Float

Double

Char

WChar

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

296 Function Manual, 09/2016, A5E37039512-AA

7.8.7.10

EDataType

Description

This list contains all the CPU data types (STEP 7).

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 297

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

};

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

298 Function Manual, 09/2016, A5E37039512-AA

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 299

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

300 Function Manual, 09/2016, A5E37039512-AA

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

}

User interfaces (API)

7.8 Data types

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 301

S7-PLCSIM Advanced

302 Function Manual, 09/2016, A5E37039512-AA

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.

Restrictions

8.2 OPC UA server

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 303

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

Restrictions

8.3 Web server

S7-PLCSIM Advanced

304 Function Manual, 09/2016, A5E37039512-AA

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.

Restrictions

8.4 Restrictions for communications services

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 305

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.

Restrictions

8.5 Restrictions for instructions

S7-PLCSIM Advanced

306 Function Manual, 09/2016, A5E37039512-AA

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

Restrictions

8.6 Restrictions with Motion Control

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 307

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

Article number

Standard CPUs

CPU 1517-3 PN/DP

CPU 1518-4 PN/DP

CPU 1518-4 PN/DP ODK

6ES7517-3AP00-0AB0

6ES7518-4AP00-0AB0

6ES7518-4AP00-3AB0

Fail-safe CPUs

CPU 1517F-3 PN/DP

CPU 1518F-4 PN/DP

CPU 1518F-4 PN/DP ODK

6ES7517-3FP00-0AB0

6ES7518-4FP00-0AB0

6ES7518-4FP00-3AB0

Technology CPUs

CPU 1517T-3 PN/DP2

CPU 1517TF-3 PN/DP

6ES7517-3TP00-0AB0

6ES7517-3UP00-0AB0

The ODK functionality of this CPU is not simulated.

2 The simulation of this CPU supports only 64 cams.

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.

Restrictions

8.7 Restrictions to local communication via Softbus

S7-PLCSIM Advanced

308 Function Manual, 09/2016, A5E37039512-AA

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

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

Restrictions

8.8 Restrictions of security with VMware vSphere Hypervisor (ESXi)

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 309

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 Policy exceptions for VMware vSphere Hypervisor (ESXi)

8.9

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)

Restrictions

8.10 Deviating I/O values in the STEP 7 user program

S7-PLCSIM Advanced

310 Function Manual, 09/2016, A5E37039512-AA

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 <IP address>" 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.

Restrictions

8.14 Error installing the antivirus software from Kaspersky

S7-PLCSIM Advanced

Function Manual, 09/2016, A5E37039512-AA 311

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

312 Function Manual, 09/2016, A5E37039512-AA

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)

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.

Organization Block

ODK

Open Development Kit

OPC UA

Open Platform Communications Unified Architecture

Programming device

PLC

Programmable Logic Controller

PROFINET

RAM

Random Access Memory

Runtime

TIA

Totally Integrated Automation

UTC

Coordinated Universal Time

Virtual Machine

VPLC

Virtual Programmable Logic Controller

WinCC

Windows Control Center

S7 PLCSIM Advanced Function Manual En US

Navigation menu

Versions of this User Manual:

Views

Navigation