Software Customisation Guide

8/13/2019 Software Customisation Guide

1/252

Software

Customisation Guide


2/252

Disclaimer

Information of a technical nature, and particulars of the product and its use, is given by AVEVASolutions Ltd and its subsidiaries without warranty. AVEVA Solutions Ltd and its subsidiaries disclaimany 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.

Copyright

Copyright and all other intellectual property rights in this manual and the associated software, and everypart of it (including source code, object code, any data contained in it, the manual and any other documentation supplied with it) belongs to AVEVA Solutions Ltd or its subsidiaries.

All other rights are reserved to AVEVA Solutions Ltd and its subsidiaries. The information contained inthis document is commercially sensitive, and shall not be copied, reproduced, stored in a retrievalsystem, or transmitted without the prior written permission of AVEVA Solutions Ltd. Where suchpermission is granted, it expressly requires that this Disclaimer and Copyright notice is prominentlydisplayed at the beginning of every copy that is made.

The manual and associated documentation may not be adapted, reproduced, or copied, in any materialor electronic form, without the prior written permission of AVEVA Solutions Ltd. The user may also notreverse engineer, decompile, copy, or adapt the associated software. Neither the whole, nor part of theproduct described in this publication may be incorporated into any third-party software, product,machine, or system without the prior written permission of AVEVA Solutions Ltd, save as permitted bylaw. Any such unauthorised action is strictly prohibited, and may give rise to civil liabilities and criminalprosecution.

The AVEVA products described in this guide are to be installed and operated strictly in accordance withthe terms and conditions of the respective license agreements, and in accordance with the relevantUser Documentation. Unauthorised or unlicensed use of the product is strictly prohibited.

First published September 2007

AVEVA Solutions Ltd, and its subsidiaries

AVEVA Solutions Ltd, High Cross, Madingley Road, Cambridge, CB3 0HB, United Kingdom

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 itssubsidiaries, registered in the UK, Europe and other countries (worldwide).

The copyright, trade mark rights, or other intellectual property rights in any other product, its name or logo belongs to its respective owner.

AVEVA Solut ions Ltd


3/252

Software Customisation Guide

Contents Page

12.0i


Customisation Guide

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1Customising a Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1

Serious Warning About Software Customisation . . . . . . . . . . . . . . . . . . . . . . . . 1:1

How to Use th is Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2Hints on the Trying the Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2

Minimising Problems for Future Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2

Note for Users Familiar with OO Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:4

Variables, Objects, Functions and Methods . . . . . . . . . . . . . . . . . . . 2:1PML Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1

Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1

Members and Attr ibu tes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:2

User-defined Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:2Storing Object Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3

Creating Variables (Objects) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3Local and Global Variable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3Notes on Naming Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3Creating a Variable with a Built-in Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:4Creating Other Types of Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:5Using the Member Values of an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:5

PML Funct ions and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:5Storing and Loading PML Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:7


4/252

12.0ii


PML Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:7

Arguments of type ANY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:8

Using the Methods of an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:9Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:9

Methods on User-Defined Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:10Method Overloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:11Constructor Methods with Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:11Overloading with ANY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:11Invoking a Method from Another Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:12Developing a PML Object with Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:12

Unset Variable Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:12

UNSET Values and UNDEFINED Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:13

Deleting PML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:13

Forms as Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:13

General Features of PML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1Funct ions, Macros and Object Defini tions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1Comments in PML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1Leaving a PML File with the RETURN Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2

Case Independence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2 Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2

Special Character $ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2

Text Delimiters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3

Filename Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3

Storing and Loading PML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3Rebuilding All PML File Indexes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4Querying the Location of PML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4

PML Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:1Format of Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:1

Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:2

Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:2

Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:3

Nesting Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:3

PML 1 and PML 2 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:3

PML 2 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4:3


5/252

12.0


ii i

Control Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:1IF Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:1Nesting if-constructs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:2BOOLEAN Expressions and if Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:2IF TRUE Expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:4

DO Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:4Stopping a DO loop: break and breakif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:5Skipping Commands in a DO Loop using Skip or Skip if . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:6Nested DO Loops. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:6

Jumping to a Labelled Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:6Conditional Jumping to a Labelled Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:7Illegal Jumping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5:7

Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:1Creating Array Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:1

Arrays o f Arrays (Multi -dimensional Arrays). . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:2

Array Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:2Appending a New Element to an Existing Array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:3Deleting an Array Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:3Deleting an Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:3Splitting a Text String into Array Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:3Length of String Array Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:4

Sort ing Arrays Using Array Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:4

Sort ing Arrays using the VAR Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:6

Subtotalling Arrays with the VAR Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:9

Arrays o f Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:10DO Values with Arrays of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:10Block Evaluation And Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:10Using Block Evaluate to Sort an Array of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:11DO VALUES and DO INDICES with Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6:11

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7:1PML Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7:1Naming and Running Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7:1Macros with Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7:1

Using Macros and Funct ions Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7:3

Synonyms in PML Macros and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7:4


6/252

12.0iv


Using PML in AVEVA Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:1Composing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:1

Defining Variables for Late Evaluation (Rules) . . . . . . . . . . . . . . . . . . . . . . . . . . 8:2

Using PML in PDMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:2Accessing DB Elements As Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:2Assigning Values to Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:3Accessing Information About a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:4Evaluating Selected DB Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:4RAW keyword When setting Variables with VAR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:5Undo and Redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8:5

Copies and References (for Advanced Users) . . . . . . . . . . . . . . . . . 9:1 Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9:1

Form and Gadget References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9:1

DB References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9:1Deep Copy involving References: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9:2

