Software Customisation Reference Manual

AVEVA Solutions Ltd

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.

Copyright
Copyright and all other intellectual property rights in this manual and the associated software, and every part 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 in this document is commercially sensitive, and shall not be copied, reproduced, stored in a retrieval system, or transmitted without the prior written permission of AVEVA Solutions Ltd Where such permission is granted, it expressly requires that this Disclaimer and Copyright notice is prominently displayed at the beginning of every copy that is made. The manual and associated documentation may not be adapted, reproduced, or copied, in any material or electronic form, without the prior written permission of AVEVA Solutions Ltd. The user may also not reverse engineer, decompile, copy, or adapt the associated software. Neither the whole, nor part of the product 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 by law. Any such unauthorised action is strictly prohibited, and may give rise to civil liabilities and criminal prosecution. The AVEVA products described in this guide are to be installed and operated strictly in accordance with the terms and conditions of the respective licence agreements, and in accordance with the relevant User Documentation. Unauthorised or unlicensed use of the product is strictly prohibited. First published September 2007 AVEVA Solutions Ltd, and its subsidiaries 2007 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 its subsidiaries, 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.

Software Customisation Reference Manual

Software Customisation Reference Manual

Contents

Page

Software Customisation
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1 Summary of Objects, Members and Methods . . . . . . . . . . . . . . . . . 2:1
Object Classification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1 Methods Available to All Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3 Forms and Menus Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:4
Members Contained by All Gadgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:4 Summary of Gadget-Specific Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:5

Gadget Syntax Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:6

Rules for Presenting and Using Syntax graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:6 Setting Up Gadget Anchoring: <fganch> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:7 Setting Up Gadget Docking: <fgdock> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:7 Setting-Up the Gadgets Position: <fgpos> and <fgprl> . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:8 Setting Up the Gadgets Width and Height: <vshap>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:9 Setting Up the Gadgets Tagwidth (TEXT, TOGGLE and OPTION): <fgtagw> . . . . . . . . . 2:10 Setting Up the Gadgets 2D Screen Position: <xypos> . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:10

Object Type Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:11

ALERT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ARC Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ARRAY Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BANNER Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BAR Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BLOCK Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BOOLEAN Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:11 2:12 2:20 2:24 2:25 2:27 2:27

2007 AVEVA Solutions Ltd

12.0

Software Customisation Reference Manual

BORE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:28 BUTTON Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:29 COLLECTION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:33 COLUMN Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:34 COLUMNFORMAT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:35 COMBOBOX Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:37 CONTAINER Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:40 DATEFORMAT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:41 DATETIME Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:42 DB Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:44 DBREF Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:46 DBSESS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:47 DIRECTION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:47 EXPRESSION Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:49 FILE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:50 FMSYS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:52 FORM Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:54 FORMAT Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:62 FRAME Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:64 LINE Gadget. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:68 LINE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:69 LINEARGRID Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:79 LIST Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:80 LOCATION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:85 MACRO Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:87 MDB Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:87 MENU Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:89 NUMERICINPUT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:96 Multi Discipline Route Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:98 OBJECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:103 OPTION Gadget. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:104 ORIENTATION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:108 PARAGRAPH Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:109 PLANE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:111 PLANTGRID Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:115 PLATFORMGRID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:116 POINTVECTOR Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:119 POSITION Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:121 POSTEVENTS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:126 PROJECT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:127

2007 AVEVA Solutions Ltd

ii

12.0

Software Customisation Reference Manual

PROFILE Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RADIALGRID Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REAL Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REPORT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RTOGGLE Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECTOR Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SESSION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SLIDER Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STRING Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TABLE Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEAM Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXTPANE Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOGGLE Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UNDOABLE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . USER Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VIEW Gadget: ALPHA Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VIEW Gadget: AREA View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VIEW Gadget: PLOT View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VIEW Gadget: VOLUME Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XYPosition Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2:129 2:138 2:140 2:142 2:145 2:147 2:151 2:153 2:155 2:160 2:161 2:163 2:165 2:167 2:170 2:171 2:172 2:173 2:175 2:177 2:180

Communicating with Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1

Invoking the Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1 Directing Commands to Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1 Sending Commands to Review. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1 Errors from the Application-to-Review Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2 Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:3 Progress Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:3
Engineering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:4

Using the Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5

Progress Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5 Engineering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:6 Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:7

Summary of the Application Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:11

Progress Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:11 Engineering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:12 Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:12

2007 AVEVA Solutions Ltd

iii

12.0

Software Customisation Reference Manual

Application Files Supplied . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14

ADMIN Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ENGDATA Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PROGRESS Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MAINTAIN Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DATA Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:15 A:15 A:16 A:16 A:17

PML 1 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B:1

Format of Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:1
Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:2 Nesting Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:2

Logical Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:2

Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:3 Logical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:6 Logical Array Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:11

Numeric (Real) Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:12

Numeric (Real) Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADD and SUBTRACT (+ and -)" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MULTIPLY and DIVIDE (* and /) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Numeric (Real) Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Real Arrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:12 B:12 B:13 B:13 B:22

Using IDs in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:22 Positions, Directions and Orientations in Expressions (PDMS only) . . . . . . . B:23
Using Positions in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WRT (PDMS Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FROM ............................................................. Comparing Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . POLAR ............................................................. Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Orientations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:23 B:23 B:25 B:27 B:28 B:28 B:29

Text Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:30

Text Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:30 Text Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:31

Late Evaluation of Variables in expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . B:40 PDMS Attributes in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:40 Querying Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:40 Units in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:40 Precision of Comparisons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:41

2007 AVEVA Solutions Ltd

iv

12.0

Software Customisation Reference Manual

Undefined Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:42 Unset Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:42

2007 AVEVA Solutions Ltd

12.0

Software Customisation Reference Manual

2007 AVEVA Solutions Ltd

vi

12.0

Software Customisation Reference Manual

Introduction

Introduction
This manual is the Reference Manual for the AVEVA Programming Language, PML. It is intended for users who are already familiar with PML. Users who are starting to use PML should refer to the PDMS Software Customisation Guide, which should be used together with this manual. There are two versions of PML, the older one, known as PML 1, and the newer one, known as PML 2. PML 2 has been written specifically for creating and customising the AVEVA GUI, and this manual is mainly concerned with PML 2. However, PML 2 has not completely replaced PML 1, and there are some tasks which are carried out more efficiently using PML 1 facilities. In particular, this manual describes the PML 1 expressions package, which is used within PDMS; for example, for writing rules and defining report templates. You should also refer to the Database Management Reference Manual. This manual contains: A list of PML 2 Objects, Members and Methods. For the Forms and Menus objects, the command syntax relating to the objects is included.

Note: Many properties of Forms and Gadgets that were previously set using commands should now be set using the Form or Gadget methods. In general, the only commands described are those which have not been replaced by methods. If you are maintaining old code, you may need to refer to the edition of the AVEVA Software Customisation Guide dated October 1995, which describes the old syntax in detail. Information about using PML in Review. A description of the PML 1 expressions package.

2007 AVEVA Solutions Ltd

1:1

12.0

Software Customisation Reference Manual

Introduction

2007 AVEVA Solutions Ltd

1:2

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2
2.1

Summary of Objects, Members and Methods

Object Classification
The table below lists the object types and shows which classifications they belong to. Classification PML Built-in Objects Object Type ARRAY BLOCK BOOLEAN FILE OBJECT REAL STRING DATETIME 3D Geometry Objects ARC LINE LINEARGRID LOCATION PLANE PLANTGRID POINTVECTOR POSTEVENTS POSTUNDO PROFILE RADIAL GRID XYPOSITION

2007 AVEVA Solutions Ltd

2:1

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Classification

Object Type BANNER BORE DB DBREF DBSESS DIRECTION MACRO MDB ORIENTATION POSITION POSTUNDO PROJECT SESSION TEAM UNDOABLE USER

PDMS Objects

Forms and Menu Objects & Gadgets

ALERT BAR BUTTON COMBOBOX CONTAINER FMSYS FORM FRAME LINE LIST MENU NUMERIC OPTION PARAGRAPH RTOGGLE SELECTOR

2007 AVEVA Solutions Ltd

2:2

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Classification

Object Type SLIDER TEXT TEXTPANE TOGGLE VIEW ALPHA AREA PLOT VOLUME

Collection and Report Objects

COLLECTION COLUMN COLUMN-FORMAT DATE-FORMAT EXPRESSION REPORT TABLE

Formatting Text
Table 2: 1. Object Types and Classification

FORMAT

2.2

Methods Available to All Objects

The table following lists the methods available to all objects. The table gives the name of each method and the type of result you get back from it. The third column of the table describes what the method does. Name Attribute( 'Name') Result ANY Purpose To set or get a member of an object, providing the member name as a STRING.

Attributes()

ARRAY OF To get a list of the names of STRINGS the members of an object as an array of STRING. NO RESULT Destroy the object - make it undefined BOOLEAN BOOLEAN Type-dependent comparison Type-dependent comparison (converting first to STRING if all else fails)

Delete() EQ(any) LT(any)

2007 AVEVA Solutions Ltd

2:3

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Max(any) Min(any) NEQ(any) ObjectType() Set() String() Unset()

Result ANY ANY BOOLEAN STRING BOOLEAN STRING BOOLEAN

Methods Available to All Objects

Purpose Return maximum of object and second object Return minimum of object and second object TRUE if objects do not have the same value(s) Return the type of the object as a string TRUE if the object has been given a value(s) Convert the STRING object to a

TRUE if the object does not have a value

Table 2: 2.

2.3
2.3.1

Forms and Menus Objects

Members Contained by All Gadgets
All gadgets contain the following members. Name visible Type BOOLEAN Get/Set Purpose You query this member to determine if a gadget is visible or invisible. To make a gadget visible, set it to TRUE; to make the gadget invisible, set it to FALSE. active BOOLEAN Get/Set You query this member to determine if a gadget is active or inactive (greyedout). To make a gadget active, set it to TRUE; to make the gadget inactive, set it to FALSE.

2007 AVEVA Solutions Ltd

2:4

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name callback

Type STRING Get/Set

Purpose Query or assign the gadgets callback string Query or assign a gadgets tag text. This is not displayed for all gadgets.

tag

STRING Get/Set

Table 2: 3.

Members Contained by All Gadgets

2.3.2

Summary of Gadget-Specific Methods

The table below summarises the methods that different gadgets support.
Bar X X X X X X X X X Button List Option X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X Para Slider Text Text-pane Toggle /Rtoggle View Alpha View 2D View 3D Numeric Input Container Combobox X X X X X X X X Frame Line Selector View:Plot X X X

Add Background Clear ClearSelection Container CurPos DisplayText FieldProperty FullName Highlight InsertAfter InsertBefore GetPickedPopup Line Name Owner Refresh RemovePopup RestoreView RToggle SetEditable Select Selection SetActive SetCurPos SetColumns

2007 AVEVA Solutions Ltd

2:5

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Bar

Button

List

Option

Para

Slider

SetEditable SetFieldProperty SetFocus SetHeadings SetLine SetPopup SetRange SetRows SetSize SetTooltip SetValue ShowPopup Shown Subtype Type ValidateCall Table 2: 4. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

X X

X X X

X X X X

Summary of Gadget-Specific Methods

Text

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

Text-pane

Toggle /Rtoggle

View Alpha

View 2D

View 3D

Numeric Input

Container

Combobox

Frame

Line

Selector

View:Plot

2.4
2.4.1

Gadget Syntax Graphs

Rules for Presenting and Using Syntax graphs
The rules for syntax graphs are as follows: 1. Each graph represents a command (or part of a command) to PDMS to perform specified actions with specified data. The graph is entered at graph_name>-- or >-, and exited at -->. The allowed flow in a graph is top to bottom, and left to right, except where indicated otherwise by a * or < symbol. 2. Vertical lines with one or more + symbols represent a new state. These are always traversed downwards. There should be a + for each allowable entry point into a state. The + symbols can only be traversed from left to right. 3. Horizontals to the right of state lines, represent command words and data which are allowable in the state. They can only be traversed from left to right. 1. Words starting with capitals represent command words. The capitalized part represents the minimum syntax which is recognized. Lower case parts denote optional characters. The whole thing is actually case independent as far as the user is concerned. 2. Words enclosed in < > represent a call to the named graph. These should be lower case. Graph calls can be recursive. 3. Words in lower case only, represent notionally atomic data items, e.g. text, integer, val (numeric value). Sometimes they are in fact graph calls, e.g. fname and

2007 AVEVA Solutions Ltd

2:6

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

gname. Sometimes they are fictitious e.g. tagtext, but more helpful than just text and easier to understand than a reference to, say, <fgtag>. 4. Continuous vertical and horizontal lines without a + symbol represent flow lines of the graph. 1. The presence of a * symbol in a vertical line indicates that the allowed direction of traverse is upwards. 2. The presence of a < symbol on a horizontal indicates that the allowed direction of traverse is backwards. 3. The symbols ., /, are just cosmetic to help the graph to look better.

2.4.2

Setting Up Gadget Anchoring: <fganch>

The ANCHOR attribute allows you to control the position of an edge of the gadget relative to the corresponding edge of its container. For example ANCHOR RIGHT specifies that the right hand edge of the gadget will maintain a fixed distance from the right hand edge of its owning container.
.---<-------------. / | >-- <fganch> -----------+-- ANCHOR --+--+- Left ----. | | +- Right ---| | | +- Top -----| | | - Bottom --+---+---* | | +---- None ----| ---- All--------> Figure 2:1. Syntax Graph -: Gadget Anchoring

2.4.3

Setting Up Gadget Docking: <fgdock>

The DOCK attribute allows you to dock a gadget to the left, right, top, or bottom edge of its container, typically a form or a frame; or you can cause the gadget to dock to all edges, or to no edges.
>-- <fgdock> -----------+-- DOCK ----+-----Left ----. +---- Right ---| +---- Top -----| +---- Bottom --| +---- None ----| ---- Fill ------> Figure 2:2. Syntax Graph - Gadget Docking

Note: The DOCK and ANCHOR attributes are mutually exclusive. Setting the DOCK attribute resets the ANCHOR to the default; setting the ANCHOR attribute resets DOCK to none. You can set these attributes only when you define the gadget: you cannot change it after the exit from form setup. Thus you are not allowed to the resize behaviour at run-time.

2007 AVEVA Solutions Ltd

2:7

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.4.4

Setting-Up the Gadgets Position: <fgpos> and <fgprl>

You can use the AT syntax, shown below on the <fgpos> graph, to define the position of a gadgets origin within a form. You can specify the position absolutely (in form layout grid units) or relative to the extremities of existing gadgets, or relative to the size of the form and the gadget.
>-- <fgpos> -- AT --+- val val -------------------------------. +- X val ------------. | +- XMIN -. | | +- XCEN -| | | +- XMAX -+- <fgprl> -| | -------------------+- Y val ------------| +- YMIN -. | +- YCEN -| | +- YMAX -- <fgprl> -| ----------------------> Figure 2:3. Syntax Graph - Absolute Positioning

The subgraph <fgprl>, shown below, sets the gadget position relative to another gadget or the forms extent. For example, you can use it to position a gadget halfway across the width of a form.
>-- <fgprl> --+- <gname> -. +-- FORM ---| -----------+| ++| | | | ++-

* val -----. | + val --. | - val ----+- + val * SIZE ---. +- - val * SIZE ---| +- + SIZE ---------| +- - SIZE ---------| ------------------| + SIZE -----------------------| - SIZE -----------------------|

----------------------------------> Figure 2:4. Syntax Graph -: Relative Positioning

Examples of Using the AT Syntax

AT 5 7.5 AT X 5.5

Puts gadget origin at form grid coordinates (5, 7.5). Puts gadget origin at form grid coordinates (5.5, y) where y is calculated automatically from the y extremity of the last placed gadget and the current VDISTANCE setting. Positions new gadget at (x, y) where x is calculated automatically from the x extremity of the last placed gadget and the current HDISTANCE setting. y is at YMAX+1 of the last gadget.

AT YMAX+1

2007 AVEVA Solutions Ltd

2:8

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

AT XMIN.GAD1-2 YMAX.GAD2+1

Positions new gadget with respect to two existing gadgets. Gadget is offset by 2 grid units to the left of GAD1(X=XMIN-2) and 1 unit below .GAD2 (Y=YMAX+1). XMAX FORM refers to the current right hand size of the form at its current stage of definition (not its final maximum extent). YMAX FORM refers to the forms current bottom extent. The -SIZE option subtracts the size of the gadget being positioned in the form. This example positions the gadget at the extreme right-hand bottom edge of the form.

AT XMAX FORM-SIZE YMAX FORM-SIZE

2.4.5

Setting Up the Gadgets Width and Height: <vshap>

This operation allows you to set a gadgets width and height.
>-- <vshap> --+- <vwid> --+- <vhei> --------. | +- ASPect (h/w) --| | -------------------> | - <vhei> --+- <vwid> --------. +- ASPect (h/w) --| -------------------> Figure 2:5. Syntax Graph -: Gadget Geometry <vshap>

h/w is the value of the Aspect Ratio (height/width). The units for <vshap> will have been preset to pixels or F&M grid units, appropriately. The default width and height for <vshap> will have been preset, so leaving the graph with only width or height set still realises both values. All values may be given as integer or reals.

Setting the Height: <vwid>

>-- <vwid> -- WIDth -+- val ------. +- <gname> --| -------------->

Setting the Width: <vhei>

>-- <vhei> -- HEIght -+- val ------. +- <gname> --| -------------->

2007 AVEVA Solutions Ltd

2:9

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.4.6

Setting Up the Gadgets Tagwidth (TEXT, TOGGLE and OPTION): <fgtagw>

The TAGWIDTH specifies the size of the gadgets tag field in grid width units including any padding space, regardless of the actual tag string. Tagwidth is not needed for gadgets with an explicit area specification (width and height, lines or length). FRAME, LIST, SELECTOR, TEXTPANE and PARAGRAPH can always force an explicit width. The syntax graph <fgtagw> defines the Tag specification
>-- <fgtagw> --+- TAGWIDth val -+-------------. ------------------ tagtext ----> Figure 2:6. Syntax Graph -: Gadget Tagwidth

The <fgtagw> graph supports both the simple tagtext setting and/or the specification of the maximum width of any tag. If the tag width is not explicitly given then it is assumed to be the number of characters in the tagtext string multiplied by the horizontal grid size (the notional character width for the font). You can specify the tag width without specifying any tagtext at definition time; this can be added at run time

2.4.7

Setting Up the Gadgets 2D Screen Position: <xypos>

This shows how to set up a gadgets 2D screen position in normalized co-ordinates.
<xypos>--+- XR val -+- YR val -. - YR val -+- XR val ---> Figure 2:7. Syntax Graph - Gadget's 2d Screen Position

Note: Normalized co-ordinates represent a proportion of the full screen size. 0.0 <= XR <= 1.0 and 0.0 <= YR <= 1.0.

2007 AVEVA Solutions Ltd

2:10

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5

Object Type Details

This section contains details of the object types listed in Table 2: 1.: Object Types and Classification.

2.5.1

ALERT Object
Methods

Name Confirm( Message is STRING, X is REAL, Y is REAL )

Result

Purpose

STRING Show a blocking CONFIRM YES OR ALERT and retrieve the NO response. X and Y are optional screen positions. STRING YES Show a blocking ERROR ALERT and retrieve the response. X and Y are optional screen positions. Show a blocking MESSAGE ALERT and retrieve the response and retrieve the response. X and Y are optional screen positions. Show a blocking QUESTION ALERT and retrieve the response. X and Y are optional screen positions. Show a blocking WARNING ALERT and retrieve the response and retrieve the response. X and Y are optional screen positions. Show a blocking INPUT ALERT. !prompt is the prompt displayed to the user, and !default is the default value in the text box. Show a blocking INPUT ALERT. !prompt is the prompt displayed to the user, and !default is the default value in the text box. xPos and yPos are the coordinates of the top lefthand corner of the alert box.

Error(Message is STRING, X is REAL, Y is REAL )

Message(Message is STRING, X is REAL, Y is REAL)

STRING YES

Question(Message is STRING, X is REAL, Y is REAL )

STRING YES, NO OR CANCEL STRING YES

Warning(Message is STRING, X is REAL, Y is REAL)

!!Alert.Input( ! prompt is STRING, !default is STRING) is STRING

STRING

!!Alert.Input( !prompt is STRING, !default is STRING, xPos is REAL, yPos is REAL) is STRING

STRING

Table 2: 5.

Alert Object Methods

2007 AVEVA Solutions Ltd

2:11

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.2

ARC Object
Basic ARC Definition: Members

Name Orientation

Type ORIENTATI ON Get/Set POSITION Get/Set REAL Get/Set REAL Get/Set REAL Get/Set BOOLEAN Get/Set

Purpose Orientation of the arc.

Position Radius StartAngle EndAngle Sense

Origin/Centre of the arc. Radius of the arc Angle from X axes to start of the arc. Angle from X axes to end of the arc. Arc sense: 0 for clockwise 1 for anti-clockwise

Table 2: 6.

Basic ARC Definition Members

Basic ARC Definition: Methods

These methods do not modify the original object. Name Arc( POSITION, ORIENTATION, REAL, REAL, REAL,BOOLEAN) Result ARC Purpose Creates an arc with the given Position, Orientation, Start Angle, End Angle, Radius. If the last argument is TRUE, the arc is clockwise. Returns the arc as a string

String()
Table 2: 7. Basic ARC Definition Methods

STRING

2007 AVEVA Solutions Ltd

2:12

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

ARC Methods that Return ARCs

None of these methods modifies the original object. Name StartPosition(POSITION) Result ARC Purpose Returns a new arc, based on the original, where the start angle, if defined as the angle from the centre of the arc through the passed position mapped onto the arc plane, forms the X axis. As StartPosition, but for the EndAngle. Returns a new arc, where the radius (of the full circle) passes through the passed position when mapped onto the arc plane. Returns a new arc, based on the original, where the EndAngle is in such a position to produce the passed chord height. Chord height > Radius or Chord height < 0 return unset objects. New arc should not produce subtended angle > 180. Chord(REAL) ARC Returns a new arc, maintaining the original StartAngle, so the EndAngle is at the specified distance from the Start Chord length > Radius * 2 or < 0 return an unset object. Circle() Circle(BOOLEAN) ARC ARC Returns a full circle definition of the arc. Returns a full circle definition of the arc. If True, the arc is anti-clock-wise Returns the complementary arc of the arc definition (the remainder of the circle)

EndPosition(POSITION) Through(POSITION)

ARC ARC

ChordHeight(REAL)

ARC

Complement()

ARC

Table 2: 8.

ARC Methods that Return ARCs

2007 AVEVA Solutions Ltd

2:13

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

EndPosition(POSITION) Through(POSITION)

Complement()

Cord(REAL) CordHeight(REAL) StartPosition(POSITION)

Figure 2:8.

ARCs Returned by ARC Methods

ARC Method that Returns POSITIONs

This method does not modify the original object. Name AnglePosition(REAL) Result Purpose

POSITION Returns the position at the specified angle on the arc.

Table 2: 9.

ARC Methods that Return POSITIONs

AnglePosition(REAL)

Figure 2:9.

POSITIONs Returned by ARC Methods

2007 AVEVA Solutions Ltd

2:14

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

ARC Methods that Return DIRECTIONs

None of these methods modifies the original object. Name AngleDirection(REAL) Result Purpose

DIRECTION Returns the direction from the centre of the arc through a point at the given angle from the X axis DIRECTION Returns the direction out of the arc, tangential to the start angle line. The sense of the arc is used. DIRECTION Returns the direction out of the arc, tangential to the end angle line. The sense of the arc is used. DIRECTION Returns tangential passed. the direction, to the angle

StartTangent()

EndTangent()

AngleTangent(REAL)

Table 2: 10.

ARC Methods that Return DIRECTIONs

EndTangent()

AngleDirection(REAL)

AngleTangent(REAL)

StartTangent()

Figure 2:10. DIRECTIONs Returned by ARC Methods

ARC Methods that Return XYOffsets

This method does not modify the original object. Name XYOffset(POSITION) Result XYPOSITI ON Purpose Returns the position, mapped onto the arc plane, in term of an XY offset from the arc plane origin

Figure 2:11.

ARC Methods that Return XYOffsets

2007 AVEVA Solutions Ltd

2:15

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

XYOffset(POSITION)
Figure 2:12. XYOffsets Returned from ARC Methods

ARC Methods that Return REALs

None of these methods modifies the original object. Name Proportion(REAL) Result REAL Purpose Returns the position, in terms of an angle from the X axis, at the proportion from the start angle of the arc: Angle = (EndAngle StartAngle) * <real> + StartAngle Returns the subtended angle of the arc Returns the position, in terms of an angle from the X axis, to the position on the arc plane of the passed position

Angle() Near(POSITION)

REAL REAL

Table 2: 11.

ARC Methods that Return REALs (a)

Near(POSITION) Proportion(REAL)

Figure 2:13. REALs Returned by ARC Methods (a)

2007 AVEVA Solutions Ltd

2:16

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Chord()

Result REAL

Purpose Returns the chord length between the start and end of the arc definition Returns the true length of the arc line Returns the chord height of the arc line

Length() ChordHeight()

REAL REAL

Table 2: 12.

ARC Methods that Return REALs (b)

Chord()

Length()

ChordHeight()
Figure 2:14. REALs Returned by ARC Methods (b)

ARC Intersection Methods that Return REAL ARRAYs

None of these methods modifies the original object. Name Intersections(LINE) Result REAL ARRAY Purpose Returns the intersection points, in terms of angles from the X axis, of the passed line (mapped onto arc plane) with the circle defined by the arc Returns the intersection points, in terms of angles from the X axis, of the passed plane with the circle defined by the arc

Intersections(PLANE)

REAL ARRAY

2007 AVEVA Solutions Ltd

2:17

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Intersections(ARC)

Result REAL ARRAY

Purpose Returns the intersection points, in terms of angles from the X axis, of the circle implied by the passed arc with the circle defined by the arc The Arcs must be in the same plane, i.e. the angle between Z components of the direction must be 0 or 180

Table 2: 13.

ARC Intersection Methods that Return REAL ARRAYs

Intersections(LINE)

Intersections(PLANE)

Intersections(ARC)
Figure 2:15. REAL ARRAYs Returned by ARC Intersection Methods

ARC Tangent Methods Returning Real Arrays

None of these methods modifies the original object. Name Tangents(POSITION) Result REAL ARRAY Purpose Returns the points of tangency on the arc circle from the passed position, in terms of angles from the X axis, Returns the points of tangency on the arc circle for the passed arc circle, in terms of angles from the X axis

Tangents(ARC)

REAL ARRAY

2007 AVEVA Solutions Ltd

2:18

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Split() Pole()

Result REAL ARRAY POSITION

ARC Tangent Methods that Return REAL ARRAYs

Purpose Splits the arc into a non-zero number of segments Returns the pole position of the arc

Table 2: 14.

Tangents(POSITION)

Tangents(ARC)
Figure 2:16. REAL ARRAYs Returned from ARC Tangent Methods

ARC Methods that Return BOOLEANs

None of these methods modify the original object. Name On(POSITION) OnProjected(POSITION) Result BOOLEAN BOOLEAN Purpose Returns true if the passed position lies on the arc line Returns true if the passed position, when projected onto the arc line, lies within it Returns true if the passed position, when mapped onto the arc line, lies outside it

OnExended(POSITION)

BOOLEAN

Table 2: 15.

ARC Methods that Return BOOLEANs

2007 AVEVA Solutions Ltd

2:19

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

On(POSITION) 8

On(POSITION) 9
Figure 2:17. ARRAY Object PML Built-in Type

2.5.3

ARRAY Object
Methods

Name Append(ANY value) AppendArray(ARRAY values) Clear() Compress()

Result

Purpose

NO RESULT Append value as a new element at the end of array. NO RESULT Append array values as new elements at the end of array. NO RESULT Remove all elements. NO RESULT Removed all undefined elements and re-index remaining elements. ARRAY Make undefined n elements starting at index. Remaining elements are not re-indexed Returns an array of the deleted elements (which need not be assigned if not wanted).

DeleteFrom( REAL index, REAL n)

DeleteFrom( REAL index)

ARRAY

Make undefined elements from index to end of array. Returns an array of the deleted elements. Remaining elements not reindexed.

2007 AVEVA Solutions Ltd

2:20

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name DeleteTo(REAL index, REAL n)

Result ARRAY

Purpose Make undefined n elements up to index Returns an array of the deleted elements Remaining elements not reindexed. Make undefined elements from start to index Returns an array of the deleted elements Remaining elements not re-indexed. Return an array of those elements in the original array not present in array two. Duplicates will appear only once TRUE if array is empty Evaluate code in command at each element. Search original array for value and return an array of index positions at which it was found. Return index of first occurrence of value. Returns UNSET if not found. Return value of first defined element Copy sub array of n elements starting at index. Copy sub array starting at index to end of array. Implements ARRAY[index] (this is an internal method). Returns an array containing the indices of the target array that have a value. a are new re-

DeleteTo(REAL index)

ARRAY

Difference(ARRAY two)

ARRAY

Empty() Evaluate(BLOCK command) Find(ANY value)

BOOLEAN NEW ARRAY NEW ARRAY

FindFirst(ANY value)

REAL

First() From(REAL index, REAL n) From(REAL index) GetIndexed(REAL index) Indices()

ANY ARRAY ARRAY ANY NEW ARRAY

Insert(REAL index, ANY value)

NO RESULT Insert value as element at index. Later elements indexed

2007 AVEVA Solutions Ltd

2:21

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name InsertArray(REAL index, ARRAY ANY values)

Result

Purpose

NO RESULT Insert values as new elements with the first at index. Later elements indexed are re-

Intersect(ARRAY two)

NEW ARRAY

Return array of elements present in both arrays. Duplicates will appear only once. Returns an inverted copy of the array. Return last element value. Subscript of last defined (non-empty) element. Subscript of first defined (non-empty) element. Replace array elements at index with elements from the array two. Returns an array of the elements which were overwritten (which need not be assigned if not required).

Invert() Last() MaxIndex() MinIndex() Overlay(REAL index, ARRAY two)

NEW ARRAY ANY REAL REAL NEW ARRAY

ReIndex(REAL ARRAY indices)

NO RESULT Apply result of SORTEDINDICES to reorder array elements into positions specified by indices. ANY Remove and Return nth element (which need not be assigned if not required). Remaining elements are reindexed.

Remove(REAL nth)

RemoveFirst()

ANY

Remove and Return first element (which need not be assigned if not required). Remaining elements are reindexed.

RemoveFrom(REAL index, REAL n)

NEW ARRAY

Remove and Return new array of n elements starting with index (which need not be assigned if not required). Remaining elements are reindexed.

2007 AVEVA Solutions Ltd

2:22

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name RemoveFrom(REAL index)

Result NEW ARRAY

Purpose Remove and Return new array of elements from index to end of array (which need not be assigned if not required). Remaining elements are reindexed.

RemoveLast()

ANY

Remove and Return last element (which need not be assigned if not required). Remaining elements are reindexed.

RemoveTo(REAL index, REAL n)

NEW ARRAY

Remove and Return n elements from start to index (which need not be assigned if not required). Remaining elements are reindexed.

RemoveTo(REAL index)

NEW ARRAY

Remove and return elements from start to index (which need not be assigned if not required). Remaining elements are reindexed.

Size() Sort() SortUnique()

REAL

Returns the number defined elements.

of

NO RESULT Sort array into ascending order. NEW ARRAY Returns a sorted copy of the array with duplicates removed.

SortedIndices()

NEW REAL Return new array of indices ARRAY representing the sorted order of elements in array. The array itself is not sorted.

To(REAL index, REAL n) To(REAL index) Union(ARRAY two)

ARRAY ARRAY NEW ARRAY

Copy sub array of n elements from start to index. Copy sub array from start of array to index. Return array of elements present in either array (duplicates will appear only once).

2007 AVEVA Solutions Ltd

2:23

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Unique() Width()

Result

Purpose

NO RESULT Discard duplicates and reindex remaining elements. REAL Return the maximum width of string elements (other element types are ignored).

Table 2: 16.

ARRAY Object Methods

2.5.4

BANNER Object
Members

Name Company Copyright Libraries Name Short Status

Table 2: 17. BANNER Object Members

Type STRING STRING

Purpose Company name, up to 120 characters. AVEVA copyright, up to 80 characters.

ARRAY OF Library names STRINGS STRING STRING STRING Title for main windows, up to 13 characters Short form of company name PDMS release status

Command

!BANNVAR = BANNER!

$ Returns a BANNER object

2007 AVEVA Solutions Ltd

2:24

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.5

BAR Gadget
Methods

Name Add(STRING dText, STRING enu)

Result

Purpose

NO RESULT Appends a barmenu field, which can show the specified menu as a pulldown menu. The name of the pulldown menu is given in menu; the DTEXT of the field is given by dText.

Clear()

NO RESULT Removes all barmenu fields. Using this method is deprecated. dText) NO RESULT Removes all barmenu fields after and including the one with DTEXT dText. Using this deprecated. method is

