Material-PML Training-Macros and Functions-REV06

PML Training – Macros and Functions
Mansu Jung
Senior Application Consultant
www.aveva.com
Objectives
▪ Broad overview of the PML language

▪ Basic coding practices and conventions
▪ How PML interacts with the Design model
▪ How Forms and Menus work with PML
Copyright © 2015 AVEVA Solutions Limited and its subsidiaries. All rights reserved.
Contents
▪ Introduction to Dabacon
▪ PML Overview
▪ PML Objects
▪ Macros, Synonyms and Control Logic
▪ PML Functions
▪ Collections
▪ Miscellaneous
▪ Exercise
Introduction to
Dabacon
Copyright © 2015 AVEVA Solutions

Limited and its subsidiaries.
All rights reserved.
Where did this data come from?
DABACON
Database system designed for AVEVA Plant and Marine
DABACON
▪ DABACON (DAtaBAse CONstructor) is the database
management system for both AVEVA Plant and Marine. It is
used to construct, navigate and interrogate a database
structure.
Dabacon elements can be
manipulated by users.
For example,
You could simply modify attributes of multiple elements at once
Or you could create your own utilities for effective design
Then how can you do all these?
You need to be familiar with
PML
Customisation language designed for AVEVA Plant and Marine
PML Overview

PML
▪ Programmable Macro Language (PML) is the

customisation language used by AVEVA Plant and
Marine and it provides a mechanism for users to
add their own functionality to the AVEVA Plant and
Marine software family.
▪ This functionality could be as simple as a re-
naming macro, or as complex a complete user-
defined application
PML - Keywords
▪ PML1
– The first version of PML based on command syntax. String
based and provides IF statement, loops, variables & error
handling
▪ PML2
– Object oriented language extending the ability of PML. Use
of functions, objects and methods to process information
▪ PML .NET
– Provides the platform in PML to display and use objects
created in other .NET languages
▪ Forms
– Most applications are driven by forms and menus. Most
PML will be based on a form.
PML 1 style macros
▪ Macros are ASCII files containing PDMS commands

in sequence
▪ Programmable macros are macros containing
program constructs such as IF statements and
DO loops
▪ Macros are run in PDMS by $m/FILENAME
▪ Any extra bits on a macro line are treated as
parameters
$M/BUILDBOX 100 200 300

– means that the extra 3 values after the macro name are
treated as parameters 1 2 and 3. These can be used within
the macro to set PDMS attributes or as calculations
Examples of Command Syntax
▪ To find out attribute information about the current element
– Q ATT
▪ To add the current element to the drawlist
– ADD CE
▪ To remove all the elements from the drawlist
– REM ALL
▪ To label the current element with its name,
– MARK CE
▪ To remove the label from the current element
– UNMARK CE
▪ To remove all labels
– UNMARK ALL
Examples of Command Syntax
▪ To apply the standard enhance colour to the current element
– ENHANCE CE / UNENHANCE CE
▪ To apply colour 10 to element /PIPE
– ENHANCE /PIPE COL 10
▪ To draw an unnumbered graphic aid line
– AID LINE NUMBER 1 E0N0U0 TO E0N1000U1000
▪ To remove the graphical aid lines numbered as 1
– AID CLEAR LINE 1
▪ To relatively move the current element east by 1000mm
– BY E 1000
▪ To explicitly position the current element
– AT E0 N1000 U2000
Command Syntax Graphs
▪ Throughout the reference manuals supplied with

PDMS, there are numerous syntax graphs to explain
how the put the syntax together.
PML2 - A More Powerful Language
▪ PML2 is more like other modern languages.
▪ Typically, fewer lines of code needed with PML2
▪ Designed to be easier to read and easier to write
▪ Most PML1 macros will still run under PML2
▪ PML2 contains many new features, but not in PML1
PML2 Jargon
Functions
Objects
Object Blocks
PMLLIB
.pmlfrm
Features Of PML2
▪ New Variable Types - STRING, REAL, BOOLEAN,

