Episode 1

“The Code”
 TABLE OF CONTENTS
1 INTRODUCTION ............................................................................................................................ 2
1.1 Restriction .............................................................................................................................. 2
1.2 History.................................................................................................................................... 2
1.3 Related documents................................................................................................................ 2
2 IMPLEMENTING SYMBOLS ......................................................................................................... 3
2.1 Introduction ............................................................................................................................ 3
2.2 Goals...................................................................................................................................... 4
2.3 Create the graphical shapes.................................................................................................. 4
2.4 How not to do it ! .................................................................................................................... 5
2.4.1 Creating the symbol using the Wizard .............................................................................. 6
2.4.2 Disadvantage..................................................................................................................... 8
2.5 Coding from ‘scratch’ ............................................................................................................. 8
2.5.1 Introduction........................................................................................................................ 8
2.5.2 Where to put the code ....................................................................................................... 8
2.5.3 Coding the base functionality ............................................................................................ 9
2.5.4 Testing the symbol .......................................................................................................... 10
2.5.5 Making the symbol (code) dynamic................................................................................. 11
2.5.6 Testing the symbol with dollar parameter ....................................................................... 13
2.5.7 Displaying the alarm status ............................................................................................. 15
2.5.8 Displaying quality ............................................................................................................ 16
2.5.9 Enabling / disabling the buttons ...................................................................................... 18
3 CONNECTING DATA .................................................................................................................. 21
3.1 Introduction .......................................................................................................................... 21
3.2 dpGet()................................................................................................................................. 21
3.3 dpConnect() ......................................................................................................................... 22
3.3.1 Connecting multiple ......................................................................................................... 22
3.3.2 Why the DP in the callback ............................................................................................. 23
3.3.3 dpConnect() with variable argument ............................................................................... 24
3.3.3.1 Solution 1 : ‘For dummies’ ..............................................................................................................26
3.3.3.2 Solution 2 : dyn_... ...........................................................................................................................27
3.4 Connecting to more than data ............................................................................................. 29
3.5 dpQueryConnect...() ............................................................................................................ 30
3.5.1 Setting up a query connect.............................................................................................. 30
3.5.2 Examples......................................................................................................................... 32

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 1 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
1 Introduction
This is the first episode in (hopefully) a long range of new adventures. Each one
describing a certain subject in the beautiful world of PVSS.

This first one is describing various techniques related to the PVSS Control language.
Various examples will hopefully help you to create top quality applications.

“Share the fun”

Agent Mulder
6/7/2008

1.1 Restriction

This document is provided AS-IS and does not replace/correct the

standard PVSS help file. It is not an official document and no rights can
be taken from it.

1.2 History

Author F. Mulder
Version 1
Date 6/7/2008
First version

1.3 Related documents

Document By Description

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 2 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
2 Implementing symbols
2.1 Introduction
The first, and most likely place, where you’ll need ctrl programming are the
symbols/panels in PVSS. Wizards are available to define the dynamics of a graphical
shape. However, a good understanding of the ctrl language helps you to implement
symbols with a maximum performance.

In this chapter we’ll focus on the implementation of an (example) symbol called

‘Light’. This relatively 'simple' symbol holds several features that require various ctrl
techniques that should apply to any symbol you develop.

The ‘Light’ symbol has a very simple specification:

□ The light ( the circle) is yellow when the light is on

□ The light is white when it is off
□ The alarm indicator ( red square ) is visible only when there is an alarm
□ The buttons ‘On’ and ‘Off’ require permission 10
□ The light will be purple when the connection to the PLC is bad

The light assumes a datapoint type ‘Light’ with the following layout:

Note:
A ‘SumAlarm’ is used that combines all the possible alarms in the datapoint. This
makes the coding of the symbol easier.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 3 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Note:
Make some instances of this datapoint type. Throughout this document we’ll assume
that there are datapoints called “light0000” to “light0100”.

2.2 Goals
You should have some goals when implementing symbols.

□ A symbol must have good performance

□ A symbol should have little ctrl code
( more code, means more time maintaining the symbol )
□ The code must look excellent

2.3 Create the graphical shapes