Clear(STRING

FieldProperty(STRING field, STRING property)

BOOLEAN

Get the value of the property named in property for the menu field named in field. The allowed values for the property are ACTIVE or VISIBLE.

FullName() InsertAfter(STRING field, STRING dText, STRING menu)

STRING

Get the full name of the gadget, e.g.'!!Form.bar'.

NO RESULT Inserts a new barmenu field immediately after the one identified by field. The name of the menu is given in menu; the DTEXT of the new field is given by dText.

InsertBefore(STRING field, STRING dText, STRING menu)

NO RESULT Inserts a new barmenu field immediately before the one identified by field. The name of the menu is given in menu; the DTEXT of the menu is given by dText.

Name()

STRING

Get the gadget's name, i.e. 'bar'

2007 AVEVA Solutions Ltd

2:25

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Owner() SetActive( STRING dText, BOOLEAN state)

Result FORM

Purpose Get the owning form.

NO RESULT Deactivate/Activate the menu field whose DTEXT is dText. Using this deprecated. method is

SetFieldProperty(STRING menu, STRING property, BOOLEAN state)

NO RESULT Set the value of the property named in property with the value of state, for the menu named in menu. The allowed values for the property are ACTIVE or VISIBLE.

Shown() Type()

BOOLEAN STRING
BAR Object Methods

Get shown status. Get the GADGET type as a STRING.

Table 2: 18.

Command
The BAR command creates a bar menu within a form definition. The recommended way to create menu fields on the bar is to use the bar's Add() method.

bar !this.bar.add ( 'Choose', 'Menu1') !this.bar.add ( ' window', 'Window' ) !this.bar.add ( 'help', 'Help' )
Note: The use of the two special menu names Help, which adds a system help menu that calls the online help; and Window, which adds a system Window menu that lists all the displayed windows.

2007 AVEVA Solutions Ltd

2:26

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.6

BLOCK Object
This object holds expressions that are evaluated later.

Methods

Name Block( STRING expression) Evaluate()

Result BLOCK ANY

Purpose Creates a block expression. Evaluate block expression on object: check result is of TYPE type. Evaluate the expression and return the result Evaluate expression and return an error if the result is not of TYPE type. Otherwise returns the result.

Evaluate() Evaluate(STRING type)

ANY ANY

Table 2: 19.

BLOCK Object Methods

2.5.7

BOOLEAN Object
Methods
None of these methods modifies the original object. Name BOOLEAN(REAL value) Result BOOLEAN Purpose Constructor that creates a boolean Object set to a nonzero value if boolean is TRUE; 0 if boolean is FALSE Constructor that creates a boolean Object set to: 'TRUE if boolean is T, TR, TRU, TRUE, Y, YE YES; FALSE if boolean is F, FA, FAL, FALS, FALSE, N, NO. BOOLEAN( STRING value, FORMAT format) BOOLEAN As above. FORMAT argument required for consistency by Forms and Menus. TRUE if both values are TRUE TRUE if FALSE; FALSE if TRUE

BOOLEAN(STRING value)

BOOLEAN

AND() NOT()

BOOLEAN BOOLEAN

2007 AVEVA Solutions Ltd

2:27

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name OR(BOOLEAN value) Real() String()

Result BOOLEAN REAL STRING

Purpose TRUE if either value is TRUE 1 if boolean is TRUE; 0 if boolean is FALSE TRUE if boolean is TRUE. FALSE if boolean is FALSE.

Table 2: 20.

BOOLEAN Object Methods

2.5.8

BORE Object
Member

Name Size

Type REAL Get/Set

Purpose The BORE size

Table 2: 21.

BORE Object Members

Methods
None of these methods modifies the original object. Name BORE(REAL value) Result BOOLEAN Purpose Constructor that creates a BORE object with the given value. Constructor that creates a BORE object with the given value. Constructor that creates a BORE object with the given value, and in the format specified by format. Comparison with the argument value dependent on current BORE units. TRUE if this object is greater than or equal to the argument bore. Comparison with the argument value dependent on current BORE units. TRUE if BORE greater than BORE

BORE(STRING value)

BOOLEAN

BORE(STRING value, FORMAT format)

BOOLEAN

EQ(REAL value)

BOOLEAN

GEQ(BORE bore)

BOOLEAN

GEQ(REAL value)

BOOLEAN

GT(BORE bore)

BOOLEAN

2007 AVEVA Solutions Ltd

2:28

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name GT(REAL value)

Result BOOLEAN

Purpose Comparison with the argument value dependent on current BORE units TRUE if this object is less than or equal to the argument bore. Comparison with the argument value dependent on current BORE units TRUE if this object is less than bore. Comparison with the argument value dependent on current BORE units Convert BORE to a REAL value Convert BORE to a STRING using the settings in the global format object.

LEQ(BORE bore)

BOOLEAN

LEQ(REAL value)

BOOLEAN

LT(BORE bore) LT(REAL value)

BOOLEAN BOOLEAN

Real() String(FORMAT format)

REAL STRING

Figure 2:18. BORE Object Methods

2.5.9

BUTTON Gadget
Members

Name Background Background Val

Type REAL Set/Get STRING Set Only BOOLEAN

Purpose Set or get Background Colour Number Set Background Name Colour

TRUE when the button is pressed FALSE when it is not

Table 2: 22.

BUTTON Object Members

2007 AVEVA Solutions Ltd

2:29

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name AddPixmap(STRING file1, STRING file2, STRING file3 ) AddPixmap(STRING file1, STRING file2) AddPixmap(STRING file ) FullName() Name() Owner() SetPopup(MENU menu) RemovePopup(MENU menu) GetPickedPopup() Shown() SetFocus() Refresh() Background()

Result

Purpose

NO RESULT Adds pixmaps to be used for the unselected, selected and inactive states. The last two are optional. STRING STRING FORM Get the full gadget name, e.g.'!!Form.gadget'. Get the gadget's name, e.g. 'gadget'. Get owning form.

NO RESULT Links the given menu with the gadget as a popup. NO RESULT Removes the given popup menu from the gadget. MENU BOOLEAN Returns the name of the menu picked from a popup. Get shown status.

NO RESULT Move keyboard focus to this gadget. NO RESULT Refresh display of gadget. STRING Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised.. SetToolTip(STRING) Type() NO RESULT Sets the text of the Tooltip. STRING Get the gadget-type as a STRING.

Table 2: 23.

BUTTON Object Methods

2007 AVEVA Solutions Ltd

2:30

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Command
The BUTTON command defines a button, and specifies its position, tag or pixmap, callback text and control attribute. You can define the BUTTON to be either PML-controlled, or core-code controlled using the gadget qualifier attribute control type, with values PML or CORE. The files defining any pixmaps should be specified in the form's default constructor method using the gadget's AddPixmap() method. A Button type Linklabel provides a purely textual button presentation, often used to indicate a link to some application item, e.g. a hyperlink to a file, a link to an associated form. An Example of the Linklabel gadget is shown on the example form in Fold up Gadget Link Example Form with Fold-up panels, NumericInput and Linklabel gadgets. 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. Note: 1. The Button has subtypes Normal, Toggle and Linklabel. 2. Linklabels are Buttons and so they do cause validation of any modified text fields of the form whenever they are pressed. 3. Linklabels: 1. cannot have pixmaps assigned to them 2. don't support change of background colour 3. don't support 'pressed' and 'not pressed' value 4. are not enclosed in a box 5. can have popup menus (though this is not recommended) 6. don't have Control Types e.g. OK, CANCEL etc 4. The sub-type of a Button gadget can be queried using the Button's Subtype method.

2007 AVEVA Solutions Ltd

2:31

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

.--------<-------. / | >-BUTTON gname -+- LINKLabel -+-- tagtext -------| | +-- <fgpos> -------| | +-- CALLback text -| | +-- TOOLTIP text --| | +-- <fganch> ------| | +-- <fgdock> ------| | +-- CORE ---------* Core managed gadget | | .------<-----. | |/ | | +- FORM fname -| | +- <vshap> ----* | | | +- TOOLTIP text -. | '----------------'--> | | .--------<----------. +-- TOGGLE -./ | '-----------+- tagtext -----------| +- <fgpos> -----------| +- CALLback text -----| +- TOOLTIP text ------| +- <fganch> ----------| +- <fgdock> ----------| +- CORE --------------| Core managed gadget +- BACKGround <colno>-| +- PIXMAP <vshap> ----* | .------<-----. |/ | +- FORM fname -| +- <vshap> ----* | +- OK -----. +- APPLY --| +- CANCEL -| +- RESET --| +- HELP ---| '----------+- TOOLTIP text -. '----------------'-->

Figure 2:19. Syntax Graph -: Creating a BUTTON Object

Note: It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured. Defaults: If no tag is specified, the tag defaults to the gadgets gname. The control attribute is unset unless you specifically enter OK, APPLY, HELP, CANCEL or RESET. The default values for anchoring and docking are DOCK = none, and ANCHOR = Left + Top. The Pixmaps associated with Button gadgets can be changed after the gadgets have been displayed on a form. Method syntax is: AddPixmap( !pixmap1 is STRING ) AddPixmap( !pixmap1 is STRING, !pixmap2 is STRING )

2007 AVEVA Solutions Ltd

2:32

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Where: !pixmap is a string holding the file pathname of the required .png file, e.g. %pmllib%\png\camera.png !pixmap1 shows the Un-selected state of the gadget, and pixmap2 shows the Selected state. Notes: 1. It is recommended that when you define the gadget you set its size to encompass the largest pixmap which you will later add. Failure to do this may give rise to unexpected behaviour. 2. Historically you could add a third pixmap which was used when the gadget was deactivated. This practice is no longer necessary as the gadget pixmapped is automatically greyed-out on de-activation.

2.5.10

COLLECTION Object
The collection object is used to extract database elements from the system using a selection filter (an expression object), restrictive search elements and scope lists.

Methods

Name Collection() Scope (COLLECTION)

Result

Purpose Constructor (initialises all the object settings). Empties the current scope list and makes the passed COLLECTION the current scope. Empties the current scope list and makes the passed DBREF the current scope. Adds the passed DBREF to the current scope list. Replaces the current scope list with the passed list of DBREFs. Appends the passed list of DBREFs to the scope list. Empties the current scope list. Sets the filter to be applied to the collection. Empties the filter to applied to the collection. be

Scope (DBREF)

AddScope Scope (DBREF ARRAY)

AppendScope (DBREF ARRAY) ClearScope() Filter (EXPRESSION) ClearFilter () Type (STRING)

Empties the current scope type list and adds the passed element type.

2007 AVEVA Solutions Ltd

2:33

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name AddType(STRING) ClearTypes() Types (ARRAY elements)

Result

Purpose Adds the passed element type to the scope type list. Empties the types to be applied to the collection. Replaces the scope element type list with the passed list, elements. Appends the passed list, types, to the scope type list. Initialises an evaluate list, so all query actions re-evaluate the collection rules. Sets index position to 1.

AppendTypes (ARRAY types) Initialise()

Filter() Scope() Types()

EXPRESSI ON DBREF ARRAY STRING ARRAY DBREF ARRAY DBREF ARRAY

Returns the expression used to filter database elements. Returns the list of database elements to scan. Returns the list of database element types to be collected. Returns the whole collection. Returns sub array from collection of n elements starting at current index position. Returns the current index of the count being used by Next(). Returns the number of elements in the collection.

Results() Next(REAL n)

Index()

REAL

Size ()

REAL
COLLECTION Object Methods

Table 2: 24.

2.5.11

COLUMN Object
The column object defines the way in which a column of a table object is populated. The formatting of a column should be separate from the column definition itself and be held within the report object used to extract data from a table object. This will allow the same table to have many different reports produced from it, without the need to regenerate the table.

2007 AVEVA Solutions Ltd

2:34

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Column() Column(EXPRESSION, BOOLEAN, BOOLEAN, STRING)

Result

Purpose Constructor (initialises all the object settings) Constructor setting Expression, Sort, Ascending, Key Sets key and forces it to be uppercase Defines the expression used to populate the column Switches on column sort Switches off column sort, this is the default setting Sets column ascending order sort to to

Key (STRING) Expression (EXPRESSION) Sort() NoSort() Ascending() Descending() Key() Expression() STRING EXPRESSI ON BOOLEAN STRING

Sets column sort descending order

Returns the key word for use when reporting Returns the expression used to derive the content of the column Returns TRUE if the column is sorted Returns the column sort setting, ascending, descending or off

IsSorted() SortType()

Table 2: 25.

COLUMN Object Methods

2.5.12

COLUMNFORMAT
The column object defines the way in which a column of a table object is populated. The formatting of a column should be separate from the column definition itself and be held within the report object used to extract data from a table object. This will allow the same table to have many different reports produced from it, without the need to regenerate the table.

2007 AVEVA Solutions Ltd

2:35

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name ColumnFormat() Format(FORMAT) Format(DATEFORMAT) FORMAT('STRING') Width (REAL) Widest()

Result

Purpose Constructor (initialises all the object settings) Sets the format of the column to the passed format Sets the format of the column to the passed date format Unsets the format of the column, i.e. the column Sets the column width Sets the maximum column width flag, setting a specific width value automatically sets the flag to FALSE. Note that this is the least efficient method for Width because a complete scan has to be done to determine the widest. Sets left and right indents (i.e. spaces) in the column

Indent(REAL, REAL) Format() Width() FORMAT REAL

Returns the format for numeric values in a column Returns the column width, strings greater than the column width are wrapped on to the next line, numeric values greater than the column width are output as a column of hashes. Returns TRUE if widest is set Returns the justification column

GetWidest() Justification() LeftIndent() RightIndent()

BOOLEAN STRING REAL REAL

Returns the left indent setting Returns setting the right indent

Table 2: 26.

COLUMNFORMAT Object Methods

2007 AVEVA Solutions Ltd

2:36

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.13

COMBOBOX Object
Members

Name Val DText

Type REAL Set

Purpose Get/ Selected option number.

ARRAY OF Set or get the entire list of STRING display texts. Get/Set STRING Get Get the display text of the Only n'th option. ARRAY OF Set or get the STRING replacement texts. Get/Set list of

DText[n] RText

RText[n]

STRING Get Get the replacement text of Only the n'th option.
COMBOBOX Object Members

Table 2: 27.

Methods

Name Add(STRING Dtext)

Result

Purpose

NO RESULT Append an entry to the drop down list, where Dtext is the text to display in the option list. NO RESULT Append and entry to the drop down list, where Dtext is the text to display in the option list, and Rtext is the replacement text for the new field. If Rtext isnt specified, it will be set to Dtext by default. NO RESULT Clear gadgets contents. NO RESULT Clears selection and returns to default of first in list. STRING STRING Get the full gadget name, e.g.'!!Form.gadget' Get the gadget's name, e.g. 'gadget'

Add(STRING Dtext, STRING Rtext))

Clear() ClearSelection() FullName() Name()

2007 AVEVA Solutions Ltd

2:37

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Owner() Select(STRING text, STRING value )

Result FORM

Purpose Get owning form.

NO RESULT Select specified item in a list: text must be Rtext or Dtext, and value is the item to be selected. STRING STRING Get current RTEXT. selections

Selection() Selection(STRING text )

Get RTEXT or DTEXT of current selection; text must be Rtext or Dtext.

SetPopup(MENU menu) Refresh() SetFocus() RemovePopup(MENU menu) GetPickedPopup() Shown() Type() Background()

NO RESULT Links menu with the gadget as a popup. NOT RESULT Refreshes the display of the gadget.

NO RESULT Move keyboard focus to this gadget. NO RESULT Removes (popup) from the gadget. MENU BOOLEAN STRING STRING menu

Returns the last picked popup menu for the gadget. Get shown status. Get the gadget type as a string. Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
Table 2: 28. COMBOBOX Object Methods

2007 AVEVA Solutions Ltd

2:38

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Command
.-------<-------. / | >-- COMBObox gname -+- <fgtagw> ------| +- <fgpos> -------| +- <fganch> ------| +- <fgdock> ------| +- CALLback text -| +- TOOLTIP text --| +- NORESELect ----| +- ZEROSELection -| +- CORE ----------* Core managed gadget | .-------<-------. |/ | +- SCRoll int ----| +- <vwid> --------* | +- TOOLTIP text -. '----------------'-->

When the ComboBox is editable, with the drop-down list closed, the user can search for a required option by typing the first few letters into the display field and clicking the downarrow. The list will open with the first matching option highlighted. This is useful for large lists.

Behaviour
The COMBOBOX command is a combination of an option list and an editable text display field similar to a windows combox. It shares most of the properties and methods of the Option gadget. Combo gadget has editable display text field (default) and so supports scroll width. Combobox does not support display of pixmaps. Note: It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.

Unselected Events Option gadgets support UNSELECT events. Typically when a field in the dropdown list is selected, an UNSELECT event is raised for the previously selected field (if any) and then a SELECT event is raised for the new field. Notes: 1. UNSELECT events are not notified to PML unless an open callback has been specified (so that SELECT and UNSELECT events can be differentiated). 2. Typically the UNSELECT action allows Appware to manage consequences of deselection for any dependent gadgets or forms. 3. We recommend that you do not change the option gadget's selection programmatically in an UNSELECT event.

Text Entry and Editing When the editable property is set (default), the display field is accessible to the user, who can edit the contents by typing at the keyboard or pasting text into the field. If the user presses the ENTER key while the gadget's text field has focus and contains some characters, a VALIDATE event is raised. You can trap this event by assigning a PML Open

2007 AVEVA Solutions Ltd

2:39

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

callback to the gadget. This callback allows you to give meaning to the action of typing text into the display field. The Open callback is necessary to differentiate the VALIDATE event from the SELECT and UNSELECT events. On receipt of the VALIDATE event, your callback method can retrieve the displayed text by means of the DisplayText method and decide what action is associated. Additionally you can assign a popup menu to the gadget, which gives the user the choice of several actions.

2.5.14

CONTAINER Gadget
Members

Member Name type control popup

Type STRING Get/Set REAL Get/Set MENU Get/Set

Purpose Gadget type as string 'Container'. Integer handle of external control. Popup menu associated with the control.

Methods

Method Name ShowPopup(!x is REAL, !y is REAL ) FullName( ) Name( ) Owner( ) GetPickedPopup( ) Shown( )

Result NO RESULT

Purpose Show the associated popup at the specified position. Position is the integer pixel position within the enclosed control. Get the full gadget name, i.e. !!Form.gadget. Get the gadget's name Get owning form Returns the last picked popup menu for the gadget. Get 'shown' status.

STRING STRING FORM MENU BOOLEAN

Command
The Container gadget allows the hosting of an external Control, e.g. a PMLNet, control inside a PML defined form. It allows the user to add an external .Net control, which may raise events that can be handled by PML. In order to customise the context menus of the .Net control, the Container may have a PML popup menu assigned to it. This is shown when the .Net control raises a 'popup' event.

2007 AVEVA Solutions Ltd

2:40

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

.--<-----. / | >---- CONTAINER gname -+- NOBOX ---| +- INDENT --* | '- PMLNET/CONTROL -+- handle -. '----------| .----<------------------------* | | .----<-----------------. |/ | +-- tagtext -------------| +-- <fgpos> -------------| +-- <fganch> ------------| +-- <fgdock> ------------* | +-- <vshape> -. '-------------'-->

Notes: 1. By default the Container will be enclosed in a box, but you can select NOBOX or INDENT. 2. Only PMLNet controls are supported. 3. 'handle' is the integer token identifying the control. 4. Positioning must be specified before size (<vshape>). 5. Dock and Anchor are supported to allow intelligent resize behaviour. The enclosed control must support resizing and is usually set as Dock fill, so that it follows size changes of the Container.

2.5.15

DATEFORMAT Object
The DATEFORMAT object is used to allow date attributes to be sorted in date order. Examples:

!format = object DATEFORMAT(T D/M/Y) !format.month(INTEGER) !format.year(2) !format = object DATEFORMAT(T D M Y) !format .month(BRIEF) !format = object DATEFORMAT (D M) !format.year(4) !format.month(FULL)
$ 5 November 2001 $ 12:10 05 Nov 01 $ 12:10 05/01/01

2007 AVEVA Solutions Ltd

2:41

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name DateFormat(STRING format)

Result

Purpose Constructor. Defines a format. The input string, format, is in the form 'T*D*M*Y', where T = time, D = day, M = month, Y = year, and the order of the letters indicate the format required. T and D are optional. H could be used if only hours are required. * is the separator character.

DateFormat() Month(STRING) Year(INT) String(DATETIME) STRING

Sets default format (T M D Y, month = INTEGER, year = 2) Sets month format. 'INTEGER', 'BRIEF' or 'FULL' Sets year format. 2 or 4 for number of digits Input a date in DATETIME format and convert to the specified format. Input a date in PDMS format and convert to the specified format.

String(STRING)

STRING

Table 2: 29.

DATEFORMAT Object Methods

2.5.16

DATETIME Object
Methods

Name DateTime()

Result DATETIME

Purpose Create a DATETIME object with current date and time in it. Create a DATETIME set to the given year, month, date. Time defaults to 00:00:00. As above, but month is a STRING at least three characters long representing month e.g. Jan, March, DECEM

DateTime(REAL year, REAL month, REAL date)

DATETIME

DateTime(REAL year, STRING month. REAL date)

DATETIME

2007 AVEVA Solutions Ltd

2:42

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name DateTime(REAL year, REAL month, REAL date, REAL hour,REAL minute)

Result DATETIME

Purpose Create a DATETIME object set to given year, month, date, hour, minute. Seconds default to 0. As above, but month is a STRING at least three characters long representing month e.g. Jan, March, DECEM Create a DATETIME object set to given year, month, date, hour, minute, second. As above, but month is a STRING at least three characters long representing month e.g. Jan, March, DECEM Return day of month for this DATETIME object (1-31). Test whether this DATETIME is later than or the same as argument DATETIME. Test whether this date is later than argument DATETIME. Return hour as REAL for this DATETIME object (0-23). Test whether this DATETIME is earlier or the same as argument DATETIME Test whether this DATETIME is earlier than argument DATETIME. Return minutes as REAL for this DATETIME object (059). Return month as REAL for this DATETIME object (112). Return month as STRING for this DATETIME object (January, February, etc.)

DateTime(REAL year, STRING month, REAL date, REAL hour, REAL minute)

DATETIME

DateTime(REAL year, REAL month, REAL date, REAL hour, REAL minute, REAL second) DateTime(REAL year, STRING month, REAL date, REAL hour, REAL minute, REAL second)

DATETIME

DATETIME

Date() GEQ(DATETIME)

REAL BOOLEAN

GT(DATETIME)

BOOLEAN

HOUR() LEQ(DATETIME)

REAL BOOLEAN

LT(DATETIME)

BOOLEAN

Minute()

REAL

Month()

REAL

MonthString()

STRING

2007 AVEVA Solutions Ltd

2:43

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Second()

Result REAL

Purpose Return number of seconds as REAL for this DATETIME object (0-59). Return year as REAL (e.g. 1998)

Year()

REAL
DATETIME Object Methods

Table 2: 30.

2.5.17

DB Object
Members

Name Name Description Access

Type STRING STRING STRING

Purpose The name of the database, up to 32 characters. The database description, up to 120 characters. Access type (UPDATE, MULTIWRITE, CONTROLLED). Claim mode for multi-write databases (EXPLICIT, IMPLICIT). Database filename, up to 17 characters. FOREIGN or LOCAL Database number Owning Team Database type, e.g. DESI String containing Database reference number Identifies whether a database is PRIMARY or SECONDARY at the current location in a global project

Claim

STRING

File Foreign Number Team Type Refno Primary

STRING STRING STRING TEAM STRING STRING STRING

Table 2: 31.

DB Object Members

2007 AVEVA Solutions Ltd

2:44

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name MDBList() Size() Sessions() Lastsession() DB(DBREF) DB(STRING)

Result ARRAY REAL

Purpose List of MDBS which contain this DB. File size in pages.

ARRAY OF All sessions of the current DBSESS database. DBSESS DB DB Last session information for database. Returns a DB object, given a DBREF. Returns a DB object, given a name or reference number.

Table 2: 32.

DB Object Methods

These methods may be used in the following ways (in all cases !!CE is assumed to be a DB DATABASE element and !!CE.Name is a STRING object containing the elements name). Examples:

!D = OBJECT DB(!!CE) !D = OBJECT DB(!!CE.Name) !D = !!CE.DB() !D = !!CE.Name.DB()

These methods should assist performance improvements to appware by making it easier to get from Database element to Object.

Command

!ARRAY = DBS

$ Returns an array of the DBs in the current project

2007 AVEVA Solutions Ltd

2:45

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.18

DBREF Object
Methods

Name Dbref( STRING )

Result DBREF

Purpose Creates a DBREF object with value set to the given STRING. As above. FORMAT argument required for consistency by Forms and Menus. Return the value of the named Attribute

Dbref( STRING, FORMAT )

DBREF

Attribute(STRING Name) Attributes()

ANY

ARRAY OF A DBREF appears to have STRING the attributes of whatever DB elements it is pointing to BOOLEAN TRUE if DBREF is not valid (cannot navigate to it)

BadRef() Delete()

NO RESULT Deletes the PML DBREF (not the database element it is pointing to) REAL REAL Count of number of members of element referenced Count of number of members of element referenced of type specified Convert to STRING using settings in global FORMAT object Returns the cut/uncut pline of a SCTN/GENSEC element as a bounded line Returns the position of the specified Ppoint of a database element.

MCount() MCount(STRING type)

String(FORMAT)

STRING

Line([CUT/UNCUT])

LINE

PPosition(REAL)

POSITION

PDirection(REAL)

DIRECTION Returns the direction of the specified Ppoint of a database element.

Table 2: 33.

DB Object Methods

2007 AVEVA Solutions Ltd

2:46

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.19

DBSESS Object
Members

Name Number Date Author Comment

Table 2: 34. DBSESS Object Members

Result REAL STRING STRING STRING

Purpose Session number Date when session started Creator of session Session comment

2.5.20

DIRECTION Object
Members

Name East North Up Origin

Type REAL Get/Set REAL Get/Set REAL Get/Set DBREF Get/Set

DIRECTION Object Members

Purpose UP component NORTH component UP component DB element that is the origin

Table 2: 35.

Methods
None of these methods modifies the original object.

Name Direction( STRING ) Direction( STRING, FORMAT )

Result

Purpose

DIRECTION Creates a DIRECTION with the value given by STRING. DIRECTION Creates a DIRECTION with the value given by STRING, in the format specified. BOOLEAN TRUE if two directions are the same

EQ(DIRECTION)

2007 AVEVA Solutions Ltd

2:47

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name LT(DIRECTION) String(FORMAT) WRT(DBREF)

Result BOOLEAN STRING

Purpose TRUE if direction is less than argument Convert to STRING

DIRECTION Convert to a new DIRECTION with respect to a given element. REAL Returns the angle between the two directions

Angle(DIRECTION) Bisect(DIRECTION)

DIRECTION Returns the direction which is half way between the two directions DIRECTION Returns the cross product of the two directions REAL BOOLEAN Returns the dot product of the two directions Returns true if the supplied directions are parallel, false otherwise. the opposite

Cross(DIRECTION) Dot(DIRECTION) IsParallel(DIRECTION)

Opposite() Orthogonal(DIRECTION)

DIRECTION Returns direction

DIRECTION Returns the direction orthogonal between the two directions DIRECTION Returns a direction projected onto the passed plane.

Projected(PLANE)

Table 2: 36.

DIRECTION Object Methods

2007 AVEVA Solutions Ltd

2:48

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.21

EXPRESSION Object
This object is used to define a basic expression that can be applied against a database element or another object and return any data typed result, BOOLEAN, STRING, etc. EXPRESSION objects may be used by COLLECTION objects to filter the results of the collection.

Methods

Name Expression Expression (STRING)

Result

Purpose Constructor (initialises all the objects settings). Constructs and defines the expression. ('ATTRIBUTE---') should be used for attributes for speed and efficiency. Other examples are ('PURP eq IPIPINGI') or ('XLEN + STRING(XLEN)'). Makes the passed attribute an expression. AttributeExpression ('LENGTH') is the same as Expression ('ATTRIBUTE LENGTH').

AttributeExpression (STRING)

String() Evaluate(DBREF)

STRING ANY

Returns the current expression as a string. Evaluates the current expression against the passed object

Table 2: 37.

EXPRESSION Object Methods

2007 AVEVA Solutions Ltd

2:49

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.22

FILE Object
Methods

Name File(STRING)

Result FILE

Purpose Create a FILE object on a file whose name is given in STRING. Return access mode for the file {CLOSED, READ, WRITE, OVERWRITE, APPEND}.

AccessMode()

STRING

Close() Copy(STRING)

NO RESULT Close file if open. FILE Copies the file whose pathname is given in STRING. Returns FILE object for copied file. Copies the file represented by the FILE object. Returns FILE object for copied file.

Copy(FILE)

FILE

DeleteFile() Directory()

NO RESULT Delete the file represented by the file object if it exists. FILE Returns a FILE object corresponding to owning directory. Returns a DATETIME object holding the date and time that this file was last modified. Returns file name as string. Returns BOOLEAN indicating whether file exists or not.

DTM()

DATETIME

Entry() Exists()

STRING BOOLEAN

Files()

ARRAY OF Returns an ARRAY of FILE FILES objects corresponding to files owned by this directory. STRING Returns the name including path for this FILE object as a STRING. Return BOOLEAN indicating whether file is open or not.

FullName()

IsOpen()

BOOLEAN

2007 AVEVA Solutions Ltd

2:50

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name LineNumber() Move(STRING)

Result REAL FILE

Purpose Return line number of line about to be written. Move this file to location given in STRING. Return FILE object for moved file. Move this file to location represented by FILE object. Return name of this FILE object as STRING.

Move(FILE) Name() Open(STRING)

FILE STRING

NO RESULT Opens this file in the mode given by STRING {READ,WRITE,OVERWRI TE, APPEND} STRING Returns the ID of this FILES owner a STRING.

Owner() Path()

ARRAY OF Returns an ARRAY of FILEs FILES corresponding to the owning directories of this FILE object. STRING Returns owning path as a STRING.

PathName() ReadFile()

ARRAY OF Open, read contents and STRING close file. Data returned as an ARRAY of STRINGs corresponding to the lines in the file. ARRAY OF As above, but ensures that STRING file is no longer than number of lines given in REAL. STRING Reads a line from an open file and returns it in a STRING. Returns an UNSET STRING if end of file is detected. Returns a BOOLEAN indicating whether this FILE object has a name set or not. Returns size of file in bytes.

ReadFile(REAL)

ReadRecord()

Set()

BOOLEAN

Size() SubDirs()

REAL

ARRAY OF Returns an ARRAY of FILE FILE objects corresponding to directories owned by this directory.

2007 AVEVA Solutions Ltd

2:51

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Type()

Result STRING

Purpose Returns a STRING indicating whether this object represents a FILE or a DIRECTORY.

WriteFile(STRING, ARRAY OF STRING)

NO RESULT Opens file in mode given in string {WRITE, OVERWRITE, APPEND}, writes STRINGs in ARRAY and closes file. NO RESULT Writes STRING to this FILE which must already be open.

WriteRecord(STRING)

Table 2: 38.

FILE Object Methods

2.5.23

FMSYS Object
Methods
None of these methods modifies the original object.

Name SetMain(FORM) Main() Refresh() Checkrefs

Result FORM FORM

Purpose Sets the main form for an Application. Query the current main form

NO RESULT Refresh all VIEW gadgets BOOLEAN By default, all references in a Form definition are checked when a form is displayed. Checking can be switched off, which may be recommended if performance problems are experienced.

SetInterrupt(GADGET)

NO RESULT Sets the Gadget which will interrupt macro or function processing. NO RESULT Removes the display of a splash screen after an abnormal exit. BOOLEAN Set to TRUE if the interrupt gadget has been selected.

Splashscreen(BOOLEAN)

Interrupt() FMINFO()

ARRAY OF Returns array of all FMINFO STRINGS strings.

2007 AVEVA Solutions Ltd

2:52

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name DocsAtMaxScreen(BOOLEAN)

Result

Purpose

NO RESULT Sets default placement position for document forms to be towards the maximum (rightmost) of the screen. Useful for wide screen ad twin screen devices. REAL Get the current Integer value in percent shown by the progress bar, in the range 0 to 100. Zero means the bars is invisible

Progress( )

SetProgress( !percent)

NO RESULT Set the Integer value in percent to be displayed in the progress bar. Values will be forced into the range 0 to 100. Resultant value of 0 will cause the bar to become invisible. FORM This method returns the current Document of the application framework as a FORM object. If there is no current document then the returned form has value Unset. Allows force loading of a form definition and/or the ability to get a reference to a form object by name. If the form exists then a reference to the form object is returned. If it doesnt exist, then an attempt is made to force load its definition. If this fails then an unset form reference is returned.

CurrentDocument()

LoadForm(STRING formname)

FORM

SetHelpFileAlias (alias is string) HelpFileAlias()

NONE STRING

establishes the application help file from its alias. returns the current help files alias.

2007 AVEVA Solutions Ltd

2:53

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name OKCurfnView(!viewtype is STRING)

Result BOOLEAN

Purpose Queries whether graphical views of the specified view type are displayed. Graphical view types supported are: G2D; G3D; ANY and any view subtype is implied. Queries whether graphical views of the specified view type and subtype are displayed. Graphical view types supported are: G2D; G3D; ANY. View subtypes supported are: ANY and for G2D: NORMAL (Draft); PLOT; ISOSPOOL G3D: NORMAL (Design)

OKCurfnView(!viewtype is STRING, subtype is STRING )

BOOLEAN

Table 2: 39.

FMSYS Object Methods

2.5.24

FORM Object
Members
Name FormRevision FormTitle IconTitle Initcall Autocall Type Purpose

STRING Get/ Form Revision text. Set STRING Get/ Form title. Set STRING Get/ Icon title. Set STRING Get/ Callback executed when form Set is initialised. STRING Get/ Callback executed when any Set of the specified application attributes have changed. STRING Get/ Callback executed when OK Set button is pressed. STRING Get/ Callback executed when Set CANCEL button is pressed. GADGET Get/Set Gadget to have initial keyboard focus on display of the form. One of TEXTFIELD, TEXTPANE, BUTTON, TOGGLE or ALPHA VIEW.

Okcall Cancelcall KeyboardFocus

2007 AVEVA Solutions Ltd

2:54

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name AutoScroll

Type BOOLEAN Get/Set

Purpose If AutoScroll is selected the form will automatically gain horizontal or vertical scrollbars if the forms size becomes too small to display its defined contents. This member does not apply to form types Main Window and Document.

Quitcall

STRING Get/ Callback executed whenever Set the user presses the Quit/ Close icon (X) on the title bar of forms and the main application window. For forms of type MAIN, the QUITCALL callback is executed, if present. This permits the user to terminate the application, and so the associated PML callback should prompt the user for confirmation. For all other form types, the QUITCALL callback is executed, if present, and then the form and its children are hidden unless the PML callback returns an error. When the form nest is hidden the CANCELCALL callback for each form of the nest is executed (in reverse display order).

Maximised Active Popup HelpContextID

BOOLEAN Get/Set BOOLEAN Get Only MENU Get/Set STRING

Get/set forms maximised status (on screen). Gives form's active/inactive status. Get/set forms current popup menu. Read/Write STRING Property:!!myform.HelpConte xtID = STRING - sets the context Id within the help file for this form. STRING=!!myform.HelpCont extID - gets the current context Id for this form.

Table 2: 40.

FORM Object Members

2007 AVEVA Solutions Ltd

2:55

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Name() FullName() NewMenu(STRING menuname) NewMenu(STRING menuname, STRING type)

Result STRING STRING MENU MENU

Purpose Get name. Get the full (Including !!). form name

Adds a new named menu to the form. Adds a new named and typed menu to the form. The first argument is the name of the new menu; the second argument is the type of the menu, and must be either POPUP or MAIN.

SetActive(BOOLEAN)

NO RESULT SetActive(FALSE) greysout all gadgets on the form, but doesnt set their Active status, so that SetActive(TRUE) restores the form to the precise state it was in before greying out, i.e. any inactive gadgets will still be inactive. NO RESULT SetGadgetsActive(FALS E) greys out all gadgets on the form and sets their Active status to inactive, i.e. their previous active state is lost. Similarly SetGadgetsActive(TRUE) greys-in all gadgets and sets their Active status to active. NO RESULT Specifies the pop-up to be displayed when the righthand mouse button is released over the form background. NO RESULT Removes a pop-up associated with a form. MENU Returns the last picked popup menu for the form.

SetGadgetsActive(BOOLEAN)

SetPopup(MENU)

RemovePopup(MENU) GetPickedPopup() Show('FREE')

NO RESULT Show the form on the screen as a FREE form.

2007 AVEVA Solutions Ltd

2:56

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Show('AT', REAL X, REAL Y)

Result

Purpose

NO RESULT Show the form as a FREE form with the origin at the X,Y relative screen position. NO RESULT Show the form as a FREE form with its centre at the X,Y relative screen position. BOOLEAN Get 'shown' status

Show('CEN', REAL X, REAL Y)

Shown() Hide() Owner()

NO RESULT Hides the form (removes it from the screen) FORM Returns the form's parent form, or unset variable if the form is free-standing Set the percentage opaqueness of the form as an integer in the range 10 (nearly transparent) to 100 (opaque - default). This is only valid for non-docking Dialog and BlockingDialog form types. Example of use: for a normal frame the subtype string will be NORMAL; for a tabset frame the subtype string will be TABSET.

SetOpacity( !percent )

NONE

Subtype( )

STRING

Table 2: 41.

FORM Object Methods

Note: SetActive()and SetGadgetsActive()can be used in combination with each other and with the Active property of individual gadgets.

Commands
SETUP FORM A form definition is introduced by the SETUP FORM command and terminated by a corresponding EXIT command. Once in Form Setup mode you can call any commands for defining the forms properties, creating a menu bar (see BAR object), main and popup menus (see MENU object) and any gadgets which it is to own. Once-only form attributes are entered as part of the SETUP FORM command line; modifiable attributes are entered as contents of the form. You can define the FORM to be either PML-controlled, or core-code controlled using the qualifier attribute control type, with values PML or CORE.

NOALIGN The gadgets BUTTON, TOGGLE, TEXT, OPTION, single line PARGRAPH fit within 1 vertical grid unit and are by default drawn with their Y-coordinate adjusted so that they would

2007 AVEVA Solutions Ltd

2:57

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

approximately centre-align with an adjacent BUTTON. This pseudo-alignment introduces small errors in all but a few circumstances and prevents accurate controlled layout. NOALIGN prevents this (historical) gadget auto-alignment. Use NOALIGN in conjunction with PATH RIGHT (the default path) and HALIGN CENTRE, as it gives a better layout, with fewer surprises. Note: It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured. The commands to set modifiable attributes are described after the syntax graph.

.---------------<---------------------------. / | >--SETUP FORM fname --+-- MAIN -----+-------------------------------| +-- DOCUMENT -+- FLOAT -----------------------| | -------------------------------| +-- DIALOG ---+- DOCKing -+-------------------| | |- Left ---. | | | |- Right --| | | | |- Top ----| | | | - Bottom ---------| | |- RESIzeable ------------------| | -------------------------------| +-- BLOCKingdialog -+- RESIzeable ------------| | -------------------------| +-- AT <xypos> -------------------------------| +-- SIZE val val -----------------------------| +-- NOQUIT -----------------------------------| +-- NOALIGN ----------------------------------| +-- CORE -------------------------------------* | .---<------. |/ | +-- <form> --* form contents EXIT -->

Default: CANCELCALL

Dialog, non-resizeable; size adjusted automatically to fit contents.

This command defines the callback string which is executed whenever the form is dismissed from the screen via the CANCEL button or the QUIT/CLOSE control on the window title bar.

>-- CANCELcall text -->

Note: This command overrides the callback string on the CANCEL button.

2007 AVEVA Solutions Ltd

2:58

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

CURSORTYPE When a screen cursor enters a view, the view gadget determines what cursor type should be displayed initially, and what type will be displayed during different types of graphical interaction. You can specify the initial setting for the cursor type using this command. Note: You cannot specify an initial cursor type for VOLUME views.

>-- CURSortype

--+-+-+-+--

POINTER ----. NOCURSOR ---| PICK -------| PICKPLUS ---|

-- CROSSHAIR ---->
Note: There are other cursor types that are for AVEVAs use only. HALIGN Works in conjunction with PATH and HDISTANCE. Defines how a newly added gadget should be aligned horizontally with the preceding gadget.

>-- HAlign --+-- Left ---. -- Right ---->

HDISTANCE Works in conjunction with PATH and HALIGN. Defines how a newly added gadget should be spaced horizontally with respect to the preceding gadget.

>-- HDistance value -->

ICONTITLE Defines the title for the icon when the form is minimised.

>-- ICONTItle text -->

INITCALL Defines the callback string that is executed each time the form is displayed. This callback is usually run to check the validity of showing the form and to initialise gadget values.