ARRAY
▪ Built in Methods for commonly used actions
▪ New Global Functions supersede old style macros
▪ User Defined Object Types
▪ New PML Search Path (PMLLIB)
▪ Dynamic Loading of Forms, Functions and Objects
▪ New Aid objects for geometric modelling
Examples of object-orientated PML
▪ To declare a local variable as a REAL 3

– !realVariable = 3
▪ To find out the value of an object
– q var !exampleObject
▪ To find out what methods are available on an
object
– q var !exampleObject.methods()
▪ To find out what members an object has
– q var !exampleObject.attributes()
▪ To delete an object that is no longer needed
– !exampleObject.delete()
Software Customisation Manual
▪ Many of the supplied object types are explained in

the Software Customisation Reference Manual.
▪ Found in the Manuals folder of the installation
directory
PML Objects
▪ Every variable in PML has an object type.

▪ Three groups of types available:
– Built-in (e.g. String, Real, Boolean and Array)

– System-defined (e.g. Position, Orientation)
– User-defined
▪ User defined objects provide an opportunity to

group together common information be easier use.
Variables
▪ Named variables
– !variablename or !!variablename
– single ! Means a local variable (can only be seen in the current macro)
– double !! Means a global variable
▪ Variable names may be up to 16 characters long and the

names can contain alpha and numeric characters
▪ NEVER start a variable name with a number

▪ NEVER use . in variable names
Declaring Variables
▪ To create a LOCAL, STRING variable

!Name = ‘Fred’
▪ To create a GLOBAL, REAL variable:

!!Answer = 42
▪ To create a GLOBAL, BOOLEAN variable:

!!Flag = TRUE
▪ To create a LOCAL empty ARRAY

!Values = ARRAY()
!Values[1] = |xxx| or !Values[1] = ‘xxx’
Using PML Objects
▪ Every variable defined in PDMS has an object type

▪ If a variable is declared as an object, it becomes an
instance of it and has all of the members and
methods
!newPlant = object FACTORY()

!newPlant.name = |ProcessA|
!newPlant.workers = 451
!newPlant.output = 2000
q var !newPlant.workers
<REAL> 451
Naming Conventions
▪ It is common practice to given meanful names to

your objects and variable names e.g
– If the object is WORKERS; Variable might be
numberOfWorkers
▪ AVEVA use a prefix of CD on most of its global
variables, although newer functionality may not.
▪ All new global variable and object names should be
checked against standard product
Special Objects
▪ In a standard PDMS DESIGN session, there are

number of specialised objects which are loaded and
used by standard product. These objects should not
be deleted or overwritten, but are available for use.
The particularly useful objects are:
– !!CE - a global DBREF object which tracks and represents the

current element
– !!ALERT - used to provide popup feedback to users
– !!AIDNUMBERS - used to manage aid graphics
PML Functions and Methods
▪ Functions and methods provide the action of PML

▪ A function is GLOBAL, while and method belongs to an
object
▪ They can accept arguments and return answers
▪ For example:
define function !!area(!len is REAL,!wid is REAL) is

REAL
!area = !len * !wid
return !area
endfunction
!area = !!area(12, 200)

PML Forms
▪ Forms are objects that are stored as global variables

▪ They provide the user interface to PDMS
▪ They can own members (i.e. the gadgets) and methods
▪ For example:
setup form !!nameCE
!this.formTitle = |Name CE|
button .button |Print Name Of CE| call |!this.print()|
exit
define method .print()

q var !!ce.flnn
endmethod
PML1 Hierarchy
▪ PDMSUI Variable
▪ Set PDMSUI=C:\AVEVA\Plant\PDMS12.1.1\pdmsui’
DES DRA ADMIN CLIB….
GEN ADMIN PIPE EQUI….
$S CALLP=$M/%PDMSUI%/DES/PIPE/$s1
CALLP MPIPE
PML2 Functions, Forms and Objects
▪ PMLLIB Variable
▪ Set PMLLIB=C:\AVEVA\Plant\PDMS12.1.1\pmllib
pmllib
functions forms objects