Funct ion Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9:2Constants as Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9:2Form and Gadget Properties Passed as Function Arguments. . . . . . . . . . . . . . . . . . . . . . . 9:3

Database Attr ibutes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9:3

Errors and Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10:1Error Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10:1

Handl ing Erro rs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10:1

Setting the ONERROR Behaviour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10:2

Other Responses to an Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10:3

Handling Files and Directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11:1Creating a File Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11:1Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11:1

Reading f rom Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11:2

Writing to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11:2

Reading and Wri ting ARRAYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11:2

Error Handling When Using a File Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11:3

Developing PML Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:1

PML Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:1


7/252

12.0


v

Diagnostic Messages From Within PML Files . . . . . . . . . . . . . . . . . . . . . . . . . . 12:1

Alpha Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:2

Alpha Log and PML Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:2Suspending a Running PML Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:2

Query ing PML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:2Querying the Currently Running PML File Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:3Querying the Values of PML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:3Querying What Can Be Typed Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12:3

Form Concepts : Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:1

Naming Forms and their Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:1

Simple Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:2Adding a Gadget Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:3

Form Defini tion File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:4

How Forms are Loaded and Displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:4

PML Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:5

Revisi ting our Simple Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13:6

Form and Gadget Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:1Callbacks: Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:1

Callbacks: Form Methods / PML Funct ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:1

PML Open Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:3Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:3Open Callbacks at Meta-events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:3Using a PML Function in an Open Callback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:5Objects That Can Have Open Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:6

Undo/Redo Support for Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:6Form Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:8Gadget Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:9Menu and Menufield Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:9

Core Managed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14:9

Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:1Modules and Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:1Application Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:1

Current Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:2


8/252

12.0vi


Defining a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:2Form Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:3

Form Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:3Minimum Size and Resizability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:4Intelligent Resizable Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:4Gadget Alignment Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:5

Form Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:5Form Title and Icon Title. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:5Form Initialisation Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:5Form OK and CANCEL Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:6Quit/Close Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:7

FIRSTSHOWN callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:8KILLING callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:8Form Variables: PML Variables within a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:9Querying Form Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:9

Loading, Showing, and Hiding Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:10Free Forms and Form Families . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:10Loading and Showing Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:10Position of Forms on the Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:11Hiding Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:12

Killing Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:12NOQUIT Form Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:12

CORE Managed Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15:12

Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:1Menu Types and Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:1Hints and Tips for Using Menu Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:1Core-Code Based Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:2

Defining a Bar Menu Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:2

Defining a Menu Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:3Window Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:4Online Help Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:4Popup Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:5Finding Who Popped up a Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:6Toggle Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:6

Edit ing Bars and Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:7Inserting Menus into a Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:7Inserting New Menu Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:8

Changing the State of Menufields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:9


9/252

12.0


vi i

Implied Menu-field Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:10Creating Menus Dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16:11

Form Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:1Form Coordinate System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:1Form Setup NOALIGN Property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:2Gadget Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:2

Positioning Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:2

Auto-placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:3Positioning Gadgets on a Defined Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:3Setting the Distance Between Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:3

Gadget Alignment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:4How It All Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:4Positioning Gadgets and Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:6

Relative Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:6Positioning Relative to the Last Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:6Positioning Relative to the Form Extremities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:7

Mixing Auto and Relative Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:8

Abso lute Gadget Posi tioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:8

AT Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:9

Intell igent Positioning and Resizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:11The ANCHOR Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:12The DOCK Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17:12

Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18:1Types of Frame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18:1Normal Frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18:1Tabset Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18:1Toolbar Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18:2PANEL Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18:2Fold Up Panel Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18:2

Gadgets and their Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:1Gadget Definit ion Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:2

Some Generic Gadget Members and Methods . . . . . . . . . . . . . . . . . . . . . . . . . 19:3

Gadget Size Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:3The Effect of the Tag on Gadget Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:3User Specifiable Tagwidth for TEXT, TOGGLE and OPTION Gadgets. . . . . . . . . . . . . . . 19:3


10/252

12.0viii


Specifying Gadget Size Relative to Other Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:4An Example Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:4

The Meaning of Size for the PML Gadget Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:6Gadgets that Suppor t Pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:7Selected and Unselected States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:7AddPixmap Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:7

De-activating gadgets: Greying Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:8Greying Out Gadgets on Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:8

Making Gadgets Vis ible and Invisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:9Making Gadgets Visible and Invisible in Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:9

Setting Keyboard Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:9

Refreshing Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:10

Gadget Background Colour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19:10

Gadget Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:1Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:1Simple Form Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:1Complex Form Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:3

Frame Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:10

Defining a Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:10Frame Radio Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:11Managing Pages in Tabset Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:14Managing the Fold Up Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:14

CONTAINER Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:15Example of Container Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:16

Paragraph Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:19Textual Paragraph Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:19Pixmap Paragraph Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:19

Textual Paragraph Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:20Button Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:20Buttons of Type Toggle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:20Buttons of type LINKLABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:21Form Control Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:21Defining a Dismiss Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:22

Toggle Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:22

RToggle Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:23

Option and Combobox Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:25


11/252

12.0


ix

Textual Option Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:25Combobox Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:26

Pixmap Option Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:26Setting and Getting the Current Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:27

Slider Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:27Event Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:28

Line Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:28

Numeric Input Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:28

List Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:29Single Choice List Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:30Multiple Choice List Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:31Multi-Column List Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:33

Database Selector Gadgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:34

Text Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:35Controlling Text Gadgets Editing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:36Copying and Pasting into Text Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:38Formatting in Text Input Gadgets: Imperial Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:38Unset Text Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:40Validating Input to Text Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:40

Setting the Value of a Text Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:43TextPane Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:43Cut and Paste in Textpanes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:44

Fast Access to Lists, Selectors and Textpanes using DO Loops . . . . . . . . . 20:44

View Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:45Defining a View Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:45Resizable View Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:45Pop-up Menus in Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:46Defining Alpha Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:46

Graphical Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:48Defining PLOT Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:50Defining DRAFTs Area (2D) Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:50Defining DESIGNs Volume (3D) Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20:52

Aler t Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21:1Position of Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21:2Input Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21:2

FMSYS Object and i ts Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:1


12/252

12.0x


Setting the Default Format of Text Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:1

Querying Forms & Menus System Information . . . . . . . . . . . . . . . . . . . . . . . . . 22:1

Swapping Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:2Progress and Interrupt Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:2

Refreshing View Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:3

Checking References to Other Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:3

Splash Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:4

Default Form Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:4

CurrentDocument () Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:4

LoadForm() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:4Cursor Funct ion Suppor t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22:4

PML Add-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:1 Appl icat ion Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:1Main Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:2Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:2Defining an Add-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:2Add-in Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:4

Initialisation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:4Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:5APPMENU Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:5Addition of Menu Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:5Removing Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:6Modifying the Bar Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:6

Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:7Toolbar Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:7Removing Gadgets from a Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:8

Deactivating Gadgets on a Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:8Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:8Registering a Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:8Hiding Forms when Exiting Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:9Storing Data Between Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:9

Converting Existing User-defined Applications . . . . . . . . . . . . . . . . . . . . . . . 23:10Replacement of the DBAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:10Menu Name Clashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:11Converting the DBAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:11


13/252

12.0


xi

Example Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:11Adding a Menu Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:11

Creating a Custom Delete Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23:12Core Managed Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1Form Core Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1FORM Core Code Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2

Gadget Core Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:2GADGET Core Code Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:3

Menufield Core Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:4MENUFIELD core code interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:4

PML Defined Menufields Managed by Application Framework Addins . . . . . . . . . . . . . . . . A:5Manipulating VIEWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B:1Manipulating 2D Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B:1

Manipulating 3D Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B:3


14/252

12.0xi i



15/252

Software Customisation GuideIntroduction

12.01:1

1 Introduction

This manual describes how to use PML, the AVEVA Programmable Macro Language. Youshould use it together with the Software Customisation Reference Manual.

You do not have to be a professional programmer to start to learn PML, although you mayfind this manual difficult to follow unless you have some understanding of programmingconcepts such as if statements and do loops. If you have no programming experience, youshould consider attending a PML Training Course. For details, contact your local supportoffice, whose address is given on the copyright page of this manual.

The current version of PML, sometimes referred to as PML2, may simply be seen as anextension to the original PML1 facilities. However, the more powerful techniques that areavailable mean that many programming tasks are carried out in different ways.

There are some tasks which are carried out more efficiently using PML 1 facilities. Theseare described in this manual where necessary, you should also refer to the DatabaseManagement Reference Manual.

1.1 Customising a Graphical User InterfaceMost AVEVA products make use of a Graphical User Interface (GUI) to drive the software.The interfaces provided with your AVEVA software are designed to apply to a wide range of situations and business needs. However, as you become more experienced with AVEVAproducts you may wish to design an interface that is more closely related to your requirements.

PML 2 has been specifically designed for writing and customising the Forms and Menus for AVEVA products. Almost all the facilities available in PML 1 and the older Forms and Menusfacilities continue to function as before even if they are not documented here.

Before you begin customising a GUI, you must have a good working knowledge of thecommand syntax for the AVEVA product you are working with. The commands aredescribed in detail in the reference manuals for the products.

1.2 Serious Warning About Software CustomisationThe ability to customise individual Applications to suit your own specific needs gives yougreat flexibility in the ways in which you use your system.

But it also introduces the risk that your modified macros may no t be compatible with futureversions of the software, since they are no longer under AVEVAs control.

Your own Applications may diverge from future standard versions and may not takeadvantage of product enhancements incorporated into the standard product.


16/252

12.01:2


To minimise this risk, it is most important that your in-house customisation policies constrainany changes which you make to the Applications so that they retain maximum compatibilitywith the standard product at all times.

Remember that AVEVA Ltd can give you full technical support only for products over whichit has control. We cannot guarantee to solve problems caused by software which you havewritten yourself.

1.3 How to Use this ManualChapters 2 to 12 describe the facilities available in PML2, with reference to the differencesbetween PML1 and PML2.

Chapters 13 onwards describe how to use PML2 to customise a GUI.

Appendix A contains detailed information for AVEVA developers on how to use core-code

managed objects.Appendix B contains details of how to manipulate the interactive 2D and 3D views.

1.3.1 Hints on the Trying the ExamplesThis manual is not really designed as a self-teach tutorial, although users who are alreadyfamiliar with PML 1 programming may be able to use it as such.

Because PML 2 is specifically designed to be used to create Forms and Menus, the bestway of experimenting is to start up an AVEVA product and display the command line.

You can then create a new form definition file, or edit an existing one, display the form, anduse it to call the PML Functions which you have defined in separate files.

The source files for some of the larger examples are available from the AVEVA web site, soyou can download them rather than having to type them in.

You can find them here under PDMS/Macro Library.

http://support.aveva.com/support/United_Kingdom/index.htm

1.4 Minimising Problems for Future UpgradesWhen future versions are released, the product documentation will identify which macro filesand which parts of the directory hierarchy have been modified. You must then decide on oneof three courses of action for dealing with any customised macros which you may have

been using: Run your existing macros, thereby ignoring any enhanced features which may have

been incorporated into the standard versions. Revert to using standard macros instead of your customised versions. Update your customised macros to take advantage of any enhanced features now

available.

