WinCCInformationSystemScripting en US
WinCCInformationSystemScripting en US
WinCC V7.2
WinCC: Scripting (VBS, ANSI-C,
VBA)
System Manual
Print of the Online Help
02/2013
A5E32315920-AA
VBS for Creating Procedures
and Actions
1
ANSI-C for Creating
Functions and Actions
2
VBA for Automated
Configuration
3
Legal information
Warning notice system
This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent
damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert
symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are
graded according to the degree of danger.
DANGER
indicates that death or severe personal injury will result if proper precautions are not taken.
WARNING
indicates that death or severe personal injury may result if proper precautions are not taken.
CAUTION
indicates that minor personal injury can result if proper precautions are not taken.
NOTICE
indicates that property damage can result if proper precautions are not taken.
If more than one degree of danger is present, the warning notice representing the highest degree of danger will be
used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property
damage.
Qualified Personnel
The product/system described in this documentation may be operated only by personnel qualified for the specific
task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified
personnel are those who, based on their training and experience, are capable of identifying risks and avoiding
potential hazards when working with these products/systems.
Proper use of Siemens products
Note the following:
WARNING
Siemens products may only be used for the applications described in the catalog and in the relevant technical
documentation. If products and components from other manufacturers are used, these must be recommended or
approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and
maintenance are required to ensure that the products operate safely and without any problems. The permissible
ambient conditions must be complied with. The information in the relevant documentation must be observed.
Trademarks
All names identified by are registered trademarks of Siemens AG. The remaining trademarks in this publication
may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.
Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and software described.
Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in
this publication is reviewed regularly and any necessary corrections are included in subsequent editions.
Siemens AG
Industry Sector
Postfach 48 48
90026 NRNBERG
GERMANY
A5E32315920-AA
02/2013 Technical data subject to change
Copyright Siemens AG 2013.
All rights reserved
Table of contents
1 VBS for Creating Procedures and Actions..................................................................................................11
1.1 VBS for creating procedures and actions....................................................................................11
1.2 Using Visual Basic Script in WinCC............................................................................................12
1.3 Modules and Procedures.............................................................................................................15
1.4 Actions.........................................................................................................................................18
1.5 Multiple Use of Procedures and Actions......................................................................................20
1.6 Use of CrossReference...............................................................................................................22
1.7 Using Global Tags in VBS...........................................................................................................24
1.8 VBScript Editors..........................................................................................................................26
1.8.1 VBScript Editors..........................................................................................................................26
1.8.2 Global Script Editor......................................................................................................................27
1.8.3 Working in an Editing Window.....................................................................................................30
1.8.4 Working with the Toolbars...........................................................................................................33
1.8.5 Deleting Actions or Procedures...................................................................................................35
1.9 Creating and Editing Procedures.................................................................................................37
1.9.1 Creating and Editing Procedures.................................................................................................37
1.9.2 Creating a New Procedure..........................................................................................................40
1.9.3 How to Write Procedure Codes...................................................................................................42
1.9.4 Using Standard and Project Procedures.....................................................................................45
1.9.5 How to add module-related information.......................................................................................46
1.9.6 Protecting a Module with a Password.........................................................................................48
1.9.7 Saving a Procedure.....................................................................................................................49
1.9.8 Renaming a Procedure or Module...............................................................................................51
1.10 Creating and Editing Actions.......................................................................................................53
1.10.1 Creating and Editing Actions.......................................................................................................53
1.10.2 Creating a New Action.................................................................................................................57
1.10.3 How to Edit Actions.....................................................................................................................58
1.10.4 How to add action-related information.........................................................................................62
1.10.5 Protecting an Action with a Password.........................................................................................64
1.10.6 Saving Actions.............................................................................................................................65
1.10.7 Triggers.......................................................................................................................................66
1.10.7.1 Triggers.......................................................................................................................................66
1.10.7.2 Animation trigger.........................................................................................................................70
1.10.7.3 How to add a trigger of the type "Timer"......................................................................................72
1.10.7.4 How to add a trigger of the type "Tag".........................................................................................74
1.10.7.5 How to change a trigger..............................................................................................................76
1.10.7.6 How to delete a trigger................................................................................................................77
1.10.8 How to Rename an Action...........................................................................................................78
1.11 How to activate global actions in Runtime...................................................................................80
1.12 Diagnostics..................................................................................................................................82
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 3
1.12.1 Diagnostics..................................................................................................................................82
1.12.2 GSC Diagnostics.........................................................................................................................83
1.12.2.1 GSC Diagnostics.........................................................................................................................83
1.12.2.2 Inserting the GSC Diagnostics Window into a Picture.................................................................84
1.12.2.3 GSC Diagnostics Attributes.........................................................................................................84
1.12.2.4 GSC Diagnostics Toolbar............................................................................................................85
1.12.3 GSC Runtime..............................................................................................................................86
1.12.3.1 GSC Runtime..............................................................................................................................86
1.12.3.2 How to insert the GSC Runtime Window into a Picture...............................................................87
1.12.3.3 GSC Runtime Attributes..............................................................................................................88
1.12.4 Testing with the Debugger...........................................................................................................89
1.12.4.1 Testing with the Debugger...........................................................................................................89
1.12.4.2 How to Activate the Debugger.....................................................................................................90
1.12.4.3 Principles of Debugging...............................................................................................................92
1.12.4.4 Components of the Microsoft Script Debuggers..........................................................................94
1.12.4.5 Structure of VBScript Files..........................................................................................................95
1.12.4.6 Action and Procedure Names in the Debugger...........................................................................97
1.12.4.7 Selecting a Script for Editing.......................................................................................................99
1.12.4.8 Processing Scripts Step-by-Step...............................................................................................101
1.12.4.9 Setting Breakpoints...................................................................................................................102
1.12.4.10 Deleting Breakpoints............................................................................................................103
1.12.4.11 How to Set Bookmarks in Scripts.........................................................................................104
1.12.4.12 How to Determine and Modify Tag and Property Values.....................................................105
1.12.4.13 Executing Script Commands................................................................................................106
1.13 Printing VBScripts......................................................................................................................108
1.14 VBS Reference..........................................................................................................................109
1.14.1 VBS Reference..........................................................................................................................109
1.14.2 Objects and Lists.......................................................................................................................113
1.14.2.1 Objects and Lists.......................................................................................................................113
1.14.2.2 Alarm object...............................................................................................................................115
1.14.2.3 Alarms object (list).....................................................................................................................116
1.14.2.4 AlarmLogs Object......................................................................................................................117
1.14.2.5 DataItem Object.........................................................................................................................118
1.14.2.6 DataLogs Object........................................................................................................................120
1.14.2.7 DataSet-Objekt (List).................................................................................................................121
1.14.2.8 HMIRuntime Object...................................................................................................................123
1.14.2.9 Item Object................................................................................................................................124
1.14.2.10 Layer Object.........................................................................................................................125
1.14.2.11 Layers Object (Listing).........................................................................................................126
1.14.2.12 Logging Object.....................................................................................................................127
1.14.2.13 ProcessValue Object............................................................................................................128
1.14.2.14 ProcessValues Object (List).................................................................................................129
1.14.2.15 Project Object.......................................................................................................................129
1.14.2.16 ScreenItem Object................................................................................................................130
1.14.2.17 ScreenItems Object (List).....................................................................................................133
1.14.2.18 Screen Object.......................................................................................................................135
1.14.2.19 Screens Object (List)............................................................................................................138
1.14.2.20 SmartTags Object................................................................................................................140
1.14.2.21 Tag Object............................................................................................................................141
1.14.2.22 Tags Object (List).................................................................................................................144
1.14.2.23 TagSet Object (List).............................................................................................................146
Table of contents
WinCC: Scripting (VBS, ANSI-C, VBA)
4 System Manual, 02/2013, A5E32315920-AA
1.14.3 Object types of the ScreenItem object.......................................................................................147
1.14.3.1 Object types of the ScreenItem object.......................................................................................147
1.14.3.2 Standard objects........................................................................................................................148
1.14.3.3 Smart objects.............................................................................................................................176
1.14.3.4 Windows objects........................................................................................................................207
1.14.3.5 Tube objects..............................................................................................................................219
1.14.3.6 Controls.....................................................................................................................................221
1.14.3.7 Customized Object....................................................................................................................287
1.14.3.8 Group.........................................................................................................................................288
1.14.4 Properties..................................................................................................................................289
1.14.4.1 Properties..................................................................................................................................289
1.14.4.2 A................................................................................................................................................290
1.14.4.3 B................................................................................................................................................309
1.14.4.4 C................................................................................................................................................335
1.14.4.5 D................................................................................................................................................369
1.14.4.6 E................................................................................................................................................378
1.14.4.7 F................................................................................................................................................388
1.14.4.8 G................................................................................................................................................410
1.14.4.9 H................................................................................................................................................414
1.14.4.10 I............................................................................................................................................422
1.14.4.11 L...........................................................................................................................................428
1.14.4.12 M..........................................................................................................................................459
1.14.4.13 N...........................................................................................................................................480
1.14.4.14 O...........................................................................................................................................482
1.14.4.15 P...........................................................................................................................................499
1.14.4.16 Q...........................................................................................................................................516
1.14.4.17 R...........................................................................................................................................517
1.14.4.18 S...........................................................................................................................................528
1.14.4.19 T...........................................................................................................................................565
1.14.4.20 U...........................................................................................................................................640
1.14.4.21 V...........................................................................................................................................649
1.14.4.22 W..........................................................................................................................................665
1.14.4.23 X - Z......................................................................................................................................670
1.14.5 Methods.....................................................................................................................................678
1.14.5.1 Methods.....................................................................................................................................678
1.14.5.2 Methods A to E..........................................................................................................................680
1.14.5.3 Get methods..............................................................................................................................688
1.14.5.4 Methods H to M.........................................................................................................................736
1.14.5.5 Methods N to R..........................................................................................................................747
1.14.5.6 Methods S to T..........................................................................................................................765
1.14.5.7 Methods U to Z..........................................................................................................................779
1.14.6 Appendix....................................................................................................................................787
1.14.6.1 Error Messages from Database Area........................................................................................787
1.15 Examples of VBScript................................................................................................................789
1.15.1 Examples of VBScript................................................................................................................789
1.15.2 Examples in WinCC...................................................................................................................789
1.15.2.1 Examples in WinCC...................................................................................................................789
1.15.2.2 Example: Accessing objects in Graphics Designer...................................................................790
1.15.2.3 Example: Defining the color of objects......................................................................................791
1.15.2.4 Example: How to Configure Language Changes......................................................................791
1.15.2.5 Example: Deactivating Runtime................................................................................................792
1.15.2.6 Example: Configuring change picture globally..........................................................................792
Table of contents
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 5
1.15.2.7 Example: Configuring Change Picture Via Property..................................................................793
1.15.2.8 Example: Configuring diagnostics output via Trace..................................................................793
1.15.2.9 Example: Writing tag values......................................................................................................794
1.15.2.10 Example: How to Read Tag Values.....................................................................................796
1.15.2.11 Example: Writing Object Properties.....................................................................................799
1.15.2.12 Example: How to Start an Action on the Server (Logging Object).......................................801
1.15.2.13 Dynamization of Controls.....................................................................................................803
1.15.3 General Examples.....................................................................................................................816
1.15.3.1 General examples for VBScript.................................................................................................816
1.15.3.2 Example: Configuring a Database Connection with VBS..........................................................817
1.15.3.3 Example: Using the MS Automation interface...........................................................................819
1.15.3.4 Example: Starting an external application.................................................................................820
1.16 Basic Principles of VBScript......................................................................................................822
1.16.1 Basic Principles of VBScript......................................................................................................822
1.16.2 VBScript Basics.........................................................................................................................822
2 ANSI-C for Creating Functions and Actions.............................................................................................823
2.1 Creating Functions and Actions with ANSI-C............................................................................823
2.2 Creating Functions and Actions.................................................................................................824
2.3 Characteristics of Project Functions..........................................................................................827
2.4 Characteristics of Standard Functions.......................................................................................828
2.5 Characteristics of Internal Functions.........................................................................................830
2.6 Characteristics of Local Actions................................................................................................831
2.7 Characteristics of Global Actions...............................................................................................832
2.8 How to Add Global Script Runtime to a Project's Startup List...................................................833
2.9 Use of Global C-Tags................................................................................................................834
2.10 Use of DLLs in Functions and Actions.......................................................................................836
2.11 The Global Script Editor............................................................................................................838
2.11.1 The Global Script Editor............................................................................................................838
2.11.2 Working in the Edit Window.......................................................................................................840
2.11.2.1 Working in the Edit Window.......................................................................................................840
2.11.2.2 Editing Functions with the Keyboard.........................................................................................841
2.11.2.3 Editing Functions with the Mouse..............................................................................................842
2.11.3 Working with the Toolbars.........................................................................................................843
2.11.4 How to Set Different Views........................................................................................................845
2.11.5 How to Set the Font Style..........................................................................................................846
2.11.6 How to Use "Save As..."............................................................................................................846
2.11.7 How to Delete Actions or Project and Standard Functions........................................................847
2.11.8 How to Generate a New Header...............................................................................................848
2.11.9 How to Compile All Functions....................................................................................................848
2.11.10 How to Search in Files...............................................................................................................849
2.11.11 Printing Functions and Actions..................................................................................................850
2.11.11.1 Printing Functions and Actions.............................................................................................850
2.11.11.2 How to Set the Print Parameters..........................................................................................850
2.11.11.3 How to Open Page View......................................................................................................851
2.11.11.4 How to Print the Project Documentation..............................................................................851
Table of contents
WinCC: Scripting (VBS, ANSI-C, VBA)
6 System Manual, 02/2013, A5E32315920-AA
2.12 Creating and Editing Functions.................................................................................................852
2.12.1 Creating and Editing Functions.................................................................................................852
2.12.2 How to Create a New Function..................................................................................................855
2.12.3 How to Write Function Code......................................................................................................856
2.12.4 How to Use Internal Functions..................................................................................................857
2.12.5 How to Use Standard and Project Functions.............................................................................858
2.12.6 Inserting Additional Function-Related Information.....................................................................859
2.12.7 How to Protect a Function Against Unauthorized Access.........................................................860
2.12.8 How to Compile and Save a Function.......................................................................................861
2.12.9 How to Rename a Function.......................................................................................................862
2.12.10 How to Use Functions from Other Sources...............................................................................863
2.13 Creating and Editing Actions.....................................................................................................865
2.13.1 How To Create and Edit Actions...............................................................................................865
2.13.2 WinCC Coding Rule..................................................................................................................868
2.13.3 How to Create a New Action.....................................................................................................869
2.13.4 How to Edit Actions...................................................................................................................870
2.13.5 How to add action-related information.......................................................................................870
2.13.6 How to Protect an Action Against Unauthorized Access...........................................................872
2.13.7 How to Compile and Save an Action.........................................................................................873
2.13.8 Triggers.....................................................................................................................................874
2.13.8.1 Triggers.....................................................................................................................................874
2.13.8.2 How to Add a New Trigger of the "Timer" Type.........................................................................877
2.13.8.3 How to Add a New Trigger of the "Tag" Type............................................................................878
2.13.8.4 How to change a trigger............................................................................................................880
2.13.8.5 How to delete a trigger..............................................................................................................881
2.13.9 How to Assign Authorizations....................................................................................................882
2.13.10 How to Export an Action............................................................................................................882
2.13.11 How to Import an Action............................................................................................................883
2.13.12 How to Rename an Action.........................................................................................................884
2.13.13 How to Use Actions From Other Sources..................................................................................885
2.14 Runtime Behavior of Actions.....................................................................................................887
2.14.1 Runtime Behavior of Actions.....................................................................................................887
2.14.2 GSC Runtime............................................................................................................................888
2.14.2.1 GSC Runtime............................................................................................................................888
2.14.2.2 How to Place GSC Runtime in a Process Picture.....................................................................891
2.14.2.3 Attributes of GSC Runtime........................................................................................................892
2.14.2.4 How to Edit Actions...................................................................................................................892
2.14.3 GSC Diagnose...........................................................................................................................893
2.14.3.1 GSC Diagnose...........................................................................................................................893
2.14.3.2 How to Place GSC Diagnose in a Process Picture?.................................................................894
2.14.3.3 Attributes of GSC Diagnose......................................................................................................895
2.14.3.4 The Toolbar of GSC Diagnose..................................................................................................895
2.15 ANSI-C function descriptions.....................................................................................................897
2.15.1 lpszPictureName.......................................................................................................................897
2.15.2 Standard functions.....................................................................................................................897
2.15.2.1 Standard functions - short description.......................................................................................897
2.15.2.2 Alarm.........................................................................................................................................898
2.15.2.3 Graphics....................................................................................................................................903
2.15.2.4 Obsolete functions.....................................................................................................................908
2.15.2.5 Report........................................................................................................................................965
Table of contents
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 7
2.15.2.6 WinCC.......................................................................................................................................967
2.15.2.7 Windows....................................................................................................................................974
2.15.3 Internal functions.......................................................................................................................975
2.15.3.1 Internal functions - short description..........................................................................................975
2.15.3.2 allocate......................................................................................................................................976
2.15.3.3 c_bib..........................................................................................................................................977
2.15.3.4 graphics...................................................................................................................................1061
2.15.3.5 tag............................................................................................................................................1387
2.15.3.6 WinCC.....................................................................................................................................1499
2.15.4 Examples.................................................................................................................................1506
2.15.4.1 Examles - A to G.....................................................................................................................1506
2.15.4.2 Examples - GetAlarmHigh to GetPropChar.............................................................................1509
2.15.4.3 Examples - GetRangeMax to GetWidth..................................................................................1525
2.15.4.4 Examples - H to S....................................................................................................................1546
2.15.4.5 Examples - SetAlarmHigh to SetPropChar..............................................................................1548
2.15.4.6 Examples - SetRangeMax to SetWidth...................................................................................1558
2.15.4.7 Examples - T to Z....................................................................................................................1568
2.15.4.8 Examples of WinCC controls...................................................................................................1573
2.15.5 Lists.........................................................................................................................................1575
2.15.5.1 Bar direction............................................................................................................................1575
2.15.5.2 Bar Scaling..............................................................................................................................1576
2.15.5.3 Flash frequencies....................................................................................................................1576
2.15.5.4 I/O field, output format.............................................................................................................1576
2.15.5.5 I/O field, data type of the field content.....................................................................................1577
2.15.5.6 I/O field, field type....................................................................................................................1578
2.15.5.7 Element alignment in check boxes and radio boxes...............................................................1578
2.15.5.8 Color chart...............................................................................................................................1578
2.15.5.9 Format descriptors...................................................................................................................1579
2.15.5.10 Fill pattern...........................................................................................................................1580
2.15.5.11 Line styles..........................................................................................................................1581
2.15.5.12 Line end style.....................................................................................................................1581
2.15.5.13 List types............................................................................................................................1582
2.15.5.14 Language ID.......................................................................................................................1582
2.15.5.15 Text alignment....................................................................................................................1583
2.15.5.16 Tag statuses.......................................................................................................................1583
2.15.6 Structure definitions.................................................................................................................1584
2.15.6.1 Structure definition CCAPErrorExecute...................................................................................1584
2.15.6.2 Structure definition CCAPTime................................................................................................1586
2.15.6.3 Structure definition CMN_ERROR...........................................................................................1587
2.15.6.4 Structure definition DM_TYPEREF..........................................................................................1587
2.15.6.5 Structure definition DM_VAR_UPDATE_STRUCT..................................................................1588
2.15.6.6 Structure definition DM_VAR_UPDATE_STRUCTEX.............................................................1589
2.15.6.7 Structure definition DM_VARKEY............................................................................................1590
2.15.6.8 Structure definition LINKINFO.................................................................................................1591
2.15.6.9 Structure definition MSG_FILTER_STRUCT...........................................................................1592
2.15.6.10 Structure definition MSG_RTDATA_STRUCT....................................................................1595
3 VBA for Automated Configuration...........................................................................................................1597
3.1 Automated configuration..........................................................................................................1597
3.2 Introduction: Using VBA in WinCC..........................................................................................1598
3.2.1 Introduction: Using VBA in WinCC..........................................................................................1598
3.2.2 Differentiation: Using VBA.......................................................................................................1598
Table of contents
WinCC: Scripting (VBS, ANSI-C, VBA)
8 System Manual, 02/2013, A5E32315920-AA
3.2.3 Organizing VBA Code in a WinCC Project..............................................................................1599
3.2.4 How to export and import VBA code.......................................................................................1602
3.2.5 Executing VBA Macros in Graphics Designer.........................................................................1603
3.3 VBA in the Graphics Designer.................................................................................................1605
3.3.1 VBA in the Graphics Designer.................................................................................................1605
3.3.2 Adapting the Graphics Designer with VBA..............................................................................1607
3.3.2.1 Adapting the Graphics Designer with VBA..............................................................................1607
3.3.2.2 Language-Dependent Configuration with VBA........................................................................1608
3.3.2.3 Creating Customized Menus and Toolbars.............................................................................1610
3.3.2.4 Accessing the component library with VBA.............................................................................1630
3.3.3 Editing Pictures with VBA........................................................................................................1638
3.3.3.1 Editing Pictures with VBA........................................................................................................1638
3.3.3.2 How to Create Picture-specific Menus and Toolbars..............................................................1639
3.3.3.3 Editing Layers with VBA..........................................................................................................1641
3.3.3.4 Editing a Copy of a Picture with VBA......................................................................................1642
3.3.4 Editing Objects with VBA.........................................................................................................1644
3.3.4.1 Editing Objects with VBA.........................................................................................................1644
3.3.4.2 Default objects, Smart objects, Windows objects and Tube objects.......................................1646
3.3.4.3 Group Objects.........................................................................................................................1660
3.3.4.4 Customized Objects................................................................................................................1667
3.3.5 Creating Dynamics with VBA...................................................................................................1672
3.3.5.1 Creating Dynamics with VBA...................................................................................................1672
3.3.5.2 Configuring Dynamics in the Properties of Pictures and Objects............................................1673
3.3.5.3 Configuring Event-Driven Actions with VBA............................................................................1685
3.3.5.4 Editing Triggers.......................................................................................................................1693
3.3.6 Event Handling........................................................................................................................1696
3.3.7 Accessing External Applications with VBA..............................................................................1699
3.3.7.1 Accessing External Applications with VBA..............................................................................1699
3.3.7.2 Example: Accessing MS Excel with VBA................................................................................1700
3.4 AddIns.....................................................................................................................................1706
3.4.1 AddIns.....................................................................................................................................1706
3.4.2 Linking Add Ins........................................................................................................................1706
3.4.3 How to Configure an AddIn in the Graphics Designer.............................................................1708
3.4.4 Example: Creating Add Ins......................................................................................................1710
3.4.4.1 Example: Creating Add Ins......................................................................................................1710
3.4.4.2 Example: Creating an Add In with Visual Basic 6.0.................................................................1710
3.5 VBA Reference........................................................................................................................1716
3.5.1 The object model of the Graphics Designer............................................................................1716
3.5.1.1 VBA Reference........................................................................................................................1716
3.5.1.2 VBA Reference: ActionDynamic..............................................................................................1718
3.5.1.3 VBA Reference: HMIObjects...................................................................................................1720
3.5.1.4 VBA Reference: Languages....................................................................................................1722
3.5.1.5 Events......................................................................................................................................1722
3.5.1.6 Methods...................................................................................................................................1757
3.5.1.7 Objects and Lists.....................................................................................................................1858
3.5.1.8 Properties................................................................................................................................2046
3.5.2 VBA in Other WinCC Editors...................................................................................................2464
3.5.2.1 VBA in Other WinCC Editors...................................................................................................2464
3.5.2.2 VBA in Tag Management........................................................................................................2466
3.5.2.3 VBA im Tag Logging................................................................................................................2478
3.5.2.4 VBA in the Text Library............................................................................................................2504
Table of contents
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 9
3.5.2.5 VBA in Alarm Logging.............................................................................................................2517
Index.......................................................................................................................................................2533
Table of contents
WinCC: Scripting (VBS, ANSI-C, VBA)
10 System Manual, 02/2013, A5E32315920-AA
VBS for Creating Procedures and Actions
1
1.1 VBS for creating procedures and actions
Contents
WinCC provides the possibility of dynamizing the Runtime environment using the Visual Basic
Script. It is possible to use VBS to program global actions and procedures as well as
dynamizing graphic objects and triggering actions in Runtime.
This chapter will show you
How to work with VBScript editors
How to create and edit procedures
How to create and edit actions
How to activate VBScripts in Runtime
How to execute diagnostics on scripts in Runtime
The object model of graphic Runtime system
Detailed examples on using VBScript
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 11
1.2 Using Visual Basic Script in WinCC
Introduction
In addition to the C script, WinCC also provides the VBScript program language as a
programming interface in order to make the WinCC Runtime environment dynamic.
Target Group of the Documentation
This documentation is aimed at project engineers with experience of Visual Basic or WinCC
Scriptings (C) used to date.
Application Options
VBScript (VBS) provides access to tags and objects of the graphical Runtime system at
Runtime and can execute picture-independent functions:
Tags: Tag values can be read and written in order, for example, to specify tag values for
the PLC by clicking the mouse when positioned on a button.
Objects: Object properties can be made dynamic using actions and actions can be triggered
by events influencing objects.
Picture-independent Actions: Picture-independent actions can be triggered cyclically or
according to tag values, e.g. for the daily transfer of values into an Excel table.
VBS can be used at the following points in WinCC:
In the Global Script Editor: This is used to configure picture-independent actions and
procedures. The procedures can be used in picture-dependent and picture-independent
actions. Several procedures are compiled in a topic-related module.
In Graphics Designer: Picture-dependent actions can be configured with which the
properties of graphic objects can be made dynamic or caused to respond to events in
Runtime.
In user-defined menus and toolbars: Here you configure procedures called in Runtime using
the menu and toolbars.
Note
Updating Changed Configuration in Runtime
A changed VB script that is connected with "Menus and toolbars" is only updated after
Runtime is restarted.
If you change the properties of "Menus and toolbars" in Runtime, the changes are only
applied in the following cases:
After a picture change, if the configuration change does not affect the basic picture.
When you load another configuration file and reload the modified configuration file.
VBS for Creating Procedures and Actions
1.2 Using Visual Basic Script in WinCC
WinCC: Scripting (VBS, ANSI-C, VBA)
12 System Manual, 02/2013, A5E32315920-AA
Registered Tags in Menus and Toolbars
The registered tags in the scripts of "Menus and toolbars" remain registered when you unselect
the picture. If you read indirectly from a process mapping the tags are registered and
unregistered again when you unselect the picture. However, registered tags in the scripts of
"Menus and toolbars" remain registered when you unselect the picture.
Application Scenarios
VBS can be used in Runtime, for example:
to configure setpoint value specification for tags for the operation of a graphic object in
order to define a value for the PLC by clicking a mouse, for example.
to configure switching the Runtime language for the operation of a graphic object.
to configure the change of color, e.g. cyclically (flashing) or to display statuses (motor on).
Apart from the specific WinCC applications, the general functionality of VBS can also be used
to customize the Windows environment, e.g.:
to transfer data to another application (e.g. Excel).
to start external applications from WinCC.
to create files and folders.
The automation objects in your environment are available with which to customize the Windows
environment.
Note
All the objects supplied with the Windows Script Host (WSH) from Microsoft can be integrated
in the environment using the standard VBS method CreateObject. However, there is no direct
access to the WSH object itself using VBS from WinCC.
There is no guarantee nor WinCC support for the VBS functionality with regard to its
adaptation to the Windows environment.
Limits to Other Programming Languages in WinCC
VBS and C
VBScript can be used in WinCC parallel to C-Script, but do not mix the script types:
VBScripts and C-scripts can be configured within a picture and project.
C-scripts cannot be invoked in VBScripts and vice versa.
VBS provides internal interfaces to tags and picture objects while the C environment
enables access to other WinCC subsystems (e.g. the report system).
VBS and VBA
VBA is used in WinCC Configuration during the configuration in order to adapt Graphics
Designer to your individual requirements and to simplify and automate configuration. VBA
programs only run in the WinCC configuration environment.
VBS for Creating Procedures and Actions
1.2 Using Visual Basic Script in WinCC
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 13
As opposed to VBA, VB scripts only run in WinCC Runtime and, from there, enable access to
graphic objects and tags. Objects and pictures can be neither created nor modified on a
permanent basis in VBS, as opposed to VBA.
The main language-related differences between VBA and VBS are e.g.:
VBS was developed for use in Internet, VBA for the automation of software applications.
The data type of VBS tags is always VARIANT. VBA, on the other hand, differentiates the
individual data types such as INT, DOUBLE, STRING, etc.
Certain language constructs from VBA have been removed from or added to VBS.
Errors are handled differently in VBS compared to VBA.
A complete list of the differences between VBA and VBS is provided in the Appendix in "Basic
Principles of VBScript".
Procedures, Modules and Actions
VBS in WinCC allows the use of procedures, modules and actions to make the Runtime
environment dynamic:
Procedures: Codes are stored in procedures which are then used at several points in the
configuration. Retrieve the code or another procedure in an action by invoking the
procedure name. Procedures can be created in WinCC with or without return values.
Procedures do not have their own trigger, they are always retrieved by an action.
Modules: It is advantageous to compile related procedures to units in modules. Create
modules for procedures, for example, which must be used in a specific picture or belong
to a specific topic, such as auxiliary mathematical functions or database access functions.
Actions: Actions are always activated by a trigger, namely a triggering event. Actions are
configured in graphic object properties, in events which occur on a graphic object or globally
in a project. Codes used several times can be called, in the form of procedures, in actions.
VBS for Creating Procedures and Actions
1.2 Using Visual Basic Script in WinCC
WinCC: Scripting (VBS, ANSI-C, VBA)
14 System Manual, 02/2013, A5E32315920-AA
1.3 Modules and Procedures
Introduction
Procedures are used to make code, created only once, available at several points in a project.
Instead of entering the code several times, simply call in the corresponding procedure. The
code is clearer and easier to maintain.
Related procedures should be stored in modules. When a certain procedure is retrieved via
an action in Runtime, the module that contains that procedure is loaded. Observe the following
when structuring the modules and procedures:
The more modules that must be loaded when a picture is called in, the worse the
performance in Runtime.
The larger a module, the more procedures are contained and, thus, the longer the loading
time for the module.
Organize the modules sensibly, e.g. a module with procedures for a specific system part/
picture.
Another type of structuring of procedures in modules is the functional structuring, e.g. a module
containing mathematical functions. Use this structure, for example, for modules which should
be used globally for projects. The following example illustrates a module containing
mathematical functions derived from the standard functions:
VBS for Creating Procedures and Actions
1.3 Modules and Procedures
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 15
Procedure Features
The procedures in WinCC have the following properties:
They are created and modified by the user.
They can be protected against modification and viewing by means of a password.
They do not have a trigger.
They are stored in a module.
WinCC does not provide predefined procedures, but does provide code templates and
Intellisense, for example, to simplify programming. Procedures differ according to module
assignment in:
Standard procedures apply globally to projects located on the computer on which they were
created.
Project procedures can only be used within the project in which they were created.
VBS for Creating Procedures and Actions
1.3 Modules and Procedures
WinCC: Scripting (VBS, ANSI-C, VBA)
16 System Manual, 02/2013, A5E32315920-AA
Module Features
A module is a file in which one or procedures is stored. The modules in WinCC have the
following properties:
They can be protected against modification and viewing by means of a password.
The have the file extension *.bmo.
Modules differ according to the validity of their procedures in:
Standard Modules: Contain procedures which are globally available to the project. Standard
modules are stored in the WinCC file system under: <WinCC-Installationsverzeichnis>
\ApLib\ScriptLibStd\<Modulname>.bmo
Project Modules: Contain project-specific procedures. Project modules are stored in the
WinCC file system under: <Projektverzeichnis>\ScriptLib\<Modulname>.bmo. Since the
project modules are stored in the project directory, they are copied when the WinCC project
is copied.
Note
If WinCC must be reinstalled and the standard procedures and modules need to be used
again, save the module files prior to the reinstallation in a different directory and copy them
in the relevant WinCC directory after the reinstallation has been completed. Otherwise,
the standard modules in the WinCC installation directory are deleted during the installation
routine.
Using Procedures and Modules
Procedures are used in:
Actions (in Graphics Designer and Global Script)
Other procedures (in Global Script)
User-defined menus and toolbars
Procedures are structured in modules.
See also
Creating and Editing Procedures (Page 37)
VBScript Editors (Page 26)
Basic Principles of VBScript (Page 822)
Actions (Page 18)
Using Visual Basic Script in WinCC (Page 12)
VBS for Creating Procedures and Actions
1.3 Modules and Procedures
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 17
1.4 Actions
Introduction
An action is always started by a trigger. An action, for example, is triggered in Runtime when
an object is operated by a mouse click, a certain time has occurred or a tag has been modified.
Action Features
Actions are defined once in Global Script and then available independent of the picture. Global
Script actions are only valid in the project in which they were defined. Actions linked to a graphic
object are only valid in the picture in which they were defined.
Note
VBS does not currently allow the creation of computer-specific actions.
The following applies for clients in a multi-user system: All global actions configured on a
server are also executed on a client when a project is opened.
The following applies to clients in a distributed system: If actions should be used on a client
computer, copy all the action files in the corresponding project directory on the client.
Actions have the following properties:
Actions are created and modified by the user.
Actions in Global Script can be protected against modification and viewing by means of a
password.
Actions have at least one trigger.
Actions in Global Script have the file extension *.bac.
Global Script actions are stored in the WinCC file system under: <Projektverzeichnis>
\ScriptAct\Aktionsname.bac
Action Trigger
Triggers are required to execute actions in Runtime. A trigger is linked to an action thus forming
the triggering event which calls the action. Actions without triggers will not be carried out.
The following trigger types are available in WinCC:
Timer: Acyclic or cyclic trigger, e.g. for calling a picture or every hour.
Tags: Change of value
Event: Modification of object properties (e.g. change of color) or event on an object (e.g.
mouse click).
VBS for Creating Procedures and Actions
1.4 Actions
WinCC: Scripting (VBS, ANSI-C, VBA)
18 System Manual, 02/2013, A5E32315920-AA
Processing of Actions in Runtime
In Graphics Designer
Two actions of the same type can be executed simultaneously in Runtime. In order, for
example, that cyclic actions are not hindered by an action executed by a mouse click, event
triggered actions and cyclic/tag triggered actions in Graphics Designer are executed
independently of each other.
Note
Please note that synchronization between both action types in WinCC may only be executed
by the DataSet object or by internal WinCC tags. As a result of the separate processing, no
common data area exists between event triggered and cyclic/tag triggered actions.
If processing cyclic actions in pictures, for example, is prevented by a high system load or
another action, the action is started once at the next opportunity. Cycles which are not executed
are not retained in a queue but rejected.
After a change of picture, scripts still running are automatically stopped 1 minute after the
change of picture.
Scripts which are still running when Runtime is terminated are stopped after 5 seconds.
In Global Script
Picture-independent actions from Global Script are executed in Runtime in succession after
being triggered. If an action is triggered while another action is in progress, the second action
is retained in a queue until it can be executed.
Note
Please note that synchronization between actions in Global Script and in Graphics Designer
may only be executed by the DataSet object or by internal WinCC tags. There is no common
data area between the actions in Graphics Designer and in Global Script.
Using the Actions
Actions can be used as follows:
In Global Script The global actions defined here run picture-independent in Runtime.
In Graphics Designer: The actions defined here only run in the configured picture. An action
is configured in Graphics Designer on an object property or an event on a graphic object.
See also
Creating and Editing Actions (Page 53)
Basic Principles of VBScript (Page 822)
Modules and Procedures (Page 15)
Using Visual Basic Script in WinCC (Page 12)
VBS for Creating Procedures and Actions
1.4 Actions
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 19
1.5 Multiple Use of Procedures and Actions
Introduction
An action configured with VBS in WinCC is always valid for the project in which it was defined.
Procedures have the following areas of application:
Standard procedures apply globally to projects located on the computer on which they were
created.
Project procedures can only be used in the project in which they were created. If a project
is copied, the project procedures (modules) are copied together with the project.
Multiple Use of Procedures and Actions
If actions or procedures/modules are to be used in other projects or on other computers, it is
possible either to:
use the "Save As" function to store the action or module in a different project directory or,
for example, on a disk.
to copy the action or module file in Windows Explorer and paste it in the corresponding
project or standard directory on the target computer.
The properties and trigger configured are retained during copying. Copied modules are directly
available in Runtime. Copied actions are executed in Runtime after they have been opened
and stored once.
Note
Tags used in an action or procedure must also be available on the target computer. If the tag
is not available, the action or procedure is not executed.
Procedures which are called in an action must be available on the target computer. If the
procedure is not available, a Runtime error occurs during Runtime.
Storing Procedures
If procedures need to be copied in other project directories in order to be able to use then in
other projects or different computers, observe the storage path of the procedures in the WinCC
file system:
Standard procedures: <WinCC-Installationsverzeichnis>\ApLib\ScriptLibStd
\Modulname.bmo
Project procedures: <Projektverzeichnis>\ScriptLib\Modulname.bmo
Note
Since procedures are always stored in modules, always copy the module (*.bmo) in which
the procedure is contained.
VBS for Creating Procedures and Actions
1.5 Multiple Use of Procedures and Actions
WinCC: Scripting (VBS, ANSI-C, VBA)
20 System Manual, 02/2013, A5E32315920-AA
The copied procedures/modules are visible after updating the Global Script navigation window
(context menu command "Update") or restarting the editor.
Storing Actions
If actions need to be copied in other project directories in order to be able to use then in other
projects or different computers, observe the storage path of the actions in the WinCC file
system:
<Projektverzeichnis>\ScriptAct\Aktionsname.bac
Each action is stored in a separate file. When an action is copied, all the triggers related to it
are also copied.
Note
Only actions created in Global Script are stored in the WinCC file system. Actions which are
programmed in Graphics Designer are always stored with the current picture and cannot be
transferred individually. If a Graphics Designer picture is copied into another project directory,
the actions stored with the picture are also copied.
The copied actions are visible after updating the Global Script navigation window (context
menu command "Update") or restarting the editor.
See also
Modules and Procedures (Page 15)
Renaming a Procedure or Module (Page 51)
Saving a Procedure (Page 49)
Protecting a Module with a Password (Page 48)
How to add module-related information (Page 46)
Using Standard and Project Procedures (Page 45)
How to Write Procedure Codes (Page 42)
Creating a New Procedure (Page 40)
Creating and Editing Procedures (Page 37)
VBS for Creating Procedures and Actions
1.5 Multiple Use of Procedures and Actions
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 21
1.6 Use of CrossReference
CrossReference and Tag Trigger
The CrossReference from WinCC can be used to quickly find all the application points of tags,
even in VBS actions. Tag triggers in actions in Graphics Designer can be "linked" using
CrossReference, i.e. replaced by other tags at all or selected points.
Note
Tags can also be directly linked in Graphics Designer by marking the graphic object and
selecting the "Linking ..." command from the shortcut menu.
Further information on CrossReference is available in the WinCC documentation.
Actions and CrossReference
All the actions used in a picture can be displayed by means of the picture properties. To do
this mark the picture in WinCC Explorer and select the "Properties" shortcut menu command.
After double clicking on an entry, detailed information on the type of dynamics appears.
It is also possible to display all the tags and pictures used in actions by means of the WinCC
CrossReference. CrossReference can also be used for the to link tag connections of Graphics
Designer actions easily.
Tags and CrossReference
All tags addressed with the following standard formulation are automatically compiled by the
CrossReference of WinCC and then listed in the picture properties.
' VBS1
HMIRuntime.Tags("Tagname")
If tags are addressed with different formulations in the code, this can be notified by the following
section of the CrossReference:
' WINCC:TAGNAME_SECTION_START
Const TagNameInAction = "TagName"
' WINCC:TAGNAME_SECTION_END
The section can be inserted in VBS actions as often as required.
Note
It is not possible to guarantee the compilation of combined tag names from the
CrossReference.
VBS for Creating Procedures and Actions
1.6 Use of CrossReference
WinCC: Scripting (VBS, ANSI-C, VBA)
22 System Manual, 02/2013, A5E32315920-AA
Pictures and CrossReference
All pictures addressed with the following standard formulation are automatically compiled by
the CrossReference of WinCC and then listed in the picture properties.
'VBS2
HMIRuntime.BaseScreenName = "Screenname"
If pictures are addressed with different formulations in the code, this can be notified by the
following section of the CrossReference:
' WINCC:SCREENNAME_SECTION_START
Const ScreenNameInAction = "ScreenName"
' WINCC:SCREENNAME_SECTION_END
The section can be inserted in VBS actions as often as required.
Note
Always enter picture names without the extension "PDL" for reasons of compatibility with
future versions.
See also
VBS Reference (Page 109)
VBScript Editors (Page 26)
Basic Principles of VBScript (Page 822)
Actions (Page 18)
Modules and Procedures (Page 15)
Using Visual Basic Script in WinCC (Page 12)
VBS for Creating Procedures and Actions
1.6 Use of CrossReference
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 23
1.7 Using Global Tags in VBS
Introduction
Global tags can be defined in the Global Script Editor which can then be used in all actions
and procedures.
Using Global Tags in Graphics Designer and Global Script
Observe the following conditions when using global tags in Graphics Designer and Global
Script:
In order to use a global tag in an action in Graphics Designer, call in the procedure in which
the tag is defined so that the associated module is loaded in Runtime.
In order to use a global tag in an action in Global Script, at least one procedure must be
activated from the module in at least one global action in which the tag is defined so that
the module is loaded in Global Script Runtime. This does not need to be the procedure in
which the tag was defined.
This process is necessary because actions from Global Script and Graphics Designer are
processed independently of each other in Runtime. There is no common data area between
the two Runtime systems.
If you need to synchronize actions from Global Script and Graphics Designer, use the DataSet
object or internal WinCC tags.
Using Global Tags in Graphics Designer
When using global tags in Graphics Designer, observe the following conditions:
In order to use a global tag in cyclic or tag triggered action in Graphics Designer, call in the
procedure in which the tag is defined. This also applies when the tag has already been
called in an event triggered action.
In order to use a global tag in an event triggered action in Graphics Designer, call in the
procedure in which the tag is defined. This also applies when the tag has already been
called in a cyclic or tag triggered action.
This process is necessary because the cyclic/tag triggered actions and the event triggered
actions in Graphics Designer in Runtime are processed independently of each other in
Runtime. There is no common data area between the two types of action.
If you need to synchronize cyclic or tag-triggered actions and event-triggered actions, use the
DataSet object or internal WinCC tags.
In the case of Graphics Designer, it is also possible to define global tags in a separate
declaration section. Because event-triggered and cyclic/tag-triggered actions are processed
separately in Runtime, the global tags can only be jointly addressed within the event-triggered
or cyclic/tag-triggered actions.
VBS for Creating Procedures and Actions
1.7 Using Global Tags in VBS
WinCC: Scripting (VBS, ANSI-C, VBA)
24 System Manual, 02/2013, A5E32315920-AA
See also
Basic Principles of VBScript (Page 822)
Structure of VBScript Files (Page 95)
Creating and Editing Actions (Page 53)
Creating and Editing Procedures (Page 37)
VBScript Editors (Page 26)
Use of CrossReference (Page 22)
Actions (Page 18)
Modules and Procedures (Page 15)
VBS for Creating Procedures and Actions
1.7 Using Global Tags in VBS
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 25
1.8 VBScript Editors
1.8.1 VBScript Editors
Introduction
VBScripts can be programmed at two points in WinCC:
In Global Script Global Script is the central editor for VBS programming. Call it in via WinCC
Explorer.
In Graphics Designer: Graphics Designer can be used to program actions related to object
properties or events related to graphic objects. The action editor in Graphics Designer is
called in via the context menu in the Properties dialog of a graphic object.
VBS for Creating Procedures and Actions
1.8 VBScript Editors
WinCC: Scripting (VBS, ANSI-C, VBA)
26 System Manual, 02/2013, A5E32315920-AA
Restrictions, Global Script - Graphics Designer
Graphics Designer can be used to program actions and picture-specific procedures but not
global procedures valid for the entire project. However, global procedures which were
programmed in Global Script can be called in.
Note
This documentation is used primarily to describe Global Script and, if necessary, makes
reference to deviations in the functionality compared to Graphics Designer. A detailed
description of the Graphics Designer action editor is provided in the WinCC help topic
"Dynamization".
Further Information
Further information on "Dynamization" is available in the WinCC documentation.
See also
Global Script Editor (Page 27)
1.8.2 Global Script Editor
Introduction
Global procedures and actions are created and edited in the Global Script editor.
Global Script provides a similar range of functions to that of the C script editor in WinCC.
Note
A detailed description of the action editor for the creation of picture-based actions and
procedures in Graphics Designer is provided under the WinCC help topic "Dynamics".
Starting Global Script
Global Script is started using the shortcut menu "Open" command in the WinCC Explorer
project window.
VBS for Creating Procedures and Actions
1.8 VBScript Editors
WinCC: Scripting (VBS, ANSI-C, VBA)
System Manual, 02/2013, A5E32315920-AA 27
Global Script is also automatically started when a module or action is opened by means of a
double click in WinCC Explorer.
Design of Global Script
Global Script editor is designed in accordance with the Windows standards.
The action editor in the Graphics Designer provides a similar range of functions to that of Global
Script. A description of the Graphics Designer action editor is provided in the WinCC help topic
"Dynamization".