xxx.pmlfnc xxx.pmlfrm xxx.pmlobj
▪ 3 new file extensions .pmlfnc .pmlfrm .pmlobj

▪ These files can be loaded and run just by calling
them: call !!mymac() runs file mymac.pmlfnc
Exercise – Updating the Environment Variables
1 ▪ Extract the provided files into the folder a suitable folder, for
example C:\temp\
▪ Right –click on the icon that opens PDMS. Choose Open File Location
▪ This can also be found from the Properties… form
2 ▪ Open the file in a suitable text editor

▪ Add the following lines to pdms.bat (somewhere after the line that
calls evars.bat)
set PDMSUI=c:\temp\pdmsui %pdmsui%
set PMLLIB=c:\temp\pmllib %pmllib%
▪ Save the .bat as a new file to the computers desktop. This is now the
icon you will use to enter PDMS.
PML Objects

What is a PML object?
▪ A PML object is a grouping of common information

and/or methods for easier use and reference.
▪ The two major aspects of a PML object are:
– Object Members
: The properties of the object, used to hold its definition
– Object Methods
: The actions available on the object
▪ Example
Example of PML objects available in PDMS
▪ PML objects are available across PDMS to

standardise code. These objects include:
– GPHLINE – an object to represent a graphical line

• Members – tag, line, colour, style
• Methods - .definition(), draw(), edit()
– GPHDRAWLISTS – an object to represent and control the
PDMS drawlists
• Members – drawlists, debug
• Methods – .attachView(), .createDrawlist(), .list(), .saveall()
– VOLUME – an object to represent the volume occupied by an
element
• Members – to, from
• Methods - .box(), .cable(), .volume()
Example of PML objects available in PDMS
▪ To investigate these objects, type the following into

the command window:
!gphline = object GPHLINE()

q var !gphline.attributes()
q var !!gphline.methods()
q var !!gphdrawlists.attributes()
q var !!gphdrawlists.methods()
!volume = object VOLUME(!!ce)
q var !volume.attributes()
q var !volume.methods()
Why are PML objects used?
▪ By using PML objects, common code can be isolated,

allowing it to be shared and reused. This reuse
means that task-specific code can be reduced,
relying on the generic object code to perform the
bulk of the effort. This will ultimately create code
that is easier to manage and maintain.
▪ PML objects can also be used to used to solve

complex problems by representing actual objects in
the real world. Consider how a complex problem,
such as particle motion could be solved by modelled
wach particle as an object.
How is a PML object used?
▪ In this arrangement, the PDMS user interacts with the form to

enter the required changes. The form methods supply the
entered information to the PML object, which processes the
information and updates the PDMS element. Once updated,
the new information is held by the object and sent back to the
form to be displayed to the user.
▪ It allows the PML object to be created and tested separately
from the PML form. It also means that the PML object can be
designed to work with multiple forms.
Exercise – Creating an Object
define object GETELEMENTINFORMATION
member .element is DBREF
member .name is STRING
member .type is STRING
member .position is POSITION
endobject
define method .getinformation()

!this.element = !!ce
!this.name = !!ce.name
!this.type = !!ce.type
!this.position = !!ce.position
endfunction
Macros,
Synonyms and
Control Logic

A Simple Macro
A macro is simply a file containing commands
ASCII file NEW EQUIP /ABCD

SimpleMac.mac NEW BOX
XLEN 300 YLEN 400 ZLEN 600
NEW CYL DIA 400 HEI 600
CONN P1 TO P2 OF PREV
To run a macro:
$M/%PDMSUI%\examples\simpleMac.mac
Finding examples of command syntax
▪ If you are not sure of the PDMS Commands you could use one
of the following to find some examples:
– DB Listings Utility
– $Q syntax
– Using standard product
– Reference Manuals
Communicating With AVEVA Products in PML
▪ All commands need to be supplied to the command

processor as STRINGS.
▪ To expand the contents of a PML variable into a string

(put a $ infront of it!)
e.g. !CompType = ‘ELBO’

!dist = 5600
NEW $!CompType
DIST $!dist
A Parameterised Macro
▪ Macros can be parameterised
ASCII file NEW EQUIP /$1