>-- INITcall text -->

2007 AVEVA Solutions Ltd

2:59

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

OKCALL Defines the OK callback string for a form. It is executed whenever the form is dismissed from the screen via its OK button or that of an ancestor.

>-- OKcall text -->

Note: This command overrides the callback string on the OK button. PATH Defines the direction in which a sequence of new gadgets is to be added to a form. The path setting remains until you give another PATH command. Used with HALIGN, HDISTANCE, VALIGN, VDISTANCE.

>-- PATH --+-- Up ------. +-- Down ----| +-- Left ----| -- Right ----->

Default: TITLE Defines the form title.

Path Right.

>-- TITLe text -->

VALIGN Use in conjunction with PATH and VDISTANCE. Defines how a newly added gadget should be aligned vertically with the preceding gadget.

>-- VAlign --+-- Top -----. -- Bottom ---->

VDISTANCE Works in conjunction with PATH and VALIGN. Defines how a newly added gadget should be spaced vertically with respect to the preceding gadget.

>-- VDistance value -->

2007 AVEVA Solutions Ltd

2:60

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

FirstShown and Killing Events

The following actions determine the life of a form: Define Load Show Activate the form, its gadgets, methods and layout are specified (usually in a '.pmlfrm' file) the form definition is read by PML and the form's constructor method is run the form's INITialisation event is raised, and the display process is begun the form and its contents is created by the window management system and is activated (actually displayed) and the FIRSTSHOWN event is raised the form is hidden and its OK or CANCEL event is raised the form's KILLING event is raised and then the form is destroyed. It is no longer known to PML

Hide Kill

Notes: 1. Load, Activate and Kill only happen once in the life of a form 2. Show and Hide may happen repeatedly 3. The form's Constructor is run once only 4. The FirstShown event only happens once 5. INIT is raised for every Show The PML user can define callbacks to service any or all of the above events. These will typically be open callbacks supported by form methods. They can be assigned within the form's Constructor method (recommended), or within the form's Setup Form . . . Exit block. FIRSTSHOWN callback Typically assigned in the Constructor by !this.FirstShownCall = '!this.<form_method>' The purpose is to allow the user to carry out any form actions which can only be completed when the form is actually displayed. There are a variety of circumstances where this arises and it is often difficult to find a reliable solution. A couple of examples are given below. Commands which manipulate form, menu or gadget visual properties, executed from a PML macro, function or callback may not happen until control is returned to the window manager's event loop. For example, in the application's start-up macro the command sequence show !!myForm hide !!myform will result in the form not being displayed, but also not becoming known at all to the window manager. Attempts to communicate with this form via the External callback mechanism (possibly from another process) will not work. This can be rectified by doing the '!this.hide()' within the FIRSTSHOWN callback, because the form will be guaranteed to be actually displayed (and hence known to the window manager), before it is hidden. It is sometimes difficult to achieve the correct gadget background colour setting the first time the form is displayed. This can be resolved by setting the required colour in the FIRSTSHOWN callback.

2007 AVEVA Solutions Ltd

2:61

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

