PML FOR STARTERS AND BEGINNERS

DISLAIMER

This tutorial is for those who are using AVEVA PDMS in their day-by-day work and wants to know the
system deeper and automate work and make the system do whatever they wants.
This is for the starters who don’t know about programming at all and for the beginners who can already do
some simple tasks. Those who are experienced PML gurus probably also find something useful.
And for sure this is for any PDMS administrators who must have PML knowledge for better doing their
duties. Enjoy!
Any questions please send – [email protected] (I’ll try to reply everyone but apologies beforehand for
any delay  ).

This tutorial should not be used as a training guide or as a training material. It is only to give a basic
explanation of what is PML, simple constructions etc. User should be trained on a PML training course
provided by AVEVA to get full knowledge needed on starting to make programs.

This tutorial is explaining only the concept and basic of PML but will not be explaining how to create own
forms and functions and complex methods or how to set some environments. This will be described in
another tutorial.

INTRODUCTION
PML (Programmable Macro Language) so called macro-language of PDMS is a PDMS built-in interpreted
programming language which:

 Does most of the actions user run thru PDMS interface – it’s a PML supplied with installation of
PDMS (For example when user press some button then it is PML code executed and do
something)
 Used in any user-defined macros or functions that could be developed by ANY user to create for
example some function that not exist in standard supply but needed for user. (For example user
can create its own GUI – Graphical User Interface like forms, special functions etc)
 Could automate nearly every action, which is repeated by user from day to day and takes much
time to perform – (we will call it “Quick Macro” and use QM abbreviation further in this tutorial)

The main manual describing the PML called Software Customisation Guide for PML basics and Software
Customisation Reference Manual for PML2 objects and their members and methods. Both manuals
supplied with the system

In general every user can learn PML as far as there is no need to have any deep programming skills but
just understanding of:

 PDMS hierarchy concept

 PDMS’s items type
 PDMS’s items attribute dependencies and references
 PDMS terminology and most commonly used words and terms (see Appendix A)

User who wants to know and use PML should have a basic knowledge of PDMS and be familiar with
described points. For example, user should not be scared of word EQUI or ZONE level or Attributes or P-
Point etc. This knowledge could be given on AVEVA’s training course. Contact your nearest AVEVA’s
representative - http://www.aveva.com/en/Contact/Worldwide_Offices.aspx - for training proposal.
In addition, it is needed to know the meaning of simple terms like variable, if statement or do loop. It is
also will be explained here in simple words.

There are two versions of PML language – more ‘old’ called PML1 and a ‘new’ called PML2. We will not
be explaining the difference except that PML2 is object-oriented programming language but will mostly
use PML2 constructions as far as this is more modern language and most GUI is done with it. However
there could be some constructions which are better to be done with PML1 – will be marked.

To write any PML code you should use comfortable for you text editor with feature to show line
numbers and better to syntax highlighting. Author uses Freeware Notepad++. For instructions how
switch on syntax highlighting please email author.

Warning: You should never modify the original PML files, so that you can always revert to using these if
things go wrong.

Warning: Please consider the naming convention for macro files in order to easy navigate and prevent
any conflict with existing files. Some recommended rules for naming:
 Always use a unique prefix in file name. For example author uses his initials (lsa) like
lsamymacro.pmlmac to make the files unique
or another example - a company name like xyzmymacro.pmlmac
 Although it is not mandatory but it is recommended to use extension .pmlmac in macro files
 Starting from PDMS version 12.1 all macroses should be saved in UTF-8 format (Unicode)

PROGRAMMING BASICS
1.Variables
Variables are used to store values.
Variables have names.
The value that is stored can be changed but the name of the variable is fixed once it is defined.
You choose the names and decide what is stored by each variable.
Values can have different types like Integer or String.
Values with different types should be converted to same before processing.

By analogy, the variable could be interpreted as a ‘box’ where you put something to or take something from. And this ‘box’ has
a name to clearly identify what is stored inside. And boxes with same type of content could interact to each other.