ParameterMac.mac NEW BOX
XLEN $2 YLEN $3 ZLEN $4
NEW CYL DIA $3 HEI $4
CONN P1 TO P2 OF PREV
▪ To run a macro with parameters:

$M/%PDMSUI%\examples\parameterMac.mac ABCD 300 400 600
More on macros (1)
▪ Macros may have up to 9 parameters separated by

space.
$M/c:\NinePara.mac ABC DEF GHK 55 66 77 88 99 00
▪ Text strings may be entered as a single parameter

$M/c:\SevenPara.mac $<ABC DEF GHK$> 55 66 77 88 99 00
▪ $< $> act as delimiters and anything in between is

interpreted as a single parameter
More on macros (2)
▪ Defaults parameters can be stored within the

macro.
$d1 = 1
$d2 = 10
▪ $d syntax is used followed by the parameter

number. If no parameters are passed to macro,
these values will be used instead.
▪ Default values should be defined once, at the top of

the macro
Variables
▪ Numbered Variable types.

– var 1 name
– var 2 ‘hello’
– var 3 (99)
– var 4 (99 * 3 / 6 + 0.5)
– var 117 pos in site
– var 118 (name of owner of owner)
– var 119 ‘hello ’ + ‘world ‘ + ‘how are you’
Setting PML 1 style variables
▪ Takes the current element’s (CE) name

VAR !NAME NAME
▪ Takes CE position relative to world coordinates

VAR !POS POS IN WORLD
▪ Sets the variable to the text string NAME

VAR !x ‘NAME’
▪ NOTE: Quotes ‘ ‘ or vertical bars | | may be used as

text delimiters
Setting PML 2 style variables
▪ Takes the current element’s (CE) name

!name = !!ce.name
▪ Takes CE position relative to world coordinates