In order to minimise any problems resulting from updating your customised macros, youshould adopt the following key principles as part of your customisation policy:

The directory which holds the macros associated with your Applications is divided intotwo main areas: a standard product area and a user area. You should makechanges only i n the User area using only copies of the standard Application macros.
http://support.aveva.com/support/United_Kingdom/index.htmhttp://support.aveva.com/support/United_Kingdom/index.htm


17/252


12.01:3

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

The environment variable PMLLIB is a search path which must be set to the directoryor list of directories under which user-defined PML Functions, objects and forms arestored. The directory specified can contain sub-directories which will automatically bescanned by PML.

When writing your own PML Application macros or functions , follow the styles andconventi ons us ed in the AVEVA standard AppWare .

Ensure that the names of any new forms which you create cannot conflict with thenames of any standard forms which may be used in the AVEVA Applications. Youshould prefix the names of your forms and global variables with a suitable code todistinguish them from AVEVA names. For example, a company XYZ could choose tostart all form and global variables names with the characters XYZ.

Current PML2 Naming Convention

The majority of the existing PML2 code has been given a three or four letter prefix to the fullname.

Ap pl icati on Pref ix Comments

Accommodation ACC

Administration ADM

Access platform, Stairs &Ladders

ASL

Area Based ADP ABA Add-in application

Assembly ASSYAssociations ASSOC None apparent

Common COMM Mixed

Design DES Mixed

Draft DRA Plus ADP, DGN, DXF

Final Designer DRA

Global GLB

Hull Design HULL

Hull Drafting HDRA NoneIntegrator INT

Isodraft ISO

Isometric ADP ISO Add-in application

Diagrams DIAG No appware except main form

Monitor MON

Paragon CAT

Review Interface REVI None - Single file


18/252

12.01:4


Icon naming

Icons are named without regard to any rules, except on odd occasions.

1.5 Note for Users Familiar with OO ConceptsPML2 is almost an object-oriented language. Its main deficiency is that it lacks inheritance.However, it does provide for classes of built-in, system-defined and user-defined objecttypes.

Objects have members (their own variables) and methods (their own functions ). All PMLVariables are an instance of a built-in, system-defined or user-defined object type.

Operators and methods are polymorphic what they do (their behaviour) depends onthe type of the variable. Overloading of functions and operators is supported for all variabletypes.

There is no concept of private members or methods, everything is public . There are onlytwo levels of scope for variables: Global and Local . Argu men ts to PML Functions arepassed-by-reference with Read/Write access so any argument can potentially be used asan output argument.

Router RTR

Spooler SPL

Training TRA

Folder Prefix Comments

Actions Various

Applications Various

Access platform, Stairs &Ladders

ASL

Assembly ADP AD

Constructs Various

Design DES Various

Draft DRAFT

Profile PRFL Various

Schematic Model Viewer SMV Various

Shapes No existing icons

Splash Various

Styles STY Plus FSTY



19/252


12.01:5

Warning: Changing the value of an argument inside a PML Functions or method willchange the value in the calling function or method .


20/252

12.01:6



21/252

Software Customisation GuideVariables, Objects, Functions and Methods

12.02:1

2 Variables, Objects, Functions and Methods

2.1 PML VariablesVariables are used to store values. Variables have names. The value that is stored can bechanged but the name is fixed. You choose the names and decide what is stored by eachvariable.

The variables used in PML 2 are objects: Every object (variable) has a unique name. An object has a set of functions associated with it, which can be called to manipulate

this data. These functions are called methods. Some methods change the data held by the object, some return a result derived from

the data, and some methods do both. The data that an object can hold and the functions that are available are fixed by the

object type (sometimes called the objects class ).

Before you can create an object, the object type must have been defined. The objecttype definition specifies what the members and methods are for that type of object.

2.2 Object TypesEvery PML2 variable has an object type which is set when the variable is created andremains fixed as long as the variable exists.

Attempting to store a value of the wrong type in an existing variable will cause an error. Theobject type must exist before you can create a variable of that type.

PML 2 is supplied with built-in object types, system-defined object types, and you can alsodefine your own user-defined object types.

The built-in object types include the following:

Object Description

STRING This holds any text, including newline and multi-bytecharacters such as Kanji. In macros written with PML1where variables are created with the VAR command, allvariables are of type STRING , even when they are storingnumbers

REAL This is used for all numeric values including do loopcounters. There is no separate integer type


22/252

12.02:2


There are also system-defined variable types, such as POSITION and ORIENTATION inPDMS.

User-defined variable types are explained in User-defined Object Types .

2.3 Members and AttributesAn object can contain one or more items of data referred to as its members or attributes .Each member has a name.

STRING , REAL and BOOLEAN variables just have a value - no members. ARRAY variables have numbered elements, not members.

2.4 User-defined Object TypesYou may find that the object types supplied with PML 2 are enough.

However, you can define new object types if you need to. In any case, the following examplemay help you understand objects, their members and how they are used.

The following commands define an object type FACTORY with two REAL members and aSTRING member:

define object FACTORY

member .Name is STRING

member .Workers is REAL

member .Output is REAL

endobjectHere is another example where the object type FACTORY is itself used for one of the datamembers of another object type:

define object PRODUCT

member .Code is STRING

member .Total is REAL

member .Site is FACTORY

endobject

BOOLEAN This is used for the result of logical expressions and holdsthe value TRUE or FALSE

Note: These are no t the same as the STRING values TRUE and FALSE .

ARRAY This holds many values of any type and is described inChapter 6.