Names of variables in PML should start with ‘!’ symbol and have meaningful name.
Examples:
!boxHeight
!boxDescription
!equipName
etc

To assign a value to variable (to put something in a ‘box’) you have to decide what type of data it will be.
Most used types are:
  <STRING> - the value should be put within single quotes or vertical bars, could not be used in
arithmetical expressions unless converted to <REAL>
 <REAL> - any integer value, could be used I arithmetical expressions. Could not be used in string
operations unless converted to <STRING>
 <DBREF> - this is a special PDMS type pointed to an object in database with all its attributes

There are many others but we will use this on start.

To assign value use ‘=’ and value:

!boxHeight = 1000
Here we created variable called !boxHeight and assign a value 1000 with no single quotes, as a digits so it means variable !boxHeight will have
a <REAL> type

!boxDescription = ‘This is my box’

Here we created variable called !boxDescription and assign a value ‘This is my box’ within single quotes, so it means variable !boxDescription
will have a <STRING> type

!equipName = /E1201
Here we created variable called !equipName and assign a value /E1201 with no single quotes but with a slash in front, so it means variable
!equipName will have a <DBREF> type
NB. Pointing the slash as a first symbol will automatically give to the system a signal that you try to refer to some item with this name. So if
there is no item with such name then it will be an error.

Now we have three variables of different types. So what can we do with them? Lets review some
arithmetical operations… Like it was said before only variables with type <REAL> can be involved into
these operations. All others should be converted to <REAL> (if possible) before.

The following example will be used to find a volume (V) of a box with known different sides (a,b,c)

The formula for calculating of box volume is:

V = a*b*c

So let do some practice using variables in PML…

Example 1. Values of variables are hardly defined in code

First, define three variable of <REAL> type. Imagine we know their values and they are constant

!aSide = 1000
!bSide = 500
!cSide = 300

Now we have to create an arithmetical expression for calculation and result should be stored in another
variable. Normally it could be done like:
!boxVolume = !aSide * !bSide * !cSide

So we defined variable !boxVolume which will store result of calculations of several variables
Let check it in PDMS.
Create a file called regarding your naming conventions (in my case it will lsaPML1.pmlmac) in any folder
you have access (in my case it will be c:\temp\pmlexamples\) with following code:

!aSide = 1000
!bSide = 500
!cSide = 300

!boxVolume = !aSide * !bSide * !cSide

q var !boxVolume

The last command means to query (q) early-defined variable (var) with some name. Result of querying
will be output to PDMS’s command line.

Now try to run this. Open command line and type - $M/path_to_your_file
In my case it will be - $M/C:\temp\pmlexamples\lsaPML1.pmlmac

And look at result!

NB.By default all dimension and distance units are in mm.

NB.Nearly every variable storing non-<STRING> type of data can be converted to <STRING>
Only digits stored as a <STRING> can be converted to <REAL>

This is your first PML program!

Example 2. Values of variables input by user

In first example, values of variables were defined within PML code as constants. However, variables
called variables because then can change their values. So in our second example we will review how the
program can interact with user let him put values. We will use alerts for that.

Alert – is a message popping up on a screen and asking user to interact. In our case we will use Input
dialog. Let see how it works.

Imagine the situation when our volume has 2 constant sides (a,b) and one which could vary by user
input. Then our code will look like:

!aSide = 1000
!bSide = 500

!cSide = !!Alert.Input(‘Please input the C-side’,’300’)

Here we created variable called !cSide which accept value after user put something in dialog window. 300 is a default value.
NB. Value you put in dialog window will have type <STRING> means !cSide variable will have type <STRING> then in our further calculation we
will have to convert it to <REAL>.

Complete code will look like

!aSide = 1000
!bSide = 500
!cSide = !!Alert.Input(‘Please input the C-side’,’300’)

!boxVolume = !aSide * !bSide * !cSide.Real()

q var !boxVolume

Save this code to next macro file and run in PDMS like it was done previously with $M/
Using ‘.’ and some method we can do some operation applying it to variables of different type. In
example we used method .Real() applied to <STRING> variable to convert it into <REAL>. Full list of
methods listed in Software Customisation Reference Guide