!pos = !!ce.pos.wrt(/*)
▪ Sets the variable to the text string NAME

!x = |NAME|
Expressions
▪ Expressions are calculations using PML variables.
▪ The PML1 way is:

VAR !Z ( ‘$!X’ + ‘$!Y’ )
▪ NOTE: in this case !Z is a STRING object
▪ The PML2 way is

!Z = !X + !Y
▪ NOTE: in this case !Z is REAL and !X and !Y must be

real.
Expression Operators – PML 1 style
▪ Expression operators
+ - / *
LT GT EQ NE LE GE
NOT AND OR
SIN COS TAN SQR POW NEGATE ASIN ACOS ATAN LOG
ALOG ABS INT NINT
!s = 30 * sin(45)
!t = pow(20,2) (raise 20 to the power 2 =400)
!f = (match(name of owner,’LPX’)gt 0)
Expression Operators – PML 2 style
▪ Expression operators (now REAL object methods)

+ - / *
.lt() .gt() .eq() .neq() .leq() .geq()
.not() .and() .or()
.sine() .cosine() .tangent() .sqrt() .power()
.asin() .acos() .atan() .log() .alog() .abs()
.int() .nint()
!a = 45
!s = 30 * !a.sine()
!b = 20
!t = !b.power(2)
Operator Precidence
()
* /
+ -
EQ NE GT LT GE LE
NOT
AND
OR
60 * 2 / 3 + 5 = 45
60 *( 2 / ( 3 + 5)) = 15
PML 2 Expressions
▪ PML 2 expressions may be of any complexity

▪ May contain calls to PML Functions and Methods
▪ May include Form gadget values, object members
and methods
For example:
!newVal = !!myFunc(!oldVal) * !!form.gadget.val /

!myArray.method()
Arrays
▪ An ARRAY variable can contain many

values, each of which is called an ARRAY
ELEMENT. !x[1] = |ABCD|
!x[2] = |DEFG|
▪ An array is created automatically by !y[1] = |1234|
creating one of its array elements. !y[2] = |5678|
!z[1] = !x
!z[2] = !y
▪ An array element may itself be an array
i.e. Multi - dimensional Arrays
q var !z[1][2]
<string> ‘DEFG’
q var !z[2][2]
<string> ‘5678’
The & Concatenation Operator
▪ Values to be concatenated are automatically converted to

STRING by the & operator.
!a = 64
!b = 32
!c = !a & !b
q var !c
!d = !a + !b
q var !d
Do loops (1)
▪ A DO loop is used to repeat code. This can either be done a

fixed number of times, or until a break condition is met.
▪ Example: DoLoop.mac
DO !loopCounter FROM 1 TO 10
!value = !loopCounter * 2
q var !loopCounter !value
ENDDO
Do loops (2)
▪ It is possible to start a loop with stating a range. In this case, the

loop will continue until a break condition is met.
▪ Example: DoBreak.mac
!n = 0
DO
!n = !n + 1
!value = POW(!n, 2)
q var !value
BREAK IF (!value GT 1000)
ENDDO
Do loops (3)
▪ It is possible to skip parts of the loop which do not meet certain

conditions.
▪ Example: DoSkip.mac
DO !n FROM 1 TO 25
SKIP IF (!n LE 5) OR (!n GT 15)
q var !n
ENDDO
Do Loops (4)
▪ Do Index and Do Values are ways of looping

through arrays.
DO !X values !ARRAY
!X takes each ARRAY element
ENDDO
DO !X INDICES !ARRAY
!X takes a number from 1 to !ARRAY size
ENDDO
Do Loops – Array Example
VAR !Zones COLL ALL ZONES FOR SITE
VAR !Names EVAL NAME FOR ALL FROM !Zones
q var !Names
DO !x VALUES !Names
q var !x
ENDDO
DO !x INDICES !Names
q var !Names[!x]
ENDDO
IF Statements (1)
▪ The IF statement is a construct for conditional

execution of commands.
▪ The simplest form of the if construct.

IF ( expression ) THEN PDMS Commands
▪ For example:
IF ( !Number LT 0 ) THEN
!Negative = TRUE
ENDIF
IF Statements (2)
▪ The ELSEIF commands are IF ($1 EQ 0) THEN
optional, once one of them $p Your value is zero
has been found to be TRUE,
any remaining are ignored. ELSEIF ($1 LT 0) THEN
$p Less than zero
▪ The ELSE commands are also
optional, you can be sure that ELSE
exactly one command within $p More than zero
the if construct will be
executed. ENDIF
▪ Example: NumCheck.mac
Errors & Error Handling
▪ An error can occur because a command could not

complete successfully or because of a mistake in a
macro or function.
▪ An error normally has three effects:
– An Alert box appears which the user must acknowledge.

– An error message is output together with a traceback of
any calling macros or functions.
– Any current running PML macros and functions are
abandoned.
Example of Errors
▪ This is an example of an error caused by an attempt to use a

PML variable which does not exist:
(46,8) ERROR – Cannot create an EQUI at this level
▪ The 46 is the program section which identified the error and 8

is the error Code itself.
Handling Errors
▪ If the input line was handle (46, 27)

part of a PML macro or not processed this time
function the error may elsehandle (46, 28)
optionally be This block is processed
HANDLED. elsehandle ANY
Would handle errors other
(46, 27) and (46,28)
▪ A command causes elsehandle NONE
Error(46, 28) Runs when there are no
errors
endhandle
Example of Errors - Example
▪ Example: ErrorCheck.mac
NEW EQUI /ABCD
HANDLE (41, 8)
$p Need to be at a ZONE or below
ELSEHANDLE (41, 12)
$p That name has already been used. Names must be
unique
ELSEHANDLE ANY
$p Another error has occurred
ELSEHANDLE NONE
$p Everything OK. EQUI created
ENDHANDLE
Alert Objects (1)
▪ There are 3 types of alert with no return value:
!!alert.error( |You cannot do this!| )

!!alert.message( |Saving your data now| )
!!alert.warning( |Do not press again!| )
▪ By default, all alert forms appear with the relevant

button as near to the cursor as possible. To
position an alert specifically, X and Y values can be
specified as a proportion of the screen size
!!alert.error(|You cannot do this!|, 0.25, 0.1)
Alert Objects (2)
Alert Objects (3)
▪ There are three types of alert which return a value,

confirm, question and input alerts.
▪ Confirm Alerts
!a = !!alert.confirm(|Are you sure!|)
Returns a ‘YES’ or ‘NO’ as a string
▪ Question Alerts
!a = !!alert.question(|OK to delete Site?|)

Returns a ‘YES’ or ‘NO’ or ‘CANCEL’ as a string
Alert Objects (4)
▪ Input Alerts
!a = !!alert.input(|Enter Floor Width|,|10|)
The first value is the prompt and the second is the default value.
Input alerts return a value as a string.
PML Functions

PML Functions
▪ PML functions are lines of PML grouped together

within a single file.
▪ When called, the lines are run in order
▪ These should be used instead of macros because:
– Functions are loaded dynamically

– Functions can accept arguments of a specific object type
– Functions can return values of a specific object type
Creating a PML function
▪ Write the PML to a text file and save as .pmlfnc

▪ The name of the file should be the same as the
name of the function e.g !!exampleFunction would
be examplefunction.pmlfnc
define function !!nameCE() is STRING

!ce = !!CE.flnn
return !ce
endfunction
▪ This is an example of a RETURN function with NO

ARGUMENTS
Using Functions with Arguments
▪ Functions can have arguments and may return a result

value:
define function !!area(!radius is REAL) is REAL
!circleArea = !radius.power(2) * 3.142
return !circleArea
endfunction
▪ Functions that return values can be used in

expressions:
!height = 64
!cylinderVolume = !!area(2.3) * !height
q var !cylinderVolume
Creating a PML Procedure
▪ A PML procedure is a PML function that carries out

an action and typically will not return a value:
define function !!lockCE()

!!CE.lock = !!CE.lock.not()
endfunction
▪ This is an example of a NON-RETURN function with

NO ARGUMENTS
Using PML Procedures with Arguments
▪ A PML procedure can be supplied arguments too:
define function !!setSize(!x is REAL, !y is REAL, !z is REAL)

if !!ce.type.eq(|BOX|) then
!!ce.xlen = !x
!!ce.ylen = !y
!!ce.zlen = !z
endif
endfunction
▪ This is an example of a NON-RETURN function with

ARGUMENTS
Using Object methods
▪ There are a number of methods available on pre-

defined objects that can be used instead of writing
new functions.
▪ For example, the .real() method on a STRING object

makes returns a REAL version of the string
!x = ‘56’ creates a string variable

!y = (!x.real() * 2) creates a real using !x
The use of . and ()
▪ Notice the dot separator between the name of the

variable and the name of the method. Also note the ()
brackets.
▪ Brackets must always be after the method name. If
not, PDMS will read the method as a member.
▪ The brackets are used to enclose the arguments of
the method, but they must be present.
▪ Although the below have the same name, they are

different methods as one has an arguement:
!nameStrings = !name.split()
!nameStrings = !name.split(|%|)
Using Object methods (2)
▪ Built-in methods can perform a variety of

operations and are more efficient than a equivalent
user-defined method.
!NumberOfNames = !NameStrings.Size()
▪ This method returns the number of elements

currently in the array. This is an example of a
RESULT method with NO-AFFECT on the original
object.
▪ Here is a method which does change the array:
!MyArray.Clear()
▪ This method deletes the contents of the array, but

not the array. This is an example of a NO RESULT
method which does AFFECT the original object.
▪ Here is a kind of method which both changes the

array and returns a result value.
!NewArray = !OldArray.RemoveFrom(5,10)
▪ This method result removes 10 elements (starting

at element 5) from the array.
▪ These elements are then returned by the method.
This is an example of a RESULT method which does
AFFECT the original object.
▪ If not required, the result can be simply discarded

by invoking the method as a command and not
assigning the result to a variable:
!OldArray.RemoveFrom(5,10)
Always use an ARRAY METHOD, if one is available,

in preference to constructing a DO LOOP as it is far
more efficient.
▪ The available Built-in methods can be found in the

Customisation Reference Manual under the relevant
object.
Method Concatenation
▪ Any number of methods can be combined

providing the passed data is valid at each stage.
!line = 'hello world how are you'

!newline = !line.upcase().split().sort()
q var !newline
<ARRAY>
[1] <STRING> 'ARE'
[2] <STRING> 'HELLO'
[3] <STRING> 'HOW'
[4] <STRING> 'WORLD'
[5] <STRING> 'YOU'
The !!CE Object (1)
▪ A special GLOBAL PML object !!CE always points to

the current PDMS element and its attributes:
!BranchHeadBore = !!CE.Hbore
!HeadPosition = !!CE.Hposition
!Easting = !HeadPosition.East
▪ To find a position with respect to another element:
!PosWRTValve = !HeadPosition.WRT(!Valve)
The !!CE Object (2)
▪ There is the ability to set attributes using pml

syntax. The format of the command is:
dbref.attributeName = PMLvariable
For example:
!dbref.name = '/PIPE-100'
!!CE.built = TRUE
▪ You can even assign a PML object, such as POSITION,

where this corresponds to the type of the attribute:
!!CE.position = !newPosition
The !!CE Object (3)
▪ When the attribute type of the CE is already a PML

object, it is not possible to set an value directly
▪ The value must be altered in two stages:
!pos = !!CE.position
q var !pos
!pos.Up = 2000
!!CE.position = !pos
q var !pos
Collections

COLLECT command syntax – PML 1 style
▪ A very powerful feature of the PDMS database is the

ability to collect and evaluate data according to
rules.
var !equipment collect all EQUI for ZONE

q var !equipment
var !pipeComponents collect ALL with owner eq /200-B- 4-

B1 for SITE
q var !pipeComponents
var !boxes collect all BOX for ce

q var !boxes
EVALUATE command syntax – PML 1 style
▪ It is possible to evaluate an expression against an

ARRAY of values, instead of individually.
var !equipmentNames evaluate NAME for ALL from !equipment

q var !equipmentNames
var !elbows evaluate FLNN for all ELBO from !pipeComponents

q var !elbows
var !pumps evaluate NAMN for ALL with MATCHWILD(NAMN, |P*|)

from !equipment
q var !pumps
var !volume eval (xlen * ylen * zlen) for ALL from !box
q var !volume
COLLECTION Object – PML 2
▪ PML 2 collections are done using the COLLECTION

object
!equiColl = object COLLECTION()

!equiColl.type(‘EQUI‘)
!equiColl.scope(!!ce)
!expr = object EXPRESSION(|NAME OF OWNER EQ ‘/EQUIP’|)
!equiColl.filter(!expr)
!results = !equiColl.results()
q var !results
▪ Note: all collected items are now DBREF objects, not

STRING objects – as with the COLLECT command
Evaluating results from a COLLECTION object
▪ The COLLECTION object returns an ARRAY of

results
▪ The ARRAY object has an .evaluate() method:
!block = object BLOCK(|!results[!evalIndex].flnn|)

!resultNames = !results.evaluate(!block)
q var !resultNames
▪ The .evaluate() method requires a BLOCK object as

the argument. This is defined with a STRING
expression.
Miscellaneous

PML Publisher (1)
▪ It is now possible to encrypt any files you create

before sharing them. Once encrypted, the files can
still be used in any compatible AVEVA program, but
they are not easily read through a normal text
editor.
▪ Encrypted files may be used without additional

licenses, but the encryption utility described below
is separately distributed and licensed.
PML Publisher (2)
▪ Examples
– Single File
pmlencrypt raw.txt encrypted.txt
– Folder
pmlencrypt.exe -pmllib original_pmllib enc_pmllib
▪ Other arguments available

-rc4 uses 40-bit RC4 encryption from the Microsoft Base Cryptographic Provider (default)
-basic uses a simple low-security encryption algorithm
-trivial uses a human-decipherable encryption scheme - for testing only
-none no encryption, but can be used with -buffer N
-buffer N causes the file to be retained in memory until a module switch once it has been read N
times (the default is never)
General Notes on PML (1)
▪ PML files are ASCII and can be created/edited in any basic text
editor
▪ PML 1 files are saved under PDMSUI folder and PML 2 under
the PMLLIB folder
▪ PML 2 objects have specific file extensions
(.pmlfnc, .pmlobj and .pmlfrm)
▪ If newly created, PML can be found by typing pml rehash all
▪ Once loaded,
objects can be reloaded by typing pml object reload OBJECT
▪ Once loaded,
forms can be reloaded by typing pml object reload FORM
General Notes on PML (2)
▪ When declaring a string, text delimiters must be

used. Either ‘single quotes’ or |vertical bars|
▪ File paths of files can be obtained by
using !!pml.getPathName(|form.pmlfrm|)
▪ Variable names are not case sensitive
▪ String comparisons are case sensitive
▪ Variable names can be 16 characters long and
should not start with a number or contain a dot
▪ It is good practice to name variables in lower case,
using upper case to separate words
e.g. !stringLength
Q &A
Thank you

Material-PML Training-Macros and Functions-REV06

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Material-PML Training-Macros and Functions-REV06

Uploaded by

Copyright:

Available Formats

PML Training – Macros and Functions

▪ Broad overview of the PML language

Copyright © 2015 AVEVA Solutions

Copyright © 2015 AVEVA Solutions

▪ Programmable Macro Language (PML) is the

▪ Macros are ASCII files containing PDMS commands

$M/BUILDBOX 100 200 300

▪ Throughout the reference manuals supplied with

▪ PML2 is more like other modern languages.

▪ Typically, fewer lines of code needed with PML2

▪ Designed to be easier to read and easier to write

▪ Most PML1 macros will still run under PML2

▪ PML2 contains many new features, but not in PML1

▪ New Variable Types - STRING, REAL, BOOLEAN,

▪ To declare a local variable as a REAL 3

▪ Many of the supplied object types are explained in

▪ Every variable in PML has an object type.

– Built-in (e.g. String, Real, Boolean and Array)

▪ User defined objects provide an opportunity to

▪ Variable names may be up to 16 characters long and the

▪ NEVER start a variable name with a number

▪ To create a LOCAL, STRING variable

▪ To create a GLOBAL, REAL variable:

▪ To create a GLOBAL, BOOLEAN variable:

▪ To create a LOCAL empty ARRAY

▪ Every variable defined in PDMS has an object type

!newPlant = object FACTORY()

▪ It is common practice to given meanful names to

▪ In a standard PDMS DESIGN session, there are

– !!CE - a global DBREF object which tracks and represents the

▪ Functions and methods provide the action of PML

define function !!area(!len is REAL,!wid is REAL) is

!area = !!area(12, 200)

▪ Forms are objects that are stored as global variables

define method .print()

DES DRA ADMIN CLIB….

GEN ADMIN PIPE EQUI….

functions forms objects

▪ 3 new file extensions .pmlfnc .pmlfrm .pmlobj

▪ This can also be found from the Properties… form

2 ▪ Open the file in a suitable text editor

Copyright © 2015 AVEVA Solutions

▪ A PML object is a grouping of common information

▪ PML objects are available across PDMS to

– GPHLINE – an object to represent a graphical line

▪ To investigate these objects, type the following into

!gphline = object GPHLINE()

▪ By using PML objects, common code can be isolated,

▪ PML objects can also be used to used to solve

▪ In this arrangement, the PDMS user interacts with the form to

define method .getinformation()

Copyright © 2015 AVEVA Solutions

ASCII file NEW EQUIP /ABCD

▪ All commands need to be supplied to the command

▪ To expand the contents of a PML variable into a string

e.g. !CompType = ‘ELBO’

▪ Macros can be parameterised

ASCII file NEW EQUIP /$1

▪ To run a macro with parameters:

▪ Macros may have up to 9 parameters separated by

▪ Text strings may be entered as a single parameter

▪ $< $> act as delimiters and anything in between is

▪ Defaults parameters can be stored within the

▪ $d syntax is used followed by the parameter