KILLING callback Typically assigned in the Constructor by !this.KillingCall = '!this.<form_method>' The purpose is to notify the form that it is being destroyed and allow the assigned callback method to destroy any associated resouirces, e.g. global PML objects which would otherwise not be destroyed. This may be necessary because PML global objects will survive an application module switch, but may not be valid in the new module. Notes: 1. The callback method MUST NOT carry out any modifications to the Gadgets belonging to the form or to the Form itself (e.g. don't show or hide the form). Attempts to edit the form or its gadgets may cause unwanted side effects or possible system errors. 2. Form callbacks designed for other Form events (e.g. CANCEL, INIT) are rarely suitable as killing callbacks. 3. Restrict form and gadget operations to querying.

2.5.25

FORMAT Object
Members

Name CompSeparator

Type STRING | |

Purpose Separator used for multicomponent data types such as POSITIONS (Default SPACE). Largest denominator Imperial fractions (Default 32) for

Denominator

REAL 32

Dimension

STRING NONE L L2 L3

Number is un-dimensioned (Default) Number is a LENGTH Number is an AREA Number is a VOLUME Number of decimal places for decimal fractions (Default 2) Use ENU outputting (Default) format when POSITIONS

DP ENU

REAL 2 BOOLEAN TRUE FALSE

Use XYZ format when outputting POSITIONS

2007 AVEVA Solutions Ltd

2:62

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Fraction

Type BOOLEAN FALSE TRUE

Purpose Fractional part output decimal (Default) Fractional fraction part output as as

FtLabel

STRING ||

Label used for feet e.g. ' or FT or ft or feet (Default )

InchSeparator

STRING |.|

Separator between inches and fractions (Default . )

Label

STRING |mm|

General distance label e.g. mm or m or " or IN (Default is no label)

PadFractions

BOOLEAN FALSE TRUE STRING MM M FINCH INCH

Do not pad Fractions (Default) Pad Fractions with trailing spaces Output number in millimetres (Default) Output number in metres. Output number in feet and inches Output number in inches With respect (Default) to World

Units

OriginExp

BLOCK || |/*| |CE|

With respect to World With respect Element to Current

Zeros

BOOLEAN TRUE FALSE

Leading zeroes are displayed for Imperial units (Default). Leading zeroes are not displayed for Imperial units

Table 2: 42.

FORMAT Object Members

2007 AVEVA Solutions Ltd

2:63

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.26

FRAME Gadget
Members

Name Tag Val RGroupCount

Type STRING Get/Set REAL Set REAL only

Purpose Text to appear as title on the frame. Get/ Selected radio button index as integer. Get Count of radio buttons (RTOGGLES) within the FRAMEs radio group. Returns zero if the FRAME is not a radio group. Radio group select callback string. FoldUpPanels status expanded

Callback

STRING Get/Set BOOLEAN Get/Set

Expanded
Table 2: 43. FRAME Object Members

Methods

Name Rtoggle( !index is REAL ) Background()

Result GADGET STRING

Purpose Returns the RTOGGLE gadget with index !index. Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
Table 2: 44. FRAME Object Methods

Command
The FRAME command defines a frame gadget. A frame is a container which owns and manages any gadgets defined within its scope, including other frames.

2007 AVEVA Solutions Ltd

2:64

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

The frame gadget properties visible and active will automatically apply to all of its children, but will not overwrite their corresponding property values. There are five types of FRAME: NORMAL, TABSET, TOOLBAR, PANEL and FOLDUP PANEL. A NORMAL frame can contain any type of gadget, including other frames. It also behaves as a radio group, with radio buttons defined by the set of RTOGGLE gadgets that it directly contains. See the entry RTOGGLE Object for more about the RTOGGLE gadget. A TABSET frame can contain only tabbed page FRAMEs; you cannot nest them and they are not named. A TOOLBAR frame can contain only a subset of gadget types: BUTTON, TOGGLE, OPTION, and TEXT. It must have a name and can appear only on main forms.

>--FRAME gname -+| | | +| | | | | | | | +| +-

.---<-------. / | TOOLBAR -+- tagtext -+- <toolbar> -* toolbar contents - EXIT --> .---<--------. / | TABSET -+-- <fgpos> ---| +-- <fganch> --| +-- <fgdock> --| +-- <vshap> ---* | .---<--------. |/ | +-- <tabset> --| tabbed frame contents +-- NL --------* -- EXIT --> PANEL --+----------. --INDENT--| FOLDUPpanel -------| .---<--------. |/ | +-- tagtext ---| +-- <fgpos> ---| +-- <fganch> --| +-- <fgdock> --| +-- <vshap> ---* | .---<--------. |/ | +-- <formc> ---* form contents -- EXIT -->

where the sub-graphs <toolbar>, <tabset> and <formc> define the allowable gadgets and layout commands available within the specific container type. Note: The graph <formc> defines the normal content of a form, all gadget types (except BAR) are allowed. There are restrictions on frame gadget types as defined below.

Setting Up a TOOLBAR Frame

The toolbar frame allows you to define formal toolbars that contain all the gadgets in the frames scope. You can define a toolbar frame only for a main form, and a main form can contain only toolbar frames.

2007 AVEVA Solutions Ltd

2:65

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

The graph below defines the allowable content of a toolbar frame: >-- toolbar -+-+-+-+-+-+-+-<fbutn> ----. <ftext> ----| <ftogl> ----| <foptio> ---| <fvar> -----| <pml> ------| <nxasgn> ---| Button gadget text gadget toggle gadget option gadget form variable definition general PML PML expressions variable setting VAR

-- <varset> ------->

Setting Up a TABSET Frame

A TABSET frame defines a container for a set of tabbed page frames. It has no visible border and no name. The graph below defines allowable contents of a TABSET frame: >-- tabset >-+-+-+-+-<fframe> ---. <fvar> -----| <pml> ------| <nxasgn> ---| frame gadget form variable definition general PML PML expressions variable setting VAR

-- <varset> ------->

Note: Frame gadgets defined anywhere within the TABSET frame can only be of type NORMAL, not TOOLBAR or TABSET frames. NORMAL frames defined directly within the TABSET frame, will appear as tabbed pages within it.

Setting up a Panel Frame

The panel is a rectangular region within a form which can contain the normal form gadgets, but doesn't have to be enclosed in a solid-line box. Notes: 1. After choosing frame type Panel, the contents is defined in the usual manner. 2. Tagtext can be specified, but it is never displayed. 3. The panel has no visible enclosing box, unless the INDENT option is specified when it will have a 3D indented appearance. 4. Panel supports all the attributes of a Normal Frame including the notion of a radio button group.

Setting up in Fold Up Panel

This is a rectangular panel with a visible title bar, and border. The following form in this section below shows examples of fold-up panel frame gadgets. Notes: 1. After choosing frame type FoldUpPanel, the contents is defined in the usual manner. The panel can contain the usual PML gadgets except another FoldUpPanel. 2. Separate events are raised after expanding or collapsing the panel.

2007 AVEVA Solutions Ltd

2:66

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

3. The default state is 'expanded'. 4. When the panel expands or collapses, any gadgets which lie below the panel and between (or partially between) the panel's horizontal limits will be moved down or up the form. 5. If the form's AutoScroll attribute is selected, then a scroll bar will automatically appear whenever gadgets have been moved off the bottom of the form, so that all of the form is still accessible. 6. The FoldUpPanel supports all the attributes of a Normal Frame including the notion of a radio button group The form shown below is a docking dialog which has four fold-up panels, the first two are collapsed (hidden) and the second two are expanded (shown). Each one has a title bar which displays the panel's tag text, and an icon which allows the panel to fold-up or folddown when it is pressed. Note the use of the form's AutoScroll attribute and the resulting scroll bar. The PML code for this example form is given in the file textbug.pmlfrm.

For frames which are FoldUpPanels, 'HIDDEN' and 'SHOWN' events are raised whenever the user interactively folds or unfolds the panel. These events are only fired if a PML open callback is defined. This ensures that the SELECT event, used to signal selection of a radio button within a foldup panel can still be handled by simple (non-Open) callbacks. To manage FoldUpPanels which are also radio groups, then you must supply an open callback so that you can differentiate the panel's SELECT, HIDDEN and SHOWN events.

2007 AVEVA Solutions Ltd

2:67

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Tabbed Page Frame Visible Property and 'Hidden' event

The VISIBLE property allows a tabbed page to be selected and given focus, e.g. !this.TabbedPage.visible = true When a tabbed page frame's tab is interactively selected, there is now a HIDDEN event raised when the currently shown page is hidden, followed by a SHOWN event when the newly selected page is shown. These events are only raised if a PML open callback has been assigned.

2.5.27

LINE Gadget
Members and Methods
The LINE gadget supports the standard default gadget members and methods only.

Command
The Line gadget gives the ability to display horizontal or vertical lines to separate groups of gadgets on a form, for increased clarity of intent. The line's presentation reflects the colour of the current Windows scheme. .-------<---------------. / | >--- LINE gname -+- tagtext ---------------| +- <fgpos> ---------------| +- <fganch> --------------| +- <fgdock> --------------* | +- VERTical ---. | | '- HORIZontal -'- <vshap> -->

2007 AVEVA Solutions Ltd

2:68

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Example: The form 'Nested Frames' above shows a vertical LINE and a horizontal LINE. The code snippet below shows the construction of the innermost frame f3. frame .f3 'f3' vdist 0.2 hdist 0.5 toggle .t1 'Toggle 1' at x 2 line .horiz 'H-Line' Horiz wid.f3 hei.t1 toggle .t2 'Toggle 2' line .vert at xmin.f3 ymin.f3+0.5 Vert wid 2 hei.f3 exit Notes: 1. The tag text is never displayed. 2. Line does not apply to toolbars. 3. The graph <vshap> allows the line's width and height to be set either specifically or in terms of other gadgets on the form. 4. Setting the height for a Horizontal separator or the width for a Vertical separator causes the line to be drawn across the middle of the implied area. This allows for equal spacing on each side of the separator line. Otherwise a default width or height is assumed. 5. The Dock and Anchor attributes allow the Lines to be dynamic and respond to interactive changes in form size. 6. The gadget is not interactive and has no associated value.

2.5.28

LINE Object
See also the POINTVECTOR object.

Members

Name StartPosition EndPosition

Type POSITION Get/Set POSITION Get/Set

Purpose Start position of line. End position of line.

Table 2: 45.

LINE Object Members

2007 AVEVA Solutions Ltd

2:69

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Definition Methods
None of these methods modifies the original object. Name Line( POSITION first, POSITION second) Result LINE Purpose Creates a LINE between the given positions, first and second. Returns the STRING. line as a

String() Direction()

STRING

DIRECTION Returns a DIRECTION representing the direction of the line. LINE Creates a new line with the same start position and length but in the direction given by way.

Direction(DIRECTION way)

Table 2: 46.

LINE Object Definition Methods

EndPosition Direction(DIRECTION)

StartPosition

Figure 2:20. : Basic LINE Definition

LINE Object Methods that Return BOOLEANs

None of these methods modifies the original object. Name On(POSITION where) OnProjected(POSITION where) Result BOOLEAN BOOLEAN Purpose Returns TRUE if where lies on the bounded line. Returns TRUE if where, when projected onto the line, lies within the bounded line.

Figure 2:21. LINE Object Methods that Return BOOLEANs

2007 AVEVA Solutions Ltd

2:70

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

OnProjected(POSITION) 9

On (POSITION) 9

Figure 2:22. BOOLEANs Returned by LINE Object Methods

LINE Object Methods that Return POSITIONs

None of these methods modifies the original object. Name Intersection(LINE other) Result POSITION Purpose Returns the intersection point of the passed LINE on the line definition Returns the intersection point of the passed POINTVECTOR on the line definition. Returns the intersection line of plane on the line definition.

Intersection(POINT point, VECTOR vector)

POSITION

Intersection(PLANE plane)

LINE

Intersections(ARC arc)

ARRAY OF Returns the intersection POSITIONS points of arc on the line definition. POSITION Returns the nearest position on the line definition to position. Returns the position at proportion along the bounded line from the StartPosition. Values > 1 will give positions off the end of the line. Values < 0 will give positions off the start of the line.

Near(POSITION position)

Proportion(REAL proprtion)

POSITION

Table 2: 47.

LINE Object Methods that Return POSITIONs

2007 AVEVA Solutions Ltd

2:71

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Proportion(REAL) Intersection(LINE)

Near(POSITION)

Figure 2:23. POSITIONs Returned by LINE Object Methods

LINE Object Methods that Return REALs

None of these methods modifies the original object. Name Length() Distance(LINE other) Result REAL REAL Purpose Returns the length of the line. Returns the minimum distance between the line definition and other. Returns the minimum distance between the line definition and position.

Distance(POSITION position)

REAL

Figure 2:24. Table -48: LINE Object Methods that Return REALs

Length()

Distance(POSITION)

Distance(LINE)

Figure 2:25. REALs Returned by LINE Object Methods

2007 AVEVA Solutions Ltd

2:72

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

LINE Object: Miscellaneous Methods

None of these methods modifies the original object. Name Plane() Result PLANE Purpose Returns a plane object, using the StartPosition and Direction of line object Returns a POINTVECTOR object, using the StartPosition and Direction of line object

Pointvector()

POINTVEC TOR

Figure 2:26. LINE Object Miscellaneous Methods

LINE Object Methods that Return LINEs (a)

None of these methods modifies the original object. Name SetLengthStart(REAL length) Result LINE Purpose Returns a new line, maintaining the original StartPosition and direction, with an EndPosition to match length. Returns a new line, maintaining the original EndPosition and direction, with a StartPosition to match length. Returns a new line object with the same StartPosition and the same relative EndPosition (Length) of the original line, but the direction is from the start position to position. Returns a line, where the StartPosition is set position, maintaining the original EndPosition. Returns a line, where the EndPosition is set to position, maintaining the original StartPosition

SetLengthEnd(REAL length)

LINE

Towards(POSITION position)

LINE

From(POSITION position)

LINE

To(POSITION position)

LINE

2007 AVEVA Solutions Ltd

2:73

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name ExtendStart(REAL distance)

Result LINE

Purpose Returns a new LINE, where the StartPosition has been extended in the opposite direction of line by distance. Returns a new LINE, where the EndPosition has been extended in the direction of the line by distance.

ExtendEnd(REAL distance)

LINE

Table 2: 48.

LINE Object Methods that Return LINEs (a)

ExtendEnd(REAL) To(POSITION)

SetLengthStart(REAL) ExtendStart(REAL)

Towards(POSITION)

From(POSITION)

SetLengthEnd(REAL)

Figure 2:27. LINEs Returned by LINE Object Methods (a)

LINE Object Methods thet Return Lines (b)

Name ExtendStart(PLANE plane)

Result LINE

Purpose Returns a new LINE, where the StartPosition has been extended to plane. Returns a new LINE, where the EndPosition has been extended to plane. Returns a line, where the StartPosition and EndPosition have been transposed.

ExtendEnd(PLANE plane)

LINE

ReverseSense()

LINE

2007 AVEVA Solutions Ltd

2:74

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Projected(PLANE plane)

Result LINE

Purpose Returns a LINE definition normalised onto plane. See picture. Returns a parallel to the line definition of the line object, through position. All other members are copied. See picture. Returns a parallel line to the LINE object, offset by offset from the original in the given direction. See picture.

Parallel(POSITION position)

LINE

Offset(DIRECTION direction, REAL offset)

LINE

Figure 2:28. LINE Object Methods that Return LINEs (b)

Parallel(POSITION)

Offset(DIRECTION, REAL)

Projected(PLANE)

Figure 2:29. LINEs Returned by LINE Object Methods (b)

2007 AVEVA Solutions Ltd

2:75

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

LINE Object Methods thet Return Lines (c)

Name Overlap(LINE other)

Result LINE

Purpose Returns the overlapping line of two parallel lines. All positions are return projected onto the original object. See picture. Returns the union of LINE and other. The two are parallel lines, all positions are return projected onto the original object. See picture.

Union(LINE other)

LINE

Table 2: 49.

LINE Object Methods that Return LINEs (c)

Union(Line)

Overlap(Line)
Figure 2:30. LINEs Returned by LINE Object Methods (c)

LINEARGRID Object Construction Aids

Members

Name Position Orientation XSpacing YSpacing

Type POSITION Get/Set ORIENTATI ON Get/Set REAL Get/Set REAL Get/Set

LINEARGRID Object Members

Purpose Origin of the grid Orientation of the grid Spacing in the X direction Spacing in the Y direction

Table 2: 50.

2007 AVEVA Solutions Ltd

2:76

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Definition Methods
These methods do not modify the original object. Name Lineargrid( POSITION, ORIENTATION, REAL, REAL) Result LINEARGRI D STRING
LINEARGRID Object: Basic Members

Purpose Creates a grid with the given POSITION, ORIENTATION, and X and Y spacing. Returns the grid as a string

String()
Table 2: 51.

Orientation YSpacing Z Y Position

X XSpacing
Figure 2:31. LINEARGRID Basic Definition

LINEARGRID Object Methods that Return POSITIONs

None of these methods modifies the original object. Name GridPoint(REAL, REAL) Result POSITION Purpose Returns the position at the intersection of the passed X and Y lines from the origin of the grid. Values can be +ve or -ve depending on the side of the origin Returns the nearest intersection point to the passed position, when mapped onto the grid plane Returns the nearest intersection point to the intersection of the passed line and the grid plane

Snap(POSITION)

POSITION

Snap(LINE)

POSITION

2007 AVEVA Solutions Ltd

2:77

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Snap(POINTVECTOR)

Result POSITION

Purpose Returns the nearest intersection point to the intersection of the passed point vector and the grid plane Returns the nearest mesh cell centre point to the passed position, when mapped onto the grid plane Returns the nearest mesh cell centre point to the intersection of the passed line and the grid plane Returns the nearest mesh cell centre point to the intersection of the passed point vector and the grid plane

SnaptoCentre(POSITION)

POSITION

SnaptoCentre(LINE)

POSITION

SnaptoCentre(POINTVECTOR)

POSITION

Table 2: 52.

LINEARGRID Object Methods that Return POSITIONs

Snap(POSITION)

Snap(LINE) GridPoint(REAL, REAL)

Figure 2:32. POSITIONs Returned by LINEARGRID Methods

2007 AVEVA Solutions Ltd

2:78

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.29

LINEARGRID Object
This method does not modify the original object. Name Plane() Result PLANE Purpose Returns the grid as plane object

Table 2: 53.

Miscellaneous LINEARGRID Object Methods

Within(POSITION)  Plane()

Within(POSITION) 
Figure 2:33. Miscellaneous Return Values from LINEARGRID Methods

LINEARGRID Object Methods that Return XYOffsets

This method does not modify the original object. Name XYOffset(POSITION) Result XYPOSITIO N Purpose Returns the position, mapped onto the grid plane, in terms of an XY offset from the grid plane origin

Table 2: 54.

LINEARGRID Object Methods that Return XYOffsets

XYOffset(POSITION)
Figure 2:34. XYOffsets Returned by LINEARGRID Object Methods

2007 AVEVA Solutions Ltd

2:79

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.30

LIST Gadget
Members

Name Val Val

Type REAL Set

Purpose Get/ Selected field-number of a single-choice list.

REAL Selected field numbers of a ARRAY Get/ multiple-choice list. Set STRING Set or get the entire list of ARRAY Get/ display texts. Set STRING Get Get the display text of the Only n'th field. REAL Only Get Last picked list field number. list of

DText

DText[n] PickedField RText

STRING Set or get the ARRAY Get/ replacement texts. Set STRING Only REAL Get only REAL Get/Set

RText[n] Count val

et Get the replacement text of the n'th field. Get count of number of fields in the list Selected field as integer. Zero implies no selection. Setting val to zero will cause an error for mandatory selection lists.

Table 2: 55.

LIST Object Members

2007 AVEVA Solutions Ltd

2:80

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Add(STRING Dtext)

Result

Purpose

NO RESULT Append an entry to the list, where Dtext is the text to display in the option list. NO RESULT Append and entry to the list, where Dtext is the text to display in the option list, and Rtext is the replacement text for the new field. If Rtext isnt specified, it will be set to Dtext by default. STRING STRING FORM Get the full name of the gadget, e.g..'!!Form.gadget' Get the gadget's name, e.g. 'gadget' Get owning form.

Add(STRING Dtext, STRING Rtext))

FullName() Name() Owner() Select(STRING text, STRING value)

NO RESULT Select specified item in a list. text must be Rtext or Dtext. value is the RTEXT or DTEXT of the item to be selected. NO RESULT Select multiple choice list items. text must be 'Rtext' or 'Dtext'. values contains the RTEXT or DTEXT values to be selected. STRING Get selected RTEXT ARRAY OF Array of RTEXT for multiSTRING choice list. STRING Get selected RTEXT or ARRAY OF DTEXT STRING Array of texts for multi-choice list. text must be 'Rtext' or 'Dtext'.

Select(STRING text, ARRAY of STRING values)

Selection( )

Selection(STRING text)

Clear() ClearSelection() SetPopup(MENU menu)

NO RESULT Clear list selections.

contents

and

NO RESULT Clear list selections. NO RESULT Links menu with the gadget as a popup.

2007 AVEVA Solutions Ltd

2:81

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name RemovePopup(MENU menu) GetPickedPopup() Refresh() Shown() Type() SetToolTip(STRING) SetFocus() SetHeadings(!Dtexts is STRING)

Result

Purpose

NO RESULT Removes popup menu from the gadget. MENU Returns the last picked popup menu for the gadget.

NO RESULT Refreshes the display of the gadget. BOOLEAN STRING Get shown status. Get the gadget type as a STRING.

NO RESULT Allows a TOOLTIP to be edited. NO RESULT Move keyboard focus to this gadget. NONE Specifies the number of columns and sets the list's column headings. Dtexts contains a set of TAB separated sub-strings. Specifies the number of columns and sets the list's column headings. Dtexts is an array of strings.

SetHeadings(!Dtexts is ARRAY)

NONE

Clear( !dtext ) Clear( !fieldNumber ) SetRows(Array of (Array of STRING))

NO RESULT Delete the field with the given DTEXT string. NO RESULT Delete the specified field number. NO RESULT This sets the display text for all the data fields of the list gadget by row. If the list gadget is already populated then it replaces all the current rows by the new ones. Array is an array of row arrays, and its size determines the number of rows in the list. Each entry is a row array of strings, which supplies the displayed text for each column of the row. The size of each row array must be less than or equal to the number of columns of the list. The columns are filled sequentially until the array is exhausted.

2007 AVEVA Solutions Ltd

2:82

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name SetColumns(Array of (Array of STRING))

Result

Purpose

NO RESULT This sets the display text for all the data fields of the list gadget by column. If the list gadget is already populated then it replaces all the current rows by the new ones. Array is an array of column arrays, and its size must match the number of columns of the list. The size of each all column arrays must be the same and determines the no of rows in the list. NO RESULT This selects the first list row whose column column has the display text dtext. If the field is not found then the list selection is unaltered. If the list is a multi-choice list then repeated use of this method will add selections to the list. STRING Get Background Name. Colour

Select(REAL column, STRING dtext)

Background()

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
Table 2: 56. LIST Object Methods

Column Headings
The number of columns is deduced from the List's data. If the user specifies a set of (1 or more) column headings before the list is populated, then this will determine the number of columns. If no headings are pre-specified then the number of columns is deduced from the display text (Dtext) of the List's first data field. This provides upwards compatibility for existing Appware using single column lists. A List gadget's headings can be replaced after the list has been populated. If the new headings specify the same number of columns then the headings are replaced but the List's data fields and selection remain unchanged. If the number of columns is different, then the list is replaced by an empty list with the new headings. Invoking the Clear() method will clear the list's data fields and rebuild the current headings. There are two methods for defining a List's column headings:

2007 AVEVA Solutions Ltd

2:83

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

The data fields can be set using the List's DTEXT member or its Add methods, where a row's Dtext string can be a set of TAB separated column sub-strings for populating multiple columns. Alternatively you can use the SetRows or SetColumns methods.

Single choice lists

Reselection of the Selected Field can be Disallowed For Single choice lists there is a keyword NORESELECT which disables UnSelect and Select events when the currently selected field is clicked with the mouse, for example: list .l1 |List gadget| zeroSel noReselect width 15 length 5 tooltip 'single choice list'

De-selection of the selected field for ZeroSelection lists For ZeroSelection lists it is possible to interactively deselect the selected field by clicking in unused rows or after the last column. The val member now allows programmatic de-selection of the current field.

Unselect Events Single choice List gadgets support UNSELECT events. Typically when a field is selected, an UNSELECT event is raised for the previously selected field (if any) and then a SELECT event is raised for the new field. An UNSELECT event is raised whenever a selected field is interactively deselected. Notes: 1. UNSELECT events are not notified to PML unless an open callback has been specified (so that SELECT and UNSELECT events can be differentiated). 2. Typically the UNSELECT action allows Appware to manage consequences of deselection for any dependent gadgets or forms. 3. We recommend that you do not change the List's selection programmatically in an UNSELECT event.

Command
The LIST command defines a single-choice or multiple-choice list gadget, and specifies its position, tag, number of columns and callback text. Also defines the area (width and height) in which the displayed part of the list will appear. The arrays defining the display texts and replacement texts for the list options are usually set in the form's default constructor method.

2007 AVEVA Solutions Ltd

2:84

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

.-------<--------. / | >- <flist> - LIST gname -+- <fgtagw> ------| +- <fgpos> -------| +- <fganch> ------| +- <fgdock> ------| +- CALLback text -| +- TOOLTIP text --| +- CORE ----------* Core managed gadget | +- MULTiple --------. | .-------<-------. | |/ | | +- NORESELect ----| | +- ZEROSELection -* | -------------------- <vshap> +- TOOLTIP text -. ----------------->

Figure 2:35. Syntax Graph -: Setting-up a LIST Object

Note: The TOOLTIP keyword can be given at two different places in the syntax.

Default:

A single choice, mandatory selection list.

2.5.31

LOCATION Object
Members

Name Name Description Locid Refno IsCurrent

Table 2: 57. LOCATION Object members

Type STRING STRING STRING STRING BOOLEAN

Purpose Location name. Description, up to 120 characters. Location identifier. STRING containing Database reference no. True for the current Location.

2007 AVEVA Solutions Ltd

2:85

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name LOCATION(DBREF) LOCATION(STRING)

Result LOCATION LOCATION

Purpose Returns a LOCATION object, given a DBREF. Returns a LOCATION object, given a name or reference number (Global projects only).

Dblist()

ARRAY OF Array of DB objects for DB Allocated DBs. This method does not modify the original object. ARRAY OF Return array of all Sessions SESSIONS extracted from COMMs db at the Location. This method does not modify the original object. STRING STRING containing Location name. This method does not modify the original object.

Sessions()

String()

Table 2: 58.

LOCATION Object Methods

Note: The Sessions() method provides information required for remote expunging. This method will cause daemon activity for locations other than the current location. You can use the constructors in the following ways:

!D = OBJECT LOCATION(!!CE) !D = OBJECT LOCATION(!!CE.Name) !D = !!CE.LOCATION()!D = !!CE.Name.LOCATION()

In all cases, !!CE is assumed to be a DB database element and !!CE.Name is a STRING object containing the elements name. These methods should assist performance improvements to AppWare by making it easier to get from Database element to Object.

2007 AVEVA Solutions Ltd

2:86

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.32

MACRO Object
Member

Name Filename From Number To

Type STRING DB REAL DB

Purpose Inter-DB macro filename (up to 17 characters). Source DB of connection macro. inter-DB

Inter-DB macro number. Target DB of connection macro. inter-DB

Table 2: 59.

MACRO Object Members

Command

!ARRAY = MACROS

$ Returns an array of all the MACRO objects in $ the project

2.5.33

MDB Object
Member

Name Name Description Refno

Type STRING STRING STRING

Purpose Name of the MDB, up to 32 characters MDB description, up to 120 characters String containing Database reference number

Figure 2:36. MDB Object Members

2007 AVEVA Solutions Ltd

2:87

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods
None of these methods modifies the original object. Name MDB(DBREF) MDB(STRING) Result MDB MDB Purpose Returns an MDB given a DBREF. object,

Returns an MDB object, given a name or reference number. an

Current() Deferred() Mode()

ARRAY OF Current databases as DBS array of DB objects

ARRAY OF Deferred databases as an DBS array of DB objects ARRAY OF Returns NR or RW for each STRINGS current DB of the MDB

Table 2: 60.

MDB Object Methods

You can use the constructors in the following ways:

!D = OBJECT MDB(!!CE) !D = OBJECT MDB(!!CE Name !D = !!CE.MDB() !D = !!CE.Name.MDB()

In all cases, !!CE is assumed to be a DB database element and !!CE.Name is a STRING object containing the elements name. These methods should assist performance improvements to AppWare by making it easier to get from Database element to Object.

Command

!ARRAY= MDBS

$ Returns an array of MDB objects in the project

2007 AVEVA Solutions Ltd

2:88

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.34

MENU Object
Members

Name Callback

Type STRING Get/Set

Purpose Sets/gets the callback on the menu. Returns the DTEXT of the last picked menu field. Using this member is now deprecated. Use the PickedFieldName property instead.

PickedField

STRING Get Only

PickedFieldName

STRING Get Only

Returns the field name of the last-picked TOGGLE or CALLBACK field.

Table 2: 61.

MENU Object Members

Methods

Name Add('SEPARATOR', {STRING fieldName})

Result

Purpose

NO RESULT Append a SEPARATOR field, with an optional STRING argument, fieldName, that if present denotes the unique field-name in the menu. NO RESULT Append a CALLBACK field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. The argument callback gives the callback command. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

Add('CALLBACK', STRING Dtext, STRING callback, {STRING fieldName})

2007 AVEVA Solutions Ltd

2:89

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Add('FORM', STRING Dtext, STRING formName, {STRING fieldName})

Result

Purpose

NO RESULT Append a FORM display field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. The argument formName, gives the name of the form to be displayed, which may be NULL but may not be blank. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu

Add('MENU', STRING DText, STRING menuName, {STRING fieldName})

NO RESULT Append a MENU (pullright) field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. menuName gives the pullright menu name, which may be NULL but may not be blank. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

Add('TOGGLE', STRING Dtext, STRING callback, {STRING fieldName})

NO RESULT Append a TOGGLE field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. The argument callback gives the callback command, which must be an open PML function. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

Clear()

NO RESULT Removes all menu fields from the menu. Using this deprecated. method is

2007 AVEVA Solutions Ltd

2:90

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Clear(STRING Dtext)

Result

Purpose

NO RESULT Removes menu fields starting with the one that matches Dtext onwards. Using this deprecated method is

FieldProperty(STRING menuField, STRING property)

BOOLEAN

Get the value of the property named in property for the menu field named in menuField. The allowed values for property are ACTIVE, VISIBLE, or SELECTED.

FullName()

STRING

Returns menu object's full name, for example: !!Form.Menu.

InsertAfter(STRING menuField, CALLBACK, STRING Dtext, STRING callback, {STRING fieldName})

NO RESULT Insert a CALLBACK field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument callback gives the callback command. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

InsertAfter(STRING menuField, FORM, STRING Dtext, STRING formName, {STRING fieldName})

NO RESULT Insert a FORM display field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument formName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

2007 AVEVA Solutions Ltd

2:91

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name InsertAfter(STRING menuField, MENU, STRING Dtext, STRING menuName, {STRING fieldName})

Result

Purpose

NO RESULT Insert a MENU (pullright) field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument menuName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

InsertAfter(STRING menuField, TOGGLE, STRING Dtext, STRING menuName, {STRING fieldName})

NO RESULT Append TOGGLE field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument callback gives the callback command, which must be an open PML function. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

InsertAfter(STRING menuField, SEPARATOR, {STRING fieldName})

NO RESULT Append a SEPARATOR field immediately after the menu field identified by menuField. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

2007 AVEVA Solutions Ltd

2:92

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name InsertBefore(STRING menuField, CALLBACK, STRING Dtext, STRING callback, {STRING fieldName})

Result

Purpose

NO RESULT Insert a CALLBACK field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument callback gives the callback command. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

InsertBefore(STRING menuField, FORM, STRING Dtext, STRING formName, {STRING fieldName})

NO RESULT Insert a FORM display field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument formName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

InsertBefore(STRING menuField, MENU, STRING Dtext, STRING menuName, {STRING fieldName})

NO RESULT Insert a MENU (pullright) field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument menuName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

2007 AVEVA Solutions Ltd

2:93

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name InsertBefore(STRING menuField, TOGGLE, STRING Dtext, STRING menuName, {STRING fieldName})

Result

Purpose

NO RESULT Append TOGGLE field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument callback gives the callback command, which must be an open PML function. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

InsertBefore(STRING menField, SEPARATOR, {STRING fieldName})

NO RESULT Append a SEPARATOR field immediately before the menu field identified by menuField. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu.

Name()

STRING

Returns menu object's simple name, for example: 'Menu'. Returns reference to owning form. Returns the name of the gadget that popped up the menu. The value is unset if the menu was not popped up by a gadget.

Owner() PopupGadget()

FORM GADGET

Refresh() Select(STRING Dtext, BOOLEAN status)

NO RESULT Refreshes the display of the gadget. NO RESULT Set the selected status of TOGGLE field identified by Dtext to the value of status. Using this deprecated. method is

Selected( STRING Dtext )

BOOLEAN

Get selected status of the TOGGLE field identified by Dtext. Using this deprecated. method is

2007 AVEVA Solutions Ltd

2:94

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name SetActive(STRING Dtext, BOOLEAN active)

Result

Purpose

NO RESULT Set the active status of the menu field identified by Dtext. Using this deprecated. method is

SetFieldProperty(STRING menuField , STRING property, BOOLEAN value)

NO RESULT Set the value of property with value, for the menu field identified by menuField. The allowed values for property are ACTIVE, VISIBLE, or SELECTED. But see the note below for special cases when you use a SEPARATOR field.

Table 2: 62.

MENU Object Methods

Note: Setting the Active and Visible properties of a SEPARATOR field will affect the implied group of fields comprising the SEPARATOR field and all subsequent fields up to but not including the next SEPARATOR field. For each of the Add() methods above, you can use a special field-type to indicate that the field is managed by core-code i.e. CORESEPARATOR, CORECALLBACK, COREFORM, COREMENU, and CORETOGGLE. You do not need to specify callback functions for core-managed fields.

Command
MENU objects are owned by FORM objects, and can be created within form setup mode. It is also possible to add a new menu to an existing form - usually for context sensitive popup menus. The recommended way to create a menu and its fields, typically within form setup mode, is:

!menu = !this.newmenu( Menu1, MAIN )

!menu.add( CALLBACK, save, <callback>, field1 ) !menu.add( FORM, save as, saveForm, field2 )

Note:
Each menu is either part of the Main menu system or part of the Popup menu system, but cannot belong to both. If you specify neither POPUP nor MAIN at setup time, then the menus usage is initially unknown. The system will attempt to deduce the usage type from the first action that references the menu. Menus in the Main system can only appear once. That is, a main system menu cannot be a sub-menu of several menus. Menus in the Popup system may appear only once in a given popup tree, but may be used in any number of popup trees. A menu cannot reference itself, either directly as a pullright of one of its own fields or be a pullright of another menu in its own menu tree.

2007 AVEVA Solutions Ltd

2:95

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

You can add menu fields with an optional field-name. If you do not specify a fieldname, then you will not be able to refer to it later. You can use a special field-type to indicate that the field is managed by core-code i.e. CORESEPARATOR, CORECALLBACK, COREFORM, COREMENU, and CORETOGGLE. You do not need to specify callback functions for core-managed fields.

An alternative is to use the MENU command, followed by the menus ADD commands and terminated by the EXIT command. The full syntax is shown below:
>-- MENU -- gname -+- POPUP --. .--------<-------. +- MAIN --| / | -----------+- NL -+- <fmenu> -| +- PML -----* +- EXIT ----. -------------> Figure 2:37. Syntax Graph -: Defining a Menu .-----<-----. | fieldname -| CORE ------* SEParator -------------------------------. dtext -+- rtext -------------------------| +- MENU -- gname -----------------| +- FORM -- fname -----------------| +- CALLback -+- rtext ------------| | --------------------| - TOGgle -+- rtext -. | ---------+- SELected -| --------------> Figure 2:38. Syntax Graph -: Using Menu,Add()

/ fmenu>-+- ADD -+++-

2.5.35

NUMERICINPUT Object
Members

Member val range ndp modifiedEvents editable

Table 2: 63.

Type REALGet/Set REAL ARRAYGet/Set REALReadonly BOOLEANGet/Set BOOLEANGet/Set

NUMERICINPUT Object Members

Purpose Value of the numeric input. Gets adjusted to the nearest value in the range. Range: Start, End and Step(>0) as reals. Integer number of decimal places to be displayed. 0 means integer values. Enable/disable modified events. Enable/disable editing of the displayed value.

2007 AVEVA Solutions Ltd

2:96

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Method Name

Result

Purpose Set the range and number of decimal places. !range is an array of REAL, defining the min, max and step (>0) values. !NDP<0 leaves the current value unchanged.

setRange( !range, !ndp ) NO RESULT

Table 2: 64.

NUMERICINPUT Object Methods

Command
The NumericInput gadget allows numeric input within a specified range, with given granularity. The Up/Down arrows control incrementing and decrementing the displayed value by the specified increment, within the range. Additionally it is possible to type in the required value. The number of decimal places can also be specified.
.-------<-------------------. / | -- NUMERICinput gname -+- <fgtagw> ------------------| +- <fgpos> -------------------| +- <fganch> ------------------| +- <fgdock> ------------------| +- CALLback text -------------| +- TOOLTIP text --------------| +- CORE ----------------------* Core managed gadget | .-------<-------------------. |/ | +- RANGE val val -------------| +- STEP val ------------------| +- NDP int -------------------* | +- VALUE val -. '-------------'- <vwid> -+- TOOLTIP text -. '--------------'-->

Notes: 1. The tag text is displayed. 2. Default initial value is the minimum value of the range. 3. The range maximum is adjusted to be an integral number of steps. 4. NDP is the number of decimal places. If NDP is zero then all values will be integer. 5. Typed in values will be adjusted to the nearest valid value in the range. 6. The graph <vwid> allows the gadget width to be set specifically or in terms of other gadgets on the form. 7. It is not possible to provide user formatting of the values displayed by the gadget. Events and Callbacks The Numeric input gadget supports SELECT and MODIFIED events, and users may provide a callback method to service these events. Note that often no callback is required, and the numeric input value is merely read and used by other gadgets of the form.

2007 AVEVA Solutions Ltd

2:97

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

A SELECT event is raised whenever the user presses the ENTER key while the numeric input display field has focus. Typically this happens after the user has typed in a required value, but will also apply if the user enters the field after modifying the values using the up/ down arrows. The callback can be a simple or an open callback. A MODIFIED event is raised for each modification of the displayed value using the up/down arrows. Modified events are only reported if they are enabled and the user has provided a PML open callback, as this allows differentiation from the SELECT events. The default state is modified events disabled.

2.5.36

Multi Discipline Route Manager

mdrRoutePoint

Name OwningDbBranch

Returns DBREF

Arguments

Description Returns owner branch element of this route point. Returns mdrRoute

Remarks

OwningRoute

mdrRoute

owning Redundant? - could be constructed easily from OwningDbBranch

IsEqual

bool

mdrRoutePoint

Returns true if Checks first if the objects are equal objects could be compared by under lying DB element. If not the position On is used Expands external geometry to mdrRoute object. Returns true if its an external geometry object.

ExpandToRoute

mdrRoute

IsExternalGeometry bool

EndingRoutePoint

mdrRoutePoint

Sets end external Valid only if this is a geometry ending external geometry type route point. route point Gets end external Valid only if this is a geometry ending external geometry type route point. route point

EndingRoutePoint

mdrRoute Point mdrRoutePoint

StartingRoutePoint

Sets end external Valid only if this is a geometry starting external geometry type route point. route point Gets end external Valid only if this is a geometry starting external geometry type route point. route point

StartingRoutePoint

mdrRoute Point

2007 AVEVA Solutions Ltd

2:98

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Position

Position

Gets position of the Valid only if this isn't an route point in world external geometry type coordinates. route point. If there is DB element owned then gets the world position, otherwise its stored as world position inside an object Position Sets position of the Valid only if this isn't an route point in world external geometry type coordinates. route point. If there is DB element owned then sets the local position, converting it before from world coordinates, otherwise sets the world position inside an object Get the fillet radius of route point Real Set the fillet radius Valid only if this isn't an of route point external geometry type route point. If there is DB element owned then sets the filet radius, otherwise sets the radius inside the object Returns object cloned Clones all the attributes taken from object which from this method is invoked (besides underlying DB element, and name)

Position

Radius Radius

Real

Clone

mdrRoute Point

Name Is That

String String type

Gets the name of named route point Returns true if the Compares if the type is named types the same with passed as match argument. Gets the type of route point object String type Sets the type of behaviour not specified route point object Gets the underlying DB element. Check if element is enables. Checks if element is named true if route point true if route point are on are on the same the same position position

Type Type DbElement IsEnabled IsNamed IsOn

String

DBREF bool

2007 AVEVA Solutions Ltd

2:99

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

DbElement Enable

DBREF bool enabled

Sets owned element. Enables disables point.

DB or enable true if we want to route enable route point otherwise false

mdrRoute

Name dbWrite

Returns bool

Arguments DBREF

Description

Remarks

Writes to DB Returns true if write hierarchy. was successful Argument specify where to method should write to. Updates hierarchy. Returns object DB Returns true if write was successful cloned Clones all the attributes taken from object which from this method is invoked (besides underlying DB element, and name)

dbUpdate clone

bool mdrRoute

DbElement DbElement Construct Equals HeadRoutePoint TailRoutePoint HeadRoutePoint TailRoutePoint InsertRoutePointAt Head InsertRoutePointAtT ail InsertRoutePoint

DBREF DBREF DBREF Bool mdrRoute Point mdrRoute Point mdrRoutePoint mdrRoutePoint mdrRoutePoint mdrRoutePoint mdrRoutePoint

Gets the underlying DB element. Sets the underlying Method element. ownership Constructs route point from DB Checks for equality of elements Gets head point route changes

Gets tail route point Sets head point route

Sets tail route point Inserts route point at head Inserts route point at tail Insert route points at chosen index

2007 AVEVA Solutions Ltd

2:100

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

RemoveRoutePoint FindRoutePoint

mdrRoutePoint mdrRoutePoint

Remove route point from route Gets route index of route point (0 based)

RoutePoints InsertRouteAtHead InsertRouteAtTail insert Route ExpandToRoute ExpandRoutePoint size at SubRoute mdrRoute real mdrRoute Point mdrRoute

Array of Gets route points mdrRoutePoint mdrRoute mdrRoute mdrRoute, mdrRoutePoint Merge two routes on head Appends route at end Inserts route route point at

Expands all the ext geom. into route mdrRoutePoint In place expand of ext geom. number of route points in route real mdrRoutePoint, mdrRoutePoint mdrRoutePoint Route Point at Cuts the route between two route points Creates sub route from head to route point Creates sub route from route point to tail Transforms route Calculates length mdrRoutePoint, mdrRoutePoint route

HeadSubRoute

mdrRoute

TailSubroute

mdrRoute

mdrRoutePoint

Transform Length Length Length From Real Real Real

Orientation

Length between two route points Length from route point

mdrBaseManager

Name CreateRoutePoint

Returns mdrRoute Point

Arguments Position

Description Route point from pos

Remarks

2007 AVEVA Solutions Ltd

2:101

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

CreateRoutePoint CreateRoutePoint FindRoute

mdrRoute Point DBREF

DBREF

Route Point from dbref Route from dbref For given connection graph, and two RoutePoints, find the best path between these route points Enter Route point model editor for given route Enter Quick Routing model editor for given route

Array of mdrConnection mdrConec Graph, tionPoint mdrRoutePoint, mdrRoutePoint

BeginInteractiveRo utePointsEditing BeginInteractiveQui ckRouting

mdrRoute

mdrRoute

mdrConnectionManager

Name CreateRouteFrom ConnectionPoints

Returns mdrRoute

Arguments

Description

Remarks

Array of For given path mdrConnection described by Points connection points array create route For given owner, create connection graph of For given array of dbrefs, create a connection graph of Connect list of branches base on their positions Connect owning branches element baser on their pos Connected from atta attas

CreateConnection mdrConnect DBREF GraphFromOwner ionGraph CreateConnection mdrRoute GraphFromBranc hes CreateConnection ByGeometryFrom branches CreateConnection sByGeometryFro mOnwer GetConnectedAtt asToAtta ARRAY DBREF Array DBREF Array DBREF DBRF

of DBREF

2007 AVEVA Solutions Ltd

2:102

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

mdrConnectionGraph

Name

Returns

Arguments

Description For given route point return connection point Get connection point list

Remarks

GetConnectionPoint mdrConnect mdrRoutePoint ionPoint GetAllConnectionPo Array of ints mdrConnect ionPoints

mdrConnectionPoint

Name getRoutePoint

Returns mdrRoute Point

Arguments

Description Get route point Get connected route point 0- head, 1- tail, 2mid, 3- free, 4none 0- head, 1- tail, 2mid, 3- free, 4none

Remarks

getConnectedRoute mdrRoute Point Point getFirstConnection Type getSecondConnecti onType Real

Real

2.5.37

OBJECT
Method

Name GetPathName()

Result STRING

Purpose Extracts the pathname for a file in the PMLLIB searchpath.

Table 2: 65.

PML Object Methods

2007 AVEVA Solutions Ltd

2:103

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.38

OPTION Gadget
Members

Name DText

Type ARRAY OF STRING Get/Set STRING Get Only ARRAY OF STRING Get/Set STRING Get Only BOOLEAN Get/Set INTEGER Get/Set

Purpose Set or get the entire list of display texts. Get the display text of the n'th option. Set or get the replacement texts. list of

DText[n] RText

RText[n]

Get the replacement text of the n'th option. Controls editable status of the text display field (ComboBox only) Controls the maximum length of a text string which can be held and scolled in the display text field (ComboBox only) Get count of number of fields in the list. Selected field as integer. Zero implies no selection. Setting val to zero will cause an error if ZeroSel is not specified.

Editable

Scroll

Count Val

REAL Get only REAL Get/Set

Table 2: 66.

OPTION Object Members

2007 AVEVA Solutions Ltd

2:104

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Add(STRING Dtext)

Result

Purpose

NO RESULT Append an entry to the drop down list, where Dtext is the text to display in the option list. NO RESULT Append and entry to the drop down list, where Dtext is the text to display in the option list, and Rtext is the replacement text for the new field. If Rtext isnt specified, it will be set to Dtext by default. NO RESULT Clear gadgets contents. NO RESULT Clears selection and returns to default of first in list. STRING STRING FORM Get the full gadget name, e.g.'!!Form.gadget' Get the gadget's name, e.g. 'gadget' Get owning form.

Add(STRING Dtext, STRING Rtext))

Clear() ClearSelection() FullName() Name() Owner() Select(STRING text, STRING value )

NO RESULT Select specified item in a list: text must be Rtext or Dtext, and value is the item to be selected. STRING STRING Get current RTEXT. selections

Selection() Selection(STRING text )

Get RTEXT or DTEXT of current selection; text must be Rtext or Dtext.

SetPopup(MENU menu) Refresh() SetFocus() RemovePopup(MENU menu) GetPickedPopup() Shown()

NO RESULT Links menu with the gadget as a popup. NOT RESULT Refreshes the display of the gadget.

NO RESULT Move keyboard focus to this gadget. NO RESULT Removes (popup) from the gadget. MENU BOOLEAN menu

Returns the last picked popup menu for the gadget. Get shown status.

2007 AVEVA Solutions Ltd

2:105

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Type() Background()

Result STRING STRING

Purpose Get the gadget type as a string. Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised.. DisplayText( ) STRING Gets the text string currently displayed in the Option gadget's display field.

SetPopup(

!menu )

NO RESULT Assigns a menu object as the gadget's current popup. NO RESULT Delete the field with the given DTEXT string. NO RESULT Delete the specified field number.

Clear( !dtext ) Clear( !fieldNumber )

Table 2: 67.

OPTION Object Methods

Command
The OPTION command defines an option gadget and specifies the position, tag or pixmap, and callback text of the option (or list button) gadget. Also sets the width allowed for displaying the list options when the gadget is selected. The arrays defining the display texts and replacement texts for the gadget should be set in the form's default constructor method. Notes: 1. Option gadget's display text field is non editable, so doesn't need scroll width (syntax is infact in place for backwards compatibility).

2007 AVEVA Solutions Ltd

2:106

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

.-------<-------. / | >------ OPTion gname -+- <fgtagw> ------| +- <fgpos> -------| +- <fganch> ------| +- <fgdock> ------| +- CALLback text -| +- TOOLTIP text --| +- NORESELect ----| +- ZEROSELection -| +- CORE ----------* Core managed gadget | +- PIXmap <vshap> -. '- <vwid> ---------+- TOOLTIP text -. '----------------'--> Figure 2:39. Syntax Graph -: Setting Up an OPTION Object

Reselection of the Selected Field can be Disallowed There is a new keyword NORESELECT which disables UNSELECT and SELECT events when the currently selected field is re-clicked with the mouse, for example: option .o1 tagwid $!w |Choose| noResel width 5 tooltip 'select option'

ZeroSelection Property Option gadgets have a ZeroSelection keyword (similar to that of single choice lists), which allows it to support the notion of no current selection (previously a selection was mandatory). The syntax has been extended with the optional 'ZEROSELection' keyword, e.g. option .choose tagWid 3 |Cars| . . . zeroSel noResel width 25 length 10

Behaviour
Note: It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.

Unselected Events Option gadgets support UNSELECT events. Typically when a field in the dropdown list is selected, an UNSELECT event is raised for the previously selected field (if any) and then a SELECT event is raised for the new field. Notes: 1. UNSELECT events are not notified to PML unless an open callback has been specified (so that SELECT and UNSELECT events can be differentiated). 2. Typically the UNSELECT action allows Appware to manage consequences of deselection for any dependent gadgets or forms. 3. We recommend that you do not change the option gadget's selection programmatically in an UNSELECT event.

2007 AVEVA Solutions Ltd

2:107

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.39

ORIENTATION Object
Members

Name Alpha Beta Gamma Origin

Type REAL Get/Set REAL Get/Set REAL Get/Set DBREF Get/Set

ORIENTATION Object Members

Purpose The Alpha component. The Beta component. The Gamma component. The DB element which is the origin.

Table 2: 68.

Methods
None of these methods modifies the original object. Name Orientation( STRING) Orientation( STRING, FORMAT ) Result Purpose

ORIENTATION Creates an ORIENTATION from the values given. ORIENTATION Creates an ORIENTATION from the values given, in the specified FORMAT. BOOLEAN BOOLEAN STRING TRUE if ORIENTATIONS are equal. TRUE if ORIENTATION is less than argument. Convert ORIENTATION to a STRING.

EQ(ORIENTATION) LT(ORIENTATION) String(FORMAT) WRT(DBREF)

ORIENTATION Convert to a new ORIENTATION with respect to given DB element. DIRECTION DIRECTION DIRECTION Return X component as a DIRECTION. Return Y component as a DIRECTION. Return Z component as a DIRECTION

XDir() YDir() ZDir()

Table 2: 69.

ORIENTATION Object Methods

2007 AVEVA Solutions Ltd

2:108

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.40

PARAGRAPH Gadget
Members

Name Val

Type STRING Get/Set

Purpose The paragraph's content as a string. textual

If it has a pixmap then the value will be the pathname of the pixmap file as a string. Background Background REAL Get/Set STRING Get/Set Set or get Background Colour Number. Set Background Name. Colour

Table 2: 70.

PARAGPRAPH Object Members

Methods

Name AddPixmap(STRING) AddPixmap(STRING, STRING) AddPixmap(STRING, STRING, STRING) FullName() Name() Owner() SetPopup (MENU) RemovePopup(MENU) GetPickedPopup() Shown()

Result

Purpose

NO RESULT Adds pixmaps to be used for the unselected, selected and inactive states. STRING STRING FORM Get the full gadget name, e.g.'!!Form.gadget'. Get the gadget's name, e.g. 'gadget'. Get owning form.

NO RESULT Links the given menu with the gadget as a popup. NO RESULT Removes the given popup menu from the gadget. MENU BOOLEAN Returns the last picked popup menu for the gadget. Get shown status.

2007 AVEVA Solutions Ltd

2:109

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Type() Background()

Result STRING STRING

Purpose Get the GADGET type as a string. Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
Table 2: 71. PARAGPRAPH Object Methods

Command
The PARAGRAPH command defines a paragraph and specifies its position, dimensions (in units of character widths and line heights), and, optionally tag text or a pixmap. Note that a paragraph gadget is passive so it s callback is never used. A paragraph gadget can have a tag, but it is not displayed. You can define the PARAGRAPH to be either PML-controlled, or core-code controlled using the gadget qualifier attribute control type, with values PML or CORE.
.--------------------<------------. / | >-- PARAgraph gname -+-- <fgpos> ------------------------| +-- BACKGround <colno> -------------| +-- <fganch> -----------------------| +-- <fgdock> -----------------------| +-- CORE --------------------------* Core managed gadget +- PIXMAP -+- filename -. | -------------<vshap>--> - TEXT text -+-<vshap>-. -----------> Figure 2:40. Syntax Graph -: Setting Up a PARAGRAPH Object

Note:
If a paragraph is to contain text, then its shape will be specified in grid units. The height is the number of lines of text and the width is typically thought of as the number characters required. This may be less that the actual string length, because the grid width is the size of the font notional character width, which is typically smaller than the largest characters in the font. You may need to specify a few extra grid units to guarantee to fit variable strings. If a paragraph contains text, and no dimensions are specified, the result is a single line of width (in grid units) equal to the number of text characters. This may not be long enough to guarantee to fit the specific string, so you may nee to pad out with extra spaces to avoid truncation.

2007 AVEVA Solutions Ltd

2:110

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

If your paragraph is to contain more than one line of text, you must specify a suitable shape. The text, which can contain newline characters, will be justified in the area given. If a pixmap is specified, the shape of the gadget must be defined and will be in pixels. Remember to define the pixmap using the paragraph's AddPixmap() method or its .Val member. If the paragraph is to have its contents modified then the text or pixmap file would normally be specified in the form's default constructor method, rather than in the gadget definition. It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.

2.5.41

PLANE Object
Members

Name Orientation Position

Type ORIENTATI ON Get/Set POSITION Get/Set

PLANE Object Members

Purpose Orientation of plane. Origin of plane.

Table 2: 72.

Definition Methods
None of these methods modifies the original object. Name Plane(POSITION, ORIENTATION) Result PLANE Purpose Creates a PLANE with the given POSITION and ORIENTATION. Returns the plane as a string.

String() Direction(DIRECTION)

STRING

DIRECTION Z component of the orientation uses standard PDMS method of maintaining X and Y components of the orientation. NO RESULT Modifies the direction (Z component of the orientation) member of the plane so it is directed to the position.

Towards(POSITION)

Table 2: 73.

PLANE Object Definition Methods

2007 AVEVA Solutions Ltd

2:111

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Towards(POSITION)

Orientation Direction(DIRECTION) Z Y

Position

Figure 2:41. PLANE Object Definition

PLANE Object: Methods that Return POSITIONs

Name Intersection(LINE)

Result POSITION

Purpose Returns the intersection point of the passed infinite line on the plane definition. Returns the intersection point of the passed point vector on the plane definition.

Intersection(POINT VECTOR) Intersections(ARC)

POSITION

ARRAY OF Returns the intersection point POSITIONS of the passed arc on the plane definition. POSITION POINTVECTOR Returns intersection position of the three planes. Returns a point vector at the origin of the plane with a direction equal to the normal of the plane. Returns 3D position of the XYPOSITION offset from the plane origin. Returns the nearest position on the plane definition of the passed position.

Intersection(PLANE, PLANE) PointVector()

ThreeDPosition(XYPOSITION)

POSITION

Near(POSITION)

POSITION

Table 2: 74.

PLANE Object Methods that Return POSITIONs

2007 AVEVA Solutions Ltd

2:112

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Intersection(LINE)

Intersection(PLANE, PLANE)

ThreeDPosition(XYPOSITION)
Figure 2:42. POSITIONs returned by PLANE Object Methods

Near(POSITION)

PLANE Object: Methods that Return LINEs

Name Line(REAL)

Result LINE

Purpose Returns a line of the given length in the direction of the plane normal. Returns the intersection line of the passed plane on the plane definition. The start position of the line is the origin of the plane definition projected onto the passed plane. The direction of the line is from the start to the position of the passed plane projected onto the reference plane. If the start and end points are coincident, a line of length 1000mm is returned with the start position being defined as described above.

Intersection(PLANE)

LINE

Table 2: 75.

PLANE Object Methods that Return LINEs

2007 AVEVA Solutions Ltd

2:113

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Intersection(PLANE)

Figure 2:43. LINEs Returned from PLANE Object Methods

PLANE Object: Methods that Return XYOffsets

Name XYOffset(Position)

Result XYPOSITIO N

Purpose Returns the position, mapped onto the plane, in term of an XY offset from the plane origin.

Figure 2:44. PLANE Object Methods that Return XYOffsets

XYOffset(POSITION)
Figure 2:45. XYPositions Returned from PLANE Object Methods

2007 AVEVA Solutions Ltd

2:114

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.42

PLANTGRID Object
Members

Name Position Orientation XSpacings

Type POSITION Get/Set

Purpose Origin of the grid.

ORIENTATION Orientation of the grid. Get/Set REAL ARRAY Get/Set REAL ARRAY Get/Set Array of spaces in the X direction, each space is relative to the previous. Array of spaces in the Y direction, each space is relative to the previous.

YSpacings

Table 2: 76.

PLANTGRID Object Members

Methods
None of these methods modifies the original object. Name Plantgrid(POSITION, ORIENTATION, ARRAY, ARRAY ) Result PLANTGRID Purpose Creates a grid with the given POSITION and ORIENTATION, and the X and Y spacings specified in the arrays. Maximum direction. Maximum direction. size size in in the the X Y

Xsize() Ysize() OutofBounds(POSITION)

REAL REAL BOOLEAN

Returns whether point lies within the grid boundaries.

Table 2: 77.

PLANTGRID Object Methods

2007 AVEVA Solutions Ltd

2:115

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Orientation Position Z

Ysize()

YSpacing

XSpacing X

Xsize()

Figure 2:46. Return Values from PLANTGRID Object Methods

2.5.43

PLATFORMGRID
The PLATFORMGRID object is used for filling PLTFRM element with certain grid pattern. Name Result NO RESULT Purpose Copies content of a PLATFORMGRID object into current instance Returns the angle value used grid

ASSIGN(PLATFORMGRID)

GRIDANGLE() GRIDANGLE(REAL) GRIDPOINT(REAL1, REAL2)

REAL NO RESULT NO RESULT

Sets grid angle value Returns position of the intersection of gridlines: X (identified by given index REAL1) and Y (identified by given index -REAL2) Returns the grid's origin Returns the grid's spacing pattern along X axe Sets the grid's spacing pattern along X axe Returns position of grid's origin Sets the position of grid Returns the size of rectangle which contains the grid Returns the grid's spacing pattern along Y axe Sets the grid's spacing pattern along Y axe

GRIDPOSITION() GRIDXSPACINGS() GRIDXSPACINGS(ARRAY) GRIDXYPOSITION() GRIDXYPOSITION(XYPOSITION) GRIDXYSIZE()

POSITION ARRAY NO RESULT XYPOSITION NO RESULT REAL ARRAY

GRIDYSPACINGS() GRIDYSPACINGS(ARRAY)

REAL ARRAY NO RESULT

2007 AVEVA Solutions Ltd

2:116

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

GROSSAREA() NETAREA() ORIENTATION() ORIENTATION(ORIENTATION) PLANE()

REAL REAL ORIENTATION NO RESULT PLANE

Returns the gross area of the grid Returns the net area of the grid Returns the orientation platform's

Sets the platform's orientation for given value Return the plane definition of platform grid. This is equivalent of PLANE method on PROFILE object a platformgrid

PLATFORMGRID() PLATFORMGRID(DBREF)

PLATFORMGRID Create object.

PLATFORMGRID Creates a platformgrid from DBREF. DBREF must be PLTGRD or INTFRM element. The outer boundary is created from owning PLTFRM routing path (RPATH). Inner boundaries are created from PLOPEN elements POSITION NO RESULT ARRAY Returns position of the platform Sets the grid's position Returns the size of rectangle (limits) which contains the grid in platform coordinate system

POSITION() POSITION(POSITION) XYSIZE()

Methods that are performing operations on grid boundaries

Name

Result NO RESULT NO RESULT PROFILE ARRAY NO RESULT

Purpose Adds new inner boundary to the grid Deletes all inner boundaries Returns array of boundaries profiles Replaces boundaries the inner inner

ADDINNERBOUNDARY(PROFILE) CLEARINNERBOUNDARY() INNERBOUNDARIES() INNERBOUNDARIES(ARRAY)

2007 AVEVA Solutions Ltd

2:117

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

INNERBOUNDARY(REAL) NUMBEROFINNERBOUNDARIES() OUTERBOUNDARY()

PROFILE REAL PROFILE

Returns the profile of the inner boundary Returns the number grid's inner boundaries of

Returns the outer boundary profile

Methods that return information about grids cells

Each cell is identified by index of two REAL. Name Result ORIENTATION Purpose Returns an orientation of cell identified by given index. Returns a position of cell identified by given index Returns a profile of cell identified by given index Returns the size of cell identified by given index (before trimming) Returns position of the cell identified by given index Returns true trimmed Returns true untrimmed if if cell cell is is

CELLORIENTATION(REAL1, REAL2) CELLPOSITION(REAL1, REAL2) CELLPROFILE(REAL1, REAL2) CELLSIZE(REAL1, REAL2)

POSITION PROFILE REAL ARRAY

CELLXYPOSITION(REAL1, REAL2) ISCELLTRIMMED(REAL1, REAL2) ISCELLUNTRIMMED(REAL1, REAL2) ISCELLWITHIN(REAL1, REAL2) LISTOFTRIMMEDCELLS() LISTOFTRIMMEDCELLS(REAL)

POSITION BOOL BOOL BOOL ARRAY ARRAY

Returns true if cell is within grid Returns indices trimmed cells of all

Returns indices of all trimmed cells which area is greater than given REAL value Returns indices untrimmed cells of all

LISTOFUNTRIMMEDCELLS() TOTALNUMBEROFCELLS() TRIMMEDCELLSIZE(REAL1, REAL2)

ARRAY REAL ARRAY

Returns a number of cells inside grid Returns the size of rectangle which contains the cell identified by given index

2007 AVEVA Solutions Ltd

2:118

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods that return information of gridlines

Lines are returned as ARRAY which first element is REAL representing line number and the second is array of LINE objects. Name Result ARRAY ARRAY ARRAY ARRAY Purpose Returns array of grid's x-lines Returns array of grid's x-lines of given index Returns array of grid's y-lines Returns array of grid's y-lines of given index

XGRIDLINES() XGRIDLINES(REAL) YGRIDLINES() YGRIDLINES(REAL)

2.5.44

POINTVECTOR Object
Members

Name Direction Position

Type

Purpose

DIRECTION Direction of point Get/Set POSITION Get/Set Origin of point

Table 2: 78.

POINTVECTOR Object Members

Definition Methods

Name Pointvector( POSITION, DIRECTION)

Result POINTVECTOR

Purpose Creates a POINTVECTOR with the given POSITION and DIRECTION Returns a POINTVECTOR as a string.

String()

STRING

Figure 2:47. POINTVECTOR Object Methods

Direction

Position

2007 AVEVA Solutions Ltd

2:119

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Figure 2:48. POINTVECTOR Object Definition

Methods that Return POINTVECTORs

Name Offset(REAL)

Result POINTVECTOR

Purpose Returns the point vector offset in its direction by the passed distance Returns the point vector with the original position and the direction constructed from the position directed to the passed position Returns the point vector at the intersection of the point line with a plane normal to the point line through the passed position

Towards(POSITION)

POINTVECTOR

Through(POSITION)

POINTVECTOR

Table 2: 79.

POINTVECTOR Object Methods that Return POINTVECTORs

Offset(REAL)

Through(POSITION)

Towards(POSITION)

Figure 2:49. POINTVECTORs Returned from POINTVECTOR Object Methods

Methods that Return POSITIONs

Name Intersection(POINTVECTOR) Intersection(LINE)

Result POSITION POSITION

Purpose Returns the intersection position of the point vectors. Returns the intersection position of the point vector with the supplied line. Returns the position at the intersection of the point vector with the supplied plane

Intersection(PLANE)

POSITION

2007 AVEVA Solutions Ltd

2:120

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Table 2: 80.

POINTVECTOR Object Methods that Return POSITIONs

Intersection(PLANE)

Figure 2:50. POINTVECTOR Intersection with a PLANE

Miscellaneous Methods

Name Intersections(ARC)

Result

Purpose

ARRAY OF Returns the positions at the POSITIONS intersection of the point vector with the supplied arc. PLANE Returns a plane with an origin equal to the position of the point vector and a normal direction equal to the point vector direction. Returns a line with a start position equal to the position of the point vector, a direction equal to the direction of the point vector and a length equal to the supplied length.

Plane()

Line(REAL)

LINE

Table 2: 81.

POINTVECTOR Object Miscellaneous Methods

2.5.45

POSITION Object
Members

Name East North Up Origin

Type REAL Get/Set REAL Get/Set REAL Get/Set DBREF Get/Set

Purpose The East component The North component The Up component The DB element that is the origin

2007 AVEVA Solutions Ltd

2:121

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Table 2: 82.

POSITION Object Members

Methods

Name Position(STRING ) Position(STRING, FORMAT)

Result POSITION POSITION

Purpose Creates a POSITION at the coordinates given in STRING. Creates a POSITION at the coordinates given in STRING, with the specified FORMAT. Magnitude of component in specified DIRECTION. TRUE if POSITIONS are the same. TRUE if POSITION is less than argument. Convert POSITION STRING. to a

Component(DIRECTION) EQ(POSITION) LT(POSITION) String(FORMAT) WRT(DBREF)

REAL BOOLEAN BOOLEAN STRING POSITION

Convert to a new POSITION with respect to given DB element. Returns the angle between the passed two points about the position object. Returns an arc using arc centre technique. The direction is the normal viewing direction. Returns an arc using arc centre technique. The direction is the normal viewing direction. Please see diagram for full explanation.

Angle (POSITION, POSITION)

REAL

ArcCentre(POSITION, POSITION, POSITION, DIRECTION, REAL )

ARC

ArcCentre(POSITION, POSITION, POSITION, DIRECTION, REAL)

ARC

Table 2: 83.

POSITION Object Methods (a)

2007 AVEVA Solutions Ltd

2:122

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

POSITION A POSITION X

RADIUS

POSITION B
Figure 2:51. !Arc = !posX.ArcFillet(!posA,!posB,!dir,!radius)

Name ArcFillet( POSITION, POSITION, DIRECTION, REAL )

Result ARC

Purpose Returns an arc using arc centre technique. The direction is the normal viewing direction. Please see diagram for full explanation. Returns an arc using arc radius technique. The direction is the normal viewing direction. The boolean selects the minor (FALSE) or major(TRUE) arc. Please see diagram for full explanation.

ArcRadius( POSITION, POSITION, DIRECTION, REAL, BOOLEAN )

ARC

Table 2: 84.

POSITION Object Methods (b)

2007 AVEVA Solutions Ltd

2:123

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

POSITION X

POSITION B MAJOR = FALSE

RADIUS POSITION A
Figure 2:52. !Arc = !posX.ArcRadius(!posA,!posB,!dir,radius,!major)

Name ArcThru( POSITION, POSITION, DIRECTION )

Result ARC

Purpose Returns an arc using arc through 3 points technique. The direction is the normal viewing direction. Please see diagram for full explanation.

Table 2: 85.

POSITION Object Methods (c)

POSITION X

POSITION A

POSITION B
Figure 2:53. !Arc = !posX.ArcThru(!posA,!posB,!dir)

2007 AVEVA Solutions Ltd

2:124

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name ArcThru( POSITION, POSITION, DIRECTION, REAL )

Result ARC

Purpose Returns an arc using arc through 3 points and radius technique. The direction is the normal viewing direction. Please see diagram for full explanation.

Table 2: 86.

POSITION Object Methods (d)

POSITION A

POSITION X RADIUS

POSITION B
Figure 2:54. !Arc = !posX.ArcThru(!posA,!posB,!dir,!radius)

Name Arc3Lines( LINE, LINE, LINE, DIRECTION )

Result ARC

Purpose Returns a circle through the 3 line tangent points. The 'this' position refers to the zone in which the circle lies. Returns the direction between the position and the supplied position Returns the distance between the position and the nearest point on the arc line of the passed arc definition Returns the mid point between the two positions

Direction(POSITION)

BOOLEAN

Distance(ARC)

REAL

MidPoint(POSITION)

POSITION

2007 AVEVA Solutions Ltd

2:125

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Near(POSITION, REAL)

Result BOOLEAN

Purpose Returns true if the passed position is within the passed distance from the position object Returns a position offset by the supplied length in the supplied direction Returns a plane in which each of the supplied points lie. Returns the distance between the position and the nearest point on the passed infinite line definition Returns the distance between the position and the nearest point on the passed plane definition Returns the distance between the two positions Returns a line between the two positions, starting at the position object Returns the mid point between the two positions Returns true if the passed position is within the passed distance from the position object Returns a position offset by the supplied length in the supplied direction Returns a plane in which each of the supplied points lie.

Offset(DIRECTION, REAL)

POSITION

Plane(POSITION, POSITION)

PLANE

Distance(LINE)

REAL

Distance(PLANE)

REAL

Distance(POSITION) Line(POSITION)

REAL LINE

MidPoint(POSITION) Near(POSITION, REAL)

POSITION BOOLEAN

Offset(DIRECTION, REAL)

POSITION

Plane(POSITION, POSITION)

PLANE

Table 2: 87.

POSITION Object Methods (e)

2.5.46

POSTEVENTS Object
The user may provide a PostEvents object, which should provide the methods described below. To use this feature, you must create a global object of this type and call it !!postEvents. The method !!postEvents.postMark will be called every time an undoable is created, after the undoable has been added to the undo stack.

2007 AVEVA Solutions Ltd

2:126

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

This refers to all undoables, whether created by a MARKDB command, an undoable object or within core functionality. Similarly, the method postUndo will be called after an UNDO has occurred, and so on. Each method will be passed a STRING object containing the name of the mark with which the mark, undo, or redo is associated.

Methods

Name postMark(STRING)

Result

Purpose

NO RESULT Called after an undoable has been added to the undo stack. STRING is the description text associated with the undoable object. NO RESULT Called after an undo has occurred. STRING is the description text associated with the undoable object. NO RESULT Called after a redo has occurred. STRING is the description text associated with the undoable object. NO RESULT Called after a clearMark has occurred NO RESULT Called after a clearAll has occurred.

postUndo (STRING)

postRedo(STRING)

postClearMark() postClearAll()

Table 2: 88.

PML PostEvents Object Methods

2.5.47

PROJECT Object
Members

Name Name Evar

Type STRING STRING

Purpose The name of the Project, up to 120 characters. Project environment variable, e.g. SAM000

Table 2: 89.

PROJECT Object Members

2007 AVEVA Solutions Ltd

2:127

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Active() Code() Description() Mbcharset() Message()

Result REAL STRING STRING STRING STRING

Purpose Number of active users of the project Project code, characters, e.g. SAM three

Project description, up to 120 characters. Multibyte number character set

Project message (information about the project), up to 120 characters. Project name Project number, up to 17 characters. Whether project is a global project.

Name() Number() Isglobal() Locations() CurrentLocation() Sessions() CurrentSession() Dblist()

STRING STRING BOOLEAN

ARRAY OF Return array of all Locations LOCATION in Project LOCATION Return true current location

ARRAY OF Return array of all Sessions SESSIONS (at the current location) SESSION Return current Session (at the current location) databases in the

ARRAY OF List of DB project. OBJECTS ARRAY MDBS ARRAY USERS

MDBList() UserList() Macros()

OF Return array of all MDBs in Project at current location. OF Return array of all USERs in Project at current location.

ARRAY OF Return array of all Inter-db MACROS macros in MISC db in Project at current location. ARRAY OF Return array of all messages STRINGS in MISC db at current location.

Messages()

Table 2: 90.

PROJECT Object Methods

2007 AVEVA Solutions Ltd

2:128

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Commands

!ARRAY = PROJECTS

$ Returns an array of all PROJECT objects $ which have project environment variables set.

!PROJECTVAR = CURRENT PROJECT $ Returns the current project object.

2.5.48

PROFILE Object
Members

Name Position Orientation Pointer

Type POSITION Get/Set

Purpose Origin of profile

ORIENTATION Orientation of profile plane Get/Set POINTER Get Only Definition of profile

Table 2: 91.

PROFILE Object Members

Methods

Name Profile(POSITION, ORIENTATION, ARRAY)

Result PROFILE

Purpose Creates a profile object. The input ARRAY is an array of LINEs, ARCs and POSITIONs. Other array member types will be ignored. Array member must be initialised correctly, otherwise it will be ignored. Creates a profile object from a LOOP, PLOO, PALJ or SPINE. Approximately from a POGO, BOUN, DRAW. 3D linear geometry (SPINE,BOUN, DRAW,PALJ) should be in a single plane. If not it is projected onto a plane defined by the first few points of the element.

Profile(DBREF)

PROFILE

2007 AVEVA Solutions Ltd

2:129

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Profile(DBREF1,DBREF2)

Result PROFILE

Purpose Creates a profile object from SPRO or SLOO at DBREF1. DBREF2 is the design element referencing the catalogue element containing the catalogue primitive thus providing its parameters. Creates a profile object which is a copy of the given profile Returns the PLANE definition of the profile. This is equivalent to the PLANE method on LINEARGRID object Return true if closed Returns true if the profile is valid and could be drawn correctly using GML, e.g. there are no self-intersecting edges True if anti-clockwise (on its plane). Returns error if profile is not closed Internal area of profile. Returns error if profile is not closed Returns the complete length of the profile. Returns true if profile is a full circle. Returns true if edge specified by REAL argument is a fillet. A fillet must be an arc with a significant angle that is tangentially continuous with its adjacent edges that are lines, or arcs of larger radius.

Profile(PROFILE) Plane()

PROFILE PLANE

IsClosed() IsValidClosed ()

BOOLEAN BOOLEAN

Sense()

BOOLEAN

Area()

REAL

Length() IsCircle() IsFillet(REAL)

REAL BOOLEAN BOOLEAN

Table 2: 92.

PROFILE Object Methods

2007 AVEVA Solutions Ltd

2:130

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Figure 2:55. Finding the Length of thje PROFILE Object

PROFILE Object Decomposition and Display Methods

Name edges()

Result ARRAY

Purpose Returns array of lines and arcs that define the profile. The direction and sense of the lines and arcs are important. If the profile is a full circle only a single full circle arc is returned regardless of the composition of the profile.

numberEdges() edge(REAL)

REAL LINE/ARC

Returns the number of edges within the profile (= vertices-1) Returns the profile element at the passed index of the edges array Populates DBREF with contents of the profile. If any geometry already exists it is replaced with the profile geometry. The geometry stored is that which is appropriate to the database element. The DBREF must be one of LOOP, PLOO, PALJ, SPINE, BOUN, DRAW, POGO. Returns itself unmodified.

dbWrite(DBREF)

PROFILE

2007 AVEVA Solutions Ltd

2:131

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name

Result

Purpose The owner of a LOOP or PLOOP is repositioned to fit with the profile. Other geometry is positioned correctly in the frame of reference of its owner or positioned ancestor. Population of catalogue geometry is not supported

draw(REAL1, REAL2, REAL3)

PROFILE

Draws the profile as a set of aid lines and arcs. REAL1 is the Segment number to draw to. REAL2 sets the style of the segment. REAL3 sets the colour of the segment.. The drawn graphics can be queried and manipulated using AID geometry functions. LINE and ARC objects also have the .draw method implemented

Table 2: 93.

PROFILE Object Decomposition and Display Methods

PROFILE Object Transformations and Modification Methods

These methods return a modified version of the profile definition: Name mirror(LINE) Result PROFILE Purpose Mirrors the boundary definition about the passed line, when mapped onto the boundary plane Offsets the boundary definition in the XY of the boundary plane with a shift of x of REAL1 and y of REAL2 Rotates the boundary definition about the POSITION by the given angle. Angle are anticlock-wise about the Z axes of the boundary plane Closes the profile with an additional edge (if necessary). If ends are within a tolerance the end point is adjusted

translate(REAL1,REAL2)

PROFILE

rotate(REAL, POSITION)

PROFILE

close()

PROFILE

2007 AVEVA Solutions Ltd

2:132

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name reverse()

Result PROFILE

Purpose Reverses the sense of the profile and the order of the edges Merge concentric contiguous arcs into one up to a maximum arc angle of REAL1 degrees according to tolerance REAL2 Mergearcs() will remove concentric back tracks in the profile as well. Merge concentric contiguous arcs into one. Merge colinear contiguous lines into one according to tolerance supplied. Mergelines() will remove colinear backtracks in the profile as well. Merge colinear lines into one. contiguous

mergearcs(REAL1, REAL2)

PROFILE

mergearcs() mergelines(REAL)

PROFILE PROFILE

mergelines() mergpoints(REAL)

PROFILE PROFILE

Remove coincident consecutive points according to tolerance supplied Remove consecutive points coincident

mergepoints() polyline(REAL)

PROFILE PROFILE

Replace arcs with a chordal approximation to the tolerance supplied Replace arcs with a chordal approximation Removes all the arcs from the definition, only leaving the straight-line edges. Arcs with angle less than the supplied argument are ignored. Arcs that are removed are replaced by projected tangents meeting at the polar position of the arc. Arcs with angles approaching 180 degrees are split in half

polyline() projectArcs(REAL)

PROFILE PROFILE

Table 2: 94.

PROFILE Object Transformations and Modification Methods

2007 AVEVA Solutions Ltd

2:133

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Figure 2:56. Transformations and Modifications by PROFILE Object Methods

PROFILE Object Methods that Query Position Relationships

These methods map the passed positions onto the profile plane, then use the resulting position to determine the result returned:

Name Near(POSITION)

Result POSITION

Purpose Returns the nearest position on the profile, to the given position projected onto the profile plane. The REAL argument is an index to an edge in the Profile. Returns the nearest point on this edge to the POSITION supplied. This is the same as .near (POSITION) but restricted to a single edge. Returns array of edge indices of the nearest edges to the given POSITION. The returned edges may be any in the profile. Edges will be consecutive if nearest point is a vertex.

Near(REAL,POSITION)

POSITION

NearEdges(POSITION)

ARRAY

2007 AVEVA Solutions Ltd

2:134

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name IsWithin(POSITION)

Result BOOLEAN

Purpose Returns TRUE if the position when mapped on to the profile plane lies inside the profile. The profile must be closed. Returns TRUE if the position when mapped on to the profile plane lies outside the profile. The profile must be closed. Returns TRUE if the position (mapped onto the profile plane) lies on the profile geometry.

IsWithout(POSITION)

BOOLEAN

OnProfile(POSITION)

BOOLEAN

Table 2: 95.

Profile Object Methods that Query Position Relationships

Figure 2:57. POSITION Relationships for PROFILE Objects

PROFILE Object Methods that Query Profile to Profile Relationships

These methods are used to check the relationship between PROFILEs. Name IsWithin(PROFILE) Result BOOLEAN Purpose True if the supplied profile lies wholly within the profile the object. Both profiles must be closed. True if the supplied profile lies completely outside the profile object. Both profiles must be closed. True if the supplied profile intersects the profile object. Both profiles must be closed

IsWithout(PROFILE)

BOOLEAN

IsIntersecting(PROFILE)

BOOLEAN

Table 2: 96.

PROFILE Object Methods that Query Profile to Profile Relationships

2007 AVEVA Solutions Ltd

2:135

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

PROFILE Object Intersection Methods

These methods return an array of results that define the intersection between an object and the profile. Note that if an intersection point occurs exactly at the junction of two spans of the profile, then two identical intersection points will occur in the array. Name intersections(LINE) Result Purpose

ARRAY OF Returns an array of points POINTS that are positions where the line (or the projection of the line into the plane of the profile) intersects the profile. All points on the extended infinite line are returned. ARRAY OF Returns an array of points POINTS that are positions where the arc (or the projection of the arc into the plane of the profile) intersects the profile. The plane of the arc must be parallel with the plane of the profile otherwise an error will occur. The points are anywhere on the circle of the arc (and not limited to be between start and end) ARRAY OF Returns an array of points POINTS which are positions where the two profiles intersect.. The two profiles must be parallel (or anti-parallel) to each other

intersections(ARC)

intersections(PROFILE)

Table 2: 97.

PROFILE Intersection Methods

Figure 2:58. Intersections of PROFILE Objects

2007 AVEVA Solutions Ltd

2:136

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

PROFILE Object Methods that Return New PROFILEs

These methods each return an array of new profiles. The new profiles are all created in he same sense as the profile object, except that holes are in the opposite sense. The profiles must lie on the same plane in space, but not necessarily having identical positions and orientations. Name intersect(PROFILE) union(PROFILE) Result Purpose

ARRAY OF Returns array of the resultant PROFILES intersection profiles ARRAY OF Returns the union of the two PROFILES profiles. Holes are returned as separate profiles (in reverse direction) ARRAY OF Returns the difference of the PROFILES passed profile against the profile definition ARRAY OF Returns the resultant profiles PROFILES from projecting the passed line onto the profile and splitting about that line ARRAY OF Returns the resultant PROFILES boundaries from splitting the profile on the line at the intersection of the passed plane and the profile plane. The side is specified by the supplied BOOLEAN. If it is TRUE then only profiles in the direction of the normal to the passed plane are created; if side is FALSE, only those in the direction of the anti-normal.

difference(PROFILE)

split(LINE)

split(PLANE, BOOLEAN)

Table 2: 98.

PROFILE Object Methods that Return New PROFILEs

2007 AVEVA Solutions Ltd

2:137

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Figure 2:59. PROFILEs Returned from PROFILE Object Methods

2.5.49

RADIALGRID Object
RADIAL GRID Object Members

Name Position Orientation Radii Angles

Type POSITION Get/Set ORIENTATION Get/Set REAL ARRAY Get/Set REAL ARRAY Get/Set

Purpose Origin of the grid. Orientation of the grid. Radii of the grid. Angular spacing, from X axes (zero).

Figure 2:60. RADIALGRID Object Members

2007 AVEVA Solutions Ltd

2:138

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

RADIALGRID Object Definition Methods

Name Radialgrid( POSITION, ORIENTATION, ARRAY, ARRAY)

Result RADIALGRID

Purpose Creates a grid with the given position and orientation, and the angles and radii specified in the arrays.

Table 2: 99.

RADIALGRID Object Definition Methods

Orientation

Position

Z Y Angles

X Radii

Figure 2:61. RADIALGRID Object definition (a)

RadialPosition(REAL, REAL)

Snap(POSITION)

Angle[1]

Snap(LINE)
Radius[1] Radius[2] Radius[3]

GridPoint(REAL, REAL)

Figure 2:62. RADIALGRID Object Definition (b)

2007 AVEVA Solutions Ltd

2:139

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.50

REAL Object
Methods

Name Real( BOOLEAN )

Result REAL

Purpose Creates a REAL from the given BOOLEAN: TRUE = 1, FALSE = 0. Creates a REAL from the given BORE. Creates a REAL from the given STRING. Creates a REAL from the given STRING in the specified format. Absolute value (make value positive). ACOS. ALOG. ASIN. ATAN. ATANT. TRUE if value lies in specified range including values specified. FALSE if value otherwise TRUE. is zero,

Real( BORE ) Real( STRING ) Real( STRING, FORMAT )

REAL REAL REAL

ABS() ACos() ALog() ASin() ATan() ATanT(REAL) Between(REAL, REAL )

REAL REAL REAL REAL REAL REAL BOOLEAN

Boolean() Bore()

BOOLEAN BORE

Convert to BORE (must be exact) dependent on current BORE units. COSINE. Give dimensions of value. Convert to a distance using default settings.

Cosine() Dimension() Distance()

REAL STRING STRING

2007 AVEVA Solutions Ltd

2:140

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Distance(BOOLEAN feet, BOOLEAN us, BOOLEAN fraction, REAL precision, BOOLEAN zeroes)

Result STRING

Purpose Convert to a distance : to feet & inches if feet (otherwise inches); to US format if us (otherwise PDMS format); use fraction if fraction (otherwise decimals); use precision as largest denominator or precision decimal places; output zeroes if zeroes (otherwise them). Comparison dependent on current BORE units. TRUE if equal. Comparison dependent on current BORE units. TRUE if greater than or equal to another value. Comparison dependent on current BORE units TRUE if greater than another value. Convert to whole number, rounding down. Comparison dependent on current BORE units. TRUE if less than or equal to another value. LOG . Comparison dependent on current BORE units. TRUE if less than another value. Convert to nearest BORE dependent on current BORE units setting. Convert to nearest whole number (up or down). Raise value to power. Convert to REAL (in this case a null operation).

EQ(BORE) EQ(REAL) GEQ(BORE) GEQ(REAL) GT(BORE) GT(REAL) INT() LEQ(BORE) LEQ(REAL) LOG() LT(BORE) LT(REAL) NearestBore()

BOOLEAN BOOLEAN BOOLEAN BOOLEAN BOOLEAN BOOLEAN REAL BOOLEAN BOOLEAN REAL BOOLEAN BOOLEAN BORE

Nint() Power(REAL) Real()

REAL REAL REAL

2007 AVEVA Solutions Ltd

2:141

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name SBetween (REAL,REAL)

Result BOOLEAN

Purpose TRUE if value lies in specified range excluding values specified. SINE. Square root of value. Convert to STRING with precision specified as a STRING in the range D0 to D6. Convert to STRING using settings in global FORMAT object. TANGENT.

Sine() Sqrt() String(STRING precision)

REAL REAL STRING

String(FORMAT)

STRING

Tangent()
Table 2: 100. REAL Object Methods

REAL

2.5.51

REPORT Object
The report object is used to format the table object data for displaying the contents of a table to the screen, forms or to file. Separating the formatting and extraction of the data from a table allows different reports to be generated from the same basic table. The report extracts the data from a TABLE and formats each of the columns according to the associated COLUMNFORMAT object. You may optionally specify that only rows which contain a specified MATCH string (which may or may not be case-dependent) should be included it the report output. The results may be extracted: all at once, using the Results() methods; a specified number of entries at a time, using the NextEntries()methods. Each entry will consist of one or more lines; a specified number of lines at a time, using the NextLines()methods. This may cause a partial entry to be returned at the end, but the next call to nextLines will fetch the remainder of the entry.

The first ARRAY argument provided to these methods will contain a set of STRINGs, each of which holds a Dtext row of data. If there is a second array argument, then this will contain the corresponding Rtext, which will be the name of the DBREF object associated with that row. For multi-line entries, the same Rtext value will be provided for each line.

2007 AVEVA Solutions Ltd

2:142

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Report() Report(TABLE) Table(TABLE) AddColumn(STRING key, COLUMNFORMAT, STRING heading)

Result

Purpose Constructor. Constructor that also sets the table and column formats. Sets the table to be used for the report. Adds the column with the specified key to the report, with the passed column format. The argument heading is the column heading. Sets the position in the result array to be used for the next evaluation. Sets the position in the matched result array to be used for the next evaluation. Used in conjunction with the 'MATCH' methods, defines whether matching is case sensitive. Re-initialises counter. the next

NextEntriesIndex(REAL position)

NextEntriesIndex(REAL n, STRING)

SetCaseMatch(BOOLEAN)

Initialise() EvaluateTable() Keys() STRING ARRAY

Re-evaluates on the table primary key and re-sorts. Returns an ARRAY of STRINGS that are the column keys used on this report. Returns the column format of the passed column key Returns the heading of the column identified by key. Returns the table used in this report. Queries whether the MATCH STRING is case sensitive. Set using CaseMatch (BOOLEAN).

ColumnFormat(STRING key) ColumnHeading (STRING key) Table() CaseMatch()

COLUMN FORMAT STRING TABLE BOOLEAN

2007 AVEVA Solutions Ltd

2:143

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Results(ARRAY Dtext, ARRAY Rtext)

Result BOOLEAN

Purpose Evaluates the report using all entries of the table (there may be more than 1 line per entry. If column formats cause a wrap-around Rtext will be repeated). The return is TRUE if there are entries to evaluate, FALSE if there are no entries. Both Rtext and Dtext must exist; they will be updated with the values.

Results(ARRAY) ResultsMatch(STRING, ARRAY, ARRAY)

BOOLEAN BOOLEAN

As above but only Dtext is evaluated. Similar to Results() but only values matching the string are put into the two arrays. As above but only Dtext is evaluated. Evaluates the report using the next n entries of the table (there may be more than 1 line per entry, if column formats cause a wrap-around the Rtext will be repeated). The return is TRUE if there are entries to evaluate, FALSE if there are no entries. Both Rtext and Dtext must exist; they will be updated with the next n values.

ResultsMatch(STRING, ARRAY) NextEntries(REAL n, ARRAY Dtext, ARRAY Rtext)

BOOLEAN BOOLEAN

NextEntries(REAL n, ARRAY) NextLines(REAL n, ARRAY Dtext, ARRAY Rtext)

BOOLEAN BOOLEAN

As above but only Dtext is evaluated. Evaluates the report with the next n lines of the table, if column formats cause a wrap-around the Rtext will be repeated. The return is BOOLEAN to indicate if there are lines to evaluate. Both Rtext and Dtext must exist; they will be updated with the next n values.

2007 AVEVA Solutions Ltd

2:144

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name NextLines(REAL n, ARRAY) NextEntriesMatch (REAL n, STRING value, ARRAY Dtext, ARRAY Rtext)

Result BOOLEAN BOOLEAN

Purpose As above but only Dtext is evaluated. Similar to NextEntries() but only values matching value are put into the two arrays. As above but only Dtext is evaluated. Returns the current position in the array of entries. Returns the current position in the array of entries. Returns the current count of the matched values array. STRING is a key word 'MATCH'.

NextEntriesMatch(REAL n, STRING value, ARRAY Dtext) NextEntriesIndex() NextLinesIndex() NextEntriesIndex (STRING)

BOOLEAN REAL REAL REAL

Table 2: 101. REPORT Object Methods

2.5.52

RTOGGLE Gadget
Members

Name val index onVal offVal visible active callback tag

Result BOOLEAN Get/Set REAL Only STRING Get/Set STRING Get/Set BOOLEAN Get/Set BOOLEAN Get/Set STRING Get/Set STRING Get/Set

Purpose Current value true or false.

Get Index of radio button within the group. Associated selected value. Associated unselected value. Visibility. Active (greyed-in) status. Callback string. Tag text.

Table 2: 102. RTOGGLE Object Members

2007 AVEVA Solutions Ltd

2:145

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name FullName( ) Name( ) Owner( ) SetPopup( MENU ) RemovePopup( MENU ) GetPickedPopup( ) Refresh( ) Shown( ) SetToolTip( STRING ) Type( ) Background()

Result STRING STRING FORM

Purpose Get the full gadget name, e.g.'!!Form.gadget'. Get the gadget's name, e.g. 'gadget'. Get owning form.

NO RESULT Links the given menu with the gadget as a popup. NO RESULT Removes the given popup menu from the gadget. MENU Returns the last picked popup menu for the gadget.

NO RESULT Refreshes the display of the gadget. BOOLEAN Get shown status.

NO RESULT Sets or edits the text of the TOOLTIP. STRING STRING Get the gadget type as a string. Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
Table 2: 103. RTOGGLE Object Methods

Command
The RTOGGLE gadget (which is very similar to the TOGGLE gadget) is allowed only within FRAMES. You can added them to a FRAME with the usual positioning and layout commands. The RTOGGLE gadgets are implicitly numbered 1,2,3 as they are added. The FRAME gadget can have an assigned callback, which is executed when the radio group selection is changed, i.e. whenever the user selects an unselected radio-toggle. As there is only a SELECT action supported, it can be either a simple callback or an open callback.

2007 AVEVA Solutions Ltd

2:146

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

.-------<------------. / | >- RTOGgle gname -+- tagtext ------------| +- CALLback text -----| +- <fgpos> ------------| +- <fganch> -----------| +- <fgdock> -----------| +- TOOLTIP text -------| +- CORE ---------------* Core managed gadget | +- STATES offval onval -. ------------------------+- TOOLTIP text -. ------------------->

Note: offval and onval are string values associated with the radio button states unselected or selected. Default values are onval = ON, offval = OFF. In order to simplify the task of replacing the use of the (now removed) RADIO gadget by the radio group Frame gadget, the RTOGGLE gadgets UNSELECT events are raised only if a PML open callback has been defined. This allows the simple replacement of TOGGLE gadgets by RTOGGLE gadgets without the need to modify their callbacks.

2.5.53

SELECTOR Gadget
Members

Name Add(STRING Dtext)

Type

Purpose

NO RESULT Append an entry to the list, where Dtext is the text to display in the option list. NO RESULT Append and entry to the list, where Dtext is the text to display in the option list, and Rtext is the replacement text for the new field. If Rtext isnt specified, it will be set to Dtext by default. REAL Get/Set Selected field number of a single choice list. (1,2,)

Add(STRING Dtext, STRING Rtext))

Val Val

ARRAY OF Selected field numbers of a REAL multiple choice list. (1,2,) Get/Set

2007 AVEVA Solutions Ltd

2:147

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name DText

Type STRING ARRAY Get/Set STRING Get Only REAL Get Only

Purpose Set or get the entire list of display texts. Get the display text of the n'th field. Last picked list field number.

DText[n] PickedField

Table 2: 104. SELECTOR Object Members

Methods

Name FullName() Name() Owner() Shown() Type() Select(STRING text, STRING value)

Result STRING STRING FORM BOOLEAN STRING

Purpose Get the full gadget name, e.g.'!!Form.gadget'. Get the gadget's name, e.g. 'gadget'. Get the owning form. Get shown status. Get the GADGET type as a string.

NO RESULT Select specified item in a selector. text must be Rtext or Dtext. value is the field RTEXT or DTEXT to be selected. NO RESULT Select multiple choice selector fields by value: text must be Rtext or Dtext. The values array contains the RTEXT or DTEXT of the fields to be selected. STRING Get current selection: text ARRAY OF must be Rtext or Dtext. STRING The value of Selection is the RTEXT or DTEXT of the selected field or fields. NO RESULT Links the given menu with the gadget as a popup. NO RESULT Move keyboard focus to this gadget.

Select(STRING text, Array values)

Selection(STRING text)

SetPopup(MENU) SetFocus()

2007 AVEVA Solutions Ltd

2:148

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name SetToolTip(STRING) Refresh() RemovePopup(MENU) GetPickedPopup() Clear() ClearSelection() Background()

Result

Purpose

NO RESULT Sets or edits the text of the TOOLTIP. NO RESULT Refreshes the display of the gadget. NO RESULT Removes the given popup menu from the gadget. MENU Returns the last picked popup menu for the gadget.

NO RESULT Clear selector contents. NO RESULT Clear selections only. STRING Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
Table 2: 105. SELECTOR Object Methods

Command
The SELECTOR command defines a database element selector gadget and specifies its position, tag, and callback text. Also specifies whether the selector allows a single choice only or multiple choices and defines the area (width and height) in which the displayed part of the list will appear. It also allows you to specify which parts of the hierarchy are shown and whether or not these are updated automatically during database navigation.

2007 AVEVA Solutions Ltd

2:149

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

.-------<---------. / | >- SELector gname -+-- <fgpos> --------| +-- tagtext --------| +-- <fganch> -------| +-- <fgdock> -------| +-- TOOLTIP text ---| +-- CALLback text --* +-- SINGle -. +------------ <vshap> DATAbase -+- MEMbers -. | +- OWNers --| | -----------+-AUTO-. | ------| - MULTiple <vshap> DATAbase ---+- MEMbers ---------| |- OWNers ----------| -------------------| | .-------<-----------* | +-- TOOLTIP text --. -------------------> Figure 2:63. Syntax Graph -: Setting up a SELECTOR Object

Default:

Single choice. If DATABASE is not qualified, default is Members plus Owners. Auto update off.

2007 AVEVA Solutions Ltd

2:150

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.54

SESSION Object
Members

Name UniqueID Name Login Host Entered LocationName IsRemote IsCurrent

Type STRING Get/Set STRING Get/Set STRING Get/Set STRING Get/Set STRING Get/Set STRING Get/Set STRING Get/Set BOOLEAN Get/Set

Purpose Internal ID Session Name Users login ID ID of the Machine running the session Time of entering PDMS Name of Session Location for

True for Sessions at Remote locations TRUE for Users SESSION object own

Table 2: 106. SESSION Object Members

Methods

Name SESSION (STRING)

Result SESSION

Purpose Returns a SESSION object, given a string containing a session's Unique-id.

Current() Deferred() Location()

ARRAY OF List of Current DBs in the DB MDB of the SESSION object. ARRAY OF List Deferred DBs in the DB MDB of the SESSION object. LOCATION Return LOCATION to which the Session applies. In a non-Global project, returns NULL or error. The current MDB of the SESSION.

MDB()

MDB

2007 AVEVA Solutions Ltd

2:151

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Mode()

Result

Purpose

ARRAY OF List of potential access STRING modes as R , RW or N for each of the current DBs. BOOLEAN STRING TRUE if database has been modified. Name of the current PDMS module.

Modified() Module() Status()

ARRAY OF List of current access modes STRINGS as R , RW or N for each of the current DBs. USER The user of this SESSION object.

User()

Table 2: 107. SESSION Object Methods

Note:
The LocationName member and Location() method imply the location to which the Session applies. This is normally the current location, except when Sessions at remote locations have been requested. In a non-Global project, these members and methods may be unavailable or unset. Some ADMIN Sessions in a Global project may apply to another location's system database. This will be returned as part of the string returned by the Module() method, if relevant. Other ADMIN Sessions may actually be Global Daemon Sessions. This is returned as part of the string for the name member. Some SESSION object methods have only restricted availability: The Modified() method only applies to the current Session at the current location. The Current(), Deferred(), Mode() and Status() methods will not be implemented for remote Sessions and will return an error. The Location(), MDB(), User() and Module() methods are valid for remote Sessions.

The last three methods will cause Daemon activity for Sessions at remote locations. It should be should be observed in using the MDB and USER objects returned by the MDB() and User() methods for a remote Session. Methods on these objects will access the currently open system database. Thus the appropriate location's system database should be opened (using the ADMINISTER SYSTEM command) before invoking methods on these remotely generated MDB and USER objects.

Command

!SESSION = CURRENT SESSION

$ Returns the current session object.

2007 AVEVA Solutions Ltd

2:152

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.55

SLIDER Gadget
Members

Name visible active callback tag val background background range

Type BOOLEAN Get/Set BOOLEAN Get/Set STRING Get/Set STRING Get/Set REAL Get/Set REAL Get/Set

Purpose Visibility. Active (greyed-in) status. Callback string. Tag text - not displayed for this gadget. Current value as integer. Background Colour Number.

STRING Set Background Colour Name. only REAL ARRAY Get/Set Range Start, End and optional Step(>0) as integers. The start value may be less than the end value. Array size must be 2 or more. Tick style as integer. 0 - none, 1 - right or bottom, 2 top or left, 3 - both 1 and 2

tickstyle

REAL Get/Set

Table 2: 108. SLIDER Object Members

Note:
The Val member represents the current value of the slider as a PML REAL (in fact always an integer). The Range member allows the slider range and optionally the step value to be set or queried. The granularity of the slider movement is determined by the specified step increment, i.e. a move event is generated at each step increment within the sliders range. The range limits must each be an integral multiple of the step size (else an error is flagged The RESET action of a form (from reset, CANCEL or QUIT actions) will only reset the slider current value not other slider properties. So if you redefine the range while a form is displayed, and press the RESET button, the range will not revert to the previous settings. You will have to do this from reset buttons callback and/or the forms CANCELCALL callback. Tick marks, if present, occur at every step value in the range.

2007 AVEVA Solutions Ltd

2:153

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name FullName() Name() Owner() SetToolTip(STRING) Shown() Type() Refresh() Background()

Result STRING STRING FORM

Purpose Get the full gadget name, e.g.'!!Form.gadget'. Get the gadget's name, e.g. 'gadget'. Get owning form.

NO RESULT Sets or edits the text of the Tooltip. BOOLEAN STRING Get shown status. Get the gadget type as a string i.e. 'SLIDER'.

NO RESULT Refresh gadget image. STRING Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised.. SetFocus() NO RESULT Set keyboard focus to gadget. Allows arrow keys to drive slider.

Table 2: 109. SLIDER Object Methods

2007 AVEVA Solutions Ltd

2:154

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Command

.-------<-------------------. / | >-- SLIDER gname -+- tagtext -------------------| +- <fgpos> -------------------| +- CORE ----------------------| Core managed gadget +- <fganch> ------------------| +- <fgdock> ------------------| +- BACKGround <colno> --------| +- CALLback text -------------| +- TOOLTIP text --------------| +- VERTical ------------------| +- HORIZontal ----------------* | | .-------<-------------------. |/ | +- RANGE int int -------------| +- STEP int ------------------| +- VALue int -----------------* | - <vshap> -+- TOOLTIP text -. ------------------> Figure 2:64. Syntax Graph -: Creating a SLIDER Object

Note: The user can specify the range as start, end and optional step and value integer values. The <vshap> graph allows the specification of the WIDTH and/or HEIGHT for sliders, in grid units. The width must be specified for a horizontal slider, and the height must be specified for a vertical slider. If the other dimension is not specified then a default size will be assumed. The tag text is not displayed for a slider gadget.

2.5.56

STRING Object
Methods

Name String(BLOCK) String(BOOLEAN) String(BOOLEAN,FORMAT)

Result STRING STRING STRING

Purpose Creates a STRING from a BLOCK expression. Creates a STRING equal to TRUE or FALSE. Creates a STRING from a BOOLEAN, as specified in the FORMAT object. Creates a STRING from a BORE.

String(BORE)

STRING

2007 AVEVA Solutions Ltd

2:155

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name String(BORE,FORMAT)

Result STRING

Purpose Creates a STRING from a BORE, as specified in the FORMAT object. Creates a STRING containing the DB name. Creates a STRING containing the DB name. The FORMAT argument is required for consistency by Forms and Menus. Creates a STRING from a DIRECTION. Creates a STRING from a Direction, as specified in the FORMAT object. Creates a STRING containing the MDB name. Creates a STRING from an Orientation. Creates a STRING from an Orientation, as specified in the FORMAT object. Creates a STRING from a POSITION. Creates a STRING from a POSITION, as specified in the FORMAT object. Creates a STRING containing the PROJECT code. Creates a STRING from a REAL. Creates a STRING from a REAL, as specified in the FORMAT object. Creates a STRING from a REAL. The STRING argument is present for converting the number of decimal places when given in the obsolete format Dn. Creates a STRING containing the SESSION number.

String(DB) String(DB,FORMAT)

STRING STRING

String(DIRECTION) String(DIRECTION,FORMAT)

STRING STRING

String(MDB) String(ORIENTATION) String(ORIENTATION,FORMAT)

STRING STRING STRING

String(POSITION) String(POSITION,FORMAT)

STRING STRING

String(PROJECT) String(REAL) String(REAL,FORMAT)

STRING STRING STRING

String(REAL,STRING)

STRING

String(SESSION)

STRING

2007 AVEVA Solutions Ltd

2:156

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name String(TEAM) String(USER) After(STRING two)

Result STRING STRING STRING

Purpose Creates a STRING containing the TEAM name. Creates a STRING containing the USER name. Return sub-string following leftmost occurrence of substring two. Return sub-string before leftmost occurrence of substring two. Make STRING into a BLOCK for evaluation. TRUE if STRING is TRUE, T, YES or Y; FALSE if STRING is FALSE, F, NO,or N.

Before(STRING two)

STRING

Block() Boolean()

BLOCK BOOLEAN

Bore()

BORE

Convert STRING to a BORE (exact conversion - see also NEARESTBORE). Convert STRING to a BORE using the settings in the global FORMAT object. Convert STRING to a DBREF. Convert STRING to a DBREF using the settings in the global format object. Convert STRING DIRECTION. to a

Bore(FORMAT)

BORE

DBRef() DBRef(FORMAT)

DBREF DBREF

Direction() Direction(FORMAT)

DIRECTION DIRECTION

Convert STRING to a DIRECTION using the settings in the global format object. As Length() but multibyte characters for

DLength() DMatch(STRING) DSubstring(REAL) DSubstring(REAL,REAL)

REAL REAL STRING STRING

As Match() but for multibyte characters. As Substring() but multibyte characters. As Substring() but multibyte characters. for for

2007 AVEVA Solutions Ltd

2:157

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Empty() Length() LowCase() LT(STRING) Match(STRING two)

Result BOOLEAN REAL STRING BOOLEAN REAL

Purpose TRUE for empty zero-length string. Number string. of characters in

Convert string to lower case. Comparison using collating sequence. ASCII

Location of start of sub-string two within first string - zero returned if not found. TRUE if strings are the same. STRING two may contain wildcard characters: * for any characters number of

MatchWild(STRING two)

BOOLEAN

? for any single character. MatchWild(STRING two, STRING multiple) BOOLEAN TRUE if strings are the same as above but multiple redefines the wildcard for any number of characters. TRUE if strings are the same as above but multiple redefines the wildcard for any number of characters and single also redefines that for a single character. Returns the number of occurrences of the given string. to an

MatchWild(STRING two, STRING multiple,STRING single)

BOOLEAN

Occurs(STRING)

REAL

Orientation() Orientation(FORMAT !!format)

ORIENTATION Convert STRING ORIENTATION.

ORIENTATION Convert STRING to an ORIENTATION using the settings in the global !!format. STRING Extract nth field from string where fields are delimited by space, tab or newline. Extract nth field from string where fields are delimited by delim. Convert STRING POSITION. to a

Part(REAL nth)

Part(REAL nth,STRING delim)

STRING

Position()

POSITION

2007 AVEVA Solutions Ltd

2:158

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Position(FORMAT !!format)

Result POSITION

Purpose Convert STRING to a POSITION using the settings in the global !!format object. Convert to a number. Replace all occurrences of sub-string two with sub-string three. Replace all occurrences of sub-string two with sub-string three starting at the nth occurrence (or -nth occurrence from the end). Replace count occurrences of sub-string two with substring three starting at the nth occurrence (or -nth occurrence from the end). Split string into an ARRAY of STRINGS at space (multiple spaces compressed). Split string into an ARRAY of STRINGS at delim (multiples of delim not compressed). Convert STRING to a STRING using the settings in the global FORMAT object. Returns a sub-string from index to the end of the string Returns a sub-string, nchars in length, starting at index. Remove initial and trailing spaces. Remove initial spaces (options =L), trailing spaces (options = R) or both (options =LR). Reduce multiple occurrences of char to a single occurrence throughout the STRING (options = M). Convert STRING to upper case.

REAL() Replace(STRING two,STRING three)

REAL STRING

Replace(STRING two,STRING three,REAL nth)

STRING

Replace(STRING wo,STRINGt hree,REAL nth,REAL count)

STRING

Split()

ARRAY

Split(STRING elim)

ARRAY

String(FORMAT)

STRING

Substring(REALindex) Substring(REAL index,REAL nchars) Trim() Trim(STRINGoptions)

STRING STRING STRING STRING

Trim(STRING options,STRING char)

STRING

UpCase()

STRING

2007 AVEVA Solutions Ltd

2:159

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name VLogical() VText() VValue()

Result BOOLEAN STRING REAL

Purpose Evaluate STRING as a BOOLEAN. Evaluate STRING as a STRING. Evaluate STRING as a REAL.

Table 2: 110. STRING Object Methods

2.5.57

TABLE Object
The TABLE object is used to hold raw data in a manner that can be manipulated in a tabular manner, i.e. as a spreadsheet. Each row of the table represents a DBREF, and is defined by the primary key. The columns of the table contain information about the DBREF according to the associated COLUMN object. Sorting of the table is by the order of the columns and the sort criteria on the relevant column. The formatting of the table data is via a REPORT object, which will allow the same data to be represented in many different ways.

Methods

Name Table() Table(DBREF ARRAY, COLUMN ARRAY)

Result

Purpose Constructor (initialises all the object settings) Constructor that passes the Primary Key as an ARRAY of DBREFS and the columns as an ARRAY of COLUMNS Constructor that passes the Primary Key as a COLLECTION and the columns as an ARRAY of COLUMNS. User defined Primary Key populated directly from a COLLECTION. User defined Primary Key. Replaces the -nth column of the table. Clears all the columns from the table. Sets up the columns from an ARRAY of COLUMN objects.

Table(COLLECTION, COLUMNARRAY)

PrimaryKey(COLLECTION)

PrimaryKey(ARRAY of DBREF) Column(REAL n, COLUMN) ClearColumns() Columns(COLUMN ARRAY)

2007 AVEVA Solutions Ltd

2:160

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Evaluate() EvaluatePrimaryKey() PrimaryKey()

Result

Purpose Evaluates the complete table. Re-evaluates the Key collection. Primary

DBREF ARRAY COLUMN ARRAY

Returns the primary Key of the table, reference list for the columns of the table. Returns the column definitions. The order of the columns is important when sorting. Returns the contents of the cell at the column and row. Returns the contents of nth column. Returns the contents of nth row. Contents of the cell at the column and row. Returns the contents column identified by key. of

Columns()

Cell(REAL column, REAL row) Column(REAL, n) Row(REAL, n) Cell(STRING key, DBREF) Column(STRING key) Row(DBREF)

ANY ARRAY ARRAY ANY ARRAY ARRAY

Returns the contents of row identified by DBREF.

Table 2: 111. Table -:TABLE Object Methods

2.5.58

TEAM Object
Members

Name Name Description Refno

Type STRING STRING STRING

Purpose Name of the TEAM, up to 32 characters. TEAM description, up to 120 characters. STRING containing Database reference number.

Table 2: 112. TEAM Object Members

2007 AVEVA Solutions Ltd

2:161

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods
None of these methods modifies the original object.

Name DbList() UserList() TEAM(DBREF) TEAM(STRING)

Result

Purpose

ARRAY OF List of DBs owned by the DB TEAM. ARRAY OF List of USERS in the TEAM. USER TEAM TEAM Returns a TEAM given a DBREF. object,

Returns a TEAM object, given a name or reference number.

Table 2: 113. TEAM Object Methods

These methods may be used in the following ways

!D = OBJECT TEAM(!!CE) !D = OBJECT TEAM(!!CE.Name) !D = !!CE.TEAM() !D = !!CE.Name.TEAM()

In all cases !!CE is assumed to be a DB database element and !!CE.Name is a STRING object containing the elements name. These methods should assist performance improvements to AppWare by making it easier to get from Database element to Object.

Command

!ARRAY = TEAMS

$ Returns an array of TEAMs

2007 AVEVA Solutions Ltd

2:162

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.59

TEXT Gadget
Members

Name Val Val Val Val

Type STRING Get/Set REAL Set

Purpose Set or get the contents of STRING type TEXT field.

Get/ Set or get the contents of REAL type TEXT field. Set or get the contents of BOOLEAN type TEXT field. Set or get the contents of the field according to the user defined type.

BOOLEAN Get/Set 'AS DEFINED Get/Set

DataType Echo

STRING Get Get the type of the field. Only BOOLEAN Get Only Get the Echo Status. Noecho means that typed characters will all appear as asterisks.

Format

STRING Get Get the name of the format Only object associated with the field. REAL Only STRING Get/Set BOOLEAN Get/Set Get Get the Scroll Width. Set/get user-defined validation callback. Controls the ability to interactively edit the content of a text field.

Scroll ValidateCall Editable

Table 2: 114. TEXT Object Members

2007 AVEVA Solutions Ltd

2:163

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name FullName() Name() Owner() Clear() SetEditable(BOOLEAN) SetFocus() SetToolTip(STRING) Refresh() SetValue(ANY value, BOOLEAN validate)

Result STRING STRING FORM

Purpose Get the full gadget name, e.g.'!!Form.gadget'. Get the gadget's name, e.g. 'gadget'. Get owning form.

NO RESULT Clear gadget contents. NO RESULT Sets the editable status for the field. NO RESULT Move keyboard focus to this gadget. NO RESULT Sets or edits the text of the TOOLTIP. NO RESULT Refreshes the display of the gadget. NO RESULT Sets the value of the field, checking for valid type and format. If validate is TRUE, the validation callback will be executed. MENU BOOLEAN STRING Returns the last picked popup menu for the gadget. Get shown status. Get the gadget type as a string i.e. 'TEXT'.

GetPickedPopup() Shown() Type()

Table 2: 115. TEXT Object Methods

Command
The TEXT command defines a text field gadget which supports data values of a given type. The following can also be specified; Gadget position, tag, size, callback, dock, anchor and tooltip; maximum length of the string that may be scrolled in the gadget; the name of a format object which says how a value is to appear as text or be interpreted; that text entered is not echoed as typed, but appears as asterisks (for entering passwords, for example); that the field contents can be seen but not edited.

2007 AVEVA Solutions Ltd

2:164

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

You can define the TEXT object to be either PML-controlled, or core-code controlled using the gadget qualifier attribute control type, with values PML or CORE.
.--------<-------------. / | >-- TEXT gname --+-- <fgpos> -------------| +-- CORE ----------------| Core managed gadget +-- <fgtagw> ------------| +-- <fganch> ------------| +-- <fgdock> ------------| +-- TOOLTIP text --------| +-- CALLback text -------* | .---------<---------. | / | --*-- WIDth integer ----| +-- SCRoll integer ---| +---NOEcho------------* | -- IS --+-- STRING --. +-- REAL ----| +-- BOOLEAN -| -- word ----+- FORMAT gvarnm -. -----------------+- TOOLTIP text -. ------------------>

Figure 2:65. Syntax Graph -: Setting Up a TEXT Object

The IS word syntax allows for any user defined data type to be used, but this will only work satisfactorily if a suitable FORMAT object is supplied. Note: The maximum string length (SCROLL integer) is 256 characters, and the default if you do not specify a length is 132. It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.

2.5.60

TEXTPANE Gadget
Members

Name Val

Type

Purpose

ARRAY OF Get or set the contents of the STRING text pane. Get/Set REAL Only Get Get the number of lines of text in the gadget.

Count

Table 2: 116. TEXTPANE Object Members

2007 AVEVA Solutions Ltd

2:165

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name FullName() Name() Owner() Clear() Line(REAL ) SetLine(REAL, STRING) CurPos() SetCurPos(REAL[2]) SetCurPos(REAL, REAL) SetEditable(BOOLEAN) SetPopup(MENU) RemovePopup(MENU) GetPickedPopup() SetToolTip(STRING) Refresh() Shown() Type() Background()

Result STRING STRING FORM

Purpose Get the full gadget e.g.'!!Form.gadget'. Get the 'gadget'. gadget's name, e.g.

name,

Get owning form.

NO RESULT Clear all lines from the gadget STRING Get the text of given line

NO RESULT Replace specified line number by STRING. ARRAY[2] OF REAL Get cursor character). position position position (line, (line, (line,

NO RESULT Set cursor character). NO RESULT Set cursor character). NO RESULT Set edit status.

NO RESULT Links the given menu with the gadget as a popup. NO RESULT Removes the given popup menu from the gadget. MENU Returns the last picked popup menu for the gadget.

NO RESULT Sets or edits the text of the TOOLTIP. NO RESULT Refreshes the display of the gadget. BOOLEAN STRING STRING Get shown status. Get the gadget type as a string. Get Background Colour Name. Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..

Table 2: 117. TXTPANE Object Methods

2007 AVEVA Solutions Ltd

2:166

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Command
The TEXTPANE command defines a text pane gadget and specifies its position and tag. This is a multi-line text input field, allowing the user to enter a number of lines of text (either directly or using cut and paste). Note that no callback string is allowed with this gadget, as there is no way of knowing when a user has finished entering text. The value of a TEXTPANE is its contents, held as an array of strings, where each line is an element of the array. You can define the BUTTON to be either PML-controlled, or core-code controlled using the gadget qualifier attribute control type, with values PML or CORE.
.--------<--------. / | >-- TEXTPane gname --+-- tagtext---------| +-- <fganch> -------| +-- <fgdock> -------| +-- <fgpos> --------| +-- CORE -----------* -- <vshap> --->

Core managed gadget

Figure 2:66. Syntax Graph -: Setting Up a TEXTPANE Object

Note: It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.

2.5.61

TOGGLE Gadget
Member

Name Val

Type BOOLEAN Get/Set

Purpose Toggles value between TRUE and FALSE.

2007 AVEVA Solutions Ltd

2:167

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name AddPixmap(STRING file1, STRING file2, STRING file3 ) AddPixmap(STRING file1, STRING file2) AddPixmap(STRING file ) FullName() Name() Owner() SetFocus() SetPopup(MENU) RemovePopup(MENU) GetPickedPopup() Refresh() Shown() SetToolTip Type() Background()

Result

Purpose

NO RESULT Adds pixmaps to be used for the unselected, selected and inactive states. The last two are optional. STRING STRING FORM Get the full gadget name, e.g.'!!Form.gadget'. Get the gadget's name, e.g. 'gadget'. Get owning form.

NO RESULT Moves keyboard focus to this gadget. NO RESULT Links the given menu with the gadget as a popup. NO RESULT Removes the given popup menu from the gadget. MENU Returns the last picked popup menu for the gadget.

NO RESULT Refreshes the display of the gadget. BOOLEAN STRING STRING STRING Get shown status. Sets or edits the text of the TOOLTIP. Get the gadget type as a string. Get Background Name. Colour

Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
Table 2: 118. TOGGLE Object Methods

2007 AVEVA Solutions Ltd

2:168

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Command
The TOGGLE command defines a toggle gadget, and specifies its position, tag, and callback text. Also allows you to specify different text strings for the default ON and OFF states. You can define the TOGGLE to be either PML-controlled, or core-code controlled using the gadget qualifier attribute control type, with values PML or CORE.
.-------<------------. / | >- TOGGLE gname -+- <fgtagw> -----------| +- PIXMAP <vshap> -----| +- CALLback text -----| +- <fgpos> ------------| +- <fganch> -----------| +- <fgdock> -----------| +- TOOLTIP text -------| +- CORE ---------------* Core managed gadget +- STATES text1 text2 -. ----------------------+- TOOLTIP text -. -------------------> Figure 2:67. Syntax Graph -: Setting Up a TOGGLE Object

where text1 corresponds to the OFF setting and text2 corresponds to the ON setting. Note: It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.

Default:

Default text strings for the two toggle settings are OFF and ON. Default state when a toggle is first defined is OFF; i.e. button raised.

Pixmaps associated with Toggle gadgets can be changed after the gadgets have been displayed on a form. Method syntax: AddPixmap( !pixmap1 is STRING ) AddPixmap( !pixmap1 is STRING, !pixmap2 is STRING ) Where: !pixmap is a string holding the file pathname of the required .png file, e.g. %pmllib%\png\camera.png !pixmap1 shows the Un-selected state of the gadget, and pixmap2 shows the Selected state. Notes: 1. It is recommended that when you define the gadget you set its size to encompass the largest pixmap which you will later add. Failure to do this may give rise to unexpected behaviour.

2007 AVEVA Solutions Ltd

2:169

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2. Historically you could add a third pixmap which was used when the gadget was deactivated. This practice is no longer necessary as the gadget pixmapped is automatically greyed-out on de-activation.

2.5.62

UNDOABLE Object
This object allows you to add functionality to the undo and redo stacks.

Methods

Name description(STRING) add()

Result

Purpose

NO RESULT Adds description text to the undoable NO RESULT Marks the database with the description text and adds this undoable to the undo stack NO RESULT Marks the database again at the end of the change. NO RESULT Specify a command to be executed when this undoable is taken off the undo stack NO RESULT Specify a command to execute when this undoable is taken off the redo stack. NO RESULT Specify a command to execute when this undoable is cleared without any associated undo/redo being performed.

endundoable() undoAction (STRING)

redoAction(STRING)

clearAction(STRING)

Table 2: 119. PMLUndoable Object Methods

Command
To use this object, first create an undoable object, and define the undoAction(), redoAction() and clearAction() methods to define the execution strings. Call the method add() to mark the database and add the undoable object to the undo stack. Make the set of changes that you may wish to undo, then call the method endundoable() to mark the end of the changes. Note: PDMS11.6, this object is only supported in PDMS Design.

2007 AVEVA Solutions Ltd

2:170

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.63

USER Object
Member

Name Name Description Access Refno

Result STRING STRING STRING STRING

Purpose The name of the User, up to 32 characters. Users description, up to 120 characters. Users access rights (FREE, GENERAL, RESTRICTED). STRING containing Database reference number.

Table 2: 120. USER Object Members

Method

Name TeamList() WorkingList()

Result

Purpose

ARRAY OF List of TEAMs including this USERS USER. ARRAY OF List of working extract DBS DB owned by a User. OBJECTS STRING USER USER The Users password, up to 6 characters preceded by /. Returns a USER given a DBREF. object,

Password() USER(DBREF) USER(STRING)

Returns a USER object, given a name or reference number.

Table 2: 121. USER Object Methods

These methods may be used in the following ways:

!D = OBJECT USER(!!CE) !D = OBJECT USER(!!CE.Name) !D = !!CE.USER() !D = !!CE.Name.USER()

In all cases !!CE is assumed to be a DB database element and !!CE.Name is a STRING object containing the elements name.

2007 AVEVA Solutions Ltd

2:171

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

These methods should assist performance improvements to AppWare by making it easier to get from Database element to Object.

Command

!ARRAY = USERS

$ Returns an array of USER objects in current project.

2.5.64

VIEW Gadget: ALPHA Views

Members

Name Channel

Type STRING Get/Set

Purpose Get or set the assigned channel.

Table 2: 122. VIEW ALPHA Object Members

Methods

Name Clear() Refresh SetFocus()

Result

Purpose

NO RESULT Clear all lines from the Alpha TTY window. NO RESULT Refreshes the display of the gadget. NO RESULT Set the keyboard immediately to this gadget. focus Alpha

removeRequests()

NO RESULT Deletes the requests channel from the alpha view gadget, and dissociates it from the current PDMS Requests IOchannel if necessary. STRING Get Background Colour Name. Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..

Background()

Table 2: 123. VIEW ALPHA Object Methods

2007 AVEVA Solutions Ltd

2:172

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Command
The VIEW ... ALPHA command puts you into View Setup mode. You remain in View Setup mode until you use the EXIT command.
.-------------------------<-------------------------. / | (ALPha)--+- <vshap> -----------------------------------. | +- CHANNEL -+- COMMANDS -----------------------| | | - REQUESTS ------------------------ NL -* -- EXIT -->

Figure 2:68. Syntax Graph -22: Setting Up an ALPHA VIEW Object

2.5.65

VIEW Gadget: AREA View

Members

Name Limits

Type REAL ARRAY[4] Get/Set BOOLEAN Get/Set REAL Set

Purpose Get or set [x1,y1,x2,y2]. limits box

Borders Background Background Contents

Get or set borders ON (TRUE) or OFF (FALSE).

Get/ Get or set background Colour Number

STRING Set Set background Colour Name. Only REAL ARRAY[2] Get/Set STRING Get/Set REAL Only REAL Set Get or set User contents ID.

Defcall Height Highlight Highlight Prompt Subtype Width

Get or set default interaction callback. Get Get view height. Get/ Get or set highlight Colour Number.

STRING Set Set highlight Colour Name Only GADGET Get/Set Get or set User Prompt PARAGRAPH gadget.

STRING Get Get subtype of graphic view. Only REAL Only Get Get view width.

Table 2: 124. VIEW AREA Object Methods

2007 AVEVA Solutions Ltd

2:173

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Background() Clear() Highlight() Refresh() RestoreView(REAL storeNumber) SaveView(REAL storeNumber)

Result STRING

Purpose Returns the highlight colour as a name string.

NO RESULT Clear VIEW contents STRING Returns the highlight colour as a name string.

NO RESULT Refreshes the display of the gadget NO RESULT Restores the saved VIEW with the given store number. NO RESULT Saves the current VIEW. The number must be in the range 1 to 4. NO RESULT Set VIEW size.

SetSize(REAL width, REAL height)

Table 2: 125. VIEW AREA Object Methods

Command
The VIEW ... AREA command puts you into View Setup mode. You remain in View Setup mode until you use the EXIT command.
.-------------------------<------------------------. / | (AREa) --+- <vshap> -----------------------------------. | +- PUT - <sgid> ------------------------------| | +- LIMits <uval> <uval> - TO - <uval> <uval> -| | +- SETColour - <colno> -----------------------| | +- SETHighlight - <colno> --------------------- NL -| +- <cursor> -----------------------------------------| +- <border> -----------------------------------------| +-- <pml> -------------------------------------------* -- EXIT --> Figure 2:69. Syntax Graph -: Setting Up an AREA VIEW Object

PDMSDRAFTwhere <sgid> is either CE (current element) or the name of a 2D graphical element (e.g., a DRAFT SHEET, VIEW, LIBRARY, etc.) and <colno> is any valid DRAFT colour definition.

2007 AVEVA Solutions Ltd

2:174

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

And <cursor> is the syntax for selecting the cursor type, as follows:
>-- CURSortype ---+-+-+-+-POINTER ----. NOCURSOR ---| PICK -------| PICKPLUS ---|

-- CROSSHAIR ----> Figure 2:70. Syntax Graph -: Setting Up the Cursor Type

<border> allows control of zooming and panning:

>--- BORDers --+-- ON --. -- OFF ----> Figure 2:71. Syntax Graph -: Setting Up the Border

2.5.66

VIEW Gadget: PLOT View

Members

Name Background Background Borders Contents

Type REAL Set

Purpose Get/ Get or set background Colour Number. Colour

STRING Set Set background Only Name. BOOLEAN Get/Set REAL ARRAY[2] Get/Set STRING Get/Set REAL Only REAL Set

Get or set borders ON (TRUE) or OFF (FALSE). Get or set User Contents ID.

Defcall Height Highlight Highlight Prompt Subtype Width

Get or set default interaction callback. Get Get view height.

Get/ Get or set highlight Colour Number.

STRING Set Set highlight Colour Name. Only GADGET Get/Set Get or set User Prompt PARAGRAPH gadget.

STRING Get Get subtype of graphic view. Only REAL Only Get Get view width.

Table 2: 126. VIEW PLOT Object Members

2007 AVEVA Solutions Ltd

2:175

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Methods

Name Add(STRING)

Result

Purpose

NO RESULT Add plot file with name given by STRING. Replaces given plot file if any. STRING Returns the background colour as a name STRING.

Background() Clear() Highlight() Refresh() SetSize(REAL width, REAL height)

Table 2: 127. VIEW PLOT Object Methods

NO RESULT Clear gadget contents STRING Returns the highlight colour as a name STRING.

NO RESULT Refreshes the display of the gadget NO RESULT Set view size.

Command
The VIEW ... PLOT command puts you into View Setup mode. You remain in View Setup mode until you use the EXIT command.
.-------------------------<------------------------. / | (PLOT) --+- <vshap> -----------------------------------. | +- ADD - plot_filename -----------------------| | +- CLear -------------------------------------| | +- SETColour - <colno> -----------------------| | +- SETHighlight - <colno> --------------------- NL -| +- <cursor> -----------------------------------------| +- <border> -----------------------------------------| +-- <pml> -------------------------------------------* -- EXIT --> Figure 2:72. Syntax Graph -: Setting Up a PLOT VIEW Object

where: <colno> is any valid PDMS colour definition. <cursor> is the syntax for selecting the cursor type, as in 2-19 <border> allows control of zooming and panning as in 2-20

2007 AVEVA Solutions Ltd

2:176

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.67

VIEW Gadget: VOLUME Views

Members

Name Background Background Contents

Type REAL Set

Purpose Get/ Get or set Background Colour Number Colour

STRING Set Set Background Only Name. REAL ARRAY[2] Get/Set STRING Get/Set REAL Only REAL Set

Get or set User Contents ID.

Defcall Height Highlight Highlight Prompt Subtype Width Borders Direction

Get or set default interaction callback. Get Get View Height.

Get/ Get or set Highlight Colour Number.

STRING Set Set Highlight Colour Name. Only GADGET Get/Set Get or Set User Prompt paragraph gadget.

STRING Get Get Subtype of graphic view. Only REAL Only Get Get View Width. Get or set Borders ON (TRUE) or OFF (FALSE). Direction vector [dE,dN,dU].

BOOLEAN Get/Set REAL ARRAY[3] Get/Set BOOLEAN Get/Set REAL ARRAY[6] Get/Set STRING Get/Set STRING Get/Set

EyeMode Limits

TRUE for Eyemode FALSE for Modelmode. Limits [E1,E2,N1,N2,U1,U2]. 'ZOOM', WALK'. 'PAN', box

Mousemode Projection

'ROTATE', or

PERSPECTIVE PARALLEL.

2007 AVEVA Solutions Ltd

2:177

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Name Radius Range Refresh RestoreView SaveView Shaded Step Through

Type REAL Set REAL Set

Purpose Get/ View Radius distance >0. Get/ Range distance >0.

NO RESULT Refreshes the display of the gadget. REAL Set REAL Set Get/ Restores view saved given view number. as

Get/ Saves view as given view number, in the range 1 to 4. TRUE for shaded FALSE for wireline.

BOOLEAN Get/Set REAL Set

Get/ Step size >0. Through point [E,N,U].

REAL ARRAY[3] Get/Set BOOLEAN Get/Set STRING Get/Set

WalkThrough LabelStyle

TRUE for Walkthrough (equivalent to Eyemode). Set by specifying ENU or XYZ. Default is ENU.

Table 2: 128. VIEW VOLUME Members

Methods

Name Background() Highlight() SetSize(REAL width, REAL height) RestoreView(REAL storeNumber) SaveView(REAL storeNumber)

Result STRING STRING

Purpose Returns the BACKGROUND colour as a name string. Returns the HIGHLIGHT colour as a name string.

NO RESULT Set view size. NO RESULT Restores view saved given view number. as

NO RESULT Saves view as given view number.

Table 2: 129. VOLUME VIEW Object Methods

2007 AVEVA Solutions Ltd

2:178

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

Command
The VIEW ... VOLUME command puts you into View Setup mode. You remain in View Setup mode until you use the EXIT command.

(VOLume)--+-- LOok --+-- <dir> ---------------------. | |-- THRough---. | | |-- FROM -----| | | -- TOWards --+-- <pos> ----. | | |-- <gid> ----| | | -- ID @ NL ----| +-- ISOmetric --+-- value --. | | ------------------------| +-- PLAN ---------------------------------| +-- ELEVation -- (one of N/S/E/W/X/Y) ----| +-- CLIPping -----+-- ON --. | | -- OFF ---------------| +-- CAPping ------+-- ON --. | | -- OFF ---------------| +-- PERSPective --+-- ON --. | | -- OFF ---------------| +-- WALKthrough --+-- ON --. | | -- OFF ---------------| +--RADius --- value ----------------------| +--STEP ----- value ----------------------| --RANGE ---- value ------------------------->
Figure 2:73. Syntax Graph -: Setting Up a VOLUME VIEW Object

Where: <colno> is any valid DESIGN colour definition; either a colour description or a colour number <cursor> is the syntax for selecting the cursor type, as in 2-19 <border> allows control of zooming and panning as in 2-20

Default:

Borders:ON; Shading OFF. View direction:PLAN or LOOK DOWN. Limits: AUTO (set to current view limits).

2007 AVEVA Solutions Ltd

2:179

12.0

Software Customisation Reference Manual

Summary of Objects, Members and Methods

2.5.68

XYPosition Object
Members

Name X Y

Type REAL Get/Set REAL Get/Set

Purpose X component of 2D POSITION. Y component of 2D POSITION.

Table 2: 130. XYPOSITION Object Members

Methods

Name XYposition() String()

Result

Purpose

XYPOSITION Creates an XYPOSITION at the given coordinates. STRING Returns a XYPOSITION as a STRING.

Table 2: 131. XYPOSITION Object Methods

2007 AVEVA Solutions Ltd

2:180

12.0

Software Customisation Reference Manual

Communicating with Review

Communicating with Review

This chapter describes the sample application provided with Review, and should be read in conjunction with the Review User Guide, where the commands available from the command line for controlling Review are explained. It also explains the responses to these commands that may be returned from Review. The Review commands available constitute a subset of the full Review functionality, together with some special commands for sending commands in batches. Note: Where primary element is referred to in this Appendix, this means an element that can be claimed.

A.1

Invoking the Command Line Interface

You invoke the command line interface in Review via the Applications icon in the Review user interface.

A.2

Directing Commands to Review

In order to direct any command line to Review, prefix the line with the command Review The remaining part of the line may be: A command sequence for controlling one or more of Reviews functions; An instruction to send one or more preceding command lines to Review. This prefix is incorporated into all commands described in the remainder of this chapter.

A.3

Sending Commands to Review

You may send command lines to Review in one of two ways: Automatically, as soon as the newline character is entered to terminate the command line; In batch mode, by entering an explicit instruction to send one or more previously entered command lines

Review refreshes its display every time a received instruction has been completely processed, which can make the automatic sending of each command line inefficient

2007 AVEVA Solutions Ltd

A:1

12.0

Software Customisation Reference Manual

Communicating with Review

compared with batch mode operation (where the display is refreshed only once for the whole command sequence). Review Command Review AUTOsend ON Review AUTOsend OFF Description Automatically send commands line-by-line. Stop sending the commands automatically and revert to batch mode (which is the default). Pass a batch of commands to Review explicitly (valid only with Autosend mode Off). This command will send all command lines that have been entered since the preceding Review SEND command. Consider, for example, the following command lines (which are numbered for reference purposes only): 1. Review MATERIAL 1 RGB 10 10 10 2. Review ELEMENT /C1101 MATERIAL 1 3. Review SEND 4. Review ELEMENT /C1002 MATERIAL 1 5. Review SEND By default, batch mode is in operation (i.e. Autosend mode is Off). Therefore lines 1 and 2, which hold Review functional commands, are not passed to Review until the explicit command to do so is given in line 3. Similarly, the command in line 5 causes line 4 (only) to be passed to Review.

Review SEND

A.4

Errors from the Application-to-Review Link

The error messages below come from one of the two the following sources, rather than from the results of the commands themselves.

Problems with the Application Module

(79, 101) (79, 102)

Environment variable CADC_IPCDIR unset Cannot start communications: error

2007 AVEVA Solutions Ltd

A:2

12.0

Software Customisation Reference Manual

Communicating with Review

Problems with the Communications Link between Applications and Review

(79, 201) Commands sent automatically as AUTOSEND is enabled (79, 202) Cannot connect to Review: error (79, 203) Cannot start command transfer to Review: error (79, 204) No commands to send to Review (79, 205) Cannot send commands to Review: error (79, 206) Cannot end transfer to Review: error (79, 207) Cannot start transfer from Review: error (79, 208) Cannot receive reply from Review: error (79, 209) Cannot receive the error message from Review: error

A.5

Sample Application
Note: The sample application supplied is for demonstration purposes only. By default it uses flat files as the data source. Note also that you should cancel the Login form displayed when the demonstration application is run. The first stage of the sample application is concerned with progress monitoring, covering both the design and construction phases. It uses the sample model to give a clear presentation of the current status of the project, which is particularly useful during concurrent design and construction. The second stage focuses on extracting a range of engineering data available from the model, including the display of P&IDs, vendor drawings and scanned images, data sheets, and reports. The third part of the application focuses on the operating life of the plant, such that items requiring maintenance can be interrogated by reference to a timebase. Maintenance history can be studied for past problems and recommendations; maintenance procedures can be displayed to show the scope of the work involved. Cost-benefits can be seen by obtaining the isolation group associated with a given element; for example, the Main Separator Tower may be highlighted together with an adjacent control valve which is to be maintained at the same time. A set of fully documented forms and macros are supplied to support these engineering applications, based around the Stabiliser model. These applications are summarised in more detail in the following sections.

A.6

Progress Monitoring
The Progress Monitoring application is based on the need to view different engineering disciplines of a plant that are at various stages of completion. Relevant information can then be displayed and highlighted within Review. The engineering disciplines recognised by the application are:

2007 AVEVA Solutions Ltd

A:3

12.0

Software Customisation Reference Manual

Communicating with Review

Piping Mechanical Vessels Structural Instruments

For each discipline, the completion status, each of which is displayed within Review in a different colour, may be any of the following: Completion Status Preliminary Design Final Design Fabricated Erected Tested Display Colour Green Cyan Blue Purple Brown

A.6.1

Engineering Data
The Engineering Data application is based on the need to derive engineering data which relates to a graphical element selected within the Review display; for example: Purchase order data; Descriptions; Document availability and viewing capability; Once these data have been supplied, a further selection can be made to display related documents and drawings through other applications. Examples supplied will allow access to plotfiles, ASCII and scanned image files.

The Maintenance application is based on the need to view different types of plant element which require maintenance at different time intervals. Maintenance activities can then be selected for further data analysis and display within Review. The types of design element recognised by the application are: Vessels Exchangers Mechanical Instruments All

For each element type, the maintenance interval, specified in terms of the date when maintenance is next due, may be any of the following: Overdue Due today Due next week Due next month

2007 AVEVA Solutions Ltd

A:4

12.0

Software Customisation Reference Manual

Communicating with Review

When applied for a selected Element Type and Due On, all available data will be displayed to show which elements require maintenance and when. These elements can then be selected for further maintenance enquiries by selecting one or more the following options: Maintenance schedule Maintenance history Parts inventory Isolation list

A.7

Using the Sample Application

First ensure that all software has been installed as explained in the Review Installation Guide. Then open a window and type:

% run_demo
Review will load its graphics and the sample model onto the screen. Click on the Applications icon to start the demonstration. The icon should look like the one below:

You will then see a Data Server Login form, which you should cancel for this flat file demonstration. Note: The file run_demo is located under the demo directory where the software was installed. Read the rvq_docs/README file for hints on how (if youre an experienced Query Toolkit user) you can customise the application for use with an external database.

A.7.1

Progress Monitoring
Select Applications>Progress Monitoring A form will be displayed, as shown in Figure A:1.: Progress Monitoring form, to enable you to access data relevant to the completion status for a particular discipline.

Figure A:1.

Progress Monitoring form

Use the two option gadgets on this form to set the required combination of design Discipline (e.g. Piping) and corresponding completion Status (e.g. Erected). Click the Apply button to highlight items meeting the selection criteria within the Review model. Different colours will be used for the various Status options.

2007 AVEVA Solutions Ltd

A:5

12.0

Software Customisation Reference Manual

Communicating with Review

Click the Make Display Translucent button to reset all materials in the Review display to translucent to enable different Discipline and Status combinations to be selected and viewed.

Progress Monitoring Examples

Select and then apply the following combinations: Combination Discipline=Piping and Status=Erected Discipline=Vessels and Status=Delivered Discipline=Vessels and Status=Installed Discipline=Structural and Status=Erected Discipline=Instr/Elect and Status=Fabricated Discipline=Mechanical and Status=Tested Result Pipes are displayed in purple Vessels are displayed in blue Vessels are displayed in purple Steelwork is displayed in purple Instrument Cabinets are displayed in blue* Pumps are displayed in brown*

* To get the best display, Select Look > ISO > One from the Review bar menu.

A.7.2

Engineering Data
Select Applications > Engineering Data. A form will be displayed, as shown in Figure A:2.: Engineering Data form, to enable you to extract engineering data relevant to the model. In the Review display, select the central upright vessel (/C1101) using the cursor and lefthand mouse button. Now select the Name field on the Engineering Data form and paste in the name of the selected vessel by clicking the right-hand mouse button.

Figure A:2.

Engineering Data form

2007 AVEVA Solutions Ltd

A:6

12.0

Software Customisation Reference Manual

Communicating with Review

Click the Apply button to display data for the specified vessel against the headings Purchase Order and Description. A list of associated documents will be shown under the Document and Description headings. To display such a document, first select the line for that document in the scrollable list and then click the View Document button. The resulting document display may be: a text file, using the system editor; a plotfile representation of orthogonal views of a drawing; a scanned image of a drawing.

Note: Any external application may be used to display documents. Any number of documents may be selected simultaneously for viewing.

Document Examples
Names can be selected graphically or by entering an explicit name. Name: /C1101 Fabrication Drawing P&ID sheets 1-3 /P1501A 2D Drawing Bill of materials Cable List Report Displays a set of orthogonal views. Displays a BOM report for Pump P1501A. Displays a cable connection list report. Displays a plotfile of the Main Separation Tower. Each displays a P&ID plotfile.

D1537851 DPL123 Name:

D8428797 D43173298 ER3245-001 Name: /V-70

D7862134

Cross Sectional View

Displays a scanned image of a valve.

A.7.3

Maintenance
Select Applications > Maintenance. A form will be displayed, as shown in Figure A:3.: General Maintenance Form, to enable you to access data relating to those items which require maintenance within specific time periods.

2007 AVEVA Solutions Ltd

A:7

12.0

Software Customisation Reference Manual

Communicating with Review

Figure A:3.

General Maintenance Form

Use the two option gadgets on this form to set the required combination of item Type (e.g. Vessels) and time when next maintenance operation is due, shown as Due When (e.g. Due in next week). Click the Apply button to highlight items meeting the selection criteria within the Review model. To make it easier to see the selected item in the Review display, click the Setup camera view button. This sets up Camera One such that the through point is at the item of interest, with a field of view of 60. The Name, Description and Inspection Date for each relevant item will be listed on the form under the corresponding headers. To obtain detailed maintenance data for any item, select the item in the scrollable list and then click the appropriate button under the heading Further data for selected item. The data available come under the following headings: Maintenance Schedule Maintenance History Parts Inventory Isolation List

Maintenance Schedule
The Maintenance Schedule form, as illustrated in Figure A:4.: The Maintenance Schedule Form, allows you to view the maintenance procedures that have been generated for a named model item.

2007 AVEVA Solutions Ltd

A:8

12.0

Software Customisation Reference Manual

Communicating with Review

Figure A:4.

The Maintenance Schedule Form

To display any of the maintenance procedures listed for the current item, select the procedure in the scrollable list and then click the View Procedure button. The selected report will be displayed (in read-only mode) to show details of the maintenance procedures. To list the available maintenance procedures for a different model item without returning to the General Maintenance form, enter the new item name and click the Apply button.

Maintenance History
The Maintenance History form, as illustrated in Figure A:5.: Maintenance History Form, allows you to view the maintenance history reports that have been generated for a named model item. To display any of the maintenance reports listed for the current item, select the report in the scrollable list and then click the View Report button. The selected report will be displayed (in read-only mode) to show details of the maintenance history. To list the available maintenance reports for a different model item without returning to the General Maintenance form, enter the new item name and click the Apply button.

2007 AVEVA Solutions Ltd

A:9

12.0

Software Customisation Reference Manual

Communicating with Review

Figure A:5.

Maintenance History Form

Parts Inventory
The Parts Inventory form, illustrated in Figure A:6.: Parts Inventory Form, allows you to view supplier details that have been generated for a named model item.

Figure A:6.

Parts Inventory Form

To display details of any part listed for the current item, select the part in the scrollable list and then click the Supplier Details button. Supplier information for the selected part will be displayed (in read-only mode). To list the available supplier details for a different model item without returning to the General Maintenance form, enter the new item name and click the Apply button.

2007 AVEVA Solutions Ltd

A:10

12.0

Software Customisation Reference Manual

Communicating with Review

Isolation List
The Isolation List form, illustrated in Figure A:7.: Isolation List Form, allows you to view details of maintenance isolation lines that have been generated for a named model item.

Figure A:7.

Isolation List Form

The scrollable list shows all associated items which make up the isolation line related to the current item. The complete isolation line will be highlighted in the Review display. To list the isolation line details for a different model item without returning to the General Maintenance form, enter the new item name and click the Apply button.

A.8

Summary of the Application Data

As a guide to the data available within the example supplied, the following tables show the data which may be extracted by using the various applications.

A.8.1

Progress Monitoring

Piping Preliminary Final Design Fabricated Erected Tested Delivered no yes yes yes yes n/a

Mech. no no n/a n/a yes no

Vessels no no n/a n/a yes yes

Civil no no n/a n/a n/a n/a

Structural no no no yes yes n/a

HVAC no no no no no n/a

Instr./ Elec. no No Yes Yes No n/a

2007 AVEVA Solutions Ltd

A:11

12.0

Software Customisation Reference Manual

Communicating with Review

Piping Installed Excavated Foundations Oversite n/a n/a n/a n/a

Mech. no n/a n/a n/a

Vessels yes n/a n/a n/a

Civil yes no no yes

Structural n/a n/a n/a n/a

HVAC n/a n/a n/a n/a

Instr./ Elec. n/a n/a n/a n/a

A.8.2

Engineering Data
The engineering data extracted from the data source (flat file or database tables) is based on the following PDMS elements: /C1101 /P1502A /V-70 Main Separator Tower Secondary Backup Pump Manual Shutdown Valve

A.8.3

Maintenance
Vessels

Overdue Primary data Schedule History Parts inventory Isolation list no no no no no

Due today no no no no no

Due next week yes yes yes yes yes

Due next month yes yes yes yes yes

Exchangers

Overdue Primary data Schedule History Parts inventory Isolation list no no no no no

Due today no no no no no

Due next week no no no no no

Due next month yes no no no no

2007 AVEVA Solutions Ltd

A:12

12.0

Software Customisation Reference Manual

Communicating with Review

Mechanical

Overdue Primary data Schedule History Parts inventory Isolation list yes no no no no

Due today yes no no no no

Due next week yes no no no no

Due next month yes no no no no

Instruments

Overdue Primary data Schedule History Parts inventory Isolation list no no no no no

Due today no no no no no

Due next week no no no no no

Due next month yes no no no no

All

Overdue Primary data Schedule History Parts inventory Isolation list yes no no no no

Due today yes no no no no

Due next week yes yes yes yes yes

Due next month yes yes yes yes yes

2007 AVEVA Solutions Ltd

A:13

12.0

Software Customisation Reference Manual

Communicating with Review

Most of the data extracted from the data source (flat file or database tables) is based on the following PDMS elements: /C1101 /P1502A /V-70 /E1301 V121 Main Separator Tower. Secondary Backup Pump. Manual Shutdown Valve. Storage Tank. Manual Shutdown Valve

There are instances where data extracted is not consistent with that of the model. In such cases the following message will be displayed:

data ignored not in Review model

A.9

Application Files Supplied

For convenience, the sample application files are supplied under a function-related directory hierarchy, thus:

Figure A:8.

Hierarchy of Supplied Application Files

These directories and files have the following functions: ADMIN PROGRESS ENGDATA MAINTAIN DATA run_demo A general directory for startup and initialisation of Query. A directory for the progress monitoring applications. A directory for the engineering data applications. A directory for the maintenance applications. A directory containing data for use by the applications. A script to run the Review demonstration application.

The names of many of the files begin with a prefix which indicates the files function, thus: F M U I Denotes a form definition. Denotes a macro definition. Denotes a utility macro. Denotes a form initialisation macro.

All other filenames denote general files which are not specifically used in creating forms.

2007 AVEVA Solutions Ltd

A:14

12.0

Software Customisation Reference Manual

Communicating with Review

A.9.1

ADMIN Directory

File CONFIG FORACLE FSYSTEM FVERSION IORACLE IVERSION MORACLE MVERSION RPODESC START UCAMERA UORACLE UQUIT URESET UVIEWDOC VAR2ENV

Purpose User-specified configuration; e.g. database server node Form definition macro for RDBMS connection Form definition macro for main system menu Form definition macro for versions Initialisation macro for RDBMS connection Initialisation macro for versions Result macro for RDBMS connection Result macro for versions Utility macro to set purchase order number and description Query start-up macro Utility macro to set up camera 1 Utility macro to invoke RDBMS connection form Utility macro to quit Query Utility macro to reset observer materials Utility macro to view documents (plotfiles and other formats) Utility macro to convert %Variable% to environmental variable

A.9.2

ENGDATA Directory

File FENGDATA FPLOTVIEW IENGDATA MENGDATA UNEXTPLOT UPREVPLOT

Purpose Form definition macro for engineering data. Form definition macro for plotfile viewer. Initialisation macro for engineering data. Result macro for engineering data. Utility macro to view next plot. Utility macro to view previous plot.

2007 AVEVA Solutions Ltd

A:15

12.0

Software Customisation Reference Manual

Communicating with Review

A.9.3

PROGRESS Directory

File FPROGRESS IPROGRESS MPROGRESS UDISCIP UTRANSLU

Purpose Form definition macro for progress monitoring. Initialisation macro for progress monitoring. Result macro for progress monitoring. Utility macro to set status list for selected discipline. Utility macro to make display translucent.

A.9.4

MAINTAIN Directory

File FHISTORY FINVENT FISOLATE FMAINTAIN FSCHEDULE FSUPPLY IHISTORY IINVENT IISOLATE IMAINTAIN ISCHEDULE ISUPPLY MHISTORY MINVENT MISOLATE MMAINTAIN MSCHEDULE UMSHOW

Purpose Form definition macro for maintenance history. Form definition macro for parts inventory. Form definition macro for isolation list. Form definition macro for maintenance requirements. Form definition macro for maintenance schedule. Form definition macro for supplier details. Initialisation macro for maintenance history. Initialisation macro for parts inventory. Initialisation macro for isolation list. Initialisation macro for maintenance requirements. Initialisation macro for maintenance schedule. Initialisation macro for supplier details. Result macro for maintenance history. Result macro for parts inventory. Result macro for isolation list. Result macro for maintenance requirements. Result macro for maintenance schedule. Utility macro to show and apply one of the maintenance forms.

2007 AVEVA Solutions Ltd

A:16

12.0

Software Customisation Reference Manual

Communicating with Review

A.9.5

DATA Directory

File DOCDATA NAMEDATA SUPPLIERDATA ISOLATEDATA PARTSINVDATA MAINHDATA MAINSDATA MAINTDATA PROGRESSDATA oracle_data

Purpose Document data for engineering application Element names against description data Supplier data containing names, addresses and telephone No. Isolation elements against primary element data Parts inventory and supplier names against element data Maintenance history data and reports against element data Maintenance service data and reports against element data Maintenance schedules and due dates against element data Progress monitoring data type against completion state An ORACLE data file in the form of tables for loading into ORACLE. Table contents and names are consistent with those of the above flat files. A Shell script for loading demo tables into Sybase RDBMS. Table contents and names are consistent with those of the above flat files. Plotfile of 2D drawing of the Stabiliser Maintenance report Maintenance report Maintenance report Maintenance report Maintenance report Electrical drawing plotfile Electrical drawing plotfile Valve specification Pump bill of materials Plotfile of 2D drawing of Pump Electrical cable list report (PEGS-generated) Electrical panel report (PEGS-generated) Process flow diagram plotfile P&ID sheet 1 for plant P&ID sheet 2 for plant

sybase_data.ksh

C1101.plot C1101020592.asc C1101091092.asc C1101111091.asc C1101121089.asc C1101141090.asc EI3245.plot EI3246.plot V-70.spec P1501A.bom P1501A.plot cablelist..rep panel.rep pfd.plot pid1.plot pid2.plot

2007 AVEVA Solutions Ltd

A:17

12.0

Software Customisation Reference Manual

Communicating with Review

File pid3.plot v-70.tif xtiff

Purpose P&ID sheet 3 for plant Scanned image of a valve (sectioned drawing) Utility to display scanned images

2007 AVEVA Solutions Ltd

A:18

12.0

Software Customisation Reference Manual

PML 1 Expressions

PML 1 Expressions
This appendix explains the PML 1 expressions package. These facilities are needed within AVEVA products, for example, to define report templates in PDMS. Note: Generally, all these facilities are compatible with PML 2. Expressions have types. For example, you can have numeric expressions, text expressions and logical expressions. All the elements in an expression must be of the correct type. For example, if you have a two numbers, x and y, and two text strings text1 and text2, the following expression is meaningless:

x + text1

However, both of the following expressions are valid:

x + y Text1 + text2

$ adds the values of the numeric variables. $ concatenates the two text strings.

The following types of expressions are available: Expression Logical expressions Logical array expressions Real expressions Real array expressions Text expressions Reference See Section C.2. See Section C.2.3 See Section C.3 See Section C.3.3 See Section C.6

B.1

Format of Expressions
The format of an expression, for example the use of brackets, spaces and quotes, is important. If you do not follow the rules given below you will get error messages: Text must be enclosed in quotes. For example:

This is text

2007 AVEVA Solutions Ltd

B:1

12.0

Software Customisation Reference Manual

PML 1 Expressions

There must be a space between each operator and operand. For example:

x + y
Use round brackets to control the order of evaluation of expressions and to enclose the argument of a function. For example:

SIN(30)
In general, you do not need spaces before or after brackets, except when a PDMS name is followed by a bracket. If there is no space, the bracket will be read as part of the name. For example:

(NAME EQ /VESS1 )

B.1.1

Operator Precedence
Operators are evaluated in the order of the following list: the ones at the top of the list are evaluated first. Operator BRACKETS Comments Brackets can be used to control the order in which operators are evaluated, in the same way as in normal arithmetic

FUNCTIONS */ +EQ, NEQ, LT, LE, GE, GT NOT AND OR

B.1.2

Nesting Expressions
Expressions can be nested using brackets. For example:

( (SIN(!angleA) * 2)

SIN(!angleB) )

B.2

Logical Expressions
Logical expressions can contain: PDMS attributes of type logical e.g. BUILT. Logical constants. The constants available are: TRUE, ON, YES for true, and FALSE, OFF, NO for false.

2007 AVEVA Solutions Ltd

B:2

12.0

Software Customisation Reference Manual

PML 1 Expressions

Logical operators. Logical functions.

B.2.1

Logical Operators
The logical operators available are: Operator AND EQ, NE GT, GE, LE, LT The operators EQ and NE may be applied to any pair of values of the same type. The operators GE, LE, GT and LT may only be used with numbers and positions. For more information, see Section C.5, Using Positions, Directions and Orientations in Expressions. Comments

NOT OR Note: The operators EQ, NE, LT, GT, LE and GE are sometimes referred to as comparator or relational operators; NOT, AND and OR are sometimes referred to as Boolean operators. See also Section C.11, Precisions of Comparisons for tolerances in comparing numbers.

AND

Synopsis Description Side Effects Example

log1 AND log2

-> logical

Perform the logical AND between two logical values. Treats unset values as FALSE. If one of the values is undefined and the other one is FALSE, the result is FALSE. TRUE and FALSE -> FALSE

2007 AVEVA Solutions Ltd

B:3

12.0

Software Customisation Reference Manual

PML 1 Expressions

EQ and NE

Synopsis

( number1 EQual number2) ( text1 EQual text2 ) ( log1 EQual log2 ) ( id1 EQual id2 ) ( pos1 EQual pos2 ) ( dir1 EQual dir2 ) ( ori1 EQual ori2 ) ( pp1 EQual pp2 ) ( number1 NEqual number2 ) ( text1 NEqual text2 ) ( log1 NEqual log2 ) ( id1 NEqual id2 ) ( pos1 NEqual pos2 ) ( dir1 NEqual dir2 ) ( ori1 NEqual ori2 ) ( pp1 NEqual pp2 )

-> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical -> logical

Description

Compare two values. A special feature is used for the positions, only the coordinates specified are compared. See Section C.5.4 for more information. Unset values result in FALSE across EQ, TRUE across NE. If two positions have no common coordinate, for example, N 10 ne U 10, the result is undefined. Units are consolidated across comparisons.

Side Effects

Example Errors

( 1.0 eq 2.0) -> FALSE

None.

2007 AVEVA Solutions Ltd

B:4

12.0

Software Customisation Reference Manual

PML 1 Expressions

GT, GE, LE and LT

Synopsis

( number1 GT number2 ) ( pos1 GT pos2 ) ( number1 GE number2 ) ( pos1 GE pos2 ) ( number1 LE number2 ) ( pos1 LE pos2 ) ( number1 LT number2 ) ( pos1 LT pos2 )

> logical > logical > logical > logical > logical > logical > logical > logical

Description

Compare two values. A special feature is used for positions: only the coordinates specified are compared. See Section C.5.4 for more information. For positions, since comparisons may be performed on more than one value, LT (GT) is not the inverse of GE (LE). Unset values result in false If two positions have no common coordinate, the result is undefined. For example, N 10 gt U 10. Units are consolidated across comparisons.

Side Effects

Example

( 1.0 LT 2.0) -> TRUE ( N 0 E 10 GT N 10 E 0 ) -> FALSE ( N 0 E 10 GT N 10 E 0 ) -FALSE

None.

Errors

NOT

Synopsis Description Side Effects Example Errors

NOT log1

-> logical

Perform the logical NOT on a logical value. None.

not TRUE -> FALSE

None.

2007 AVEVA Solutions Ltd

B:5

12.0

Software Customisation Reference Manual

PML 1 Expressions

OR

Synopsis Description

OR log2

-> logical

Perform the logical inclusive OR between two logical values. (The exclusive OR is defined by using NE.) Allows numbers instead of logical values.

Side Effects Example Errors

If one of the values is undefined and the other one is TRUE, the result is TRUE.

TRUE or FALSE -> TRUE

None.

B.2.2

Logical Functions
The logical functions available are: Function BADREF DEFINED,UNDEFINED CREATED DELETED EMPTY MATCHWILD MODIFIED UNSET VLOGICAL Comments

BADREF

Synopsis Description Side Effects Example Errors

BADREF (id)
TRUE if id is invalid, else FALSE. None

-> logical

BADREF(TREF)
None.

->

true if TREF=nulref

2007 AVEVA Solutions Ltd

B:6

12.0

Software Customisation Reference Manual

PML 1 Expressions

DEFINED and UNDEFINED

Synopsis

DEFined (variable_name) DEFined (variable_name,number) UNDEFined (variable_name) UNDEFined (variable_name , number)

-> logical -> logical -> logical -> logical

Description

With one argument, DEFINED is true only if the scalar variable, the array variable or the array variable element exists. With two arguments, DEFINED is true only if the first argument is an array variable which has a value for the index denoted by the second argument.

UNDEFINED( !foo ) is equivalent to NOT DEFINED( !foo ).

Side Effects Example None.

DEFINED ( DEFINED ( DEFINED ( DEFINED ( DEFINED ( UNDEFINED DEFINED (

None.

!var ) -> TRUE !array ) -> TRUE !array[1] )) -> TRUE !array , 1 ) -> TRUE !var) -> FALSE ( !array) -> TRUE !array , 3 ) -> FALSE