First step, when creating a new symbol, is to create a new panel and add some
shapes to it. In this case:

□ Create a circle and call the shape ‘LIGHT’

□ Add a small rectangle and call it ‘ALARM’
□ Add the 2 buttons and call them BUTTONON and BUTTONOFF

Save this panel as \objects\Light.pnl

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 4 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Note:
Saving a panel under \objects means that it becomes a symbol that you can drag
onto a panel. Choose ‘View – Catalogue’ to see the symbol

2.4 How not to do it !

The ‘easiest’ solution would be to use the Ctrl wizard to add code to the light. Then
use the wizard again to add code to the alarm indicator as well.

Result would be a symbol that has code in several shapes. Also, the performance
wont be at its best, because the symbol has to do 2 dpConnect()’s. ( Where one
would have been enough )

Please note:
The Wizard is an excellent tool. However, use it wisely !

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 5 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
2.4.1 Creating the symbol using the Wizard
The ctrl wizard is an excellent tool to add code to a symbol. However, if you use it
wrong, then you could get a symbol that has many dpConnect()’s, thus having not
the best possible performance.

To use the wizard:

□ Click on the circle

□ Click on event ‘Initialize’
□ Start the Ctrl wizard

In the Ctrl Wizard, choose the option ‘Change color’. Choose the option ‘Background’
and choose ‘Value – dependent’

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 6 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Then select the datapoint element ‘$dp + .Status.On’.

We’ll repeat the same thing for the alarm indicator. Here we again change the
background color. But now we choose the option ‘Alert handling’

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 7 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
2.4.2 Disadvantage
The disadvantage of this method is that the object will have more and more
dpConnect()’s making the total symbol slower.

Also, the symbol has code in several places. This is ok for a very small symbol, but
managing the code becomes more difficult when your symbol becomes more
complex.

2.5 Coding from ‘scratch’

2.5.1 Introduction
This paragraph will show how to code the symbol ‘from scratch’ thus illustrating the
relevant pieces of source code. We’ll start with a very basic symbol, and will then
extend it to include more advanced features like:

□ Indication of sum alarm color

□ Indication of ‘bad’ status

2.5.2 Where to put the code

When you look at the graphical shapes in our symbol, then there are several
‘locations’ where we could leave our code.

(1) We could add the code to the circular shape

(2) We could add code to the alarm indicator
(3) We can type the code in the background of the symbol. This ‘location’ is
clear. ( It can be the same for any symbol you develop )

the disadvantage of locations (1) and (2) is that it is not very clear where the code is
located. A ‘Colleague’ working on the symbol won’t know where you left the code.

This is why method (3) is preferred

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 8 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Note:
An alternative solution would be to add an invisible shape ( example: a small red dot
) to your symbol. This way, you’ll always know where you left the code.
Minor disadvantage : your symbol won’t be ‘wysiwig’ because of the little red dot.

2.5.3 Coding the base functionality

As said before, we’re going to add the code to the background of our symbol.

Click on the background of the symbol, and choose the ‘EventInitialize’ method:

We type the following source code:

Let’s look at the code in more detail:

We first make a ‘simple’ dpConnect to the ‘Status.On’ of any of our

datapoints.
Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 9 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
 Note:
Eventually, we’re going to add a dollar parameter to make our symbol
‘dynamic’ so it can connect to any datapoint.

The dpConnect() would fail when the database doesn’t match the mentioned
datapoint elements in the symbol. Or, the symbol is trying to connect to
datapoint elements that do not exist.

When the dpConnect() fails, then we need to show this in our symbol.
Typically you do this by assigning some color to the shapes in your symbol.

The dpConnect() contained one datapoint element called

‘mp_Light.Status.On”. For every dp element you connect to you’ll get:

- The name of the datapoint element you’ve connected to

- It’s latest value

Note:
When you dpConnect() to N values, then the callback will receive 2*N
arguments. N * (Dp element + value )

2.5.4 Testing the symbol

We’ve connected the symbol to our datapoint ‘light000’. Therefore, we can now
‘Save and run’ our symbol and then check the functionality of the light.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 10 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
 □ Open the Para panel and select the dp element ‘light000.on’
