Function reference
9 min readScreens and objects
List of all functions that can be bound to events: their parameters, tag type conditions and behavior in Live.
Functions are added to the function list of an event on the Inspector's Events tab with <Add function>. In the list the functions are grouped; the names in parentheses are the Siemens WinCC equivalents of the function. For a description of the events and the rules for how they run, see Events and functions.
Bit operations
| Function | Parameters | Behavior |
|---|---|---|
| Set bit (SetBit) | Tag (Bool) | Writes 1 (true) to the tag. |
| Reset bit (ResetBit) | Tag (Bool) | Writes 0 (false) to the tag. |
| Invert bit (InvertBit) | Tag (Bool) | Writes the inverse of the current value of the tag. |
| Set bit n of an integer tag to 1 (SetBitInTag), … to 0 (ResetBitInTag), … invert (InvertBitInTag) | Tag (Byte, SInt, Int, UInt, DInt, UDInt), Bit number | Reads the value of the tag and changes only the selected bit; the other bits are preserved. The bit number starts at 0 (0 – 7 for an 8-bit type, 0 – 15 for 16-bit, 0 – 31 for 32-bit). If the value of the tag is not reliable (no connection, no value received), no operation is performed and an error is reported. |
Value operations
| Function | Parameters | Behavior |
|---|---|---|
| Set value (SetValue) | Tag, Value | Converts the value to the data type of the tag and writes it. The value is read as a decimal number (the decimal separator is a comma or a period); hexadecimal notation such as 16#FF is valid only in the operator's value input window. A number outside the lower / upper limit of the tag is rejected. |
| Increase value, Decrease value | Tag (numeric), Value (default 1) | Adds / subtracts Value to / from the value of the tag. If Value is empty, not a number or 0, 1 is used. |
| Scale the raw value and write it to a tag (LinearScaling) | Raw tag, Scaled tag, Raw min / max, Scaled min / max | Reads the value of the raw tag, scales it with c + (ham − a) × (d − c) / (b − a) and writes it to the scaled tag. The two end points of the range cannot be the same. |
| Convert the scaled value back to the raw value and write it to a tag (InverseLinearScaling) | same | In the reverse direction: converts the value of the scaled tag back to the raw value and writes it to the raw tag. |
| Write a value to the tag whose name is stored in another tag (SetTagIndirect) | Name tag (String / WString), Value | The value of the name tag is the name (or the ID) of a tag; the Value is written to that tag. In this way the same button writes to the tag selected by the PLC. If the name is empty or there is no tag with this name, it gives an error. |
| Look up text in a text list and write it to a tag (LookupText) | Value tag (numeric), Text list, Text tag (String / WString) | Finds the text corresponding to the number in the value tag in the list and writes it (translated into the runtime language) to the text tag. If there is no match, an empty text is written (Text and graphic lists). |
Screen
| Function | Parameters | Behavior |
|---|---|---|
| Open screen | Screen | Opens the screen in the main area; the previous screen is written to the navigation history. If the selected screen is of type Pop-up window, it opens as a window (the tag prefix of the screen in which the event runs is carried over). If the screen is a draft, is closed to the web in the viewer or requires authorization, a notification / login window appears. |
| Go to previous screen | — | Returns to the previous screen in the navigation history (the last 50 screens are kept). If the history is empty, it does nothing. |
| Open pop-up window (with tag prefix) | Screen, Tag prefix | Opens the screen as a pop-up window. If the tag prefix is empty, the prefix of the event's view is used, and if there is none either, the screen's Design instance is used. Details: Faceplate and pop-up window. |
| Close pop-up window | — | Closes the window in which the event runs; if the event is not in a window, closes the topmost open window. |
| Go to 3D view (value = name of the saved view) | Value | Moves the camera of the 3D scene to the saved view; if Value is empty, it goes to the start view (3D screens). |
| Show / hide layer | Layer (0 – 31), Operation (Show, Hide, Invert) | Shows / hides all objects of a layer on the screen of the event together. If called from a fixed-area screen, it is applied to the main screen. The state lasts until Live is closed and is not written to the project. The initial state is set under Screen properties › Layers. |
Objects and windows
While running in Live, this group changes the property of an object. The change is session-only: it is not written to the project and ends when the screen is closed. 3D objects cannot be targets. If the property is bound to a tag, the binding wins when the value produced by the binding changes afterwards (the check reports this as information). The group does not exist in the event tables of menus and toolbars.
| Function | Parameters | Behavior |
|---|---|---|
| Set object property to a constant (SetPropertyByConstant) | Object, Property, Value | Assigns a fixed value to a property of a 2D object on the screen of the event. The value field varies with the type of the property: on / off, number, color, selection list, text. |
| Set object property from a tag (SetPropertyByTag) | Object, Property, Tag | Assigns the current value of the tag to the property once. Gives an error if the tag is not reliable. |
| Set object property from another object's property (SetPropertyByProperty) | Object, Property, Source object, Source property | Assigns the current value of the source property to the target property; if the types differ, it tries to convert. |
| Show screen in screen window (ActivateScreenInScreenWindow) | Screen window, Screen, Tag prefix | Changes the screen shown by the selected Screen window object. If the object is on another screen, it works while that screen is open (this is how the navigation buttons in a fixed area change the window on the main screen). If the tag prefix is empty, the window's previous prefix is kept. |
The property list contains only properties to which a value can be assigned: those of the types number, on / off, color, selection, text and font, as well as common properties such as Visible, Flashing, Opacity, X, Y, Width, Height and Angle.
Script
| Function | Parameters | Behavior |
|---|---|---|
| Run script | Script, Procedure / function | Runs a script from the project's Scripts section. In a VBS module a Procedure is selected, in C and Python scripts a Function; if left empty, the procedure / function with the same name as the script is called. |
| Run VBS code, Run C code, Run Python code | Code (Edit…) | Runs the code written directly in the event. Item (VBS / Python) or lpszObjectName (C) is the object of the event; ScreenItems and lpszPictureName correspond to the screen of the event. Details: Scripts. |
The next row of the list waits until the script functions have finished (30 seconds at most). In viewer mode, scripts do not run.
System
| Function | Parameters | Behavior |
|---|---|---|
| Acknowledge alarms | — | Acknowledges all pending alarms (Alarm handling). |
| User login | — | Opens the User login window. |
| Logout | — | Logs off the open session. |
| Change Live language (value = language code) | Value | Switches to the language code in the value (tr, en …). If the value is empty, it switches to the next language. For a language that is not defined in the project or that is disabled in the Live settings, an error notification appears (Languages and texts). |
| Exit Live | — | Asks "Close the Live program?" and, if confirmed, closes the program. If an exit authorization is required in the Live settings, a user without that authorization gets a log-on window or an error. |
Recipe and report
The functions of the recipe and report sections are listed in the relevant groups:
- Recipe: Load recipe record to PLC (according to transfer setting), Save PLC values as recipe record, Compare recipe record with PLC (window); parameters Recipe and Record name. Details: Using recipes.
- Report: Create report record (read the field tags now), Open report print preview (print / PDF), Save report to PDF file, Export report records to Excel file; parameter Report. Details: Generating reports.
In the event table of the items in the Menus and toolbars section there are also the functions Open alarm window, Open / close system menu, Open remote monitoring window, Toggle light / dark theme and Print; these do not exist in object events (Menus and toolbars).
Limitations and points to note
- A function acts on a single tag (or a single object); add several rows for several tags.
- Entering
0in the Increase value function does not mean “do not change at all”; 1 is used. - In the viewer, only functions that change screens and assign object properties work (see Events and functions).