Errors

CREATED

Synopsis Description Side Effects Example Errors

CREATED

-> logical

Returns TRUE if the element has been created since the set date. None.

CREATED -> TRUE

None.

2007 AVEVA Solutions Ltd

B:7

12.0

Software Customisation Reference Manual

PML 1 Expressions

DELETED

Synopsis Description Side Effects Example Errors

DELETED

-> logical

Returns TRUE if the element has been deleted since the set date. None.

DELETED -> TRUE

None.

EMPTY

Synopsis Description Side Effects Example

EMPTY(text)

-> logical

Returns TRUE if text is a zero length string, else FALSE None.

EMPTY() -> TRUE EMPTY(not empty) -> FALSE

None.

Errors

MATCHWILD

Synopsis

MATCHW/ILD( text1, text2) MATCHW/ILD( text1, text2, text3) MATCHW/ILD( text1, text2, text3, text4)

-> logical -> logical -> logical

Description

Matches string text2 to string text1. If they are the same then returns TRUE, else FALSE. text2 may contain wildcard characters. The defaults for wildcards are * for any number of characters, and ? for a single character. With three arguments, the multiple wildcard character * may be redefined by text3. With four arguments the single wildcard character ? may be redefined by text4.

Side Effects

None

2007 AVEVA Solutions Ltd

