2. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
2
www.aveva.com
3. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
3
www.aveva.com
Revision Log
Date Revision Description of Revision Author Reviewed Approved
16/01/2009 0.1 Issued for Review BT
26/01/2009 0.2 Reviewed BT EW
29/01/2009 1.0 Approved for Training 12.0.SP3 BT EW RP
Updates
All headings containing updated or new material will be highlighted.
Suggestion / Problems
If you have a suggestion about this manual or the system to which it refers please report it to the AVEVA
Group Solutions Centre at gsc@aveva.com
This manual provides documentation relating to products to which you may not have access or which may
not be licensed to you. For further information on which products are licensed to you please refer to your
licence conditions.
Visit our website at http://www.aveva.com
Disclaimer
Information of a technical nature, and particulars of the product and its use, is given by AVEVA Solutions Ltd
and its subsidiaries without warranty. AVEVA Solutions Ltd. and its subsidiaries disclaim any and all
warranties and conditions, expressed or implied, to the fullest extent permitted by law.
Neither the author nor AVEVA Solutions Ltd or any of its subsidiaries shall be liable to any person or entity
for any actions, claims, loss or damage arising from the use or possession of any information, particulars or
errors in this publication, or any incorrect use of the product, whatsoever.
Trademarks
AVEVA and Tribon are registered trademarks of AVEVA Solutions Ltd or its subsidiaries. Unauthorised use
of the AVEVA or Tribon trademarks is strictly forbidden.
AVEVA product names are trademarks or registered trademarks of AVEVA Solutions Ltd or its subsidiaries,
registered in the UK, Europe and other countries (worldwide).
The copyright, trademark rights or other intellectual property rights in any other product, its name or logo
belongs to its respective owner.
5. 5
Contents
www.aveva.com
1 Introduction.............................................................................................................................................. 9
1.1 Aim .................................................................................................................................................... 9
1.2 Objectives......................................................................................................................................... 9
1.3 Prerequisites .................................................................................................................................... 9
1.4 Course Structure.............................................................................................................................. 9
1.5 Using this guide ............................................................................................................................... 9
2 PML Overview ........................................................................................................................................ 11
2.1 PML Programmable Macro Language.......................................................................................... 11
2.2 PML2 - A More Powerful Language.............................................................................................. 11
2.3 PML 2 Jargon.................................................................................................................................. 12
2.4 Features of PML2 ........................................................................................................................... 12
3 Macros and Synonyms.......................................................................................................................... 13
3.1 A simple Macro............................................................................................................................... 13
3.2 The OUTPUT Command ................................................................................................................ 13
3.3 Communicating with AVEVA Products in PML........................................................................... 14
3.4 Parameterised Macros................................................................................................................... 14
3.5 Synonyms....................................................................................................................................... 14
3.6 Recursive Synonyms..................................................................................................................... 15
3.7 Deleting Synonyms........................................................................................................................ 15
Exercise 1 - The Centre of a Handwheel ..................................................................................................... 16
4 Variables................................................................................................................................................. 17
4.1 Numbered Variable types.............................................................................................................. 17
4.2 Named Variable types.................................................................................................................... 17
4.2.1 Setting named variables........................................................................................................... 17
4.3 PML 2 Variable types ..................................................................................................................... 18
4.3.1 Creating Variables.................................................................................................................... 18
4.3.2 Expanding Variables ................................................................................................................ 18
4.3.3 Expressions.............................................................................................................................. 19
4.3.4 Expression operators ............................................................................................................... 19
4.3.5 Operator Precedence............................................................................................................... 19
4.3.6 PML 2 expressions................................................................................................................... 20
4.3.7 Using Variables In Expressions ............................................................................................... 20
4.3.8 Arrays....................................................................................................................................... 20
4.3.9 Concatenation Operator........................................................................................................... 20
Exercise 2 - The variable Centre of a Handwheel....................................................................................... 21
5 PML Control............................................................................................................................................ 23
5.1 DO loop ........................................................................................................................................... 23
5.1.1 DO loops with BREAK.............................................................................................................. 23
5.1.2 DO loops with SKIP.................................................................................................................. 24
5.1.3 DO Index and DO Values......................................................................................................... 24
5.1.4 DO Loops Examples ................................................................................................................ 24
5.2 IF Statements.................................................................................................................................. 25
5.2.1 Simple IF construct. ................................................................................................................. 25
5.2.2 IF, THEN, ELSEIF and ELSE Statements ............................................................................... 25
5.3 Branching ....................................................................................................................................... 25
5.4 Conditional Jumping ..................................................................................................................... 26
Exercise 3 - The Full Handwheel.................................................................................................................. 26
6 Boolean Expressions and IF Statements ............................................................................................ 27
6.1 Simple Boolean Expressions........................................................................................................ 27
6.2 Converting a value to BOOLEAN ................................................................................................. 27
6.3 Valid Boolean expressions ........................................................................................................... 27
6.4 Invalid Boolean expressions ........................................................................................................ 28
6.5 Boolean expressions PML1 upward compatibility.................................................................... 28
7 Errors & Error Handling ........................................................................................................................ 29
7.1 Example of Errors .......................................................................................................................... 29
7.2 Error Handling................................................................................................................................ 29
7.3 Alert Objects................................................................................................................................... 29
7.3.1 Alert Objects with no return value ............................................................................................ 29
6. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
6
www.aveva.com
7.4 Alert Objects that return value ..................................................................................................... 30
7.4.1 Confirm Alerts........................................................................................................................... 30
7.4.2 Question Alerts......................................................................................................................... 30
7.4.3 Input Alerts ............................................................................................................................... 30
Exercise 4 – Error Handling.......................................................................................................................... 31
8 PML 1 Hierarchy..................................................................................................................................... 33
8.1 Modifications to PDMSUI .............................................................................................................. 33
9 PML2 Functions and Objects ............................................................................................................... 35
9.1 The pmllib environment variable.................................................................................................. 35
9.2 Modifications to pmllib.................................................................................................................. 35
9.3 Updating PDMSUI and PMLLIB..................................................................................................... 36
9.4 PML2 Objects ................................................................................................................................. 36
9.5 PML2 Methods................................................................................................................................ 36
9.6 Method Concatenation .................................................................................................................. 37
9.7 The !!CE Object .............................................................................................................................. 38
9.8 PML2 Functions ............................................................................................................................. 38
Exercise 5(a) – Convert the Hose reel macro into a function ................................................................... 39
Exercise 5(b) – Adding arguments to the function .................................................................................... 40
10 Forms .................................................................................................................................................. 41
10.1 Forms Are Global Objects............................................................................................................. 41
10.2 Dynamic loading of Objects, Forms and Functions................................................................... 41
10.3 Form Definition............................................................................................................................... 42
10.3.1 Using the .net framework ......................................................................................................... 42
10.3.2 Showing and hiding Forms....................................................................................................... 42
10.3.3 Built-in methods for Forms....................................................................................................... 43
10.4 Callbacks ........................................................................................................................................ 43
10.5 Form Gadgets................................................................................................................................. 44
10.5.1 Built-in members and methods for Gadgets ............................................................................ 44
10.5.2 Gadget positioning ................................................................................................................... 45
10.5.3 Docking and Anchoring Gadgets ............................................................................................. 46
10.6 Paragraph Gadgets........................................................................................................................ 47
10.7 Button Gadgets .............................................................................................................................. 47
10.7.1 Linklabel ................................................................................................................................... 48
10.8 Text Entry Gadgets ........................................................................................................................ 48
10.9 Format Object................................................................................................................................. 49
10.10 List Gadgets ............................................................................................................................... 50
10.11 Frame Gadgets........................................................................................................................... 52
10.11.1 Fold Up Panel Frames ......................................................................................................... 53
10.12 Textpane Gadgets...................................................................................................................... 53
10.13 Option Gadgets .......................................................................................................................... 54
10.14 Toggle Gadgets.......................................................................................................................... 54
10.15 Radio Gadgets............................................................................................................................ 55
10.16 Form Member Variables ............................................................................................................ 56
10.17 Tooltips ....................................................................................................................................... 56
10.18 Progress Bar............................................................................................................................... 57
Exercise 6(a) - Calculation methods........................................................................................................... 58
Exercise 6(b) - Loops .................................................................................................................................... 59
Exercise 6(c) – Concatenation ..................................................................................................................... 60
Exercise 6(d) – String manipulation ............................................................................................................ 61
Exercise 7 – Storing and resetting defaults................................................................................................ 62
10.19 Open Callbacks .......................................................................................................................... 63
Exercise 8 – Tabsets and Open Callbacks.................................................................................................. 64
10.20 Bar Menus................................................................................................................................... 65
10.20.1 Defining a Menu Object........................................................................................................ 65
11 PML Objects ....................................................................................................................................... 67
11.1 Built in PML OBJECT Types ......................................................................................................... 67
11.2 Forms and Menus Objects............................................................................................................ 68
11.3 3D Geometry Objects .................................................................................................................... 68
11.4 Methods Available to All Objects ................................................................................................. 69
11.5 The File Object ............................................................................................................................... 70
11.5.1 Using file objects ...................................................................................................................... 70
7. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
7
www.aveva.com
11.5.2 Use Notepad to open file.......................................................................................................... 71
Exercise 9 – Menubar.................................................................................................................................... 71
12 User-Defined Objects ........................................................................................................................ 73
13 Collections.......................................................................................................................................... 75
13.1 The Collection Syntax (PML 1) ..................................................................................................... 75
13.2 The Object Collection Syntax (PML 2) ......................................................................................... 75
Exercise 10 – Equipment Collections.......................................................................................................... 76
14 Pop-Up Menus.................................................................................................................................... 77
Exercise 11(a) – Pop-up menu ..................................................................................................................... 78
Exercise 11(b) – Equipment Checking ........................................................................................................ 79
Exercise 11(c) – Setting Equipment attributes........................................................................................... 80
15 View Gadgets ..................................................................................................................................... 81
15.1 Alpha Views.................................................................................................................................... 81
15.2 Plot View Example ......................................................................................................................... 81
15.3 Volume View example ................................................................................................................... 82
Exercise 12(a) – Adding a Volume View...................................................................................................... 83
Exercise 12(b) – Adding a Clipbox to the view........................................................................................... 84
Exercise 12(c) – Dynamically modify a clipbox.......................................................................................... 85
Exercise 12(d) – Add Nozzle tagging........................................................................................................... 86
Exercise 12(e) – Add Highlighting ............................................................................................................... 87
16 Event Driven Graphics (EDG) ........................................................................................................... 89
16.1 Simple EDG..................................................................................................................................... 89
16.2 Using EDG ...................................................................................................................................... 90
Exercise 13 – Using EDG .............................................................................................................................. 91
Exercise 13(a) – Add EDG to !!ex10............................................................................................................. 91
Exercise 13(b) – Add EDG to !!ex11b .......................................................................................................... 92
Exercise 13(c) – Add EDG to !!ex12b........................................................................................................... 93
17 Miscellaneous .................................................................................................................................... 95
17.1 Recursive Pml2 Functions............................................................................................................ 95
17.2 Undo and Redo............................................................................................................................... 95
17.2.1 Marking the database............................................................................................................... 95
17.2.2 Undo and Redo Database Commands .................................................................................... 95
17.3 Error tracing ................................................................................................................................... 96
18 Menu Additions .................................................................................................................................. 97
18.1 Miscellaneous Notes ..................................................................................................................... 97
18.2 Modules that use the new Addins functionality ......................................................................... 97
18.3 Adding a Menu/Toolbar................................................................................................................. 97
18.4 Application Design ........................................................................................................................ 97
18.5 Form and Toolbar Control............................................................................................................. 98
18.6 Converting Existing Applications ................................................................................................ 98
18.6.1 DBAR and Add-in Object ......................................................................................................... 99
18.6.2 Bar Menu and Toolbar ............................................................................................................. 99
18.6.3 Define toolbar........................................................................................................................... 99
18.6.4 Adding to Menus ...................................................................................................................... 99
18.6.5 Adding new menus to form .................................................................................................... 100
18.7 Example object including toolbars, bar menus and menus.................................................... 101
Exercise 14 – Add a Utility and Toolbar menu ......................................................................................... 103
19 Upgrading from PML1 to PML2 ...................................................................................................... 105
19.1 Points to watch out for................................................................................................................ 105
Appendix A – PDMS Primitives.................................................................................................................. 107
Appendix B – Example code ...................................................................................................................... 111
Appendix B1 - Example ex1.mac ........................................................................................................... 111
Appendix B2 - Example ex2.mac ........................................................................................................... 112
Appendix B3 - Example ex3.mac ........................................................................................................... 113
Appendix B4 - Example ex4.mac ........................................................................................................... 114
Appendix B5 - Example ex5a.pmlfnc..................................................................................................... 115
Appendix B6 - Example ex5b.pmlfnc..................................................................................................... 116
Appendix B7 - Example ex6a.pmlfrm .................................................................................................... 118
Appendix B8 - Example ex6b.pmlfrm .................................................................................................... 119
Appendix B9 - Example ex6c.pmlfrm .................................................................................................... 121
Appendix B10 - Example ex6d.pmlfrm .................................................................................................. 124
8. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
8
www.aveva.com
Appendix B11 - Example ex7.pmlfrm .................................................................................................... 127
Appendix B12 - Example ex8.pmlfrm .................................................................................................... 131
Appendix B13 - Example ex9.pmlfrm .................................................................................................... 135
Appendix B14 - Example ex10.pmlfrm .................................................................................................. 139
Appendix B15 - Example ex11a.pmlfrm ................................................................................................ 140
Appendix B16 - Example ex11b.pmlfrm ................................................................................................ 141
Appendix B17 - Example ex11c.pmlfrm ................................................................................................ 143
Appendix B18 - Example ex12a.pmlfrm ................................................................................................ 146
Appendix B19 - Example ex12b.pmlfrm ................................................................................................ 150
Appendix B20 - Example ex12c.pmlfrm ................................................................................................ 154
Appendix B21 - Example ex12d.pmlfrm ................................................................................................ 159
Appendix B22 - Example ex12e.pmlfrm ................................................................................................ 165
Appendix B23 - Example ex13a.pmlfrm ................................................................................................ 172
Appendix B24 - Example ex13b.pmlfrm ................................................................................................ 174
Appendix B25 - Example ex13c.pmlfrm ................................................................................................ 177
Appendix B26 - Example ex14................................................................................................................ 182
9. 9
www.aveva.com
CHAPTER 1
1 Introduction
This manual is designed to give an introduction to the AVEVA Plant Programming Macro Language, There
is no intention to teach software programming but just how the customisation using PML can be done in
AVEVA Plant.
Appendix B contains example code that answers each exercise. The exercises have been deliberately
written to be open to interpretation. This means that the code you produce maybe different.
1.1 Aim
The following points need to be understood by the trainees:
Understand how PML can be used to customise Vantage Plant Design (PDMS)
Understand how to create Functions, Forms and Objects.
Understand how to use the built-in features of Vantage Plant Design (PDMS)
Understand the use of Addins to customise the environment.
1.2 Objectives
At the end of this training, you will have a:
Broad overview of Programmable Macro Language
Basic coding practices and conventions
How PML can interact with the Design model
How Forms and Menus can be defined with PML
1.3 Prerequisites
The participants must have completed an AVEVA Basic Design Course and have some basic progremmin
knowledge.
1.4 Course Structure
Training will consist of oral and visual presentations, demonstrations and set exercises. Each workstation
will have a training project, populated with model objects. This will be used by the trainees to practice their
methods, and complete the set exercises.
1.5 Using this guide
Certain text styles are used to indicate special situations throughout this document, here is a summary;
Menu pull downs and button press actions are indicated by bold dark turquoise text.
Information the user has to Key-in 'will be red and BOLD'
Annotation for trainees benefit:
Additional information
Refer to other documentation
System prompts should be bold and italic in inverted commas i.e. 'Choose function'
Example files or inputs will be in the courier new font, colours and styles used as before.
10. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
10
www.aveva.com
11. 11
www.aveva.com
CHAPTER 2
2 PML Overview
Macros A macro is a group of PDMS commands written to a file
PML Programmable Macro Language (two parts)
PML1 First version of PML including loops, IF statements, string handling, labels etc.
PML2 Object orientated language builds on PML1 and extends the facilities to be like other object
based languages (C++, Smalltalk)
Forms Most applications are driven by forms and menus. Most PML will be based on a form.
2.1 PML Programmable Macro Language
Macros are ASCII files containing PDMS commands in sequence. By asking PDMS to run a macro, you are
really asking PDMS to run a series of commands in a set order (as defined in the macro file)
Programmable macros are macros that contain program constructs such as IF statements, DO loops and
variables
Macros are run in PDMS by typing $m/FILENAME on to the command line (Display>Command Line).
Any extra information added to a macro line is treated as input parameters and are passed to the macro.
i.e. $M/BUILDBOX 100 200 300
This means that the extra 3 values after the macro name are treated as parameters 1, 2 and 3. When
entered in this way, these parameters are then available for use in the macro instead of fixed values.
2.2 PML2 - A More Powerful Language
PML2 is an enhanced version of PML and is more like other modern languages that you may be familiar
with.
PML2 is almost an object oriented language. It provides most features of other Object Orientated
Programming (OOP) languages except for inheritance. It provides for classes of built-in, system-defined
and user-defined object types. Objects have members (their own variables) and methods (their own
functions). All PML variables are an instance of a built-in, system-defined or user-defined object type.
Typically, fewer lines of code needed with PML2 when compared to traditional PML (PML1) and it has been
designed to be easier to read/write. While most PML1 macros will still run within PDMS, PML2 bring many
new features that were previously unavailable.
Built in methods for different variable types remove several multi line procedures used in old style macros.
Use of $ characters is dramatically reduced with a more readable format for expressions
$-style macros will still work provided the syntax has been followed correctly. It is possible to convert
traditional PML code to include newer PML2 features, but it is important that users maintain compatibility at
all times.
Many new features have been added to improve speed and ease of use. These features will be discussed
and demonstrated through this course.
12. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
12
www.aveva.com
2.3 PML 2 Jargon
2.4 Features of PML2
The main features of PML2 are:
• Available Variable Types - STRING, REAL, BOOLEAN, ARRAY
• Built in Methods for commonly used actions
• Global Functions supersede old style macros
• User Defined Object Types
• PML Search Path (PMLLIB)
• Dynamic Loading of Forms, Functions and Objects
• Aid objects for geometric modelling
PML is now more consistent with other programming languages and more structured in form. The new data
types are now OBJECTS which can be operated by running METHODS.
The old $ based variables are still valid, but are always treated as strings.
Global functions are macros which can be called more like subroutines than traditional macros. e.g. a
function can be called between the brackets of an IF statement and return a BOOLEAN result
User-defined object types enable a group of mixed variables to be combined into packages. The resulting
object can then be used as a simple variable and the separate parts set or used as attributes of the variable.
e.g. !fred.position !fred.name
Search paths and dynamic loading mean that it is no longer necessary to pre load forms or have synonyms
for calling macros.
A large number of new aid objects have been created so that users can do more graphical construction.
13. 13
www.aveva.com
CHAPTER 3
3 Macros and Synonyms
A macro is a group of PDMS commands written to a file (in sequence) that can be run together. This
removes the need for user to have to enter every line of code separately. This means that repetitive
processes can be run as a macro.
3.1 A simple Macro
Below is an example of a macro to produce a BOX and CYLINDER and connect to two together, all within
an EQUI.
Type the following into a suitable text editor and save it as c:pmltrainingSimpleMac.mac
NEW EQUIP /ABCD
NEW BOX
XLEN 300 YLEN 400 ZLEN 600
NEW CYL DIA 400 HEI 600
CONN P1 TO P2 OF PREV
You have created your first macro. To run the macro into PDMS, type $M/ onto the command file, followed
by the full file path of the saved macro.
e.g. $M/c:pmltrainingSimpleMac.mac
When running this macro in, ensure the Current Element (CE) is a ZONE or below
Alternatively the macro can be run by Dragging and Dropping it onto the Command Window.
3.2 The OUTPUT Command
While developing a macro there are two main methods within PDMS to find the information it needs:
OUTPUT command
DB listing utility
Both provide the information needed, so the choice on which will be personal. An example of using the
OUTPUT command is as follows:
Type file /c:pmltrainingaa.txt onto the command line, then press enter
(typing file /c:pmltrainingaa.txt over or FFile /c: pmltrainingaa.txt is also acceptable).
PDMS will open the specified file ready to write to. If the file does not exist, this process will create it.
Choose the require element of interest and ensure it is the CE. After it is chosen, type OUTPUT CE onto
the command line. This will print the information PDMS has about the CE to the file.
Last step, type TERM onto the command line. This will close the form, allowing it to be opened by another
program. This file will hold the information (e.g. attributes) PDMS needs to define the elements.
Try the OUTPUT command on the equipment created by SimpleMac.mac. Notice the additional
information PDMS saves about the elements (information not specified in the macro).
14. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
14
www.aveva.com
3.3 Communicating with AVEVA Products in PML
All commands need to be supplied to the command processor as STRINGS. This is important when
working with element creation (using the NEW syntax)
To expand the contents of a PML variable into a string - put a $ in front of it!
!CompType = |ELBO|
!dist = 5600
NEW $!CompType
DIST $!dist
3.4 Parameterised Macros
Macros can be parameterised. This means instead of hard coding the values through the macro, the values
can be referenced, allowing them to be varied. Simplemac.mac can be parameterised as follows:
NEW EQUIP /$1
NEW BOX
XLEN $2 YLEN $3 ZLEN $4
NEW CYL DIA $3 HEI $4
CONN P1 TO P2 OF PREV
Save the Macro as c:pmltrainingParameterMac.mac
To run this Macro, parameters need to be passed to it. This appending the parameter values to the macro:
e.g. $M/c:pmltrainingParameterMac.mac ABCDE 300 400 600
If no parameters are specified, the macro will fail. To avoid this, default values can be put inside the macro.
This is done by specified $d1= at the top of the macro. For example:
$d1=ABCDEF
$d2=300
$d3=400
$d4=600
Default values will only be used if no parameters are specified.
Macros may have up to 9 parameters separated by space. In the below example, ABC, DEF & GHK are
seen as separate strings and therefore different parameters:
e.g. $M/c:pmltrainingNinePara.mac ABC DEF GHK 55 66 77 88 99 00
If a text string is required as a single parameter, it can be entered by placing a $< before and a $> after the
string.
e.g. $M/c:pmltrainingSevenPara.mac $<ABC DEF GHK$> 55 66 77 88 99 00
$< $> act as delimiters and anything in between is interpreted as a single parameter.
3.5 Synonyms
Synonyms are abbreviations of longer commands. They are created by assigning the command to a
synonym variable:
e.g. $SNewBox=NEW BOX XLEN 100 YLEN 200 ZLEN 300
A synonym can also be parameterised:
15. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
15
www.aveva.com
e.g. $SNewBox=NEW BOX XLEN $S1 YLEN $S2 ZLEN $S3
To call the first version, type NewBox.
For the second version, type NewBox 100 200 300
3.6 Recursive Synonyms
It is possible for a synonym to call itself, effectively looping through the same command. The following
example shows how the XLEN attribute of a group of boxes (owned by the same element) can be updated:
e.g. $SXChange=XLEN 1000 $/ NEXT $/ XChange
This method will end with an error as it runs until it runs out of boxes to change. $/ acts as a return
character
3.7 Deleting Synonyms
To kill a synonym, type $SXXX= & all synonyms $sk
To switch synonyms off and on $S- and $S+
If all synonyms are killed, the synonyms needed to run PDMS will be removed. This means PDMS will
no longer work properly and will require restarting. If synonyms are turned off, some PDMS
functionality will also be removed. The return this functionality, the synonyms should be turned back
on.
16. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
16
www.aveva.com
Exercise 1 - The Centre of a Handwheel
Write a macro to build the centre of a handwheel (shown right)
It shall be constructed from 4 primitives: 2 boxes, a cylinder and a dish
Create the primitives within a PDMS Design session using the available
appware. Once this is done, use the OUTPUT command to see the
information PDMS needs to create them.
Based on the output, use the CONN command to connect the Ppoints of
primitives together
i.e. CONN P1 TO P1 OF PREV
This will connect PPoint 1 (P1) of the current primitive to P1 of the primitive created previously.
The hierarchy created should look similar to the following:
The dimensions of the primitives are:
BOX1 - Xlength = 100mm
Ylength = 100mm
Zlength = 100mm
CYLI - Diameter = 80mm
Height = 5mm
BOX2 - Xlength = 50mm
Ylength = 50mm
Zlength = 15mm
DISH1 - Diameter = 50mm
Height = 15mm
To aid with connecting the primitives, refer to the adjacent
diagram showing an exploded version of the equipment,
with the PPoints identified.
At the end of the macro add the following line:
ADD /HandWheel AUTO /HandWheel
This line will add the created equipment to the drawlist and
scale the view so it can be seen. You could also add the
following line before it.
REM ALL
This will clear the drawlist first, ensuring that only the new piece of equipment is seen in the main 3D
window.
Save the file as c:pmltrainingex1.mac and run it on the command line by typing
$m/c:pmltrainingex1.mac
An example of the completed macro can be found in Appendix B
17. 17
www.aveva.com
CHAPTER 4
4 Variables
Variables set using the VAR syntax are PML1 style variables and are stored in AVEVA products as strings.
Otherwise, they are PML2 style variables.
4.1 Numbered Variable types
Numbered variables are set by typing a number then value after the command VAR. Examples of this are
below:
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’
To obtain the value of variable 1, enter q var 1, q var 117 etc.
The available variable numbers only go to 119 (there is no 120) and they are module dependant. For these
reasons, this technique is no longer commonly used.
4.2 Named Variable types
To give a variable a name, the required name must be preceded with either a single or double exclamation
mark (!), !variablename or !!variablename
single ! - a local variable (can only be seen in the current macro)
double!! - a global variable
Variable names may be up to 64 characters long and the names can contain alpha and numeric
characters.
Variable names must not start with a number or contain a . (full stop)
4.2.1 Setting named variables
The following are some examples of setting variables:
VAR !FRED NAME
Takes the current element’s (ce) name attribute
VAR !POS POS IN WORLD
Takes ce position attribute relative to world coordinates
VAR !x ‘NAME’
Sets the variable to the text string ‘NAME’
VAR !temp (23 * 1.8 + 32)
Calculate a value using the expression
VAR !list COLL ALL ELBO FOR CE
Makes a string array of database references
Quotes ‘ ‘ or vertical bars | | may be used as text Delimiters
18. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
18
www.aveva.com
4.3 PML 2 Variable types
There are four basic variable types: STRING ‘any alpha numeric characters’
REAL any numeric value
BOOLEAN true/false t/f (but not 0/1)
ARRAY any combination of the above
Note: PML1 style variables using the VAR syntax are only stored as strings.
4.3.1 Creating Variables
The following are some examples of setting PML2 variables types:
!Name = ‘Fred’
To create a LOCAL, STRING variable
!!Answer = 42
To create a GLOBAL, REAL variable:
!!Flag = TRUE
To create a GLOBAL, BOOLEAN variable:
!newarray = ARRAY()
To create a LOCAL empty ARRAY
!newarray[1] = |xxx| or !newarray[1] = ‘xxx’
To add to first value to the empty ARRAY (locally)
The type of variable is automatically implied by its content
!!answer = 42 becomes a REAL
!name = ‘fred’ becomes STRING
!flag = TRUE becomes BOOLEAN
Variables can be initialised to ensure only correct results can be set. All variable types can be set up the
following way:
!!number = real()
!!text = string()
4.3.2 Expanding Variables
To expand variables in AVEVA products on the command line use a $. When the line is read, the values of
the variables will be used.
VAR !XLEN (1000)
VAR !YLEN (1000)
VAR !ZLEN (1000)
NEW BOX XLEN $!XLEN YLEN $!YLEN ZLEN $!ZLEN
19. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
19
www.aveva.com
4.3.3 Expressions
Expressions are calculations using PML variables. This can be done is a PML1 or PML2 style:
PML1: VAR !Z ( |$!X| + |$!Y| )
PML2: !Z = !X + !Y
In the PML1 example, !Z is set as a STRING variable. In the PML2 example, !Z is returned as a REAL,
if !X and !Y are REAL
Setting variables using the PML2 method is neater and more readable when compared to PML1.
Any variable can be forced to be a STRING by putting a dollar in front of it.
!x = 64 this returns a REAL.
VAR !y (64) this returns a STRING
IF(!x eq !y)THEN is invalid syntax because the comparison is mixing variable types.
IF($!x eq !y)THEN valid because the dollar in front of !x forces it to be a STRING.
4.3.4 Expression operators
There are a number of expression operators which are available for use. The actual syntax will depend on
whether a PML1 or PML2 style has been adopted.
Numeric operators: + - / *
Comparison operators: LT GT EQ NE LE GE
Logic operators: NOT AND OR
Numeric functions: SIN COS TAN SQR POW NEGATE ASIN ACOS ATAN LOG ALOG ABS INT NINT
For further examples, refer to PDMS Software Customisation Reference Manual:
Some examples of expressions in use:
!s = 30 * sin(45)
!t = pow(20,2) (raise 20 to the power 2 (=400))
!f = (match(name of owner,|LPX|)gt 0)
4.3.5 Operator Precedence
When PDMS reads an expression, there is a precedence that applied to it. This should be considered when
writing one. The order is as follows:
()
* /
+ -
EQ NE GT LT GE LE
NOT
AND
OR
e.g. (60 * 2 / 3 + 5) = 45
20. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
20
www.aveva.com
4.3.6 PML 2 expressions
PML 2 expressions may be of any complexity, they may contain calls to PML Functions and Methods and
include Form gadget values ,object members and methods.
For example:
!NewVal = !!MyFunc(!OldVal) * !!Form.Gadget.Val / !MyArray.Method()
4.3.7 Using Variables In Expressions
$ and quotes are not necessary when using the value of a variable in a PML2 expression:
!X = 64 (instead of VAR !X (64))
!Y = 32
!Z = !X + !Y
The same expression PML1 is still valid ( VAR !Z (|$!X| + |$!Y|) ), but in this case !Z is a STRING
variable
4.3.8 Arrays
An ARRAY variable can contain many values, each of which is called an ARRAY ELEMENT.
An array is created automatically by creating one of its array elements or it can be initialised as an empty
ARRAY. If an ARRAY ELEMENT is itself an ARRAY, this will create a Multi-dimensional ARRAY.
For example an example of an array, type out the following onto the command line:
!x[1] = |ABCD|
!x[2] = |DEFG|
!y[1] = |1234|
!y[2] = |5678|
!z[1] = !x
!z[2] = !y
To query the information about !z, type q var !z. This will return the following information:
<ARRAY>
[1] <ARRAY> 2 Elements
[2] <ARRAY> 2 Elements
To find out more information about the elements within the Multi-dimensional array, type q var !z[1] or q var
!z[2][1]
4.3.9 Concatenation Operator
Values to be concatenated are automatically converted to STRING by the ‘&’ operator. Type the following
onto the command line:
!a = 64
!b = 32
!m = ‘mm’
!c = !a & !b & !m
q var !c
Compare this against the results of typing
!d = !a + !b
q var !d
21. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
21
www.aveva.com
Exercise 2 - The variable Centre of a Handwheel
Write a parameterised macro to build the centre of a handwheel. ex1.mac will be the basis for the new
macro. Also, add two extra primitives to represent an arm (a cylinder) and part of the wheel (a circular
torus).
Use the $d1=XXX syntax to replace the values used in ex1.mac with parameters
$d1 should be used for the name of the equipment and the rest should be set as the required dimensions
Give BOX1 a name so that it can be referred to. This will be useful when positioning the new cylinder and
circular torus. As $1 is a string, a unique name can be created by using the variable with some additional
characters e.g. /$1-XXX
The new cylinder shall have a height of 500mm and should not overlap the original BOX1. Both the cylinder
and circular torus shall have a diameter of 50mm. The centre line of the circular torus shall intercept the end
of the new cylinder.
The CONN method from exercise 1 can still be used, but instead of using PREV, we can reference other
named elements. Think about the available PPoints when positioning the new primitives (Refer to Appendix
A)
The hierarchy created should look similar to the following:
Save the file as c:pmltrainingex2.mac and run it on the command line by typing
$m/c:pmltrainingex2.mac
An example of the completed macro can be found in Appendix B
Try running the macro again with a different equipment name variable to check it works
22. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
22
www.aveva.com
23. 23
www.aveva.com
CHAPTER 5
5 PML Control
5.1 DO loop
A DO loop is a way of looping within the PML macro allowing pieces of code to be run more than once. This
is useful as it allows code to be reused and reduces the length of code.
As an example, type out the following and save it a c:pmltrainingDoLoop.mac:
DO !loopCounter FROM 1 TO 10
!value = !loopCounter * 2
q var !loopCounter !value
ENDDO
If the above example is run into PDMS, values of !loopCounter and !value with be printed to the command
line for the full range of the defined loop. The step of the loop can be altered by adding BY to the loop
definition:
eg: DO !loopCounter FROM 1 TO 10 BY 2
5.1.1 DO loops with BREAK
If you need a loop to run until a certain condition is reached, a BREAK command will exit the current loop:
Type out the following example and save it a c:pmltrainingDoBreak.mac:
!n = 0
DO
!n = !n + 1
!value = POW(!n, 2)
q var !value
BREAK IF (!value GT 1000)
ENDDO
The BREAK command can also be called from within a normal IF construct. This is typically done if multiple
break conditions need to be considered.
e.g. IF (!value GT 1000)
BREAK
ENDIF
The loop in the example will run until the BREAK condition is met. If the condition is never reached, then the
code will run indefinitely! A DO loop of 1 to 100000 could be used instead, as it has an end.
An open DO loop that never meets the break condition will run indefinitely
24. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
24
www.aveva.com
5.1.2 DO loops with SKIP
It is possible to skip part of the DO loop using the SKIP command. This could be useful if parts of a number
sequence needs to be missed:
Type out the following example and save it a c:pmltrainingDoSkip.mac:
DO !n FROM 1 TO 25
SKIP IF (!n LE 5) OR (!n GT 15)
q var !n
ENDDO
The SKIP command can also be called within a normal IF construct (as the BREAK command)
5.1.3 DO Index and DO Values
DO Index and DO Values are ways of looping through arrays. This is an effective method for controlling the
values used for the loops. Typically values are collected into an ARRAY variable then looped through using
the following:
DO !X VALUES !ARRAY
!X takes each ARRAY element
ENDDO
DO !X INDEX !ARRAY
!X takes a number from 1 to !ARRAY size
ENDDO
5.1.4 DO Loops Examples
Type out the following as an example of looping through an ARRAY of values. Save the following as
c:pmltrainingDoArray.mac.
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 INDEX !Names
q var !Names[!x]
ENDDO
The example uses the COLL syntax as a method of defining an array. This syntax will be explained later in
the manual. It shows how the two methods can extract the same information from the source array.
25. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
25
www.aveva.com
5.2 IF Statements
An IF statement is a construct for the conditional execution of commands. The commands will only be run if
the conditions of the IF statement are met.
5.2.1 Simple IF construct.
A simple example of an IF construct is shown below. The code within the IF construct is only run if the
expression is TRUE. An example is as follows:
IF ( !Number LT 0 ) THEN
!Negative = TRUE
ENDIF
5.2.2 IF, THEN, ELSEIF and ELSE Statements
An IF construct can be extended by adding additional conditions. This is done by adding either ELSEIF or
ELSE to it. When an IF construct is encountered, PML will evaluate its condition. If the condition is FALSE,
PDMS will look to the next ELSEIF condition.
Once a condition is found to be TRUE, that code will be run that proportional of the code and the IF
construct is complete. If an ELSE condition is added, this portion of code will only be run if the other
conditions are never met. This is a way of ensuring some code is always run.
Type out the following example, and save it as c:pmltrainingNumCheck.mac. Run it with one real
parameter.
IF ($1 EQ 0) THEN
$p Your value is zero
ELSEIF ($1 LT 0) THEN
$p Your value is less than zero
ELSE
$p Your value is Greater than zero
ENDIF
The ELSEIF and ELSE commands are optional, but there can only be one ELSE command in an IF
construct.
5.3 Branching
PML provides a way of jumping from one part of a macro to another using GOLABEL.
LABEL /FRED Max length 16 characters, excluding (/)
...
Some PML code
...
GOLABEL /FRED
The next line to be executed will be the line following LABEL /FRED, which could be before or after the
GOLABEL command.
The use of this method should be limited. It can make code hard to read and debug.
26. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
26
www.aveva.com
5.4 Conditional Jumping
Type out the following as an example of conditional jumping. Save it as c:pmltrainingConditional.mac.
DO !A
$P Processing $!A
DO !B TO 10
!C = !A * !B
GOLABEL /finished if (!C GT 100)
$P Product $!C
ENDDO
ENDDO
LABEL /finished
$P Finished with processing = $!A Product = $!C
If the expression !C GT 100 is TRUE there will be a jump to label /finished and PML execution will continue
with the $P command. If the expression is FALSE, PML execution will continue with the command: $P
Product $!C and go back through the DO loop.
Exercise 3 - The Full Handwheel
Introduce variables and calculations to reduce the number of parameters needed to build a handwheel. Use
ex2.mac as a basis for the new macro and use a loop to complete the outer wheel.
Create two SUBE elements. One will contain the
primitives that make up the centre of the handwheel
and the other the arm of the handwheel.
Use a loop to copy the arm SUBE element to
complete the outer wheel. When building the loop,
consider how many copies are needed.
When creating a copy, create the element as usual
but append COPY /XXXX to the line. This will create
a new element, but copy it from /XXXX
e.g. NEW BOX COPY /XXXX
As each arm will need to be rotated 90° from the previous, the ROTATE command can be used
e.g. ROTATE BY AAA ABOUT BBB
where AAA is the angle of rotation and BBB a direction to rotate around i.e. U. Think about how the loop
can be used to change the angle of rotation and the name of the copied elements.
The hierarchy created should look similar to the
following
Save the file as c:pmltrainingex3.mac and run it on the command line by typing $m
c:pmltrainingex3.mac
An example of the completed macro can be found in Appendix B
27. 27
www.aveva.com
CHAPTER 6
6 Boolean Expressions and IF Statements
6.1 Simple Boolean Expressions
Expressions based on the operators such as EQ (equal to) and GT (greater than) give a BOOLEAN result
which can be used directly in an IF construct.
An example is as follows. Type out the example and save it as c:pmltrainingBoolean.mac. Run it as a
single parameter macro.
!value = int($1)
IF ( !value NE 1 ) THEN
!Test = FALSE
ELSEIF ( !value.eq(1) ) THEN
!Test = TRUE
ENDIF
q var !Test
The expression can be a simple variable provided it is a BOOLEAN type variable:
!Success = !Value GT 0
IF ( !Success ) THEN
The expression could be a user-defined PML function or method that returns a BOOLEAN result:
IF ( !!MyFunction() ) THEN
6.2 Converting a value to BOOLEAN
There is a built-in PML method and a function for converting a value to BOOLEAN:
!MyString = |TRUE|
IF ( !MyString.Boolean() ) THEN ...
The Boolean conversion is as follows:
REAL zero becomes FALSE
All other positive and negative REAL values become TRUE
STRING ‘FALSE, ‘F’, ‘NO’ and ‘N’ become FALSE
STRING ‘false, ‘f’, ‘no’ and ‘n’ become FALSE
STRING ‘TRUE’, ‘T’, ‘YES’ AND ‘Y’ become TRUE
STRING ‘true’, ‘t’, ‘yes’ and ‘y’ become TRUE
6.3 Valid Boolean expressions
BOOLEAN constants are TRUE, FALSE, YES and NO and their single-letter abbreviations not enclosed in
quotes return Boolean results and so can be used directly in expressions.
For example:
if ( TRUE ) and if ( FALSE ) BOOLEAN OK
if ( T ) and if ( F ) BOOLEAN OK
if ( YES ) and if ( NO ) BOOLEAN OK
if ( Y ) and if ( N ) BOOLEAN OK
28. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
28
www.aveva.com
6.4 Invalid Boolean expressions
The following do not return BOOLEAN values and are therefore invalid:
if ( 1 ) and if ( 0 ) REAL invalid
if ( |TRUE| ) and if ( |FALSE| ) STRING invalid
if ( |T| ) and if ( |F| ) STRING invalid
if ($Variable) where Variable = 1 REAL invalid
6.5 Boolean expressions PML1 upward compatibility
For upward compatibility with PML1, STRING variables set to ‘TRUE’, ‘FALSE’, ‘YES’ or ‘NO’ or their single-
letter abbreviations can be used in an if test as long as they are evaluated with a preceding $.
For example:
if ($Variable) where Variable = ‘TRUE’ STRING OK
29. 29
www.aveva.com
CHAPTER 7
7 Errors & Error Handling
An error condition can occur when a command could not complete successfully. This is because of a
mistake in the
macro or function (either input or execution). An error normally has three effects:
• An Alert box appears which the user must acknowledge.
• An error message is outputted to the command line together with a trace back to the error source.
• Any current running PML macros and functions are abandoned.
7.1 Example of Errors
This example of an error is caused by an attempt to create an Equipment when in the wrong part of the
hierarchy.
(41,8) ERROR – Cannot create an EQUI at this level.
The 41 is the program section which identified the error and 8 is the error code itself.
7.2 Error Handling
If the input line was part of a PML macro or function, the error may optionally be HANDLED. This allows the
designer of the macro to limit the errors the user will experience.
Type out the following example and save it as c:pmltrainingErrorTest.mac. First run the macro at a SITE
element, then at a ZONE element and then again at the same ZONE. Compare the return printed lines in
the command window.
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
7.3 Alert Objects
Alert objects allow user-controlled pop-up forms to be used.
7.3.1 Alert Objects with no return value
There are 3 types of alert with no return value:
!!Alert.Error( |You cannot do this!| )
!!Alert.Message( |Saving your data now| )
!!Alert.Warning( |Incorrect value!| )
30. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
30
www.aveva.com
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)
7.4 Alert Objects that return value
There are three types of alert which return a value, confirm, question and input alerts.
7.4.1 Confirm Alerts
Confirm alerts return ‘YES’ or ‘NO’ as strings
e.g. !Answer = !!Alert.Confirm( |Are you sure!| )
After typing the above onto the command line, type q var !Answer
7.4.2 Question Alerts
Answer alerts return ‘YES’ or ‘NO’ or ‘CANCEL’ as strings
e.g. !Answer = !!Alert.Question( |OK to delete Site| )
After typing the above onto the command line,
type q var !Answer
7.4.3 Input Alerts
The first value is the prompt and the second is the default value. Input alerts return a value as a string.
e.g. !Answer = !!Alert.Input( |Enter Width of Floor|,|10| )
After typing the above onto the
command line, type q var !Answer
31. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
31
www.aveva.com
Exercise 4 – Error Handling
Add some error handling to control any errors generated while running ex3.mac.
Although you will not be able to handle every error, think about likely errors and how to handle them
What would be a suitable response to an error? Should it be ignored? Or maybe some user-feedback
provided? Maybe PDMS should do something automatically to correct it?
An example of user-feedback could be to print a warning to the command line. To do this, start a line with
$p followed by a space. Whatever is written after this shall be printed to the command line.
e.g. $p Error Found
To get you started, the following are examples of some errors which may occur:
• At the wrong level in the hierarchy (i.e. at a PIPE element rather than a ZONE)
• A suitable hierarchy level for equipment creation does not exist (or cannot be found)
• An element called ‘HandWheel’ already exists
Save the file as c:pmltrainingex4.mac and run it on the command line by typing $m/c:pmltraining
ex4.mac
An example of the completed macro can be found in Appendix B
32. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
32
www.aveva.com
33. 33
www.aveva.com
CHAPTER 8
8 PML 1 Hierarchy
All PML1 Macros are in a directory structure pointed at by the variable PDMSUI.
The PDMSUI environment variable
Set PDMSUI=C:AVEVAplantPDMS12.0.2pdmsui
Standard AVEVA environment variable are set in a bat files called EVAR.bat in the executable directory.
All PML1 macros and forms are called using synonyms
For example the macros and forms associated with piping are called using the synonym CALLP
$S CALLP=$M/%PDMSUI%/DES/PIPE/$s1
CALLP MPIPE
This is why if all synonyms are killed that PDMS will no longer work properly
8.1 Modifications to PDMSUI
It is normal practice to create a parallel hierarchy to contain any new or modified PML.
Changes to AVEVA standard product may cause PDMS to function inappropriately
These modifications can then be called by modifying the PDMSUI variable to point at a multi path. This can
be done by putting a new file path in front of the %PDMSUI% definition. This will update the PDMSUI
environment variable to include the specified file path.
Set PDMSUI=c:pmltrainingPDMSUI %pdmsui%
The new file path should go in front of %PDMSUI% so this area is checked first for content. Once content is
found, other locations will not be searched.
This modification should be done after the PDMSUI environment variable has been defined. This can be
done at the bottom of the EVAR.bat file or in the PDMS.bat file (after the line which calls evar.bat).
The environment variables can be checked with PDMS by using the q evar syntax
q evar PDMSUI or q evar ‘SAM000’
34. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
34
www.aveva.com
35. 35
www.aveva.com
CHAPTER 8
9 PML2 Functions and Objects
9.1 The pmllib environment variable
The PMLLIB environment variable points to a PML2 directory structure
Set PMLLIB= C:AVEVAplantPDMS12.0.2pmllib
There are 3 new file extensions .pmlfnc for Functions, .pmlfrm for Forms and .pmlobj for Objects, with these
extensions the files will be loaded by PDMS automatically when the program is started.
Functions are loaded by PDMS and are run by typing the following !!mymac(). This runs file
mymac.pmlfnc
Forms are displayed by typing Show !!Myform or !!Myform.show()
Objects have to be assigned to a variable before they can be used i.e. !x = object MyObject()
9.2 Modifications to pmllib
It is normal practice to create a parallel hierarchy to contain any new or modified PML.
Changes to AVEVA standard product may cause PDMS to function inappropriately
These modifications can then be called by modifying the PMLLIB variable to point at a multi path. This can
be done by putting a new file path in front of the %PMLLIB% definition. This will update the PMLLIB
environment variable to include the specified file path.
Set pmllib=c:pmltrainingPMLLIB %pmllib%
The new file path should go in front of %PMLLIB% so this area is checked first for content. Once content is
found, other locations will not be searched.
This modification should be done after the PMLLIB environment variable has been defined. This can be
done at the bottom of the EVAR.bat file or in the PDMS.bat file (after the line which calls evar.bat).
In AVEVA products environment variables can be checked using the q evar syntax i.e. q evar pmllib
36. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
36
www.aveva.com
9.3 Updating PDMSUI and PMLLIB
Edit the Evar.bat file to include multi paths for PDMSUI and PMLLIB
These settings should be made at the bottom of the evar.bat file
Set pdmsui=c:pmltrainingpdmsui %pdmsui%
Set pmllib=c:pmltrainingpmllib %pmllib%
The setting of the variable can be checked in AVEVA Plant Design (PDMS) using the following commands:
q evar pdmsui and q evar pmllib
If a pmllib file is c once items have been loaded by PDMS, it needs to be reloaded. This can be done by
typing either pml reload form !!NAME or pml reload object NAME
If a new file is to pmllib, the files can be remapped so PDMS knows where it is located. This is done by
typing pml rehash onto the command line. This will update the first file location in the search path. To
update all search paths, type pml rehash all.
9.4 PML2 Objects
An object is a PML grouping of information. It may have MEMBERS (used to hold data) ands METHODS
(used to complete an action). Once assigned to a variable, that variable becomes an instance of that object.
This means that variable will behave as the object definition.
While it is possible to create user-defined objects (discussed later), PDMS is supplied with a large number of
built-in objects. A full list of these can be found in the PDMS Software Customisation Reference Manual.
For example, type !pos = object position() onto the command line. Query the variable and check the results
against the members of a position object listed in the reference manual.
Although a FORM is an object, it is a subject in its own and will be discussed later.
9.5 PML2 Methods
When working with built-in objects, there may also be BUILT-IN METHODS (object dependant). These
methods have been defined to complete certain actions applicable to object. For example, type the
following into the command line:
!value = |56|
!result = !value * 2
This example will have caused an error as a string cannot be used in an expression like this. To avoid the
error, refer to the STRING object in the Reference Manual and find the .real() method. This method
translates the variable from a STRING to a REAL so that it can be used in the expression. The !value
remains a string, but !results now becomes a REAL e.g.
!value = |56|
!result = !value.real() * 2
Within PML2, there are built-in methods for all the standard objects (ARRAY, TABLE, FORM, and STRING).
Refer to PDMS Software Customisation Reference Manual for the available methods and information
37. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
37
www.aveva.com
For each object type, the table shows:
NAME The name of the method or member. For example, a REAL object has a method named
Cosine.
If there are any arguments, they are indicated in the brackets () after the name. For
example, the REAL object has a method named BETWEEN which takes two REAL
arguments.
RESULT The type of value returned by the method. For example, the result of the method Cosine is a
REAL value. Some methods do not return a value: these are shown as NO RESULT.
STATUS This column is used to give other information about the method or members.
For methods, this column tells you whether the method MODIFIES the value of the object.
For members, this column tells you whether the member is SETTABLE (by the user) or
UNSETTABLE.
Note that for the system-defined PDMS object types, members correspond to PDMS attributes
ACTION This column tells you what the member or method does.
A large number of methods have been provided for the built-in PML data types: For example, for STRING
objects, you will find a method named Length.
!Name = ‘Tony Blair’
!NumberOfLetters = !Name.Length()
q var !NumberOfLetters
This method returns a REAL value (the number of characters in the string), but has NO EFFECT on the
variable itself.
Notice the dot separator between the name of the variable and the name of the method.
Also note the () brackets following the name of the method. The brackets are used to enclose the arguments
of the method, but they must be present.
The following method creates an ARRAY of STRINGS:
e.g. !NameStrings = !Name.Split()
9.6 Method Concatenation
It is possible to apply multiple methods to the same variable within the same line of code. This process will
work providing the data passed at each stage is valid. Try the following on the command line:
!line = 'hello world how are you'
!newline = !line.upcase().split().sort()
q var !line !newline
<STRING> 'hello world how are you'
<ARRAY>
[1] <STRING> 'ARE'
[2] <STRING> 'HELLO'
[3] <STRING> 'HOW'
[4] <STRING> 'WORLD'
[5] <STRING> 'YOU'
38. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
38
www.aveva.com
9.7 The !!CE Object
A special GLOBAL PML variable !!CE always points to the current PDMS element and its attributes. Type q
var !!CE onto the command line and compare it against typing q att. You will notice the returned attribute
information is the same of the members list of the !!CE object.
This means that the !!CE object can be used to assign the values of attributes to !variables
For example, !BranchHeadBore = !!CE.Hbore assigns the HBORE attribute (taken from the current BRAN
element) to the variable !BranchHeadBore making it real.
If the !!CE object member is an object itself, that object will also have members so further information be
obtained e.g.
!HeadPosition = !!CE.Hpos.East East member from a POSITION object
!Easting = !!CE.Href.Cpar[1] Cata parameter member (attribute) of a DBREF object
If the !!CE object member is an object with built-in methods, these methods can also be called:
!PosWRTValve = !!CE.Hpos.WRT(ZONE) POSITION object w.r.t the owning ZONE
This process can also be reversed allowing the setting of attributes for the CE. This means that it is possible
to record the current value of an attribute, modify and reassign back to the CE. For example, type out the
following onto the command line:
!Pos = !!CE.Pos
q POS
!Pos.Up = 2000
!!CE.Pos = !Pos
q POS
These lines will have moved the CE up by 2000. Try this example again with some other attributes.
9.8 PML2 Functions
Functions are new style macros which are pre-loaded by PDMS and can be called directly. For example, to
call the function called FuncName.pmlfnc, type !!FuncName() onto the command line.
A function is defined within a .pmlfnc file stored within the PMLLIB file path. For an example of a function,
type the following into a new file and save it as c:pmltrainingpmllibfunctionsNameCE.pmlfnc.
define function !!NameCE()
!ce = !!CE.fullname
$p $!ce
endfunction
To run this function, type !!NameCE() onto the command line. You will notice the fullname is printed below
it. This is an example of a NON-RETURN function with NO ARGUMENTS.
If the function can be given arguments which are then assigned to variables with the function. If a variable is
returned, this means that the function can be assigned to another variable or as part of a calculation. Type
out the following, and save it as c:pmltrainingpmllibfunctionsArea.pmlfnc:
define function !!Area(!Radius is REAL) is REAL
!CircleArea = !Radius.Power(2) * 3.142
return !CircleArea
endfunction
As this function is an example of a RETURN function with an ARGUEMENT, it can be used as part of an
expression. The returned value is based the functions argument and its type (REAL in this case):
39. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
39
www.aveva.com
!Height = 64
!CylinderVolume = !!Area(2.3) * !Height
q var !CylinderVolume
As indicated by the !!, functions are global. This means that once defined, they can be called by any form or
method within PDMS minimising repetitive code.
Synonyms are disabled inside functions
Exercise 5(a) – Convert the Hose reel macro into a function
This exercise will cover how to update existing macros to make use of updated functionality.
The macro that will be updated is c:pmltrainingmacrosex5.mac. Have a look at the file. It uses the
READ method and this technique is no longer valid. How can the required values be passed to the macro?
A function can be used to allow input values. Save the updated macro as a function called ex5a.pmlfnc in
the directory c:pmltrainingpmllibfunctions
To begin with, define a function with one argument: The name of the equipment. Apply suitable error
handling to the function and check it works. After typing PML REHASH ALL, type !!ex5a(‘HoseWheel’) and
a new hose wheel will be created.
Look at the macro and you will see it uses the same hand wheel we have defined so far.
The function uses the variable !WheelDia to alter the diameter of the hand wheel. Update the function by
adding another argument, the diameter of the hand wheel. Test your function and see the impact of altering
this variable.
40. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
40
www.aveva.com
Exercise 5(b) – Adding arguments to the function
Extend the function written in exercise 5a to accept two more arguments:
• the width of the hosewheel
• the diameter of the hose wheel.
Rewrite parts of the functions so that hosewheel will change size based on these inputted numbers. How do
the primitives in the hosewheel relate to these dimensions.
Reduce the lines of code by introducing DO loops and PML2 syntax
Save the updated function as a function called ex5b.pmlfnc in the directory
c:pmltrainingpmllibfunctions
Type show !!ex5plt to see an dimensioned plot file
!!ex5b(|Hose-Reel-001|, 1000, 2000)
41. 41
www.aveva.com
CHAPTER 10
10 Forms
10.1 Forms Are Global Objects
Forms now look like GLOBAL OBJECTS, with Gadgets as their MEMBERS. Once loaded, the information
held within a form can be accessed at anytime.
To find out information about the form, it can be queried as if it was an object. For example, lets use the
Graphics Settings form (Settings>Graphics…)
Type Show !!gphsettings onto the command line to see the form in question or choose it from the menu
Type q var !!gphsettings onto the command line. The information is a list of the members of the form.
Compare this list against some of the gadget s on the form. As gadgets are members of forms, we can find
information about these.
The first gadget listed is called OK (representing the OK button on the form). Type q var !!gphsettings.ok.
The information returned is information about the button. Specific information about the gadget can be
queried directly e.g.:
q var !!gphsettings.ok.tag
q var !!gphsettings.ok.val
q var !!gphsettings.ok.active
To get the name of a shown form, type show !!pmlforms. This form can list shown forms
10.2 Dynamic loading of Objects, Forms and Functions
When a PML object is used for the first time, it is loaded automatically. This applies to both FORMS and
OBJECTS e.g.:
!Person = object PRIMEMINISTER()
show !!MyInputForm
Once an object is loaded by PDMS, the definition is held by PDMS. This means that if the object is changed
whilst it is loaded, the form will need to be reloaded. To reload a form type pml reload form or object
followed by the object name e.g.:
pml reload form !!MyInputForm
pml reload object PRIMEMINISTER
If a new file is created whilst PDMS is open, the file will not be mapped (even if it is saved in an appropriate
file path). The remap files type pml rehash. This will remap all the files within the first file path in the
PMLLIB variable.
The remap all files in all the file paths, type pml rehash all
42. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
42
www.aveva.com
10.3 Form Definition...
Forms are defined within .pmlfrm files and should be defined in the following way. A .pmlfrm file can contain
the form setup definition and any methods created in association:
setup form !!fname
...
exit
define method .init()
...
Endmethod
10.3.1 Using the .net framework
Form objects can now make use of the .net framework. This allows new features to be included on forms:
• Docking forms (automatic resizing)
• Anchoring gadgets (useful when resizing)
• Multicolumn lists
• Tabs on Forms
• Menu Additions to existing applications:
• Toolbar Additions to existing applications
• DBAR Conversions
Although it is now possible to dock forms, it does not apply to every form. There are some rules to consider
when deciding if a form should dock:
• Does the form need to remain open?
• Is the form used heavily
• If a form has an OK/Cancel button, it should not need docking
• If a form has a menubar, it CANNOT be docked
To declare a form as dockable, this has to be done on the top of the definition. By including dialog dock left,
we are stating that the form is displayed, it shall already be docked to the left:
setup form !!fnam dialog dock left
To define a floating, dockable form, use the following line:
setup form !!fnam dialog resizeable
To define a form of a certain size in the centre of the screen, use the following line:
setup form !!fnam document at xr 0.5 yr 0.5 size 100 100
If no additional details are included, the default form creation is a Dialog, non-resizeable, size adjusted
automatically to fit contents form.
For more examples, refer to the FORM object in the PDMS Software Customisation Reference Manual
10.3.2 Showing and hiding Forms
Now forms can be found through the PMLLIB search path, there is no longer the need to load them
individually. To show a form use show !!formname. This will load the form definition and show it in one go!
Sometimes it is useful to have the form loaded with seeing it (e.g. to refer to stored information). A form can
be loaded (but not shown) by typing loadform !!formname
43. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
43
www.aveva.com
10.3.3 Built-in methods for Forms
Although is possible to define user-defined methods within user-defined forms (discussed later), all FORM
objects have built-in methods available. Try on the following on the command line:
!!gphsettings.show()
q var !!gphsettings.shown()
!!gphsettings.hide()
q var !!gphsettings.shown()
In this example, the .show() method is used to show the form, the .shown() method returns whether the form
is shown and the .hide() method hides the form.
For more examples, refer to the FORM object in the PDMS Software Customisation Reference Manual
10.4 Callbacks
If an object has a CALLBACK member, it can be given a callback string. This means that if the user
interacts with the object, an action can be performed. The callback can do one of three things:
• show a form
• execute a command directly
• run a function or method
A FORM object has some special callbacks which are used when the form completes certain actions (e.g.
Shown, closed)
Copy out the following into a new file and save it as Callback.pmlfrm. Put the file into the appropriate file
path c:pmltrainingpmllibforms and remap the files. To see the form, type show !!Callback. Press the
buttons look at the command line.
setup form !!Callback
!this.formTitle = |Callback Example|
!this.initcall = |!this.init()|
!this.okcall = |!this.okCall()|
!this.cancelcall = |!this.cancelCall()|
!this.quitcall = |!this.quitcall()|
button .ok ' OK ' OK
button .can 'Cancel' at x30 CANCEL
exit
define method .Callback()
$p --Constructor Method--
endmethod
define method .init()
$p --Initialise Method--
endmethod
define method .okcall()
$p --OK Method--
endmethod
define method .cancelcall()
$p --Cancel Method--
endmethod
44. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
44
www.aveva.com
define method .quitcall()
$p --Quit Method--
endmethod
At the top of the form, the callback members of the form where set user-defined methods within the form.
• The CONSTRUCTOR method was called when the form loaded (notice, it has the same name as
the form).
• The INITCALL method is called everytime the form is shown (perfect for setting default values
• The OKCALL method is called by any button gadget with the OK in its definition
• The CANCELCALL method is called by any button gadget with CANCEL in its definition
• The QUITCALL method is called by clicking the close button on the form.
If no callbacks are defined for OKCALL, CANCELCALL and QUITCALL the default is to hide the form
only
10.5 Form Gadgets
There are many kinds of form gadgets, each an object that will have its own members and methods. When
you are defining gadgets on a form, there are two common aims:
• Define the area to be taken up on the form
• Define the action to be taken if the gadget is selected
It is the position and size of the gadget that determines the area taken up and its action is defined by its
CALLBACK member.
10.5.1 Built-in members and methods for Gadgets
As Gadgets are objects, there are a variety of useful members and built-in methods that can be used. Using
the previous example (!!Callback), type the following onto the command line:
To grey-out the OK button
!!Callback.ok.Active = FALSE
To hide the CANCEL button
!!Callback.can.Visible = FALSE
Apply a tooltip to the OK button
!!Myform.ok.setToolTip(|This is an OK button|)
For further information, PDMS Software Customisation Reference Manual
45. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
45
www.aveva.com
10.5.2 Gadget positioning
Gadgets are positioned on a form from top left using the AT syntax. The AT syntax defines the origin of the
gadget in relationing to the owning object (i.e. FORM or FRAME). .
Gadgets can be positioned explicity or in relation to other gadgets. When referring to other gadgets, there 6
known positions on a gadget: XMIN, XCEN, XMAX, YMIN, YCEN and YMAX. These refer to fixed position
in the x and y directions on the referenced gadget. A gadget can be thought of as an enclosing box that will
enclose the geometry of the gadget (including its name tag if specified).
To position a gadget at a known position use:
at x 0 y 0
To position the above CANCEL button use Xmax and Ymin of OK use:
at xmax.ok + 10 ymin.ok
To position a DISMISS button in the bottom corner of a form use:
at xmax form – size ymax form
For more positioning syntax, refer page 2-59 in the PDMS Software Customisation Reference Manual
The available syntax and its order can be derived by referring to the SYNTAX GRAPHS in the reference
manual. These diagrams are available for most Gadgets and can be used when initially defining them. The
picture below is an example of the Syntax Graph for gadget positioning (<fgprl> refers to another graph):
Refer PDMS Software Customisation Reference Manual for more guidance on these graphs
46. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
46
www.aveva.com
10.5.2.1 Position Gadgets using the path command
The path command can be used to define the logical position of subsequent gadgets. This method has
been superseded by the previous method and has been included for information.
After a gadget has been defined, the next gadget is positioned based on a PATH, HDIST or VDIST and
HALIGN or VALIGN. As an example, see the picture below:
Button .But1 $* default placement
PATH down
HALIGN centre
VDIST 2
paragraph .Par2 width 3 height 2 $* auto-placed
toggle .Tog3 $* auto-placed
PATH right
HDIST 3
VALIGN bottom
List .Lis4 width 2 height 3 $* auto-placed
PATH up
HALIGN right
Paragraph .Par5 width 3 height 3 $* auto-placed
10.5.3 Docking and Anchoring Gadgets
After a gadget has been loaded its size and position are locked. To modify the position or size manually, the
alterations have to be made in the file and the form reloaded. As forms can be resized, it is necessary for
gadgets to move/resize so the layout of the form remains.
There are two available syntax definitions that can help DOCK or ANCHOR. This syntax should be included
when defining a gadget and can be included if <fgdock> or <fganch> are included in the gadgets syntax
graph.
The DOCK and ANCHOR are mutually exclusive so only one is defined per gadget
ANCHOR controls the position of an edge of the gadget relative to the corresponding edge of its container.
For example, if a DISMISS button is anchored to the Right + Bottom, it will remain in the bottom, right of the
form if it is resized.
DOCK forces gadget fill the available space in a certain direction. For example, if a list is docked to the left,
it will maintain its width, but its height will change it fill its container. DOCK FILL is very useful for ensuring a
gadget is the full size of its container.
Copy out the following into a new file and save it as DockExample.pmlfrm. Put the file into the appropriate
file path c:pmltrainingpmllibforms and remap the files.
setup form !!DockExample dialog resizeable
!this.formTitle = |Dock and Anchor|
!buttpos = |xmax.f1 - size ymax.f1 - size|
frame .f1 anchor ALL width 30 height 5
button .butt1 |Dock TOP| dock TOP
button .butt2 |Anchor B+R| at $!buttpos anchor R+B
exit
exit
47. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
47
www.aveva.com
Resize the form and observe the results.
Once a gadget is declared as Anchored or Docking it will remain so. If a change is required, the form
definition should be updated and the form reloaded.
Refer PDMS Software Customisation Reference Manual for the Syntax Graphs.
10.6 Paragraph Gadgets
Paragraph gadgets are simple named gadgets which allow a piece of TEXT or a PIXMAP to be displayed on
a form. It is a passive gadget that cannot be selected by the user so has no callback. Paragraph gadgets
are used display either instructions or pictures.
Copy out the following into a new file and save it as ParaExample.pmlfrm. Put the file into the appropriate
file path c:pmltrainingpmllibforms and remap the files.
setup form !!ParaExample
!this.formTitle = |Paragraphs|
para .para1 text |Normal paragraph gadget| width 20
para .para2 at x 0 ymax.para1 backg 6 text |A cyan paragraph gadget| width 20
para .para3 at x 0 ymax.para2 pixmap width 154 height 50
para .para4 at x 0 ymax.para3 + 0.5 text || wid 20 hei 2
exit
define method .ParaExample()
-- Update the displayed text using CONSTRUCTOR method
!this.para4.val = |Above was a PIXMAP, this is on two lines|
-- Use built-in method to apply picture
!this.para3.AddPixmap(|c:pmltrainingpmllibimagesaveva.png|)
Endmethod
Refer to the Reference Manual and Guide for more examples
The last value of the last gadget was set during the CONSTRUCTOR method. empty paragraph gadgets
can be created to reserve space with values set after creation..
10.7 Button Gadgets
Button gadgets are typically used to invoke an action or to display a child form. Its CALLBACK can call a
LOCAL METHOD, GLOBAL FUNCTION or OBJECT METHOD. If a callback and a child form are both
specified, the callback command will be run before the child form is displayed.
Copy out the following into a new file and save it as ButtonExample.pmlfrm. Put the file into the
appropriate file path c:pmltrainingpmllibforms and remap the files.
setup form !!ButtonExample dialog resizeable
!this.formTitle = |Buttons|
button .butt1 |Normal|
button .butt2 |Green| backg 5
button .butt3 |Deactive|
button .butt4 |form| form !!ParaExample
button .butt5 toggle backg 4 call |!this.check()| pixmap wid 31 hei 21
exit
define method .ButtonExample()
-- Deactivate butt3 in CONSTRUCTOR method
!this.butt3.active = FALSE
-- Use built in method to apply pictures
!this.butt5.AddPixmap(|c:pmltrainingpmllibimagesoff.png|, |c:pmltrainingpmllibimageson.png|)
48. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
48
www.aveva.com
endmethod
define method .check()
-- Return the toggle button value to the command line
!check = !this.butt5.val
$p $!check
endmethod
Refer to the Reference Manual and Guide for more examples
As .butt5 was set as a toggle button, it has either a TRUE or FALSE state. This means that a toggle button
holds a .val member which can be set or queried.
10.7.1 Linklabel
The Linklabel, provides a purely textual button presentation, i.e. it has no enclosing box. It is often used to
indicate a link to some application item, e.g. a hyperlink to a file, a link to an associated form. They do cause
validation of any modified text fields of the form whenever they are pressed.
The tag text is shown in a different colour to all other gadget's tag text. The link label gadget highlights by
underlining when the mouse cursor passes over it. Pressing it causes a SELECT event to be raised and
runs any associated call back.
Linklabels have the following restrictions:
• They don't support change of background colour.
• They don't support 'pressed' and 'not pressed' value.
• They can have popup menus, though this is not recommended.
• They don't have Control Types e.g. OK, CANCEL etc.
Copy out the following into a new file and save it as LinkLabelExample.pmlfrm. Put the file into the
appropriate file path c:pmltrainingpmllibforms and remap the files
setup form !!LinkLabelExample dialog resizeable
!this.formTitle = |LinkLabel|
button .butt1 |Paragraph Form| linklabel form !!ParaExample
exit
10.8 Text Entry Gadgets
A text input gadget provides the user a way of entering a single value into PDMS. A TEXT gadget is defined
by:
WIDTH – determines the displayed number of characters. An optional scroll width can also be specified
TYPE – determines the type of the variable created when inputting a value. This is important when PML
uses the variable. You may also supply a FORMAT object (explained below) to format the value entered
(e.g. whole number)
Copy out the following into a new file and save it as TextExample.pmlfrm. Put the file into the appropriate
file path c:pmltrainingpmllibforms and remap the files.
49. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
49
www.aveva.com
setup form !!TextExample
!this.formTitle = |Text|
path down
text .txt1 |Val as String | width 10 is STRING
text .txt2 |Only numbers | width 10 is REAL format
!!REALFMT
text .txt3 |Round numbers | width 10 is REAL format
!!INTEGERFMT
text .txt4 |For passwords | width 10 NOE is STRING
text .txt5 |Limited scroll| width 10 scroll 1 is STRING
text .txt6 |Not editable | width 10 is STRING
exit
define method .TextExample()
-- Make Text 6 uneditable
!this.txt6.val = |Cannot change!|
!this.txt6.setEditable(FALSE)
endmethod
The benefit of making a text gadget uneditable (rather than deactivated) is so the user can select its
contents. A deactive text box will be full greyed out and unselectable.
Refer to the Reference Manual and Guide for more examples
10.9 Format Object
A FORMAT object manages the information needed to convert a number (always in mm) to a STRING. It
can also be used apply a format to a text gadget. A format objects are usually defined as global variables so
that they are available across PDMS. For example, type the following onto the command line:
!!OneDP = object FORMAT()
!!OneDP.dp = 1
q var !!OneDp
There are four standard FORMAT objects which are already defined in standard PDMS:
!!DistanceFmt For distance units
!!BoreFmt For Bore Units
!!RealFmt To give a consistent level of decimal places on real numbers
!!IntegerFmt To force real numbers to be integers(0 dp Rounded)
To find out more information about these FORMAT object, query them as global variables on the command
line q var !!BoreFmt
For example the number of decimal places displayed using !!RealFmt could be set !!RealFmt.dp = 6 the
default value is 2.
These standard format objects are used within the forms of PDMS. Changing the definition of these objects
will change the way standard product behaves.
50. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
50
www.aveva.com
10.10List Gadgets
A LIST gadget presents and ARRAY of values to the user. This can be a SINGLE or MULTI-
DIMENSIONAL ARRAY
All the values in the gadget are set by assigning an ARRAY. ARRAY variables can be applied to a LIST at
any time. The choice between MULTIPLE, COLUMN and SINGLE has to be made when the gadget is
defined. The values within a COLUMN list (headings and values) are set by using built-in gadget methods.
Copy out the following into a new file and save it as ListExample.pmlfrm. Put the file into the appropriate
file path c:pmltrainingpmllibforms and remap the files
setup form !!ListExample
!this.formTitle = |Lists|
!vshap = |width 15 height 6|
list .lst1 |Single Array List| call |!this.value()| SINGLE ZEROSEL $!vshap
list .lst2 |Multi-Select List| MULTI $!vshap
list .lst3 |Appending List| call |!this.append()| $!vshap
list .lst4 |Multi-column List| COLUMNS $!vshap
exit
define method .ListExample()
-- Define values contained within the lists
do !I from 1 to 5
!Dvalue[!I] = |Number| & !I
!Rvalue[!I] = |<| & !I & |>|
do !J from 1 to 2
!multi[!I][!J] = |col | & !J & |(| & !I & |)|
enddo
enddo
!this.lst1.dtext = !Dvalue
!this.lst1.rtext = !Rvalue
!this.lst2.dtext = !Dvalue
!single[1] = |Click to append values|
!this.lst3.dtext = !single
!this.lst4.setRows(!multi)
!heading[1] = |One|
!heading[2] = |Two|
!this.lst4.setHeadings(!heading)
endmethod
define method .value()
--Print the Dtext and Rtext values to the command line
!dtext = !this.lst1.selection('Dtext')
!rtext = !this.lst1.selection('Rtext')
$p Selected Dtext is $!<dtext> (Rtext is $!<rtext> - hidden!)
endmethod
define method .append()
-- Append value to List 3
!nextLine = !this.lst3.dtext.size() + 1
!val = |Appended | & !nextLine
!this.lst3.add(!val)
Endmethod
51. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
51
www.aveva.com
Refer to the Reference Manual and Guide for more examples
52. AVEVA Plant (12 Series)
Programmable Macro Language - TM-1401
52
www.aveva.com
10.11Frame Gadgets
A FRAME is a cosmetic gadget which is used to surround a group of similar gadgets. This helps with
organisation, positioning and user experience. A frame can also be declared as a TABSET or a RGROUP
(explained later) and even a TOOLBAR (when defined for the main PDMS window).
Copy out the following into a new file and save it as FrameExample.pmlfrm. Put the file into the
appropriate file path c:pmltrainingpmllibforms and remap the files
setup form !!FrameExample dialog resizeable
!this.formTitle = |Frames|
frame .tabset TABSET anchor ALL wid 15 hei 5
frame .f1 |Docked| at 0 0 dock FILL
frame .fA |Dock All| dock FILL
frame .fB |Dock Right| dock RIGHT wid 10
frame .fC |Dock Bottom| dock B hei 4
exit
exit
exit
exit
frame .f3 |Other| at 0 0 dock FILL
!pos = |at xcen.fG - 0.5 * size ymax|
frame .fG |Deactive| wid 15 hei 4
button .but1 |Try and click!| at 1 1
exit
button .but |Show Frame| $!pos backg 8 call |!this.showF()|
frame .fH |Hidden Frame| at xmin.fG ymax.but2 width.fG hei.fG
exit
exit
exit
exit
define method .FrameExample()
!this.fG.active = FALSE
!this.fH.visible = FALSE
endmethod
define method .showF()
if !this.but.val.eq(TRUE) then
!this.fH.visible = TRUE
!this.but.tag = |Hide Frame|
else
!this.fH.visible = FALSE
!this.but.tag = |Show Frame|
endif
endmethod
When creating a FRAME gadget, for every FRAME there must be an associated EXIT.
If insufficient exits are provided, this will cause an error and the form will NOT LOAD. As the error occurred
in side the FORM DEFINITION, the command line will still be in form definition mode and will not function as
usual.
To exit this mode, type EXIT on the command line until and ERROR is received. This will mean that form
definition mode has been exited and normal commands will work again.
It is good practise to provide 2 spaces when working inside a code block. This provides an easy way to spot
missing exits.