Feeling the magic already? To be continued 

2.IF statements
IF statement is used to let the system compare two values and by the result of comparison we can select
what to do.
Normally values of variables are compared.
<REAL> should be compared with <REAL>, <STRING> with <STRING> etc.
Result of comparison is TRUE (statement is TRUE) or FALSE (if statement is FALSE)

By analogy, remember our ‘variable-box’? Imagine that one ‘box’ contains an apple and other ‘box’ contains a peach. You want
to eat an apple but you don’t know which ‘box’ stores it. You have to check. So you put your arm into one box and IF you find an
apple THEN you eat it ELSE (peach) you do nothing.

In very basic IF statement looks like:

If (comparison_expression) then
And in between you have to put PML code which will be executed if comparison_expression is TRUE
Else
Do something else
Then close statement with
endif

Each IF should have its ENDIF!

Example 3. Do some action depends on variable value

Imagine the situation that we have to show some message to user if the value some variable equal to 2.
And another message if it is differs from 2. And we let user input this variable

!userVariable = !!Alert.Input(‘Please input the any value’,’3’)

Here we let user input value for variable !userVariable

Now we will compare the value of the input with 2. Not forgetting to convert input to <REAL>
If (!userVariable.Real() EQ 2) then
!!Alert.Message(‘You have input correct value’)
Else
!!Alert.Message(‘You have input incorrect value. Please put 2’)
RETURN
endif
Here we used IF statement to check if our input variable is EQual to 2. We have used EQ operator to check for equality. If result of statement is
FALSE then we un another message and quir from the program execution by using command RETURN. We user another type of Alert –
Message to output a simple message on a screen)

Complete code will look like:

!userVariable = !!Alert.Input(‘Please input the any value’,’3’)
If (!userVariable.Real() EQ 2) then
!!Alert.Message(‘You have input correct value’)
Else
!!Alert.Message(‘You have input incorrect value. Please put 2’)
RETURN
endif
Save this code to next macro file and run in PDMS like it was done previously with $M/

Operators used in comparison are:

 EQ – check for equality (all type)
 NEQ – check for non-equality (all types)
 GT – Greater Than (for <REAL>)
 GEQ – Greater or EQual (for <REAL>)
 LT – Less Than (for <REAL>)
 LEQ – Less or EQual (for <REAL>)

Quick examples of comparisons. Imagine we have two variable one is called !realVariable which stores
some <REAL> value and the other is !stringVariable which stores some <STRING> value. And we will
compare them to some values.

If (!realVariable EQ 10) then

Do something if !realVariable value is 10
Endif
If (!realVariable NEQ 10) then
Do something if !realVariable value is not 10
Endif

If (!stringVariable EQ ‘a string’) then

Do something if !stringVarialbe is ‘a string’
endif
If (!stringVariable NEQ ‘a string’) then
Do something if !stringVarialbe is not ‘a string’
endif

3.DO LOOP
DO LOOP is used to perform actions over multiple (collection) items
Usually collection is an ARRAY variable each cell of which contains some data of particular type like
ARRAY of <STRING>s or ARRAY of <REAL>s.

To define array you can use a simple construction like:

!arrayOfStrings[1] = ‘String1’
!arrayOfStrings[2] = ‘String2’
!arrayOfStrings[3] = ‘String3’
Here we have defined an array of three cells. Each cell has a value of <STRING> type

By analogy, remember our ‘variable-box’? Imagine that this ‘box’ contains 10 apples and we have to check if all ten are fresh.
We can do it by picking them up one by one and do check. DO LOOP is doing the same – you have a collection and one by one
you doing same actions on each item in collection

Very basic DO LOOP could look like:

Do !x from 1 to 10
Do here something 10 times
enddo
We have started DO LOOP which has its start from 1 index and do some actions 10 times

Each DO should have its ENDDO!

Example 4. Output 5 messages with index number one by one
Imagine the situation that we have to show 5 messages to user. On each message, you have to show
index number from our DO LOOP