Object Description


23/252


12.02:3

It is a good idea to use upper case for object-type names, and mixed upper and lower casefor variable names, the objects themselves. For example, a type might be WORKERS , anda variable name might be NumberOfWorkers.

2.4.1 Storing Object Type DefinitionsObject type definitions should normally be stored in a file with a lowercase name matchingthe name of the object type and a . pml obj suffix in a directory specified in the PMLLIBsearch-path , which can include the current directory. PML will load a definitionautomatically when it is needed.

2.5 Creating Variables (Objects)Note: There is no limit to the number of objects you can create of each type.

2.5.1 Local and Global Variable Names

PML variables are of two kinds: global and local .

Global variables last for a whole session (or until you delete them). A local variable can beused only from within one PML Function or macro.

These two kinds of variable are distinguished by their names. Names beginning ! ! areglobal ; names beginning ! are local :

!SurfaceArea

!!Area

PML Variable names may be any combination of letters and digits, starting with a letter, upto a maximum of 16 characters (plus the ! ! or ! ). Names are allowed to contain a dot (.)but this is now strongly discouraged as a dot has a special meaning in PML2 as a separator between an object and its methods (see Using the Methods of an Object ), and between thecomponents of form and gadget names.

Rather than using a dot as part of a name we recommend that you use a mixture of upper and lower case to make variable names more meaningful, for example:

!!StartInUpperCase

2.5.2 Notes on Naming Conventions

Use a naming convention to avoid 'polluting thenamespace

of global variables. All globalnames beginning with the letters CD are reserved for AVEVA system use.

Note that the most recent AVEVA Ap pl icati onware ( Ap pWare ) does not use a prefix. Whencreating new PML Macros you are responsible for avoiding name-clashes, for example, byusing your own prefix.

Here are some guidelines on naming variables: Use each variable for one purpose only and give it a meaningful name. Limit your use of global variables. Where possible use PML Functions rather than macros (macros are described in

Macros ) so as to make use of function return values and output arguments to returnresults.


24/252

12.02:4


Remember that within the methods of PML Objects and Forms you generally need onlylocal variables. Any values which are to be exported should be made available asmembers or as method values or returned arguments.

Only use PML Functions (necessarily global) for tasks which are genuinely globallyaccessible, i.e. independent of a specific object or form, or which need to be shared byseveral objects or forms.

Current Global Variables

2.5.3 Creating a Variable with a Built-in TypeYou can create variables of any of the built-in types ( REAL , STRING , BOOLEAN or

ARRAY ), as in the following example, which creates a REAL variable and sets it value to99:

!MyNumber = 99

Because the variable is set to a real, PML knows that its type is real. Similarly, you cancreate a STRING variable and set it like this:

!MyString = Hello World

The PML Variable !MyString and the constant Hello World are both objects of typeSTRING . A STRING is a very simple object and the only data it contains is its text value. Inthis simple expression we are creating a new object, a variable of STRING type, by makinga copy of the original object, the STRING constant Hel l o Wor l d .

Other examples:


Area Based ADP !!ABA Add-in application

Administration !!ADM Plus !!CDA

Application Switching !!APP

Batch Handling !!BAT

CADCentre !!CADC

Draft !!CDR

Draft Icon Location !!CD2D Icon pathnames

Defaults !!DFLTS

General !!CDC Plus !!CDD, E, F, G, H, I, L, M, N, P, S, U, V, W

Specialised !!CE Plus !!ERROR, !!FMSYS

Various Others

!!Answer = 42 $* creates !!Answer as a GLOBAL REAL variable

\!Name = 'Fred' $* creates !Name as a LOCAL STRING variable

!Grid = TRUE $* creates !Grid as a LOCAL BOOLEAN variable


25/252


12.02:5

A variable may also be given a type without giving it an initial value, in which case it willhave the value UNSET:

!!Answer = REAL()

!Name = STRING()

!Grid = BOOLEAN()

!Lengths = ARRAY()

For more about unset variables, see UNSET Values and UNDEFINED Variables .

2.5.4 Creating Other Types of VariableYou create variables of types that are system-defined or user-defined, using the OBJECTkeyword. For example, to create a variable of type FACTORY :

!NewPlant = object FACTORY()

2.5.5 Using the Member Values of an ObjectThe way to set individual members of an object is to use the dot notation as follows:

!NewPlant = object FACTORY()

!NewPlant.Name = ProcessA

!NewPlant.Workers = 451

!NewPlant.Output = 2001

The dot notation is used in a similar way to access the value of a member of an object:

!People = !NewPlant.Workers

sets the variable !People to 451.

2.6 PML Funct ions and MethodsFunctions and Methods may optionally have arguments that can be used to return values.

Arguments have a data type which is specified in the function or method definition and theyare checked when the Function or Method is called. An argument may be one of the built-intypes REAL, STRING or BOOLEAN ; an ARRAY ; a built-in object or a user-defined

object or specified as ANY.Functions and methods can optionally return values as their results. Functions that do notreturn values are known as PML Procedures (see PML Procedures ).

Here is a definition of a PML Function that has two REAL arguments. It also has a REALreturn value, as shown by the final i s REAL :

define function !!Area( !Length is REAL, !Width is REAL )is REAL

Inside a function, the arguments are referenced just as if they were local PML Variables.The RETURN keyword is used to specify the variable that stores the return value:


26/252

12.02:6


define function !!Area( !Length is REAL, !Width is REAL )is REAL

!Area = !Length * !Widthreturn !Area

endfunction