B:8

12.0

Software Customisation Reference Manual

PML 1 Expressions

Example

MATCHW/ILD(A big bottle of beer,*big*) -> TRUE MATCHW/ILD(A big bottle of beer,??big*) -> TRUE MATCHW/ILD(A big bottle of beer,???*big*) -> FALSE MATCHW/ILD(A big bottle of beer,*big*beer) -> TRUE MATCHW/ILD(** text,**!,!) -> TRUE
None.

Errors

MODIFIED

Synopsis
.-----------------------------------. / | >- MODIFIED-(-+- attname -------*- DESCENDANTS --+-+-comma +-attname - | | | | |- DESCENDANTS -. |- SIGNIFICANT --| | | | | | | |- SIGNIFICANT--| |- PRIMARY ----- | | | | | | | |- PRIMARY -----| |- OFFSPRING-----| | | | | | | |- OFFSPRING ---| ---------------- | | | | | | | | | | ---------------+--------------------+--+-- ) - OF - id | -

Description

For sophisticated queries relating to modifications. Returns TRUE if a modification has taken place. Each attribute name may be followed by the following qualifying keywords: OFFSPRING, to check this element and members SIGNIF, to check all elements for which this element represents the significant one; PRIMARY, check all elements for which this element represents the primary one; DESCENDANTS, (descendants). this element and everything below