□ Type values ‘0’ and ‘1’ and ensure that the symbol switches between yellow
and white ! ( Note: You can type 'true', false', '0' or '1' )

2.5.5 Making the symbol (code) dynamic

Our initial symbol has a ‘hard’ connection to the datapoint light000. Of course, our
symbol should be able to connect to any of the datapoints of type ‘Light’.

Making the code ‘dynamic’ is done by introducing a dollar parameter into the source
code.

This dollar parameter is like a ‘keyword’. A replacement for this keyword can be
defined when a symbol is dragged into a panel. Any number of keywords can be
defined for a symbol. Of course, more dollar parameters will make the symbol more
flexible but will also mean that you’ll have more to fill in when using the symbol.

You will see the dollar parameter in the ‘Properties’ window.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 11 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
The dollar parameter can have any meaning you need in the source code. Typically:
you’ll use a dollar parameter to connect the symbol to a particular datapoint. But it is
also possible to use dollar parameters as settings for the symbol.

Example:
Dollar parameter ( Description
example)
$dp To define the name of the datapoint that is being
visualized
$SHOW_ALARM A ‘setting’ for a symbol. Value 1 could mean that the
symbol must show an alarm color.
$TEXT_COLOR A ‘setting’ for the symbol. Defines the color that is to
be used for the text shown in the symbol.

We’ll introduce a dollar parameter $dp that connects our code to one specific
datapoint instance.

There are many standard panels in PVSS ( like the 'RefDef' panels ) that use
$dp or $dpe to indicate a datapoint or datapoint element.
Using $dp in your symbols means that you'll be able to use these standard
panels much easier.

The dollar parameter is like a string replacement in our code. The part that we want
to make dynamic is shown below:

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 12 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
The dollar parameter is basically replacing the text “System1:light000”.
( Note: Make sure not(!) to include the dot just after light000 )

The source code with the dollar parameter replacing “light000” looks like:

2.5.6 Testing the symbol with dollar parameter

The graphical editor will ask for the dollar parameter when you drag the symbol into
a panel. Therefore, take the following steps to test the symbol with dollar parameter.

□ Create a new panel

□ Drag the symbol onto the panel
□ For the dollar parameter “$dp” type the value “light0000”
□ “Save and run’ our panel

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 13 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
 Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 14 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
2.5.7 Displaying the alarm status
Our datapoint type “Light” has a sum-alarm in the datapoint element “.SumAlarm”.
The complexity of determining the appropriate alarm status is done by the sum-alarm
mechanism performed by the event manager. Therefore, you do not have to worry
about this yourself in the code of the symbol.

Our datapoint element “.SumAlarm” has a _alert_hdl config.

Note:
The help file will show you what attributes you can find in an alert_hdl config under:
\Reference tables\Datapoint configs\_alert_hdl.

We can directly connect to the ‘actual state color’ of the alarm handling. This will give
us the color that is currently on display in the alarm line. We’ll assign the same color
to our little square alarm indicator.

We change the script code so that it becomes:

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 15 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Let’s look at the code in more detail:

We’ll extend our dpConnect() to include the attribute _act_state_color of the

config _alert_hdl.

Our dpConnect() now contains 2 datapoint elements. Therefore, the callback

will also include 2 * 2 arguments.

We receive the name of the color, or the actual RGB color value.

The current alarm color can be assigned directly to our little alarm indicator.

You could also decide to hide the alarm indicator when there is no current
alarm. This can be achieved quite easily. You can use the fact that the alarm
color will be an empty string, when there is no active alarm. Therefore, you
could extend the code with:

// Make the symbol visible when there is an alarm

ALARM.visible = strlen( AlarmColor );

2.5.8 Displaying quality

Our symbol is tied to a datapoint that is most likely connected to an external device (
a PLC ). The driver that communicates with this external device can mark the value
of the datapoint element as ‘bad’, typically indicating that there is a problem with the
connection.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 16 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
We’ll extend our dpConnect() to include this quality indication.

Let’s look at the new code in more detail:

We’re adding the attribute _bad to our dpConnect(). This attribute will become
true when the driver and/or event manager determine that the quality of the
value is not good ( driver reports error or event manager sees a range
violation )

Our callback gets 2 more arguments. The boolean bBad will become true
when the value is not good.

We assign a color ‘_invalid’ to our symbol when the quality is not good. We
then do a ‘return’ because performing the rest of the code seems not very
useful.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 17 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249

Be careful with the ‘return’ statement.Verify that the correct code is being
executed when the quality changes from bad back to good !

2.5.9 Enabling / disabling the buttons

We’re still left with the 2 buttons that are used to turn the light on and/or off. Our
specification stated that these buttons require permission 10.

An obvious choice would be to enable / disable these buttons in the EventInitialize()

of our symbol.

This method has one major disadvantage : The buttons won’t be enabled / disabled
when the user logs out ( while a panel with symbols stays open ). A better method is
to handle the state of the buttons as follows:

□ Extend the dpConnect() so that the callback function is called whenever the
user logs in or out.
□ Control the state of the buttons in the callback.

We need to connect to the current user name. That is, the user of the current user
interface. The dpConnect() would look like:

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 18 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
The dpConnect() will receive the name of the current user. However, we’re not
interested in this name and are not using this argument.

The permission 10 in this paragraph is just an example. Go to ‘System

Management \ User management’ to define permissions, user groups and
users.
Note that the ‘root’ user will always have all permissions.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 19 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Let’s look at this code in more detail:

This expression evaluates to the datapoint element that holds the user name
logged in to the current user interface.

Example:
_Ui_1.UserName

We receive the current user name but do not really need it. We just need to
connect it so that we are triggered whenever the user logs in or out.

The above example shows that you’d need to extend the dpConnect() so that
the buttons are enabled/disabled the right way. This of course means a bit of
extra work for every symbol you implement.
An easier solution could be to simply change the panel when the user logs in
or out. Example: go back to a panel with a welcome message every time the
user logs out.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 20 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
3 Connecting data
3.1 Introduction
PVSS is event driven. The scripting language contains several options to connect to
data. This chapter will show the methods to connect to one or more datapoint
elements.

This paragraph will show you how to ‘connect’ to data asynchronously. This
means that a ‘callback’ function is triggered when the connected datapoint
elements change.
Make sure not to built in dpGet()’s in your callback since this will highly affect
the performance of your symbol. It is better to extend the dpConnect() (
conect to more values ) than to perform dpGet()’s to get additional values !

3.2 dpGet()
There are basically two ways of getting data : synchronous or asynchronous.
Asynchronous means that you request data, but your script doesn’t wait for it.
Instead, the data will arrive at a later time.

Synchronous means that your script code will wait for the value. This can be done,
for example, with a dpGet() statement.

Example:

There are various situations where performing a dpGet() ( or a dpQuery ) is

excellent. However, the rest of this chapter will focus on the asynchronous methods.

Normally, the asynchronous, that is event- and change-driven, is by far the

preferred solution.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 21 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
3.3 dpConnect()
The most obvious way to get asynchronous data updates is to use the dpConnect().
This statement, which sends a network messages to the event manager, is used to
subscribe to 1 or more values.

The syntax is as follows:

Let’s look at this code in more detail:

The first argument in the dpConnect() is the name of a ctrl function. Any
function name is possible.

A ctrl function must be defined having N * 2 arguments where N is the number

of values you connected in the dpConnect() statement.

There will always be a pair of values.

o First one is the datapoint name of the element you’ve requested
o Second one is the actual value you’ve requested

3.3.1 Connecting multiple

A dpConnect() can contain 1 or more values. The callback will be executed
whenever 1 (or more) of the values have changed.

This could look like:

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 22 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Note: When the dpConnect() is used to request 2 values, then the callback will
contain 2 * 2 = 4 arguments.

3.3.2 Why the DP in the callback

It may seem useless that the callback also receives the DP name that you’ve
requested. Because, why would you need to know the name of the DP when you’ve
defined it yourself in the dpConnect().

This becomes clear when you consider the possibility of using one callback function
for N dpConnect()’s.

Lets assume that we have N datapoints of type Light. We want to send out an email
when one of the lights breaks down.

We do this by implementing 1 generic callback function:

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 23 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
We can then dpConnect() to N Light datapoints, each using the same callback
function:

Our callback function will need to know which datapoint ‘called’ it. This is done by the
following code:

The function dpSubStr will cut out just the datapoint name from the argument strDP
that the callback received.

Traditionally a scada (script) application holds N objects * M lines of code. In

PVSS you only need one callback function that is connected N times.

3.3.3 dpConnect() with variable argument

The dpConnect(), and its callback function, must match in number of arguments. Or,
when the dpConnect() connects to N values, then the callback must have N * 2
arguments.

Lets assume that you have a dpConnect() that sometimes connects to N and
sometimes to M values. This is not possible without a creative solution.

Example:
Let’s assume that we want to have a symbol that displays an analogue value.
Optionally, it can also dpConnect() to a boolean value that makes the symbol visible
or invisible.

The non creative solution would be to have 2 dpConnect() statements. One with just
the analogue value, and one that makes the symbol visible/invisible.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 24 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
This of course has some mayor disadvantages:

□ When you have N optional items to connect to, then you may need 2N
callback functions.

Example:
Lets say that you develop a symbol to enter a float value. You have 2 optional
dollar parameters called "$Visible" and "$Enabled". Optional means that the
engineer may or may not want to use these 2 features.

The engineer could decide to use:

Not use $Visible AND Not use $Enable

Not Use $Visible AND Use $Enable
Use $Visible AND Not use $Enable
Use $Visible AND Use $Enable

In this case, having 2 optional features, means that you would need 22 = 4
different callbacks.

□ The symbol will become slower and slower. It is not wise to add more
dpConnects.
□ The total source code will become ‘spaghetti’

There are different solutions to these tasks.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 25 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
3.3.3.1 Solution 1 : ‘For dummies’
As said before, the dpConnect() and its callback function must have a matching
number of arguments. That is : the dpConnect() and the callback must form a
matching pair.

Also, it is not possible to connect to ‘nothing’. The dpConnect() must refer to actual
datapoints.

A simple solution would be to:

□ When visibility handling is required, then we connect to the corresponding

datapoint.
□ When visibility handling is not used, then we connect to a dummy datapoint !

This would look like:

Let’s look at this code in more detail:

Our local variable initially refers to a dummy datapoint that we’ve created. The
dummy datapoint should have a value that will give you the desired effect in
your callback function.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 26 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
 □

When the symbol requires visibility handling ( bDoVisible == true ) then it sets
the local variable to the name of the actual datapoint.

The advantage of this method is :

□ There will always be just one dpConnect() and just one callback !
□ We give a dummy value to the callback that has exactly the right value.
Therefore, it keeps the callback function simple.

3.3.3.2 Solution 2 : dyn_...

An alternative solution is to connect via dyn_string. That is : we pass a dyn_string of

names to the dpConnect(). The callback will also receive a dyn_string of datapoint
names.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 27 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Let’s look at this code in more detail:

We’re building a dyn_string of datapoint names.

When visibility handling is requested, then the name of the datapoint is added
to the dyn_string as well.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 28 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
 □

When you pass a dyn_string to the dpConnect() then the callback will require
exactly 2 arguments:

o dyn_string strDP

An array of dp element names

o dyn_anytype aValue

an array of values.

3.4 Connecting to more than data

Typically a dpConnect() is used to receive an update from a process value.
However, the dpConnect() can also connect to different items of information.

The dpConnect() can be used to get an update from any attribute of any config.

See the help file under ‘\Reference tables\Datapoint configs’ for a detailed list
of attributes for each possible config.

There’s a large set of attributes that you could connect to. However, there are
probably just a couple of attributes that you’ll encounter frequently.

Attribute Description
Light1.Status:_alert_hdl.._act_state_color The current alarm color
Light1.Status:_alert_hdl.._act_state The current alarm state
Light1.Status:_alert_hdl.._active Alarm enabled or disabled

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 29 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
 Light1.Status:_address.._reference The actual address string

In general, the attribute _type of a config can be used to check whether the
config is actually being used.

Example:
If you want to check whether alert handling is being used then check:

Light1.Status:_alert_hdl.._type

3.5 dpQueryConnect...()
A dpConnect() will request data from an exact specified number of datapoint
elements. You’ll get exactly the data that you’ve requested. Nothing more and
nothing less.

Quite often, you will:

□ Want to connect to many datapoints OR

□ Want to connect to a datapoint that doesn’t exist yet

Both of these requirements can be met by doing a dpQueryConnect. This is like a

‘wildcard connect’. Or, connect to all datapoint elements that match a specified query
string.

The dpQueryConnect..() will give you a callback when one or more values, matching
the specified query, change. This means that the callback function will typically
receive a 2 dimensional array of values.

The advantages of a dpQueryConnect() are:

□ It works like a ‘wildcard connect’. Which means that you don’t have to specify
individual datapoints but adress a whole set of datapoints
□ It will even work for a datapoint that has been newly created
□ Updates can be received as a ‘block’. Typically this would mean less network
traffic.

3.5.1 Setting up a query connect

A ‘query connect’ is different from a dpConnect() because it requires a query string,
and not a distinct set of datapoint elements.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 30 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
Let’s look at this code in more detail:

We start of with a very simple query that gives us the ‘original value’ from all
datapoint elements matching the wildcard ‘*.Status.On’

We perform a dpQueryConnectSingle. Single means that it will only give us

the values that have changed. A dpQueryConnectAll() will always give the
entire set matching the query.

“valueCB”
Is the name of the callback function that will be called.

“true”
Indicates that we want the initial values of all datapoint elements matching the
query

“MyQuery”
Is an identifier that the callback function receives

“Query”
Is the actual query that we want to execute.

The callback function receives : the identifier of the query plus the 2
Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 31 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
 dimensional array with the values we’ve requested.

Every element in the array ‘aResult’ contains one ‘record’. The very first
record does not actually contain data. Instead, it tells you what values have
been requested.

Every record in the result ‘aResult’ contains:

- The name of the datapoint

- The value(s) that you have requested

Normally, you’ll only want to receive the changes. Therefore, the

dpQueryConnectSingle() is the preferred solution.

3.5.2 Examples
This paragraph shows several example queries:

"SELECT '_alert_hdl.._type' FROM '*.**'

WHERE ('_alert_hdl.._type' != 0) AND _LEAF

Returns all datapoint elements that have an _alert_hdl config.

"SELECT '_original.._value' FROM '*.Status.On' WHERE

('_original.._value' == 1)AND _LEAF")

Returns all datapoints that match *.Status.On that currently have the value 1

"SELECT '_original.._value' FROM '*.Status.On' WHERE

('_original.._value' == 1) AND (_DPT == \"Light\") AND _LEAF"

Returns all datapoints that match *.Status.On and are of datapoint type “Light” that
currently have the value 1

" SELECT '.Status.On:_original.._value,

.Alarms.Broken:_original.._value' FROM '*'
WHERE (_DPT == \"Light\")"

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 32 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249
A query that returns 2 elements from selected datapoints.

Note:
This will only work when you add the _DPT clause ! Also, you can only specify one
datapoint type

" SELECT '_online.._value' FROM '*.**.General.Notes' WHERE

(_ELC = DPEL_DYN_STRING) AND (_DP NOT LIKE \"_mp_*\")"

A query to retrieve all elements called *.General.Notes excluding the value in the
master datapoint

"SELECT '_alert_hdl.._active' FROM '*.**' WHERE

('_alert_hdl.._type' != 0) AND _LEAF"

Collect the ‘active’ bit of all datapoint elements that have an _alert_hdl config.

Project: XFiles ETM Benelux B.V. Tel: +31 (0)73 - 523 28 28 Author: F. Mulder
A Siemens Company Fax: +31 (0)73 - 523 28 29
Document: XFiles – 1 – Raadhuisstraat 53 [email protected] Date: 6/7/2008
The Code NL-5241BK Rosmalen www.etm.at
Versie: 1 Page 33 of 34
Status: Released BTW nr. NL8115.29.794.B01
Rek. nr. 48.90.70.469 KvK ‘s-Hertogenbosch
ABN AMRO Bank 17150249