--start our do loop counting from 1 till 5

Do !x from 1 to 5
!!Alert.Message(‘Next index number is ‘ + !x.String)
Enddo
Here we used output of a message with concatenation of two strings – constant string between single quotes and variable called !x which is DO
LOOP index and which is changing its value from 1 to 5 with step 1 (1 2 3 4 %)

As a result, you will get 5 messages on a screen. One by one until DO LOOP ends on 5

4.COMBINATIONS
You can now combine IF statement and DO LOOP.

Example 5. Check number from 1 to 5 and output only even values

Imagine the situation that we have to output in a message only even values from a range. Here is a code
with comments how to do it

--Let first define a constant ARRAY of digits

!digitArray[1] = 1
!digitArray[2] = 2
!digitArray[3] = 3
!digitArray[4] = 4
!digitArray[5] = 5

--Now we have an array of 5 cells. That means Size of array equal to 5.

--Now we have to pass thru each cell of arrya, check it values and if it is even – output it
--To do it we now define DO LOOP counting from 1 to ??
--TRUE! the end of DO LOOP will be a size of array (that is number of cells).

--To get the Size we will introduce another variable for storing this values can use a method called .Size() applied to earlier defined ARRAY
--Here it is:
!digitArraySize = !digitArray.Size()

--Now start do loop:

Do !x from 1 to !digitArraySize

--To understand if the value is even or odd we have to take value and try to divide by 2
--if result of the division will contain a decimal point then value was odd otherwise it was even
--lets do it

--first make a division (remember in each iteration !x will have a next value) and this is <REAL> type
!resultOfDivision = !x / 2

--check for point. We will use MATCHWILD method which is applied to STRING object to find if there something we’d like to find
--so we also will be converting result of division stored in previous variable to <STRING> type
!isThereAPoint = !resultOfDivision.String().Matchwild(‘*.*’)
--so previous variable will store TRUE if variable !resultOfDivision contain point and FALSE – if not

--now start IF statement to make action depends on !isThereAPoint variable’s value

--and we will be using SKIP to let DO LOOP skip current index and take next if value is odd
 If (!isThereAPoint NEQ TRUE) THEN
--If its even then compose and output a message
!!Alert.Message(‘Value is ‘ + !x.String() + ‘ and its even.’)
Else
SKIP
endif

Enddo

Complete code look like

!digitArray[1] = 1
!digitArray[2] = 2
!digitArray[3] = 3
!digitArray[4] = 4
!digitArray[5] = 5

!digitArraySize = !digitArray.Size()

Do !x from 1 to !digitArraySize

!resultOfDivision = !x / 2

!isThereAPoint = !resultOfDivision.String().Matchwild('*.*')

If (!isThereAPoint NEQ TRUE) THEN

!!Alert.Message('Value is ' + !x.String() + ' and its even.')
Else
SKIP
endif

Enddo

Or we can even shorten to skip intermediate variables like

!digitArray[1] = 1
!digitArray[2] = 2
!digitArrya[3] = 3
!digitArray[4] = 4
!digitArray[5] = 5

Do !x from 1 to !digitArray.Size()

!resultOfDivision = !x / 2

!isThereAPoint = !resultOfDivision.String().Matchwild('*.*')

If (!resultOfDivision.String().Matchwild('*.*').Not()) THEN
!!Alert.Message('Value is ' + !x.String() + ' and its even.')
Else
SKIP
endif

Enddo
Or even shorter
--put number in a <STRING> then split it and get array
!stringNumber = ‘1 2 3 4 5’
!digitArray = !stringNumber.Split()

Do !x from 1 to !digitArray.Size()

!resultOfDivision = !x / 2

!isThereAPoint = !resultOfDivision.String().Matchwild('*.*')

If (!resultOfDivision.String().Matchwild('*.*').Not()) THEN
!!Alert.Message('Value is ' + !x.String() + ' and its even.')
Else
SKIP
endif

Enddo

TO BE CONTINUED…