The OF syntax may be used as for attributes. The MODIFIED function or the GEOM, CATTEXT and CATMOD pseudo-attributes (see Appendix D.2.2.1) can be used instead of the AFTERDATE function.

2007 AVEVA Solutions Ltd

B:9

12.0

Software Customisation Reference Manual

PML 1 Expressions

The MODIFIED, DELETED and CREATED functions may go anywhere within a PDMS PML1 expression. i.e. after Q/VAR and within collections Side Effects Example None

Q MODIFIED()

Returns TRUE if element has changed at all since the comparison date. It will also return TRUE if the element has been created since the comparison date.

Q MODIFIED(POS,ORI)

Returns TRUE if POS or ORI modified since the comparison date. Returns TRUE if the position of P1 has changed. Returns TRUE if any geometry for item or any descendants has changed Returns TRUE if any element for which this element is primary, has changed. Returns TRUE if /PIPE1 has been modified since the comparison date.

Q MODIFIED(P1 POS) Q MODIFIED(GEOM DESCENDANTS Q MODIFIED(PRIMARY)

Q MODIFIED() OF / PIPE1 Q (BUIL OR MODIFIED()OR ELECREC OF NEXT )

Errors None.

The MODIFIED, DELETED and CREATED functions are not implemented within PML2 expressions.

UNSET

Synopsis Description

UNSET(value)

-> logical

Returns TRUE if value is unset, else FALSE. The value can be of any data type including ARRAYS. Normally it will be a PDMS attribute. None.

Side Effects

2007 AVEVA Solutions Ltd

B:10

12.0

Software Customisation Reference Manual

PML 1 Expressions

Example

UNSET( DESC ) UNSET(CRFA)

TRUE where DESC is an unset text attribute FALSE where CRFA contains unset reference attributes

Errors

None.

VLOGICAL
VLOGICAL is used for the late evaluation of variables.

Synopsis

VLOGICAL ( variable_name )) VLOGICAL ( variable_name , number)

-> logical -> logical

Description

With one argument, return the value of the scalar variable or the value of the array variable element as a logical. With two arguments, return the value of the element corresponding to the index number as a logical. The rules of conversion are: TRUE for the strings T, TR, TRU or TRUE (case insensitive) or any numeric value not equal to zero; FALSE for the strings F, FA, FAL, FALS or FALSE (case insensitive) or a numeric value equal to zero. Scalar variables may not be indexed. For example, VTEXT(!var[1]) will return an error. Array variables must have an index. For example, VTEXT (!array) will return an error. The value cannot be translated into a logical. See also VTEXT, used for late evaluation when a text result is required; and VVALUE, used for late evaluation when a numeric result is required.

Side Effects Example

If the scalar variable, the array variable, or the array variable element does not exist, the result is undefined.

VLOG ( !array[1] ) -> TRUE VLOG ( !array , 2 ) -> FALSE

None.

Errors

B.2.3

Logical Array Expressions

Logical array expressions can contain: PDMS attributes of type logical array. For example, LOGARR where LOGARR is a UDA of type logical.

2007 AVEVA Solutions Ltd

B:11

12.0

Software Customisation Reference Manual

PML 1 Expressions

Logical constants. The constants available are: TRUE, ON, YES for true; and FALSE, OFF, NO for false. Logical operators. See Logical Operators. Logical functions. See Logical Functions.

B.3

Numeric (Real) Expressions

In PDMS expressions, integers are treated as reals; they are fully interchangeable. Numeric expressions can contain: Numbers, for example: 32, 10.1. Numbers can be given as as integer exponents, for example: 10 exp 5, and 5 E 6. Numbers can contain units. The valid units are MM, M/ETRES, IN/CHES, and FT, FEET. These may be preceded by SQU/ARE, CUBIC, CUB/E to denote non-linear values. For example: 100 mm, 10 exp 5 cubic feet. Feet and inches can be shown as, for example, 106: PDMS attributes of type number, for example: XLEN. Position, direction and orientation attributes which have a subscript to indicate which part of the array is required. For example, POS[2] means the second element of the POSITION attribute; that is, the northing. Note that position, direction and orientation attributes without subscripts can only be used in number array expressions. The keyword PI (3.142). Numeric operators. Numeric functions.

B.3.1

Numeric (Real) Operators

The numeric operators available are: Operator + * / Comments Addition. Subtraction. Multiplication. Division.

B.3.2

ADD and SUBTRACT (+ and -)"

Synopsis

number + number number - number + number - number

-> number -> number -> number -> number

2007 AVEVA Solutions Ltd

B:12

12.0

Software Customisation Reference Manual

PML 1 Expressions

Description

Add or subtract two numbers. They can also be used as unary operators at the beginning of a parenthesised subexpression. Units are consolidated across add and subtract.

Side Effects Example

1 1 + -

+ 1 1

2 -> 3.0 2 -> 1.0 -> 1.0 -> -1.0

Errors

Floating point underflow.

B.3.3

MULTIPLY and DIVIDE (* and /)

Synopsis

number * number number / number

-> number -> number

Description

Multiply or divide two numbers. They can also be used as unary operators at the beginning of a parenthesised subexpression. Numeric underflow is not considered to be an error and neither is it flagged as a warning. The result returned is zero. Units are consolidated across Multiply and Divide.

Side Effects Example

2 * 3 -> 6.0 2 / 3 -> 0.666666666

Divide by zero.

Errors

B.3.4

Numeric (Real) Functions

The numeric functions available are:

Function

Comments Gives the absolute value of a number Gives the arc cosine of a number, in degrees. Gives the arc sine of a number, in degrees. Gives the arc tangent of a number, in degrees. Gives the arc tangent of number1/number2, in degrees, with the appropriate sign. Gives the exponential function (natural anti-log) of a number.

ABS ( number1 ) ACOS ( number1 ) ASIN ( number1 ) ATAN ( number1 ) ATANT ( number1, number2 ) ALOG ( number1 )

2007 AVEVA Solutions Ltd

B:13

12.0

Software Customisation Reference Manual

PML 1 Expressions

Function

Comments Converts a position, direction or orientation value or attribute into three numbers. Gives the size of an array variable. Gives the largest display width of any string in array variable-name. Gives the magnitude of a vector drawn from E0 N0 U0 to pos2, projected in the direction dir1. Gives the truncated integer value of a number. Gives the sine, cosine or tangent value of a number (considered to be in degrees). Gives the sine, cosine or tangent value of a number (considered to be in degrees). Gives the sine, cosine or tangent value of a number (considered to be in degrees). Gives the length of text1. Gives the length of text1. DLENGTH is used with characters which have a displayed width that is different from standard characters, such as Japanese. Gives the natural logarithm of a number. Gives the position of the beginning of the leftmost occurrence of text2 in text1. If text2 does not occur in text1, 0 is returned. Gives the position of the beginning of the leftmost occurrence of text2 in text1. If text2 does not occur in text1, 0 is returned. DMATCH is used with characters which have a displayed width that is different from standard characters, such as Japanese.

ARRAY(pos or dir or ori) ARRAYSIZE ( variable-name ) ARRAYWIDTH( variable-name ) COMPONENT dir OF pos2 INT ( number1 ) SIN ( number1 ) COS ( number1 ) TAN ( number1 ) LENGTH ( text1 ) DLENGTH ( text1 )

LOG ( number1 ) MATCH ( text1, text2 )

DMATCH ( text1, text2 )

MAX ( number1, number2[ , number3 [. . .]]) ) MIN ( number1, number2[ , number3 [. . .]]) ) NEGATE NINT ( number1 )

Gives the maximum value of the arguments. Gives the minimum value of the arguments. Multiply a number by -1.0. Gives the nearest integer to a real. NINT(N+0.5) is equal to N+1 if N is positive or equal to zero, to N if N is negative. Gives the number of times string text2 occurs in string text1. Try to read a number at the beginning of text1.

OCCUR ( text1, text2 ) REAL ( text1 )

2007 AVEVA Solutions Ltd

B:14

12.0

Software Customisation Reference Manual

PML 1 Expressions

Function

Comments Gives the value of number1 raised to the power number2. Gives the square root of a number. Used for late evaluation of variables. Gives a real value.

POWER ( number1, number2 ) SQRT ( number1 ) VVALUE ( variable-name )

ABS

Synopsis Description Side Effects Example Errors

ABS ( number1 )
Returns the absolute value of a real. None.

-> number

ABS ( -3.2 ) -> 3.2

None.

ACOS, ASIN, ATAN and ATANT

Synopsis

ASIN ( number1 ) ACOS ( number1 ) ATAN ( number1 ) ATANT ( number1, number2 )

-> number -> number -> number -> number

Description

Return the arc-cosine, arc-sine or arc-tangent of a number, in degrees. ATANT returns the arc-tangent of number1/number2 with the appropriate sign. ATANT is useful where the second value is near or equal to zero. For example, (6 0 ATANT) will give the correct result of 90 degrees, but (6 0 D ATAN) will indicate an error when trying to divide by zero.

Side Effects Example Errors

None.

ACOS ( 0.8660254 ) -> 30

Argument of ACOS or ASIN out of range [-1.0,+1.0] ATANT (0.0,0.0) is undefined.

2007 AVEVA Solutions Ltd

B:15

12.0

Software Customisation Reference Manual

PML 1 Expressions

ALOG

Synopsis Description Side Effects Example Errors

ALOG ( number1 )

-> number

Return the exponential function (natural anti-log) of a number. Numeric underflow causes the result to be set to zero.

ALOG( -0.7 ) -> 0.4965853

Floating point overflow.

ARRAY

Synopsis Description Side Effects Example Errors

ARRAY(pos or dir or ori)

-> number

Converts a position, direction or orientation value or attribute into three numbers. None

ARRAY(e100 )
None.

-> 100

ARRAYSIZE

Synopsis Description Side Effects Example Errors

ARRAYSize ( variable-name )
Give the size of an array variable.

-> number

If the array variable does not exist, the result is undefined.

ARRAYSIZE(!array)

-> 2.0

The variable is a scalar variable and not an array variable. The variable is an array variable element and not an array variable.

ARRAYWIDTH

Synopsis Description Side Effects

ARRAYWIDTH ( variable-name )

-> number

Give the largest display with of any string in array variable_name. None.

2007 AVEVA Solutions Ltd

B:16

12.0

Software Customisation Reference Manual

PML 1 Expressions

Example

If an array contains the following values:

!ARRAY[1] !ARRAY[2] !ARRAY[3] !ARRAY[4] !ARRAY[5] !ARRAY[6] !ARRAY[7] !ARRAY[8]

Then

Bread is for life, not just for breakfast

ARRAYWIDTH(!ARRAY -> 9
i.e. the length of breakfast. Errors The variable is a scalar variable and not an array variable. The variable is an array variable element and not an array variable.

COMPONENT ... OF ...

Synopsis Description Side Effects Example Errors

COMPonent dir1 OF pos2

-> text

Returns the magnitude of a vector drawn from E0 N0 U0 to pos2, projected in the direction dir1. None.

COMP E 45 N of N 0 E 100 U 50 -> 70.710

None.

SINE, COSINE and TANGENT

Synopsis

SINe ( number1 ) COSine ( number1 ) TANgent ( number1 )

-> number -> number -> number

Description Side Effects Example

Return the sine, cosine or tangent value of a number (considered to be in degrees). None.

COS ( 0.0 ) -> 1.0 TAN ( 45.0 ) -> 1.0

Division by zero for TAN if the sine is (nearly) equal to zero.

Errors

2007 AVEVA Solutions Ltd

B:17

12.0

Software Customisation Reference Manual

PML 1 Expressions

INT

Synopsis Description Side Effects Example

INT ( number1 )

-> number

Return the truncated integer value of a number. None.

INT ( 1.6 ) INT ( -23.7 )

Integer overflow.

-> 1.0 -> -23.0

Errors

LENGTH and DLENGTH

Synopsis

LENgth ( text1 ) DLENgth ( text1 )

-> number -> number

Description

Return the length of text1. DLENGTH is for use with characters which have a displayed width that is different from standard characters, such as Japanese.

Side Effects Example

None.

LENGTH ( abcdef ) -> 6.0 LENGTH ( ) -> 0.0

None.

Errors

ALOG

Synopsis Description Side Effects Example Errors

LOG ( number1 )
Return the natural logarithm of a number.. None.

-> number

LOG( 3 ) -> 1 0986123

Negative arguments.

2007 AVEVA Solutions Ltd

B:18

12.0

Software Customisation Reference Manual

PML 1 Expressions

MATCH and DMATCH

Synopsis

MATch ( text1 , text2) DMATch ( text1 , text2)

-> number -> number

Description

Return the position of the beginning of the leftmost occurrence of text2 in text1. If text2 does not occur in text1, 0 is returned DMATCH is for use with characters which have a displayed width that is different from standard characters, such as Japanese.

Side Effects Example

None.

MATCH ( abcdef , cd ) -> 3.0 MATCH ( abcdef , x ) -> 0.0 MATCH ( abcdef , ) -> 1.0
None.

Errors

MAX and MIN

Synopsis

MAX ( number1 , number2 [ , number3 [ ... ] ] ) MIN ( number1 , number2 [ , number3 [ ... ] ] )

-> number -> number

Description Side Effects Example

Return the maximum or minimum value of the arguments. None.

MAX ( 1 , 3.4 ) -> 3.4 MIN ( 7.6 , -12.33 , 2.3 ) -> -12.33
None.

Errors

NEGATE

Synopsis Description Side Effects Example Errors

NEGate ( number1 )
Multiply a real by -1.0. None.

-> number

NEG ( 1 ) -> -1.0

None.

2007 AVEVA Solutions Ltd

B:19

12.0

Software Customisation Reference Manual

PML 1 Expressions

NINT

Synopsis Description Side Effects Example

NINT ( number1 )

-> number

Return the nearest integer to a real. NINT(N+0.5) is equal to N+1 if N is positive or equal to zero, to N if N is negative. None.

NINT NINT NINT NINT

( ( ( (

1.1 ) -> 1.0 -23.7 ) -> -24.0 1.5 ) -> 2.0 -11.5 ) -> -12.0

Errors

Integer overflow.

OCCUR

Synopsis Description Side Effects Example

OCCUR(text1, text2)

-> integer

Counts the number of times string text2 occurs in string text1 None.

OCCUR (ABBACCBBBBBAB, BB) -> 3 OCCUR(ZZZZZZZZZZZ, A) -> 0

None..

Errors

REAL

Synopsis Description

REAL ( text1 )

-> number

Try to read a real number at the beginning of text1. Note that if text is in the form of an exponent, (-12E-1 in the third example), there must be no spaces in it. Note: this function was formerly called NUMBER.

Side Effects

Numeric underflow causes the result to be set to zero. Units are consolidated across POWER.

Example

REAL ( 12.34) -> 12.34 REAL ( 7.23 E 3 meters ) -> 7.23 REAL ( -12E-1 meters ) -> -1.2
Unable to convert the text into a real number.

Errors

2007 AVEVA Solutions Ltd

B:20

12.0

Software Customisation Reference Manual

PML 1 Expressions

POWER

Synopsis Description Side Effects Example Errors

POWer ( number1 , number2 )

-> real

Return the value of number1 raised to the power number2. None.

POWER ( -2 , 3 ) -> -8
Floating point overflow. Zero first argument and (effectively divide by zero). non-positive second argument

Negative first argument and non-integer second argument.

SQRT

Synopsis Description Side Effects Example Errors

SQrt ( number1 )
Return the square root of a real. Units are consolidated across SQRT.

-> number

SQRT ( 4 ) -> 2.0

Negative argument.

VVALUE
VVALUE is used for the late evaluation of variables.

Synopsis

VVALue( variable_name ) VVALue( variable_name , number )

-> number -> number

Description

With one argument, returns value of the scalar variable or value of the array variable element as a number. With two arguments, returns value of the corresponding to the index number as a number. element

See also VLOGICAL, used for late evaluation when a logical result is required, and VTEXT, used for late evaluation when a text result is required. Side Effects If the scalar variable, the array variable or the array variable element does not exist, the result is undefined.

2007 AVEVA Solutions Ltd

B:21

12.0

Software Customisation Reference Manual

PML 1 Expressions

Example

VVAL ( !array[1] ) -> 1.0 VVAL ( !array , 2 ) -> 0.0

Scalar variable may not be indexed. For example, VTEXT (!var[1]) ) will return an error. Array variable must have an index. For example, VTEXT ( !array ) ) will return an error. The string can not be converted to a number.

Errors

B.3.5

Real Arrays
Real array expressions can contain attributes of type real array, for example: DESP.

B.4

Using IDs in Expressions

IDs can be used in expressions. IDs can be any of the following: Element name, for example: /VESS1. Refno, for example: =23/456. Element type further up the hierarchy, for example: SITE. Number within member list, for example: 3. Type and number within member list, for example: BOX 3. NEXT, PREV for next, previous within current list. Optionally with a count and/or element type, for example: NEXT 2 BOX, LAST CYL. NEXT, PREV MEMBER for next, previous within member list. Optionally with a count and/or element type. If the element type given is only valid as a member then MEMBER is assumed. For example, NEXT BOX at an EQUIPMENT will assume MEMBER. FIRST, LAST for first and last in current list. Optionally with a count and/or element type. FIRST, LAST MEMBER for first and last in member list. If the element type given is only valid as a member then MEMBER is assumed. END to navigate up from current list. END is similar to owner but not quite the same. For example, if the current element is a GROUP MEMBER, and it has been reached from the GROUP then END will return to the group but OWNE will go to the true owner. Attribute of type ref, for example: CREF SAME to mean last current element NULREF to mean =0/0 CE for the current element OF may be used to nest the options indefinitely. For example:

SPEC OF SPREF OF FLAN 1 OF NEXT BRAN.

This denotes the SPEC element owing the SELE element pointed to by the SPREF attribute on the first FLANGE of the next BRANCH. ILEAVE TUBE, IARRIV TUBE, HEAD TUBE, TAIL TUBE can be added to denote tube. For example:

HEAD TUBE OF /BRAN1.

2007 AVEVA Solutions Ltd

B:22

12.0

Software Customisation Reference Manual

PML 1 Expressions

An error will occur if there is no implied tube for the element concerned. ID arrays can also be used in expressions. For example, CRFA.

Note: Some of the ID syntax clashes with other types. To allow for this, an id expression may always be preceded with the keyword ID. For example, ID 3 will mean the third member of the current list rather than a number of value 3.

B.5

Positions, Directions and Orientations in Expressions (PDMS only)

Using Positions in Expressions
The basic ways of defining a position are: Position attribute plus optional WRT. For example:

B.5.1