When a PML Function is called, all the PML Variables passed as arguments must alreadyexist.

In addition, arguments used for input must have a value, which could be a constant, whenthe function is called:

define function !!LengthOfName(!Name is STRING) is REAL

!TidyName = !Name.trim()

return !TidyName.Length()

endfunction

The function is called to set the value of a variable !Length as follows:

!Length = !!LengthOfName( ' FRED ')

Here ' FRED ' is a string constant passed as an argument. We could rewrite this functionso that it returns its results by changing its arguments. The output argument, !Length , willbe set to the value required when the function is called:

define function !!LengthAndTrim(!Name is STRING, !Lengthis REAL)

!Name = !Name.Trim()!Length = !Name.Length()

endfunction

Arguments used for output must exist prior to the call and one that is also used as an inputargument must also have a value:

!Name = ' FRED '

!Length = REAL()

The function is called to set the value of a variable !Length as follows:

!!LengthAndTrim(' FRED ', !Length)

When an argument value is changed within a PML Function its value outside the function isalso changed.

The following call is incorrect, as the function cannot modify a constant:

A PML Function returning a value may be used wherever an expression or PML Variablecan be used, for example, this call to the ! Ar ea function defined above:

!PartLength = 7

!PartWidth = 6

!!LengthAndTrim(' FRED ' ,4 ) $* WRONG


27/252


12.02:7

!SurfaceArea = !!Area(!PartLength, !PartWidth)

Note: You cannot switch to a different PDMS module if a PML Function is running. Use

EXIT to exit from the function if it has failed to complete.

2.6.1 Storing and Loading PML Functions

When a PML Function is called it is loaded automatically from its source file in a directorylocated via the environment variable PMLLI B. The name of the external file must belowercase and must have the . pml f nc suffix. The source of a PML Function invoked as! !AREA or !!Area or ! !a rea all correspond to the file named ar ea. pml f nc .

Note: The ! ! signifies that the function is user-defined and that it is global - but ! ! does notform part of the external filename. All user-defined functions are global and only onemay be defined per file.

Note: The def i ne f uncti on must be the first line in the file and that its name and the filename must correspond.

2.6.2 PML Procedures

A PML Procedure is a PML Function that does not return a result.

A function is defined as a procedure by omitting the data type at the end of the def i nef unct i on statement:

define function !!Area( !Length is REAL, !Width is REAL,

!Result is REAL)

!Result = !Length * !Width

endfunction

Here we are using an output argument, !Result , to return the result rather than using afunction re turn value.

The arguments to the !!Area procedure can be set as follows, and then the procedureinvoked with the cal l command.

!SurfaceArea = REAL()

!Partlength = 7

!PartWidth = 6call !!Area(!PartLength, !PartWidth, !SurfaceArea)

There will be an error if you attempt to assign the result of a PML Procedure because thereis no return value to assign. So, for example you can say:

call !!Area(!PartLength, !PartWidth, !SurfaceArea)

!Answer = !SurfaceArea

But you cannot say:

!Answer = !!Area(!PartLength, !PartWidth,

!SurfaceArea)

$* WRONG


28/252

12.02:8


The ( ) parentheses after the name of a procedure or function must always be present even for procedures that do not need arguments:

define function !!Initialise()

!TotalWeight = 0

!!MaxWeight = 0

endfunction

call !!Initialise()

Although the cal l keyword is strictly speaking optional, its use is recommended withprocedures.

Note: As well as procedures, you can invoke a PML Function that has a return value usingcall , in which case the function result value is discarded.

2.7 Arguments of type ANYYou may specify ANY as the type of an argument (and even as the type of the functionreturn value).

Note: The use of ANY should be the exception rather than the rule as it switches off argument type checking - an important feature of PML Functions to help ensurecorrect functioning of your PML.

In the case an argument of type ANY, a value of any type may be passed as the argument tothe function:

define function !!Print(!Argument is ANY)$P $!Argument

endfunction

Where an argument of type ANY is used, you may need to find out its actual type before youcan do anything with it. The Obj ect Type( ) method can be used for this purpose:

define function !!AnyType(!Argument is ANY)

Type = !Argument.pmlobjectType()

if ( !Type EQ 'STRING' ) then

- - do something with a STRINGelseif ( !Type EQ 'REAL' ) then

- - do something with a REAL

elseif ( !Type EQ 'DBREF' ) then

- - do something with a DB Reference

else

- - do something with all other types or give an error

endif

endfunction


29/252


12.02:9

2.8 Using the Methods of an ObjectNote: A method is a function that is specific to an object.

The Software Customisation Reference Manual contains a table of the object types suppliedas part of PML 2. For each object type, there is a list of the associated methods andmembers.

For each object type, the table shows:

2.8.1 ExampleThis section explains how to use methods, using a STRING variable as an example.Although the STRING is a simple object type, it has a large number of methods which canbe called.

For example, if you are interested in the length of the string value, look under the list in theSoftware Customisation Reference Manual for STRING objects, and you will find a methodnamed Lengt h .

Name The name of the method or member. For example, a REALobject has a method named Cosi ne .

If there are any arguments, they are indicated in the

brackets () after the name.For example, the REAL object has a method namedBETWEEN which takes two REAL arguments.

Result or Type For members, we use the heading Type; for methods, weuse the heading Result.

The type of the member or the result describes what kind of object we are expecting to see as a member or result of themethod.

For example, the result of the method Cosine is a REALvalue.

Some methods do not return a value: these are shown asNO RESULT .

Status This column is used to give other information about themethod or member.