POS OF /VESS1 WRT /* or P1 POS OF /CYL2

Cartesian position. For example:

N 45 W 20000 U 1000
Cartesian position from an element. For example:

N 1000 FROM /ATEST.

Cartesian position from a ppoint. For example:

N 1000 FROM P1 OF /BOX2.

Cartesian position from an attribute. For example:

N 1000 FROM POSS OF /SCTN1

Any numeric value within a position may itself be an expression. For example: the following is a valid position expression

N (DESP[1] + 10) E
The Cartesian position may optionally be followed by WRT to specify the axis system. See WRT (PDMS Only).

B.5.2

WRT (PDMS Only)

The WRT keyword is used to toggle between absolute and relative units. When we specify an element (or attribute of an element) we are specifying an absolute point in world space. The point can be given in world space or some other axis. Normally the answer is required relative to the owner axis system and this is taken as the default. For example: Q POS $ will return the position of the current element $ relatively to its owner. Q POS OF /EQUIP1 $ will return the position of EQUIP1 relative to its $ owner.

2007 AVEVA Solutions Ltd

B:23

12.0

Software Customisation Reference Manual

PML 1 Expressions

If we require the result in some other axis system then the WRT keyword is used. For example: Q POS WRT /* $.for the position in world coordinates.

When we specify a Cartesian coordinate we are dealing with a relative position. For example, N 10 is meaningless until we specify the axis system, or default to an axis system. Again we use WRT to do this, although it is important to note that in this case we are going from a relative position to an absolute position (in the previous example WRT was used to go from an absolute position to a relative one). For example:

N 100 WRT /BOX1

$ specifies an absolute position in world space $ which is N100 of /BOX1.

The default is that Cartesian coordinates are in the owning elements axis system. This absolute position can be expressed in different coordinate systems: the default is again the owners axis system. Note: The CONSTRUCT syntax uses the world as the default axis

Example

Item A SITE at (0,0,0) A ZONE at (100,0,0) An EQUIPMENT at (100,0,0) A BOX at (-100,0,0) MISSING FIGURE IN WORD

Comments With default (World) orientation With default (World) orientation With orientation N IS E With default (World) orientation

Figure B:1.

Results of WRT

The result of Q (N 100 WRT /BOX1), shown as in , will depend on the current element.

2007 AVEVA Solutions Ltd

B:24

12.0

Software Customisation Reference Manual

PML 1 Expressions

Location World Site Zone

Result (300,100,0), in World coordinates. (300,100,0) in World coordinates because the World is the owner of the current element. (300,100,0) in World coordinates, because the Site is the owner of the current element, and the Site coordinates are the same as the World coordinates. (200,100,0), which is the position relative to its owner, the Zone. (100,100,0) which is the position relative to its owner, the Equipment.

Equipment Box

WRT can be further qualified by FROM.

B.5.3

FROM
In some cases we require an offset from a fixed point, other than the position of an item. For example, a point or attribute. The FROM syntax is used for this. We may still use WRT in combination with FROM, but in this case the WRT is only used to determine the axis direction and not the offset, since the offset is specified by the FROM part. Consider the following: Item A SITE at (0,0,0) A ZONE at (100,0,0) An EQUIPMENT at (100,0,0) A BOX at (-100,0,0) MISSING FIGURE Comments With default (World) orientation With default (World) orientation With orientation N IS E With default (World) orientation

Figure B:2.

The Effect of FROM

2007 AVEVA Solutions Ltd

B:25

12.0

Software Customisation Reference Manual

PML 1 Expressions

The result of Q (N 100 WRT /* FROM /BOX1), shown as in , will depend on the current element. Location World, Site, and Zone Equipment Result (200,200,0) since the offset of N100 is applied in world axis rather than /BOX1 axis. (100,200,0). Note: The default axis for the result is the Zone. Box (200,0,0), because the default axis for the result is the Equipment.

The result of Q (N 100 WRT /BOX1 FROM /* ) is different: Location Site and Zone Equipment Box Result (100,0,0) (0,0,0) (0, -100, 0), because the axis for the result is the Equipment.

The result of Q (N 100 FROM /* ) is different yet again. For this we cannot mark an absolute point on the diagram since the default WRT will vary with the current element. In fact for the SITE, ZONE, EQUI the point is marked in , and for the BOX the point coincides with the ZONE.

MISSING FIGURE
Figure B:3. Varying WRT

Location Site and Zone Equipment Box

Result (0,100,0) (-100,100,0), because the default result axis is the Zone. (0, -100, 0), because the axis for the result is the Equipment.

2007 AVEVA Solutions Ltd

B:26

12.0

Software Customisation Reference Manual

PML 1 Expressions

B.5.4

Comparing Positions
Two positions can be compared with EQ, NE, GT, LT, GE or LE. The pairs of coordinates are only compared in the coordinate axes for which the two positions are defined. A position attribute always has all three coordinates defined. For positions entered by the user, only those coordinates which are given by the user are defined. For example:

N10U3

$ only the Y and Z coordinates are defined, $ while the X coordinate remains undefined

For the EQ operator, all the pairs of defined coordinates should be equal. For NE, only one pair of defined coordinates need be different. For GT (LT,GE,LE), all the defined coordinates of the first position should be greater than (less than, greater than or equal to, less than or equal to) the defined coordinates of the second position. This means that GE is not the opposite of LT and LE is not the opposite of GT. If no coordinate of the two positions are defined for a common axis (e.g. N10 and W4D7), the result of the comparison is undefined.

Examples

POS EQ W1S2D3 POS GT N10 or N10 LE POS E10N10 GT E0N0

$ This evaluates to true only if POS of the current $ element is (-1,-2,-3). $ Only the second coordinate of POS is compared; $ if it is greater than 10, then the result is true. $ Is true because the inequality is verified for the X $ and Y axis (both coordinates are undefined for $ the Z axis, so it is ignored).

E10N0 GT E0N0 E10N0 GT E0U100

$ Is false because the Y components are different $ axes. $ Is true. Although no comparison can be $ performed n either the Y or the Z axis, because $ the components are not present in both position $ constants, the comparison is true in the X $ component.

N10 EQ W4D7

$ Is undefined (no comparison is possible).

See also Precision of Comparisons, for tolerances in comparing numbers.

2007 AVEVA Solutions Ltd

B:27

12.0

Software Customisation Reference Manual

PML 1 Expressions

B.5.5

POLAR
The POLAR keyword allows positions to be defined in terms of a distance in a particular direction from a point. The syntax is:

POLAR dir DISTance expr -+- FROM -+- pos -----. | | | | - point ---| | | --------------------+--->
If FROM is not specified the default is the origin of the owner. For example:

POLAR N 45 E DIST 20M FROM U 10 M POLAR AXES PL OF PREV DIST ( ABORE * 10 ) FROM PL OF PRE V

B.5.6

Direction
The basic ways of defining a direction are: Direction attribute plus optional WRT. For example,

HDIR OF /PIPE1 WRT /*

Cartesian direction. For example,

N 45 W
Cartesian direction WRT to an element. All Cartesian directions are returned in the axis of the owner of the current element. For example:

(U WRT CE )
will return the Z axis of the current element relative to its owner.

Q ( Z WRT /SCTN )
will return the Z axis direction of /SCTN relative to the owner of the current element. For example, if the result is required in world coordinates the current element must be the World or a Site. FROM pos2 TO pos2. For example

FROM N 50 WRT CE TO N 100

Keyword AXES followed by a p-point or pline.

2007 AVEVA Solutions Ltd

B:28

12.0

Software Customisation Reference Manual

PML 1 Expressions

The CLOSEST keyword, which will find the closest element in a particular direction. The syntax is:

>- CLOSEST type -+- WITH exp -. | | ------------+- DIRECTION dir -+- EXTENT val -. | | --------------+--> cont continued >-+- AFTER val -. | | -------------+- FROM ? -. | | ----------+-->

In the above graph the keywords are: EXTENT, which is how far to search in the direction specified, default 10M AFTER, or the distance along vector after which to start search, default 0M FROM, which specifies an alternative start point other than current element. This is of particular use for a branch where you might want to specify the HPOS or TPOS. Examples are:

CLOSEST DIR E CLOSEST BOX WITH ( PURP EQ FLOO ) DIR D WRT / * EXTENT 20M CLOSEST VALVE DIR N 45 U FROM E100 N200 U300 CLOSEST BRAN HANG AFTER 2M

B.5.7

Orientations
The basic ways of defining an orientation are: Orientation attribute plus optional WRT. For example:

ORI OF /BOX1 WRT /*

Cartesian orientation. For example:

dir IS dir AND dir IS dir

For example to set an orientation of an element to that of a section, rotated by 90 degrees use:

(E IS U WRT /SCTN1 AND N IS E WRT /SCTN1)

The AXES keyword, which will allow you to use P-points to specify orientations.

2007 AVEVA Solutions Ltd

B:29

12.0

Software Customisation Reference Manual

PML 1 Expressions

The syntax is:

----<---------. / | >-- AXES --*--- PArrive ---| | | |--- PLeave ----| | | |--- PTail -----| | | |--- HHead -----| | | |--- HTail -----| | | --- PPOINT n --+-- OF - <gid> ---->
An example is:

( AXES PLEAVE IS AXES PLEAVE OF PREV AND AXES P3 IS UP )

This will orient a branch component, such as a valve, so that it is aligned with the previous component and its P3 is up. See also Comparing Positions.

B.6

Text Expressions
Text expressions can contain the following: A text string, which must be enclosed in quotes. For example: FRED. A PDMS attribute of type text or word. For example: FUNC A single element of a word array attribute. For example: ELEL[2]. Text operators Text functions

B.6.1

Text Operator
The text operator available is +, used for concatenation. Synopsis Description Side Effects Example Errors

text1 + text2 -> text

-> text

Return the concatenation of two text strings. None.

no + space -> nospace

Text result too long.

2007 AVEVA Solutions Ltd

B:30

12.0

Software Customisation Reference Manual

PML 1 Expressions

B.6.2

Text Functions
The text functions available are: Function AFTER BEFORE DISTANCE LOWCASE, UPCASE PART REPLACE STRING SUBS, DSUBS TRIM VTEXT Comments

AFTER

Synopsis Description

AFTER ( text1 , text2 )

-> text

Return the substring of text1 which is after the leftmost occurrence of text2 in text1. If text2 does not occur in text1, the null string is returned.

Side Effects Example

None.

AFTER ( abcdef , cd ) ->ef AFTER ( abcdef , x ) -> AFTER ( abcdef , ) -> abcdef
None.

Errors

BEFORE

Synopsis Description

BEFORE ( text1 , text2 )

-> text

Return the substring of text1 which is before the leftmost occurrence of text2 in text1. If text2 does not occur in text1, text1 is returned. None.

Side Effects Example

BEFORE ( abcdef , cd ) -> ab BEFORE ( abcdef , x ) -> BEFORE ( abcdef , ) ->

None.

Errors

2007 AVEVA Solutions Ltd

B:31

12.0

Software Customisation Reference Manual

PML 1 Expressions

DISTANCE

Synopsis

DISTance ( number1 ) DISTance( number1, logical1, logical2, logical3, number2, logical4)

-> text -> text

Description

For the one-argument form, if the current distance units are FINCH, text is the conversion of the decimal inches value number1 into the format aabb.cc/dd. Otherwise, text is the STRING conversion of number1. The six-argument form is more complex. The format is:

DIST/ANCE (distance, feet, usformat, fraction, denom_or_dp, zeros)

where: distance is the numeric distance in inches that is to be formatted. feet is a logical flag set to true if output is to be in feet and inches and to false if output is to be in inches. usformat is a logical set to true if US format is to be used or false if PDMS format is to be used. fraction is a logical set to true if the fractional component is to be output as a fraction or false if to be output as a decimal denom_or_dp is a number representing the largest denominator if fraction is TRUE or representing the number of decimal places if it is FALSE. zeros is a logical set to true if zeros are to be shown when that component of the output has no value

PDMS For both US and PDMS formats the following rules are observed: If distance is negative, the first symbol is a minus sign. If feet is true and the distance is at least a foot, then the number of feet is output next, followed by a single quote (). Only if zeros is true will the number of feet be output as 0 for distances less than a foot. Otherwise the feet will be omitted. If feet have been output, the inches will be at least two characters wide. Numbers less than ten will be preceded by a space if US format is being used or a zero if PDMS format is used. A zero will be output if there are no whole inches. If no feet have been output and the distance is at least an inch, then the number of inches is displayed but without any preceding spaces. Only if zeros is true will a 0 be output for distances of less than an inch. If inches have been output and fraction is true, these will be followed by a decimal point (.).

2007 AVEVA Solutions Ltd

B:32

12.0

Software Customisation Reference Manual

PML 1 Expressions

If fraction is TRUE and the number has a fractional component, then the numerator and the denominator are shown separated by a slash (/). This is then blank padded up to the width that the largest numerator and denominator would take. If fraction is FALSE and the number of decimal places is greater than zero, then the decimal point (.) is displayed followed by the remainder up to the appropriate number of decimal places. If the number of decimal places is 0 then the decimal point is not shown either. If US format has been selected then the following additional rules are observed on output: The () after the number of feet is followed by a dash (-). The decimal point separating the inches from the fraction is replaced by a space. The inches and fraction of inches are followed by a double quote().

Side Effects Example

None. If the current distance units are FINCH:

DISTANCE ( 17.5 ) ->

15.1/2

Some examples, where the current distance units are feet and inches:
DIST(34.5,TRUE,TRUE,TRUE,100,TRUE) DIST(34.5,FALSE,TRUE,FALSE,1,TRUE) DIST(34.5,FALSE,TRUE,TRUE,4,FALSE) DIST(128.5,TRUE,FALSE,TRUE,2,TRUE) -> -> -> -> 2-10.1/2. 34.5 34 1/2 1008.1/2

The following table shows sets of options that could have been chosen and the format of the output produced for different numbers. Blanks output by the system are represented by underscores(_).
Distance Feet & Inch US Fraction Denom 100 Zeros
10-_8_1/2___ 10-_0_______ 0-11_1/2___ 0-_0_3/4___ 0-_0_______ -0-10_______

Feet & Inch US Fraction Denom 32 No Zeros

10-_8_1/2__ 10-_0______ 11_1/2__ 3/4__ ______ -10______

Inches US Decimal DP 1 Zeros

128.5 120.0 11.5 0.8 0.0 -10.0

Inches US Fraction Denom 4 No Zeros

128_1/2 120____ 11_1/2 3/4 ____ -10____

Feet & Inch PDMS Fraction Denom 2 Zeros

1008.1/2 1000____ 011.1/2 001____ 000____ -010____

128.5 120.0 11.5 0.75 0.0 -10.0

Errors

The value is too big to be converted.

2007 AVEVA Solutions Ltd

B:33

12.0

Software Customisation Reference Manual

PML 1 Expressions

LOWCASE and UPCASE

Synopsis

UPCase ( text1 ) LOWCase ( text1 )

-> text -> text

Description Side Effects Example

Return an upper or lower case version of text1. None.

UPCASE ( False) -> FALSE LOWCASE ( False) -> false

None.

Errors

PART

Synopsis

PART(text1, number1) PART(text1, number1 , text2)

-> text -> text

Description

With two arguments, returns the number1 component of text1 assuming that text1 is split on any whitespace characters. If number1 is negative, counting of components starts from the right. With three arguments, as above, but use text2 as the separator on which splitting takes place. If the user gives a part number higher than the number of components in the string, the function returns an empty string.

Side Effects Example

None.

PART (x-y-z, 1, - -> x PART (a b c d e, 4-> d PART (/PIPE45/B9, -1, /) -> B9 PART(aa bb cc, 2) -> bb PART(aa-bb-cc,3,-) -> cc
None.

Errors

REPLACE

Synopsis

REPLace (text1,text2,text3) -> text REPLace(text1,text2,text3,i -> text nt1) REPLace(text1,text2,text2,i -> text nt1,int2)

2007 AVEVA Solutions Ltd

B:34

12.0

Software Customisation Reference Manual

PML 1 Expressions

Description

Replace search string text2 in input string text1 with replacement string text3. If int1 is given this specifies the first occurrence of text2 at which to start replacement. If int2 is given this specifies the number of replacements to make. int1 and/or int2 may be negative to indicate that the direction is backwards.

Side Effects Example

None. Three arguments:

REPLACE (cat dog cat cat dog , cat, dog ) -> dog dog dog dog dog
All occurrences of cat are replaced with dog. Four arguments: start occurrence given:

REPLACE (cat dog cat cat cat dog, cat, dog, 2) -> cat dog dog dog dog dog
All occurrence of cat from the second occurrence onwards are replaced with dog

REPLACE(cat dog cat cat dog ,cat, dog, -2 -> dog dog dog cat dog
All occurrences starting at the second occurrence from the end of the string and moving backwards are replaced Note that a negative fourth argument without a fifth argument implies backwards mode. Five arguments: start occurrence and number of replacements given. Replace two occurrences of cat starting at second occurrence:

REPLACE (cat dog cat cat cat, cat,dog, 2,2) -> cat dog dog dog cat
Replace two occurrences in backwards direction starting at the second occurrence:

REPLACE (cat dog cat cat cat, ,cat, dog, 2, -2) -> dog dog dog cat cat
Replace two occurrences in forwards direction starting at second occurrence from the end of the string:

REPLACE (cat cat cat cat dog, cat, dog,-2,2) -> cat cat dog dog dog
Replace two occurrences in backwards direction starting at second occurrence from the end of the string.

REPLACE (cat cat cat cat dog,cat, dog, -2, -2) -> cat dog dog cat dog

2007 AVEVA Solutions Ltd

B:35

12.0

Software Customisation Reference Manual

PML 1 Expressions

The following examples all give the same result:

REPLACE(cat1 cat2 cat3 cat4 cat5 cat9 cat10, cat, dog, 4, 2) REPLACE(cat1 cat2 cat3 cat4 cat5 cat9 cat10, cat, dog, 5, -2) REPLACE(cat1 cat2 cat3 cat4 cat5 cat9 cat10, cat, dog,-6, -2) REPLACE(cat1 cat2 cat3 cat4 cat5 cat9 cat10, cat, dog, -7, 2) cat6 cat7 cat8 cat6 cat7 cat8 cat6 cat7 cat8 cat6 cat7 cat8

in each case, the output string is

cat1 cat2 cat3 dog4 dog5 cat6 cat7 cat8 cat9 cat10
If the replacement string text3 is a null string the required number of occurrences of the search string text2 are removed. For example:

REPLACE (AAABBABZ, B, ) -> AAAAZ REPLACE (AAABBABZ, B, , -1, -1) -> AAABBAZ
Errors If the input string text1 is a null string or an unset text attribute, the input string text1 is returned unchanged. For example:

REPLACE (, A,B)

->

If the search string text2 is longer than the input string text1, the input string text1 is returned unchanged. For example:

REPLACE(AA, AAAAA , B) -> AA

If no occurrence of the search string text2 is found, the input string text1 is returned unchanged. For example:

REPLACE( AAAAAA,B,C) AAAAAA

->

If required occurrence int1 is not found the input string text1 is returned unchanged. For example:

REPLACE(AAAAAA, A, B, 10 ) AAAAAA

->

If the number of replacements required int2 is greater than the actual number of occurrence from the specified start occurrence, replacements are made up to the end of the string ( or beginning in backwards mode). For example:

REPLACE(AAAAAA, A, B, 2, 8) -> ABBBBB REPLACE (AAAAAA, A, B, -3, 8) -> BBBBAA

2007 AVEVA Solutions Ltd

B:36

12.0

Software Customisation Reference Manual

PML 1 Expressions

STRING

Synopsis

STRing ( any scalar type ) STRing ( number , text1 ) STRing ( pos , text1 )

-> text -> text -> text

Description

Turns a value into a text string. With a single argument the STRING function can be applied to the following scalar data types: Numeric Logical Id Position Direction Orientation

With only one argument, decimal places are output to give a maximum of six significant figures. Trailing zeros are always removed in this case. With two arguments the data type may be either numeric (scalar) or position or direction. With two arguments, convert a number or position into a text string using the format described by text1, which may take any of the values between D0 and D6 (or d0 and d6), where the number indicates the number of decimal places. For numbers, STRING always outputs values as millimetres. If unit conversion is needed then the DIST function should be used. For positions, the current distance units are used. Side Effects Example None.
STRING ( 1 ) -> 1 STRING ( 1 , D3 ) -> 1.000 STRING ( 1.23456789 ) -> 1.23457 STRING(1.1230000) ->1.123 STRING ( 1.23456789 , D3 ) -> 1.235 STRING (9*9 LT 100) -> TRUE STRING (OWN OF CE) -> /PIPE1 STRING(POS) -> W1000 N20000 U18000 STRING(POS, D4 ) -> W10000.1234 N20000.1234 U18000.1234 STRING(HDIR OF /PIPE1-1) -> D STRING(E 22.0125 N, D2) -> E 22.01 N STRING (ORI OF NEXT) -> Y IS D AND Z IS U

Errors

2007 AVEVA Solutions Ltd

B:37

12.0

Software Customisation Reference Manual

PML 1 Expressions

SUBSTRING and DSUBSTRING

Synopsis

SUBString ( text1 , number1 ) SUBString ( text1 , number1 , number2 ) DSUBString ( text1 , number1 ) DSUBString ( text1 , number1 , number2 )

-> text -> text -> text -> text

Description

With two arguments, return the substring of text1 beginning at the position number1 to the end of text1. With three arguments, return the substring of text1 beginning at the position number1 and of length number2. If number1 is negative, then counting of characters starts from the RHS of the input string. If number2 is negative, then characters up to and including the start position are returned. DSUBSTRING used with characters which have a displayed width that is different from standard characters, such as Japanese. If the chosen range is outside the original string, an empty string is returned

Side Effects Example

None.

SUBSTRING SUBSTRING SUBSTRING SUBSTRING SUBSTRING SUBSTRING SUBSTRING

None.

( ( ( ( ( ( (

abcdef abcdef abcdef abcdef abcdef abcdef abcdef

, 3 ) -> cdef ,-3 ) -> abcd , 3 , 2 ) -> cd , -3, 2 ) -> de , 3 , -2 ) -> bc , 10 ) -> , -10 , 2 ) -> ab

Errors

TRIM

Synopsis

TRIM ( text1 ) TRIM ( text1, text2 ) TRIM ( text1, text2, text3 )

-> text -> text -> text

2007 AVEVA Solutions Ltd

B:38

12.0

Software Customisation Reference Manual

PML 1 Expressions

Description

When only one argument is supplied, TRIM removes all spaces to the left (leading) and right (trailing) of text1 and returns the answer in text. When two arguments are supplied, text2 specifies where the spaces should be removed from: either L or l for left, R or r for right, and M or m for multiple (where multiple occurrences of blanks are squeezed to a single spaces) or any combination of the three key letters. So the default is LR when this field is omitted. When the third argument text3 is also supplied, this should only be a single character which overrides the space character as the character being trimmed.

Side Effects Example

None.

TRIM ( How now, brown cow , LRM ) -> How now, brown cow TRIM ( 10.3000, R, 0 ) -> 10.3
None.

Errors

VTEXT
VTEXT is used for the late evaluation of variables. Synopsis

VTEXT ( variable-name ) VTEXT ( variable-name , number )

-> text -> text

Description

With one argument, it gets the value of the scalar variable or the value of the array variable element. With two arguments, it gets the value of the element corresponding to the index number. The value is returned as a text string. See also VLOGICAL used for late evaluation when a logical result is required, and VVALUE used for late evaluation when a numeric result is required.

Side Effects Example

If the scalar variable, the array variable or the array variable element does not exist, the result is undefined.

VTEXT ( !var ) -> hello VTEXT ( !array[1] ) -> 1.00 VTEXT ( !array , 2 ) -> 0.00
Errors Scalar variable may not be indexed (e.g. VTEXT (!var[1]) ). Array variable must have an index (e.g. VTEXT ( !array ) ).

Errors

2007 AVEVA Solutions Ltd

B:39

12.0

Software Customisation Reference Manual

PML 1 Expressions

B.7

Late Evaluation of Variables in expressions

The functions VVALUE, VLOGICAL and VTEXT are used for late evaluation of PML variables, that is, they enable you to specify PML variables in expressions which will not be evaluated until the expression is evaluated. For example, when you are creating a report template, you are actually creating a macro which will run when a report is generated. All variables in a report template must therefore be preceded by a suitable late evaluation operator; otherwise the system will try to substitute a value for the variable when it is entered on the form. The difference between the operators is the type of output. VVALUE is used to output a numeric value, VLOGICAL to output a logical variable and VTEXT to output a text variable.

B.8

PDMS Attributes in Expressions

All PDMS attributes and pseudo-attributes may be recognised within expressions. Optionally they may be followed by OF to denote a different element to the current one; e.g. POS OF /VESS1. Brackets may be used to denote an element of an array, for example DESP[8 + 1] for the ninth value of DESP. Since syntax clashes are possible, the keyword ATTRIB may be used to denote that an attribute follows. For example, ATTRIB E will denote the pseudo-attribute EAST as opposed to the start of a position or direction. PDMS attributes are described in the relevant manuals. Pseudo-attributes which can be used in expressions are listed in Appendix D.2.

B.9

Querying Expressions
All expressions may be queried. Arrays are always concatenated into a single variable. Imperial values are always output as inch to variables. This preserves maximum accuracy. To output in FINCH, then the DISTANCE function must be used. In general expression do not have to be enclosed in brackets, but to be sure that other queries are not picked up by mistake then it is advisable to do so. Particular queries that could lead to confusion are those available both outside and inside expressions. These are: Q PPOINT n Q POS or cartesian position Q ORI or cartesian orientation The functionality may vary between outside and inside expression queries. For example, Q N 100 FROM /POSS is not valid. It must be entered as Q N 100 FROM /POSS ).

B.10 Units in Expressions

When a user enters a literal value then the units are not necessarily known. The units for PML variables are also unknown. Where units are known, then all internal values are set to mm. The value is then converted to the target (local) units on assignment to a variable or on output. To cope with unknown units each value remembers its original units internally. An attempt is then made to allow for unknown units across operators.

2007 AVEVA Solutions Ltd

B:40

12.0

Software Customisation Reference Manual

PML 1 Expressions

The internal settings for units are as follows:

Setting NONE UNKN MM INCH SQIN CUIN

Comments No units. e.g. attribute OBS. Unknown units. e.g. 10. Dist/bore attribute if units are MM, or literal e.g. 10 mm. Dist/bore attribute if units are INCH/FINCH, or literal e.g. 10. Multiply two INCH values together, or literal e.g. 10 sq in. Multiply SQIN by INCH, or literal e.g. 10 cu in.

On comparison, addition or subtraction of two values the following assumptions are made. If one of the units is unknown and the other is anything other than UNKN, then the unknown value is assumed to have the same units as the known units. A suitable conversion is then done if the known units is INCH or SQIN or CUIN. For example:

(XLEN GT 10).
If we are working in distance units of inches, it is known that XLEN is a distance value. Internally the value is held in mm, but the units are held as INCH. The units for 10 are held as unknown. On doing the comparison, the 10 is assumed to be inches and thus multiplied by 25.4 to ensure that the comparison works as expected. Special action is also taken to preserve the correct units across multiplication, division, POWER and SQRT, in particular the maintenance of SQIN and CUIN. In these situations, units of %UNKN are treated as none. For example, (10 * XLEN) is assumed to result in INCH rather than SQIN. An exception is made when a reciprocal would result from division. For example: for (10 / XLEN) we assume that the 10 is in inches rather than none.

B.11

Precision of Comparisons
To allow for small losses of accuracy, the following tolerances are used. Object Number Tolerance Tolerance factor of 0.000001. In other words, if the difference between two reals is not greater than 0.000001* (maximum of the two values) then the values are considered to be equal. e.g. Position Direction or Orientation (1.000001 GT 1) is FALSE as it considers 1.000001; and 1 to be equal; (1.000002 GT 1) is TRUE.

Considered to be equal if within 0.5 mm of one another. Considered to be equal if values are within 0.005.

2007 AVEVA Solutions Ltd

B:41

12.0

Software Customisation Reference Manual

PML 1 Expressions

B.12 Undefined Values

In order to permit expressions like ((DIAM GT 200.0) OR (TYPE EQ BOX)), expressions must be able to cope with undefined values. Generally, applying an operator to one or more undefined arguments has an undefined result. Two exceptions are: the use of the AND operator with a false argument, will result in FALSE, regardless of whether or not the remainder of the arguments are defined; and OR which returns TRUE if any of its arguments is TRUE. For example, consider applying the above expression when the current element is a box. DIAM is undefined; therefore (DIAM GT 200.0) is also undefined. However, (TYPE EQ BOX) is certainly true and so the final result of the whole expression evaluates to TRUE. An undefined result occurs when: One of the operands or arguments of a function (except some cases of AND and OR) is undefined. An attribute is unavailable for the corresponding element (e.g.DIAM OF OWNER when the current element is a box). An element is undefined (e.g. OWNER when the current element is the WORLD). An attribute is unset (e.g. text attribute or UDA of length 0). A variable is undefined (e.g. initialised). VVAL(!ARC6) where !ARC6 has never been

Two position constants are compared with GT, GE, LT or LE and they have no common coordinates (e.g. N10 EQ E5). If the result of the whole expression is undefined, an error occurs.

B.13 Unset Values

A particular class of undefined values are unset values. The concept exists for attributes which are valid for a given element, but for which no value has been assigned. Typically these may be elements of an array, or word attributes. References of value =0/0 are also treated as unset. Unset values are propagated as for undefined values (except for Boolean operations- see below). Undefined values take precedence over unset. There is a specific logical function UNSET to test if a values is unset. Across comparisons, unset values are not propagated, but are treated as follows: Operator EQ, GT, GE, LT, LE NE OR , AND When Applied to an UNSET Results in FALSE. Results in TRUE. Values are treated as FALSE.

For example, if DESP(2) and LVAL(3) are unset then:

(DESP(2) GT 99) -> False (DESP(2) NE 33) -> True (:LVAL(3) AND TRUE) -> False

2007 AVEVA Solutions Ltd

B:42

12.0

Software Customisation Reference Manual

Index

A
ABS . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:15 ACOS . . . . . . . . . . . . . . . . . . . . . . . . . . B:15 ADD . . . . . . . . . . . . . . . . . . . . . . . . . . . B:12 AFTER . . . . . . . . . . . . . . . . . . . . . . . . . B:31 ALOG . . . . . . . . . . . . . . . . . . . . . B:16, B:18 AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:3 AREA command ( Design and ) . . . . . 2:174 Area view gadget . . . . . . . . . . . . . . . . 2:174 Area view setup mode . . . . . . . . . . . . 2:174 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . B:16 ARRAYSIZE . . . . . . . . . . . . . . . . . . . . . B:16 ARRAYWIDTH . . . . . . . . . . . . . . . . . . . B:16 ASIN . . . . . . . . . . . . . . . . . . . . . . . . . . . B:15 ATAN . . . . . . . . . . . . . . . . . . . . . . . . . . B:15 ATANT . . . . . . . . . . . . . . . . . . . . . . . . . B:15 attributes in expressions . . . . . . . . . . . . . . . . B:40 AUTOSEND command . . . . . . . . . . . . . . A:2

D
DEFINED . . . . . . . . . . . . . . . . . . . . . . . . B:7 DELETED . . . . . . . . . . . . . . . . . . . . . . . . B:8 DISTANCE . . . . . . . . . . . . . . . . . . . . . . B:32 format . . . . . . . . . . . . . . . . . . . . . . . B:32 US format . . . . . . . . . . . . . . . . . . . . B:32 DIVIDE . . . . . . . . . . . . . . . . . . . . . . . . . B:13 DLENGTH . . . . . . . . . . . . . . . . . . . . . . B:18 DMATCH . . . . . . . . . . . . . . . . . . . . . . . B:19 DSUBSTRING Japanese characters . . . . . . . . . . . B:38

E
EMPTY . . . . . . . . . . . . . . . . . . . . . . . . . . B:8 EQUAL . . . . . . . . . . . . . . . . . . . . . . . . . . B:4 Expressions directions in . . . . . . . . . . . . . B:28, B:30 format . . . . . . . . . . . . . . . . . . . . B:1, B:2 IDS in . . . . . . . . . . . . . . . . . . . . . . . B:22 logical . . . . . . . . . . . . . . . . . . . . . . . . B:2 logical array . . . . . . . . . . . . . . . . . . B:11 nesting . . . . . . . . . . . . . . . . . . . . . . . B:2 numeric . . . . . . . . . . . . . . . . . . . . . B:12 positions in . . . . . . . . . . . . . . . . . . . B:23 precision of comparisions . . . . . . . B:41 real . . . . . . . . . . . . . . . . . . . . . . . . . B:12 real array . . . . . . . . . . . . . . . . . . . . B:22 types . . . . . . . . . . . . . . . . . . . . . . . . B:1

B
BADREF . . . . . . . . . . . . . . . . . . . . . . . . . B:6 BEFORE . . . . . . . . . . . . . . . . . . . . . . . . B:31 Boolean operators . . . . . . . . . . . . . . . . . . B:3

C
COMP . . . OF . . . . . . . . . . . . . . . . . . . . B:17 Comparator operators . . . . . . . . . . . . . . . B:3 Comparision precision in expressions . . . . . . . . . . . . . . . . B:41 COSINE . . . . . . . . . . . . . . . . . . . . . . . . B:17 CREATED . . . . . . . . . . . . . . . . . . . . . . . . B:7

F
format distances . . . . . . . . . . . . . . . . . . B:32 FROM . . . . . . . . . . . . . . . . . . . . . . . . . . B:25

2007 AVEVA Solutions Ltd

Index page i

12.0

Software Customisation Reference Manual

Functions logical . . . . . . . . . . . . . . . . . . . . . . . . B:6 numeric . . . . . . . . . . . . . . . . . . . . . . B:13 real . . . . . . . . . . . . . . . . . . . . . . . . . B:13

P
PART . . . . . . . . . . . . . . . . . . . . . . . . . . B:34 Positions comparing . . . . . . . . . . . . . . . . . . . B:27 POWER . . . . . . . . . . . . . . . . . . . . . . . . B:21

G
GE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:5 GT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:5

Q
Querying variables and expressions . . . . . . . B:40

I
IDs in expressions . . . . . . . . . . . . . . . . . B:22 INT . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:18

R
REAL . . . . . . . . . . . . . . . . . . . . . . . . . . B:20 Real arrays in expressions . . . . . . . . . . B:22 Real expressions . . . . . . . . . . . . . . . . . B:12 Relational operators . . . . . . . . . . . . . . . . B:3 REPLACE . . . . . . . . . . . . . . . . . . . . . . B:34 REVIEW command . . . . . . . . . . . . . . . . A:1

L
Late evaluation of expressions . . B:21, B:40 LE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:5 LENGTH . . . . . . . . . . . . . . . . . . . . . . . . B:18 Logical functions . . . . . . . . . . . . . . . . . . . B:6 LOWCASE . . . . . . . . . . . . . . . . . . . . . . B:34 LT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:5

S
SEND command . . . . . . . . . . . . . . . . . . A:2 SINE . . . . . . . . . . . . . . . . . . . . . . . . . . . B:17 SQRT . . . . . . . . . . . . . . . . . . . . . . . . . . B:21 STRING . . . . . . . . . . . . . . . . . . . . . . . . B:37 SUBSTRING . . . . . . . . . . . . . . . . . . . . B:38 SUBTRACT . . . . . . . . . . . . . . . . . . . . . B:12

M
MATCH . . . . . . . . . . . . . . . . . . . . . . . . . B:19 MATCHWILD . . . . . . . . . . . . . . . . . . . . . B:8 MAX . . . . . . . . . . . . . . . . . . . . . . . . . . . B:19 MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:19 MODIFIED . . . . . . . . . . . . . . . . . . . . . . . B:9 MULTIPLY . . . . . . . . . . . . . . . . . . . . . . B:13

T
TANGENT . . . . . . . . . . . . . . . . . . . . . . Text functions . . . . . . . . . . . . . . . . . . . . Text operator . . . . . . . . . . . . . . . . . . . . TRIM . . . . . . . . . . . . . . . . . . . . . . . . . . B:17 B:31 B:30 B:38

N
NEGATE . . . . . . . . . . . . . . . . . . . . . . . . B:19 NEQUAL . . . . . . . . . . . . . . . . . . . . . . . . . B:4 NINT . . . . . . . . . . . . . . . . . . . . . . . . . . . B:20 NOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:5 NUMBER (REAL) . . . . . . . . . . . . . . . . . B:20 Numeric expressions . . . . . . . . . . . . . . B:12 Numeric operators . . . . . . . . . . . . . . . . B:12

U
UNDEFINED . . . . . . . . . . . . . . . . . . . . . B:7 Undefined values in expressions . . . . . . . . . . . . . . . . B:42 Units in expressions . . . . . . . . . . . . . . . . B:40 UNSET . . . . . . . . . . . . . . . . . . . . . . . . . B:10 Unset values in expressions . . . . . . . . . . . . . . . . B:42 US format distances . . . . . . . . . . . . . . . B:32

O
OCCUR . . . . . . . . . . . . . . . . . . . . . . . . . B:20 Operators logical . . . . . . . . . . . . . . . . . . . . . . . . B:3 numeric . . . . . . . . . . . . . . . . . . . . . . B:12 text . . . . . . . . . . . . . . . . . . . . . . . . . B:30 OR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B:6

V
VLOGICAL . . . . . . . . . . . . . . . . . . . . . . B:11 VTEXT . . . . . . . . . . . . . . . . . . . . . . . . . B:39 VVALUE . . . . . . . . . . . . . . . . . . . . . . . . B:21

2007 AVEVA Solutions Ltd

Index page ii

12.0

Software Customisation Reference Manual

W
WRT . . . . . . . . . . . . . . . . . . . . . . . . . . . B:23

2007 AVEVA Solutions Ltd

Index page iii

12.0