For methods, this column tells you whether the methodmodifies the state of the object.

For members, this column tells you whether the member isMutable (by the user) or Read Only .

Note that for the system-defined PDMS object types,members correspond to PDMS attributes

Purpose This column tells you what the member or method does.


30/252

12.02:10


This method returns a REAL value (the number of characters in the string), but has noeffect on the variable itself.

You can extract the number of characters in the string and store it in a new variable ,!Nchars , by calling the method as follows:

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 toenclose the arguments of the method, but they must be present even if there are noarguments.

2.9 Methods on User-Defined Object TypesWhen you define a new object type, you can also define methods which can be used tohandle all objects created with the new type. PML Method definitions are stored in the samefile as the object definition, after the endobj ect command.

Here is an example of an object which defines three methods to illustrate the main ideas.Note that within a method, !This represents the object which invoked the method and! Thi s. Answer is the way to refer to member An swer of this object.

These methods might be used in the following way:

!Marvin = object LIFE()

-- The method .Life() was called automatically

!Number = !Marvin.Answer()

!Nchars = !MyString.length() $* A method call

The Code What it Does

define object LIFE member .Answer is REALendobject

Defines the object, with a singlemember, An swer .

define method .Life()!This.Answer = 42

endmethod

Defines a method with no argumentsbut the same name as the type of theobject is called the defaultconstructor method. If the defaultconstructor method is present, PMLwill call it automatically to initialise theobject whenever an object of that typeis created.

define method .Answer() IS REAL

return !This.Answerendmethod define method .Answer( !Value IsREAL)

!This.Answer = !Valueendmethod

A method may return a result in just

the same way as a PML Functionusing the re turn command. Set amember of the object using!This.membername .


31/252


12.02:11

-- !Number is set to the value 42

!Marvin.Answer(40)

!Number = !Marvin.Answer()-- !Number now has the value 40

Warning: When you create a new object type, or change an existing definition, youmust load the definition by giving the command:

pml r el oad obj ect _name_

2.9.1 Method Over loadingTwo or more methods on an object may share the same name providing they have differentarguments. This is called method overloading . PML will invoke the method with thearguments which match the method call. It is common practice:

To use a method with the same name as a member and one argument of the sametype to set the members value. For example:

!Marvin.Answer(65)

To use a method of the same name as a member returning a value of the same typebut with no arguments to get the members value. For example:

!Number = !Marvin.Answer()

2.9.2 Constructor Methods with ArgumentsWhen an object is created, it is possible to supply arguments that are passed by PML to a

constructor method with matching arguments instead of the default constructor method:!Marvin = object LIFE(40)

This would invoke a method:

define method .Life(!Value IS REAL)

2.9.3 Overloading with ANYAs with PML Functions, the type of a method argument may be specified as ANY. If methodoverloading is being used, PML will invoke the method with a matching set of explicitly-typed arguments in preference to calling a method with arguments of type ANY, irrespectiveof the order the methods appeared in the object definition file:

define method .SetValue( !Argument Is ANY)define method .SetValue( !Argument Is REAL)

Then:

!SomeObject.SetValue(100)

will invoke the method with the REAL argument, but

!SomeObject.SetValue(Priceless )

will invoke the method with the ANY argument.


32/252

12.02:12


2.9.4 Invoking a Method from Another MethodWithin a method ! Thi s. Met hodname( ) refers to another method on the same object. So

our secondLIFE

constructor method, the one with an argument, could be defined as:define method .Life(!Value IS REAL)

!This.Answer(!Value)

endmethod

2.9.5 Developing a PML Object with Methods

Whenever you add a new method to an object, you need to tell PML to re-read the objectdefinition, by giving the command:

pml reload object life

It is not necessary to use this command if you are simply editing an existing method(although you will have to use it if you edit a form definition file , and change the defaultconstructor method, described in Form Definition File .)

2.10 Unset Variable RepresentationsEach new data type supports a St r i ng( ) method that returns a string representing thevalue of the variable. For example:

UNSET variables of all built-in data types have an unset representation:

Other variable types are system-defined variables. Most of these have adopted the unsetstring Unset . For example:

!X = 2.5 $* defines a variable X of type REAL with 2.5 as itsnumeric value

!S = !X.String() $* will be a variable of type STRING, with thevalue 2.5

!X = REAL()!

S = !X.String()

$* yields the string (the empty string)

!X = BOOLEAN()

!S = !X.String()

$* yields the string (the empty string)

!X = STRING()!S = !X.String()

$* yields the string Unset

!X = ARRAY()

!S = !X.String()

$* yields the string ARRAY

!X = DIRECTION()

!S = !X.String()

$* yields the string Unset


33/252


12.02:13

User-defined data types can also provide a St r i ng( ) method. These also support anUNSET representation, and usually adopt the UNSET representation Unset.

2.11 UNSET Values and UNDEFINED VariablesAll data types can have the value UNSET which indicates that a variable does not have avalue. A variable created without giving it an initial value in fact has the value UNSET:

!X = REAL()

Variables with an UNSET value can be passed around and assigned, but use of an UNSETvalue where a valid item of data is required will always result in a PML error.

The presence of an UNSET value may be tested either with functions or methods:

An UNDEFINED variable is one that does not exist. The existence of a variable may betested with these functions:

if ( Undefined(!!Y) ) then . . .

if ( Defined(!!Y) ) then

There is no equivalent method call. If the variable does not exist, attempting to call a methodwould result in an error.

2.12 Deleting PML VariablesA variable that exists can be explicitly made UNDEFINED with the Del et e( ) method:

!!Y.Delete()

Warning : You must not attempt to delete members of objects or forms.

2.13 Forms as Global Variables

In PML 2, forms are a type of global variable. This means that a form cannot have the samename as any other global variable or any other form.

Note that a form definition is also the definition of an object, so a form cannot have the samename as any other object type.

Functions Methodsif ( Unset(!X) ) then if ( !X.Unset() ) then

i f ( Set (!X) ) then if ( !X.Set() ) then


34/252

12.02:14



35/252

Software Customisation GuideGeneral Features of PML

12.03:1

3 General Features of PML

3.1 Functions, Macros and Object DefinitionsFunctions and Macros are PML Files that contain stored sequences of commands. ThePML File is invoked whenever this sequence of commands is required.

The PML File may also include control logic which alters the order in which the commandsare carried out and special commands for handling errors.

PML Files are normally created using a text editor.

PML Functions and methods on objects (including forms) are the recommended way of storing command sequences because:

There is a check that they have been called with the right type of arguments. Arguments can return values. A PML Function or method can return a result of any type.

Most new AppWare code is written as methods on objects. PML Macro s are explained

in Macros as they are the basis of the older AppWare code.PML Macros are normally stored in a directory under the PDMSUI search-path.

PML Functions are automatically loaded from a directory under the PMLLI B search-path.

3.1.1 Comments in PML Fi les

Comments are additional text included in a PML File for the benefit of someone reading thePML code.

The PML processor ignores comments and so they do not affect the way the code executes.

For a simple one line comment, begin the line with - - (two dashes) or $* (dollar andasterisk).

- - This is a new-style PML comment

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

$* The following lines calculate the new angle

You can also use $* to add an inline comment to any line of PML:

A comment may extend over several lines provided it is enclosed in the escape sequences$( and $) .

$( A comment containing

!Z = !X + !Y $* We are assuming both !X and !Y are REAL


36/252

12.03:2


more than one line $)

A comment of this kind can be used temporarily to comment-out lines of PML to preventthem from being executed, but without deleting them from the file:

$(

skip if (!X EQ !Y)

$)

3.1.2 Leaving a PML File with the RETURN CommandAt any point within a PML File a re turn command will stop further execution of the file andreturn to the calling PML File, if there is one:

if ( count EQ 0 ) then

returnendif

For clarity, re turn can be used as the final line of a PML Macro. However, the use of thiscommand is not essential and there will be no error if it is not used.

Note: This is a different use of re turn from the command used to set return values of variables.

3.2 Case IndependenceEverything written in PML, including keywords such as i f , do and el s e means the samething in upper or lower case.

The exception is text enclosed between quotes or vertical bars, which is used exactly as it istyped. Throughout this document you will see examples of PML code using a mixture of upper and lower case for readability.

3.3 AbbreviationsMany commands have a minimum abbreviation which can be used in place of the fullcommand.

For readability it is recommended that you use the full form of the command note that it is

no t less efficient than using the abbreviation.PML keywords such as i f , el se and do have no abbreviations.

3.4 Special Character $The $ character has a special meaning in PML. It is an escape character , which meansthat together with the character which follows it are treated as a special instruction to PML.

The pair of characters beginning with $ is known as an escape sequence . $P is acommonly encountered example, which is used to output a message to the screen:

$P This text will be output to the screen


37/252


12.03:3

A number of other escape sequences will be described later in this manual. The importantpoint to note here that if you need the dollar character itself as part of a command, you willneed to double it:

$$

As the last character on a line, $ means that the next line is a continuation line.

For example:

$P This is an example of a much longer message that will be $

output to the screen

3.5 Text DelimitersText strings must be enclosed in either single quotes, or apostrophes, or vertical bars:

'apostrophes' or vertical bars .

The apostrophes and vertical bars are known as delimiters . Take great care to avoid un-matched delimiters as this can lead to many lines of PML code being included as part of thetext string, and so lost.

3.6 Filename ExtensionsThe naming conventions are as follows:

Note: All filename extensions must be entered in lower case.

3.7 Storing and Loading PML Files

PML Files must be stored in directories pointed to by the PMLLI B environment variable.When an AVEVA product is started up, PML scans each directory in the PMLLI B searchpath and creates a file named pml . i ndex in each directory.

This index file contains a list of all the PML Files in all the directories under the directorygiven in the PMLLI B search path. All the PML Files listed in the pml . i ndex files are loadedautomatically when the product is started up.

When you are working on PML Files, you should store them in your own PML workingdirectory, and add the path of your PML working directory as the first entry in your PMLLI Bsearch path. Then, when you add a new PML File (after you have started up an AVEVAproduct), you will need to tell PML to rebuild its file index by giving the command:

pml rehash

Extension Use for

.pmlfnc PML Function definition files

.pmlobj PML object type definition files

.pmlfrm PML Form definition files


38/252

12.03:4


This command scans all the files under the first directory in your PMLLI B path, and updatesthe pml . i ndex file.

If other users have added PML Files and updated the appropriate pml . i ndex files, you canaccess the new files by giving the command:

pml index

This command re-reads all the pml . i ndex files in your search path without rebuildingthem.

When you are not running an AVEVA product, you can update the pml . i ndex file in a givendirectory by giving the command:

pmlscan directory_name

This command runs a utility supplied with AVEVA products.

Note: The commands pml r ehash and pml i ndex are a type of

Software Customisation Guide

Documents

Transcript of Software Customisation Guide