Software Customisation

Reference Manual
 

 AVEVA Sol u t i on s L im i t ed

PML
PML Disclaimer 
1.1 AVEVA does not warrant that the use of the AVEVA software will be uninterrupted, error-free or free from
viruses.
1.2 AVEV
AVEVA A shall not be liable for: loss of profits; loss of business; depletion of goodwill and/or similar losses; loss of 
anticipated savings; loss of goods; loss of contract; loss of use; loss or corruption of data or information; any
special, indirect, consequential or pure economic loss, costs, damages, charges or expenses which may be
suffered by the
created by the AVEVA
user, including anyirrespective
software, loss suffered by the user
of whether suchresulting fromsuffered
losses are the inaccuracy
directly or
or invalidity
indirectly,oforany data
arise in
contract, tort (including negligence) or otherwise.
1.3 AVEVA
AVEVA shall have no liability in contract, tort (including negligence), or otherwise, arising in connection with the
performance of the AVEVA software where the faulty performance of the AVEVA software results from a user's
modification of the AV
AVEV
EVA
A software. User's rights to modify the AVEVA VEVA software are strictly limited to those set out
in the Customisation Manual.
1.4 AVEVA
AVEVA shall not be liable for any breach or infringement of a third party's intellectual property rights where such
breach results from a user's modification of the AVEVA
AVEVA software or associated documentation.
1.5 AVEVA's total liability in contract, tort (including negligence), or otherwise, arising in connection with the
performance of the AVEVA
AVEVA software shall be limited to 100% of the licence fees paid in the year in which the user's
claim is brought.
1.6 Clauses 1.1 to 1.5 shall apply to the fullest extent permissible at law.
1.7. In the event of any conflict between the above clauses and the analogous clauses in the software licence

under which the AVEVA

AVEVA software was purchased, the clauses in the software licence shall take precedence.
PML 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, or is validly licensed by, A
AVEV
VEVA
A Solutions Limited or iits
ts subsidiaries.
All rights are reserved to AVEVA
AVEVA Solutions Limited and its subsidiaries. The information contained in this d
document
ocument
is commercially sensitive, and shall not be copied, reproduced, stored in a retrieval system, or transmitted without
the prior written permission of AVEVA Solutions Limited. Where such permission is granted, it expressly requires
that this copyright notice, and the above disclaimer, 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 AVEV
AVEVA
A Solutions Limited. Subject to the user's rights, as set
out in the customisation manuals to amend PML software files contained in the PDMSUI and PMLLIB folders and
any configuration files, the user may not reverse engineer, decompile, copy, or adapt the software. Neither the
whole, nor
product, part of or
machine, the software
system described
without in written
the prior this publication may
permission be incorporated
of AVEVA
AVEV A Solutions into any save
Limited, third-party software,
as permitted by
law. Any such unauthorised action is strictly prohibited, and may give rise to civil liabilities and criminal prosecution.
The AVEVA software described in this guide is to be installed and operated strictly in accordance with the terms
and conditions of the respective software licences, and in accordance with the relevant User Documentation.
Unauthorised or unlicensed use of the software is strictly prohibited.
Copyright 1974 to current year. A AVEV
VEVAA Solutions Limited and its subsidiaries. All rights reserved. AVEV
AVEVAA shall not
be liable for any breach or infringement of a third party's intellectual property rights where such breach results from
a user's modification of the AVEV
AVEVA A software or associated documentation.
AVEVA
VEVA Solutions Limited, High Cross, Madingley Road, Cambridge, CB3 0HB, United Kingdom.

PML Trademark
AVEVA and Tribon are registered trademarks of AVEVA Solutions Limited or its subsidiaries. Unauthorised use of 
the AVEVA
AVEVA or Tribon trademarks is strictly forbidden.

AVEVA product/software names are trademarks or registered trademarks of AVEVA Solutions Limited or its
subsidiaries, registered in the UK, Europe and other countries (worldwide).
The copyright, trademark rights, or other intellectual property rights in any other product or software, its name or 
logo belongs to its respective owner .
 

Software Custom isation Re

Reference
ference Ma
Manual
nual

Revision
Revision Sheet
Sheet

Dat e Ver s i o n Co m m en ts / Rem ar k s

September 2011 12.1.1 Event Driven Graphics added.

 

Software Custom isation Re

Reference
ference Ma
Manual
nual
 

 Soft ware Customi sation Reference

Reference Manual
Manual

 Soft
 Software
ware Cus
usto
tomi
misati
sation
on Re
Reference
ference M
Manual
anual

Co n t en t s Pag e

Refer
Reference
ence Manual

Introd
Intr oduc
ucti
tion
on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1
Summary of Obj ects
ects,, M
Members
embers and Me
Meth
thod
ods
s . . . . . . . . . . . . . . . . . 2:1
Object
Obj ect Class if ic ati
ation
on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1
Method s Av ailabl e to A
Allll Object s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3
Form s and Menus Obj ects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:4
Members Contained by All Gadgets.
Gadg ets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:4
Summary of Gadget-Specific Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:5
Gadget Syn
Syntax
tax Graph s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:6
Rules for Presenting and Using Syntax Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:6
Setting Up Gadget Anchoring: <fganch>
<fgan ch> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:7
Setting Up Gadget Docking: <fgdock>
<fgdo ck>.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:7
Setting-Up the Gadget’s Position: <fgpos> and <fgprl> . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:8
Setting Up the Gadget’s Width and Height: <vshap>.
<vshap> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:9
Setting Up the Gadget’s Tagwidth (TEXT, TOGGLE and OPTION): <fgtagw> . . . . . . . . . 2:10
Setting Up the Gadget’s 2D Screen Position: <xypos> . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:10
Obj ect Type Detai ls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:11
Object
ALERT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:11
ARC Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:12
ARRAY Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:20
BANNER Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:24
BAR Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:25

BLOCK Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:27

BOOLEAN Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:27

i 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual

BORE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:28

BUTTON Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:29
COLLECTION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:33
COLUMN Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:34
COLUMNFORMAT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:35
COMBOBOX Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:37
CONTAINER Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:41
DATEFORMAT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:42
DATETIME Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:43
DB Object
Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:45
DBREF Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:47
DBSESS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:48
DIRECTION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:48
EXPRESSION Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:50
FILE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:51
FMSYS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:53

FORM Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:56

FORMAT Object.
Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:65
FRAME Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:68
Graphical Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:72
IDLis
IDListt . .. . .. . .. . .. . .. . .. .. . .. . .. . .. . .. . .. . .. . .. . .. . .. . .. . .. . .. . .. . . 2:7
2:74
4
LINE Gadget. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:76
LINE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:77
LINEARGRID Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:86
LIST Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:88
LOCATION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:93
MACRO Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:95
MDB Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:95
MEASURE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:97
MENU Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:99
Multi Discipline Route
R oute Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:106
NUMERICINPUT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:111
OBJECT
OBJ ECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1
2:113
13
OPTION Gadget.
Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:113
ORIENTATION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:117
PARAGRAPH Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:118
PLANE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:120
PLANTGRID Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:124
PLATFORMGRID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:125
PMLReport Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:128

ii 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual

PMLSECURELOGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:130
PMLUSERLOGIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:131
POINTVECTOR Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:131
POSITION Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:134
POSTEVENTS Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:139
PROJECT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:140
PROFILE Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:141
RADIALGRID Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:151
REAL Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:153
REPORT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:158
RTOGGLE Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:161
Section Plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:163
Section Plane Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:165
SELECTOR Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:168
SESSION Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:171
SLIDER Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:173

STRING Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:175

STAT
ST ATE
E . . .. . . .. . . .. . . .. . .. . . .. . . .. . . .. . . .. . . .. . . .. . . .. . . .. . . .. . . .. . 2:
2:18
182
2
TABLE Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:182
TEAM Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:184
TEXT Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:185
TEXTPANE Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:188
TOGGLE Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:190
UNDOABLE Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:192
UNIT Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:193
USER Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:195
VERIFY
VER IFY . . . .. . . .. . . .. . . .. . . .. . . .. . . .. . . .. . .. . . .. . . .. . . .. . .. . . .. . . .. . 2:1
2:196
96
ViewFinder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:196
VIEW Gadget: ALPHA Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:198
VIEW Gadget: AREA View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:199
VIEW Gadget: PLOT View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:201
VIEW Gadget: VOLUME Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:203
XYPosition Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:206

Event Driv en Graphi

Grap hics
cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
Overvi
Over vi ew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
Purpos
Purp ose
e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1
Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2
Defini
Defi ni ti on s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2

ii i 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual

Target Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2

Superseded
Supers eded Func ti onal
onalit
ity
y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2
Com po nent s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3
Compo
Main Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3
Secondary Components.
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3
Concep
Con cepts
ts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4
Event Driven Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4
Pick
Picking
ing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4
Pick Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5
Event Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5
Event Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5
Event Con trtrol
ol Syst
System em (edgCnt
(edgCntrl rl)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:6
Published Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:7
Add Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:8
Remove Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:9

Change Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:9

View the Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:10
Limitations and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:11
Event Packet (edgPac
(edgPacket ket)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:11
Published Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:15
Exampless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:23
Example
Limitations and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:29
Pick Packet (edgPic kPacket) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:30 3:30
Published Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:31
Examples (Defining Pick Sequences) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:52
Examples (Using Pick Packets) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:54

Limitations and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:56

Pic k Ty
Pick Type
pe (edg
(edgPic
PickTykType) pe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:56
Published Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:57
Exampless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:59
Example
Limitations and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:59
Pic k (edg Pic
Pick Pick) k).. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:59
Pick Filtering.
Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:59
Rule Combination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:60
Published Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:61
Exampless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:61
Example
Limitations and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:63

Pick
Pic k Data (edg Pic
PickData)
kData) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:63

iv 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual

Published Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:63

Pick ed Posi
Picked Posititi on Data ((edgPos
edgPosit itio
ionData)
nData) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:64
Published Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:65

PML 1 Express
Expr essio
ions
ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1
Form at of Expr
Expressi
essions
ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: A:11
Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2
Nesting Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2
Log ical
ic al Expr
Expressi
ession
ons s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A: . A:2
2
Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:3
Logical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:6
Logical Array Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:11
Numeri c (Rea
(Real) l) Expr essiessions ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..A: A:12
12
Real Physical Quantities with Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:12
Numeric (Real) Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:13
ADD and SUBTRACT (+ and -) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:13
MULTIPLY and DIVIDE (* and /) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:13
Numeric (Real) Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:14
Real Arrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:22
Using
Usin g IDs in Expr
Expressi
essions
ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:
A:22
22
Positi ons, Directio ns and Orientations i n Expression s (P (PDMDMS S only) . . . . . . . A:23
Using Positions in Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:23
WRT (PDMS Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:23
FROM
FR OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:
A:25
25
Comparing Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:27
POLAR
POL AR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2
A:28
8
Directi
Direction
on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2
A:29
9
Orientations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:30
Text Expr essi
essions
ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: A:31
31
Text Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:31
Text Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:32
Late Evaluati on o f Variabl es in Exp ress
ressio
ions
ns . . . . . . . . . . . . . . . . . . . . . . . . . . ..A:
A:40
40
 At tr ib ut es i n Ex pr ess
essii on s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 41
Queryi ng Expr
Expressi
ession
onss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:
A:41
41
Unit s i n Exp ress
ressio
ions
ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:
A:41
41
Precis ion
io n of Compar
Comparis
isons
ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:
A:42
42
Undefi
Und efined
ned Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A: 42

v 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual

Unset
Uns et Valu es.
es . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:
. A: 43

vi 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Introduction

1 In t r o d u c t i o n

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 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
crea ting 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,
Objects, Members
Members and Methods.
Methods. For tthe
he For
Forms
ms and Menus objects,
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 AVEV
AVEVA
A Software
Customisation Guide dated October 1995, which describes the old syntax in detail.
• In
Infor
forma
mati
tion
on a
abo
bout
ut usi
using
ng PML
PML in
in Rev
Review
iew..
• A descr
descript
iption
ion of the
the PML 1 expr
express
ession
ionss pack
package
age..

1:1 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Introduction

1:2 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2 Su mm
mmaar y of Ob je
jec
c t s , Memb
mbeer s and Met ho
hodds

2.1 Ob j ec t Cl
Cl as s i f i c at i o n
The table below lists the object types and shows which classifications they b
belong
elong to.

Cl as s i f i c at i o n Ob j ec t Ty p e

PML Bu
Bui l t - i n Obj ect s ARRAY
BLOCK
BOOLEAN
FILE
OBJECT
REAL
STRING
DATETIME
UNIT
MEASURE
3D Geomet r y Obj
Obj ect s ARC
LINE
LINEARGRID
LOCATION
PLANE
PLANTGRID
POINTVECTOR
POSTEVENTS
PROFILE
RADIAL GRID
XYPOSITION

2:1 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Cl as s i f i c at i o n Ob j ec t Ty p e

PDM
PDMS Obj
Obj ect s BANNER
BORE
DB
DBREF
DBSESS
DIRECTION
MACRO
MDB
ORIENTATION
POSITION
POSTUNDO
PROJECT
SESSION
TEAM
UNDOABLE
USER
For ms and Menu Obj ect s & ALERT
Gadget s
BAR
BUTTON
COMBOBOX
CONTAINER
FMSYS
FORM
FRAME
LINE
LIST
MENU
NUMERIC
OPTION
PARAGRAPH
RTOGGLE
SELECTOR

2:2 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Cl as s i f i c at i o n Ob j ec t Ty p e

SLIDER
TEXT
TEXTPANE
TOGGLE
VIEW ALPHA
AREA
PLOT
VOLUME
Col l ect i on and Re
Repor t Obj ect s COLLECTION
COLUMN
COLUMN-FORMAT
DATE-FORMAT
EXPRESSION
REPORT
TABLE
For mat t i ng Tex
Textt FORMAT

Table
able 2
2:: 1. Obje
Object
ct T
Typ
ypes
es a
and
nd C
Cla
lass
ssif
ific
icat
atio
ion
n

2.2 Method
thodss Avail
vailaable
ble to All
All Obj
Objeects
cts
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.

Nam e Re s u l t Pu r p o s e
At t r i but e( ' Name' ) ANY To set or get a member of an
object, providing the member 
name as a STRING.
At t r i but es ( ) ARRAY OF To get a list of the names of 
STRINGS the members of an object as
an array of STRING.
Del et e( ) NO RESUL
RESULT Des
Destro
troyy the ob
objec
jectt - make it
undefined
EQ( any) BOOL
BOOLEA
EAN
N Type-
ype-de
depe
pend
nden
entt comp
compar
aris
ison
on
LT( any)
any) BOOL
BOOLEA
EAN
N Type-
ype-dedepe
pend
nden
entt ccom
ompa
pari
riso
son
n
(converting first to STRING if 
all else fails)

2:3 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Max( any) ANY Return maximum of object

and second object
Mi n( any)
any) ANY Return minimum of object
and second object
NEQ(
EQ( any) BOOL
BOOLEA
EAN
N TR
TRUE
UE if obje
object
ctss do not
not have
have
the same value(s)
Obj ect Typ
Type( ) STRING Return the type of the object
as a string
Set ( ) BOOL
BOOLEA
EAN
N TR
TRUE
UE if the
the obje
object
ct has
has been
been
given a value(s)
St r i ng( ) STRING C o n v e r t th e o
ob
bj ec t tto
o a
STRING
Unset ( ) BOOL
BOOLEA
EAN
N TRUE
TRUE if the
the obje
object
ct does
does not
not
have a value

Table
able 2
2:: 2. Me
Meth
thod
ods
sAAva
vail
ilab
able
le tto
o Al
Alll Obje
Object
cts
s

2.3 Fo r m s an d Men u s Ob j ec ts

2.3.1 Memb
mbeers C
Con
onttaine
ined by Al
Alll G
Ga
adg
dgeets
All gadgets contain the following members.

Nam e Ty p e Pu r p o s e

vi s i bl e BOOLEAN You query this member to

determine if a gadget is
Get/Set
visible or invisible.
To make a gadget visible, set
it to TRUE; to make the

gadget invisible, set it to

FALSE.
ac t i ve BOOLEAN You query this member to
determine if a gadget is
Get/Set
active or inactive (greyed-
out).
To make a gadget active, set
it to TRUE; to make the
gadget inactive, set it to
FALSE.

2:4 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e

cal
cal l back STRING Query or assign the gadget’s
callback string
Get/Set
t ag STRING Query or assign a gadget’s
Get/Set tag text. This is not displayed
for all gadgets.

Table
able 2
2:: 3. Me
Memb
mber
ers
sCCon
onta
taine
ined
d by Al
Alll Ga
Gadg
dget
ets
s

2.3.2 Sum
umma
mary
ry of G
Ga
adg
dge
et-
t-S
Spe
peci
cific
fic M
Me
ethod
thods
s
The table below summarises the methods that different gadgets support.
B  B  L   O P   S  T  T  T  V  V  V  N  C   C  F  L   S  V 
 a  u  s  i    p  a l    e  e  o i    e i  
i    e  u  o  o r  i  
n  e  e i  
r   t    t    t    a i   x 
r   d  x   g  e w w w m n m  a l   w
 t   i    e  t    t    g  t   m  e  e
 o  o -
 p  
l   A   
 2   3   e  a  b   c  : 
n n r   e  e  t   P 
 a r  i  
n  o  o
n  /   l   D D
 p i  
 c   b  r   ol  
 e R h   e  o
 t   I   r   t  
 o  a n x 
 g  p
 g  u
l    t  
 e

Add X X X X
Backgr ound
ound X X X X X X X X X X X X
Cl ea
earr X X X X X X X X
Cl ear Sel ecti on X X X X
Cont
ont ai ne
nerr X X X X X X X X X X X X X X
Cur Pos X
Di spl ayTe
ayText
xt X X
Fi el dPr oper t y X
Ful l Name X X X X X X X X X X X X X X X X X X X
Get Pi ckedP
ckedPop
opup
up X X X X X X X X X X X X X X X
Hi ghl i ght X X X
I ns ert
ert Af t er X
I nser
ser t Bef or e X
Li ne X
Na
Namme X X X X X X X X X X X X X X X
Owner X X X X X X X X X X X X X X X
Ref r esh X X X X X X X X X X X X X X X X X X
Remov
oveP
ePopup
opup X X X X X X X X X X X X X X X X
Rest or eV
eVii ew X X
RTog
Toggl
gl e X
Sel ec
ectt X X X X
Sel ec t i on X X X X
Set Act i ve X
Set
Set Backgr ound
ound X X X X X X X
Set Col umns X
Set
Set Cur Pos
X

2:5 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

B  B  L   O P   S  T  T  T  V  V  V  N  C   C  F  L   S  V 

 a  u  s  i    p  a l    e  e  o  e i    e i  
i    e  u  o  o r  i  
n  e  e i  
r   t   i   x 
r   d  x   g m n m  a l   w
 t    t    t  
i    a  e  t    t    g w w w m  e  e
 o  o -
 p    
 2   3   e  t  
 a  b   c  : 
n n r  l   A 
 e  e  t   P 
 a r  i  
n  o  o
n  /   l   D D
 p i  
 c   b  r   ol  
 e R h   e  o
 t   I   r   t  
 o  a n x 
 g  p
 g  u
l    t  
 e

Set Edi t abl e X X

Set Fi el dPr oper t y X
Set
Set Focus X X X X X X X X X X X
Set
Set Head
eadii ngs
ngs X
Set Li ne X
Set Pop
Popup
up X X X X X X X X X X X X X X X
Set Range X
Set Rows X
Set Si ze X X X X
Set Tool t i p X X X X X X X X X
Set Val ue X
Shown X X X X X X X X X X X X X X X X X X X

ShowPopup X
Su
Subt
bt ype X X X X X X X X X X X X X X X X X X X
 Type X X X X X X X X X X X X X X X X X X X
Val i dat eCal l X

Tabl
able
e 2:
2: 4.
4. Sum
Summar
mary
y of
of Gadg
Gadget-
et-Spe
Specif
cific
ic Me
Metho
thods
ds

2.4 Gad g et Sy
Sy n tax Gr
Gr ap h s

2.4.1 Rule
ules
s for Pre
rese
senti
nting
ng a
and
nd U
Usin
singgS
Synt
ynta
ax G
Gra
raphs
phs
The rules for syntax graphs are as follows:
1. Each graph
graph represents
represents a command
command (or(or part of
of a command)
command) to PDMSPDMS to perform
perform
specified actions with specified data. The graph is entered at “ gr aph_nam
aph_ 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. Ve
Verti
rtical
cal line
liness with
with one or
or more
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
Horizontals to the the right of state
state lines, represent
represent command
command words
words and data which
which are
allowable in the state. They can only be traversed from left to right.
1. Words starting
starting with
with capitals
capitals represent
represent command words.words. The capitalize
capitalizedd 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. Word
Wordss enc
enclolose
sed
d iin
n “< >“ represent a call to the named graph. These should be
lower case. Graph calls can be recursive.
3. Words in lower
lower case only,
only, represent ‘notional
‘notionally’
ly’ atomic dat
data
a items, e.g. text,
text, integer,
integer,
val (numeric value). Sometimes they are in fact graph calls, e.g. ‘f name’   and

2:6 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

‘gna
gname’ . Sometimes they are fictitious e.g. ‘t agt ext’ , but more helpful than just
“text” and easier to understand than a reference to, say, <f gt ag>.
4. Continuous
Continuous vertica
verticall and horizontal
horizontal lines without
without a “ + “ symbol represent flow lines of 
the graph.
1. Th
Thee pre
prese
senc
ncee of
of a “* “ symbol in a vertical line indicates that the allowed direction of 
traverse is upwards.
2. Th
Thee pre
prese
senc
ncee of
of a “<“ symbol on a horizontal indicates that the allowed direction of 
traverse is backwards.
3. Th
Thee sym
symbo
bols
ls “.“
“.“,  “/ “,  “ ‘  “ are just cosmetic to help the graph to look better.

2.4.2 Setti
tting
ng U
Up
pGGa
adg
dge
et An
Anch
chor
orin
ing:
g: <
<fg
fgaanc
nch>
h>
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
r ight hand edge of its owning container.

. - - - <-
<- - - - - - - - - - - - - .
/ |
>- - <f ga
ganc h> - - - - - - - - - - - +- - ANCHOR - - +- - +- L ef t - - - - . |
| +- Ri ght - - - | |
| +- Top - - - - - | |
| ‘- Bot t om
om - - +- - - +- - - *
| |
+- - - - None - - - - |
‘ - - - - Al l - - - - - - ’ - - >

Figure
Figure 2:1.
2:1. Syn
Syntax
tax Graph
Graph -: Gad
Gadget
get Anc
Anchor
horing
ing

2.4.3 Setti
tting
ng U
Up
pGGa
adg
dge
et D
Doc
ocki
king
ng:: <
<fg
fgdo
dock
ck>>
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.

>- - <f g
gddoc k> - - - - - - - - - - - +-
+- - DOCK - - - - +- - - - - L
Leef t - - - - .
+- - - - Ri ght - - - |
+- - - - Top - - - - - |
+- - - - Bot t omom - - |
+- - - - None - - - - |
‘ - - - - Fi l l - - - - ’ - - >

Figu
Figure
re 2
2:2
:2.. Synt
Syntax
ax G
Gra
raph
ph - Gadg
Gadget
et D
Doc
ocki
king
ng

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.

2:7 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.4.4 Setting-
tting-U
Up tthe
he Gadge
dget’s
t’s Positio
osition:
n: <fgpos
fgpos>> and <f
<fgprl>
gprl>
You can use the AT syntax, shown below on the <fgpos> graph, to define the position of a
gadget’s 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.

>- - <f gp
gpos > - - AT - - +- val val - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .
+- X val - - - - - - - - - - - - . |
+- XMI N - . | |
+- XCEN - | | |
+- XM XMAX - +- <f gpr l > - | |
‘ - - - - - - - - ‘ - - - - - - - - - - - +- Y val - - - - - - - - - - - - |
+- YMI N - . |
+- YCEN - | |
+- YMAX - ‘ - <f ggp pr l > - |
‘--------------------‘-->

Figure
Figure 2:3.
2:3. Syn
Syntax
tax Gra
Graph
ph - Abso
Absolut
lute
ePPosi
ositio
tionin
ning
g

The subgraph <fgprl>, shown below, sets the gadget position relative to another gadget or 

the
of aform’s
form. extent. For example, you can use it to position a gadget halfway across the width

>- - <f gpr l > - - +- <gname> - .

+- - FORM - - - |
‘ - - - - - - - - - - - +- * val - - - - - .
| |
+- + v
va
al - - . |
+- - val - - ‘ - - +- + v vaal * SI Z ZEE - -- .
| +- - va val * SI ZE - - - |
| +- + SI ZE - - - - - - - - - |
| +- - SI ZE - - - - - - - - - |
| ‘------------------|
+- + SI ZE
ZE - - - - - - - - - - - - - - - - - - - - - - - |
+- - SI ZE
ZE - - - - - - - - - - - - - - - - - - - - - - - |
‘--------------------------------‘-->

Figure
Figure 2:4.
2:4. Syn
Syntax
tax Graph
Graph -: Rel
Relati
ative
ve Pos
Positi
itioni
oning
ng

Examples of Using the AT Synta

Syntax
x

AT 5 7. 5 Puts gadget origin at form grid coordinates (5, 7.5).

AT X 5. 5 Puts gadget origin at form grid coordinates
coordinate s (5.5, y) where
y is calculated automatically from the y extremity of the
last placed gadget and the current VDISTANCE setting.
AT YMAX+1 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.

2:8 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

AT XMI N. GAD1- 2 Positions new gadget with respect to two existing

 YMAX. GAD2+1 gadgets. Gadget is offset by 2 grid units to the left of 
GAD1(X=XMIN-2) and 1 unit below .GAD2
(Y=YMAX+1).
AT XMAX FORM
FORM- SI ZE YMAX XMAX FORM refers to the current right hand size of the
FOR
FORM- SI ZE form at its current stage of definition (not its final
maximum extent). YMAX FORM refers to the form’s
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.

2.4.5 Setting Up th
thee Gadge
dget’s
t’s Widt
idth
haand
nd Height: <vsha
vshap>
p>
This operation allows you to set a gadget’s width and height.

>- - <vs h
ha
ap> - - +- <vwi d> - - +- <vhei > - - - - - - - - .
| +- ASPec t ( h/ w) - - |
| ‘-----------------‘-->
|
‘ - <vhei > - - +- <vwi d> - - - - - - - - .
+- ASPec t ( h/
h/ w) - - |
‘-----------------‘-->

Figure
Figure 2:5.
2:5. Syn
Syntax
tax Graph
Graph -: G
Gadg
adget
et G
Geom
eometr
etry
y<<vs
vshap
hap>
>

h/w is the value of the Aspect Ratio (height/width).

The units for <vshap> will have
ha ve been preset to pixels or F&M grid units, a
appropriately
ppropriately..
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.

Se
Setting
tting the Height:
Height: <vwid>

>- - <vwi d> - - WI Dt h - +- val - - - - - - .

+- <gname> - - |
‘------------‘-->

Setting the Width: <vhei>

>- - <vhei > - - HEI ght - +- val - - - - - - .

+- <gname> - - |
‘------------‘-->

2:9 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.4.
2.4.6
6 Se
Setting
tting Up the Ga
Gadget’s
dget’s Tagwidth ((TE
TEXT
XT,, TOG
OGGLE
GLE and OP
OPTI
TION
ON):
):
<fgtagw>
The TAGWIDTH specifies the size of the gadget’s 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

>- - <f gt ag
a gw> - - +- TAGWI Dt h val - +- - - - - - - - - - - - - .
‘ - - - - - - - - - - - - - - - - ‘ - - t ag
agt ex
ext - - ‘ - - >

Figure
Figure 2:6.
2:6. Syntax
Syntax Graph
Graph -: Gad
Gadget
get Tagw
agwidt
idth
h

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
nu mber 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 th
thee Gadge
dget’s
t’s 2D Scre
cree
en P
Positio
osition:
n: <
<xypos
xypos>>
This shows how to set up a gadget’s 2D screen position in normalized co-ordinates.

<xypos >- - +- XR val - +- YR val - .

‘ - YR val - +- XR val - ‘ - - >

Figure
Figure 2:7.
2:7. Synta
Syntax
x Gr
Graph
aph - Gadget
Gadget's
's 2
2d
d Sc
Scree
reen
n Po
Posit
sition
ion

Note: Normalized co-ordinates represent a proportion of the full screen size.

0. 0 <= an d 0. 0 <= YR <= 1. 0.
<= XR <= 1. 0 and

2:10 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5 Ob j ec t Ty
Ty p e Detai l s
This section contains details of the object types listed in Table 2: 1.: Object Types and
Classification.

2.5.1 A L ERT Ob j ec t

Methods

Nam e Res u l t Pu r p o s e

Conf
onf i r m( Message
essage i s STR
STRI NG, X i s STRING Show a blocking CONFIRM
REAL,
EAL, Y i s REA
REAL
L ) ‘YES’ OR ALERT and retrieve the
‘NO’ response. X  and Y  are
optional screen positions.
Er r or ( Messag
essage i s STR
STRI NG, X i s STRING Show a blocking ERROR
REAL,
EAL, Y i s REAREAL
L )  ‘YES’ ALERT and retrieve the
response. X  and Y  are
optional screen positions.
Message(
essage( Message i s STRI
STRI NG, X i s STRING Show a blocking MESSAGE
REAL,
EAL, Y i s REA
REAL)
L)  ‘YES’ ALERT and retrieve the
response and retrieve the
response. X  and Y  are
optional screen positions.
Que
uest
st i on(
on( Message
essage i s STR
STRI NG, X i s STRING Show a blocking QUESTION
REAL,
EAL, Y i s REA
REAL
L ) ‘YES’, ‘NO’ ALERT and retrieve the
OR response. X  and Y  are
‘CANCEL’ optional screen positions.
War ni ng(
ng( Message i s STR
STRI NG, X i s STRING Show a blocking WARNING
REAL,
EAL, Y i s REA
REAL)
L)  ‘YES’ ALERT and retrieve the
response and retrieve the
response. X  and Y  are
optional screen positions.
! ! Al er t . I nput ( ! pr ompt i s STRING Show a blocking INPUT
STRI
TRI NG, ! def aul t i s S STR
TRII NG) i s ALERT. !prompt   is the
STRII NG
STR prompt displayed to the user,
and !default   is the default
value in the text box.
! ! Al er t . I nput ( ! pr ompt i s STRING Show a blocking INPUT
STRI
TRI NG, ! def aulaul t i s STR
STRII NG, xPos
xPos ALERT. !prompt   is the
i s RE
REAL, yPos yPos i s RE
REAL) i s STRSTRII NG prompt displayed to the user,
and !default   is the default
value in the text box. xPos
and yPos   are the
coordinates of the top left-
hand corner of the alert box.

Tab
able
le 2: 5. Aler
Alertt Obj
Objec
ectt M
Met
etho
hods
ds

2:11 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.2 A RC Ob j ec t

Basic ARC Definit

Definit ion: Members
Members

Nam e Ty p e Pu r p o s e
Or i ent at i on ORIENTATI Orientation of the arc.
ON
Get/Set
Pos i t i on POSITION Origin/Centre of the arc.
Get/Set
Radi
adi us REAL Radius of the arc
Get/Set
St ar t Angl e REAL Angle from X axes to start of 
Get/Set the arc.
EndA
EndAng
ngll e REAL Angle from X axes to end of 
Get/Set the arc.

Sense BOOLEAN Arc sense:

Get/Set
·0 for clockwise
·1 for anti-clockwise

Table
able 2
2:: 6. Basi
Basic
cAARC
RC Defin
Definit
itio
ion
nMMem
embe
bers
rs

Basic ARC Definitio

Definitio n: Methods
These methods do not modify the original object.

Nam e Res u l t Pu r p o s e

Ar c( POSI TI ON, ORI ENTATI

TATI ON, ARC Creates an arc with the given
REAL,
EAL, REAL,
EAL, REAL,
EAL, BOOLEAN)
LEAN) Position, Orientation, Start
Angle, End Angle, Radius. If 
the last argument is TRUE,
the arc is clockwise.
St r i ng( ) STRING Returns the arc as a string

Table
able 2: 7. Basi
Basic
c ARC
ARC Defi
Defini
niti
tion
on Meth
Method
ods
s

2:12 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

 ARC Met ho ds th at Ret ur n A RCs

None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

St ar t Posi t i on( POSI TI ON) ARC 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.
EndPo
Posi
si t i on(
on( POSI TI ON) ARC As St ar t Pos i t i on, but for 
the EndA
EndAngngll e.
 Thr ough(
ough( POSI
POSI TI ON) ARC Returns a new arc, where the
radius (of the full circle)
passes through the passed
position when mapped onto
the arc plane.
Cho
horr dHei ght
ght ( REAL)
EAL)
ARC Returnoriginal,
the s a new arwhere
c, based the
on
EndA
EndAngngll e  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.
Chor d( REAL)
EAL) ARC R e tu r n s a new arc,
maintaining the original
St ar t Angl e, so the
EndA
EndAng ngll e is at the specified

distance from the Start

Chord length > Radius * 2 or 
< 0 return an unset object.
Ci r c l e( ) ARC Returns a full circle definition
of the arc.
Ci r cl e( BOOLEAN
LEAN) ARC Returns a full circle definition
of the arc. If True, the arc is
anti-clock-wise
Compl ement ( ) ARC Returns the complementary
arc of the arc definition (the
remainder of the circle)

Table
able 2: 8. ARC
ARC Met
Metho
hods
ds that
that Retu
Return
rn AR
ARCs
Cs

2:13 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

EndPosition(POSITION)
Through(POSITION)

Complement()

Cord(REAL)

CordHeight(REAL)
StartPosition(POSITION)

Figu
Figure
re 2
2:8
:8.. AR
ARCs
Cs Retu
Return
rned
ed b
by
y AR
ARC
CMMet
etho
hods
ds

 ARC Met ho d t hat Retu rn s POSITIONs

POS ITIONs
This method does not modify the original object.

Nam e Res u l t Pu r p o s e

Angl ePo
Posi
si t i on(
on( REAL) POSITIO
POSITION
N Returns
Returns the pospositi
ition
on aatt the
the
specified angle on the arc.

Table
able 2
2:: 9. AR
ARC
C Met
Metho
hods
ds ttha
hatt Re
Retu
turn
rn P
POS
OSIT
ITIO
IONs
Ns

 A
 An
ngle
leP
Posit
itio
ion
n(REAL)

Figure
Figure 2:9.
2:9. PO
POSIT
SITION
IONs
s Ret
Return
urned
ed by ARC
ARC Met
Method
hods
s

2:14 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

 ARC Met ho ds th at Ret ur n DIRECTIONs

None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Angl eDi r ect i on(

on( REAL) DIRECTI
DIRECTION
ON Returns
Returns the directi
direction
on from
the centre of the arc through
a point at the given angle
from the X axis
St ar t Ta
Tan
ngent ( ) DIRECT
DIRECTION
ION Returns
Returns the direct
direction
ion out of 
the arc, tangential to the start
angle line. The “sense” of the
arc is used.
EndTa
EndTang
ngen
entt ( ) DIRECT
DIRECTION
ION Returns
Returns the direct
direction
ion out of 
the arc, tangential to the end
angle line. The “sense” of the
arc is used.
Angl
ngl eTang
eTangen
entt ( REAL)
EAL) DIRE
DIRECT
CTIO
ION
N Retu
Return
rnss the dir
direc
ecti
tion
on,,
tangential to the angle

passed.
Tabl
able
e 2: 10. ARC M
Meth
ethods
ods that
that Ret
Return
urn DI
DIREC
RECTIO
TIONs
Ns

 
 A
 An
ngle
leD
Dir
ire
ecti
tio
on(REAL)
EndTangent()

 A
 An
ngleT
leTangent(
t(R
REAL)
StartTangent()

Figure
Figure 2:1
2:10.
0. DIRE
DIRECTIO
CTIONs
Ns Retur
Returned
ned b
by
y AR
ARC
CMMethods
ethods

 ARC Met ho ds th at Ret ur n XYOf fs ets

This method does not modify the original object.

Nam e Res u l t Pu r p o s e

XYOf f set ( POSI TI ON) XYPOSITI Returns the position, mapped

ON onto the arc plane, in term of 
an XY offset from the arc plane
origin

Figure
Figure 2:
2:1
11. ARC Methods
Methods that Retu
Return
rn X
XYOffs
YOffsets
ets

2:15 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

XYOffset
Offset POSITION
SITION

Figure
Figure 2:1
2:12.
2. XYOf
XYOffset
fsets
sRReturn
eturned
ed fr
from
om ARC Methods
Methods

 ARC Met ho ds th at Ret ur n REA Ls

None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Pr opor
opor t i on(
on( REAL) REAL 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)
StartAngle * <real> +
Angl e( ) REAL R e tu r n s th e s u b te n d e d a n g l e
of the arc
Near ( POSI TI ON) REAL Returns the position, in terms
of an angle from the X axis,
to the position on the arc
plane of the passed position

Tabl
able
e 2: 11.
11. ARC Method
Methods
s tha
thatt Ret
Return
urn R
REAL
EALs
s (a)

Ne
Near
ar POSITION

Proportion(REAL)

Figure
Figure 2:1
2:13.
3. REAL
REALs
sRReturn
eturned
ed by ARC Methods
Methods (a)

2:16 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Cho
horr d( ) REAL Returns the chord length
between the start and end of 
the arc definition
Len
Lengt h( ) REAL Returns the true length of the
arc line
Cho
horr dHei ght
ght ( ) REAL Returns the chord height of  
the arc line

Tabl
able
e 2: 12. ARC
ARC Met
Method
hods
s tha
thatt Ret
Return
urn R
REAL
EALs
s (b)

  Chord()

Length()

ChordHeight()

Figure
Figure 2:1
2:14.
4. REAL
REALs
sRReturn
eturned
ed by ARC Methods
Methods (b)

 ARC In ter sec ti on Meth od s t hat Retu rn REAL ARRAYs

None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

I nt er secti
secti ons( LI NE) REAL Returns the intersection
ARRAY points, in terms of angles
from the X axis, of the
passed line (mapped onto
arc plane) with the circle
defined by the arc
I nt er se
sect
ct i ons(
ons( PLA
PLANE) REAL Returns the intersection
ARRAY points, in terms of angles
from the X axis, of the
passed plane with the circle
defined by the arc

2:17 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

I nt er se
sect
ct i ons(
ons( ARC) REAL Returns the intersection
ARRAY 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.
13. ARC In
Inters
tersectio
ection
n Meth
Methods
ods th
that
at Retu
Return
rn REA
REAL
L ARRA
ARRAYs
Ys

  Inte
Interse
rsection
ctions
s LINE
LINE Intersections(PLANE)

Intersections(ARC)

Figure
Figure 2:15. REAL AR
ARRA
RAYs
Ys Ret
Returned
urned by A
ARC
RC Int
Intersec
ersection
tion Me
Methods
thods

 ARC Tangent
Tang ent Meth od s Ret ur ni ng Real A rr ays

None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

 Tangent
 Tangent s( POSI
POSI TI ON) REAL Returns the points of 
ARRAY tangency on the arc circle
from the passed position, in
terms of angles from the X
axis,
 Tangent
 Tangent s( ARC) REAL Returns the points of 
ARRAY tangency on the arc circle for 
the passed arc circle, in
terms of angles from the X
axis

2:18 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Spl i t ( ) REAL Splits the arc into a non-zero

ARRAY number of segments
Pol e( ) POSI
POSITI
TION
ON Retu
Return
rnss tthe
he pole
pole posi
positi
tion
on of 

the arc
Table 2: 14.
14. ARC T
Tangent
angent M
Methods
ethods that Re
Return
turn R
REAL
EAL ARRA
ARRAYs
Ys

  Tangents(POSITION)

Tangents(ARC)

Figure
Figure 2:16. REAL A
ARRA
RRAYs
Ys Returned
Returned fro
from
m ARC T
Tangen
angentt Metho
Methods
ds

 ARC Met ho ds th at Ret ur n B OOLEA Ns

None of these methods modify the original object.

Nam e Res u l t Pu r p o s e

On( POSI
POSI TI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the pass
passed
ed

position lies on the arc line

OnP
nPrr oj ect ed(
ed( POSI TI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the pass
passed
ed
position, when projected onto
the arc line, lies within it
OnExt ended(
ended( POSI
POSI TI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the pass
passed
ed
position, when mapped onto
the arc line, lies outside it

Tabl
able
e 2: 15. ARC Method
Methods
s tha
thatt Ret
Return
urn B
BOO
OOLEA
LEANs
Ns

2:19 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

  On(POSITION)

On(POSITION)

Figure
Figure 2:17
2:17.. ARRA
ARRAY
Y Object
Object PML Built-
Built-in
in T
Type
ype

2.5.3 A RRAY Ob j ec t

Methods

Nam e Res u l t Pu r p o s e
Append(
ppend( ANY val ue) NO RESU
RESUL
LT Appe
Append
nd value  as a new
element at the end of array.
Appen
ppendA
dArr r ay( ARRAY val ues)
ues) NO RESU
RESUL
LT Appe
Append
nd array  values as new
elements at the end of array.
array.
Cl ear ( ) NO RESUL
RESULT Remove
Remove all ele
elemen
ments.
ts.
Compr ess ( ) NO RESUL
RESULT Remove
Removed d all und
undefi
efined
ned
elements and re-index
remaining elements.
Del et eFr om( REAL
EAL i ndex,
ndex, REAL
EAL n) ARRAY Make undefined n   elements
starting at index . Remaining
elements are not re-indexed

Returns
deleted an array of
elements the
(which
need not be assigned if not
wanted).
Del et eFr om( REAL
EAL i ndex)
ndex) ARRAY Make undefined elements
from index  to end of array.
Returns an array of the
deleted elements.
Remaining elements not re-
indexed.

2:20 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Del et eTo(
eTo( REAL
EAL i ndex
ndex,, REAL
EAL n) ARRAY Make undefined n   elements
up to index  Returns an array
of the deleted elements
Remaining elements not re-
indexed.
Del et eTo(
eTo( REAL
EAL i ndex
ndex)) ARRAY Make undefined elements
from start to index   Returns
an array of the deleted
elements Remaining
elements not re-indexed.
Di f f er ence(
ence( ARRAY t wo) ARRAY Return an array of those
elements in the original array
not present in array tw o .
Duplicates will appear only
once
Empt y( ) BOOL
BOOLEA
EAN
N TR
TRUE
UE if arra
arrayy is empt
emptyy
Eval uat e( BLOCK
BLOCK command) NEW Evaluate code in command
ARRAY at each element.
Fi nd( ANY val
val ue)
ue) NEW Search original array for 
ARRAY value and return an array of 
index positions at which it
was found.
Fi ndFi r st ( ANY va
vall ue) REAL R e tu r n i ndex of first
occurrence of value. Returns
UNSET if not found.
Fi r st
st ( ) ANY Return value of first defined
element
Fr om( REAL
EAL i ndex,
ndex, REAL
EAL n) ARRAY Copy sub array of n
elements starting at index.
Fr om( REAL
EAL i ndex)
ndex) ARRAY Copy sub array starting at
index  to end of array
a rray..
Get I ndexe
ndexed(
d( REAL
EAL i ndex)
ndex) ANY Implements ARRAY[index ]
(this is an internal method).
I ndi c e
es
s() NEW Returns an array containing
ARRAY the indices of the target array
that have a value.
I nser t ( REAL i ndex, ANY va
val ue) NO RESU
RESUL
LT Inse
Insert
rt value  as a new
element at index .
Later elements are re-
indexed

2:21 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

I nser
nser t Ar r ay
ay(( REAL i nde
dex,
x, ARRAY NO RESUL
RESULT Insert
Insert values
values as new
ANY val ues)
ues) elements with the first at
index.

Later elements
indexed are re-

I nt er sect ( ARRAY t wo) NEW Return array of elements

ARRAY present in both arrays.
Duplicates will appear only
once.
I nver t ( ) NEW Returns an inverted copy of 
ARRAY the array
arr ay..
Last() ANY Return last element value.
MaxI ndex(
ndex( ) REAL Subscript of last defined
(non-empty) element.
Mi nI ndex( ) REAL Subscript of first defined
(non-empty) element.
Over l ay( REAL
EAL i ndex,
ndex, ARRAY t wo) NEW Replace array elements at
ARRAY index  with elements from the
array tw o . Returns an array
of the elements which were
overwritten (which need not
be assigned if not required).
ReI ndex(
ndex( REAL
EAL AR
ARRAY i ndi
ndi ces) NO RESU
RESUL
LT Ap
Appl
plyy resu
result
lt of 
SORTEDINDICES to re-
order array elements into
positions specified by
indices.

Remove( REAL
REAL nt h) ANY Remove and Return nt h
element (which need not be
assigned if not required).
Remaining elements are re-
indexed.
RemoveF
oveFii r st ( ) ANY Remove and Return first
element (which need not be
assigned if not required).
Remaining elements are re-
indexed.
RemoveFr om( REAL
EAL i ndex, REAL
EAL n) NEW Remove and Return new
ARRAY array of n   elements starting
with index   (which need not
be assigned if not required).
Remaining elements are re-
indexed.

2:22 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

RemoveFr
oveF r om( REAL i ndex) NEW Remove and Return new
ARRAY array of elements from index
to end of array (which need
not be assigned if not
required).
Remaining elements are re-
indexed.
RemoveLast
oveLas t ( ) ANY Remove and Return last
element (which need not be
assigned if not required).
Remaining elements are re-
indexed.
RemoveTo( REAL
EAL i ndex, REAL
EAL n) NEW Remove and Return n
ARRAY elements from start to index
(which need not be assigned
if not required).
Remaining elements are re-
indexed.
RemoveTo( REAL
EAL i ndex) NEW Remove and return elements
ARRAY from start to index   (which
need not be assigned if not
required).
Remaining elements are re-
indexed.
Si z e
e(( ) REAL Returns the number of  
defined elements.
S or t ( ) NO RESUL
RESULT Sort array into ascending
ascending
order.
Sor t Uni que( ) NEW Returns a sorted copy of the
ARRAY array with duplicates
removed.
Sor t edI ndi ce
ces(
s( ) NEW REAL Return new array of indices
ARRAY representing the sorted order 
of elements in array.
The array itself is not sorted.
 To( REAL
EAL i ndex,
ndex, REAL
EAL n) ARRAY Copy sub array of n
elements from start to index.
 To( REAL
EAL i ndex)
ndex) ARRAY Copy susub array from start of  
array to index.
Uni on( ARRAY t wo) NEW Return array of elements
ARRAY present in either array
(duplicates will appear only
once).

2:23 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Uni que(
que( ) NO RESUL
RESULT Discar
Discardd dup
duplic
licate
atess and re-
index remaining elements.
Wi dt h( ) REAL R e tu r n th e m a x i m u m w i d th o f  
string elements
element types (other 
are ignored).

Tabl
able
e 2: 16. ARRA
ARRAY Obje
Object
ct M
Meth
ethods
ods

2.5.4 B A NNER Ob j ec t

Members

Nam e Ty p e Pu r p o s e

Com
Company
pa ny STRING Company na name, up tto
o 12 0
characters.
Copyr
opyr i ght STRING AVEVA cocopyright, u
up
p tto
o 8
80
0
characters.
L i br ar
a r i es ARRAY OF Library names
STRINGS
Nam
Na me STRING Title for main windows, up to
13 characters
Shor
Shor t STRING Short fo
form o
off co
company n
na
am e
St at us STRING PDMS release status

Tabl
able
e 2: 17. BANNE
BANNER
R Obje
Object
ct M
Mem
ember
bers
s

Command

! BANNVAR = BANNER!
ER! $ Returns a BANNER object

2:24 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.5 B A R Gad g et

Methods

Nam e Res u l t Pu r p o s e
Add( STRI
STRI NG dText , STRI
STRI NG enu)
enu) NO RESUL
RESULT Appends
Appends a barmen
barmenuu fiel
field,
d,
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 .
Cl ear ( ) NO RESUL
RESULT Remove
Removess all barm
barmenu
enu fie
fields
lds..
Using this method is
deprecated .

Cl ear
ear ( ST
STR
RI NG dT
dText
ext ) NO RESUL
RESULT Remove
Removess all barme
barmenu
nu fiel
fields
ds
after and including the one
with DTEXT dText .
Using this method is
deprecated .

Fi el dPr oper t y( STRI NG f i el d, BOOL

BOOLEA
EAN
N Ge
Gett the
the valu
value
eooff the
the prop
proper
erty
ty
ST
STRRI NG pr op
oper
er t y) named in pr oper t y  for the
menu field named in f i el d.
The allowed values for the
property are ‘ACTIVE’ or 
‘VISIBLE’.
Ful l Name( ) STRING Get the full name of the
gadget, e.g.'!!Form.bar'.
I nser
ser t Af t er ( STRI NG f i el d, STRI NG NO RESUL
RESULT Ins
Insert
ertss a new barm
barmenu
enu field
field
dText , STRI
STRI NG menu) immediately after the one
identified by f i el d.
The name of the menu is
given in menu; the DTEXT of 
the new field is given by
dText .
I nser
ser t Bef or e( STRI NG f i el d, NO RESUL
RESULT Ins
Insert
ertss a new barm
barmenu
enu field
field
STRI NG dText , STRI
STRI STRI NG menu) immediately before the one
identified by f i el d.
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'

Owner ( ) FORM Get the owning form.

2:25 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Set
Set Act i ve( STRI
STRI NG dText
dText , BOOLEAN
LEAN NO RESUL
RESULT Deacti
Deactivat
vate/Ac
e/Activ
tivate
ate the
st at e) menu field whose DTEXT is
dText .

Using this
deprecated . method is

Set Fi el dPr oper

oper t y( STRI
TRI NG menu
enu, NO RESUL
RESULT Set the
the val
valueue of tthe
he pr
prope
operty
rty
STRII NG pr oper
STR oper t y, BOOLEAN
LEAN st at e) named in pr oper t y with the
value of s t a t e, for the menu
named in menu.
The allowed values for the
property are ‘ACTIVE’ or 
‘VISIBLE’.
Shown( ) BOOLEAN Get sh
shown
own ssttatus
tus.
 Type( ) STRING Get the GADGET type as a
STRING.

Table
able 2
2:: 18
18.. BA
BAR
R Ob
Obje
ject
ct M
Met
etho
hods
ds

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(
dd( )  method.
bar
! t hi s . bar . add ( ' Choos e' , ' Menu1' )
! t hi
hi s . bar . add ( ' wi ndow' , ' Wi ndow' )
! t hi
hi s . ba
bar . ad
add ( ' hel p' , ' Hel p' )
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.

2:26 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.6 B L OCK Ob j ec t
This object holds expressions that
th at are evaluated later.

Methods

Nam e Res u l t Pu r p o s e

Bl ock( STRI
TRI NG ex
expr
pr essi on)
on) BLOCK Creates a block expression.
Eva
vall uat e( ) ANY Evaluate block expression on
object: check result is of 
TYPE type.
Eva
vall uat e( ) ANY Evaluate the expression and
return the result
Ev
Eval
al ua
uatt e( ST
STR
RI NG t yp
ype)
e) ANY Evaluate expression and
return an error if the result is
not of TYPE type. Otherwise
returns the result.

Tabl
able
e 2: 19. BLOCK
BLOCK Ob
Objec
jectt M
Meth
ethods
ods

2.5.7 B OOL EA N Ob j ec
ec t

Methods
None of these methods modifies the original object.
Nam e Res u l t Pu r p o s e
BOOL EAN( REAL val ue) BOOL
BOOLEA
EAN
N Co
Cons
nstr
truc
ucto
torr that
that cr
crea
eate
tess a
boolean Object set to a non-
zero value if boolean is
TRUE; 0 if boolean is FALSE
BOOL EAN( STRI NG val ue) BOOL
BOOLEA
EAN
N Co
Cons
nstr
truc
ucto
torr that
that cr
crea
eate
tess 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.
BOOL EAN( STRI NG val ue, FORM
FORMAT BOOLEA
EAN
N As abov e. F
FO
ORMAT
f or mat ) argument required for 
consistency by Forms and
Menus.
AND
AND( ) BOOL
BOOLEA
EAN
N TR
TRU
UE ifif b
bot
oth
h va
valu
lues
es are
are
TRUE
NOT( ) BOOL
BOOLEA
EAN
N TR
TRUE
UE if FALSE
ALSE;; F
FAL
ALSE
SE if 
TRUE

OR( BOOL EAN val ue) BOOL

BOOLEA
EAN
N TR
TRUE
UE if eith
either
er valu
value
e is
is T
TRU
RUE
E

2:27 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
Real ( ) REAL 1 if boolean is TRUE; 0 if  
boolean is FALSE
St r i ng( ) STRING ‘TRUE’ ifif bo
boolean is
is T
TR
RUE.

‘FALSE’ if boolean is FALSE.

Tabl
able
e 2: 20. BOOLEA
BOOLEAN
N Objec
Objectt M
Meth
ethods
ods

2.5.8 B ORE Ob j ec t

Member 

Nam e Ty p e Pu r p o s e

Si ze REAL The BORE size

Get/Set

Tabl
able
e 2:
2: 2
21.
1. BO
BORE
RE Object
Object Me
Membe
mbers
rs

Methods
None of these methods modifies the original object.
Nam e Res u l t Pu r p o s e
BORE( REAL
EAL val ue) BOOL
BOOLEA
EAN
N Co
Cons
nstr
truc
ucto
torr that
that cr
crea
eate
tess a
BORE object with the given
vall ue.
va
BORE( STRI
STRI NG val
val ue) BOOL
BOOLEA
EAN
N Co
Cons
nstr
truc
ucto
torr that
that cr
crea
eate
tess a
BORE object with the given
val
val ue.
BORE( STRI NG val ue, FORM
FORMAT BOOL
BOOLEA
EAN
N Co
Cons
nstr
truc
ucto
torr that
that cr
crea
eate
tess a
f or mat ) BORE object with the given
vall ue, and in the format
va
specified by f or mat .
EQ( REAL
EAL val ue) BOOL
BOOLEA
EAN
N Co
Comp
mpar
aris
ison
on with
with the
the
argument vavall ue  dependent
on current BORE units.
GEQ(
EQ( BORE bor e) BOOL
BOOLEA
EAN
N TR
TRUE
UE if this
this obje
object
ct is grea
greate
ter 
r 
than or equal to the
argument bor e.
GEQ( REAL
EAL val ue) BOOL
BOOLEA
EAN
N Co
Comp
mpar
aris
ison
on with
with the
the
argument vavall ue  dependent
on current BORE units.
GT( BORE bor e) BOOL
BOOLEA
EAN
N TR
TRUE
UE if BO
BORE
RE grea
greate
terr tth
han
BORE

2:28 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
GT( REAL
EAL val ue)
ue) BOOL
BOOLEA
EAN
N Co
Comp
mpar
aris
ison
on with
with the
the
argument vavall ue  dependent
on current BORE units
LEQ(( BORE bor
LEQ bor e) BOOL
BOOLEA
EAN
N TR
TRUE
UE if this
this obje
object
ct is less
less
than or equal to the
argument bor e.
LEQ( REAL
EAL val ue)
ue) BOOL
BOOLEA
EAN
N Co
Comp
mpar
aris
ison
on with
with the
the
argument vavall ue  dependent
on current BORE units
LT( BORE bor e) BOOL
BOOLEA
EAN
N TR
TRUE
UE if this
this obje
object
ct is less
less
than bor e.
LT( REAL
EAL val ue
ue)) BOOL
BOOLEA
EAN
N Co
Comp
mpar
aris
ison
on with
with the
the
argument vavall ue  dependent
on current BORE units
Real ( ) REAL Convert BORE to a REAL
value
St r i ng(
ng( FOR
FORMAT f or mat ) STRING Convert BORE to a STRING
using the settings in the
global f or mat object.

Figure
Figure 2:18.
2:18. BOR
BORE
EOObje
bject
ct Me
Metho
thods
ds

2.5.9 B UTTON Gad g et

Members

Nam e Ty p e Pu r p o s e

Backgr ound
ound REAL Set or get Background
Set/Get Colour Number 

Backgr ound
ound STRING Set Background Colour 
Set Only Name
Val BOO
BOOLEAN
LEAN TRUE
TRUE when
when the
the butt
button
on is
pressed
FALSE when it is not

Tabl
able
e 2: 22. BUTTO
BUTTON
N Obje
Object
ct M
Memb
embers
ers

2:29 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

AddPi
ddPi xmap(
ap( ST
STR
RI NG f i l e1,
e1, ST
STR
RI NG NO RESUL
RESULT Adds pixm
pixmaps
aps to
to be us
used
ed fo
for 
r 
f i l e2, STRI NG f i l e3 ) the unselected, selected and
AddPi
ddPi xmap(
ap( ST
STR
RI NG f i l e1,
e1, ST
STR
RI NG inactive states. The last two
f i l e2) are optional.
AddPi
ddPi xmap(
ap( ST
STR
RI NG fi l e )
Ful l Name( ) STRING Get the full gadget name,
e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get owning form.
Set Po
Popup(
pup( MENU
ENU menu) NO RESUL
RESULT Links
Links the given
given menu with
the gadget as a popup.
RemovePop
eP opup
up(( MENU menu)
enu) NO RESUL
RESULT Remove
Removess the given popup
popup
menu from the gadget.
Get Pi ckedPop
ckedPopup
up(( ) MENU R e tu r n s th e n a m e o f t h e
menu picked from a popup.
Shown( ) BOOLEAN Get sh
shown
own ssttatus
tus.
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Move
Move keyboard
keyboard ffocu
ocuss to this
gadget.
Ref r esh
sh(( ) NO RESU
RESUL
LT Ref
Refres
resh
h displa
displayy of ga
gadge
dget.
t.
Backgr ound
ound(( ) STRING G et Ba
Background Co
Colour  
Name.
Some gadgets do not
support this property in all
circumstances, e.g. gadgets
which are whose
Gadgets showingcolour
a pixmap.
has
not been set explicitly, may
not have a colour with a
known colourname. In this
case an error is raised..
Set Tool
Tool Ti p( STRI
TRI NG) NO RESUL
RESULT
T Set
Setss the te
text
xt of the T
Tool
ooltip
tip..
 Type( ) STRING Get the gadget-type as a
STRING.

Tabl
able
e 2: 23. BUTTO
BUTTON
N Obje
Object
ct Me
Metho
thods
ds

2:30 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
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 AddPi xmap( )  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
Button has subtypes
subtypes Normal,
Normal, TToggle
oggle and Linklabel.
Linklabel.
2. Linklabels
Linklabels are Buttons
Buttons and so
so they do cause
cause validation
validation of any mo
modified
dified ttext
ext fiel
fields
ds of the
form whenever they are pressed.
3. Li
Link
nkla
labe
bels
ls::
1. cannot
cannot have
have pixma
pixmapsps as
assig
signed
ned to tthem
hem
2. don't
don't support
support change
change ofof backgrou
background nd colour 
colour 
3. don't support 'pressed'
'pressed' and
and 'not
'not pressed'
pressed' value
4. are no
nott encl
enclose
osedd in a bo
boxx
5. can have
have popup menus (though
(though this is not recommended)
recommended)
6. don't have Control
Control Types
Types e.g.
e.g. OK,
OK, CANCEL
CANCEL etcetc
4. The sub-type
sub-type of a Button
Button gadget cancan be queried
queried using th
the
e Button's Su
Subtype
btype met
method.
hod.

2:31 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

.- ----- --< <-- - - - - - - .

/ |
>- BUTTON gname - +- L I NK
NKL abel - +- - t a g
gtt e x
xtt - - - - - - - |
| +- - <f gpos > - - - - - - - |
| +- - CAL L bac k t ext - |
| +- - TOOL TI P t ext - - |
| +- - <f ganc h> - - - - - - |
| +- - <f gdoc k> - - - - - - |
| +- - CORE - - - - - - - - - * Co Core
re ma
mana
nage
ged
d ga
gadg
dget
et
| | . - - - - - - <- - - - - .
| |/ |
| +- F ORM f name - |
| +- <vs hap> - - - - *
| |
| +- TOOL TI P t ext - .
| ' ----------------' -->
|
| .-- ---- --< <-- - - - - - - - - - .
+- - TOGGL E - . / |
' -----------+ +-- t ag
agt eexxt - - - - - - - - - - - |
+- <f gpg pos > - - - - - - - - - - - |
+- CAL L bac k t ex ext - - - - - |
+- TOOL TI P t ex ext - - - - - - |
+- <f ganc h> - - - - - - - - - - |
+- <f gdoc k> - - - - - - - - - - |
+- CORE - - - - - - - - - - - - - - | Co Core
re ma
mana
nage
ged
d ga
gadg
dget
et
+- BACKGr oun ound d <col no>- |
+- PI XMAP <vsh vsha ap> - - - - *
| .-- ----< <-- - - - - .
|/ |
+- FORM f name - |
+- <vs ha hap> - - - - *
|
+- OK - - - - - .
+- APPL Y - - |
+- CANCEL - |
+- RESET - - |
+- HEL P - - - |
' - - - - - - - - - - +- TOOL TI P t e ex
xt - .
'----------------'-->

Figure
Figure 2:19. Synt
Syntax
ax Gr
Graph
aph -: Crea
Creating
ting a B
BUTT
UTTON
ON O
Object
bject
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 gadget’s 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 )

2:32 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
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 recommende
recommended d that when you
you define
define the gadget
gadget you set ititss size to encompa
encompass
ss the
largest pixmap which you will later add. Failure to do this may give rise to unexpected
behaviour.
2. Historically
Historically you
you could add
add a third pixmap
pixmap which
which was used whe
when n the gadge
gadgett was de-
activated. This practice is no longer necessary as the gadget pixmapped is
automatically greyed-out on de-activation.

2.5.10 COLLE
LLEC
CTION O
Obje
bject
ct
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

Nam e Res u l t Pu r p o s e
Col l ec t i on( ) Constructor (initialises all the
object settings).
Scope ( COLL ECTI
ECTI ON) Empties the current scope
list and makes the passed
COLLECTION the current
scope.
Scope
Sco pe ( DBREF)
BREF) Empties the current scope
list and makes the passed
DBREF the current scope.
AddScope Adds the passed DBREF to
the current scope list.

Sc
Scope
ope ( DBREF
BREF ARRAY)
ARRAY) Replaces the passed
list with the current list
scopeof 
DBREFs.
AppendScope
AppendSc ope ( DBREF
BREF ARRAY)
ARRAY) Appends the passed list of 
DBREFs to the scope list.
Cl earScop
arScope( ) Empties the current scope
list.
Fi l t er ( EXPRE
PRESSI ON) Sets the filter to be applied to
the collection.
Cl ear F i l t er ( ) Empties the filter to be
applied to the collection.
 Type ( STRI
STRI NG) Empties the current scope
type list and adds the passed
element type.

2:33 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

AddType( STRI
STRI NG) Adds the passed element
type to the scope type list.
Cl earTypes(
arTypes( ) Empties the types to be
applied to the collection.
 Types ( ARRAY el ement s) Replaces the scope element
type list with the passed list,
elements .

AppendTypes
ppendTypes ( ARRAY t ypes)
ypes ) Appends the passed list,
types , to the scope type list.

I ni t i al i s e( ) Initialises an evaluate list, so

all query actions re-evaluate
the collection rules. Sets
index position to 1.
Fi l t er
er ( ) EXPRESSI Returns the expression used
ON to filter database elements.
Scope
Scope(( ) DBREF Returns the list of database
ARRAY elements to scan.
 Types( ) STRING Returns the list of database
ARRAY element types to be
collected.
Resu
sull t s( ) DBREF Returns the whole collection.
ARRAY
Next ( REAL
EAL n) DBREF Returns sub array from
ARRAY collection of n   elements
starting at current index
position.
I ndex( ) REAL Returns the current index of  
the count being used by
Next( ) .
Si z e ( ) REAL Returns the number of  
elements in the collection.

Tabl
able
e 2: 24.
24. CO
COLLE
LLECT
CTION
ION Object
Object M
Meth
ethods
ods

2.5.11 COLU
LUM
MN Obje
bject
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.

2:34 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Col umn( ) Constructor

object (initialises all the
settings)
Col umn( EXPR
EXPRESSI
ESSI ON, BOOLEAN,
LEAN, Constructor setting
BOOL EAN,
EAN, STRI NG) Expression, Sort, Ascending,
Key
Ke
Key
y ( STRI
STRI NG) Sets key and forces it to be
uppercase
Exprr essi
Exp ess i on ( EXPR
EXPRES
ESSI
SI ON) Defines the expression used
to populate the column
S or t ( ) Switches on column sort
NoSor
oSor t ( ) Switches off column sort, this
is the default setting
Ascendi
scendi ng( ) Sets column sort to
ascending order 
Descendi
escendi ng(
ng( ) Sets column sort to
descending order 
Key
ey(( ) STRING Returns the key word for use
when reporting
Expr
xpr essi on(
on( ) EXPRESSI Returns the expression used
ON to derive the content of the
column
I sSo
sSor t ed( ) BOOL
BOOLEA
EAN
N Re
Retuturn
rnss TR
TRUE
UE if the
the ccol
olum
umn
n
is sorted
Sor t Ty
Typ
pe( ) STRING Returns th e column sort
setting, ascending,
descending or off 
Tabl
able
e 2: 25. COLUM
COLUMN
NOObje
bject
ct Met
Method
hods
s

2.5.12 COLU
LUM
MNFORMAT
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.

2:35 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Col umnFor mat ( ) Constructor

object (initialises all the
settings)
For mat ( FOR
FORMAT) Sets the format of the column
to the passed format
For
Fo r mat ( DATEFORM
ATEFORMAT) Sets the format of the column
to the passed date format
FOR
FORMAT( ' STRI
STRI NG' ) Unsets the format of the
column, i.e. the column
Wi dt h ( REAL)
EAL) Sets the column width
Wi dest ( ) 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.
I nden
ndentt ( REAL, REAL)
EAL) Sets left and right indents
(i.e. spaces) in the column
For mat ( ) FORMAT Returns the format for 
numeric values in a column
Wi dt h( ) REAL 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.
Get Wi de
dest
st ( ) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss TR
TRUE
UE if “wid
“wides
est”
t” is
set
 J ust i f i cat i on( ) STRING R e tu r n s th e column
 justification
Lef
Lef t I ndent ( ) REAL Returns the left indent setting
Ri ght I ndent ( ) REAL Returns th e right i ndent
setting

Tabl
able
e 2: 26. CO
COLUM
LUMNFO
NFORM
RMA
AT Obje
Object
ct Me
Metho
thods
ds

2:36 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.13 COMBO
BOBO
BOX
X Gadge
dgett

Members

Nam e Ty p e Pu r p o s e
Val REAL Get/ Selected option number.
Set
DText ARRAY OF Set or get the entire list of 
STRING display texts.
Get/Set
DTe
Text
xt [ n] STRING Get Get the display text of the
Only n 'th option.

RText ARRAY OF Set or get the list of 

STRING replacement texts.
Get/Set
RText
Text [ n] STRING Get Get the replacement text of 
n
Only the 'th option.
Edi t abl e BOOLEAN Controls editable status of 
Get/Set the text display field
(ComboBox only)
Scr ol
ol l INTEGER Controls the maximum length
Get/Set of a text string which can be
held and scrolled in the
display text field (ComboBox
only)
Count REAL Get count of number of fields
Get only in the list.
Val REAL Selected field as integer.
Get/Set Zero implies no selection.
Setting val  to zero will cause
an error if ZeroSel is not
specified.

Tabl
able
e 2: 27.
27. CO
COMB
MBOB
OBOX
OX G
Gadg
adget
et M
Memb
embers
ers

2:37 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Add(
dd( STRI
STRI NG Dt ext ) NO RESUL
RESULT
T Appe
Append
downnd list,anwhere
e
entry
ntryDtext
to the
the isdro
drop
p
the
text to display in the option
list.
Add(
dd( ST
STR
RI NG Dt ext , ST
STR
RI NG Rt ext ) ) NO RESUL
RESULT
T Append
Append an and
d ent
entry
ry to the drop
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  isn’t specified, it
will be set to Dtext   by
default.
Cl ear ( ) NO RESUL
RESULT
T Cle
Clear
ar ga
gadge
dget’s
t’s con
conten
tents.
ts.
Cl ear Sel ecti on( ) NO RESUL
RESULT
T Cle
Clears
ars sel
select
ection
ion and return
returnss
to default of first in list.
Ful l Name( ) STRING G e t t h e fu l l g a d g e t n a m e ,
e.g.'!!Form.gadget'
Name( ) STRING Get the gadget's name, e.g.
'gadget'
Owner ( ) FORM Get owning form.
Sel ect ( ST
STR
RI NG t ex
extt , STRI
TRI NG va
vall ue NO RESUL
RESULT
T Sel
Select
ect sp
speci
ecified
fied iitem
tem iin
n a list
list::
) text   must be ‘Rtext’ or 
‘Dtext’, and value is the item
to be selected.
Sel ecti on( ) STRING G et cu
current sse
election’s
RTEXT.

Sel ect i on(

on( STRI NG t ext ) STRING Get RTE
current XT or DTtext
selection; EX Tmust
of  
be ‘Rtext’ or ‘Dtext’.
Set Di spl
spl ayTe
ayText
xt ( STRI
TRI NG t ext ) NO RESUL
RESULT
T Set the dis
displa
playy text
text field
field
value, if the gadget is
editable.
Set Po
Popup(
pup( MENU
ENU menu) NO RESU
RESUL
LT Link
Linkss menu   with the gadget
as a popup.
Ref r esh
sh(( ) NOT Refreshes the display of the
RESULT gadget.
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Move
Move keyboar
keyboard
d focus
focus to this
this
gadget.
RemovePo
eP opu
pup(
p( MENU menu)
enu) NO RESU
RESUL
LT Re
Remov
moves
es (p(popu
opup)
p) menu
from the gadget.

2:38 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.
Shown( ) BOOL
BOOLEA
EAN
N Get
Get ‘sh
show
own’
n’ st
stat
atus
us..
 Type( ) STRING G e t th e g a d g e t ty p e a s a
string.
Backgr ound(
ound( ) STRING G et Ba
Background Co
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..

Di spl
spl ayText ( ) STRING Gets tth
he te
displayed texin
t st
strithe
ng cu
cuOption
rrently
gadget's display field.
Set Popup(
Popup( ! menu ) NO RESUL
RESULT
T Assign
Assignss a me
menu
nu obje
object
ct as the
gadget's current popup.
Cl ear ( ! dt ext ) NO RESUL
RESULT
T Del
Delete
ete the
the fi
field
eld w
with
ith tthe
he gi
given
ven
DTEXT string.
Cl ear ( ! f i el dNumber ) NO RESUL
RESULT
T Del
Delete
ete the spe
specif
cified
ied field
field
number.

Tabl
able
e 2: 28.
28. CO
COMB
MBOB
OBOX
OX G
Gadg
adget
et M
Meth
ethods
ods

Command
. - - - - - - - <-
<- - - - - - - .
/ |
>- - COMBObox gnam
gname - +- <f gt agw> - - - - - - |
+- <f gpos> - - - - - - - |
+- <f gan anchch> > ------|
+- <f gdock> ck> - - - - - - |
+- CALLback
LLback t ext - |
+- TOOLTI P t ex extt - - |
+- NORES ESELe
ELectct - - - - |
+- ZERO EROSE SELect
Lect i on - |
+- CORE - - - - - - - - - - * Core manag
anaged
ed gad
adg
get
| . - - - - - - - <-<- - - - - - - .
|/ |
+- SCRol l i nt - - - - |
+- <vwi d> - - - - - - - - *
|
+- TOOLTI P t ext - .
'----------------'-->

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 down-

2:39 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

arrow. 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
Optionsimilar to a windows combobox. It shares most of the properties and methods of the
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
UNSELECT events
events are not notified
notified to PML unless
unless an open
open callback
callback has be
been
en specified
specified
(so that SELECT and UNSELECT events can be differentiated).
2. Typicall
Typicallyy the UNSELECT
UNSELECT action allowsallows Appware
Appware to manage consequeconsequences
nces of 
deselection for any dependent gadgets or forms.
3. We recommend
recommend that you do not change
change the opti
option
on gadget'
gadget'ss selecti
selection
on programmatical
programmaticallyly
in an UNSELECT event.

Text Entry and Edit ing

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
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:40 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.14 CONTAI
AIN
NER Gadge
dgett

Members

Mem b er Nam e Ty p e Pu r p o s e

ty p e STRING Get/Set Gadget type as string 'Container'.

control REAL Get/Set Integer handle of external control.
popup MENU Get/Set Popup menu associated with the control.

Methods

Met h o d Nam e Res u l t Pu r p o s e

ShowPopup(!x is NO RESUL
RESULT
T Sh
Show
ow the asso
associ
ciat
ated
ed popu
popup p a
att the
the spec
specif
ifie
ied
d
REAL, !y is REAL ) position. Position is the integer pixel position

within the enclosed control.

FullName( ) STRING Get the full gadget name, i.e. !!Form.gadget.
N am e( ) STRING Get the gadget's name
Owner( ) FORM Get owning form
GetPickedPopup( ) MENU Returns the last picked popup menu for the
gadget.
Shown( ) BOOLEAN Get 'shown' status.

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.
. --<
<-- - - - - .
/ |
>- - - - CONTAI
TAI NER gnam
gname - +- NOBOX - - - |
+- I NDENT - - *
|
' - PMLNETLNET// CONTRO TROL - +- ha handndll e - .
'----------|
. - - - - <- - - - - - - - - - - - - - - - - - - - - - - - *
|
| . - - - - <- - - - - - - - - - - - - - - - - .
|/ |
+- - t ag agt eexxt - - - - - - - - - - - - - |
+- - <f gpos > - - - - - - - - - - - - - |
+- - <f ganc h h>> ------------|
+- - <f gdoc k
k>
> ------------*
|

2:41 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

+- - <vshape>
vs hape> - .
'-------------'-->

Notes:
1. By default the
the Container
Container will
will be enclosed
enclosed in a box, box, but you can sselect
elect NOBOX
NOBOX or 
INDENT.
2. Only
Only PMLNet
PMLNet contr
controls
ols are
are suppor
supported
ted..
3. 'handle'
'handle' is the
the inte
integer
ger token
token identifyi
identifying
ng the contro
control.l.
4. Positioning
Positioning must
must be specified
specified before
before size
size (<vshape>
(<vshape>). ).
5. Dock and Anchor
Anchor are supported
supported to allow intellig
intelligent
ent resize be
behaviou
haviour.
r. The en
enclosed
closed
control must support resizing and is usually set as Dock fill, so that it follows size
changes of the Container.

2.5.15
.15 DATEFORMAT Obje
bject
ct
The DATEFORMAT
DATEFORMAT object is used to allow date attributes to be sorted in date order.
Examples:

! f or mat = obj ect DATEFORMAT( T D/ M/ Y’ )

! f or mat . mont
ont h( ‘ I NTEG
TEGER’ )
! f or mat . year ( 2) $ 12:10 05/01/01

! f or mat = obj ec t DATEFORMAT( ‘ T D M Y’ )

! f or mat . mont h( ‘ BRI EF’ ) $ 12:10 05 Nov 01

! f or mat = obj ec t DATEFORMAT ( ‘ D M’ )

! f or mat . year ( 4)
! f or mat . mont
ont h( ‘ FULL)
FULL) $ 5 November 2001

2:42 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Dat eFor mat ( STRI

STRI NG f or mat ) 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.
Dat eFor mat ( ) Sets default format (‘T M D Y’,
month = ‘INTEGER’, year = 2)
Mont h( STRI
STRI NG) Sets month format. 'INTEGER',
'BRIEF' or 'FULL'

 Year ( I NT) Sets year format. 2 or 4 for 

number of digits
St r i ng( DATETI
TETI ME) STRING Input a date in DATETIME
format and convert to the
specified format.
St r i ng( STRI
TRI NG) STRING Input a date in PDMS format and
convert to the specified format.

Table 2: 29. DA
DATEFO
TEFORMA
RMAT
T Object
Object M
Methods
ethods

2.5.16 DATETIME Obje

bject
ct

Methods

Nam e Res u l t Pu r p o s e

Dat eTi me( ) DATE

DATETI
TIME
ME Cr
Creaeate
te a DA
DATE
TETI
TIME
ME o obj
bjec
ectt
with current date and time in
it.
Dat eTi me( REAL
EAL year , REAL
EAL mont
ont h, DATE
DATETI
TIME
ME Cr
Crea
eate
te a DA
DATE
TETI
TIME
ME set
set to
to
REAL
EAL dat e) the given year, month, date.
Time defaults to 00:00:00.
Dat eTi me( REAL
EAL year
year , DATE
DATETI
TIME
ME As abov
above,
e, but
but mmon
onth
th is a
  STRI NG mont h. STRING at least three
  REA
REAL dat e) characters long representing
month e.g. ‘Jan’, ‘March’,
‘DECEM’

2:43 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Dat eTi me( REAL

EAL year , REAL
EAL mont
ont h, DATE
DATETI
TIME
ME Cr
Crea
eate
te a DA
DATE
TETI
TIME
ME oobj
bjec
ectt
REAL
EAL dat e, set to given year, month,
  REA
REAL
L hour , REAL
EAL mi nut e) date, hour, minute. Seconds
default to 0.
Dat eTi me( REAL
EAL year
year , DATE
DATETI
TIME
ME As abov
above,
e, but
but mmon
onth
th is a
  STRI
STRI NG mont h, REAL
EAL dat e, REAL
EAL STRING at least three
hourr , REAL
hou EAL mi nut
nut e) characters long representing
month e.g. ‘Jan’, ‘March’,
‘DECEM’
Dat eTi me( REAL
EAL year , REAL
EAL mont
ont h, DATE
DATETI
TIME
ME Cr
Crea
eate
te a DA
DATE
TETI
TIME
ME o obj
bjec
ectt
REAL
EAL dat e, REAL
EAL hour
hour , REAL
EAL set to given year, month,
mi nut
nut e, REAL
EAL s econd)
econd) date, hour, minute, second.
Dat eTi me( REAL
EAL year , STRI
STRI NG DATE
DATETI
TIME
ME As abov
above,
e, but
but mmon
onth
th is a
mon
ontt h, REAL
EAL dat e, REAL
EAL hour
hour , STRING at least three
REAL
EAL mi nut e, characters long representing
REAL second)
month e.g. ‘Jan’, ‘March’,
‘DECEM’

Dat e( ) REAL Return day of month for this

DATETIME object (1-31).
GEQ(
EQ( DATETI ME) BOOL
BOOLEA
EAN
N Test
est whe
wheth
ther
er this
this DA
DATE
TETI
TIME
ME
is later than or the same as
argument DATETIME.
GT( DATETI ME) BOOL
BOOLEA
EAN
N Test
est wh
whet
ethe
herr tthi
hiss date
date is
later than argument
DATETIME.
HOUR(
UR( ) REAL Return hour as REAL for this
DATETIME object (0-23).
LEQ(( DATETI ME)
LEQ BOOL
BOOLEA
EAN
N Test
est whe
wheth
ther
er this
this DA
DATE
TETI
TIME
ME
is earlier or the same as
argument DATETIME
LT( DATETI ME) BOOL
BOOLEA
EAN
N Test
est whe
wheth
ther
er this
this DA
DATE
TETI
TIME
ME
is earlier than argument
DATETIME.
Mi nut e( ) REAL Return minutes as REAL for  
this DATETIME object (0-
59).
Mont h( ) REAL Return month as REAL for  
this DATETIME object (1-
12).
Mont
ont hSt r i ng( ) STRING Return mo month aass ST
STRING
for this DATETIME object
(‘January’, ’February’, etc.)

2:44 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Second
Second(( ) REAL Return number of seconds
as REAL for this DATETIME
object (0-59).

 Year ( ) REAL Return year as REAL

(e.g. 1998)

Tabl
able
e 2: 30.
30. DA
DATET
TETIM
IME
E Objec
Objectt Me
Metho
thods
ds

2.5.17 DB O
Ob
b j ec t

Members

Nam e Ty p e Pu r p o s e

Nam
Name STRING The name of the database,
up to 32 characters.

Descri pt i on STRING Th120

to e da
dacharacters.
tabase d
de
escription, up
up

Access STRING Access type (UPDATE,

MULTIWRITE,
CONTROLLED).
Cl ai m STRING Claim mode for multi-write
databases (EXPLICIT,
IMPLICIT).
Fi l e STRING Database filename, up to 17
characters.
Fo
Forr ei gn STRING FOREIGN or LOCAL
Number STRING Database n
nu
um ber  
 Team TEAM Owning Team
 Type STRING Database ttyype, e.g. DESI
Ref no STRING String cco
ontaining D
Da
atabase
reference number 
Pr i mar y STRING Id e n ti fi e s w h e th e r a
database is PRIMARY or 
SECONDARY at the current
location in a global project

Table
able 2
2:: 31
31.. DB O
Obj
bjec
ectt Me
Memb
mber
ers
s

2:45 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

MDBLi st ( ) ARRAY L ist DB.

this of MDBS which contain

Si z e
e(( ) REAL File size in pages.
Sessi ons(
ons( ) ARRAY OF All sessions of the current
DBSESS database.
La
Last
st sessi
sessi on( ) DBSESS
SESS Last session information for 
database.
DB( DBREF
BREF)) DB Returns a DB object, given a
DBREF.
DB( STRI NG) DB Returns a DB object, given a
name or reference number.

Table
able 2
2:: 32
32.. DB O
Obj
bjec
ectt Me
Meth
thod
ods
s

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

! D = OBJ ECT DB( ! ! CE)

! D = OBJ ECT 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

2:46 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.18 DB R
RE
EF O
Ob
b je
j ec t

Methods

Nam e Res u l t Pu r p o s e
Dbr ef ( ST
STR
RI NG ) DBREF Creates a DBREF object with
value set to the given
STRING.
Dbr ef ( STRI
STRI NG, FOR
FORMAT ) DBREF As above. FORMAT
argument required for 
consistency by Forms and
Menus.
At t r i but
but e( ST
STR
RI NG Name) ANY Return the value of the
named Attribute
At t r i but es ( ) ARRAY OF A DBREF appears to have
STRING the attributes of whatever DB
elements it is pointing to
BadR
adRef ( ) BOOL
BOOLEA
EAN
N TR
TRUUE ifif D
DBR
BREF
EF is nnotot va
valilid
d
(cannot navigate to it)
Del et e( ) NO RESUL
RESULT
T Del
Deletes
etes the PML DBREF
(not the database element it
is pointing to)
MCount
ount ( ) REAL Count of number of members
of element referenced
MCount
ount ( STRI
STRI NG t ype) REAL Count of number of members
of element referenced of type
specified
St r i ng(
ng( FOR
FORMAT) STRING Convert to STRING using
settings in global FORMAT
object
Li ne
ne(( [ CUT/ UNCUT] ) L IN E Returns the cut/uncut pline of  
a SCTN/GENSEC element
as a bounded line
PPosi
Posi t i on(
on( REAL) POSI
POSITI
TION
ON Retu
Return
rnss the
the posi
positi
tion
on of the
the
specified Ppoint of a
database element.
PDi r ect i on(
on( REAL) DIRECT
DIRECTION
ION Return
Returnss tthe
he direct
direction
ion of the
specified Ppoint of a
database element.

Table
able 2
2:: 33
33.. DB O
Obj
bjec
ectt Me
Meth
thod
ods
s

2:47 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.19 DBS
BSE
ESS Obje
bject

Members

Nam e Res u l t Pu r p o s e
Number REAL Session number  
Dat e STRING D a te w
wh
hen sse
ession st
started
Aut hor STRING Creator of session
Co
Commment STRING Session comment

Tabl
able
e 2: 34. DBSESS
DBSESS Ob
Objec
jectt M
Memb
embers
ers

2.5.20 DIRECTION O
Obje
bject
ct

Members

Nam e Ty p e Pu r p o s e

East REAL UP component

Get/Set
Nor t h REAL NORTH component
Get/Set
Up REAL UP component
Get/Set
Or i gi n DBREF DB element that is the origin
Get/Set

Tabl
able
e 2: 35.
35. DIR
DIREC
ECTIO
TION
N Ob
Objec
jectt Me
Membe
mbers
rs

Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Di r ect
ect i on(
on( STRI
TRI NG ) DIRECT
DIRECTION
ION Create
Createss a DIR
DIRECTI
ECTION
ON with
with
the value given by STRING.
Di r ect i on
on(( ST
STR
RI NG, FOR
FORMAT ) DIRECT
DIRECTION
ION Create
Createss a DIR
DIRECTI
ECTIONON with
with
the value given by STRING,
in the format specified.
EQ( DI RECTI
ECTI ON) BOOL
BOOLEA
EAN
N TR
TRUE
UE if tw
two
o dire
direct
ctio
ions
ns are
are
the same

2:48 12 Series
 

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

LT( DI RECTI
ECTI ON) BOOL
BOOLEA
EAN
N TR
TRUE
UE if dire
direct
ctio
ion
n is
is lles
esss ttha
han
n
argument
St r i ng(
ng( FOR
FORMAT) STRING Convert to STRING
WRT( DBREF)
BREF) DIRE
DIRECT
CTIO
ION
N Conv
Conver
ertt to a new
new
DIRECTION with respect to
a given element.
Angl
ngl e( DI RECTI
ECTI ON) REAL Returns the angle between
the two directions
Bi sect ( DI RECTI
ECTI ON) DIRECT
DIRECTION
ION Return
Returnss tthe
he direct
direction
ion whi
which
ch
is half way between the two
directions
Cr oss( DI RECTI
ECTI ON) DIRECT
DIRECTION
ION Return
Returnss tthe
he cros
crosss prod
product
uct of 
the two directions
Dot ( DI RECTI
ECTI ON) REAL Returns the dot product of  
the two directions

I sPa
sPar al l el ( DI RECTI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the ssup
uppl
plie
ied
d
directions are parallel, false
otherwise.
I sPar
sPar al l el ( DI RECTI ON, REAL) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the ssup
uppl
plie
ied
d
directions are parallel
according to tolerance
supplied, false otherwise.
Opposi t e( ) DIRE
DIRECT
CTION
ION Retu
Return
rnss th
the
e oppo
opposi
site
te
direction
Or t ho
hogo
gona
nall ( DI RECTI
ECTI ON) DIRE
DIRECT
CTIO
ION
N Retu
Returns
rns tthe
he di
dire
rect
ctio
ion
n
orthogonal between the two
directions
Pr oj ect ed(
ed( PLAN
PLANE) DIRECT
DIRECTION
ION Return
Returnss a direct
direction
ion proj
projecte
ected
d
onto the passed plane.
I sPer
sPer pendi cul
cul ar ( DI RECTI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the ssup
uppl
plie
ied
d
directions are perpendicular,
false otherwise.
I sPer
sPer pendi cul
cul ar ( DI RECTI ON, REAL) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the ssup
uppl
plie
ied
d
directions are perpendicular 
according to tolerance
supplied, false otherwise.

Tabl
able
e 2: 36.
36. DIR
DIRECT
ECTION
ION Object
Object Met
Method
hods
s

2:49 12 Series
 

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.21
.21 EXPRESSION Obje
bject
ct
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

Nam e Res u l t Pu r p o s e

Expr
xpr essi on Constructor (initialises all the
object’s settings).
Exp
xprr essi on ( ST
STR
RI NG) Constructs and defines the
expression. ('ATTRIBUTE----
') should be used for 
attributes for speed and
efficiency.. Other examples
efficiency
are ('PURP eq IPIPINGI') or 
('XLEN + STRING(XLEN)').
At t r i but eExpr
xpr essi on ( STRI
TRI NG) Makes the passed attribute
an expression.
AttributeExpression
('LENGTH') is the same as
Expression ('ATTRIBUTE
LENGTH').
St r i ng( ) STRING Returns th e current
expression as a string.
Evall uat
Eva uat e( DBREF) ANY Evaluates th e current
expression against the
passed object

Tabl
able
e 2: 37.
37. EXP
EXPRES
RESSIO
SION
N Objec
Objectt Me
Metho
thods
ds

2:50 12 Series
 2:50 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.22 FIL E Ob je
jec t

Methods

Nam e Res u l t Pu r p o s e
Fi l e( STRI NG) FILE Create a FILE object on a file
whose name is given in
STRING.
Acc
ccess
ess Mode( ) STRING Return ac
access mo
mode fo
for th
the
file {‘CLOSED’, ‘READ’,
‘WRITE’, ‘OVERWRITE’,
‘APPEND}.
Cl ose(
se( ) NO RESUL
RESULT
T Clo
Close
se ffile
ile if open
open..
Copy( STRI
STRI NG) FILE Copies the file whose
pathname is given in
STRING. Returns FILE
object for copied file.
Copy(
opy( FI LE) FILE Copies the file represented
by the FILE object. Returns
FILE object for copied file.
Del et eFi l e( ) NO RESUL
RESULT Del
Delete
ete the file repr
represe
esente
nted
d
by the file object if it exists.
Di r ectory( ) F IL E Returns a FILE object
corresponding to owning
directory.
DTM( ) DATE
DATETI
TIME
ME Retu
Return
rnss a DA
DATE
TETI
TIME
ME o
obj
bjec
ectt
holding the date and time
that this file was last
modified.

Entry() STRING Returns file name as string.

Exi s t s ( ) BOO
BOOLEAN
LEAN Returns BOO
BOOLEAN
indicating whether file exists
or not.
Fi l es ( ) ARRAY OF Returns an ARRAY of FILE
FILES objects corresponding to files
owned by this directory.
Ful l Name( ) STRING Returns the name including
path for this FILE object as a
STRING.
I sOpe
sOpen(
n( ) BOOL
BOOLEA
EAN
N Retu
Return
rn BO
BOOL OLEA
EANN indi
indica
cati
ting
ng
whether file is open or not.
 2:51 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Li neN
neNumber
ber ( ) REAL Return line number of line
about to be written.
Move( STRI NG) FILE Move this file to location
given in STRING. Return
FILE object for moved file.
Move(
ove( FI LE) FILE Move this file to location
represented by FILE object.
Name( ) STRING Return name of this FILE
object as STRING.
Open( STRI NG) NO RESUL
RESULT
T Ope
Opens
ns thi
thiss file in the
the mode
given by STRING
{‘READ’,’WRITE’,’OVERWRI
TE’, ‘APPEND’}
Owner ( ) STRING Returns the ID of this FILES
owner a STRING.

Pat h( ) ARRAY OF Returns an ARRAY of FILEs

FILES corresponding to the owning
directories of this FILE
object.
Pat hNam
hName( ) STRING Returns owning path as a
STRING.
ReadFi l e( ) ARRAY OF Open, read contents and
STRING close file. Data returned as
an ARRAY of STRINGs
corresponding to the lines in
the file.
Rea
eadF
dFii l e( REAL) ARRAY OF As above, but ensures that
STRING file is no longer than number 
of lines given in REAL.
ReadR
eadRecor d( ) STRING Reads a line from an open
file and returns it in a
STRING. Returns an UNSET
STRING if end of file is
detected.
Set ( ) BOO
BOOLEA
EAN
N Retur
turns a BOOLEAN
EAN
indicating whether this FILE
object has a name set or not.
Si z e
e(( ) REAL Returns size of file in bytes.
SubDi r s( ) ARRAY OF Returns an ARRAY of FILE
FILE objects corresponding to
directories owned by this

directory.
 2:52 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

 Type( ) STRING Returns a STRING indicating

whether this object
represents a ‘FILE’ or a

‘DIRECTORY’.
Wr i t eFi l e( ST
STR
RI NG, ARRAY OF NO RESUL
RESULT
T Ope
Opensns fi
file
le in mode
mode gi
given
ven in
STRI NG) string {‘WRITE’,
’OVERWRITE’, ’APPEND’},
writes STRINGs in ARRAY
and closes file.
Wr i t eRecor
eRecor d( ST
STR
RI NG) NO RESUL
RESULT
T Wri
Writes
tes STRIN
STRING G to thi
thiss FILE
which must already be open.

Table
able 2: 3
38.
8. FI
FILE
LE O
Obj
bjec
ectt Me
Meth
thod
ods
s

2.5.23 FMSYS Obje

bject

Methods

None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e
Che
heckr
ckr ef s BOOL
BOOLEA
EAN
N By defa
defaul
ult,
t, all
all ref
refer
eren
ence
cess in
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.
Cur r en
entt Documen
entt ( ) FORM This method returns the
current Document of the
application
FORM object.framework
If there as a
is no
current document then the
returned form has value
Unset .
 2:53 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
Def aul
aul t Fo
Forr mat ( ) FORMAT Query ththe ssyystem de
default
format object for use by
typed text gadgets. If none
defined then returns an
Unset local variable.
The returned format object is
a copy, so changing it will not
affect the system default
format. However the user 
can apply it to variables e.g
!text=!myVar.String(!!fmsys.d
efaultFormat())
Def aul
aul t For mLayou
Layoutt ( ) STRING query ththe ccu
urrent d
de
e fa u l t
form layout mode
Docs
oc s At MaxScr
axSc r een( BOOL EAN) NO RESUL
RESULT Sets
Sets def
defaul
aultt plac
placeme
ement
nt
position for document forms
to be towards the maximum
(rightmost) of the screen.
Useful for wide screen ad
twin screen devices.
FMI NFO(
FO( ) ARRAY OF Returns array of all FMINFO
STRINGS strings.
Hel pFi l eAl i as ( ) STR
STR IN G retur
turns the
the current help
elp file’s
alias.
I nt er r upt ( ) BOOL
BOOLEA
EAN
N Set
Set to
to TR
TRUE
UE if the
the inte
interr
rrup
uptt
gadget has been selected.
Lo
LoadFor
adFor m( STRI NG f or mname) FORM 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 doesn’t exist,
then an attempt is made to
force load its definition. If this
fails then an unset form
reference is returned.
Mai n( ) FORM Query the current main form
OKCur f nVi
nVi ew( ! vi ewt yp
ype
e i s STR
STRI NG) BOOL
BOOLEA
EAN
N Qu
Quer
erie
iess wh
whet
ethe
herr grap
graphi
hica
call
views of the specified view
type are displayed. Graphical
view types supported are:
‘G2D’; ‘G3D’; ‘ANY’ and any
view subtype is implied.
 2:54 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
OKCur f nVi ew( ! vi ewt yp
ype
e i s STR
STRI NG, BOOL
BOOLEA
EAN
N Qu
Quer
erie
iess wh
whet
ethe
herr grap
graphihica
call
subtt ype
sub ype i s STRI
STRI NG ) 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
G2D ‘NORMAL’’ (Dr
(Draft
aft);
);
‘PLOT’; ‘ISOSPOOL’
G3D: ‘NORMAL’ (Design)
Pr ogr ess( ) 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
Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refres
resh
h all
all VIE
VIEW
W gadget
gadgetss
Set Def aul t Fo
Forr mat ( ! ! f mt i s NO RESUL
RESULT
T Pro
Provid
videe a defa
default
ult glo
global
bal
FORMAT) format object to be used if no
specific format is defined for 
any typed text field. Once
only call, users cannot
change it. !!fmt must be a
global variable.
Sett Def aul
Se aul t For mLayout
Layout ( STR
STRI NG N ON E Set the default form layout
) mode to 'VARCHARS' or 
'FIXCHARS'.
Set Hel pF i l eAl i as ( al
a l i as i s NONE establishes th the ap application
s t r i ng) help file from its alias.
Set I nt er r upt ( GADGET) NO RESUL
RESULT Set
Setss the Gadge
Gadgett which wi
willll
interrupt macro or function
processing.

Set Mai n( FOR

FORM) FORM Sets the main form for an
Application.
Set Pr ogr ess( ! per cen
cent ) NO RESUL
RESULT Set the Intege
Integerr val
value
ue 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.
Spl ashscr
ashs cr een(
een( BOOLEAN
LEAN) NO RESUL
RESULT
T Rem
Remove
ovess the displa
displayy of a
splash screen after an
abnormal exit.
Tabl
able
e 2:
2: 3
39.
9. FMS
FMSYS
YS Obj
Object
ect Me
Metho
thods
ds
 2:55 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.24 FORM Ob je
jec t

Members

Nam e Ty p e Pu r p o s e
For mRev
evii si on STRING Get/ Form Revision text.
Set
Fo
Forr mTi t l e STRING Get/ Form title.
Set
I c onTi t l e STRING Get/ Icon title.
Set
I ni t c al
al l STRING Get/ Callback executed when form
Set is initialised.
Aut oca
ocal l STRING Get/ Callback executed when any
Set of the specified application
attributes have changed.
Okcal l STRING Get/ Callback executed when OK
Set button is pressed.
Cance
cell cal
cal l STRING Get/ Callback executed when
Set CANCEL button is pressed.
Keyboar
eyboar dFocus
dFocus GADGET Gadget to have initial
Get/Set keyboard focus on display of 
the form. One of TEXTFIELD,
TEXTPANE, BUTTON,
TOGGLE or ALPHA VIEW.
Aut oScr
oScr ol l BOOLEAN If AutoScroll is selected the
Get/Set 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.
 2:56 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e
Qui t cal
cal l 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
QUI TCA
TCALLL  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
QUI TCA
TCALLL  callback is
executed, if present, and then
the form and its children are
hidden unless the PML
callback returns
When the form nestan error.
is hidden
the CANCELCALL  callback for 
each form of the nest is
executed (in reverse display
order).
Maxi mi sed BOOLEAN Get/set form’s maximised
Get/Set status (on screen).
Acti ve BOOLEAN Gives form's active/inactive
Get Only status.
Popup MENU Get/set form’s current popup
Get/Set menu.
Hel pCont
ont ext I D STRING 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.
 2:57 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e
Ki l l i ngc al l STRING Notify the form that it is being
destroyed and allow the
Get/Set
assigned callback method to
destroy any associated
resources, e.g. global PML
objects which would
otherwise not be destroyed
(see Killing callback).
Fi r st Showncal
cal l STRING Allow the user to carry out
any form actions which can
Get/Set
only be completed when the
form is actually displayed for 
the first time (see FirstShown
callback).
Tabl
able
e 2:
2: 4
40.
0. FOR
FORM
M Obj
Object
ect Mem
Member
bers
s

Methods

Nam e Res u l t Pu r p o s e

Name( ) STRING Get name.

Ful l Name( ) STRING G e t th e fu l l form n am e
(Including !!).
NewM
ewMen
enu(
u( ST
STRI
RI NG men
enuna
unam
me) MENU Adds a new named menu to
the form.
NewM
ewMenu( STRI NG menunam
enun ame, STRI NG ME N U Adds a new named and
t ype
ype) 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’.
Set
Set Act i ve( BOOLEAN
LEAN) NO RESULT Set Act i ve(
ve( FALS E)   greys-
FALSE
out all gadgets on the form,
but doesn’t set their Active
status, so that
Set Act i ve TRUE)  restores
ve(( TRU
the form to the precise state
it was in before greying out,
i.e. any inactive gadgets will
still be inactive.
 2:58 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Set Gadget
adget sAct i ve( BOOLEAN
LEAN) NO RESULT Set Gadadge
gett sAct
sAct i ve
ve(( FALS
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
Se
Sett Gadge TRUE)
adgett sAct i ve( TRU
greys-in all gadgets and sets
their Active status to ‘active’.
Set Popup( MENU
ENU) NO RESUL
RESULT
T Sp
Speci
ecifie
fiess the pop-up to be
displayed when the right-
hand mouse button is
released over the form
background.
RemoveP
ov ePop
opup(
up( MENU)
ENU) NO RESU
RESUL
LT Re
Remov
moveses a pop
pop-u
-up
p
associated with a form.
Get Pi ckedPop
ckedPopup
up(( ) MENU Returns th e l as t pi c k ed
popup menu for the form.
Sho
how
w( ' FRE
FREE' ) NO RESUL
RESULT
T Sho
Showw the form
form on tthe
he scree
screen
n
as a FREE form.
Show
Show( ' AT' , REAL
EAL X,
X, REAL
EAL Y) NO RESUL
RESULT
T Show tthe
he form
form as a FREE
form with the origin at the
X,Y relative screen position.
Show
Show( ' CEN'
EN' , REAL
EAL X,
X, REAL
EAL Y) NO RESUL
RESULT
T Show tthe
he form
form as a FREE
form with its centre at the X,Y
relative screen position.
Shown( ) BOO
BOOLEAN
LEAN Get 's
'show
hown' status
Hi de( ) NO RESUL
RESULT
T Hid
Hides
es the form (re
(remov
moves
es it
from the screen)

Owner ( ) FORM Returnor

form, s unset
the fvariable
orm's pifarthe
ent
form is free-standing
Set Opaci t y( REAL
EAL PERC
PERCENT
ENT ) NONE Set th e 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.
Subt
ubt yp
ype(
e( ) STRING Gets the form's subtype, one
of 'DIALOG',
'BLOCKINGDIALOG',
'MAIN', 'DOCUMENT'
 2:59 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Se
Sett Undoa
ndoabl
bl e( ) STRING,
ANY
Undoa
ndoabl
bl e( ) STRING

Tabl
able
e 2:
2: 4
41.
1. FOR
FORM
M Obj
Object
ect Met
Method
hods
s

ve(( ) and Set Gadget sAct

Note: Set Act i ve ve( ) can be used in combination with each
sAct i ve(
other and with the Ac ti ve  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 form’s 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
ar e by default drawn with th
their
eir Y-coordinate
Y-coordinate adjusted so that they would
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.
 2:60 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

. - - - - - - - - - - - - - - - <-
<- - - - - - - - - - - - - - - - - - - - - - - - - - - .
/ |
>- - SETUP FORM f n
naame - - +- - MAI N - - - - - + +-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - DOCUMENT - + +-- FL OAT - - - - - - - - - - - - - - - - - - - - - - - |
| ‘-------------------------------|
+- - DI AL OG - - - +- +- DOCKi ng - + +-- - - - - - - - - - - - - - - - - - - |
| | - Lef t - - - . |
| | | - Ri ght - - | |
| | | - Top - - - - | |
| | ‘ - Bot t om - ‘ - - - - - - - - |
| | - RESI z eabl e - - - - - - - - - - - - - - - - - - |
| ‘-------------------------------|
+- - BLOCKi ngdi al og - +- RESI z e eaabl e - - - - - - - - - - - - |
| ‘-------------------------|
+- - AT <xypos > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - SI ZEZE val val - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - NOQUI T - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - NOAL I GN - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - CORE - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
| . - - - <- - - - - - .
|/ |
+- - <f or m> - - * fo
form
rm co
contntenentsts
‘ —EXI T - - >

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

CANCELCALL
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.

>- - CANCEL c al l t ex
ext - - >

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

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.
 2:61 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

>- - CURSor t ype - - +- - POI NTER - - - - .

+- - NOCURSOR - - - |
+- - PI CK - - - - - - - |
+- - PI CKPL US - - - |
‘ - - CROSSHAI R - - ‘ - - >

Note: There are other cursor types that are for AVEVA’s
AVEVA’s use only.

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

>- - HAl i gn - - +- - L ef t - - - .
‘ - - Ri gh
ght - - ‘ - - >

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

>- - HDi s t a
annc e val ue - - >

ICONTITLE

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

>- - I CONTI t l e t ex
ext - - >

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.

>- - I NI
NI Tc
T c al l t ex
ext - - >

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 a
ann ancestor.

>- - OKc al l t ex
ext - - >

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

 2:62 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

PATH
Defines the direction in which a sequence of new gadgets is to be added to a form.
fo rm. The path
setting remains until you give another PATH command. Used with HALIGN, HDISTANCE,
VALIGN, VDISTANCE.

>- - PATH - - +-
+- - Up - - - - - - .
+- - Down - - - - |
+- - L ef t - - - - |
‘ - - Ri gh
ght - - - ‘ - - >

Default: Path Right.

TITLE
Defines the form title.

>- - TI TL e t ex
ext - - >
VALIGN
Use in conjunction with PATH and VDISTANCE. Defines how a newly added gadget should
be aligned vertically with the preceding gadget.

>- - VAl i gn - - +- - Top - - - - - .

‘ - - Bot t om
om - - ‘ - - >

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

>- - VDi s t a
annc e val ue - - >

FirstShown and Killing Events

The following actions determine the life of a form:

Defi
Define
ne the
the for
form,
m, its
its gadg
gadget
ets,
s, meth
method
odss and
and layo
layout
ut are
are sspe
peci
cifi
fied
ed (usu
(usual
ally
ly in a
'.pmlfrm' file)
Load
Load the
the form
form defi
defini
niti
tion
on is re
read
ad by PM
PML
L and
and the
the for
form'
m'ss co
constr
nstruc
ucto
torr m
met
etho
hod
d is
run
Sh
Show
ow the
the form
form's
's IN
INIT
ITia
ialilisa
sati
tion
on even
eventt is rais
raised
ed,, and
and the
the disp
displa
layy proc
proces
esss is begu
begun
n
Ac
Acti
tiva
vate
te the
the for
form
m and
and its
its con
conte
tent
ntss iiss cre
creat
ated
ed by the
the w
win
indo
dow
w m
mana
anage
geme
ment
nt sy
syste
stem
m
and is activated (actually displayed) and the FIRSTSHOWN event is

raised
 2:63 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Hide the form is hidden and its OK or CANCEL event is raised

Kill the form
form''s KILL
ILLING event is raised and then the form is destroy
royed. It is no
longer known to PML

Notes:
1. Load, Activate
Activate and Kill
Kill only happen
happen once
once in the life of a form
2. Show and Hide
Hide may
may happen
happen repeate
repeatedly
dly
3. The form's
form's Const
Construc
ructor
tor is
is run once
once only
only
4. The First
FirstShow
Shown n event
event only
only happen
happenss once
once
5. INIT
INIT is rai
raised
sed for eve
every
ry Show
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
corre ct gadget background colour setting the first time
the form is displayed. This can be resolved by setting the required colour in the
FIRSTSHOWN callback.

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 resources, e.g. global PML objects which would
otherwise not be destroyed. This may be necessary because PML P ML global objects will survive
an application module switch, but may not be valid in the new module.
Notes:
1. The
The call
callba
back
ck met
metho
hodd 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:64 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2. Form callbacks
callbacks designed
designed for other
other Form events
events (e.g. CANCEL,
CANCEL, INIT) are
are rarely suitable
suitable
as killing callbacks.
3. Restrict
Restrict form
form and gadget operations
operations to querying.
querying.

2.5.25 FORMAT O
Obj
bjeect
The format object is used to format the output of real objects and especially real physical
objects such as distances. It controls precision, units, conversions and unit qualifiers.
Format objects are also used to control conversions of strings to reals by providing guidance
on dimensions and units. This occurs for text boxes in the user interface, and also for real to
string and string to real conversion methods.

Members

Nam e Ty p e Pu r p o s e

CompSepar
pSepar at or STRI
STRING
NG | | Sepa
Separa
rato
torr used
used for
for mu
mult
lti-
i-
component data types such as
POSITIONS (Default SPACE).
Denomi nat or REAL 32 Largest denominator for Imperial
fractions
 (Default 32)
Di men
ensi
si on STRING Number is un-dimensioned
‘NONE’ (Default)
L Number is a LENGTH
LENGTH
L2 Number is an AREA
L3 Number is a VOLUME
The TYPE string can be any
existing values (L L2 L3 NONE) or 
any standard dimension (i.e.
Measure), or any standard unit

(which
dimension)indirectly
either in defines
full namea
(e.g. metre), or description or 
shortname (unitqualifier), or 
compound unit qualifier (e.g. lb/
m4) form. No validation is actually
performed until the format is used.
DP REAL 2 Number of decimal places for 
decimal fractions (Default 2)
ENU BOOLEAN Use ENU format when outputting
TRUE POSITIONS (Default)
FALSE
Use XYZ format when outputting
POSITIONS
 2:65 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e

Fr acti on BOOLEAN Fractional part output as decimal

FALSE (Default)
TRUE
Fractional part output as fraction
FtLabe
FtLabel STRI
STRING
NG |’|
|’| Labe
Labell u
use
sedd for
for feet
feet
e.g. ' or FT or fftt or feet
(Default ‘ )
I nchS
chSeparat
eparat or STRI
STRING
NG |.|
|.| Sepa
Separarato
torr betw
betwee
een
n inch
inches
es and
fractions
(Default . )
Lab
Label STRING General distance label
|mm|
e.g. mm or m or " or IN
(Default is no label)
The label (and similarly the foot
label and the inch separator can
be any string (within normal and
reasonable unit limitations!). They
are primarily supplied to allow
physical values to be formatted in
any reasonable way on reports, in
files and in text fields etc.
However it is often necessary for 
such values to be re-interpreted
by the system (especially as they
are validated after entry in the text
field. In these case, if normal
value and unit parsing fails to
interpret the values then the string
is reinterpreted with the Label,
ftlabel and inch separators
substituted by normal standard
unit qualifiers and separators
enabling the values and units to
be successfully interpreted when
correct and consistent with the
format object.
If the label is set to UNITS then
the standard unit qualifier will be
output by the system, consistent
with the dimension of the format.
PadFr act i ons BOOLEAN Do not pad Fractions (Default)
FALSE Pad Fractions with trailing spaces
TRUE
 2:66 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e

 Tr ai l Zer os BOOL

BOOLEA
EAN
N Trail
railin
ing
g ze
zero
ross are
are incl
includ
uded
ed u
up
p th
the
e
required number of decimal
places (as set by the DP member)

ifTRUE.
TrailZeros is unset, or if it is
If TrailZeros is FALSE trailing
zeros will be removed up to and
including a trailing decimal point
Uni t s STRING Output number in millimetres
MM (Default)
M Output number in metres.
FINCH Output number in feet and inches
INCH Output number in inches
The TYPE string can be any
standard form of unit, or a
compound unit. If dimension is
unset the isunit
the unit oftenthe
when defines what
format is
used. No validation is performed
on this string until the format is
used when the values will be
converted to units specified.
Or i gi nExp BLOCK With respect to World (Default)
||
With respect to World
|/*|
|CE| With respect to Current Element
Zer os BOOLEAN Leading zeroes are displayed for 
Imperial units (Default).
TRUE
FALSE Leading zeroes are not displayed
for Imperial units

Tabl
able
e 2: 42.
42. FOR
FORMA
MAT
T Ob
Objec
jectt Me
Memb
mbers
ers
 2:67 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.26 FRAM
AME
E Gadg
dgeet

Members

Nam e Ty p e Pu r p o s e

 Tag STRING Text to appear as title on the

Get/Set frame.
Val REAL Get/ Selected radio button index
Set as integer.
RGr oupCount REAL Get Count of radio buttons
only (RTOGGLES) within the
FRAME’s radio group.
Returns zero if the FRAME is
not a radio group.
Cal l back STRING Radio group select callback
Get/Set string.

Expanded BOOLEAN
Get/Set
FoldUpPanel’s
status
expanded

Tabl
able
e 2: 43. FRAME
FRAME Gad
Gadget
get Me
Membe
mbers
rs

Methods

Nam e Res u l t Pu r p o s e

Rt oggl e( ! i ndex i s RE
REAL ) GADGET Returns th
the R
RTTOGGLE
gadget with index !index .
Backgr ound(
ound( ) STRING G et Ba
Background Co
Colour  
Name.

Some gadgets
support this do in not
property 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..

Tabl
able
e 2:
2: 4
44.
4. FRA
FRAME
ME Gad
Gadget
get Me
Metho
thods
ds

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.
 2:68 12 Series

 Soft ware Customi sation Reference

Reference Manual
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
NORMAL frame frame can
can contain
contain any type
type of gadget, includ
including
ing oother
ther fframes.
rames. It also
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
TABSET fframerame can
can contain
contain only tabbed page FRAMEs; you cannot
cannot nest tthem
hem and
and
they are not named.
• A TOOLBAR
TOOLBAR frame frame can
can contain
contain only
only a subset
subset of gadge
gadgett type
types:
s: BUTTON
BUTTON,, TOGGLE,
TOGGLE,
OPTION, and TEXT. It must have a name and can appear appea r only on main forms.

. - - - <- - - - - - - .
/ |
>- - F RA
RAME gname - +- TOOL B
BA
AR - +- t a gt gt ext - +- <t o o oll bar > - * t o o
oll bar c o
on
nt ent s
| ‘ —- EXI T - - >
| . - - - <- - - - - - - - .
| / |
+- TABSET - +- - <f gpos > - - - |
| +- - <f ganc h> - - |
| +- - <f gdoc k> - - |
| +- - <vs hap> - - - *
| | . - - - <- - - - - - - - .
| |/ |
| +- - <t abs et > - - | tabb
ta bbeded fr fram
ame
e cont
conten
ents
ts
| +- - NL - - - - - - - - *
| ‘-- E EX
XI T - - >
+- PANEL - - +- - - - - - - - - - .
| ‘ - - I NDENT- - |
+- FOL DUPpanel - - - - - - - | . - - - < <-- - - - - - - - .
|/ |
+- - t ag
agt exext - - - |
+- - <f gpos > - - - |
+- - <f ganc h h>> --|
+- - <f gdoc k> - - |
+- - <vs ha hap> - - - *
| . - - - <- - - - - - - - .
|/ |
+- - <f or mc > - - - * fo form
rm co
cont
nten
ents
ts

‘ - - EXI T - - >

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.

Settin g Up a TOOLBAR
TOOLBAR Frame
The toolbar frame allows you to define formal toolbars that contain all the gadgets in the
frame’s scope. You can define a toolbar frame only for a main form, and a main form can
contain only toolbar frames.
 2:69 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

The graph below defines the allowable content of a toolbar frame:

>- - t oo
ool bar - +-
+- - <f bu
but n>
n> - - - - . Bu
Butt
tton
on ga
gadg
dget
et
+- - <f t ext > - - - - | te
text
xt ga
gadg
dget
et
+- - <f t ogl > - - - - | to
togg
ggle
le ga
gadg
dget
et
+- - <f opt i o> - - - | op
opti
tion
on ga
gadg
dget
et
+- - <f va
v ar > - - - - - | fo
form
rm va
vari
riab
able
le de
defi
fini
niti
tion
on
+- - <pml > - - - - - - | ge
gene
nera
ral
l PM
PML
L
+- - <nxas gngn> - - - | PM
PML
L ex
expr
pres
essi
sion
ons
s
‘ -- <var sseet > - - - ‘ - - - - > var
ari
iab
abl
le se
sett
ttin
ing
g VA
VARº
Rº

Settin g Up a TABSET
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:

>- - t ab
a bs e
ett >- +- - <f f r a
amme> - - - . fr
fram
ame
e ga
gadg
dget
et
+- - <f va
v ar > - - - - - | fo
form
rm va
vari
riab
able
le de
defi
fini
niti
tion
on
+- - <pml > - - - - - - | ge
gene
nera
ral
l PM
PML
L
+- - <nxas gngn> - - - | PM
PML
L ex
expr
pres
essi
sion
ons
s
‘ - - <var s
seet > - - - ‘ - - - - > var
ari
iab
abl
le se
sett
ttin
ing
g VA
VARº
Rº

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
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
choosing frame
frame type Panel,
Panel, the contents
contents is defined
defined in tthe
he usual mmanner
anner..
2. Tagtext can be specifie
specified,
d, but itit is never
never displayed.
displayed.
3. The panel has
has no visible enclosin
enclosing g box, unless
unless the INDENT opt option
ion is specified
specified when it
will have a 3D indented appearance.
4. Panel supports
supports all the
the attributes
attributes of a Normal FrameFrame includ
including
ing the noti
notion
on of a radio
button group.

Setting up i n 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
choosing frame
frame type FoldUpPanel
FoldUpPanel,, the contents
contents is def
defined
ined in the usual
usual manner
manner..
The panel can contain the usual PML gadgets except another FoldUpPanel.
2. Separate
Separate events
events are raised
raised after expandi
expanding
ng or collapsing
collapsing tthe
he panel
panel..
 2:70 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

3. The defa
default
ult stat
state
e is ''exp
expande
anded'.
d'.
4. When the panel
panel expands
expands or collapses,
collapses, any gadgets
gadgets which
which lie below
below the panel
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
AutoScroll attribute
attribute is selected,
selected, then
then a scroll bar wil
willl automatically
automatically appear 
appear 
whenever
still gadgets have been moved off the bottom of the form, so that all of the form
accessible. f orm is
6. The FoldUpPanel
FoldUpPanel supports
supports all the
the attributes
attributes of a Normal Frame
Frame including
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 fold-
down 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 fold-
up panel can still be handled by simple (non-Open) callbacks.

To manage
callback FoldUpPanels
so that which arethealso
you can differentiate radioSELECT,
panel's groups, HIDDEN
then youand
must supplyevents.
SHOWN an open
 2:71 12 Series

 Soft ware Customis ation Reference

Reference Manual
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
!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 Graph
raphic
ica
al Select
lectio
ion
n
The Selection object allows the PML user to interact with the graphical selections set. It is
not reliant on PDMS being in graphical mode - the selection set can be created and
manipulated in TTY mode, and thus can be used in regression tests.
Only significant elements can be in selection sets. The definition of what is significant varies
between graphical interaction modes:
• in Desig
Designn navi
navigat
gate
e mode,
mode, all
all databas
databasee elemen
elements
ts are
are signifi
significan
cantt
• in Model
Model Editor
Editor mode,
mode, then only those
those database
database elements
elements defined
defined in th
the
e Model Editor 
definition are significant, and some non-database elements.

• In Draft
Draft mode,
mode, only
only drawli
drawlist
st eleme
elements
nts are
are si
signi
gnific
ficant
ant..
Most methods look for the 'highest significant element' - they climb up the ownership tree
looking for significant elements, until the value of 'scope' is reached - the nearest significant
element below this ceiling is used.

Set-up
Set-up Methods
Methods

Nam e Pu r p o s e

. s el
el ec t i on( ) Creates an empty selection object .

Methods
Methods that Modify Object
Note that this object is manipulating the graphical selection set itself. As elements are added
or removed, they will be highlighted in the graphics view at the same time (if in graphics
mode).

Nam e Res u l t Pu r p o s e

. sc
scop
ope(
e( DBREF) BOOLEAN D e fi n e s th e s c o p e o f th e
selection, i.e. defines the top
element that the selected
elements must exist beneath.
Default is WORLD.
. add(
add( DBREF) DBREF A d d s th e h i g h e s t s i g n i fi c a n t
parent of passed element to
selection
 2:72 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

. addC
addConnect
onnect ed( DBREF) ARRAY Simulates "Select connected" for  
piping components:
Adds the given component and
the connected network relative to

the component
. addB
addBr anchLeg( DBREF) ARRAY Simulates "Select leg" for piping
components:
Adds the given component and
adjacent components within the
branch which are in the same leg
as the passed component
. addA
addAtt t ached(
ached( DBREF) ARRAY Simulates "S
"Select at
attached" fo
for  
sections:
Adds the given section and all
sections attached into the
selection
. add
addOf f spr i ng(
ng( DBREF) ARRAY A d d s t h e h i g h e s t s i g n i fi c a n t s u b -
elements
selection. of This
givenaction
element
as toif 
DBREF were ancestor for select
. r emove( DBREF) No Result R em ov e hi ghes t s i g n i fi c a n t
parent of passed element from
selection
. c l ear ( ) No Result E m p ty th e s e l e c ti o n
. get Cur r ent ( ) No Result Set th
the co
contents ooff th
the sse
e l e c ti o n
to the contents of the current
graphical selection set
. get Al
Al l ( ) No Result Set tth
he sse
election sse
et tto
o co
contain
the entire drawlist
. set
set Cur r ent ( ) No Result Set the current graphical
selection set to be the same as
the contents of the selection set
 2:73 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Query Methods

Nam e Res u l t Pu r p o s e

. i s Val i d( ) BOOLEAN Is the selection valid. (This is

a standard method, and
should not normally need to
be called)
. sel ect ed(
ed( DBREF) DBREF Returns highest significant
parent of given element, i.e.
the element which will be
included in the selection
. i sSe
sSel ect abl e( DBREF) BOOLEAN Returns true if the given
element is in itself selectable
within the scope of the
selection
. i sModi f i abl e( DBREF) BOOLEAN Returns true if the highest
significant parent of the given
element is modifiable

. i nSel ect i on( DBREF) BOOLEAN Returns true if the given

element exists in the selection
  . ancest
ancest or s( DBREF) ARRAY of  Returns list of permissible
DBREFs ancestors for given element,
within the current scope
  . get Sel ecti on( ) ARRAY of  Returns all elements in the
DBREFs selection

Tabl
able
e 2: 45. Gra
Graphi
phical
cal Se
Selec
lectio
tion
n Obje
Object
ct Me
Metho
thods
ds

2.5.28 IDL i s t
The IDList object provides features for the accessing and manipulation of elements in an
IDLIST database element.
Elements in the IDlist object must be significant elements, in the following sense. The
database element reference supplied to the constructor is examined to see if it either:
• Owns a valid
valid design
design drawlist
drawlist element;
element; in which
which case
case the
the supp
supplied
lied elemen
elementt is a
added
dded to
the idlist object.
• Is owned
owned by a drawlist
drawlist element
element,, in which case the signific
significant
ant ow
owner
ner is added to the
idlist.
Elements below the level of the design drawlist element cannot be manipulated via this
object.
 2:74 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Set-up
Set-up Methods
Methods

Nam e Pu r p o s e

.idlist(DBREF) Creates an PML IDlist object from the given DBREF of an

IDLIST. Searches up the ownership hierarchy until a
significant element is found, and adds this to the Idlist.

Before adding an ADDE, the object will check whether there is an 'active' ADDE in the list -
this is an ADDE for the identical element, without an intervening REME for the same object.
If so, it will not add it again. Similarly for REMEs.
When removing ADDEs or REMEs, the system will start from the bottom of the list and work
backwards removing the requested entry.

 Ac ces s Met ho ds

Nam e Res u l t Pu r p o s e

. add ( DBREF) No Resu

Result
lt Adds
Adds a ADADDE to the
the ID
IDLIST
LIST.. IfIf the
there
re is
already an ADDE of either the same
element or one of its ancestors (without
an intervening REME) then nothing will
be done. If there is an intervening
identical REME, then the REME is
removed.
. add
add ( SELEC
SELECTI
TI ON) No Resu
Result
lt Adds
Adds ADDE
ADDEss for
for the
the e
ent
ntir
ire
e ssel
elec
ecti
tion
on se
sett
to the IDList at this point, in the same
way as for individual DBREFs.
. r emove ( DBREF) No Resu
Result
lt If ther
there
eeexi
xist
stss an
an ADD
ADDEE for
for this
this elem
elemen
entt
in the list, then it is removed. If there
exists an ADDE for an ancestor for this
element, then a REME is inserted.
. r emove ( SELEC
SELECTI
TI ON) No Result Removes al alll ADD
ADDEs de deffined in th
the
e
selection set, using the same rules as in
removing a single element.
. cop
copy( I DLI ST ot
ot her ) BOOL
BOOLEA
EAN
N Clea
Clears
rs the
the idl
idlis
ist,
t, and
and a
add
ddss a
allll the
the e
ent
ntri
ries
es
from idlist other. Returns TRUE if copy
successful.
. c l ear ( ) No Re
Result Remove al
all el
elements ffrrom iid
dl i s t

. quer y( ) ARRAY of  Returns an array of strings of the form:

STRINGS
ADDE element
or
REME element
itemising all the elements in the idlist.

Tabl
able
e 2: 46. IDl
IDlist
ist Object
Object Met
Method
hods
s
 2:75 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.29 L IN
INE Gad g
geet

Members
Members and Methods
Methods
The LINE gadget supports
supp orts the standard default gadget members
me mbers 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.
. - - - - - - - <-
<- - - - - - - - - - - - - - - .
/ |
>- - - L I NE gname - +- t a aggt eexxt - - - - - - - - - - - - - - - |
+- <f g gppos > - - - - - - - - - - - - - - - |
+- <f ga ganc h> - - - - - - - - - - - - - - |
+- <f gd gdoc k> - - - - - - - - - - - - - - *
|
+- VERTi c al - - - .
| |
' - HORI Zont al
al - ' - <vs hap> - - >

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 'T
'Toggle
oggle 1' at x 2
line .horiz 'H-Line' Horiz wid.f3 hei.t1
toggle .t2 'T
'Toggle
oggle 2'

line .vert at xmin.f3 ymin.f3+0.5 Vert wid 2 hei.f3

 2:76 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

exit

Notes:
1. The tag text
text is never
never displ
displaye
ayed.d.
2. Line
Line does
does not
not apply
apply to
to too
toolba
lbars.
rs.
3. The graph <vshap>
<vshap> allows
allows the line's
line's width
width and height
height to be set eit
either
her spec
specifical
ifically
ly or in
terms of other gadgets on the form.
4. Setting the
the height for a Horizont
Horizontalal separator
separator or the width
width for a Vertical
Vertical sep
separator
arator causes
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 and Anchor
Anchor attributes
attributes allow
allow the Lines
Lines to be dyna
dynamic
mic and respond
respond to
interactive changes in form size.
6. The gadget
gadget is not interactiv
interactivee and has no associated
associated value.

2.5.30 L IN
INE Ob je
jec t
See also the POINTVECTOR object.

Members

Nam e Ty p e Pu r p o s e

St ar t Pos i t i on POSITION Start position of line.

Get/Set
EndPosi t i on POSITION End position of line.
Get/Set

Tabl
able
e 2:
2: 4
47.
7. LIN
LINE
E Obje
Object
ct Mem
Member
bers
s

Definition Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Li ne( POSI TI ON f i r st , POSI TI ON L IN E Creates a LINE between the

second) given positions, first   and
second .

St r i ng( ) STRING Returns the l i ne as a

STRING.
Di r ec t i on( ) DIRE
DIRECT
CTIO
ION
N Retu
Returnrnss a D
DIR
IREC
ECTIO
TION
N
representing the direction of 
the line.
Di r ect i on
on(( DI RECTI
ECTI ON way) L IN E Creates a new line with the
same start position and
length but in the direction
given by way .

Tabl
able
e 2: 48.
48. LIN
LINE
E Objec
Objectt Def
Defini
initio
tion
n Met
Method
hods
s
 2:77 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

EndPosition
Direction(DIRECTION)

StartPosition

Figure
Figure 2:20.
2:20. : Ba
Basic
sic LIN
LINE
E Defin
Definiti
ition
on

LINE Object
Object Methods that Return BOOLEANs
BOOLEANs
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

On( POSI
POSI TI ON wher e) BOO
BOOLEA
EAN
N Retur
turns TRUE if where  lies
on the unbounded line.
On( POSI
POSI TI ON wher e, BOOLEAN BOO
BOOLEA
EAN
N Retur
turns TRUE if where  lies
bounded) on the line, bounded
indicates if the point is also
checked to be on the
bounded line segment.
OnP
nPrr oj ect ed(
ed( POSI TI ON whe
herr e) BOO
BOOLEA
EAN
N Returns
rns TRUE if where,
when projected onto the line,
lies within the bounded line.

Figure 2:21. LINE Objec

Objectt Me
Methods
thods that Retur
Return
n BO
BOOLEA
OLEANs
Ns

  OnProjected(POSITION)

On (POSITION)

Figure
Figure 2:22
2:22.. BOOL
BOOLEANs
EANs Retur
Returned
ned b
by
y LIN
LINE
E Obj
Object
ect Metho
Methods
ds
 2:78 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

LINE Object Method s th at Return POSITIONs

POSITIONs
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

I nt er secti
secti on( LI NE ot
ot her ) POSI
POSITI
TION
ON Retu
Return
of rnsspassed
the the
the iint
nter
erse
sect
ctio
LINE ion
n po
onpoin
intt
the
line definition
I nt er secti
secti on( POI NT po
poi nt , POSI
POSITI
TION
ON Retu
Return
rnss the
the iint
nter
erse
sect
ctio
ion
n po
poin
intt
VECTO
ECTOR R vect or ) of the passed
POINTVECTOR on the line
definition.
I nt er se
sect
ct i on(
on( PLAN
LANE pl
pl ane) L IN E Returns the intersection line
of plane  on the line
definition.
I nt er se
sect
ct i ons(
ons( ARC ar c) ARRAY OF Returns the intersection
POSITIONS points of arc   on the line
definition.
Nea
earr ( POSI TI ON posi t i on)
on) POSI
POSITI
TION
ON Retu
Return
rnss the
the near
neares
estt p
pos
osit
itio
ion
n
on the line definition to
position .

Pr opor t i on( REAL p

prr opor t i on) POSI
POSITI
TION
ON Retu
Return
rnss tthe
he posi
positi
tion
on at
proportion   along the
“bounded” line from the
St ar t Pos i t i on.
Values > 1 will give positions
off the end of the line.
Values < 0 will give positions
off the start of the line.

Table 2:
2: 49. LINE Objec
Objectt Met
Methods
hods that Retur
Return
n POS
POSITION
ITIONs
s

Proportion(REAL)
Intersection(LINE)

Near(POSITION)

Figure
Figure 2:23. POSI
POSITION
TIONs
s Returned
Returned b
by
y LIN
LINE
E Obj
Object
ect M
Method
ethods
s
 2:79 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

LINE Object
Object Methods that Return REALs
REALs
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Len
Lengt h( ) REAL Returns the length of the line.
Di st ance(
ce( LI NE ot
ot her ) REAL Returns the m i ni m um
distance between the line
definition and other .
Di st ance(
ce( POSI TI ON p
posi
osi t i on) REAL Returns the m i ni m um
distance between the line
definition and position .

Figure
Figure 2:24. Table -48
-48:: LINE O
Object
bject Metho
Methods
ds tha
thatt Retur
Return
n REAL
REALs
s

  Length()

Distance(POSITION)

Distance(LINE)

Figure
Figure 2:25
2:25.. REAL
REALs
s Re
Returne
turned
d by LINE Objec
Objectt Me
Methods
thods

LINE Object:
Object: Miscellaneous Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e
Pl ane( ) PLANE Returns a plane object, using
the StartPosition   and
Direction of line object
Poi nt vector( ) POINTVEC Returns a POINTVECTOR
TOR object, using the
StartPosition   and Direction
of line object

Figure
Figure 2:
2:26.
26. LINE Objec
Objectt M
Misce
iscellaneo
llaneous
us Metho
Methods
ds
 2:80 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

LINE Object Methods that Return LINEs (a)

None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Set Len
Lengt hSt ar t ( REAL l eng
engt h) L IN E Returns a new l i ne,
maintaining the original
StartPosition   and direction,
with an EndPosition  to
match length .
Se
Sett Lengt
Lengt hEnd
hEnd(( REAL
EAL l engt
engt h) L IN E Returns a new l i ne,
maintaining the original
EndPosition   and direction,
with a StartPosition   to
match length .
 Towar ds( POSI TI ON posi t i on) L IN E Returns a new line object
with the same StartPosition
and the same relative
EndPosition   (Length) of the

original
is from line, but the
the start direction
position to
position.

Fr om( POSI TI ON po
posi
si t i on)
on) L IN E Returns a line, where the
StartPosition   is set
position , maintaining the
original EndPosition.
 To( POSI
POSI TI ON posi t i on) L IN E Returns a line, where the
EndPosition   is set to
position , maintaining the
original StartPosition  
Ext en
end
dSt ar t ( REAL di st ance
ance)) L IN E Returns a new LINE, where
the StartPosition   has been
extended in the opposite
direction of line by distance.
Ex
Extt endE
endEnd
nd(( REAL
EAL di st ance)
ance) L IN E Returns a new LINE, where
the EndPosition  has been
extended in the direction of 
the line by distance.

Table 2:
2: 50. LINE Objec
Objectt Met
Methods
hods that Retur
Return
n LIN
LINEs
Es (a)
(a)
 2:81 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

ExtendEnd(REAL)

To(POSITION)

SetLengthStart(REAL)
ExtendStart(REAL)

Towards(POSITION)

From(POSITION) SetLengthEnd(REAL)

Figure
Figure 2:27
2:27.. LINEs
LINEs Returne
Returned
d by LINE Objec
Objectt Me
Methods
thods (a)

LINE Object
Object Methods that Return Li nes (b)

Nam e Res u l t Pu r p o s e

Ext endS
endStt ar t ( PLAN
PLANE pl
pl ane)
ane) L IN E Returns a new LINE, where
the StartPosition   has been
extended to plane.
Ext en
endE
dEnd
nd(( PLAN
PLANE pl an
ane)
e) L IN E Returns a new LINE, where
the EndPosition  has been
extended to plane.
Rever
ever seSense(
seSense( ) L IN E Returns a line, where the
StartPosition   and
EndPosition
transposed.   have been

Pr oj ect ed(
ed( PLAN
PLANE pl ane)
ane) L IN E Returns a LINE definition
normalised onto plane. See
picture.
Par al l el ( POSI TI ON posi t i on) L IN E Returns a parallel to the line
definition of the line object,
through position . All other 
members are copied. See
picture.
Of f set ( DI RECTI ON di r ect i on,
on, REAL L IN E Returns a parallel line to the
of f s et
et ) LINE object, offset by offset
from the original in the given
direction. See picture.

Figure
Figure 2:28
2:28.. LINE Objec
Objectt Met
Methods
hods that Retur
Return
n LIN
LINEs
Es (b)
(b)
 2:82 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

  Parallel(POSITION)

Offset(DIRECTION, REAL)

Projected(PLANE)

Figure
Figure 2:29
2:29.. LINEs
LINEs Returne
Returned
d by LINE Objec
Objectt Me
Methods
thods (b)

LINE Object
Object Methods that Return Li nes (c)

Nam e Res u l t Pu r p o s e

Over
ver l ap(
ap( LI NE ot her) L IN E Returns the overlapping line
of two parallel   lines. All
positions are return projected
onto the original object. See
picture.
Uni on(
on( LI NE ot her) L IN E Returns the union of LINE
and other . The two are
parallel   lines, all positions
are return projected onto the
original object. See picture.
Table 2:
2: 51. LINE Objec
Objectt Met
Methods
hods that Retur
Return
n LIN
LINEs
Es (c)
(c)

Union(Line)

Overlap(Line)

Figure
Figure 2:30
2:30.. LINEs
LINEs Returne
Returned
d by LINE Objec
Objectt Me
Methods
thods (c)
 2:83 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

LINEARGR
LINEARGRID
ID O
Object
bject Const ructi on A ids

Members

Nam e Ty p e Pu r p o s e

Pos i t i on POSITION Origin of the grid

Get/Set
Or i ent at i on ORIENTATI Orientation of the grid
ON Get/Set
XSpaci
Spaci ng REAL Spacing in the X direction
Get/Set
 YSpaci
 YSpaci ng REAL Spacing in the Y direction
Get/Set

Tabl
able
e 2: 52.
52. LIN
LINEAR
EARGR
GRID
ID O
Objec
bjectt Me
Membe
mbers
rs

Definition Methods
These methods do not modify the original object.

Nam e Res u l t Pu r p o s e

Li near gr i d( POSI TI ON, LINEARGRI Creates a grid with the given

ORI ENTA
ENTATI
TI ON, REAL,
EAL, REAL)
EAL) D POSITION, ORIENTATION,
and X and Y spacing.
St r i ng( ) STRING Returns the grid as a string

Table 2: 5
53.
3. LINE
LINEARGR
ARGRID
ID Object:
Object: B
Basic
asic Mem
Members
bers

  Orientation

YSpacing
Z Y

Position

XSpacing

Figure
Figure 2:31.
2:31. LIN
LINEAR
EARGR
GRID
ID Bas
Basic
ic Def
Defini
initio
tion
n
 2:84 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

LINEARGRI
LINEARGRID
D Object Methods that Re
Retur
tur n POSIT
POSITION
IONs
s
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Gr i dPo
Poii nt ( REAL, REAL) POSI
POSITI
TION
ON Retu
Return
rnss the
the posi
positi
tion
on at the
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
Snap
Snap(( POSI TI ON) POSI
POSITI
TION
ON Retu
Return
rnss the
the near
neares
estt
intersection point to the
passed position, when
mapped onto the grid plane
Snap
Snap(( LI NE) POSI
POSITI
TION
ON Retu
Return
rnss the
the near
neares
estt
intersection point to the
intersection of the passed
line and the grid plane
Snap( POI
POI NTVECTO
TVECTOR
R) POSI
POSITI
TION
ON Retu
Return
rnss the
the near
neares
estt
intersection point to the
intersection of the passed
point vector and the grid
plane
Snap
Snaptt oCen
oCentt r e( POSI TI ON) POSI
POSITI
TION
ON Retu
Return
rnss tthe
he near
neares
estt m
mes
esh
h
cell centre point to the
passed position, when
mapped onto the grid plane
Sna
napt
pt oCen
oCentt r e( LI NE) POSI
POSITI
TION
ON Retu
Return
rnss tthe
he near
neares
estt m
mes
esh
h
cell centre point to the
intersection of the passed
line and the grid plane

Snapt
Snapt oCent
oCent r e( POI
POI NTVEC
TVECTO
TOR
R) POSI
POSITI
TION
ON Retu
Re
cellturn
rns
s tthe
he near
centre neares
esttto m
point mes
eshh
the
intersection of the passed
point vector and the grid
plane

Table 2: 54. LINE

LINEARGR
ARGRID
ID Object
Object M
Method
ethods
s that Retu
Return
rn PO
POSITIO
SITIONs
Ns
 2:85 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Snap(POSITION)

Snap(LINE)

GridPoint(REAL, REAL)

Figure
Figure 2:32. POSI
POSITION
TIONs
s Returned
Returned b
by
y LIN
LINEARG
EARGRID
RID M
Method
ethods
s

2.5.31 LI
LIN
NEAR
ARG
GRID O
Obje
bject
ct
This method does not modify the original object.

Nam e Res u l t Pu r p o s e

Pl ane( ) PLANE Returns the grid as plane

object

Table 2: 55
55.. Misc
Miscellane
ellaneous
ous LINE
LINEARGR
ARGRID
ID Object
Object Meth
Methods
ods

  Within(POSITION)  
Plane()

Within(POSITION)  

Figure
Figure 2:33. Misc
Miscellane
ellaneous
ous Ret
Return
urn Va
Values
lues fr
from
om LINE
LINEARG
ARGRID
RID Me
Methods
thods
 2:86 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

LINEARGRID Object Methods that Return XYOffsets

This method does not modify the original object.

Nam e Res u l t Pu r p o s e

XYOf f set ( POSI TI ON) XYPOSITIO Returns the position,

N mapped onto the grid plane,
in terms of an XY offset from
the grid plane origin

Table 2: 56. LINE

LINEARGR
ARGRID
ID Object
Object M
Method
ethods
s that Retur
Return
n XYO
XYOffset
ffsets
s

XYOffset(POSITION)

Figure
Figure 2:34. XYOffset
XYOffsets
s Retu
Returned
rned by LINE
LINEARGR
ARGRID
ID Object
Object M
Methods
ethods
 2:87 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.32 L IS
IST Gad g
geet

Members

Nam e Ty p e Pu r p o s e

Val REAL Get/ Selected field-number of a

Set single-choice list.
Val REAL Selected field numbers of a
ARRAY Get/ multiple-choice list.
Set
DText STRING Set or get the entire list of 
ARRAY Get/ display texts.
Set
DTe
Text
xt [ n] STRING Get Get the display text of the
Only n 'th field.

Pi cke
ckedFi el d REAL Get Last picked list field number.
Only
RText STRING Set or get the list of 
ARRAY Get/ replacement texts.
Set
RText
Text [ n] STRING et Get the replacement text of 
Only the n 'th field.
Count REAL Get count of number of fields
Get only in the list
val REAL Selected field as integer.
Get/Set Zero implies no selection.
Setting val to zero will cause
an error for mandatory
selection lists.

Tabl
able
e 2:
2: 5
57.
7. LIS
LIST
TOObje
bject
ct Mem
Member
bers
s
 2:88 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Add(
dd( STRI
STRI NG Dt ext ) NO RESUL
RESULT Append
Append an en entry
try to tthe
he list,
list,
where Dtext   is the text to
display in the option list.
Add(
dd( ST
STR
RI NG Dt ext , ST
STR
RI NG Rt ext ) ) NO RESUL
RESULT
T App
Append
end an
and
d entr
entryy to the llist
ist,,
where Dtext   is the text to
display in the option list, and
Rtext  is the replacement text
for the new field. If Rtext  isn’t
specified, it will be set to
Dtext  by default.

Ful l Name( ) STRING Get the full name of the

gadget, e.g..'!!Form.gadget'
Name( ) STRING Get the gadget's name, e.g.
'gadget'
Owner ( ) FORM Get owning form.
Sel ect ( ST
STR
RI NG t ex
extt , STRI
TRI NG NO RESUL
RESULT
T Sel
Select
ect sp
speci
ecified
fied iitem
tem iin
n a list
list..
val
val ue) text   must be ‘Rtext’ or 
‘Dtext’. value  is the RTEXT
or DTEXT of the item to be
selected.
Sel ect ( ST
STR
RI NG t ex
extt , ARRAY of
of NO RESUL
RESULT
T Sel
Select
ect multip
multiple
le cho
choice
ice list
list
STRII NG val ues)
STR ues) items. text  must be 'Rtext' or 
'Dtext'. values   contains the
RTEXT or DTEXT values to
be selected.
Sel ecti on( ) STRING Get selected RTEXT
ARRAY OF
STRING Array
choice of
list.RTEXT for multi-
Sel ect i on(
on( STRI NG t ext ) STRING Get selected RTEXT or 
ARRAY OF DTEXT
STRING
Array of texts for multi-choice
list.
text  must be 'Rtext' or 'Dtext'.

Cl ear ( ) NO RESUL
RESULT
T Cle
Clear
ar list
list con
conten
tents
ts and
selections.
Cl ear Sel ecti on( ) NO RESUL
RESULT
T Cle
Clear
ar lilist
st ssele
electi
ctions
ons..
Set Po
Popup(
pup( MENU
ENU menu) NO RESU
RESUL
LT Link
Linkss menu   with the gadget
as a popup.
 2:89 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

RemovePo
eP opu
pup(
p( MENU menu)
enu) NO RESU
RESUL
LT Re
Remov
moves
es popup
popup menu   from
the gadget.
Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.
Ref r esh
sh(( ) NO RESUL
RESULT Refres
Refreshes
hes the
the display
display of th
the
e
gadget.
Shown( ) BOOL
BOOLEA
EAN
N Get
Get ‘s
‘sho
how
wn’ st
stat
atus
us..
 Type( ) STRING G e t th e g a d g e t ty p e a s a
STRING.
Set Tool
Tool Ti p( STRI
TRI NG) NO RESUL
RESULT Allows
Allows a TOOL
TOOLTIP to be
edited.
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Move
Move keyboar
keyboard
d focus
focus to this
this
gadget.
Set Hea
ead
di ngs( ! Dt ex
extt s i s STR
STRII NG) NONE Specifies the number of  
columns and sets the list's
column headings. Dtexts
contains a set of TAB
separated sub-strings.
Set Hea
ead
di ngs( ! Dt ex
extt s i s ARR
ARRAY) NONE Specifies the number of  
columns and sets the list's
column headings. Dtexts is
an array of strings.
Cl ear ( ! dt ext ) NO RESUL
RESULT
T Del
Delete
ete the
the fi
field
eld w
with
ith tthe
he gi
given
ven
DTEXT string.
Cl ear ( ! f i el dNumber ) NO RESUL
RESULT
T Del
Delete
ete the spe
specif
cified
ied field
field
number.
Set Rows( Ar r ay of ( Ar r ay of NO RESUL
RESULT
T Thi
Thiss sets
sets the displa
displayy text fo
for 
r 
STRII NG) )
STR 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.  Ar ray   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
exhausted. until the array is
 2:90 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Set Col umns( Ar r ay of ( Ar r ay of

of NO RESUL
RESULT Thi
Thiss sets
sets the displa
displayy text fo
for 
r 
STRII NG) )
STR 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.  Ar ray   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.
Se
Sell ect ( REAL
EAL c ol umn, ST
STR
RI NG NO RESUL
RESULT Thi
Thiss selects
selects th
the
e first list
list row
dt ext ) 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.
Backgr ound(
ound( ) STRING G et Ba
Background Co
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
able 2: 5
58.
8. LIST
LIST O
Obj
bjec
ectt Me
Meth
thod
ods
s

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:
 2:91 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

The data fields can be set using the List's DTEXT  member or its  Ad d   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
Reselection o f th e Selected
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-sele
De-selection
ction of th e selected
selected field f or ZeroSelection
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
event is raised is raised
for the for An
new field. theUNSELECT
previously selected field (ifwhenever
event is raised any) andathen a SELECT
selected field is
interactively deselected.

Notes:
1. UNSELECT
UNSELECT events
events are not notified
notified to PML unless
unless an open
open callback
callback has be
been
en specified
specified
(so that SELECT and UNSELECT events can be differentiated).
2. Typicall
Typicallyy the UNSELECT
UNSELECT action allowsallows Appware
Appware to manage consequeconsequences
nces of 
deselection for any dependent gadgets or forms.
3. We recommend
recommend that you
you do not change
change the List's
List's sele
selection
ction programm
programmaticall
aticallyy 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.
 2:92 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

. - - - - - - - <- - - - - - - - .
/ |
>- <f l i s t > - L I ST gname - +-
+- <f g gtt ag
agw> - - - - - - |
+- <f g gppos > - - - - - - - |
+-- <
+ <ff g
gdaoncckh>> -- -- -- -- -- -- ||
+- CAL L bac k t e ex xt - |
+- TOOL TI P t ex ext - - |
+- CORE - - - - - - - - - - * Cor e managed gadget
|
+- MUL Ti pl e - - - - - - - - .
| . - - - - - - - <- - - - - - - . |
|/ | |
+- NORESEL ec t - - - - | |
+- ZEROSEL ec ec t i on - * |
‘ - - - - - - - - - - - - - - - - - - - ‘ - <vs hap> +- TOOL TI P t e
ex
xt - .
‘----------------‘->

Figure
Figure 2:35
2:35.. Synt
Syntax
ax G
Graph
raph --:: Set
Setting-
ting-up
up a L
LIST
IST O
Object
bject

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

Default: A single choice, mandatory selection list.

2.5.33 LO
LOC
CATION Obje
bject
ct

Members

Nam e Ty p e Pu r p o s e

Nam
Name STRING Location name.
Descri pt i on STRING Description, up to 120
characters.
Lo
oc
ci d STRING Location identifier.
Ref no STRING STRING containing
Database reference no.
I sCu
sCur r ent BOOL
BOOLEA
EAN
N True
rue for
for tthe
he curr
curren
entt Lo
Loca
cati
tion
on..

Tabl
able
e 2: 59.
59. LOC
LOCA
ATIO
TION
N Ob
Objec
jectt mem
member
bers
s
 2:93 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

L OCATI
CATI ON( DBREF)
BREF) LOCA
LOCATI
TION
ON Retur
Returns
ns a LOC
LOCA
ATION
TION obje
object
ct,,
given a DBREF.
LOC
LOCATI ON( STRI NG) LOCA
LOCATI
TION
ON Retur
Returnsns a LOC
LOCA
ATION
TION obje
object
ct,,
given a name or reference
number (Global projects
only).
Dbl i s t ( ) ARRAY OF Array of DB objects for 
DB Allocated DBs. This method
does not modify the original
object.
Sessi ons(
ons( ) ARRAY OF Return array of all Sessions
SESSIONS extracted from COMMs db at
the Location. This method
does not modify the original
object.
St r i ng( ) STRING STRING cco ontaining LLo
o c a ti o n
name. This method does not
modify the original object.

Tabl
able
e 2: 60.
60. LOC
LOCA
ATIO
TION
N Obj
Objec
ectt Met
Method
hods
s

Note: The Sessi ons( )  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 = OBJ ECT LOCATI ON( ! ! CE)
! D = OBJ ECT LOCATI ON( ! ! CE. Name)
! D = ! ! CE. LOCATI ON( ) ! D = ! ! CE. Name. LOCATI ON( )
In all cases, !!CE is assumed to be a DB database element and !!CE.Name is a STRING
object containing the element’s name.
These methods should assist performance
performa nce improvements to AppWare by making it easier to
get from Database element to Object.
 2:94 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.34 MA C
CR
RO O
Ob
b je
jec t

Member 

Nam e Ty p e Pu r p o s e

Fi l enam
ename STRING Inter-DB macro filename (up
to 17 characters).
Fr om DB Source DB of inter-DB
connection macro.
Number REAL Inter-DB macro number.
 To DB Target DB of inter-DB
connection macro.

Tabl
able
e 2: 61. MACRO
MACRO Obj
Object
ect Mem
Member
bers
s

Command

!ARR
!ARRAY
AY = MACR
MACROS
OS $ Returns an array of all the MACRO objects in
$ the project

2.5.35 MDB O
Ob
b je
jec t

Member 

Nam e Ty p e Pu r p o s e

Nam
Name STRING Name of the MDB, up to 32
characters
Descri pt i on STRING MDB dedescription, u
up
p tto
o 1
12
20
characters
Ref no STRING String cco
ontaining D
Da
atabase
reference number 

Figure
Figure 2:36.
2:36. MD
MDB
B Obje
Object
ct Mem
Member
bers
s
 2:95 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

MDB( DBREF)
BREF ) MDB Returns an MDB object,
given a DBREF.
MDB( STRI NG) MDB Returns an MDB object,
given a name or reference
number.
Cur r ent ( ) ARRAY OF Current databases as an
DBS array of DB objects
Def er r ed( ) ARRAY OF Deferred databases as an
DBS array of DB objects
Mode( ) ARRAY OF Returns ‘NR’ or ‘RW’ for each
STRINGS current DB of the MDB

Tabl
able
e 2:
2: 62.
62. MD
MDB
B Obj
Object
ect Met
Method
hods
s

You can use the constructors in the following ways:

! D = OBJ ECT MDB( ! ! CE)

! D = OBJ ECT 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 element’s name.
These methods should assist performance
performa nce improvements to AppWare by making it easier to
get from Database element to Object.

Command

!ARRAY
!ARRAY=
= MDB
MDBS
S $ Returns an array of MDB objects in the project
 2:96 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.36 MEAS
ASU
URE O
Obj
bjeect

Members

Nam e Ty p e Pu r p o s e

Constructors

Measur e ( ) MEAS
MEASUR
URE
E Cr
Crea
eate
tess an inva
invalilid/
d/un
unse
sett
dimension (INVALID).
Measur e( STRI
STRI NG) MEAS
MEASUR
URE
E Creat
reates
es a ME MEASASURURE
E of 
of 
which string is a 'reasonable'
match to any of description,
name, hashcode, format
code (L, L2 etc) or any other 
recognisable name or 
abbreviation of a unit of the
measure.

Measur e( REAL)
EAL) MEAS
MEASUR
URE
E Creat
reates
which es
the a ME
MEAS
value ofASUR
URE
E is of 
REAL oaf 
(valid) enum value, or is a
negative (non standard)
dimension..

Tabl
able
e 2: 63. MEASU
MEASURE
RE O
Obje
bject
ct M
Memb
embers
ers

Methods

Nam e Res u l t Pu r p o s e

Descri pt i on( ) STRING Long description of  

St r i ng( ) dimension.

Name( ) STRING Unique name used fo r  

format statements and
commands
Hashcode( ) STRING H as h c ode of di m ens i on .
Pt ype
ype( ) Returns 'GENERIC' if 
generic dimension - i.e. non
standard.
Current Unit Methods

curr r ent uni t s( )

cu UNIT Returns current unit of this
dimension.
Uni t Qual i f i er ( ) STR
STRING Unit qualifier of curren
rent units.

Uni t Fact
Fact or ( ) REAL Conversion fa c to r to
database units from current
units.
 2:97 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Set Uni t s( uni t ) BOOL

BOOLEA
EAN
N Retu
Return
rnss ttru
rue
e ifif suc
succe
cess
ssfu
fullllyy
set current unit of the
dimension to unit.
Numer i c( ) BOOL
BOOLEA
EAN
N Set
Sets cu
curr
rren
entt unit
unitss of 
dimension to be Numeric (i.e.
no unit conversion in place).
NUMERIC units have
Hashcode NUMB and null
names, unitqualifiers, and
descriptions.
Returns true if successful.
Def aul t ( ) BOO
BOOLEAN
LEAN Set
Sets cur
curre
rent
nt uni
units o
off all
all
dimensions to those defined
by catalogue BUNI/DUNI.
Returns true if successful.

Suspen
Suspend(
d( ) BOOL
BOOLEA
EAN
N Susp
Suspen
ends
ds curr
physical cu rren
entt u
uni
nits
quantities ts ofand
all
all
operates exclusively in
database units. Pushes up
one level of suspension.
Returns true if successful.
Suspen
Suspend
dLevel
Level ( ) REAL Returns number of levels of  
suspension of current units.
If 0 no suspension in force.
Rei nst at e( ) BOOL
BOOLEA
EAN
N Rein
Reinst
stat
ates
es ccur
urre
rent
ntly
ly defi
define
ned
d
current working units for all
quantities.
quanti ties. Clears
suspension stack.
Returns true if successful.
Unsuspe
nsus pend
nd(( ) BOOL
BOOLEA
EAN
N Pops
Pops one
one lev
level
el of susp
suspen
ensision
on
stack of current units. If level
now one working in defined
current units.
Returns true if successful.
General Queries

I s Nul l ( ) BOOL
BOOLEA
EAN
N TRU
TRUE ifif dime
dimens
nsio
ion
n is NO
NONE
NE..

I sSt
sSt andar d( ) BOOL
BOOLEA
EAN
N TR
TRU
UE ifif d
dim
imen
ensi
sion
on is a
named (standard) dimension.
FALSE if specified from
powers of its base
components (i.e. Generic).
 2:98 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

DBUni t s( ) UNIT Database unit fo r th i s

DBUni t ( ) dimension.
ARRAY of  Set of standard units of this
Uni t sOf ( ) UNITs dimension.
Al l Di mensi ons( ) ARRAY of  Set of all standard
MEASUREs dimensions.
Al l Uni t s ( ) ARRAY of  Set of all named Units
UNITs
Enum
Enu m( ) REAL Unique integer ID for this
Dimension.
Positive if standard
dimension (packed Hash
Value)
Negative if generic
dimension coded from
component
dimensions.base

2.5.37 MENU Ob je
jec t

Members

Nam e Ty p e Pu r p o s e

Cal l back STRING Sets/gets the callback on the

menu.
Get/Set
Pi ck
cke
edFi el d STRING Returns the DTEXT of the
last picked menu field.
Get Only
Using this member is now
deprecated. Use the
PickedFieldName property
instead.

Pi ckedFi
ckedFi el dName STRING Returns the field name of the
last-picked TOGGLE or 
Get Only
CALLBACK field.

Tabl
able
e 2:
2: 6
64.
4. ME
MENU
NU Objec
Objectt M
Memb
embers
ers
 2:99 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Add( ' SEPA

SEPARATOR
TOR' , {S
{STR
TRII NG NO RESUL
RESULT
T App
Append
end a SEP
SEPARA
ARATOR
TOR fiel
field,
d,
f i el dName})
e}) with an optional STRING
argument, fieldName, that if 
present denotes the unique
field-name in the menu.
Add(
dd( ' CALLBA
LLBACK' , STSTR
RI NG Dt ex
extt , NO RESUL
RESULT
T App
Append
end a CALLB
CALLBACK
ACK fiel
field
d
ST
STR RI NG cal l ba
back,
ck, {STR
{STRII NG with Dtext , which may
f i el dName})
e}) 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(
dd( ' FOR
FORM' , ST
STR
RI NG Dt ext , ST
STR
RI NG NO RESUL
RESULT
T Append
Append a FOR
FORM M displa
displayy fie
field
ld
f or mName, {STRI
{STRI NG f i el dNam
dName}) 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(
dd( ' MENU
ENU' , STRI
STRI NG DText , STRI
STRI NG NO RESUL
RESULT
T App
Append
end a MENU (pull
(pullrig
right)
ht)
menuNam
enuName, {STRI NG f i el dNam
dName}) field with Dtext , which may
contain multi-byte
characters, but which cannot
be NULL or blank.
Name gives the pullright
menuNam
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.
 2:100 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Add(
dd( ' TOGGLE' , ST
STRRI NG Dt ext , NO RESUL
RESULT
T App
Append
end a T
TOGG
OGGLE
LE field
field w
with
ith
ST
STR RI NG cal l ba
back,
ck, {STR
{STRII NG Dtext , which may contain
f i el dName})
e}) 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.
Cl ear ( ) NO RESUL
RESULT
T Rem
Removes
oves all menu
menu fields
fields
from the menu.
Using this method is
deprecated .

Cl ea
earr ( STRI
TRI NG Dt ex
extt ) NO RESUL
RESULT
T Rem
Removeovess menu
menu fields
fields
starting with the one that
matches Dtext  onwards.
Using this method is
deprecated

Fi el dPr ope
oper t y( STRI
TRI NG menuFi el d, BOOL
BOOLEA
EAN
N Ge
Gett the
the valu
valueeooff the
the prop
proper
erty
ty
ST
STRRI NG pr op
oper
er t y) named in property  for the
menu field named in
menuField.
The allowed values for 
property   are ‘ACTIVE’,
‘VISIBLE’, or ‘SELECTED’.

Ful l Name( ) STRING Returns mefor

name, nu obje ct's full
example:
‘!!Form.Menu’.
I nse
serr t Af t er ( STRI NG menuFi el d, NO RESUL
RESULT
T Insert
Insert a CALLB
CALLBACK
ACK fiel
field
d wit
with
h
‘ CALLBAC
LLBACK’ , ST STR
RI NG Dt ext , ST
STR
RI NG Dtext , which may contain
cal l back, {STR{STRII NG f i el dName})
e}) 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
field name the unique
in the menu.
 2:101 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

I nse
serr t Af t er ( STRI NG menuFi el d, NO RESUL
RESULT Ins
Insert
ert a FORM displ
display
ay fiel
field
d
‘ FOR
FORM’ , STRSTRI NG Dt ext , STRI
STRI NG with Dtext , which may
f or mName, {STRI
{STRI NG f i el dNam
dName}) 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.
I nse
serr t Af t er ( STRI NG menuFi el d, NO RESUL
RESULT Ins
Insert
ert a MEN
MENU U (pullr
(pullrigh
ight)
t)
‘ MENU
ENU’ , STRSTRI NG Dt ext , STRI
STRI NG field with Dtext , which may
menuNam
enuName, {STRI NG f i el dNamdName}) 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.
I nse
serr t Af t er ( STRI NG menuFi el d, NO RESUL
RESULT
T App
Append
end TOG
TOGGLE
GLE fie
field
ld with
‘ TOGGLE’ , STRISTRI NG Dt ext , STRI
STRI NG Dtext , which may contain
menuNam
enuName, {STRI NG f i el dNamdName}) 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.
 2:102 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

I nse
serr t Af t er ( STRI NG menuFi el d, NO RESUL
RESULT
T Appe
Append nd a SEP
SEPARA
ARATO
TOR
R field
field
‘ SEPA
SEPAR RATOR’ , {STR{STRII NG f i el dNam
dName}
e})) 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.
I nser t Bef or e( STRI
TRI NG menu
enuFi el d, NO RESUL
RESULT
T Insert
Insert a CALLB
CALLBACK
ACK fiel
field
d wit
with
h
‘ CALLBAC
LLBACK’ , ST STRRI NG Dt ext , ST
STR
RI NG Dtext , which may contain
cal l back, {STR
{STRII NG f i el dName})
e}) 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.
I nser t Bef or e( STRI
TRI NG menu
enuFi el d, NO RESUL
RESULT
T Ins
Insert
ert a FORM displ
display
ay fiel
field
d
‘ FOR
FORM’ , STR
STRI NG Dt ext , STRI
STRI NG with Dtext , which may
f or mName, {STRI
{STRI NG f i el dNam
dName}) 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
present, denotes that, if 
the unique
field name in the menu.
I nser t Bef or e( STRI
TRI NG menu
enuFi el d, NO RESUL
RESULT
T Ins
Insert
ert a MEN MENUU (pullr
(pullrigh
ight)
t)
‘ MENU
ENU’ , STR
STRI NG Dt ext , STRI
STRI NG field with Dtext , which may
menuNam
enuName, {STRI NG f i el dNam
dName}) 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
field name the unique
in the menu.
 2:103 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

I nser t Bef or e( STRI

TRI NG menu
enuFi el d, NO RESUL
RESULT
T App
Append
end TOG
TOGGLE
GLE fie
field
ld with
‘ TOGGLE’ , STRI
STRI NG Dt ext , STRI
STRI NG Dtext , which may contain
menuNam
enuName, {STRI NG f i el dNam
dName}) 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.
I nser t Bef or e( STRI
TRI NG menFi
enFi el d, NO RESUL
RESULT
T Appe
Append
nd a SEP
SEPARA
ARATOTORR field
field
‘ SEPA
SEPARRATOR’ , {STR
{STRII NG f i el dNam
dName}
e})) 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 me
menu ob
object's
simple name, for example:
'Menu'.
Owner ( )  FORM Returns reference to owning
form.
PopupG
PopupGadget
adget ( ) GADGET Returns the name of the
gadget that popped up the
menu. The value is unset if 
the
by amenu was not popped up
gadget.
Ref r esh
sh(( ) NO RESUL
RESULT Refres
Refreshes
hes the
the display
display of th
the
e
gadget.
Sel
Sel ect ( STRI
STRI NG Dt ext , BOOLEAN
LEAN NO RESULT Set the selected status of 
st at us) TOGGLE field identified by
Dtext  to the value of status .
Using this method is
deprecated.

Sel ect ed(

ed( ST
STR
RI NG Dt ex
extt ) BOOL
BOOLEA
EAN
N Get
Get sele
select
cted
ed st
stat
atus
us of the
the
TOGGLE field identified by
Dtext .
Using this method is
deprecated.
 2:104 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Set
Set Act i ve( STRI
STRI NG Dt ext , BOOLEAN
LEAN NO RESUL
RESULT
T Set th
the e acti
active
ve sta
status
tus of the
the
acti ve) menu field identified by
Dtext .
Using this method is
deprecated.

Set Fi el dPr opert

opert y( STRI
TRI NG NO RESU
RESUL
LT Set the valvalue
ue of property
menuF
enuFii el d , ST
STR
RI NG pr oper
oper t y, with value, for the menu field
BOOL EAN val ue) 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.

Tabl
able
e 2:
2: 6
65.
5. ME
MENU
NU Objec
Objectt M
Meth
ethods
ods

Note: Setting the  Ac ti ve   and Visible  properties of a SEPARATOR field will affect the
implied group of fields comprising the SEPARATOR
SEPARATOR field and all subsequent fields up
to but not including the next SEPARATOR
SEPARATOR field.
For each of the Add(
dd( )  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 = ! t hi s . newmenu( ‘ Menu1’ , ‘ MAI N’ )
! menu. add( ‘ CAL L BACK’ , ‘ s av
ave’ , ‘ <c al l bac k>’ , ‘ f i el d1’ )
! menu. add( ‘ FORM’ , ‘ s ave as º ’ , ‘ s aveFor m’ , ‘ f i el d2’ )

Note:
• Each menu
menu is eithe
eitherr part of
of the Main
Main men
menuu system
system or part
part of the Po
Popup
pup memenu
nu sys
system
tem,,
but cannot belong to both.
• If you specify
specify neither
neither POPUP
POPUP nor nor MAIN at setup
setup time,
time, then
then the menu’
menu’ss usage
usage is initially
initially
unknown. The system will attempt to deduce the usage type from the first action that
references the menu.
• Menus in the
the Main
Main system
system cancan only
only appear
appear once.
once. That
That is,
is, a main
main system
system menu cannot
cannot
be a sub-menu of several menus.
• Menus
Menus in the Popu
Popup p system
system may appe
appear
ar only
only once in
in a given
given pop
popup
up tre
tree,
e, but may
may be
used in any number of popup trees.

• A menu cannot
cannot
a pullright referen
reference
of another ce itself,
menuitsinelf,
itseither
eown
ither menu
directl
directly
y as a pullright
tree. pullright of one of its o
own
wn fields
fields or be
 2:105 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

• You can add menu fields with an op tional field-name. IIff you do n ot specify a field-
name, then you w ill no t be able to refer to it later .
• You can use a special
special field-type
field-type to indicate
indicate that the
the fiel
field
d is managed
managed by core
core-code
-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 menu’s ADD commands and
terminated by the EXIT command. The full syntax is shown below:

>- - MENU - - gname - +- POPUP - - . . - - - - - - - - <-

<- - - - - - - .
+- MAI N - - | / |
‘ -- -- -- -- -- ‘ -+
+-- NL - + +-- <f menu> - |
+- PML - - - - - *
+- EXI T - - - - .
‘-----------‘-->

Figure
Figure 2:37
2:37.. Synta
Syntax
x Gra
Graph
ph -: D
Defi
efinin
ning
g a Men
Menu
u

. - - - - - <- - - - - .
/ |

f menu>- +- ADD - +
+-- fCiOR
eE
l d-n-a-m-e- -- |*
+- SEPar atat o
orr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .
‘- dt ex
ext - +- r t ext - - - - - - - - - - - - - - - - - - - - - - - - - |
+- MENU - - gname - - - - - - - - - - - - - - - - - |
+- FORM - - f na name - - - - - - - - - - - - - - - - - |
+- CAL L back - +- r t ex ext - - - - - - - - - - - - |
| ‘--------------------|
‘ - TOGgl e - +- r t ext - . |
‘ - - - - - - - - - +- SEL ec t ed ed - |
‘------------‘-->

Figure
Figure 2:
2:38.
38. Syntax
Syntax Grap
Graph
h --:: U
Using
sing Menu
Menu,Add(
,Add())

2.5.38
.38 Multi Discipl
iscipline
ine Route Mana
nage
ger 
r 

mdrRoutePoint

Nam e Ret u r n s A r g u m en ts Des c r i p t i o n Rem ar k s

OwningDbBranch DBREF Returns owner    

branch element of 
this route point.
OwningRoute mdrRoute Returns owning Redundant? - could be
mdrRoute 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
 2:106 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

ExpandToRoute mdrRoute Expands external  

geometry to
mdrRoute object.
IsExte
IsExterna
rnalGe
lGeome
ometry
try bool
bool Ret
Return true if its  
urnss true

an external
geometry object.
Ending
EndingRou
RouteP
tePoin
ointt mdr
mdrRou
RouteP
tePoin
ointt Sets
Sets end ext external Valid only if this is a
ernal
geometry ending external geometry type
route point. route point
EndingRoutePoint mdrRoute   Gets end external Valid only if this is a
Point geometry ending external geometry type
route point. route point
Start
tartin
ingR
gRou
oute
tePo
Poin
intt mdrR
mdrRou
oute
tePo
Poin
intt Se
Sets
ts en
endd exexte
ternal Valid only if this is a
rnal
geometry starting external geometry type
route point. route point
Start
tartin
ingR
gRou
oute
tePo
Poin
intt md
mdrR
rRou
oute
te   Gets end external Valid only if this is a
Point geometry starting external geometry type
route point. route point

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 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
Radius Real Get the fillet radius
of route point
Radius 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
Clone mdrRoute   Returns cloned Clones all the attributes
Point object taken from object which
from this method is
invoked (besides
underlying DB element,
and name)
 2:107 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Name String Gets the name of    

named route point
Is That String type Returns true if the Compares if the type is
named types the same with passed as

match argument.
Type String Gets the type of    
route point object
Type String type Sets the type of   behaviour not specified
route point object
DbElement DBREF Gets the underlying  
DB element.
IsEnabled bool Check if element is  
enables.
IsNamed Checks if element  
is named
IsOn true if route point true if route point are on
are on the same the same position
position
DbElement DBREF Sets owned DB  
element.
Enable bool enabled Enables or   enable true if we want to
disables route enable route point
point. otherwise false

mdrRoute

Nam e Ret u r n s A r g u m en ts Des c r i p t i o n Rem ar k s

dbWrite bool DBREF Writes to DB Returns true if write

hierarchy. was successful
Argument specify
where to method
should write to.
dbUpdate bool Updates DB Returns true if write
hierarchy. was successful
clone mdrRoute Returns cloned Clones all the attributes
object taken from object which
from this method is
invoked (besides
underlying DB element,
and name)
DbElement DBREF Gets the underlying  
DB element.
DbElement DBREF Sets the underlying Method changes
element. ownership

Construct DBREF Constructs route  

point from DB
 2:108 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Equals Bool Checks for equality  

of elements
HeadRoutePoint mdrRoute   Gets head route  
Point point

TailRoutePoint mdrRoute Ge
Gets
ts ta
tailil ro
rout
ute
e poi
point
nt
Point
HeadRoutePoint mdrRoutePoint Sets head route  
point
TailRoutePoint mdrRoutePoint Sets tail route point
InsertRoutePointAt   mdrR
mdrRou
oute
tePo
Point
int In
Inse
sert
rtss ro
rout
ute
e po
poin
intt  
Head at head
InsertRoutePointAtT   mdrR
mdrRou
oute
tePo
Point
int In
Inse
sert
rtss ro
rout
ute
e po
poin
intt  
ail at tail
Inser
sertRoutePoint mdrRoutePoint Insert route points  
at chosen index
Re
Remo
move
veRo
Rout
uteP
ePoi
oint
nt mdrR
mdrRou
oute
tePo
Poin
intt Re
Remo
moveve rout
route
e  
point from route
Fi
Fin
ndR
dRou
oute
teP
Poin
oint md
mdrrRo
Rou
ute
teP
Point
oint Get
Gets rout
route
e in
inde
dexx of   
route point (0
based)
RoutePoints Array of   Gets route points
mdrRoutePoint
InsertRouteAtHead mdrRoute Merge two routes  
on head
InsertRouteAtTail mdrRoute Appends route at  
end
insert Route mdrRoute, Inserts route at  
mdrRoutePoint route point
ExpandToRoute Expands all the ext  
geom. into route
Exp
xpan
andR
dRou
oute
tePo
Poin
intt md
mdrrRo
Rout
ute
e md
mdrrRou
oute
teP
Point
oint In pl
plac
ace
e exp
expan
and
d of   
ext geom.
size real number of route  
points in route
at mdrRoute real Route Point at
Point
SubRoute mdrRoute mdrRoutePoint, Cuts the route  
mdrRoutePoint between two route
points
HeadSubRoute mdrRoute mdrRoutePoint Creates sub route  
from head to route
point
TailSubroute mdrRoute mdrRoutePoint Creates su route  
sub ro
from route point to
tail
 2:109 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Transform Orientation Transforms route

Length Real Calculates route  
length
Length Real mdrRoutePoint, Length between  
mdrRoutePoint two route points
Length From Real Length from route  
point

mdrBaseManager 

Nam e Ret u r n s A r g u m en ts Des c r i p t i o n Rem ar k s

Crea
eate
teR
Rou
oute
teP
Point
oint mdrR
mdrRououte
te Position Route point from  
Point pos
Crea
eate
teR
Rou
oute
teP
Point
oint mdrR
mdrRououte
te DBREF Route Point from  
Point dbref 
CreateRoutePoint DBREF Route from dbref
FindRoute Array of   mdrConnection For given  
mdrConec Graph, connection graph,
tionPoint mdrRoutePoint, and two
mdrRoutePoint RoutePoints, find
the best path
between these
route points
BeginInteractiveRo   mdrRoute Enter Route point  
utePointsEditing model editor for 
given route
BeginInteractiveQui   mdrRoute Enter Quick  
ckRouting Routing model
editor for given
route

mdrConnectionManager 

Nam e Ret u r n s A r g u m en ts Des c r i p t i o n Rem ar k s

CreateRouteFrom mdrRoute Array of   For given path  

of
ConnectionPoints mdrConnection described by
Points connection points
array create route
CreateConnection mdrConnect DBREF For given owner,  
GraphFromOwner  ionGraph create connection
graph
CreateConnection mdrRoute Array of
of   For given array of   
GraphFromBranc DBREF dbrefs, create a
hes connection graph
 2:110 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

CreateConnection   Array of  Connect list of   

ByGeometryFrom DBREF branches base on
branches their positions
CreateConnection   DBRF Connect owning  
sByGeometryFro
mOwner  branches element
based on their pos
GetConnectedAtt ARRAY of  DBREF Connected attas  
asToAtta DBREF from atta

mdrConnectionGraph

Nam e Ret u r n s A r g u m en ts Des c r i p t i o n Rem ar k s

GetCon
GetConnec
nectio
tionPo
nPoint
int mdr
mdrCon
Connec
nectt mdrRoutePoint For given route  
ionPoint point return
connection point
GetAllConnectionPo Array of    Get connection  
ints mdrConnect point list
ionPoints

mdrConnectionPoint

Nam e Ret u r n s A r g u m en ts Des c r i p t i o n Rem ar k s

getRoutePoint mdrRoute   Get route point

Point
getConnectedRoute mdrRoute   Get connected  
Point Point route point
getFirstConnection Real 0- head, 1- tail, 2-  
Type mid, 3- free, 4-
none
getSecondConnecti Real 0- head, 1- tail, 2-  
onType mid, 3- free, 4-
none

2.5.39
.39 NUMERICI
ICINPUT O
Obje
bject
ct

Members

Mem b er Ty p e Pu r p o s e
v al REALGet/Set Value of the numeric input. Gets adjusted to
the nearest value in the range.
range REAL ARRAYGet/Set Range: Start, End and Step(>0) as reals.
 2:111 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Mem b er Ty p e Pu r p o s e
ndp REALReadonly In te g e r n u m b e r o f d e c i m a l p l a c e s t o b e
displayed. 0 means integer values.
modifiedEvents BOOLEANGet/Set Enable/disable modified events.
editable BOOLEANGet/Set Enable/disable editing of the displayed
value.
Tabl
able
e 2: 66. NU
NUME
MERIC
RICINP
INPUT
UT Ob
Objec
jectt Mem
Member
bers
s

Methods

Met h o d Nam e Res u l t Pu r p o s e

ange, ! ndp ) NO RESU

set Range( ! r ang RESUL
LT Se
Sett th
the
e rang
range
e an
and
d nu
numb
mber
er of
of de
deci
cimal
mal
places. !range is an array of REAL,
defining the min, max and step (>0)
values. !NDP<0 leaves the current
value unchanged.

Tabl
able
e 2: 67. NU
NUME
MERIC
RICINP
INPUT
UT Ob
Objec
jectt Met
Method
hods
s

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.
. - - - - - - - <-
<- - - - - - - - - - - - - - - - - - - .
/ |
- - NUMERI Ci nput gn
gna
ame - +- <f gt agw> - - - - - - - - - - - - - - - - - - |
+- <f gpos > - - - - - - - - - - - - - - - - - - - |
+- <f <f ganc h> - - - - - - - - - - - - - - - - - - |
+- <f gdoc k> - - - - - - - - - - - - - - - - - - |
+- CAL L Lbbac k t ext - - - - - - - - - - - - - |
+- TOOL TI P t e exxt - - - - - - - - - - - - - - |
+- CO CORE - - - - - - - - - - - - - - - - - - - - - - * Cor e managed gadget
| . - - - - - - - <-<- - - - - - - - - - - - - - - - - - - .
|/ |
+- RANGE val val - - - - - - - - - - - - - |
+- STEP val - - - - - - - - - - - - - - - - - - |
+- ND NDP i nt - - - - - - - - - - - - - - - - - - - *
|
+- VALU LUE E val
val - .
' - - - - - - - - - - - - - ' - <vwi d> - +- TOOL T TII P t ext - .
' ------- ------- ' -->

Notes:
1. The tag text
text is dis
displa
played
yed..
2. Default
Default initial
initial value
value is the minimum
minimum value of the range.
3. The range
range maximum
maximum is adjusted
adjusted to
to be an integral
integral number o
off steps.
steps.
4. NDP is the number
number of decimal
decimal places.
places. If NDP
NDP is zero then all
all valu
values
es will be iinteger
nteger..
5. Typed
Typed in values
values will be
be adjusted
adjusted to the nearest
nearest valid
valid value in the
the range.
 2:112 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

6. The graph <vwid>

<vwid> allows
allows the gadget width
width to be set specifical
specifically
ly or in terms of other 
other 
gadgets on the form.
7. It is not possible
possible to provide
provide user
user formatting
formatting of the
the values d
display
isplayed
ed by the gadget.
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.
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.40 OB J ECT

Method

Nam e Res u l t Pu r p o s e

Get Pat hNam

hName( ) STRING Extracts the pathname for a
file in the PMLLIB
searchpath.

Table
able 2
2:: 68
68.. PM
PML
L Ob
Obje
ject
ct M
Met
etho
hods
ds

2.5.41 OPTION G
Ga
adg
dgeet

Members

Nam e Ty p e Pu r p o s e

DText ARRAY OF Set or get the entire list of 

STRING display texts.
Get/Set
DTe
Text
xt [ n] STRING Get the display text of the
Get Only n 'th option.

RText ARRAY OF Set or get the list of 

STRING replacement texts.
Get/Set
RText
Text [ n] STRING Get the replacement text of 
Get Only the n 'th option.
 2:113 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e

Count REAL Get count of number of fields

Get only in the list.

Val REAL
Get/Set Selected
Zero impliesfield noas selection.
integer.
Setting val  to zero will cause
an error if ZeroSel is not
specified.

Tabl
able
e 2: 69. OPTIO
OPTION
NGGadg
adget
et M
Memb
embers
ers

Methods

Nam e Res u l t Pu r p o s e

Add(
dd( STRI
STRI NG Dt ext ) NO RESUL
RESULT
T Appe
Appendnd an eentry
ntry to the
the dro
drop
p
down list, where Dtext  is the
text to display in the option
list.
Add(
dd( ST
STR
RI NG Dt ext , ST
STR
RI NG Rt ext ) ) NO RESUL
RESULT
T Append
Append an and
d ent
entry
ry to the drop
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  isn’t specified, it
will be set to Dtext   by
default.
Cl ear ( ) NO RESUL
RESULT
T Cle
Clear
ar ga
gadge
dget’s
t’s con
conten
tents.
ts.
Cl ear Sel ecti on( ) NO RESUL
RESULT
T Cle
Clears
ars sel
select
ection
ion and return
returnss
to default of first in list.
Ful l Name( ) STRING G e t th e fu l l g a d g e t n a m e ,
e.g.'!!Form.gadget'
Name( ) STRING Get the gadget's name, e.g.
'gadget'
Owner ( ) FORM Get owning form.
Sel ect ( ST
STR
RI NG t ex
extt , STRI
TRI NG va
vall ue NO RESUL
RESULT
T Sel
Select
ect sp
speci
ecifie
fied
d ite
item
m in a lis
list:
t:
) text   must be ‘Rtext’ or 
‘Dtext’, and value is the item
to be selected.
Sel ecti on( ) STRING G et cu
current sse
election’s
RTEXT.
Sel ect i on(
on( STRI NG t ext ) STRING Get RTEXT or DTEXT of  
current selection; text   must
be ‘Rtext’ or ‘Dtext’.
 2:114 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Set Po
Popup(
pup( MENU
ENU menu) NO RESU
RESUL
LT Link
Linkss menu   with the gadget
as a popup.

Ref r esh
sh(( ) NOT
RESULT Refreshes
gadget. the display of the

Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Move
Move keyboar
keyboard
d focus
focus to this
this
gadget.
RemovePo
eP opu
pup(
p( MENU menu)
enu) NO RESU
RESUL
LT Re
Remov
moves
es (p(popu
opup)
p) menu
from the gadget.
Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.
Shown( ) BOOL
BOOLEA
EAN
N Get
Get ‘s
‘sho
how
wn’ st
stat
atus
us..
 Type( ) STRING G e t th e g a d g e t ty p e a s a
string.
Backgr ound(
ound( ) STRING G et Ba
Background Co
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..
Di spl
spl ayText ( ) STRING Gets tth
he te
text st
string cu
currently
displayed in the Option
gadget's display field.
Set Popup(
Popup( ! menu ) NO RESUL
RESULT
T Assigns
Assigns a men
menu
u object
object as tthe
he
gadget's current popup.
Cl ear ( ! dt ext ) NO RESUL
RESULT
T Del
Delete
ete the
the fi
field
eld w
with
ith tthe
he gi
given
ven
DTEXT string.
Cl ear ( ! f i el dNumber ) NO RESUL
RESULT
T Del
Delete
ete the spe
specif
cified
ied field
field
number.

Tabl
able
e 2: 70. OPTIO
OPTION
NGGadg
adget
et M
Meth
ethods
ods

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.
 2:115 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Notes:
1. Option gadget's
gadget's display
display text field
field is non editable,
editable, so doesn't need scroll
scroll width (sy
(syntax
ntax is
in fact in place for backwards compatibility).

. - - - - - - - <- - - - - - - .
/ |
>- - - - - - OPTi on gname - +- <f gt agw> - - - - - - |
  +- <f gpos> - - - - - - - |
  +- <f ganc h> h> - - - - - - |
  +- <f gdoc k k>> ------|
  +- CALLba
LLback ck t ext - |
  +- TOOLTI P t ext ext - - |
  +- NORESELect - - - - |
  +- ZER
ERO OSELect
SELect i on - |
  +- CORE - - - - - - - - - - * Cor e manag
anaged
ed gadg
adget
 |
  +- PI Xmap <vs hap> - .
 '- <vwi d> - - - - - - - - - +- TOOLT
LTII P t ext - .
' ------- ------ ---' -->

Figure
Figure 2:39. Synt
Syntax
ax G
Graph
raph --:: Sett
Setting
ing Up an OP
OPTION
TION Gadge
Gadgett

Reselection
Reselection o f th e Selected
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
width 5 tooltip 'select option'

ZeroSelection
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
UNSELECT events
events are not notified
notified to PML unless
unless an open
open callback
callback has be
been
en specified
specified
(so that SELECT and UNSELECT events can be differentiated).
2. Typicall
Typicallyy the UNSELECT
UNSELECT action allowsallows Appware
Appware to manage consequeconsequences
nces of 
deselection for any dependent gadgets or forms.
3. We recommend
recommend that you do not change
change the opti
option
on gadget'
gadget'ss selecti
selection
on programmatical
programmaticallyly
in an UNSELECT event.
 2:116 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.42
.42 ORIENTATIO
ION
N Ob
Obje
ject
ct

Members

Nam e Ty p e Pu r p o s e

Al pha
pha REAL The Alpha component.
Get/Set
Bet a REAL The Beta component.
Get/Set
Gam
Gamma REAL The Gamma component.
Get/Set
Or i gi n DBREF The DB element which is the
Get/Set origin.

Table 2: 7
71.
1. ORIE
ORIENT
NTA
ATION Objec
Objectt M
Membe
embers
rs

Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Or i ent
ent at i on(
on( STRI
TRI NG) ORIENTA
ORIENTATION Creates
Creates an ORIEN
ORIENT TATION
from the values given.
Or i ent
ent at i on
on(( ST
STR
RI NG, FOR
FORMAT ) ORIENTA
ORIENTATION Creates
Creates an ORIEN
ORIENTTATION
from the values given, in the
specified FORMAT.
EQ(( ORI ENTATI
EQ ENTATI ON) BOOLEAN TRUE if ORIENTATIONS are
equal.
LT( ORI ENTA
ENTATI
TI ON) BOOLEAN TRUE ifif OR
ORIENTATION is
less than argument.
St r i ng(
ng( FOR
FORMAT) STRING Convert ORIENTATION to a
STRING.
WRT( DBREF)
BREF) ORIENT
ORIENTA
ATION
TION Conver
Convertt to a ne
new
w
ORIENTATION with respect
to given DB element.
XDi r ( ) DIRECTION Return X component a
ass a
DIRECTION.
 YDii r ( )
 YD DIRECTION Return Y component a
ass a
DIRECTION.
ZDi r ( ) DIRECTION Return
urn Z component a
ass a
DIRECTION

Table 2: 7
72.
2. ORIE
ORIENT
NTA
ATION Objec
Objectt M
Method
ethods
s
 2:117 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.43 PAR
ARAG
AGR
RAP
APH
HGGa
adge
dgett

Members

Nam e Ty p e Pu r p o s e

Val STRING The paragraph's textual

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

Tabl
able
e 2: 73. PARAGPR
ARAGPRAPH
APH O
Obje
bject
ct Me
Membe
mbers
rs

Methods

Nam e Res u l t Pu r p o s e

AddPi xmap( STRI

STRI NG) NO RESUL
RESULT
T Adds pix
pixmap
mapss to be used
used ffor 
or 
AddPi xmap( STRI
STRI NG, STRI
STRI NG) the unselected, selected and
AddPi
ddPi xmap
ap(( STRI
STRI NG, STRI
STRI NG, inactive states.
STRI NG)
Ful l Name( ) STRING Get the full gadget name,
e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get owning form.
Set Popup ( MENU
ENU) NO RESUL
RESULT
T Lin
Links
ks the giv
given
en menu with
with
the gadget as a popup.
RemoveP
ov ePop
opup(
up( MENU)
ENU) NO RESUL
RESULT
T Rem
Removes
oves the given popup
popup
menu from the gadget.
Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.
Shown( ) BOOL
BOOLEA
EAN
N Ge
Gett ‘s
‘sho
how
wn’ st
stat
atus
us..
 2:118 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

 Type( ) STRING Get the GADGET type as a

string.

Backgr ound(
ound( ) STRING G et
Name. Ba
Background Co
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..

Tabl
able
e 2: 74. PARAGPR
ARAGPRAPH
APH O
Obje
bject
ct Me
Metho
thods
ds

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”.

. - - - - - - - - - - - - - - - - - - - - <- - - - - - - - - - - - .
/ |
>- - PARAgr a
apph gname - +
+-- - <f gp g pos > - - - - - - - - - - - - - - - - - - - - - - - - |
+- - BACKGr o ouund <c ol no> - - - - - - - - - - - - - |
+- - <f g gaanc h> - - - - - - - - - - - - - - - - - - - - - - - |
+- - <f g gddoc k> - - - - - - - - - - - - - - - - - - - - - - - |
+- - CORE - - - - - - - - - - - - - - - - - - - - - - - - - - -
* Cor e managed gadget
+- PI XMAP - +- f i l ename - .

|‘ - TEXT t ex‘t - - -+- -<-vs

- -ha
-p
ha->
- - .‘ - <vs hap>- - >
‘---------‘-->

Figure
Figure 2:40. Syntax
Syntax Gr
Graph
aph -: S
Setting
etting U
Up
paP
PARAG
ARAGRAPH
RAPH Objec
Objectt

Note:
• If a paragraph
paragraph is to contai
contain
n text, then its
its shape
shape will be spe
specified
cified in grid units
units.. The height
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
paragraph contains
contains text,
text, and no dimension
dimensionss are sp
specifie
ecified,
d, the result is a single
single line
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.
 2:119 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

• If your paragraph
paragraph is
is to contai
contain
n more than one
one line
line of ttext,
ext, yyou
ou must
must specify
specify a suitable
suitable
shape. The text, which can contain newline characters, will be justified in the area
given.
• If a pixmap
pixmap is specified,
specified, the
the shape of the gadget
gadget must
must be define
defined d and w
will
ill be in pixe
pixels.
ls.
Remember to define the pixmap using the paragraph's AddPi xmap( )   method or its
.Val member.
• If the paragrap
paragraph
h is to have itsits contents
contents modifi
modified
ed then the tex textt or pixmap
pixmap fifile
le would
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.44 PL A
AN
NE O
Ob
b je
j ec t

Members

Nam e Ty p e Pu r p o s e

Or i ent at i on ORIENTATI Orientation of plane.

ON Get/Set
Pos i t i on POSITION Origin of plane.
Get/Set

Tabl
able
e 2: 75. PLANE
PLANE Obj
Objec
ectt M
Memb
embers
ers

Definition Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Pl an
ane(
e( POSI TI ON, ORI ENTA
ENTATI
TI ON) PLANE Creates a PLANE with the
given POSITION and
ORIENTATION.

St r i ng( ) STRING Returns the plane as a string.

Di r ect
ect i on(
on( DI RECTI ON) DIRE
DIRECTI
CTION
ON Z com
compo
pone
nent
nt of the
the
orientation uses standard
PDMS method of maintaining
X and Y components of the
orientation.
 Towar ds( POSI TI ON) NO RESUL
RESULT
T Mod
Modifi
ifies
es the direct
direction
ion (Z
component of the orientation)
member of the plane so it is
directed to the position.

Tabl
able
e 2: 76. PLA
PLANE
NE Obje
Object
ct De
Defin
finiti
ition
on Me
Metho
thods
ds
 2:120 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

  Towards(POSITION)

Orientation

Direction(DIRECTION)
Z
Y

Position
X

Figure
Figure 2:41.
2:41. PLA
PLANE
NE Obje
Object
ct D
Defi
efinit
nition
ion

PLANE Object: Methods that Return POSITIONs

Nam e Res u l t Pu r p o s e

I nt er secti
secti on( LI NE) POSI
POSITI
TION
ON Retu
Return
rnss the
the iint
nter
erse
sect
ctio
ion
n po
poin
intt
of the passed infinite line on
the plane definition.
I nt er sect
sect i on( POI NT POSI
POSITI
TION
ON Retu
Return
rnss the
the iint
nter
erse
sect
ctio
ion
n po
poin
intt
VECTOR) of the passed point vector on
the plane definition.
I nt er se
sect
ct i ons(
ons( ARC) ARRAY OF Returns the intersection point
POSITIONS of the passed arc on the
plane definition.
I nt ers ect i on(
on( PLAN
PLANE, PLAN
PLANE) POSI
POSITI
TION
ON Retu
Return
rnss in
inte
ters
rsec
ecti
tion
on pos
posit
itio
ion
n
of the three planes.
Poi nt Vect or ( ) POINT- Returns a point vector at the
VECTOR origin of the plane with a
direction equal to the normal
of the plane.
 Thr eeDPosi t i on( XYPOSI TI ON) POSI
POSITI
TION
ON Retu
Return
rnss 3D posi
positi
tion
on of the
the
XYPOSITION offset from the
plane origin.
Near ( POSI TI ON) POSI
POSITI
TION
ON Retu
Return
rnss the
the near
neares
estt p
pos
osit
itio
ion
n
on the plane definition of the
passed position.

Table 2:
2: 77. PLAN
PLANE
E Ob
Object
ject Metho
Methods
ds tthat
hat R
Return
eturn POSI
POSITION
TIONs
s
 2:121 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Intersection(LINE) Intersection(PLANE, PLANE)

Near(POSITION)
ThreeDPosition(XYPOSITION)

Figure
Figure 2:42
2:42.. POSITION
POSITIONs
s returned
returned b
by
y PLA
PLANE
NE Ob
Object
ject M
Method
ethods
s

PLANE Object:
Object: Methods
Methods that Return LINEs
LINEs

Nam e Res u l t Pu r p o s e

Li ne( REAL) L IN E Returns a line of the given

length in the direction of the
plane normal.
I nt er se
sect
ct i on(
on( PLAN
LANE) L IN E 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.

Table 2: 78
78.. PLAN
PLANE
EOObject
bject Metho
Methods
ds th
that
at R
Return
eturn LINEs
LINEs
 2:122 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Intersection(PLANE)

Figure
Figure 2:43
2:43.. LINEs
LINEs Returne
Returned
d from PLAN
PLANE
E Ob
Object
ject Metho
Methods
ds

PLANE Object: Methods t hat Return XYOffsets

Nam e Res u l t Pu r p o s e

XYOf f set
set ( Posi t i on) XYPOSITIO Returns the position,
N mapped onto the plane, in
term of an XY offset from the
plane origin.

Figure
Figure 2:44. PLAN
PLANE
E Obj
Object
ect M
Method
ethods
s that Retur
Return
n XYO
XYOffse
ffsets
ts

XYOffset(POSITION)

Figure
Figure 2:45. XYPos
XYPositions
itions Retur
Returned
ned fro
from
m PLA
PLANE
NE Ob
Object
ject M
Method
ethods
s
 2:123 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.45 PLAN
LANT
TGRID Obje
bject
ct

Members

Nam e Ty p e Pu r p o s e

Pos i t i on POSITION Origin of the grid.

Get/Set
Or i ent at i on ORIENTATION Orientation of the grid.
Get/Set
XSpaci
Spaci ngs
ngs REAL ARRAY Array of spaces in the X
Get/Set direction, each space is
relative to the previous.
 YSpaci
 YSpaci ngs REAL ARRAY Array of spaces in the Y
Get/Set direction, each space is
relative to the previous.

Tabl
able
e 2: 79.
79. PLA
PLANTG
NTGRID
RID Object
Object Me
Membe
mbers
rs

Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

Pl ant gr i d( POSI TI ON, PLANT

PLANTGR
GRID
ID Crea
Create
tess a grid
grid w
wit
ith
h th
the
e gi
give
ven
n
ORI ENTATI
ENTATI ON, ARRARRAY, ARR
ARRAY ) POSITION and
ORIENTATION, and the X
and Y spacings specified in
the arrays.
Xsi ze
ze(( ) REAL Maximum size in the X
direction.
 Ysi z e( ) REAL Maximum size in the Y
direction.
Out of Bounds(
ounds( POSI TI ON) BOOL
BOOLEA
EAN
N Retu
Return
rnss wh
whet
ethe
herr poin
pointt lies
lies
within the grid boundaries.

Tabl
able
e 2: 80.
80. PLA
PLANTG
NTGRID
RID Object
Object Me
Metho
thods
ds
 2:124 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

  Orientation Y Ysize()

Position Z

YSpacing

XSpacing Xsize()
X

Figure
Figure 2:46. Retur
Return
nVValues
alues from PLAN
PLANTGRI
TGRID
D Object
Object Methods
Methods

2.5.46 PLA
LAT
TFORMGRID
PLATFORMGRID object is used for filling PLTFRM element with certain grid pattern.

Nam e Res u l t Pu r p o s e

ASSI GN( PLATFO

PL ATFORM
RMGRI D) NO RESULT C o p i e s c o n te n t o f a
PLATFORMGRID object
into current instance
GRI DANGL E( ) REAL Returns the us ed grid
angle value
GRI DANGL E( REAL
REAL ) NO RESULT Sets grid angle value

GRI DPOI
POI NT( REAL1,
EAL1, REAL2)
EAL2) NO RESULT Returns position of the
intersection of gridlines: X
(identified by given index -
REAL1) and Y (identified
by given index -REAL2)
GRI DPOSI TI ON( ) POSITION Returns the grid's origin

GRI DXSPAC
SPACI NGS( ) ARRAY Returns the grid's spacing
pattern along X axe
GRI DXSPAC
XSPACI NGS( ARRA
ARRAY)
Y) NO RESULT Sets the grid's spacing
pattern along X axe
GRI DXYPOSI TI ON( ) XYP
XYPOSITI
ITION Returns
rns posi
osition of grid's
origin
GRI DXYPOSI TI ON( XYPOSI
YPOSI TI ON) NO RESULT Sets the position of grid

GRI DXYSI ZE( ) REAL ARRAY Returns th e size of  

rectangle which contains
the grid
GRI DYSPACI
YSPACI NGS( ) REAL
EAL AR
ARR
RAY Returns
rns th
the gr
grid's spaci
acing
pattern along Y axe
 2:125 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

GRI DYSPACI
YSPACI NGS( ARRA
ARRAY)
Y) NO RESULT Sets the grid's spacing
pattern along Y axe
GROSSAREA( ) REAL Returns the gross area of  
the grid
NETAREA(
ETAREA( ) REAL Returns the net area of the
grid
ORI ENTA
ENTATI
TI ON( ) ORIE
ORIENT
NTA
ATION
TION Ret
Returns
urns thethe pla
plattform'
orm'ss
orientation
ORI ENTATI
ENTATI ON( ORI ENTATI
ENTATI ON) NO RESULT Sets th e platform's
orientation for given value
PLANE(
PLANE( ) PLANE Return the plane definition
of platform grid. This is
equivalent of PLANE
method on PROFILE
object
PLATF
PL ATFO
ORMGRI D( ) PLATFOR
PLATFORMGR
MGRID
ID Create
Create a platfo
platformgr
rmgrid
id

object.
PLATF
PL ATFO
ORMGRI D( DBREF
BREF)) PLATFO
PLATFORMG
RMGRID
RID Create
Createss a pl
platf
atform
ormgri
grid
d from
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
POSI TI ON( ) POSITION Returns position of the
platform
POSI TI ON( POSI TI ON) NO RESULT Sets the grid's position
ARRAY R e tu r n s th e size of  
XYSI
YSI ZE( ) rectangle (limits) which
contains the grid in platform
coordinate system

Methods that are performing operations on grid boundaries

Nam e Res u l t Pu r p o s e

ADD
ADDI NNERBOUNDARY(
ARY( PROF
PROFI L E) NO RESULT Adds new inner boundary to
the grid
CLEARI
CLE ARI NNERBOUNDARY( ) NO RE
RESULT D e l e te s a
alll inner bo
boundaries

I NNERBO
ERBOUNDARI
ARI ES( ) PROF
PROFIL
ILE
E AR
ARRA
RAY
Y Re
Retu
turn
rnss arra
arrayy of inne
inner 
r 
boundaries profiles
 2:126 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

I NNERBO
ERBOUNDARI
ARI ES( ARRA
ARRAY)
Y) NO RESULT Replaces the i nn er  
boundaries
I NNERBOUNDARY( REAL) PROFILE Returns the profile of the
inner boundary
NUMBEROFI NNERBOUNDARI ES(
ES( ) REAL R e tu r n s th e n u m b e r of  
grid's inner boundaries
OUTERBO
UTERBOUNDARY(
ARY( ) PROFILE R e tu r n s th e o u t e r b o u n d a r y
profile

Methods
Methods that return in formation about grids cells
Each cell is identified by index of two REAL.

Nam e Res u l t Pu r p o s e

CELLO
ELL ORI ENTA
ENTATI
TI ON( REAL1,
EAL1, ORIE
ORIENT
NTA
ATION
TION Retu
Return
rnss a
an
n ori
orien
enta
tati
tion
on of 
REAL2) cell identified by given
index.

CELLPOSI
ELLPOSI TI ON( REAL1,
EAL1, REAL2)
EAL2) POSITION Returns a position of cell
identified by given index
CELLPRO
ELLPROFI LE( REAL1,
EAL1, REAL2)
EAL2) PROFILE Returns a profile of cell
identified by given index
CELLSI ZE( REAL1,
EAL1, REAL2)
EAL2) REAL
EAL ARRAY Retur
turns the
the si
sizze of cel
cell
identified by given index
(before trimming)
CELLXYPO
ELLXYPOSI TI ON( REAL1,
EAL1, POSITION Returns position of the cell
REAL2) identified by given index
I SCELLTR
SCELLTRII MMED(
ED( REAL1,
EAL1, BOOL Returns true if c el l is
REAL2) trimmed
I SCELL
SCELLUUNTRI
TRI MMED( REAL1,
EAL1, BOOL Returns true if c el l is
REAL2) untrimmed
I SCELLW
SCELLWI THI
THI N( REAL1,
EAL1, REAL2)
EAL2) BOOL Returns true if cell is within
grid
LI STOFTRI
STOFTRI MMEDC
EDCELLS(
ELL S( ) ARRAY Returns indices of al l
trimmed cells
LI STOFTRI
STOFTRI MMEDC
EDCELLS(
ELL S( REAL)
EAL) ARRAY Returns indices of all
trimmed cells which area is
greater than given REAL
value
L I STOFUN
STOFUNTRI MMEDC
EDCELL
EL L S( ) ARRAY Returns indices of al l
untrimmed cells
 2:127 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

 TOTALN
TALNU
UMBERO
EROFCELLS(
FCELLS( ) REAL Returns a number of cells
inside grid
 TRI MMEDCELLSI ZE( REAL1,
 TRI EAL1, ARRAY Returns the size of  
REAL2) rectangle which contains
the cell identified by given
index

Methods
Methods that return in formation of gr idlines
Lines are returned as ARRAY which first element is REAL representing line number and the
second is array of LINE objects.

Nam e Res u l t Pu r p o s e

XGRI DLI NES(

ES( ) ARRAY Returns array of grid's x-lines

XGRI DLI NES( REAL)

EAL) ARRAY Returns array of grid's x-lines
of given index
 YGR
 YGRI DLI NES(
ES( ) ARRAY Returns array of grid's y-lines

 YGR
 YGRI DLI NES(
ES( REAL)
EAL) ARRAY Returns array of grid's y-lines
of given index

2.5.47 PMLR
LRe
epo
port
rt O
Obj
bjeect
This object is used to run new reports created by the designer in batch. The interface is
available on the .NET ReportingAddin assembly which may be imported and used as
follows:
i mpor t ' Repor t i ngAddi n'
hand
andl e ( 1000, 0)
endh
endhan
andl
dl e
using namespace 'Aveva.Pdms.Reporting'

! ! r epor t = obj
obj ect PMLRe
LReport ( )
For example, to add parameters to a parameterised report
! ar gNames = obj
obj ect ar r ay( )
! ar gNames[ 1] = ' par am1'
! ar gVal ues = obj ect ar r ay( )
! ar gVal ues[ 1] = ' val
val ue1'
! ! r epor t . add
addPar
Par amet er s( ! argNam
argNames, ! ar gVal ues)
To add scope to a report for limiting the data to be displayed, overriding existing scope
defined in the report
! ancest
ancest or El ement
ent s = ' / ATES
TEST, / BTES
TEST'
! el ement
ent s = ' '
! ! r epor t . AddScope
cope( ! ance
ancest
st or El ement s, ! el ement s)
 2:128 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

And to export report as csv file

! r ep1 = obj ect f i l e( ' C: \ r ep1. r epv' )
! c sv
sv1 = obj ec t f i l e( ' C: \ r ep1. c sv
s v' )

! ! r epor t . expor t AsCsv

sCsv(( ! r ep1. f ul l name( ) , ! csv1
csv1. f ul l name( ) )
Errors loading the report data may be logged by adding a handler to the response event.
The interface has the following methods:
Methods

Nam e Res u l t Pu r p o s e

AddPar amet er s ( ARRAY No Resul

esultt Adds
Adds par
param
amet
eter
erss to rre
eport
port a
ass 2
ar gNames, ARRAY arrays of argument names and
ar gVal ues) values, which will be used to
generate a parameterised report.
AddScope(
ddScope( STRI
STRI NG No Resu
Result
lt Speci
pecify
fy sc
scop
opee vval
alue
ue to filt
filter
er the
the d
dat
ata
a
ancest or El ement
ancest ent s, STR
STRI NG given by comma separated list of 
el ement
ent s) ancestor elements and comma
separated list of elements.
AddScope(
ddScope( STRI
STRI NG No re
resu
sult
lt Speci
pecify
fy sc
scop
opee val
value
ue to filt
filter
er the
the d
dat
ata
a
ancest
an cest or El ement
ent s, STR
STRI NG given by comma separated list of 
el ement
ent s, ancestor elements, comma
BOOLEA
LEAN f ul l y, separated list of elements, if limit
REAL
EAL mi nX,
nX, box is specified then whether it
REAL
EAL mi nY, should be considered fully or 
REAL
EAL mi nZ,
nZ, partially, to construct limit box minX,
REAL
REA L maxX,
axX,
REAL
REA L maxY,
axY , minY, minZ, maxX, maxY, maxZ.
REAL maxZ)
ax Z)
Expor t AsCsv( STR
Expor STRI NG No Res
Resu
ul t Exp
Export re
report
ort to
to ccssv ffiile
r epor
epor t Fi l eName, STRI
TRI NG
dest i nat i onFi l ename)

Ex
Expo
por
orr tt Fi
r epor
ep AsPdf ( STR
l eNamST
e,RI S
NTRI
G I NG
TR No Res
Resu
ul t Exp
Export re
report to
to p
pd
df fifile
dest i nat i onFi l ename)
Expor
xpor t AsXl
sXl sx( STRI
TRI NG No Resul
esultt Expo
Export
rt repo
report
rt to Xlsx
Xlsx fil
file
r epor
epor t Fi l eName, STRI
TRI NG
dest i nat i onFi l ename)
Expor
xpor t AsXl
sXl s( STRI
TRI NG No Re
Result Exp
Export re
report to X
Xlls ffiile
r epor
epor t Fi l eName, STRI
TRI NG
dest i nat i onFi l ename)
I ni t i al i z ePr i nt e Set t i ng No Resul
err Se esultt Init
Initia
ialilise
se the
the p
pri
rint
nter
er se
sett
ttin
ings
gs
()
OpenRepor
penRepor t Manager No re
result Opens rre
eport m
ma
anager  

Pr i nt ( STRI NG No re
resu
sult
lt Pri
Print rep
repor
ortt wi
with
th ssyyst
stem
em def
defin
ined
ed
r epor
epor t Fi l eName) printer settings passing name of 
report definition file
 2:129 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Pr i nt Di r ect ( STRI NG No Resu

Result
lt Prin
Printt rep
repor
ortt w
wit
ith
h use
userr d
def
efin
ined
ed prin
printe
ter 
r 
r epor
epor t Fi l eName) settings
Publl i s hToA
Pub hToAVEVA
EVANET( STRI
STRI NG No Resu
Result
lt Publ
Publis
ishe
hess rrep
epor
ortt tto
o AVE
AVEV
VA N
NET
ET in
r epor
epor t Fi l eName, STRI
TRI NG form of pdf file
pdf Fi l ename)
RemovePar amet er s ( ) No Resu
Result
lt Re
Remo
movevess tthe
he para
parame
mete
ters
rs appl
applie
ied
d to
to
report
RemoveSc
ove Scope(
ope( ) No Resul
esultt Remo
Remove vess the scop
scope
e appli
applied
ed to
report

2.5.48
.48 PMLS
LSE
ECURELO
LOG
GIN
PMLSECURELOGIN object is used to control the encrypted command script generation
functionality.

Methods

Nam e Res u l t Pu r p o s e

PMLSecur
LSecur eLogi
eLogi n( ) PMLSECUR Construct an instance of this object
ELOGIN
EmbedM
bedMacr
ac r o( BOOLEAN)
EAN) NO RESU
RESUL
LT Emb
Embed
ed the
the sspec
pecifi
ified
ed m
mac
acro
ro

HasLi
asL i cenceToEmbedM
bedMacr o( BOOL
BOOLEA
EAN
N Retu
Return
rnss TR
TRUEUE if EmbeEmbedM
dMac
acro
ro
) functionality is available.
Macr o( STRI
STRI NG) NO RESUL
RESULT
T Set the macro
macro to run where
where
STRING specifies the full path of 
the macro
MDB( STRI NG) NO RESU
RESUL
LT Sets
Sets the
the log
login
in MD
MDB
B

Pass wor d( STRI

STRI NG) NO RESU
RESUL
LT Sets
Sets tthe
he logi
login
nppas
assw
swor
ord
d

Pr oj ect ( STRI
TRI NG) NO RESU
RESUL
LT Sets
Sets tthe
he logi
login
nppro
roje
ject
ct

SaveT
aveToF
oFii l e( STR
STRI NG) NO RESUL
RESULT
T Encrypt
Encrypt and save to spec
specifi
ified
ed p
path
ath

User ( STR
STRI NG) NO RES
RESUL
ULT
T Sets
Sets the
the lo
logi
gin
n us
user 
er 

Ver i f yAf
yAf t er ( DATETI ME) NO RESU
RESUL
LT Verify
erify af
afte
terr spe
speci
cifi
fied
ed date
date

Ver i f yBef
yBef or e( DATETI
TETI ME) NO RESUL
RESULT Verif
erifyy bef
before
ore spe
specif
cified
ied dat
date
e

Ver i f yHost
yHost names( ARRAY) NO RESUL
RESULT
T Verif
erifyy a numb
number
er of host names
names
specified as an array of strings
Ver i f yWi nuser s( ARRAY) NO RESUL
RESULT Ve
Verif
rifyy a number
number of
of windows
windows users
users
specified as an array of strings

Tabl
able
e 2: 81. PM
PMLSE
LSECU
CUREL
RELOG
OGIN
IN Objec
Objectt Met
Method
hod
 2:130 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.49 PMLU
LUS
SERLO
LOG
GIN
PMLUSERLOGIN object allows generation of a project entry script only for the currently
logged-in user which means that it does not require entry of username and password.

Methods

Nam e Res u l t Pu r p o s e

PMLUser
LUser Logi
Logi n( ) PMLUSERLO Construct an instance of this
GIN object
Macr o( STRI
STRI NG) NO RESU
RESUL
LT Set
Set the mamacr
cro
o to run
run whe
where
re
STRING specifies the full path of 
the macro
MDB( STRI NG) NO RE
RESUL
SULT Sets
ets tth
he lo
login M
MD
DB

Pr oj ect ( STRI
TRI NG) NO RESU
RESUL
LT Set
Sets tthe
he logi
login
nppro
roje
ject
ct

SaveT
aveToF
oFii l e( STR
STRI NG) NO RES
RESUL
ULT
T Encr
Encryp
yptt an
and
d sa
save
ve tto
o sp
spec
ecif
ifie
ied
dppat
ath
h

ve(( BOO NO RESU

Ver i f yNonI nt er act i ve RESUL
LT If TRU
TRUE
E is pas
passe
sed,
d, vver
erif
ifyy th
that
at n
no
o
LEAN) user interaction occurs after 
execution of the generated macro

Tabl
able
e 2: 82. PM
PMLUS
LUSER
ERLOG
LOGIN
IN Ob
Objec
jectt Met
Method
hods
s

2.5.50
.50 POINT
INTVECTOR O
Obje
bject
ct

Members

Nam e Ty p e Pu r p o s e

Di r e ct
ct i on DIRECTION Direction of point
Get/Set

Pos i t i on POSITION Origin of point

Get/Set

Tabl
able
e 2: 83. PO
POINT
INTVEC
VECTO
TOR
R Obj
Object
ect Mem
Member
bers
s

Definition Methods

Nam e Res u l t Pu r p o s e

Poi nt ve
vect
ct or ( POSI TI ON, POIN
POINTVE
TVECT
CTOR
OR Crea
Create
tess a POINT
POINTVEC
VECTO
TORR
DI RECTI
ECTI ON) with the given POSITION
and DIRECTION
St r i ng( ) STRING Returns a POINTVECTOR
as a string.

Figure
Figure 2:47.
2:47. POI
POINTV
NTVECT
ECTOR
OR Ob
Objec
jectt Meth
Methods
ods
 2:131 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

 
Direction

Position

Figure
Figure 2:48. POINTVEC
POINTVECTOR
TOR Object
Object Defin
Definition
ition

Method s t hat Retur n POINTVECT

POINTVECTORs
ORs

Nam e Res u l t Pu r p o s e
Of f set ( REAL) POIN
POINTV
TVECT
ECTOR
OR Retu
Returns
rns tthe
he poin
pointt vec
vecto
tor 
r 
offset in its direction by the
passed distance
 Towar ds( POSI TI ON) POIN
POINTV
TVECT
ECTOR
OR Retu
Returns
rns tthe
he poin
pointt vec
vecto
tor 
r 
with the original position
and the direction
constructed from the
position directed to the
passed position
 Thr ough(
ough( POSI TI ON) POIN
POINTV
TVECT
ECTOR
OR Retu
Returns
rns tthe
he poin
pointt vec
vecto
torr at
the intersection of the point
line with a plane normal to
the point line through the
passed position

Table 2: 84. POIN

POINTVEC
TVECTOR
TOR O
Object
bject M
Method
ethods
s that Re
Return
turn PO
POINTV
INTVECT
ECTORs
ORs

  Offset(REAL)
Through(POSITION)

Towards(POSITION)

Figure
Figure 2:49. POINTVEC
POINTVECTOR
TORs
s Return
Returned
ed from POIN
POINTVEC
TVECTOR
TOR Ob
Object
ject Meth
Methods
ods
 2:132 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods that Return POSITIONs

Nam e Res u l t Pu r p o s e

I nt er sect i on(
on( POI NTVEC
TVECTO
TOR) POSI
POSITI
TION
ON Retu
Return
rnss the
the inte
inters
rsec
ecti
tion
on
position of the point vectors.
I nt er secti
secti on( LI NE) POSI
POSITI
TION
ON Retu
Return
rnss the
the inte
inters
rsec
ecti
tion
on
position of the point vector 
with the supplied line.
I nt er se
sect
ct i on(
on( PLAN
LANE) POSI
POSITI
TION
ON Retu
Return
rnss the
the posi
positi
tion
on at the
the
intersection of the point
vector with the supplied plane

Table 2: 85.
85. POIN
POINTVEC
TVECTOR
TOR O
Object
bject Metho
Methods
ds tha
thatt Retur
Return
n POSI
POSITION
TIONs
s

Intersection(PLANE)

Figure
Figure 2:50
2:50.. POINTVEC
POINTVECTOR
TOR Intersect
Intersection
ion w
with
ith a PLAN
PLANE
E

Miscellaneous Methods

Nam e Res u l t Pu r p o s e
I nt er se
sect
ct i ons(
ons( ARC) ARRAY OF Returns the positions at the
POSITIONS intersection
the supplied of the point vector with
arc.
Pl ane( ) 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.
Li ne( REAL) LINE 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.

Table 2:
2: 86. POIN
POINTVEC
TVECTOR
TOR Object
Object M
Misce
iscellaneo
llaneous
us M
Methods
ethods
 2:133 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.51 POSITION Obje

bject
ct

Members

Nam e Ty p e Pu r p o s e
East REAL The East component
Get/Set
Nor t h REAL The North component
Get/Set
Up REAL The Up component
Get/Set
Or i gi n DBREF The DB element that is the origin
Get/Set

Tabl
able
e 2: 87.
87. PO
POSIT
SITION
ION Object
Object Mem
Member
bers
s

Methods

Nam e Res u l t Pu r p o s e

Posi t i on( STRI

TRI NG ) POSI
POSITI
TION
ON Cr
Crea
eate
tess a P
POS
OSIT
ITIO
IONN a
att the
the
coordinates given in STRING.
Posi t i on
on(( ST
STR
RI NG, FORMAT) POSI
POSITI
TION
ON Cr
Crea
eate
tess a P
POS
OSITITIO
ION
N a
att the
the
coordinates given in STRING,
STRING,
with the specified FORMAT.
Component ( DI RECTI
ECTI ON) REAL M a g n i tu d e o f c o m p o n e n t i n
specified DIRECTION.
EQ( POSI
POSI TI ON) BOOL
BOOLEA
EAN
N TR
TRUE
UE if PO
POSI
SITI
TION
ONS
S are
are the
the
same.

LT( POSI TI ON) BOOL

BOOLEA
EAN
N TR
TRUE
UE if PO
POSI
SITI
TION
ON is less
less
than argument.
St r i ng(
ng( FOR
FORMAT) STRING Convert POSITION to a
STRING.
WRT( DBREF)
BREF) POSI
POSITI
TION
ON Conv
Conver
ertt to
to a n
new
ew POSI
POSITI
TION
ON
with respect to given DB
element.
Angl
ngl e ( POSI TI ON, POSI TI ON) REAL Returns the angle between
the passed two points about
the position object.
 2:134 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Ar cCen
cCentt r e( POSI TI ON, POSI TI ON, ARC Returns an arc using arc
POSI TI ON, DI RECTI
ECTI ON, REAL
EAL ) centre technique. The
direction is the ‘normal
viewing’ direction.
Ar cCen
cCentt r e( POSI TI ON, POSI TI ON, ARC Returns an arc using arc
POSI TI ON, DI RECTI
ECTI ON, REAL)
EAL) centre technique. The
direction is the ‘normal
viewing’ direction. Please see
diagram for full explanation.

Tabl
able
e 2: 88.
88. PO
POSIT
SITION
ION Object
Object Meth
Methods
ods (a)
(a)

 POSITION A 
POSITION X

RADIUS

POSITION B

Figure
Figure 2:51. !Arc = !pos
!posX.Ar
X.ArcFill
cFillet(!po
et(!posA,!p
sA,!posB,!
osB,!dir
dir,!rad
,!radius)
ius)
 2:135 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Ar cF
cFii l l et ( POSI TI ON, PO
POSI TI ON, ARC Returns an arc using arc
DI RECTI
ECTI ON, REALEAL )
centre
direction technique.
is the ‘normal The
viewing’ direction. Please see
diagram for full explanation.
Ar cR
cRad
adii us( POSI TI ON, POSI TI ON, ARC Returns an arc using arc
DI RECTI
ECTI ON, REAL, BOOLEAN ) 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.

Tabl
able
e 2: 89.
89. PO
POSIT
SITION
ION Object
Object Meth
Methods
ods (b)
(b)

 POSITION X 

POSITION B
MAJOR = FALSE 

RADIUS 
POSITION A

Figure
Figure 2:52. !Arc = !posX.ArcRad
!posX.ArcRadius(
ius(!posA
!posA,!pos
,!posB,!dir
B,!dir,radiu
,radius,!m
s,!major)
ajor)

Nam e Res u l t Pu r p o s e

Ar cThr
cThr u( POSI TI ON, POSI TI ON, ARC Returns an arc using arc
DI RECTI
ECTI ON ) through 3 points technique.
The direction is the ‘normal
viewing’ direction. Please
see diagram for full
explanation.

Tabl
able
e 2: 90.
90. PO
POSIT
SITION
ION Object
Object Meth
Methods
ods (c)
(c)
 2:136 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

POSITION X  POSITION A

POSITION B

Figure
Figure 2:5
2:53.
3. !Arc = !posX.A
!posX.ArcTh
rcThru(!p
ru(!posA,!
osA,!posB,
posB,!dir)
!dir)

Nam e Res u l t Pu r p o s e

Ar cThr
cThr u( POSI TI ON, POSI TI ON, ARC Returns an arc using arc
DI RECTI
ECTI ON, REAL
EAL ) through 3 points and radius
technique. The direction is
the ‘normal viewing’
direction. Please see
diagram for full explanation.

Tabl
able
e 2: 91.
91. PO
POSIT
SITION
ION Object
Object Meth
Methods
ods (d)
(d)

  POSITION A

POSITION X 

RADIUS

POSITION B 

Figure
Figure 2:54. !Arc = !po
!posX.A
sX.ArcThr
rcThru(!po
u(!posA,!
sA,!posB,
posB,!dir
!dir,!rad
,!radius)
ius)
 2:137 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Ar c3
c3Li
Li nes( LI NE, LI NE, LI NE, ARC Returns a circle through the 3
DI RECTI
ECTI ON )
line tangent
position points.
refers to theThe 'this'
zone in
which the circle lies.
Di r ect i on(
on( POSI TI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss tthe
he dire
direct
ctio
ion
n
between the position and the
supplied position
Di st ance(
ance( ARC) REAL Returns the distance between
the position and the nearest
point on the arc line of the
passed arc definition
Mi dPoi
Poi nt ( POSI TI ON) POSI
POSITI
TION
ON Retu
Return
rnss the
the midmid poin
pointt
between the two positions
Near ( POSI TI ON, REAL)
EAL) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the pass
passed
ed
position is within the passed
distance from the position
object
Of f set ( DI RECTI
ECTI ON, REAL)
EAL) POSI
POSITI
TION
ON Retu
Return
rnss a posi
positi
tion
on offs
offset
et by
the supplied length in the
supplied direction
Pl ane(
ane( POSI TI ON, POSI TI ON) PLANE R e tu r n s a p l a n e i n w h i c h
each of the supplied points
lie.
Di st ance(
ce( LI NE) REAL Returns the distance between
the position and the nearest
point on the passed infinite
line definition
Di st ance(
ance( PLAN
PLANE) REAL Returns the distance between
the position and the nearest
point on the passed plane
definition
Di st ance(
ance( POSI TI ON) REAL Returns the distance between
the two positions
Li ne( POSI TI ON) LINE Returns a line between the
two positions, starting at the
position object
Mi dPoi
Poi nt ( POSI TI ON) POSI
POSITI
TION
ON Retu
Return
rnss the
the midmid poin
pointt
between the two positions
Near ( POSI TI ON, REAL)
EAL) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss true
true if the
the pass
passed
ed
position is within the passed
distance from the position
object
 2:138 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Of f set ( DI RECTI
ECTI ON, POSI
POSITI
TION
ON Retu
Return
rnss a posi
positi
tion
on offs
offset
et by
  REAL) the supplied length in the
supplied direction
Pl ane(
ane( POSI TI ON, POSI TI ON) PLANE R e tu r n s a p l a n e i n w h i c h
each of the supplied points
lie.

Tabl
able
e 2: 92.
92. PO
POSIT
SITION
ION Object
Object Meth
Methods
ods (e)
(e)

2.5.52 POSTEVENTS Obje

bject
ct
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 ! ! post Eve
vennt s. post Mar k will be called every time an undoable is created,
after the undoable has been added to the undo stack.

This refers
or within to all
core undoables,
. whether created by a MARKDB command, an undoable object
functionality.
functionality
Similarly, the method post Undo  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

Nam e Res u l t Pu r p o s e

post Mar k( STRI

STRI NG) NO RESUL
RESULT
T Cal
Called
led after
after an u
undo
ndoabl
able
e has
been added to the undo
stack. STRING is the
description text associated
with the undoable object.
post Undo ( STRI
STRI NG) NO RESUL
RESULT Called
Called after
after an undo has
occurred. STRING is the
description text associated
with the undoable object.
post Red
edo(
o( STRI
STRI NG) NO RESUL
RESULT
T Cal
Called
led after a redredoo has
occurred. STRING is the
description text associated
with the undoable object.
post Cl earMark( ) NO RESUL
RESULT
T Ca
Calllled
ed afte
afterr a cl ea
earr Mar k
has occurred
pos t Cl
Cl ear Al l ( ) NO RESU
RESUL
LT Ca
Calllled
ed aft
after
er a c l ear Al l  has
occurred.

Tabl
able
e 2: 93. PM
PML
L Pos
PostEv
tEvent
ents
s Ob
Objec
jectt Met
Method
hods
s
 2:139 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.53 PROJE
JEC
CT O
Obj
bjeect

Members

Nam e Ty p e Pu r p o s e

Nam
Name STRING The name of ththe Project, up
up
to 120 characters.
Evar STR
TRIN
ING
G Pro
Project envi
nvironment variable,
e.g. SAM000

Tabl
able
e 2: 94. PROJE
PROJECT
CT O
Obje
bject
ct M
Mem
ember
bers
s

Methods

Nam e Res u l t Pu r p o s e

Acti ve( ) REAL Number of active users of the

project
Code(
ode( ) STRING Project code, three
characters, e.g. SAM
Descri pt i on( ) STRING Project de
description, up
up to
to 1
12
20
characters.
Mbchar
bchar set ( ) STRING Multibyte c h a r a c te r s et
number 
Mess age(
age( ) STRING Project me
message ((iinformation
about the project), up to 120
characters.
Name( ) STRING Project name

Number ( ) STRING Project number, up to 17

characters.
I s gl
gl obal ( ) BOOL
BOOLEA
EAN
N Whet
Whethe
herr proj
projec
ectt is a glob
global
al
project.
Lo
Loca
catt i ons( ) ARRAY OF Return array of all Locations
LOCATION in Project
Cur r ent Lo
Loca
catt i on( ) LOCA
LOCATIO
TION
N Retur
Return
n tru
true
e ccur
urren
rentt loc
locat
atio
ion
n
Sessi ons(
ons( ) ARRAY OF Return array of all Sessions
SESSIONS (at the current location)
Cur r ent Sessi on(
on( ) SESS
SESSIO
ION
N Retu
Return
rn cu
curr
rren
entt Sess
Sessio
ion
n (at
(at
the current location)
Dbl i s t ( ) ARRAY OF List of databases in the

DB
OBJECTS project.
 2:140 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

MDBLi st ( ) ARRAY OF Return array of all MDBs in

MDBS Project at current location.

Us e
err L i s t ( ) ARRAY OF Return array of all USERs in
USERS Project at current location.
Macr os( ) ARRAY OF Return array of all Inter-db
MACROS macros in MISC db in Project
at current location.
Mess ages
ages ( ) ARRAY OF Return array of all messages
STRINGS in MISC db at current
location.

Tabl
able
e 2: 95. PROJE
PROJECT
CT O
Obje
bject
ct M
Meth
ethods
ods

Commands

!ARR
!ARRAY
AY = PROJ
PROJEC
ECTS
TS $ Returns an array of all PROJECT objects
$ which have project environment variables
set.

!PROJE
!PROJECTV
CTVAR
AR = CURREN
CURRENT
T PRO
PROJEC
JECT
T $ Returns the current project object.

2.5.54 PROFILE Obje

bject

Members

Nam e Ty p e Pu r p o s e

Pos i t i on POSITION Origin of profile

Get/Set
Or i ent at i on ORIENTATION Orientation of profile plane
Get/Set
Poi nt er POINTER Definition of profile
Get Only

Tabl
able
e 2: 96. PROFIL
PROFILE
EOObje
bject
ct M
Memb
embers
ers
 2:141 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Pr of i l e( POSI TI ON, ORI ENTATI

TATI ON, PROFILE Creates a profile object. The
ARRAY) 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.
Pr of i l e( DBREF) PROFILE Creates a profile o
ob
bject fr
from
a LOOP, PLOO, PALJ or 
SPINE. Approximately from a
POGO, BOUN, DRAW.
DRAW.
3D linear geometry
(SPINE,BOUN, DRAW,PALJ)
should
not it be
is inprojected
a single plane.
onto aIf 
plane defined by the first few
points of the element.
Pr of i l e( DBREF1,
F1, DBREF2)
F2) PROFILE Creates a profile o ob
bject fr
from
SPRO or SLOO at DBREF1.
DBREF2 is the design
element referencing the
catalogue element containing
the catalogue primitive thus
providing its parameters.
Pr of i l e( PROFI LE)
LE) PROFILE Creates a profile object which
is a copy of the given profile
Pl ane( ) PLANE Returns the PLANE definition
of the profile. This is
equivalent to the PLANE
method on LINEARGRID
object
I sCl
sCl osed
sed( ) BOOLEAN Return true if closed
I sVa
sVal i dCl osed
sed ( ) BOO
BOOLEAN Returns
rns tru
true if the pro
profile is
valid and could be drawn
correctly using GML, e.g.
there are no self-intersecting
edges
Se
Sense(
nse( ) BOO
BOOLEAN
LEAN True ifif a
an
nti-clockwise (o
(on iitts
plane). Returns error if profile
is not closed
 2:142 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Ar ea( ) REAL Internal area of profile.

Returns error if profile is not
closed
Len
Lengt h( ) REAL Returns the complete length
of the profile.
I s Ci
Ci r c l e( ) BOO
BOOLEAN
EAN Returns
rns ttrrue ifif pro
proffile is
is a full
circle.
I s Fi
Fi l l et ( REAL ) BOO
BOOLEAN Returns
rns 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.

Tabl
able
e 2: 97. PROFIL
PROFILE
EOObje
bject
ct M
Meth
ethods
ods

Figure
Figure 2:55
2:55.. Finding
Finding the Length of th
the
e PRO
PROFILE
FILE Object
Object
PROFI
PROFILE
LE Object Decompositi on and Display Methods

Nam e Res u l t Pu r p o s e
edge
edges(
s( ) ARRAY 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.

number Edges
Edges ( ) REAL Returnthe
within s thprofile
e num(=bevertices-1)
r of edges
 2:143 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
edge( REAL)
EAL) LIN
INE/
E/AR
ARC
C Retu
Return
rnss tthe
he prof
profilile
e e
ele
leme
ment
nt at
the passed index of the edges
array
dbWr i t e( DBREF) PROFILE P o p u l a te s 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.
The owner of a LOOP or 
PLOOP is repositioned to fit
with the profile. Other 
geometry
correctly in isthe positioned
frame of 
reference of its owner or 
positioned ancestor.
Population of catalogue
geometry is not supported
dr aw( REAL1,
EAL1, REAL2,
EAL2, REAL3)
EAL3) PROFILE Draws th
the pr
profile a
ass 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: 98. PROF
PROFILE
ILE O
Object
bject Deco
Decompos
mposition
ition and Dis
Display
play Meth
Methods
ods
 2:144 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

PROFI
PROFILE
LE Object T
Transform
ransform ations and Modification Methods
Methods
These methods return a modified version of the profile definition:
Nam e Res u l t Pu r p o s e

mi r r or ( LI NE) PROF
PROFIL
ILE
E Mirr
Mirror
orss tthe
he boun
bounda
dary
ry defi
defin
nitio
ition
n
about the passed line, when
mapped onto the boundary
plane
t r ansl
ansl at e( REAL1, REAL2
L2)) PROF
PROFIL
ILE
E Offset
Offsetss tthe
he boun
bounda
dary
ry defi
defin
nitio
ition
n
in the XY of the boundary
plane with a shift of x of REAL1
and y of REAL2
r ot at e( REAL,
EAL, POSI TI ON) PROF
PROFIL
ILE
E Rot
Rotates
ates the
the b
bou
ound
ndar
aryy d
def
efin
init
itio
ion
n
about the POSITION by the
given angle. Angle are anti-
clock-wise about the Z axes of 
the boundary plane
c l os e(
e( ) PROFILE Closes tth
he pro
proffile w
wiith an
an
additional edge (if necessary).
If ends are within a tolerance
the end point is adjusted
r ever se(
se( ) PROFILE Reversrses
es the sense of the
profile and the order of the
edges
mer gea
gearr cs ( REAL1,
EAL1, REAL2)
EAL2) PROF
PROFIL
ILE
E Merg
Merge e co
connce
cent
ntri
ricc co
cont
ntiiguou
guouss
arcs into one up to a maximum
arc angle of REAL1 degrees
according to tolerance REAL2
earr cs( )   will remove
Mer gea
concentric back tracks in the
profile as well.
mer ge
gear
ar cs( ) PROF
PROFIL
ILE
E Merg
Merge
e co
con
nce
cent
ntri
ricc co
cont
ntiiguou
guouss
arcs into one.
mer ge
gell i ne
nes(
s( REAL)
EAL) PRO
PROFIL
FILE Merge cco olinear cco ontiguou
guouss
lines into one according to
tolerance supplied.
Mer gel i nes( )   will remove
colinear backtracks in the
profile as well.
mer gel i nes( ) PRO
PROFIL
FILE Merge cco ol i near cco
ontiguou
guouss
lines into one.
mer gepoi
gepoi nt s( REAL)
EAL) PROFILE Remove cco
oi nc i dent
consecutive points according
to tolerance supplied
mer ge
gep
poi nt s( ) PROFILE Remove cco
oi nc i dent
consecutive points
 2:145 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
pol yl i ne( REAL) PROFILE Replace arc
arcss wi
with a chorda
rdal
approximation to the tolerance
supplied
pol yl i ne( ) PROFILE Replace arc
arcss wi
with a chorda
rdal
approximation
pr oj ect Ar cs( REAL) PRO
PROFILE
ILE Remove
oves alall th
the a
arrcs ffrrom th
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 
Table 2: 99. PRO
PROFILE
FILE Ob
Object
ject T
Transf
ransforma
ormations
tions a
and
nd Modif
Modificatio
ication
n Methods
Methods

Figure
Figure 2:56. Trans
ransform
formations
ations an
and
d Modifi
Modificatio
cations
ns by PRO
PROFILE
FILE Obj
Object
ect Met
Methods
hods

PROFI
PROFILE
LE Object Methods th at Query Position Re
Relationsh
lationsh ips
These methods map the passed positions onto the profile plane, then use the resulting
position to determine the result returned:
 2:146 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Near ( POSI TI ON) POSI

POSITI
TION
ON Retu
Return
rnss tthe
he near
neares
estt p
pos
osit
itio
ion
n
on the profile,
position to the
projected ontogiven
the
profile plane.
Near ( REAL,
EAL, POSI TI ON) POSI
POSITI
TION
ON The
The R REA
EAL
L aarg
rgum
umenentt iiss a
ann
index to an edge in the
Profile. Returns the nearest
point on this edge to the
POSITION supplied. This is
the same as . neaearr
( POSI TI ON)  but restricted to
a single edge.
Near Edge
Edges(
s( POSI TI ON) ARRAY 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.
I sWi t hi n( POSI TI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss T
TRU
RUE
E ifif the
the posi
positi
tion
on
when mapped on to the
profile plane lies inside the
profile. The profile must be
closed.
I sWi t hout
out ( POSI TI ON) BOOL
BOOLEA
EAN
N Re
Retu
turn
rnss T
TRU
RUE
E ifif the
the posi
positi
tion
on
when mapped on to the
profile plane lies outside the
profile. The profile must be
closed.

OnPr of i l e( POSI TI ON) BOOL

BOOLEA
EAN
N Re
Retu
turn
rnss T
(mapped TRU
RUEE ifif the
onto the
the posi
poprofile
siti
tion
on
plane) lies on the profile
geometry.

Table 2: 100. Profile Object Methods that Query Pos

Position
ition Relationships
 2:147 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Figure
Figure 2:57. POSI
POSITION
TION Relat
Relationsh
ionships
ips ffor
or PR
PROFILE
OFILE Objec
Objects
ts

PROFI
PROFILE
LE Object Methods th at Query Profile to Profile Relationships
These methods are used to check the relationship between PROFILEs.

Nam e Res u l t Pu r p o s e

I sWi t hi n( PROFI LE
LE)) BOOL
BOOLEA
EAN
N True
rue iiff the
the supp
supplilied
ed prof
profilile
e
lies wholly within the profile
the object. Both profiles must
be closed.
I sWi t hout
out ( PRO
PROFI LE)
LE) BOOL
BOOLEA
EAN
N True
rue iiff the
the supp
supplilied
ed prof
profilile
e
lies completely outside the
profile object. Both profiles
must be closed.
I sI nt er sect
sect i ng( PROFI LE
LE)) BOOL
BOOLEA
EAN
N True
rue iiff the
the supp
supplilied
ed prof
profilile
e
intersects the profile object.
Both profiles must be closed

Table 2: 101. PROFILE Ob

Object
ject Methods th
that
at Query Pr
Profile
ofile to Profile Relations
Relationships
hips
 2:148 12 Series

 Soft ware Customi sation Reference

Reference Manual
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.

Nam e Res u l t Pu r p o s e

i nt er secti
secti ons( LI NE) 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.
i nt er sect
sect i ons( ARC) 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)
i nt er sect
sect i ons( PROFI LE
LE)) 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 

Table 2: 102. PROF

PROFILE
ILE Inter
Intersec
section
tion Meth
Methods
ods
 Figure
Figure 2:
2:58.
58. Intersect
Intersections
ions of P
PROFI
ROFILE
LE Object
Objects
s

2:149 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

PROFILE
PROFILE Object Metho ds t hat Retur n New PROFILEs
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.

Nam e Res u l t Pu r p o s e

i nt er se
sect
ct ( PRO
PROFI LE
LE)) ARRAY OF Returns array of the resultant
PROFILES intersection profiles
uni on(
on( PRO
PROFI LE) ARRAY OF Returns the union of the two
PROFILES profiles. Holes are returned
as separate profiles (in
reverse direction)
di f f er ence(
ce( PROFI LE
LE)) ARRAY OF Returns the difference of the
PROFILES passed profile against the
profile definition
s pl
pl i t ( L I NE) ARRAY OF Returns the resultant profiles
PROFILES from projecting the passed
line onto the profile and
splitting about that line
spl i t ( PLAN
PLANE, BOOLEAN
LEAN) 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.
Table 2: 103. PROFILE Ob
Object
ject Methods th
that
at Return New PROFILEs
 2:150 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Figure
Figure 2:59. PROFILEs
PROFILEs Returned
Returned fro
from
m PRO
PROFILE
FILE O
Object
bject Metho
Methods
ds

2.5.55 RAD
ADIIALG
ALGR
RID Obje
bject
ct

RADIAL GRID Object

Object Members

Nam e Ty p e Pu r p o s e

Pos i t i on POSITION Origin of the grid.

Get/Set
Or i ent at i on ORIENTATION Orientation of the grid.
Get/Set
Radi
adi i REAL ARRAY Radii of the grid.
Get/Set
Angl
ngl es REAL ARRAY Angular spacing, from X axes
Get/Set (zero).

Figure
Figure 2:60.
2:60. RAD
RADIAL
IALGR
GRID
ID Obj
Object
ect M
Mem
ember
bers
s
 2:151 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

RADIALGRI
RADIALGRID
D Object Definit ion Methods
Methods

Nam e Res u l t Pu r p o s e

Radi al gr i d( POSI TI ON, RADIAL

RADIALGRI
GRID
D Creates
Creates a grid
grid with
with the
the giv
given
en
ORI ENTATI
ENTATI ON, ARR
ARRAY, ARR
ARRAY) position and orientation, and
the angles and radii specified
in the arrays.

Table 2: 104. RADIALGRID Object Definition Methods

  Orientation

Position
Z
Y
Angles

X
Radii

Figure
Figure22:61.
:61. RADI
RADIALGR
ALGRID
ID Objec
Objectt definit
definition
ion (a)

RadialPosition(REAL, REAL)

Snap(POSITION)

Angle[1]

Snap(LINE)

Radius[1]
Radius[2] GridPoint(REAL, REAL)
Radius[3]

Figure
Figure22:62.
:62. RADI
RADIALGR
ALGRID
ID Objec
Objectt Definit
Definition
ion (b)
 2:152 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.56 REA L O
Ob
b je
jec t
The Real Object is a number with integer and decimal (fractional) parts. It also can
represent a physical quantity so in addition to a value it can also have units, and the units
will be of that physical quantity (or Measure, or dimension). Reals with physical quantity
preserve this in all their functions, when used as arguments to other objects, and in
arithmetic expressions. The units have to be compatible with the operation being performed
(for example trignometrical functions will expect to operate on ANGLEs. In the following
methods comments are made about constraints and expectations regarding the dimensions
of the real values.
When a real is created it is normally, (but not always e.g. the convert units functions) created
in current working units of the
t he quantity.

Methods

Nam e Res u l t Pu r p o s e
Constructors
Real ( BOOLEAN)
LEAN) REAL Creates a REAL from the given
BOOLEAN: TRUE = 1, FALSE = 0.
Real ( BORE) REAL Creates a REAL from the given
BORE.
Rea
eall ( ST
STR
RI NG) REAL Creates a REAL from the given
STRING.
The String must include a number to
give value to the REAL If the STRING
also a unit qualifier appended to the
number the REAL is given the
dimension of the physical quantity and
its value will be converted to current
working units of that dimension. It will
also interpret an extended range of 
feet and inch formats.
Real ( STRI
STRI NG, FOR
FORMAT ) REAL Creates a REAL from the given
STRING in the specified format.
If the string contains no unit qualifier 
the format defines the type of physical
quantity and the units of the number.
(or current units if format units not set).
set) .
The resulting REAL has current units
regardless of the format or input units.
If the conversion fails then the Format
object is used to provide alternative
unit qualifiers for the dimension (unit of 
measure) and these are used to try
and interpret the value. This is similar 
to the matching string functions.
 2:153 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
Real
eal ( REAL, UNI T) n /a creates an new REAL with the value of  
the REAL argument (ignoring its units)
in the units of UNIT.
Unit Related Queries
Val ue( ) REAL return undimensioned real with same
value as original.
Di mensi
ensi on(
on( ) MEAS
MEASUR
URE
E dime
dimens
nsio
ion
n ((of
of me meas
asur
ure)
e) of the the
physical quantity recorded by the real.
Uni t ( ) UNIT unit of measure of the quantity stored
Uni t s ( ) in the REAL.
Al l Di mensi ons( ) ARRAY of  Set of all standard dimensions.
MEASURES
Al l Uni t s ( ) ARRAY of  set of all named, standard Units.
UNITS
Unit Conversion Methods

Cast ( UNI T) REAL Same as REAL(REAL,UNIT).

Returns a REAL with the value of the
REAL object (ignoring its units) in the
units of UNIT.
Conve
onverr t Uni t s( STRI
TRI NG) REAL Returns a REAL converted from
Conve
onverr t ( UNI T) original units to the units specified by
Conve
onverr t Uni t s( UNI T) the UNIT or STRING argument.
The STRING value must be able to be
interpreted as a valid unit.
If Object is undimensioned its value is
assumed to be in the DatabaseUnits
consistent with the unit specified by
the STRING or UNIT argument.
DBUni t s( ) REAL Returns a real of same physical size,
but in database units.
Cur r ent Uni t s( ) REAL Returns a Real of the same physical
size, whose value is converted to be in
current working units and units of 
current units.
 2:154 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
Cur r ent Uni t s( STRI NG) REAL Returns a REAL of the same
Cur r ent Uni t s( UNI T) dimension as original and whose
Cur r ent
ent Uni t s ( MEASU
EASURRE) value reflects the same physical size,
but whose value is measured in
current units.
If the original REAL has units - returns
a Real with units of current units. The
argument is ignored.
If the REAL has no units - The
argument used to qualify the units of 
measure of the REAL. Its units are
that of the UNIT or STRING
argument. If the argument is a
MEASURE of name of a MEASURE
then the units are the appropriate
database units.
The returned REAL is returned only as
a converted Value. It has no units or 
dimension (as had the original REAL).
 Ar it hm eti c an d L og ic al Fu nc ti on s
ABS( ) REAL Absolute value (make value positive).
ACos( ) REAL ACOS. The real must be purely
numeric.
ALog(
Log( ) REAL ALOG. The real must be purely
numeric.
ASi n( ) REAL ASIN. The real must be purely
numeric.
ATan(
Tan( ) REAL ATAN. The real must be purely
numeric.
ATanT(
TanT( REAL)
EAL) REAL ATANT. The real must be purely
numeric.
Bet ween(
een( REAL,
EAL, REAL)
EAL) BOOL
BOOLEAN
EAN TRUE
TRUE if valu
value
e lie
liess in
in sspe
peci
cifi
fied
ed rang
range
e
including values specified. All the reals
must be of the same or compatible
physical quantities and will be
interpreted in consistent units.
Boo
ooll ean( ) BOOL
BOOLEA
EAN
N FALSE
ALSE iiff va
valu
lue
e is zero
zero,, ot
othe
herw
rwis
ise
e
TRUE.
Bor e( ) BORE Convert to BORE (must be exact)
dependent on current BORE units.
Cosi ne( ) REAL COSINE. The real must be an angle,
or purely numeric.
Di st ance(
ce( ) STR
STRING
ING Convert tto
o a distance u
ussing d
de
efault
ult
settings.
 settings.

2:155 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
Di st ance(
ance( BOOLEAN
LEAN f eet
eet , STRING Convert to a distance :
BOOL EAN us,
us , BOOL EAN to feet & inches if feet (otherwise
f r acti on, REAL pr
pr eci si on, inches);
BOOL EAN z er oes)
oes ) 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).
EQ(( BORE)
EQ RE) BOOL
BOOLEA
EAN
N Comp
Compar
aris
ison
on dep
depen
ende
dent
nt oonn curr
curren
entt
BORE units. The two reals must be of 
compatible quantities and are
compared in consistent units.
EQ( REAL)
EAL) BOOL
BOOLEA
EAN
N TRUE
TRUE if e
equ
qual
al.. Th
The
e ttwo
wo rrea
eals
ls mu
must
st be
be
of compatible quantities and are
compared in consistent units.
GEQ(
EQ( BORE) BOOL
BOOLEA
EAN
N Comp
Compar
aris
ison
on dep
depen
ende
dent
nt oonn curr
curren
entt
BORE units. The two reals must be of 
compatible quantities and are
compared in consistent units.
GEQ( REAL)
EAL) BOOL
BOOLEA
EAN
N TRUE
TRUE if grea
greate
terr ttha
han
n o
orr e
equ
qual
al to
another value. The two reals must be
of compatible quantities and are
compared in consistent units.
GT( BORE)
RE) BOOL
BOOLEA
EAN
N Comp
Compar
aris
ison
on dep
depen
ende
dent
nt oonn curr
curren
entt
BORE units. The two reals must be of 
compatible quantities and are
compared in consistent units.
GT( REAL)
EAL) BOOL
BOOLEA
EAN
N TRUE
TRUE ifif grea
greate
terr th
than
an ano
anoth
ther
er vval
alue
ue..
The two reals must be of compatible
quantities and are compared in
consistent units.
I NT( ) REAL Convert to whole number, rounding
down.
LEQ(( BORE)
LEQ BOOL
BOOLEA
EAN
N Comp
Compar
aris
ison
on dep
depen
ende
dent
nt oonn curr
curren
entt
BORE units. The two reals must be of 
compatible quantities and are
compared in consistent units.
LEQ(( REAL)
LEQ EAL) BOOL
BOOLEA
EAN
N TRUE
TRUE ifif less
less tha
than
n or equ
equal
al tto
o anot
anothe
her 
r 
value. The two reals must be of 
compatible quantities and are
compared in consistent units.

LOG
LOG( ) REAL LOG. Real should be numeric.
 2:156 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e
LT( BORE) BOOL
BOOLEA
EAN
N Comp
Compar
aris
ison
on dep
depen
ende
dent
nt oonn curr
curren
entt
BORE units. The two reals must be of 
compatible quantities and are
compared in consistent units.
LT( REAL) BOOL
BOOLEA
EAN
N TRUE
TRUE ifif less
less than
than ano
anoth
ther
er vval
alue
ue.. Th
The
e
two reals must be of compatible
quantities and are compared in
consistent units.
MODULO
ULO ( REAL)
REAL ) REAL The remainder MODULO the given
REAL.
A.MODULO(P) has the value A - floor 
(A / P) * P, where P cannot be zero.
Nea
earr est Bore( ) B OR E Convert tto
o nearest BORE dependent
on current BORE units setting.
Ni nt ( ) REAL Convert to nearest whole number (up
or down).
Power ( REAL)
EAL) REAL Raise vavalue to p
po
ower. IfIf th
the o
orriginal
real is of physical quantity the power 
value should be integer.
Real ( ) REAL Convert to REAL (in this case a null
operation).
SBet
SBet ween ( REAL,
EAL, REAL)
EAL) BOOL
BOOLEAN
EAN TRUE
TRUE if valu
value
e lie
liess in
in sspe
peci
cifi
fied
ed rang
range
e
excluding values specified. All the
reals must be of the same or 
compatible physical quantities and will
be interpreted in consistent units.
Si ne( ) REAL SINE. The real must be an angle, or  
purely numeric.
Sqrt() REAL Square root of value. If result is not a
supported unit of measure it will error.
St r i ng( STRI NG pr eci si on)
on) STR
STRING Convert to STRSTRING with precision
specified as a STRING in the range
‘D0’ to ‘D6’.
St r i ng(
ng( FOR
FORMAT) STR
STRING Convert tto
o S
STR
TRIING us using settin
tings in
in
global FORMAT object. same process
of using format units and unit qualifiers
in the STRING as applied in
REAL(STRING, FORMAT).
 Tangent
 Tangent ( ) REAL TANGENT. The real must be an angle,
or purely numeric.

Table 2: 105.
105. REAL O
Object
bject M
Method
ethods
s
 2:157 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.57 REPORT Obje

bject
The report object is used to format the table object data for displaying the contents
conte nts 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:
• al
alll a
att onc
once,
e, usin
using
g the
the Resul
sul t s( )  methods;
• a speci
specifie
fied
d numbe
numberr of entries
entries at a time,
time, usin
using
g th
the
e NextEnt
xtEnt r i es( ) methods. Each
entry will consist of one or more lines;
• a speci
specifie
fied
d numbe
numberr of lines
lines at a time,
time, usin
using
g th
the
e NextLi nes( ) 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
row.corresponding Rtext , which
For multi-line entries, will be
the same the value
Rtext namewill
of the DBREF object
be provided associated
for each line. with that

Methods

Nam e Res u l t Pu r p o s e

Report ( ) Constructor.
Repor
epor t ( TAB
TABLE) Constructor that also sets the
table and column formats.
 Tabl e( TAB
TABLE) Sets the table to be used for 
the report.
AddCol
ddCol umn( STRI
STRI NG key, Adds the column with the
COL UMNFORM
FORMAT, STRI NG headi ng) specified
with the key to the column
passed report,
format. The argument
heading   is the column
heading.
Next Ent r i esI ndex( REAL posi
posi t i on)
on) Sets the position in the result
array to be used for the next
evaluation.
Nex
extt Ent r i esI ndex
ndex(( REAL n, ST
STR
RI NG) Sets the position in the
matched result array to be
used for the next evaluation.
Set CaseMat c h( BOOL EAN
EAN) Used in conjunction with the
'…MATCH' methods, defines
whether matching is case
sensitive.
 2:158 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

I ni t i al i s e( ) Re-initialises the next

counter.

Eva
vall uat eTabl e( ) Re-evaluates on the table
primary key and re-sorts.
Key
eys(
s( ) STRING Returns an ARRAY of 
ARRAY STRINGS that are the
column keys used on this
report.
Col umnFor mat ( STRI
STRI NG key) COLUMN Returns the column format of 
FORMAT the passed column key
Col umnHeadi
nHeadi ng ( STRI
STRI NG key) STRING R e tu r n s th e h
he
eadi ng o
off tth
he
column identified by key.
 Tabl e( ) TABLE Returns the table used in this
report.

CaseMat ch( ) BOOL

BOOLEA
EAN
N Quer
Querie
iess wh
STRING whet
isethe
herr the
case thesensitive.
MA
MATC
TCH H
Set using CaseM
as eMat ch
EAN)) .
( BOOL EAN
Resul t s( ARRAY Dt
Dt ext , ARRAY BOOL
BOOLEA
EAN
N Eval
Evalua
uate
tess tthe
he repo
report
rt usin
using
gaallll
Rt ext ) 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.
Resul t s( ARRAY) BOOLEAN As above b bu
ut o
on
nly Dtext   is
evaluated.
Resul t sMat ch( ST
STR
RI NG, ARRAY, BOOLEAN Similar tto
o Resu
sull t s( )   but
ARRAY) only values matching the
string are put into the two
arrays.
Resul t sMat ch( STRI
STRI NG, ARRAY) BOOLEAN As above b bu
ut o
on
nly Dtext is
evaluated.
 2:159 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Nex
extt Ent r i es( REAL n,
n, ARRAY Dt ex
extt , BOOL
BOOLEA
EAN
N Eval
Evalua
uate
tess the
the repo
report
rt usin
usingg
ARRAY Rt ext ) the next n entries of the table

(there mayentry,
line per be more than 1
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.
Next Ent
Ent r i es( REAL
EAL n, ARRAY) BOOLEAN As above b bu
ut o
on
nly Dtext   is
evaluated.
Next Li ne
nes(
s( REAL
EAL n,
n, ARRAY Dt ext
ext , BOOL
BOOLEA
EAN
N Eval
Evalua
uate
tess the
the repo
report
rt with
with the
the
ARRAY Rt ext ) next
columnn   lines of thecause
formats table, a
if 
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.
Next Li nes(
nes( REAL
EAL n, ARRAY) BOOLEAN As above b bu
ut o
on
nly Dtext   is
evaluated.
Next Ent
Ent r i esMat ch ( REAL
EAL n, ST
STR
RI NG BOOLEAN Similar to
to NextEntries()  but
val ue
ue,, ARRAY DtDt ext , ARRAY Rt
Rt ext ) only values matching value
are put into the two arrays.
Next Ent
Ent r i esMat ch( REAL
EAL n, ST
STR
RI NG BOOLEAN As above b bu
ut o
on
nly Dtext   is
val ue
ue,, ARRAY DtDt ext ) evaluated.
Next Ent r i esI ndex( ) REAL Returns the current position
in the array of entries.
Nex
extt Li nesI ndex
ex(( ) REAL Returns the current position
in the array of entries.
Nex
extt Ent r i esI ndex
ndex ( STRI
TRI NG) REAL Returns the current count of  
the matched values array.
STRING is a key word
'MATCH'.

Table 2: 106. REPO

REPORT
RT Obj
Object
ect Me
Methods
thods
 2:160 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.58 RTOGGLE Gadge

dgett

Members

Nam e Res u l t Pu r p o s e

val BOOLEAN Current value true or false.

Get/Set
i ndex REAL Get Index of radio button within
Only the group.
onVal STRING Associated selected value.
Get/Set
of f Val STRING Associated unselected value.
Get/Set
vi s i bl e BOOLEAN Visibility.
Get/Set
ac t i ve BOOLEAN Active (greyed-in) status.
Get/Set
cal
cal l back STRING Callback string.
Get/Set
t ag STRING Tag text.
Get/Set

Table 2: 107. RTO

RTOGGLE
GGLE Object
Object Me
Member
mbers
s
 2:161 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Ful l Name( ) STRING Get the full gadget name,

e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get owning form.
Set Popup( MENU
ENU ) NO RESUL
RESULT
T Lin
Links
ks the give
given
n menu with
the gadget as a popup.
RemoveP
ov ePop
opup(
up( MENU ) NO RESUL
RESULT
T Rem
Remove
ovess the given popup
popup
menu from the gadget.
Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.

Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refresh
reshes
es the displ
display
ay of the
gadget.
Shown( ) BOOL
BOOLEA
EAN
N Get ‘s
‘sho
how
wn’ st
stat
atus
us..
Set Tool
Tool Ti p( ST
STR
RI NG ) NO RESUL
RESULT
T Set
Setss or edi
edits
ts th
the
e text o
off the
TOOLTIP.
 Type( ) STRING Get the gadget type as a
string.
Backgr ound
ound(( ) STRING Get Ba
Background Co
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: 108. RTO

RTOGGLE
GGLE Object
Object Me
Methods
thods

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.
 2:162 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

. - - - - - - - <-
<- - - - - - - - - - - - .
/ |
>- RTOGgl e gname - +- t a aggt ex
ext - - - - - - - - - - - - |
+- CAL L back t ex e xt —- - - - - |
+- <f g gppos > - - - - - - - - - - - - |
+- <f ganc h> - - - - - - - - - - - |
+- <f gdoc k> - - - - - - - - - - - |
+- TOOL TI P t ex ext - - - - - - - |
+- CORE - - - - - - - - - - - - - - - *   Core managed gadget
|
+- STATES of f val onval - -
.
‘ - - - - - - - - - - - - - - - - - - - - - - - - +- TOOL TI P t ex
ext - .
‘----------------‘--->

Not
otee: of
offv al  and onval  are string values associated with the radio button states unselected
fv al
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 gadget’s 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.59 Sec ti
ti on
on P
Pll an
an e
The Section Plane object provides an interface for interrogating and modifying a Section
Plane in the 3D View in Draft. It can be used in conjunction with the
PMLSectionPlaneManager PML Object. In order to add a PMLSectionPlane to the 3D View,
the PMLSectionPlaneManager must be used.

Set-up
Set-up Methods
Methods

Met h o d Res u l t Pu r p o s e
sect i onPl
onPl ane
ane ( DBREF) constructor Creates the Section Plane Object
with the given DBREF, which
must represent a SPLA, PPLA or 
FPLA element
 2:163 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Display Methods

Nam e Res u l t Pu r p o s e

N o R es ul t Redraw the plane in the 3D View.

Redr aw ( ) A plane is infinite in two directions,
but is drawn with it's infinite edges
clipped to the edges of the current
drawlist. Therefore, if the plane is
moved, or if the drawlist changes,
the plane may need to be redrawn.
Hi ghl i ght ( ) No Result Temporarily hhiighlight th
th e S
See c ti o n
Plane in the 3D View.
Show
Show ( BOOL EAN) N o R es ul t Show/hide a plane in the 3D View.

set Cl i ppi ng ( BOOLEA

LEAN, No Re
Result Set/unset the clipping status o
off th
the
DBREF) section plane within the VIEW.
DBREF is the reference of the
VIEW element
swii t chC
sw chCl i psi de ( DBREF) N o R es ul t Switch be between ssttandard aan
nd
reverse for which side of the
section plane the model will be
clipped. . DBREF is the reference
of the VIEW element
showCl i pI t ems
show No Result Highlight the items in the 3d view
( BOOL EAN,
EAN, DBREF
BREF)) that are in the clip list for this
section plane. DBREF is the
reference of the VIEW element
r edef i nePoi nt s No Result Clear tthhe p
pooints d
deefining tth
he
( DI RECTI
ECTI ON) section plane, and start a user 
interaction to redefine them.
DIRECTION specifies the
direction in which the lines
between the points are to be
extruded.
Col our
our ( REAL) N o R es ul t Set the colour of the Section Plane
(Real must be a colour.code())
 Tr ansl ucency ( REAL)
EAL) No Result Set tthhe ttrranslucency ooff th
t he
Section Plane.
99 = transparent, 1 = opaque

Query Methods

Nam e Res u l t Pu r p o s e

i s Val i d ( ) BOOLEAN C h e c k s i f th e s e c ti o n p l a n e o b j e c t
is valid.
quer yDbr ef ( ) DBREF Returns th e a c tu a l database
 element.

2:164 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

quer
quer yShow
yShow ( ) BOOLEAN Get the show of the Section Plane

quer yCl i p () BOOLEAN G e t th e c l i p p e d v a l u e o f t h e

Section Plane
quer
quer yType
yType ( ) STRING Get the types of the Section Plane.
(SPLA, FPLA, PPLA)
quer yCo
yCol our
our ( ) INTEGER G e t th e c o l o u r o f th e S e c ti o n
Plane
quer yTr
yTr ansl
ansl ucen
cency ( ) INTEGER Get the translucency of th e
Section Plane.

Table 2: 109. Selec

Selection
tion Plan
Plane
e Objec
Objectt Methods

2.5.60 Secti
ction
on P
Pla
lane
ne Mana
nage
ger 
r 
The Graphical Section Plane Manager object provides an interface for interrogating and
modifying Section Planes in the 3D View in Draft. It maintains a list of all PML SectionPlane
objects that have been added to the 3D View.

Set-up
Set-up Methods
Methods

Met h o d Res u l t Pu r p o s e

Sect i onPl
onPl aneM
aneManager ( ) constructor
anager Creates tth
he Se
Section P
Pllane
Manager Object

Display Methods

Nam e Res u l t Pu r p o s e

i ni t i al i se ( BOOLE
LEA
AN) No Re
Result True - Initialises S
Se
e c ti o n p
pllane m
mo
ode.
False - Uninitialise Section Plane
mode.

add ( DBREF)
BREF) No Result If DB
DBREPlanes
Section F is
is afrom
v i ew th
theView
a 2D n AAdd(Draft
d a
alll
VIEW element) to the 3D View.
If DBREF is a PLLB Add all Section
Planes from a 2D Library to the 3D
View. This includes all elements of the
following types:
• SPLA, PPLA, FP
FPLA
If DBREF is a SPLA, PPLA, or FPLA,
then it will be added to the 3D View.
A SECTIONPLANE object for each
section plane added will be created
and added to the list.
add ( SECTI
SECTI ONPLAN
PL ANE) N o R es ul t Adds the SECTIONPLANE o
ob
b j e c t to
the 3D View.
 2:165 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

add ( STRI
STRI NG) N o R es ul t Creates a S SEECTIONPLANE ob object
from the element with the given name
and adds it to the
th e 3D view.

r emove ( DBREF)
BREF) N o R es ul t If DBR
then it Ewill
F isbea Sremoved
PLA, PPLfrom
A, orthe
FPL3D
A,
View. If the corresponding
SECTIONPLANE object is in the list, it
will be removed..
r emove ( SECTI
SECTI ONPLAN
PL ANE) N o R es ul t Removes the SECTIONPLANE object
from the 3D View and the list.
c l ear ( ) N o R es ul t Clears all Section Planes from the 3D
View .
hi ghl i ght ( DBREF) N o R es ul t Temporarily highlights the Section
Plane with DBREF
DBREF..
r edr aw ( DBREF) N o R es ul t Redraw a alll pl
planes in
in tth
he 3
3D
D Vi
View. A
plane is infinite in two directions, but is
drawn with it's infinite edges clipped to
the edges of the current drawlist.
Therefore, if the plane is moved, or if 
the drawlist changes, the plane may
need to be redrawn.
DBREF is the reference of the VIEW
element.
cl i p ( BOOLEAN
LEAN) No Result Clip/Unclip th
the 3
3DD mmoodel ((w
within tth
he
3D View) with all the planes displayed
in the 3D View. SPLA items will not be
clipped.
s how ( BOOL EAN)
EAN) N o R es ul t Show/hide all planes in the 3D View.
showCl i ppi
show ppi ng N o R es ul t Show/hide tthhe ssiide ooff ea
each sse
ection
( BOOL EAN) plane that will be clipped
col our
our ( REAL) No Result Set the colour of All Section Planes
(Real must be a colour.code())
t r ansl
ansl ucency
cency ( REAL) N o R es ul t Set th
the transparency of Al
All S
Se
e c ti o n
Planes.
cr eat ePoi nt s No Result Creates an SPLA with the given name
( ST
STR
RI NG1, ST
STRRI NG2, STRING1 in the PLLB named
DI RECTI
ECTI ON) STRING2, extruded in the given
DIRECTION.
end
endCr ea
eatt eP
ePoi
oi nt s No Result Finish collecting points for the SPLA
 2:166 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Query Methods

Nam e Res u l t Pu r p o s e

ARRAY of 
ARRA Get all Section Planes in the 3D view
quer y ( ) SECTIONPLANEs
quer ySe
ySel ect ed ( ) DBREF Return the DBREF of the selected
Section Plane.

Create Methods

Nam e Res u l t Pu r p o s e

cr eat
eat eSp
eSpl a ( name, SECT
SECTIO
IONP
NPLA
LANE
NE Cr
Crea
eate
tess a new
new S
SPL
PLA
A ele
eleme
ment
nt with
with a
l i br ar y name, f i r s t specified name, which resides in a
poi nt , seco
secon
nd specific library. The first and second
poi nt , ext r usi on points represent the locations of the
di r ec t i on) first two WPOS elements. (These
will be created automatically by the
system
extrusionwith default
direction names).
must also be The
set.
The new SPLA will be drawn in the
3D view.
cr eat eFpl
Fpl a ( name, SECTI
SECTION
ONPLA
PLANE.
NE. Crea
Create
tess a new
new FPL
FPLA
A ele
eleme
ment
nt with
with a
l i br ar y name, specified name, which resides in a
poi nt , nor mal specific library. The position and
di r ec t i on) normal directions must be set. The
new FPLA will be drawn in the 3D
view.
cr eat
eat ePp
ePpl a ( name, SECTIO
SECTIONP
NPLA
LANE.
NE. Crea
Create
tess a new
new PPLA
PPLA elem
elemenentt w
wit
ith
ha
l i br ar y name, specified name , which resides in a
poi nt ) specific library. The position must be
set. The new PPLA will be drawn in
the 3D view.

Table 2: 110.
110. Selec
Selection
tion Plane Man
Manager
ager Objec
Objectt Methods
 2:167 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.61 SELE
LEC
CTOR G
Ga
adge
dgett

Members

Nam e Ty p e Pu r p o s e

Add(
dd( STRI
STRI NG Dt ext ) NO RESUL
RESULT Append
Append an e entry
ntry tto
o the list
list,,
where Dtext   is the text to
display in the option list.
Add(
dd( ST
STR
RI NG Dt ext , ST
STR
RI NG Rt ext ) ) NO RESUL
RESULT Append
Append an andd ent
entry
ry to tthe
he list,
list,
where Dtext   is the text to
display in the option list, and
Rtext  is the replacement text
for the new field. If Rtext  isn’t
specified, it will be set to
Dtext  by default.

Val REAL Selected field number of a

Get/Set single choice list. (1,2,…)
Val ARRAY OF Selected field numbers of a
REAL multiple choice list. (1,2,…)
Get/Set
DText STRING Set or get the entire list of 
ARRAY display texts.
Get/Set
DTe
Text
xt [ n] STRING Get the display text of the
Get Only n 'th field.

Pi cke
ckedFi el d REAL Last picked list field number.
Get Only

Table 2: 11
111. SELE
SELECTO
CTOR
R Objec
Objectt Member
Members
s

Methods

Nam e Res u l t Pu r p o s e

Ful l Name( ) STRING Get the full gadget name,

e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get the owning form.
Shown( ) BOOL
BOOLEA
EAN
N Get
Get ‘s
‘sho
how
wn’ st
stat
atus
us..
 Type( ) STRING Get the GADGET type as a

string.
 2:168 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Sel ect ( ST
STR
RI NG t ex
extt , STRI
TRI NG NO RESUL
RESULT Select
Select specifie
specified
d item
item in a
val
val ue) selector. t ext   must be
‘Rtext’
the fieldorRTEXT
‘Dtext’. va
vall ue  to
or DTEXT is
be selected.
Sel ect ( STRI NG t ext , Ar r ay NO RESUL
RESULT Sel
Select
ect multip
multiple
le cho
choice
ice
val
val ues) selector fields by value:
t ext   must be ‘Rtext’ or 
‘Dtext’. The val
val ues  array
contains the RTEXT or 
DTEXT of the fields to be
selected.
Sel ect i on(
on( STRI NG t ext ) STRING Get current selection: t ext
ARRAY OF must be ‘Rtext’ or ‘Dtext’.
STRING The value of Sel ec t i on  is
the RTEXT or DTEXT of the
selected field or fields.
Set Popup( MENU
ENU) NO RESUL
RESULT
T Lin
Links
ks the give
given
n menu with
the gadget as a popup.
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Mov
Move
e keyboar
keyboard
d focu
focuss to this
this
gadget.
Set Tool
Tool Ti p( STRI
TRI NG) NO RESUL
RESULT
T Set
Setss or edi
edits
ts th
the
e text o
off the
TOOLTIP.
Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refres
reshes
hes the
the display
display of th
the
e
gadget.
RemoveP
ov ePop
opup(
up( MENU)
ENU) NO RESUL
RESULT
T Rem
Remove
ovess the given popup
popup
menu from the gadget.
Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.
Cl ear ( ) NO RESUL
RESULT
T Cle
Clear
ar selec
selector
tor ccont
ontent
ents.
s.
Cl ear Sel ecti on( ) NO RESUL
RESULT
T Cle
Clear
ar selec
selectio
tions
ns on
only
ly..
Backgr ound(
ound( ) STRING Get Ba
Background Co
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: 112.
112. SELE
SELECTO
CTOR
R Objec
Objectt Method
Methods
s

2:169 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and 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.

. - - - - - - - <-
<- - - - - - - - - .
/ |
>- SELe
Lector
ctor gname - +-
+- - <f g gppos > - - - - - - - - |
+- - t ag agtext - - - - - - - - |
+- - <f ganc h> - - - - - - - |
+- - <f gdoc k> - - - - - - - |
+- - TOOLTI P t e exxt - - - |
+- - CALLba LLback text - - *
+- - SI NGl e - .
+- - - - - - - - - - - ‘ - <vs ha hap> DATAbas e - +- MEMber s - .
| +- OWNer s - - |
| ‘ - - - - - - - - - - - +- AUTO- .
| ‘------|
‘ - MUL Ti pl e <vs ha hap> DATAbas e - - - +- MEMber s - - - - - - - - - |
| - OWNer s - - - - - - - - - - |
‘-------------------|
|
. - - - - - - - <-
<- - - - - - - - - - - *
|
+- - TOOL TI P t ex e xt - - .
‘------------------‘->

Figure
Figure 2:63. Synt
Syntax
ax G
Graph
raph --:: Sett
Setting
ing up a SEL
SELECTO
ECTOR
R Obj
Object
ect

Default: Single choice. If DATABASE is not qualified, default is Members

plus  Owners. Auto update off.
 2:170 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.62 SESSION O
Obj
bje
ect

Members

Nam e Ty p e Pu r p o s e

Uni queI D STRING Internal ID

Get/Set
Nam
Name STRING Session Name
Get/Set
Logii n
Log STRING User’s login ID
Get/Set
Host STRING ID of the Machine running
Get/Set the session
Ent er ed STRING Time of entering the session
Get/Set

Locat
Loc at i onNam
onName STRING Name of Location for 
Get/Set Session
I sRem
sRemot e STRING True for Sessions at Remote
Get/Set locations
I sCu
sCur r ent BOOLEAN TRUE for User’s own
Get/Set SESSION object

Table 2: 113.
113. SESS
SESSION
ION Obj
Object
ect Mem
Members
bers

Methods

Nam e Res u l t Pu r p o s e

SESSII ON ( STRI
SESS STRI NG) SES
ESSI
SIO
ON Returns
rns a S
SE
ESS
SSIION ob
object,
given a string containing a
session's Unique-id.
Conf
onf i r mI D ( STR
STRI NG) BOOLEAN Returns TRU TRUE ifif th
the
password specified by the
STRING is correct for the
currently logged-in user. (The
STRING value must include
the leading ‘/’ character).
Cur r ent ( ) ARRAY OF List of Current DBs in the
DB MDB of the SESSION object.
Def er r ed( ) ARRAY OF List Deferred DB’s in the
DB MDB of the SESSION object.
 2:171 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Lo
Loca
catt i on( ) LOCA
LOCATI
TION
ON Retu
Return
rn L
LOC
OCAATION
TION tto
o whic
which
h
the Session applies. In a
non-Global project, returns
NULL or error.
MDB( ) MDB The current MDB of the
SESSION.
Mode(
ode( ) ARRAY OF List of potential access
STRING modes as ‘R’ , ‘RW’ or ‘N’ for 
each of the current DBs.
Modi f i ed( ) BOOL
BOOLEA
EAN
N TRU
TRUE ifif dat
datab
abas
ase
e h
has
as been
been
modified.
Modul
odul e( ) STRING Name of the current module.
Status() ARRAY OF List of current access modes
STRINGS as ‘R’ , ‘RW’ or ‘N’ for each
of the current DBs.
User
ser ( ) USER The user of this SESSION
object.

Table 2: 114.
114. SESS
SESSION
ION Ob
Object
ject Me
Methods
thods

Note:
• The LocationName member and Lo catt i on( )  method imply the location to which the
Loca
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
ADMIN Sessions
Sessions in a Glo Global
bal project
project may apply
apply to another
another location's
location's ssystem
ystem
database. This will be returned as part of the string returned by the Mod ul e( )  method,
odul
if relevant. Other ADMIN Sessions may actually be Global Daemon Sessions. This is
returned as part of the string for the name member.
• Some SESSI
SESSIONON objec
objectt methods
methods have onlyonly rest
restric
ricted
ted avai
availab
labili
ility:
ty:
• The Modi f i ed( )   method only applies to the current Session at the current
location.
• The Cur r ent ( ) ,   Def er r ed( ) ,   Mode( )   and Status()   methods will not be
implemented for remote Sessions and will return an error.
• The Lo catt i on( ) , MDB( ) , Use
Loca serr ( )   and Mod
odulul e( )  methods are valid for remote
Sessions.
The last three methods will cause Daemon activity for Sessions at remote locations.
• It should
should be should
should be
be observed
observed in using
using the
the MDB
MDB and USER objects
objects retu
returned
rned 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 ADMI NI STER SYSTEM command) before
invoking methods on these remotely generated MDB and USER objects.
 2:172 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Command

!SES
!SESSI
SION
ON = CURR
CURREN
ENT
T SE
SESS
SSIO
ION
N
$ Returns the current session object.

2.5.63 SLID
LIDER Gadg
dgeet

Members

Nam e Ty p e Pu r p o s e

vi s i bl e BOOLEAN Visibility.
Get/Set
ac t i ve BOOLEAN Active (greyed-in) status.
Get/Set
cal
cal l back STRING Callback string.
Get/Set
t ag STRING Tag text - not displayed for 
Get/Set this gadget.
val REAL Current value as integer.
Get/Set
backgr
backgr ound
ound REAL Background Colour Number.
Get/Set
backgr
backgr ound
ound STRING Set Background Colour Name.
only
r ange
ange REAL Range Start, End and
ARRAY optional Step(>0) as integers.
Get/Set The start value may be less
than the end value. Array
size must be 2 or more.
t i c ks t yl
yl e REAL Tick style as integer.
Get/Set
0 - none, 1 - right or bottom, 2
top or left, 3 - both 1 and 2

Table 2: 115.
115. SLIDE
SLIDER
R Object
Object Memb
Members
ers

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 slider’s
range. The range limits must each be an integral multiple of the step size (else an error 
is flagged
 is flagged
The RESET action of a form (from reset, CANCEL or QUIT actions) will only reset the

2:173 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

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 button’s callback and/or the form’s
CANCELCALL callback.

• Ti
Tick
ck marks
marks,, if prese
present,
nt, occu
occurr at every
every step val
value
ue in the rrang
ange.
e.
Methods

Nam e Res u l t Pu r p o s e

Ful l Name( ) STRING Get the full gadget name,

e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get owning form.
Set Tool
Tool Ti p( STRI
TRI NG) NO RESUL
RESULT Sets
Sets or edi
edits
ts the
the text of
of the
Tooltip.
Shown( ) BOOL
BOOLEA
EAN
N Ge
Gett ‘s
‘sho
hown
wn’’ st
stat
atus
us..
 Type( ) STRING G e t th e g a d g e t ty p e a s a
string i.e. 'SLIDER'.
Ref r esh
sh(( ) NO RESUL
RESULT Refresh
Refresh gadget
gadget image.
image.
Backgr ound
ound(( ) STRING G et Ba
Background Co
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..
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Set keyboa
keyboard
rd focus
focus to
gadget. Allows arrow keys to
drive slider.

Table 2: 116.
116. SLIDE
SLIDER
R Object
Object Metho
Methods
ds
 2:174 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Command

.-- -----<
<-- - - - - - - - - - - - - - - - - - - .

>- - SL I DER gname - +-/ t ag

agt e exxt - - - - - - - - - - - - - - - - - - - ||
+- <f g gppos > - - - - - - - - - - - - - - - - - - - |
+- CORE - - - - - - - - - - - - - - - - - - - - - - | Cor e managed gadget
+- <f g gaanc h> - - - - - - - - - - - - - - - - - - |
+- <f g gddoc k> - - - - - - - - - - - - - - - - - - |
+- BACKGr ound <c o oll no> - - - - - - - - |
+- CAL L back t e exxt - - - - - - - - - - - - - |
+- TOOL TI P t ex ext - - - - - - - - - - - - - - |
+- VERTi c al - - - - - - - - - - - - - - - - - - |
+- HORI Zont a all - - - - - - - - - - - - - - - - *
|
| . - - - - - - - <- - - - - - - - - - - - - - - - - - - .
|/ |
+- RANGE i nt i nt - - - - - - - - - - - - - |
+- STEP i nt - - - - - - - - - - - - - - - - - - |
+- VAL ue i nt - - - - - - - - - - - - - - - - - *
|
‘ - <vs hap> - +
+-- TOOL TI P t e
exxt - .
‘----------------‘-->

Figure
Figure 2:64
2:64.. Synt
Syntax
ax G
Graph
raph --:: Cr
Creating
eating a SLI
SLIDER
DER Object
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
WI DTH 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.64 STRING Obje

bject
String.real() will convert the string to a number in the same way as REAL(string) does
including an extended
will be in current set of feet and
units consistent with inch formats
the units thatstring.
in the can be interpreted. The resultant real

Methods

Nam e Res u l t Pu r p o s e

Af t er ( ST
STR
RI NG t wo) STRING Return sub-string following
leftmost occurrence of sub-
string two.
Bef or e( ST
STR
RI NG t wo) STRING Return ssu
ub-string b
be
e fo r e
leftmost occurrence of sub-
string two.
Bl ock
ck(( ) B LO C K Make STRING into a BLOCK
for evaluation.
 2:175 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Bool
ool ea
ean(
n( ) BOOLEAN TRUE iiff SST
TRING iiss ‘T
‘TRUE’,
‘T’, ‘YES’ or ‘Y’;
FALSE if STRING is ‘FALSE’,
‘F’, ‘NO’,or ‘N’.
Bor e( ) BORE Convert STRING to a BORE
(exact conversion - see also
NEARESTBORE).
Bor e( FOR
FORMAT) BORE Convert STRING to a BORE
using the settings in the global
FORMAT
FORMA T object.
DBRef ( ) DBREF Convert STRING to a DBREF.
DBRef
BRef ( F ORMAT) DBREF Convert STRING to a DBREF
using the settings in the global
format  object.

Di gi t s ( ) REAL Idigits
f Strinonly,
g cothen
ntainsreturn
decim al
the
positive value represented,
else return value -1.0. This
handles the digit characters
from any Unicode supported
language.
Di r ec t i on( ) DIRECTION Conve
nvert STR
TRIING to a
DIRECTION.
Di r ect i on
on(( FOR
FORMAT) DIRECTION Conve
nvert STR
TRIING to a
DIRECTION using the
settings in the global format
object.
Empt y( ) BOOLEAN TRUE for empty zero-length
string.
EQNoCas
oCase(
e( STRI
STRI NG ) BOOLEAN Compare eqequal ig
ignoring cca
as e,
with given string.
i s Di gi t s ( ) BOO
BOOLEAN Str
triing is a contig
tiguous
uous string of 
decimal digits only. This
includes the digit characters
from any Unicode supported
language.
i s Le
Let t er s ( ) BOO
BOOLEAN Str
triing is a contig
tiguous
uous string of 
letters only. This includes the
letter characters from any
Unicode supported language.
 2:176 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

i sLe
sLet t er sAn
sAndDi gi t s( ) BOO
BOOLEAN Str
triing is a contig
tiguous
uous string of 
letters and decimal digits only.
This
digits includes the letters
characters from and
any
Unicode supported language.
Len
Lengt h( ) REAL Number of characters in
string.
LowC
LowCase( ) STRING Convert string to lower case.
LT( STRI
STRI NG) BOOLEAN Comparison using ASCII
collating sequence.
Mat ch( STRI
STRI NG t wo) REAL Location of start of sub-string
tw o   within first string - zero
returned if not found.
Mat chWi l d( STRI
STRI NG t wo) BOOLEAN TRUE ifif strings are the same.
STRING tw o   may contain
wildcard characters:
·* for any
any number
number of 
characters
·? for any singl
single
e character
character..
Mat chWi l d( STRI
STRI NG t wo, STR
STRI NG BOOLEAN TRUE if strings are the same
mul t i pl e) as above but multiple
redefines the wildcard for any
number of characters.
Mat chWi l d( STRI
STRI NG t wo, STR
STRI NG BOOLEAN TRUE if strings are the same
mul t i pl e, STRI
TRI NG si ngl e) as above but multiple
redefines the wildcard for any
number of characters and
single  also redefines that for 

a single character.
Occur s( STRI
STRI NG) REAL Returns the number of  
occurrences of the given
string.
Or i ent at i on( ) ORIENT
ORIENTA
ATION Conver
Convertt STRING
STRING tto
o an
ORIENTATION.
Or i ent
ent at i on(
on( FORMAT ! ! f or mat ) ORIENT
ORIENTA
ATION Conver
Convertt STRING
STRING tto o an
ORIENTATION using the
settings in the global !!format.
Par
Par t ( REAL
EAL nt
nt h) STRING Extract nt h   field from string
where fields are delimited by
space, tab or newline.
Par
Par t ( REAL
EAL nt h, ST
STR
RI NG de
dell i m) STRING Extract nt h   field from string
where fields are delimited by
 where fields are delimited by
delim .

2:177 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Pos i t i on( ) POSITION Convert STRING to a

POSITION.
Po
Posi
si t i on(
on( FORMAT ! ! f or mat ) POSITION Convert STRING to a
POSITION using the settings
in the global !!format object.
REAL(
EAL( ) REAL Convert to a number.
Rep
epll ace( STRI
STRI NG t wo, STRI
STRI NG STRING Replace all occurrences of  
t hr ee) sub-string two with sub-string
three.

Rep
epll ace( STRI
STRI NG t wo, STRI
STRI NG STRING Replace all occurrences of  
t hr ee
ee,, REAL nt
nt h) sub-string tw o  with sub-string
three  starting at the nt h
occurrence (or -nt h
occurrence from the end).
Rep
epll ace( STRI
STRI NG wo, STRI
STRI NGt STRING Replace count   occurrences
hr ee,
ee, REAL
EAL nt h, REAL
EAL count
count ) of sub-string tw o   with sub-
string three starting at the nt h
occurrence (or -nth
occurrence from the end).
Spl i t ( ) ARRAY Split string into an ARRAY of  
STRINGS at space (multiple
spaces compressed).
Spl i t ( STRI NG el i m) ARRAY Split string into an ARRAY of  
STRINGS at delim   (multiples
of delim  not compressed).
St r i ng( BLOC
LOCK) STRING Creates a STRING from a
BLOCK expression.
St r i ng(
ng( BOOLEAN
LEAN) STRING Creates a STRING equal to
TRUE or FALSE.
St r i ng( BOOLEAN,
LEAN, FOR
FORMAT) STRING Creates a STRING from a
BOOLEAN, as specified in the
FORMAT
FORMA T object.
St r i ng( BORE) STRING Creates a STRING from a
BORE.
St r i ng
ng(( BORE, FOR
FORMAT) STRING Creates a STRING from a
BORE, as specified in the
FORMAT
FORMA T object.
St r i ng( DB) STRING Creates a STRING containing
the DB name.
 2:178 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

St r i ng(
ng( DB, FOR
FORMAT) STRING Creates a STRING containing
the DB name. The FORMAT
argument is required for 
consistency by Forms and
Menus.
St r i ng( DI RECTI
ECTI ON) STRING Creates a STRING from a
DIRECTION.
St r i ng(
ng( DI RECTI
ECTI ON, FOR
FORMAT) STRING Creates a STRING from a
Direction, as specified in the
FORMAT
FORMA T object.
St r i ng(
ng( FOR
FORMAT) STRING Convert STRING to a
STRING using the settings in
the global FORMAT object.
St r i ng(
ng( MDB) STRING Creates a STRING containing
the MDB name.

St r i ng(
ng( ORI ENTATI
TATI ON) STRING Creates a STRING from an
Orientation.
St r i ng
ng(( ORI ENTA
ENTATI
TI ON, FOR
FORMAT) STRING Creates a STRING from an
Orientation, as specified in the
FORMAT
FORMA T object.
St r i ng( POSI TI ON) STRING Creates a STRING from a
POSITION.
St r i ng(
ng( POSI TI ON, FOR
FORMAT) STRING Creates a STRING from a
POSITION, as specified in the
FORMAT
FORMA T object.
St r i ng( PRO
PROJ ECT) STRING Creates a STRING containing
the PROJECT code.

St r i ng( REAL) STRING C reates a STRING from a

REAL.
St r i ng(
ng( REAL,
EAL, FOR
FORMAT) STRING Creates a STRING from a
REAL, as specified in the
FORMAT
FORMA T object.
St r i ng( REAL,
EAL, ST
STR
RI NG) STRING 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.
St r i ng( SESSI ON) STRING Creates a STRING containing
the SESSION number.
St r i ng( TEA
TEAM) STRING Creates a STRING containing
 the TEAM name.

2:179 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

St r i ng( USER) STRING Creates a STRING containing

the USER name.
Subst
ubst r i ng( REAL i ndex
ndex,, REAL STRING Returns a sub-string, nchars
nchar
char s) in length, starting at index .
Subst r i ng( REALi ndex) STRING Returns a sub-string from
index  to the end of the string

 Tr i m( ) STRING Remove initial and trailing

spaces.
 Tr i m( STRI
STRI NG opt i ons, STRI
STRI NG STRING Reduce multiple occurrences
cha
char ) of char  to
 to a single occurrence
throughout the STRING
(options = ‘M’).
 Tr i m( STRI
STRI NG‘ opt i ons’ ) STRING Remove i n i ti a l spaces
(options  =‘L’), trailing spaces
(options   = ‘R’) or both
(options  =’LR’).
UpCase(
pCase( ) STRING Convert STRING to upper  
case.
VLog
Logi cal
cal ( ) BOOLEAN Evaluate STRING as a
BOOLEAN.
VTe
Text
xt ( ) STRING Evaluate STRING as a
STRING.
VVal ue( ) REAL Evaluate STRING as a
REAL.

Table 2: 117.
117. STRI
STRING
NG Obj
Object
ect Me
Methods
thods

Compare Strings Igno ring Case

Examples:

Notes:
• Th
The
e ne
new coconstr
tru
uct if( !this.attrib.eqNoCase('Name') ) is more efficient than
comparisons of the form if( !this.attrib.upcase() eq 'NAME' )  particularly when the
 check fails. It isagainst.
value checked also more reliable because it doesn t matter what is the case of the

2:180 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

• It may be worth
worth revisitin
revisiting
g such checks in the Appware and replacin
replacing
g them with the ne
new
w
construction as this could fix undiagnosed defects and improve performance!

Is Strin
Strin g Letters Only?

Example:

Is String Digits Only?

Example:

Get Value Of Digits Only String

Example:
! val = ! s t r dgt s . Di gi t s ( )
q var
var ! val
val
<REAL> 1234

Is String
String L etters And Digits Only?
Example:
! st r mi x= ! st r l et + ! st r dgt s
q var ! st r mi x. i sLsLe
et t er sAn
sAndDi gi t s( )

<BOO
q varL E!AN>
st r T
mRUE
i x. i sLe
sLet t er s( )
<BOO
BOOL EAN>
EAN> FALSE
AL SE
q var ! st r mi x. Di gi t s( )
<REAL> - 1
q var ! s t r l et . i s Le
Let t er s An
AndDi gi t s ( )
<BOOL EAN> TRUE
q var ! st r dgt s. i sLesLet t er sAn
sAndDi gi t s( )
<BOOL EAN> TRUE
 2:181 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.65 STATE
The STATE object provides an interface for interrogating and modifying the status of modify
mode. It is only available to Design running in graphical mode.

Met h o d Res u l t Pu r p o s e

state () constructor 

modi f yMode ( ) BOOLEAN Returns TRUE if modify mode is on;

else returns FALSE
modi f yMode none Sets modify mode on or off  
( BOOL EAN)
EAN)
enab
enabll eModi
odi f yMode
ode ( ) BOOLEAN Returns TRUE if modify mode is
enabled, else returns FALSE
enabll eModi
enab odi f yMode
ode BOOLEAN If TRUE, then modify mode is
( BOOL EAN)
EAN) enabled. If FALSE, modify mode is
disabled unless it is already on, in
which case this method has no effect.
The method returns TRUE if the
action is successful, else returns
FALSE.
. f eat ur eHi ghl i ght No Result If TTR
RUE, th t hen ffe
eatures ((p
ppoints,
( BOOL EAN)
EAN) plines, vertices, etc) are temporarily
highlighted in the 3d view as the
cursor passes over them. Setting this
to FALSE turns this feature off.

Table 2: 118.
118. ST
STA
ATE Objec
Objectt Method

2.5.66 TA B
BL
L E Ob je
jec t
The TABLE object is used to hold raw data in a manner that can be manipulated in a tabular 
manner, i.e.key.
the primary as aThe
spreadsheet.
columns ofEach row of
the table the table
contain represents
information a DBREF,
aboutDBREF , and is
the DBREF defined by
according btoy
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.
 2:182 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

 Tabl e( ) Constructor (initialises all the

object settings)
 Tabl e( DBREF ARRAY, COLU
LUM
MN ARRAY) Constructor that passes the
Primary Key as an ARRAY of 
DBREFS and the columns as
an ARRAY of COLUMNS
 Tabl e( COLLEC
LL ECTI
TI ON, COLU
LUM
MNARRAY) Constructor that passes the
Primary Key as a
COLLECTION and the
columns as an ARRAY of 
COLUMNS.
Pr i mar yKey( COLL
LLEC
ECTI
TI ON) User defined Primary Key
populated directly from a
COLLECTION.
Pr i mar yKey( ARRAY of DBREF) User defined Primary Key.
Col umn( REAL
REAL n, COL UMN) Replaces the -nth column of 
the table.
Cl ear
ear Col umns( ) Clears all the columns from
the table.
Col umns ( COL UMN ARRAY)
ARRAY) Sets up the columns from an
ARRAY
ARRA Y of COLUMN objects.
Eva
vall uat e( ) Evaluates the complete table.
Eva
vall uat eP
ePrr i mar yK
yKey
ey(( ) Re-evaluates the Primary
Key collection.
Pr i mar yK
yKey
ey(( ) DBREF Returns the primary Key of 
ARRAY the table, reference list for the
columns of the table.
Col umns( ) COLUMN Returns the column
ARRAY definitions. The order of the
columns is important when
sorting.
Cel l ( REAL
EAL c ol umn, REAL
EAL r ow) ANY Returns the contents of the
cell at the column  and ro w.
Col umn( REAL,
EAL, n) ARRAY Returns the contents of nt h
column.
Row( REAL,
EAL, n) ARRAY Returns the contents of nt h
row.
 Cel l ( ST
STR
RI NG key, DBREF) ANY Contentand
s ofrow.
the cell at the
column

2:183 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Col umn( STRI

STRI NG key) ARRAY Returns the contents of  
column identified by key .
Row( DBREF
BREF)) ARRAY Returns the contents of row
identified by DBREF
DBREF..

Table 2: 119.
119. Table -:T
-:TABLE
ABLE Objec
Objectt Methods

2.5.67 TEA M Ob je
jec t

Members

Nam e Ty p e Pu r p o s e

Nam
Name STRING Name of the TEAM, up to 32
characters.

Descri pt i on STRING TEAM description, up to 120

characters.
Ref no STRING STRING cco
ontaining
Database reference number.

Table 2: 120.
120. TEAM Object
Object Mem
Members
bers

Methods
None of these methods modifies the original object.

Nam e Res u l t Pu r p o s e

DbLi st ( ) ARRAY OF List of DBs owned by the

DB TEAM.
Us e
err L i s t ( ) ARRAY OF List of USERS in the TEAM.
USER
 TEAM
 TEAM( DBREF) TEAM Returns a TEAM o b j e c t,
given a DBREF.
 TEAM
 TEAM( STRI
STRI NG) TEAM Returns a TEAM object,
given a name or reference
number.

Table 2: 121.
121. TEAM Object
Object Meth
Methods
ods

These methods may be used in the following ways

! D = OBJ ECT TEAM( ! ! CE)

 ! D = OBJ ECT TEA
TEAM( ! ! CE. Name)

2:184 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

! 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 element’s name.
These methods should assist performance
performa nce improvements to AppWare by making it easier to
get from Database element to Object.

Command

! ARRAY = TEA
TEAMS $ Returns an array of TEAMs

2.5.68 TEXT G
Ga
ad g
geet

Members

Nam e Ty p e Pu r p o s e

Val STRING Set or get the contents of 

Get/Set STRING type TEXT field.
Val REAL Get/ Set or get the contents of 
Set REAL type TEXT field.
Val BOOLEAN Set or get the contents of 
Get/Set BOOLEAN type TEXT field.
Val 'AS Set or get the contents of the
DEFINED field according to the user 
Get/Set defined type.

Dat aType STRING Get Get the type of the field.

Only
Echo BOOLEAN Get the Echo Status. No-
Get Only echo means that typed
characters will all appear as
asterisks.
For
Fo r mat STRING Get Get the name of the format
Only object associated with the
field.
Sc r ol
ol l REAL Get Get the Scroll Width.
Only
Val i dat eCal l STRING Set/get user-defined
Get/Set validation callback.
 2:185 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e

Edi t abl e BOOLEAN Controls the ability to

Get/Set interactively edit the content
of a text field.
Table 2: 122.
122. TEXT O
Object
bject M
Member
embers
s

Methods

Nam e Res u l t Pu r p o s e

Ful l Name( ) STRING Get the full gadget name,

e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get owning form.

Cl ear ( ) NO RESUL
RESULT
T Cle
Clear
ar gadg
gadget
et cconte
ontents
nts..
Set
Set Edi
Edi t ab
abll e( BOOLEAN
LEAN) NO RESUL
RESULT Sets
Sets the edita
editable
ble st
status
atus fo
for 
r 
the field.
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Mov
Move
e keyboar
keyboard
d focu
focuss to this
this
gadget.
Set Tool
Tool Ti p( STRI
TRI NG) NO RESUL
RESULT
T Set
Setss or edi
edits
ts th
the
e text o
off the
TOOLTIP.
Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refresh
reshes
es the displ
display
ay of the
gadget.
Set Val ue( ANY val ue, BOOLEAN NO RESUL
RESULT Sets
Sets the valu
value
e of the field
field,,
val i dat e) checking for valid type and
format. If val i dat e  is

TRUE,
callback willthe validation
be executed.
Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.
Shown( ) BOOL
BOOLEA
EAN
N Get ‘s
‘sho
how
wn’ st
stat
atus
us..
 Type( ) STRING Get the gadget type as a
string i.e. 'TEXT'.
 2:186 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Set edi t abl e( STRI NG at t r i b, NO RESUL

RESULT
T Speci
pecify
fy value
value of namnamed
ed
REAL
EAL val ue)
ue) attribute. Currently the only
attribute supported is
HANDLEMODIFY which
determines when the text
MODIFIED events are fired.
It has values:
0 MODIFIED events off 
(default).
1 Generate MODIFIED event
for first user modification.
2 Generate MODIFIED event
for all user modifications.

Table 2: 123.
123. TEXT O
Object
bject M
Methods
ethods

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.
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 - - +- - <f gpos > - - - - - - - - - - - - - |
+- - CORE - - - - - - - - - - - - - - - - | Cor e managed gadget
+- - <f gt ag agw> - - - - - - - - - - - - |
+- - <f ganc h> - - - - - - - - - - - - |
+- - <f gd g doc k> - - - - - - - - - - - - |
+- - TOOL TI P t ex ext - - - - - - - - |
+- - CAL L bac k t e exxt - - - - - - - *
| . - - - - - - - - - <- - - - - - - - - .
| / |
‘ - - * - - WI Dt h i nt e egger - - - - |
+- - SCRol l i nt eg eger - - - |
+- - - NOEc ho- - - - - - - - - - - - *
|
‘ - - I S - - +- - STRI N NGG --.
+- - REAL - - - - |
+- - BOOLEA LEAN - |
‘ - - wor d - - - - +- FORMAT gvar nm nm - .
‘- ---- ----- ----- --+
+-- TOOL TI P t ex
ext - .
‘----------------‘-->

Figure
Figure 2:65
2:65.. Synt
Syntax
ax G
Graph
raph --:: Set
Setting
ting Up a TEXT Objec
Objectt

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.

2:187 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

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.69 TEXTPAN
ANE
EGGa
adge
dgett

Members

Nam e Ty p e Pu r p o s e

Val ARRAY OF Get or set the contents of the

STRING text pane.
Get/Set
Count REAL Get Get the number of lines of 
Only text in the gadget.

Table 2: 124. TEXT

TEXTP
PANE Gadg
Gadget
et Membe
Members
rs
Methods

Nam e Res u l t Pu r p o s e

Ful l Name( ) STRING Get the full gadget name,

e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get owning form.
Cl ear ( ) NO RESUL
RESULT
T Clear
Clear all
all lin
lines
es fr
from
om the gadg
gadget
et
Li ne( REAL
EAL ) STRING Get the text of given line
Se
Sett Li ne
ne(( REAL,
EAL, ST
STR
RI NG) NO RESUL
RESULT
T Rep
Replac
lace
e speci
specifie
fied
d line num
number
ber by
STRING.
Cur Pos(
Pos( ) ARRAY[2] Get cursor position (line,
OF REAL character).
Se
Sett Cur Pos(
Pos( REAL[ 2] ) NO RESUL
RESULT
T Set cursor
cursor positi
position
on (line,
(line,
character).
Se
Sett Cur Pos( REAL,
EAL, REAL)
EAL) NO RESUL
RESULT
T Set cursor
cursor positi
position
on (line,
(line,
character).
Set
Set Edi
Edi t ab
abll e( BOOLEAN
LEAN) NO RESU
RESUL
LT Set edit
edit ssta
tatus
tus..
Set Popup( MENU
ENU) NO RESUL
RESULT
T Lin
Links
ks the given men
menu
u with the
gadget as a popup.
 RemoveP
ov ePop
opup(
up( MENU)
ENU) NO RESUL
RESULT from
Removes
Remothe
vesgadget.
the given
given popup
popup menu
menu

2:188 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked popup
menu for the gadget.
Set Tool
Tool Ti p( STRI
TRI NG) NO RESUL
RESULT Sets
Sets or edits
edits the text of the
TOOLTIP.
Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refres
reshes
hes the dis
displa
playy of the
gadget.
Shown( ) BOOL
BOOLEA
EAN
N Ge
Gett ‘s
‘sho
hown
wn’’ st
stat
atus
us..
 Type( ) STRING Get th
the g
ga
adget ty
type a
ass a string.
Backgr ound(
ound( ) 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
colourname. In this with
caseaanknown
error 
is raised..
Table 2: 125. TXTP
TXTPANE
ANE Gad
Gadget
get Meth
Methods
ods

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 TEXTPANE to be either PML-controlled, or core-code controlled using
the gadget qualifier attribute control type, with values ‘PML” or “CORE”.
The Textpane gadget definition has a new keyword 'FixChars' to force the use of a fixed
width font. This allows the text pane to be used to show simple reports laid out using the
space character.
The chosen font is Courier New   (TrueType), because it has a reasonable selection of 
character glyphs (nowhere near as extensive as the default variable width font  Ar ial
Unicode MS).
 2:189 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

. - - - - - - - - <- - - - - - - - .
/ |
>- - TEXTPane gname - - +- - ta
aggt e xt
xt - - - - - - - - - |
+- - <f ganc h> - - - - - - - |
+- - <f gdoc k> - - - - - - - |
+- - <f gp
g pos > - - - - - - - - |
+- - FI XCHARS - - - - - - - |
+- - CORE - - - - - - - - - - - * Cor e managed gadget
‘ -- <vs hap> - - - >

Figure
Figure 2:66. Syntax
Syntax Gr
Graph
aph -: S
Setting
etting U
Up
p a TEXT
TEXTP
PANE O
Object
bject

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

2.5.70 TOGGLE Gadg

dgeet

Member 

Nam e Ty p e Pu r p o s e

Val BOOLEAN Toggles value between

Get/Set TRUE and FALSE.

Methods

Nam e Res u l t Pu r p o s e

AddPi
ddPi xmap(
ap( ST
STR
RI NG f i l e1,
e1, ST
STR
RI NG NO RESUL
RESULT
T Adds pix
pixmap
mapss to be used for 
f i l e2, STRI NG f i l e3 ) the unselected, selected and

fAiddPi
dd
l Pi
e2xm
) ap(
ap( ST
STR
RI NG f i l e1,
e1, ST
STR
RI NG inactive states. The last two
are optional.
AddPi
ddPi xmap(
ap( ST
STR
RI NG f i l e )
Ful l Name( ) STRING Get the full gadget name,
e.g.'!!Form.gadget'.
Name( ) STRING Get the gadget's name, e.g.
'gadget'.
Owner ( ) FORM Get owning form.
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT
T Moves
Moves keyboa
keyboard
rd fo
focus
cus to
to this
this
gadget.
Set Popup( MENU
ENU) NO RESUL
RESULT
T Lin
Links
ks the give
given
n menu with
the gadget as a popup.
RemoveP
ov ePop
opup(
up( MENU)
ENU) NO RESUL
RESULT
T Rem
Remove
ovess the given popup
popup
 menu from the gadget.

2:190 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Get Pi ckedPop
ckedPopup
up(( ) MENU Returns the last picked
popup menu for the gadget.
Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refresh
reshes
es the displ
display
ay of the
gadget.
Shown( ) BOOL
BOOLEA
EAN
N Get ‘s
‘sho
how
wn’ st
stat
atus
us..
Set Tool Ti p STRING Sets or edits the text of the
TOOLTIP.
 Type( ) STRING Get the gadget type as a
string.
Backgr ound
ound(( ) STRING Get Ba
Background Co
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: 126. TOG

TOGGLE
GLE Obj
Object
ect Me
Methods
thods

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”.

. - - - - - - - <-
<- - - - - - - - - - - - .
/ |
>- TOGGL E gname - +- <f gt agw> - - - - - - - - - - - |
+- PI XMAP <vs ha hap> - - - - - |
+- CAL L bac k t e exxt —- - - - - |
+- <f g gppos > - - - - - - - - - - - - |
+- <f ganc h> - - - - - - - - - - - |
+- <f gdoc k> - - - - - - - - - - - |
+- TOOL TI P t e exxt - - - - - - - |
+- CORE - - - - - - - - - - - - - - - * Cor e managed gadget
+- STATES t e exxt 1 t ex e xt 2 - .
‘ - - - - - - - - - - - - - - - - - - - - - - +- TOOL TI P t ex
ext - .
‘----------------‘--->

Figure
Figure 2:67. Synt
Syntax
ax G
Graph
raph --:: Sett
Setting
ing Up a TO
TOGGLE
GGLE Objec
Objectt
 where text1 corresponds to the OFF setting and text2 corresponds to the ON setting.

2:191 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

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 recommende
recommended d that when you
you define
define the gadget
gadget you set ititss size to encompa
encompass
ss the
largest pixmap which you will later add. Failure to do this may give rise to unexpected
behaviour.
2. Historically
Historically you
you could add
add a third pixmap
pixmap which
which was used whe
when n the gadge
gadgett was de-
activated. This practice is no longer necessary as the gadget pixmapped is
automatically greyed-out on de-activation.

2.5.71 UNDOAB
ABLE
LE Obje
bject
This object allows you to add functionality to the undo and redo stacks.

Methods

Nam e Res u l t Pu r p o s e

descr i pt i on( STRI NG) NO RESUL

RESULT Add
Addss descri
descripti
ption
on text
text to the
undoable

add(
add( ) NO RESUL
RESULT Marks
Marks the databas
databasee with
with the
description text and adds this
undoable to the undo stack

endu
endund
ndoa
oabl
bl e( ) NO RESUL
RESULT
T Marks
Marks the data
database
base a
agai
gain
n at the
end of the change.
undo
undoA
Act i on ( ST
STR
RI NG) NO RESUL
RESULT Sp
Speci
ecify
fy a comman
command d to be
executed when this undoable is
 taken off the undo stack

2:192 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

r edoA
edoAct
ct i on(
on( STRI
TRI NG) NO RESUL
RESULT Sp
Specif
ecifyy a comman
command
d to execute
execute
when this undoable is taken off 
the redo stack.
cl earAct
arAct i on(
on( STRI
TRI NG) NO RESUL
RESULT Sp
Specif
ecifyy a comman
command
d to execute
execute
when this undoable  is cleared
without any associated undo/
redo being performed.

Table 2: 127. PMLU

PMLUndoabl
ndoable
e Object M
Methods
ethods

Command
To use this object, first create an undoable object, and define the undoAct on( ) ,
oAct i on(
r edoAct i on( )  and c l ear Ac t i on( ) methods to define the execution strings.
Call the method add(
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 endu
endund
ndoa
oabl
bl e( )
to mark the end of the changes.

2.5.72 UNIT Ob je
j ec t

Member 

Nam e Res u l t Pu r p o s e

Constructors

Uni t ( )
Uni t ( REAL) U N IT Creates a UNIT of which the
value of REAL is a (valid) enum
value, or is a negative
(compound) unit.
Uni t ( ST
STR
RI NG) U N IT Creates a UNIT with String
equivalent to (in order)
Description, Name,
ComponentName, or Hashcode.

Table 2: 128.
128. UNIT O
Object
bject Mem
Members
bers

Methods

Nam e Res u l t Pu r p o s e

Name
Name String Method
Method s

Des c
crr i pt i on( ) STRING Long de
descriptio
tion o
off un
unit, ve
very o
offten
 St r i ng( ) same as Name()

2:193 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Res u l t Pu r p o s e

Name( ) STRING Unit na

name us used a
ass q
qu
ualifier fo
for 
solitary units
Shorr t Name( )
Sho STRING Sho
Short name used as qualifier for 
component units. Very often same
as Name()
Hashcode( ) STRING H a s h c o d e o f u n i t. I f a c o m p o u n d
Pt ype
ype( ) unit returns 'COMPOUND', if 
derived from component standard
units (e.g. Area units are Distance
squared) returns 'DRVD'.

General Queries

Enum( ) REAL Unique integer ID for this unit.

Positive if standard unit.
Negative if compound unit.
Factor() REAL Conversion factor to database
units.
Uni t Qual i f i er ( ) STRING Unit qual
ualifier of current units.
Di mensi
ensi on
on(( ) MEAS
MEASUR
URE
E Dime
Dimens
nsiion of unit
unit..
I sSt
sSt andar d( ) BOOL
BOOLEA
EAN
N TR
TRUE
UE ifif a st
stan
anda
dard
rd,, si
sing
ngle
le,, un
unit
it..
FALSE if a compound unit (e.g.
kg/m3, m2)
I s Nul l ( ) BOOL
BOOLEA
EAN
N TR
TRUE
UE if unit
unitss a
are
re NON
ONE.
E.
Al l Di mensi ons(
ons( ) ARRAY of  Set of all standard dimensions.
MEASURES
Al l Uni t s ( ) ARRAY of  Set of all named, standard Units.
UNITS
I s I mper i al ( ) BOOL
BOOLEA
EAN
N TR
TRUE
UE ifif an excl
exclus
usiv
ivel
elyy iimp
mper
eria
iall
unit (e.g. inch, lb) or a non specific
unit (e.g. second, ohm, degree).
I s Met r i c ( ) BOOL
BOOLEA
EAN
N TR
TRUE
UE ifif an exc
exclu
lusi
sive
vely
ly m
met
etri
ricc unit
unit
(e.g. mm, kg) or a non specific unit
used in metric situations.

Note: Derived units (which are units derived from current units of component dimensions
such as area units derived from current distance) and numeric units (no conversion
or unit qualifiers) have empty strings for name, description and qualifier. However 
their hash codes are DRVD and NUMB so they can be created using a form as
object unit ('DRVD'). Current units can be set to this using measure.setUnits.
Additionally numeric current units can be set using measure.numeric().
 2:194 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.73 USER Ob je
jec t

Member 

Nam e Res u l t Pu r p o s e

Nam
Name STRING The name of the User, up to
32 characters.
Descri pt i on STRING User’s
r’s description, u
up
p to
to 1
12
20
characters.
Access STRING User’s
r’s access rights (FREE,
GENERAL, RESTRICTED).
Ref no STRING STRING cco
ontaining
Database reference number.

Table 2: 129.
129. USER Object
Object Mem
Members
bers

Method

Nam e Res u l t Pu r p o s e

 TeamLi st ( ) ARRAY OF List of TEAMs including this

USERS USER.
Wor ki ngLi st ( ) ARRAY OF List of working extract DBS
DB owned by a User.
OBJECTS
Pa
Pass
ss wor d( ) STRING N o v al ue .
USER( DBREF
BREF)) USER Returns a USER o b j e c t,
given a DBREF.

USER(
SER( STRI NG) USER Returna
given s name
a USor
ERreference
o b j e c t,
number.

Table 2: 130.
130. USER Object
Object Meth
Methods
ods

These methods may be used in the following ways:

! D = OBJ ECT USER( ! ! CE)

! D = OBJ ECT 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 element’s name.

2:195 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

These methods should assist performance

performa nce 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.74 VERIFY
VERIFY object is used directly to verify that the executing user is on a list of approved users
and is running on an approved host computer, and is running within a given time period. If 
the condition is not met the command script terminates immediately with a "Verification
error".

Methods

Nam e Res u l t Pu r p o s e

Ver i f y( ) PMLUSERL
PMLUSERLOGI
OGIN
N Constr
Construct
uct an
an instanc
instance
e of thi
thiss
object
Af t er ( DATETI
TETI ME) NO RE
RESULT Verify af
after th
the ssp
p e c i fi e d d
da
a te

Bef or e( DATETI
TETI ME) NO RE
RESULT Verify be
before th
the ssp
pecified d
da
a te

Host
os t name( STRI NG) NO RESULT Verify current c o m p u te r  
hostname matches single
hostname passed as STRING
Hos
ostt name( ARRA
ARRAY)
Y) NO RESULT Verify current c o m p u te r  
hostname matches one of a set
of hostnames passed as ARRAY
of STRING
Wi nUs
nUs er ( STRI
STRI NG) NO RESULT Verify current Windows user  

matchesas STRING
passed single username

Wi nUs
nUs er ( ARRAY) NO RESULT Verify current Windows user  
matches one of a set of 
usernames passed as ARRAY of 
STRING

Table 2: 131.
131. VERI
VERIFY
FY Obj
Object
ect Me
Method
thod

2.5.75 Vi e
ew
wFFii nd
nd e
err  
The ViewFinder object is to allow the Draft PML user to create a frame in the 3d view which
represents the view frame in the 2d view. Once drawn, the frame can be moved, rotated,
change its representation (but not its size). By manipulating the frame in the 3d view, the
user can modify the view parameters in the current drawing.
 2:196 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Set-up
Set-up Methods
Methods

Nam e Pu r p o s e

. vi ewFi nder ( DBREF) Creates a viewfinder object based on the parameters of the
Draft View. The input argument must be the dbref of a valid
View .
. vi ew( DBREF) Sets the associated View object using the DBREF which
must be a valid view

Methods

Nam e Res u l t Pu r p o s e

. r edr aw( ) No Result

ult Redraws th
the bo
box u
ussing cur
currrent st
state
of View parameters
. updat e3d( ) No Resu
esult Regene
generrates ffrrame an
and 3
3d
d m
mo
odel
view from the 2d view

. col
col our ( REAL) No Result Changes colour to
to the
the PDMS co
colour 
number specified
. t r ansl
ansl ucency(
ucency( BOOLEAN
LEAN) No Result Swi
Switches translucency on or off 

. al i gn( ) No Resul
esultt Alig
Aligns
ns the
the vi
view
ewfi
find
nder
er fram
frame
e with
with the
the
3d view direction
. l ock( BOOLEAN
LEAN) No Result Locks/unlock
ocks the frame so it
cannot be moved
. dynami c( BOOLEAN) No Result If true, updat e des i gn will
automatically occur whenever the
frame is moved
. hi de( ) No Result Makes the frame invisible

. show
show( ) No Result Makes the frame visible. Als
Also
expands the clipping planes to make
sure they include the frame.

Query Methods

Nam e Res u l t Pu r p o s e

. val i d( ) BOO
BOOLEAN Is the viewfinder valid. This will be
true if it was created with a valid
View, otherwise false
. vi ew( ) DBREF Returns the dbref of the associated
view object
. pos i t i on( ) POS
POSITION
ION Returns the position of the centre of 
the viewfinder frame.
 . di r e
ecc t i on( ) DI
DIRE
RECT
CTIO
ION
N Retu
Return
rnss tthe
he dire
direct
ctio
ion
n o
off the
the View
View
associated with the viewfinder 

2:197 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

. s i z e( ) ARRAY of  Returns the size of the viewfinder 

REAL frame ( as Xnnn Ynnn)
. dynam
ynami c( ) BOOLEAN Returns true if in dynamic mode

Table 2: 132. View

ViewFinde
Finderr Object M
Method
ethods
s

2.5.76
.76 VIEW Gadge
dget:
t: AL
ALPPHA V
Vie
iews
ws

Members

Nam e Ty p e Pu r p o s e

Channel STRING Get or set the assigned

Get/Set channel.

Table 2: 133. VIEW AL

ALPHA
PHA Object
Object Mem
Members
bers

Methods

Nam e Res u l t Pu r p o s e

Cl ear ( ) NO RESUL
RESULT
T Cle
Clear
ar all lines
lines fro
from
m the Alpha
Alpha
TTY window.
Ref r esh NO RESUL
RESULT
T Ref
Refresh
reshes
es the display
display of the
gadget.
Set Fo
Focu
cus(
s( ) NO RESUL
RESULT Set the key keyboa
board
rd foc
focus
us
immediately to this Alpha
gadget.
r emoveReq
oveReque
uest
st s( ) NO RESUL
RESULT Del
Delete
etess the ‘reques
‘requests’
ts’ cha
channe
nnell
from the alpha view gadget,

and dissociates
current it from theif 
Requests IO-channel
necessary.
Backgr ound(
ound( ) 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: 134. VIEW A

ALPHA
LPHA O
Object
bject M
Methods
ethods
 2:198 12 Series

 Soft ware Customi sation Reference

Reference Manual
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.

. - - - - - - - - - - - - - - - - - - - - - - - - - <- - - - - - - - - - - - - - - - - - - - - - - - - .
/ |
(A
AL
L Pha) - - +- <vs hap> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - . |
+- CHANNEL - +- COMMANDS - - - - - - - - - - - - - - - - - - - - - - - | |
| ‘ - REQUESTS - - - - - - - - - - - - - - - - - - - - - - - ‘ - NL - *
‘ - - EXI T - - >

Figure
Figure 2:68. Syntax
Syntax Gr
Graph
aph -22
-22:: Setti
Setting
ng Up an ALPHA
ALPHA V
VIEW
IEW O
Object
bject

2.5.77
.77 VIEW Gadge
dget:
t: AR
ARE
EA V
Vie
iew
w

Members

Nam e Ty p e Pu r p o s e

L i mi t s REAL Get or set limits box

ARRAY[4] [x1,y1,x2,y2].
Get/Set
Bor de
derr s BOOLEAN Get or set borders ON (TRUE)
Get/Set or OFF (FALSE).
Backgr ound REAL Get/ Get or set background Colour 
Set Number 
Backgr ound STRING Set Set background Colour Name.
Only
Cont
ont ent
ent s REAL Get or set User contents ID.
ARRAY[2]
Get/Set
Def cal
cal l STRING Get or set default interaction
Get/Set callback.
Hei ght REAL Get Get view height.
Only
Hi ghl i ght REAL Get/ Get or set highlight Colour 
Set Number.
Hi ghl i ght STRING Set Set highlight Colour Name
Only
Pr ompt GADGET Get or set User Prompt
Get/Set PARAGRAPH gadget.
Subt
Subt ype STRING Get Get subtype of graphic view.
Only
Wi dt h REAL Get Get view width.
Only
 Table 2: 135. VIEW AR
AREA
EA Object
Object Met
Methods
hods

2:199 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e

Backgr ound
ound(( ) STRING Returns tth
he hi
highlight cco
olour 
as a name string.
Cl ear ( ) NO RESUL
RESULT Clear
Clear VIEW conten
contents
ts
Hi ghl i ght ( ) STRING Returns tth
he hi
highlight cco
olour 
as a name string.
Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refresh
reshes
es the displ
display
ay of the
gadget
Rest or eVi
eVi ew( REAL
EAL s t or eNum
eNumber
ber ) NO RESUL
RESULT Restore
Restoress the saved VIEW
with the given store number.
num ber.
SaveVii ew( REAL
SaveV EAL s t or eNum
eNumber ) NO RESUL
RESULT
T Save
Savess the cur
current
rent VIEW
VIEW.. The
number must be in the range
1 to 4.
Set Si ze( REAL wi dt h, REAL
EAL hei
hei ght
ght ) NO RESUL
RESULT
T Set VIE
VIEWW ssiz
ize.
e.

Table 2: 136. VIEW AR

AREA
EA Object
Object Met
Methods
hods

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

. - - - - - - - - - - - - - - - - - - - - - - - - - <- - - - - - - - - - - - - - - - - - - - - - - - .
/ |
(A
AR
REa) - - +- <vs hap> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - . |
+- PUT - <s gi d> d> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | |
+- LI Mi Mi t s <uval > <uval > - TO - <uval > <uval > - | |
+- SETCol o ouur - <c ol n noo> - - - - - - - - - - - - - - - - - - - - - - - | |
+- SETHi ghl i ght - <c ol no> - - - - - - - - - - - - - - - - - - - - ‘ - NL - |
+- <c ur so
s or > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- <bor de
der > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - <pml > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
‘ - - EXI T - - >

Figure
Figure 2:69. Synt
Syntax
ax G
Graph
raph --:: Sett
Setting
ing U
Up
p an AR
AREA
EA VI
VIEW
EW Ob
Object
ject

DRAFT where <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.
 2:200 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

And <cursor> is the syntax for selecting the cursor type, as follows:
>- - CURSor t ype - - - +- - POI NTER - - - - .
+- - NOCURSOR - - - |

+
+-- -- P
PII C
CK
KPL
-U- -S- -- -- -- ||

‘ - - CROSSHAI R - - ‘ - - >

Figure
Figure 2:70. Synt
Syntax
ax G
Graph
raph --:: Sett
Setting
ing U
Up
p the C
Cursor
ursor Type

<border> allows control of zooming and panning:

>- - - BORDer s - - +- - ON - - .
‘ - - OFF - ‘ - - - >

Figure
Figure 2:7
2:71.
1. Synt
Syntax
ax G
Graph
raph -: S
Setting
etting Up tthe
he Bo
Border 
rder 

2.5.78
.78 VIEW Gadge
dget:
t: P
PLO
LOT
T View
iew

Members

Nam e Ty p e Pu r p o s e
Backgr ound
ound REAL Get/ Get or set background
Set Colour Number.
Backgr ound
ound STRING Set Set background Colour 
Only Name.
Bor der
der s BOOLEAN Get or set borders ON
Get/Set (TRUE) or OFF (FALSE).
Cont
ont ent
ent s REAL Get or set User Contents ID.
ARRAY[2]
Get/Set
Def ca
call l STRING Get or set default interaction
Get/Set callback.
Hei ght REAL Get Get view height.
Only
Hi ghl i ght REAL Get/ Get or set highlight Colour 
Set Number.
Hi ghl i ght STRING Set Set highlight Colour Name.
Only
Pr ompt GADGET Get or set User Prompt
Get/Set PARAGRAPH gadget.
Subt
Subt ype STRING Get Get subtype of graphic view.
Only
Wi dt h REAL Get Get view width.
 Only

Table 2: 137. VIEW P

PLOT
LOT Obj
Object
ect Me
Members
mbers

2:201 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Methods

Nam e Res u l t Pu r p o s e
Add( STRI
STRI NG) NO RESUL
RESULT Add p plot
lot ffile
ile w
with
ith n
name
ame g
give
iven
n
by STRING. Replaces given
plot file if any.
Backgr ound
ound(( ) STRING Returns the background
colour as a name STRING
STRING..
Cl ear ( ) NO RESUL
RESULT
T Cle
Clear
ar gadg
gadget
et cconte
ontents
nts
Hi ghl i ght ( ) STRING Returns tth
he hi
highlight cco
olour 
as a name STRING.
Ref r esh
sh(( ) NO RESUL
RESULT
T Ref
Refresh
reshes
es the displ
display
ay of the
gadget
Set Si ze( REAL wi dt h, REAL
EAL hei
hei ght
ght ) NO RESUL
RESULT
T Set vi
view
ew ssiz
ize.
e.

Table 2: 138. VIEW P

PLOT
LOT Obj
Object
ect Me
Methods
thods

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

. - - - - - - - - - - - - - - - - - - - - - - - - - <- - - - - - - - - - - - - - - - - - - - - - - - .
/ |
(P
PL
L OT) - - +- <vs hap> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - . |
+- ADD - pl o ott _ f i l en
ename - - - - - - - - - - - - - - - - - - - - - - - | |
+- CL ear - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | |
+- SETCol o ouur - <c ol n noo> - - - - - - - - - - - - - - - - - - - - - - - | |
+- SETHi ghl i ght - <c ol no> - - - - - - - - - - - - - - - - - - - - ‘ - NL - |
+- <c ur sos or > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- <bor de
der > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - <pml > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *
‘ - - EXI T - - >

Figure
Figure 2:72. Synt
Syntax
ax Gr
Graph
aph -: Setti
Setting
ng Up a PLOT VIEW Objec
Objectt

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
 2:202 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.79 VIEW G
Ga
adge
dget:
t: VO
VOLU
LUM
ME V
Vie
iews
ws

Members

Nam e Ty p e Pu r p o s e

Backgr ound
ound REAL Get/ Get or set Background
Set Colour Number 
Backgr ound
ound STRING Set Set Background Colour 
Only Name.
Cont
ont ent
ent s REAL Get or set User Contents ID.
ARRAY[2]
Get/Set
Def ca
call l STRING Get or set default interaction
Get/Set callback.
Hei ght REAL Get Get View Height.
Only
Hi ghl i ght REAL Get/ Get or set Highlight Colour 
Set Number.
Hi ghl i ght STRING Set Set Highlight Colour Name.
Only
Pr ompt GADGET Get or Set User Prompt
Get/Set paragraph gadget.
Subt
Subt ype STRING Get Get Subtype of graphic
gra phic view.
Only
Wi dt h REAL Get Get View Width.
Only
Bor der
der s BOOLEAN Get or set Borders ON
Get/Set (TRUE) or OFF (FALSE).
Di r e ct
ct i on REAL Direction vector [dE,dN,dU].
ARRAY[3]
Get/Set
EyeMode BOOLEAN TRUE for Eyemode FALSE
Get/Set for Modelmode.
L i mi t s REAL Limits box
ARRAY[6] [E1,E2,N1,N2,U1,U2].
Get/Set
Mous emod
odee STRING 'ZOOM', 'PAN', 'ROTATE',
Get/Set WALK'.
Pr oj ec t i on STRING ‘PERSPECTIVE’ or 
 Get/Set ‘PARALLEL’.

2:203 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

Nam e Ty p e Pu r p o s e

Radi
adi us REAL Get/ View Radius distance >0.
Set
Range REAL Get/ Range distance >0.
Set
Ref r esh NO RESUL
RESULT
T Ref
Refresh
reshes
es the displ
display
ay of the
gadget.
Rest or eVi ew REAL Get/ Restores view saved as
Set given view number.
Sa
SaveV
veVii ew REAL Get/ Saves view as given view
Set number, in the range 1 to 4.
Shaded BOOLEAN TRUE for shaded FALSE for 
Get/Set wireline.
St ep REAL Get/ Step size >0.
Set
 Thr ough REAL Through point [E,N,U].
ARRAY[3]
Get/Set
Wal kThr ough
ough BOOLEAN TRUE for Walkthrough
Get/Set (equivalent to Eyemode).
Lab
Label St yl e STRING Set by specifying ‘ENU’ or 
Get/Set ‘XYZ’. Default is ‘ENU’.

Table 2: 139. VIEW VO

VOLUM
LUME
E Memb
Members
ers

Methods

Nam e Res u l t Pu r p o s e
Backgr ound(
ound( ) STRING Returns the BACKGROUND
colour as a name string.
Hi ghl i ght ( ) STRING Returns the HIGHLIGHT
colour as a name string.
Set Si ze( REAL wi dt h, REAL
EAL hei
hei ght
ght ) NO RESUL
RESULT
T Set vi
view
ew ssiz
ize.
e.
Rest or eVi
eVi ew( REAL
EAL s t or eNum
eNumber
ber ) NO RESUL
RESULT
T Res
Restore
toress view
view saved
saved as
given view number.
SaveVii ew( REAL
SaveV EAL s t or eNum
eNumber ) NO RESUL
RESULT Saves
Saves view as given view
view
number.

Table 2: 140. VOLU

VOLUME
ME VIEW Object
Object Me
Methods
thods
 2:204 12 Series

 Soft ware Customi sation Reference

Reference Manual
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.

( VO
VOL ume) - - +-
+- - L Ook - - +- - <di r > - - - - - - - - - - - - - - - - - - - - - .
| | - - THRough- - - . |
| | - - FROM - - - - - | |
| ‘ - - TOWar ds - - +- - <pos > - - - - . |
| | - - <gi d> - - - - | |
| ‘ - - I D @ NL - - ‘ - - |
+- - I SOmet r i c - - +- - value - - . |
| ‘-----------‘-------------|
+- - PL AN - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
+- - EL EVat i on - - ( on one of N/ S/ E/ W/ X/ Y) - - - - |
+- - CL I Ppi ng - - - - - +- - ON - - . |
| ‘ - - OFF - ‘ - - - - - - - - - - - - - - |
+- - CAPpi ng - - - - - - +- - ON - - . |
| ‘ - - OFF - ‘ - - - - - - - - - - - - - - |
+- - PERSPec t i ve - - +- - ON - - . |
| ‘ - - OFF - ‘ - - - - - - - - - - - - - - |
+- - WAL Kt hr ough - - +- - ON - - . |
| ‘ - - OFF - ‘ - - - - - - - - - - - - - - |
+- - RADi us - - - val
value ue ------
--------- ---------------------------- -|
+- - STEP - - - - - val
value ue ------
--------- ---------------------------- -|
‘ - - RANGE - - - - val
value
ue ------
---------
------
------
------
-------‘ - - - >
----

Figure
Figure 2:73. Syntax
Syntax Gr
Graph
aph -: S
Setting
etting U
Up
p a VOLU
VOLUME
ME VI
VIEW
EW Obj
Object
ect

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.

OFF.
View direction:PLAN or LOOK DOWN.
Limits: AUTO (set to current view limits).
 2:205 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Summary of Objects, Members and Methods

2.5.80 XYPos
ositi
ition
on Obje
bject

Members

Nam e Ty p e Pu r p o s e

X REAL X component of 2D POSITION.

Get/Set
 Y REAL Y component of 2D POSITION.
Get/Set

Table 2: 141. XYPO

XYPOSITIO
SITION
N Object Me
Members
mbers

Methods

Nam e Res u l t Pu r p o s e

XYposi t i on( ) XYPOSITI

XYPOSITION
ON Creates
Creates an XYPO
XYPOSITI
SITION
ON at
the given coordinates.
St r i ng( ) STRING Returns a XY
XYPOSITION as a
STRING.

Table 2: 142. XYPO

XYPOSITIO
SITION
N Objec
Objectt Method
Methods
s
 2:206 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

3 Ev en t Dr i v en Gr ap h i c s

Event Driven Graphics (EDG) describes the AppWare implemented EDG interface, which is
used as the interface between most applications/utilities requiring graphics interaction and
the graphic canvas.
It describes the Public  methods and members of the objects used within the system and
how they interact with each other. Also it describes how the AppWare
A ppWare developer can use the
system, write their own handlers, etc. etc.
The EDG interface has been developed to allow a common interface for the AppWare
developer to setup the graphic canvas in an EDG mode, which is relatively simple and
easily extendible. This will allow the developer to concentrate on the development of their 
own application without the need to know the underlying mechanism (core implementation)
of the EDG interaction handlers and system.
The system handles all the underlying maintenance of the current events stacked e.g.
associated forms, initialisation sequences, close sequences, etc.
The current implementation of the system has mainly been developed for interaction with
the 3D graphic views in the DESIGN module. However, the interface can be used with any
of the modules that use the same executable and the standard 3D graphic views.
Note: EDG does not form part of the formal definition of PDMS and is subject to change.
There is no AVEVA commitment to keep or maintain this interface in subsequent
versions of PDMS.

3.1 Ov er v i ew
The EDG interface has been developed using the basic core functionality available in the
Forms and Menus system.
Even though the underlying core commands are very powerful allowing the developer great
flexibility and control of graphical picking, they only relate to a single view gadget, and so
would require the developer to write their own code to encapsulate the commands and
maintain the graphical views the event is to be applied to.

3.2 Pu r p o s e
What the EDG system does, is to control the event handlers in a more global sense, so that
the same pick sequence is applied to all current graphical design views.
It also handles the stacking of EDG events, allowing the user to temporary suspend one
 event with another, then return to the previous,
p revious, without the lost of data, etc.

3:1 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

3.3 Sc o p e
The current implementation has been developed mainly for the DESIGN module using the
standard 3D Graphical Design views. The system can be used in any of the modules using
the "des" executable and the standard 3D Graphical Design views, e.g. IsoSpool,
PARAGON, etc. The current implementation it is not available in DRAFT.
Only the interfaces described can be classed as being supported in any form or manner.

3.4 Def i n i t i o n s
The following are abbreviations, acronyms and "buzz words" that may be used within this
document:
• EDG - Event Driven Graphics, this allow the application writer supply their own method
for interpreting the pick from the view gadget.
• Event Handlers  - these are core defined handler that are used define the interaction
with the view gadget.
• Geometry Calculator   - set of core functions, objects or methods used to derive
positional, angular, linear or directional data.
• GUI - Graphical User Interface, the forms and menus the user interacts with.
• Super Applications   - these are applications/utilities, that are used for creating
elements, (sections, panels, etc.) or moving items, etc.
• Sub Application s - these are applications/utilities, used to derived data that may be
required when using the positioning tool kit, measure, construction aids, etc.
• edgCntrl  - this is the global control object for the EDG system, the global variable for 
the system within PDMS is !!edgCntrl .
• Packet  - this is an object that defines a complete definition of an application/utility that
is to be placed into the event system.
• PickPacket  - this is a definition of the pick sequence and types that are used by an
application packet.
• PickType  - this is a definition of how an actual pick is interpreted, e.g. if a database
element is picked, is it decomposed into a basic graphical entity, point, line, arc or 
plane or is it returned as a pointer to the database element.
• Pick  - this is the definition of the pick on the graphical canvas, it is a stylised version of 
the core event handlers.
• Public Members & Methods   - these are the members and the methods that the
AppWare developer should use when defining objects within the system.

3.5 Tar g et Us er s
EDG is intended for any user who wishes to write an application/utility that requires
interaction with the graphics design canvas (as supplied with the standard product).
It is assumed that the user wanting to use the EDG interface is familiar with both the
concepts of an Object Orientated language and PML II.

3.6 Su p er s
seed ed Fu
Fu n c t i o n al i t y
 The concept of event driven graphics is intended to replace the old suspend macro and pick
commands, i.e. the @ operator used with ID, IDP and IDPL and VAR <varid> PICK used to

3:2 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

return the picked element and pick vector. Bring the PML language up to dat
datee with other OO
languages and GUI tool kits.
However, the old suspend macro command are still available, but should not be used for 

any new development, as it is intended to deprecate these commands at some later version.

3.7 Co m p o n en ts
There are several components that the EDG system uses; each component of the system
usually has an equivalent object definition. Its members and methods, defining the data
required and actions that are pertinent to that component.
Several of components within the system can be loosely defined as being a type of object
factory; these allow new components to be added into the system, without the need to
modify the base EDG system objects.
There are two main types of components that the system uses, these are:

3.7.1 Mai n C
Co
o m p o n en ts

Main
used components
in conjunctionare used
with theto define and control the actual EDG system and should only be
system.
The following table lists the main component names and gives a basic description of their 
function within the system:

Ob j e c t Des c r i p t i o n

edgCntrl Controls and contains all currently active events that are
registered in the system.
edgPacket Defines a application/utility that requires graphical picks.
edgPickPacket Defines the pick sequences and types of pick a packet
requires.
edgPickType Defines how a pick is to be interpreted.

edgP i c k Defines the basic graphic pick, cursor style, filter, etc.
edgPosCntrl Object for controlling all graphical position picks settings and
active working planes/grids.

There are several other components that the system uses. However, these are to be
classed as being private to the EDG system, therefore
theref ore the AppWare developer should never 
access the directory.

3.7.2 Sec o
on
ndda
ar y Co m
mp
poon
n en t s
Secondary components are used by the EDG system to derive information and in many
cases can be used independently of the system.
 3:3 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

The following table lists the secondary components and object that are used by the system:

Ob j e c t Des c r i p t i o n

edgTypes Object factory for defined "edg" database type object, the
interpreting how a database element is decomposed into
their basic geometrical type, point, line, arc or plane.
appMathLib Object factory for gr
graphical application mathematical objects,
used to derive information about basic geometrical objects,
i.e. proportion, distance, etc.
edgPickData Return data from a graphical pick.
edgPositionData A processed version of the edgPickData  object that is used
to extract position and basic geometrical data from a picked
element.

The system access many more components, either directly or indirectly, the above shows
only those that are extensively used in the interpretation of data.

3.8 Co n c e p t s
There are several concepts that need to be understood by the AppWare developer, to
understand why the system is written the way it has and how best to use the system.

3.8.1 Ev en t Dr iv
iv e
en
n G
Grr a
ap
p h ic
ic s
Unlike the old style of graphical picking used by PDMS, which suspended the running of a
macro until a graphical element had
ha d been picked. EDG is a state in which the graphical view
gadget is put into, which defines criteria about how and what can be picked and how the
picked item is interpreted. When an item is picked, an action is carried out, i.e. a macro,
function or method is executed, similar to the callback on other gadgets types. What does
not happen, as with the old macro suspended mechanism, is that all other forms and
gadgets within the application, are still active.

What
system, thisthe
means
actiontocarried
the AppWare
out whendeveloper is that when
a pick happens, writing
can only a utility thatonce
be completed usesallthe
theEDG
pick
information has been ascertained. Therefore, where an action requires two or more picks or 
the picked information was incorrect, the action routine must either cache the information
until it has all the required pick information or it must instigate another event that setups the
system for the subsequent picks.
The AppWare developer should now consider the graphic view gadget as any other gadget,
i.e. on left-mouse-button up, the callback of the gadget will be actions.
What EDG allows from the user point of view, is that they can have the graphics view in a
EDG state, but they can still interact with any other form before they have completed the
actual pick task. Whereas, pre-EDG they would have to complete all the picks for a utility,
before anything else could be done.

3.8.2 Pi c k i n g
 Previous to the implementation of the EDG functionality, picking within the graphics view
had a limited scope, in that it was a means to navigate to an element in the database or a

3:4 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

way of identifying and returning some key features on an item in the graphics, i.e. ppoints or 
plines.
What EDG allows now is a richer set of functions that allow the user to specify the type of 

pick the user

of return can perform,
information which
that the can
user have
can usepredefined criteria
without having toapplied to them
derive the and richer
information set
within
their own application code.

3.8.3 Pi c k S
Se
eq u en c e
When picking information from the canvas, a single pick cannot always describe what the
developer requires. Many instances require a standard and predictable sequence of picks to
define some sensible interaction. A simple example of this is a line created between two
points in space.
A more complex, but still a predefined sequence of picks, could involve different types of 
picks, e.g. where a pick sequence requires a user to identify an item then pick a new
position where that item is to be positioned.
In some instances, what could be perceived as being a simple single pick sequence can
actually require several. The most obvious of these is a positioning picks, a simple position
at the origin of an item is only one pick, but a position at an intersection could be either two
or three picks depending on the items picked. In these cases, the numbers of picks are
handled from within the edgPickType object.

3.8.4 Ev en t Pac k et
One of the underlying principles of the system is the event packet, this is a packet of 
information that is used to define an operation in its entirety. These packets are self 
contained, holding all the information about associated forms, operation criteria, actions
carried out on picking, etc. etc.
Once a packet has been defined and submitted to the system, then there should be no
requirement from external sources required for that packet to complete its task. Where
packets required run time data, the method for ascertaining this information should defined
within the packet. As event packets are run autonomously, all expected exceptions (errors)
must be handled internally.
internally.

3.8.5 Ev en t Fl o w
The event system works such that at each
ea ch level within the system, it is possible for an action
to be performed on the returned data. This data is automatically passed from the lower 
routines up through the system, carrying out any predefined action on the data, then
passing it up to the next level. Only when all picks and actions are carried out is the data
passed to the user action routines within the event packet.
 3:5 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

3.9 Event
vent Contr
ontrol
ol Syste
ystem
m (edgC
dgCntrl
ntrl))
The control system is managed by the edgCntrl  object; this contains and controls all the
data pertaining to the AppWare implementation of the EDG system. There are three main
components to the control system, these are:
•  Ac ti ve ev ent  - this is the currently active event that is applied to all the Design graphic
views the system knows about.
• Stacked events   - these are all the events that are currently inactive but the system
knows about. Once the currently active event is completed or removed, the last event
to be added onto the stack will be made current.
• Design Graphic views   - this is a register of all the graphic views that have been
registered for being maintained by the EDG system. Each time an event is added or 
changed, all the view in the stack will be updated with the same data.
There is a single global instance of the edgCntrl   object !!edgCntrl , this controls and
contains all data for the standard DESIGN applications.
 3:6 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

3.9.1 Pu b llii sh
sh e
ed
d In tte
er ffa
ac e
The main components to the event control system that are available to the AppWare
developer can be split into three main sections:

 Ad di ng /Remo vi ng Even ts

Methods for adding and removing event packets to and from the event system:

Nam e Res u l t Acti on

.add(EDGPACKET) BOOL
BOOLEA
EAN
N Ad
Add
d the
the pass
passed
ed even
eventt pac
packe
kett to
to the
the sy
syst
stem
em,,
making it active.

.remove(STRING) Removes the first event packets with the

passed event packet description from the
system.

Modifyin g Ac tive/S
tive/Stacked
tacked Events
Methods used to modify event packets within the event system:

Nam e Res u l t Ac tion

.setPrompt(STRING) Sets the primary prompt of the currently

active event.
.setPrompt(STRING, Sets the primary and secondary prompt of 
STRING) the currently active event.
 setStackPrompt(STRIN Sets the primary prompt of the stacked event
G, STRING) with the passed description.

3:7 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Viewing Stack Contents

Methods used to view the current contents for the event system:

Nam e Res u l t Action

.viewStack() Displays the currently active and stacked
event in the system.
.viewStack(REAL) Display the event at the specified stack
position, zero will display the currently active
event.

All members and methods NOT defined within the table should be classed as being private
to the control object. Therefore, AppWare developer should never use them when writing
applications.

3.9.2 A d d Pac k et
Before an event can be used, the event packet must be defined in its entirety. When an

event is added to the system, several tasks are performed:

• Remove
Remove equiv
equivale
alent
nt packet
packetss from the sy syste
stemm (prom
(prompts
pts on major
major packe
packets)
ts)
• Makes
Makes prev
previou
iouss even
eventt pack
packet's
et's forms
forms ina
inacti
ctive
ve
• Move current
currently
ly acti
active
ve even
eventt pack
packetet onto
onto the sta
stack
ck
• Applies
Applies curre
currently
ntly defin
defined
ed pickin
pickingg filte
filters
rs to picks
picks (wh
(where
ere appli
applicab
cable)
le)
• Applies
Applies new
new packet
packet event
event handl
handlers
ers to all
all register
registered
ed graphi
graphical
cal vi
views
ews
If an event fails for any reason when it is added to the system, the .add  method will return
false.
The AppWare developer should handle failures and inform the user why the event was not
added to the system. Where a packet does fail, the developer should pass any error 
messages that they wish to use back via the public_error  object
 object !!error .
The following example is a simple adding of an event packet object edgPacket   into the
event system:

- - Def i ne Eve
Even
nt Pa
Packe
ckett
! packet
packet = obj ect EDG
EDGPAC
PACKET(
KET( )
! packet ….
- - Add Pa Packe
ckett t o eve
even nt syst em
i f ( ! ! edgCnt r l . add( ! pac kke
et ) . not ( ) ) t hen
! ! al er t . war ni ng( ' Fa
Faii l ed l oadi ng event packe cket ( ' & ! ! er r or . t ext
& ' ). ' )
endi f 
- - End
return

Any code in the macro, function or method which is after the event has been added into the
system, will be completed before the event is available to the user.
 Note: Code after the .add   method, SHOULD NOT  modify any element of the packet
definition, i.e. forms, global variable, etc. as it will only modify the local definition, not
the one that has been added on the EDG system.

3:8 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

3.9.3 Rem o v e Pac k et

The .remove  method will remove the first event in the EDG system that has the passed
description. Where a utility has more than one event, then a remove must be used for each
event added into the system.
An event can be removed from the system in one of two ways, either forcibly by using the
.remove  method, giving the event packet description or automatically as defined in the
event packet definition (see below).
When an event is removed from to the system, several tasks are performed:
• The .close method of event packet is executed
• Remove
Removess any associ
associate
ated
d forms decla
declared
red agains
againstt the pac
packet
ket's
's defini
definitio
tion
n
• Reinst
Reinstate
atess the event
event fr
from
om the top
top of the stack
stack,, making
making it the acti
active
ve eve
eventnt
If the event description passed to the remove methods does not exist in the event control
system, no error is produced.
The following is a closing method for a form that uses an event packet to perform some form
of picking from the graphic view:

- - Define Close Method 

def i ne met hod . cl ose(
se( )
- - Remove event
! edgCnt r l . r emove(
ve( ' <packet
cket descr i pt i on>' )
- - Hide the form
! t hi s . hi de( )
- - End 
endmet hod

Note: Where there is a form associated with an event packet, the form will automatically be
removed by the event system, when the packet is removed from the system.

3.9.4 Ch an g e Pr o m p t s
In several instances it may be necessary to change the prompt of an event, which is already
within the event system.
There are two methods available to change the currently active event prompt(s). These can
be used to change either only the primary prompt or the primary and secondary prompts of 
the event (see below for definition of primary and secondary prompts).
The modifying of prompts should only be necessary where an event packet is recursive, i.e.
it reinstates itself into the system, and subsequent picks require a different prompt from the
first pick.
A typical example of this type of use is the creation of a SCTN (section), the first pick is the
"start" of the section, the second is the "end". After the first pick, the event pick data is
cached, on completion of the second pick, the section if created.
The following is an example of where a packet's action (a method on a controlling form)
 requires the subsequent prompts to be indexed until 4 picks have been made:

3:9 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

- - Check if there are less than 4 elements in the cache

i f ( ! t hi s . c ac he. s i z e
e(( ) l t 4)
4) t hen

- - Increment the prompt of the next pick

! ! edgCnt r l . se
sett Pr ompt ( ' Pr i mar y pr ompt ' ,
! t hi s . c ac he. s i z e
e(( ) . s t r i ng( ) )

- - If there are 4 pick, process the data

el s e

- - Process the pick data

! t hi s. pr ocessD
cessDat a( )

- - Initialise Data
! t hi s . c ac
ac he. c l ear ( )

- - Redefine first prompt

! ! edgCnt r l . s e
ett Pr ompt ( ' Pr i mar y pr
pr ompt ' , ' pi c k f i r s t poi nt ' )

endi f 

Note: Several of the predefined event packets, maintain the prompts in a more direct
manner, these mechanisms MUST NOT  be copied by the developer, as they are
maintained by the standard product and could potentially change without notification.
A third method of the event system, allows a stacked events primary prompt to be changed.
This will mean that when the event is reinstated as the active event, the prompt will be
different, than when it was added to the stack.
This is basically the same as the setting of the primary prompt of the currently active event,
but changes the event by description. This is regardless of whether the event is active or 

stacked.
3.9.5 Vi ew t h e Stac k
There are two methods available to view the current state of the stack. These are only
intended for use whilst developing AppWare and should only be used via the command line.
The outputs are directly written to the command request window,
windo w, and look something like:
 3:10 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

!!edgCntrl.viewStack()

Currently Active EDG Packet

Description : Define a linear dimension
Key : editDimension
Type : measure
Priority : 1
Initialisation : None
Action : !!gphMeasure.setMeasure(!this.return[1])
Form : GPHMEASURE
Remove : false
Input Data : None

Pick Packet
Description : Standard Distance Measure

EDG Packet - Stack position [1]

Description : Standard Navigate

Key : stdNavigate
Type : navi
Priority : 10
Initialisation : None
Action : !this.moveToDBRef()
Form : None
Remove : false
Input Data : None

Pick Packet
Description : Standard Element Pick

3.9.6 L im
im iitt at io
io n
nss a
an
n d Res ttri
ricc ttii on
on s
AppWare developers MUST always access the control object by only Published Interface
methods. All members and methods of the object not within this document are classed as
being private and MUST NOT be used by developer writing applications.

3.10 Event
vent Pa
Packet
cket (edgP
(edgPa
acket)
cket)
The main controlling component of the event system, is the Event Packet. The Event Packet
is used to define an event in its entirety, from the actions carried out when the object is
added to the stack to the action carried out when it is removed from the stack.
The Packet should be considered as being the complete definition of the utility that requires
a sequence of picks, when fully defined it can then be added to the event control system.
Once the Packet is in the system, as the active event, it will then run autonomously until it
has completed the pick sequence or removed from the system, forcible.
 The Event Packet object can be broken down into several components, these basically are:
• Admi
Admini
nisstrat
tratio
ion
n dat
data
• Actions

3:11 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

• Pick
Pick se
sequ
quen
ence
ce defi
defini
niti
tion
on
• Input Data
• Output Data
Currently the main interface into the object is via members, however, there are several
methods available for defining the most common pick sequences.

 Ad mi ni st rat io n Data

Dat a
There are several administration members available within the event object.
Currently the only members that have any relevance and are used by the system are:

.description Description of the event packet which is used when adding or 
removing the packet into/from the edg system.
All packets relating to the same utility should have the same
description. This makes the removing and maintenance of the
system a lot simpler.
.priority Defines the priority within in the edg system of the packet, with
respects to other packets of the same description.
The priority is a real number, zero being the highest priority. Where
a primary packet (priority = 0) is added to the system and there is
already another primary packet in the system. The user will be
prompted to whether they want to replace the one currently in the
system with the one being added.
Only major utilities should be flagged as being primary packets, e.g.
creating a section, element, etc. Subsequent packets relating to the
same utility (having the same description) should have a lower 
priority.
Note: Only packets of the same priority are removed from the
system, lower priorities DO NOT get removed when a higher 
one is added.
.remove Defines whether the event packet is automatically removed from
the system when all the picks within the pick sequences and
actions of the packet have been executed.
The member is a Boolean, true if the packet is to be removed false
if the packet is to be reinstated into the system.
Note: Where a packet fails, it will be removed from the system if 
true, the system DOES NOT return to the beginning of the
event pick sequence.
.form Contains a pointer to the form that is to be shown when the event is
added into the system.
As the member is of "form" data type, the form MUST exist before it
is assigned.
 3:12 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

When the event packet is added to the system, the form will
automatically be shown and any initialisation for the form will be run
as normal. The form will be shown at the right hand side of the
screen, slightly
controlling formsoffset from the
(especially the top. This allows
positioning controlany low tolevel
form) be
positioned above the form.
When the event packet is removed from the system, the form will
automatically be removed from the system and any low level control
forms that the packet may require.
When another event is placed on the stack, the form will still be
active, however, the event picks will relate to the event packet at the
top of the stack. Any low-level forms that are not required by the
new event packet, will be left on the screen, but made inactive. This
shows that they are still required be a currently stacked event, but
does not allow the modification of the event packet until the event
has been reinstated at the top of the stack.

 Ac ti on s
All actions within the event packet object are defined as strings, however, they MUST
represent either a standard command, PML function or PML object/form method. Old style
macros MUST NOT be used within the actions of the object.
The main actions that a packet can have are:

.initialisation The action that is carried out when the event packet is initially
added to the edg system.
When an event packet is reinstated into the system (this is where
the .remove members is false). The action will NOT be executed.
.action An action which is carried out when all the picks within the pick
sequence object (edgPickPacket) have been successfully
completed.
All data derived from picking in the sequence object are returned
through the system via the local variable !this.return  (refer to
Output Data).

.close An action which is carried out just prior to the event packet being
removed from the edg system, whether after a successful
completion of the .action , forcibly by another action of the same
priority/type or using the escape key, when in the graphics canvas.
The action is carried out within the event packet object, therefore,
arguments that refer to !this   relate to the members of the event
packet object itself.
Where a packet has a form associated with the packet (using the
.form  member) then the close action should not attempt to hide the
 form, as the system will automatically remove the form.

3:13 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

.continue An action which is carried out after the event packet has been
removed from the edg system, whether after a successful
completion of the .action  or forcibly by another action of the same
priority.
As the action is carried out external to the event packet object, it is
not possible to access any data from the event packet, unless this
has been stored via other means, i.e. a global variable or form.
Note: This action member is NOT run if the event packet is
removed using the <esc>  key on the Design graphics
canvas is used.
.escape An action which works the same as the .continue  member,
however it is only carried out if the event has been removed from
the using the <esc> key, from the Design graphic canvas.

Pick Definition
The Pick Definition defines the number and types of picks required for the event packet
(refer to Pick Packet (edgPickPacket).
There are several predefined methods that allow the most commonly used event pick
sequences to be declared without the need to define them explicitly. Where a predefined
pick sequence does not exactly give the required picks, they can be used as a basis, then
modified to suite the requirements.
Where there is no event packet method defined that gives the required pick sequences and
pick types, then the developer will have to define the pick packet from first principles.
However, it is hoped that the currently available methods for defining the pick sequences
are adequate for most.
See below for a full list of the available methods (refer to Pick Sequence Methods).

Input Data
Data
Where data is to be passed to an event packet, that is used either on initialisation or whilst it
is running, the data has to be stored in the objects .input  member. This means the event
packet can run autonomously without the need to access data from external variables or 
forms.
The input member is an ARRAY type, allowing any variable data type to be passed to the
system. Setting the input data is the same as defining any other array element:

-- Define input data for packet

! pa
pac ket [ 1]
1] = ' St r i ng'
!ppa
ac ket [ 2]
2] = 20
!ppa
ac ket [ 3]
3] = ! ! ce
c e. pos i t i on
! packet
acket . app
append(
end( 10)10)
! pac k
ke
et . i ns e
err t ( 1, ! ! c e
e))
.
.
 When using the input data, the developer MUST make sure that they know the positions
and data type of the element of the array they are using.

3:14 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

As input member can only be accessed directly from within the system by the action
routines associated with the action members of the event object. The input variable must be
refereed to thus !this.input:

-- Initialisation Action (using first element of input)

!p
paac k
ke
et . i ni t i al i s at
at i on = ' ! ! f or m. event I ni t ( ! t hi s . i nput [ 1] )
-- Action routine (using all input array and return pick data)
! p ac
ac ke
ket . ac t i on = ' ! ! f orm. event Ac t i on( ! t hi s . i nput , ! t hi s . r et urn )
-- Close action (using first element of input)
! pack
cke
et . cl ose = ' ! ! f or m. event Cl ose(
se( ! t hi s. i nput [ 1] )

Note: Variables are passed by reference, therefore, changing the variable associated to the
input variable, will change the input variable.
Where a pick sequence requires multiple picked and the lower objects do not process the
pick data, then the return array will contain multiple entries, one for each pick.

Output Data
Data

All
passthethe
objects within thethe
data between event picking
objects mechanism
within have
the system. a .return
All the  members,
objects are of an this
ARRAYis used to
type,
as this allows any data type to be assigned to the elements.
When a pick sequence has completed, all the derived data ascertained from the picking, will
be returned into the .return  member of the pick event object. Therefore, all .action  routines
requiring the pick data MUST use the variable.
Similar to the input variable, the return variable can only be accessed directly
dire ctly from within the
system, and therefore must be declared in the argument list of the actions as !this.return .

-- Action routine
 _
 _!! packet . act i on = ' ! ! f or m. event Act i on( ! t hi s . r et ur n)

In most instances, only the first element of the return array will be populated. This could be
either with another array or a specific object type. In these cases, the developer may want
only to pass the relevant element to the action routine:
-- Action routine
 _
 _!! packet . act i on = ' ! ! f or m. event Act i on( ! t hi s . r et ur n[ 1] )

Note: Variables are passed by reference, therefore, changing the variable associated to the
return variable, will change the input variable.

3.10.1 Pub
ubli
lish
sheed IInt
nteerf
rfaace
The main components of the object that the developer can use, can be broken into two
sections:
 3:15 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Members
These are the published members for the object that the developer can used to define the
event packet object:

Nam e Ty p e Action

.description STRING Description of the event packet.

.priority REAL Priority of event within the event packets of the
same description.
.initialisation STRING Action carried out when event packet is initially
added to the event system.
.close STRING Action carried out just before the event packet
is removed from the event system.
.action STRING Action carried out when all picks within the pick
sequence has been completed.
.continue STRING Action carried out after the event packet has
been removed from the event system.
.escape STRING Action carried out when the event packet is
removed from the system using the <esc> key
in the design graphic canvas.
.form FORM Form to be show when event packet is added
to the event system.
.pickPacket EDGP
EDGPIC
ICKP
KPACK
ACKET
ET Defi
Defini
niti
tion
on o
off pic
pickk se
sequ
quen
ence
ce and
and typ
types
es rreq
equi
uired
red
for the event packet.
.remove BOOLEAN True  if event is automatically removed when
the pick sequence has been completed.
False  if event is to be reinstated, without the
.initialisation  action being carried out.

.input ARRAY Contains information to be held local to the

event packet, which can be used during its
execution.

Pick Sequence Method

Method s
There are several methods that define standard pick sequences, the following are the ones
currently supported:

Nam e Ac tion

.navigate() Standard navigate pick.

.elementPick(<prompt>) Standard database element pick.
.plinePick(<prompt>) Standard pline pick.
 .anyPick(<prompt>) Standard "any" pick.
.aidPick(<prompt>) Standard graphical aid pick.

3:16 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

.definePosition(<prompt>) Define basic positioning pick packet.

.defineCircle(<option>) Define circle definition pick packet.

.definePoint(<option>) Define point definition pick packet.

.defineLine(<option>) Define line definition pick packet.
.definePlane(<option>) Define plane definition pick packet.
.defineMeasure(<option>) Define a pick sequence for performing a measure.

The following are the standard available pick sequence methods and the event packet
settings that can be modified by the developer. Members not shown in the list, but which are
available for the developer, should be left as defined by the method, so that the pick
sequence works correctly:

Met h o d Nam e Des c r i p t i o n

.navigate() Standard navigation pick, this will reposition the user at the
element picked.
 Ar gu men ts Desc ri pt io n

Pac k et Mem b er s Set t i n g s

.description Standard Navigate.

.priority 10.
.remove True.
.input
Ret u r n A r r ay Des c r i p t i o n

None None.

Met h o d Nam e Des c r i p t i o n

.eleme
.elementP
ntPick
ick(<pr
(<prompt
ompt>)
>) St
Stand
andard
ard element
element pic
pick,
k, allows
allows a data
databas
base
e e
elem
lement
ent to be
picked from the design canvas.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt shown in the views information field.

Pac k et Mem b er s Set t i n g s

.description Standard Element Pick.

.priority 0.
.remove F al s e.
 .input

3:17 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.p
.pliline
nePi
Pick
ck(<
(<pr
prom
ompt
pt>)
>) Stand
tandar
ard
d str
struc
uctu
tura
rall ele
eleme
ment
nt plin
pline
eppic
ick.
k.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt shown in the views information field.

Pac k et Mem b er s Set t i n g s

.description Standard Pline Pick.

.priority 0.
.remove F al s e.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.a
.any
nyPi
Pick
ck(<
(<p
pro
romp
mpt>
t>)) Standa
andard
rd "any
"any"" ppic
ick,
k, allo
allow
ws ele
eleme
ment
nt,, p
pliline
ne,, p
ppo
poin
intt o
or 
r 
graphical aid to be picked.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt shown in the views information field.

Packet Members Settings.
.description Standard ANy Pick.
.priority 0.
.remove F al s e.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.aidPick(<prompt>) Standard g
grraphical ai
aid e
ellement pi
pick.
  Ar gu men ts Desc ri pt io n
<prompt> Primary display prompt shown in the views information field.

3:18 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Pac k et Mem b er s Set t i n g s

.description Standard Aid Pick.

.priority 0.
.remove F al s e.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.definePositi
.definePosition(<pr
on(<prompt>)
ompt>) Standard
Standard position
position pick,
pick, display
display position
position con
control
trol form
form used
used to
define pick type selection and derive position filter.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt shown in the views information field.

Pac k et Mem b er s Set t i n g s

.description Basic Position.

.priority 0.
.remove F al s e.
.input
Ret u r n A r r ay Des c r i p t i o n

[1
[1]] edg
edgPo
Posi
siti
tion
onDa
Data
ta Ev
Even
entt pic
picke
ked
d posi
positi
tion
on retu
return
rn obje
object
ct,, con
conta
tain
inss all
all pic
pickk data
data and
and
derived position from the pick.

Met h o d Nam e Des c r i p t i o n

.d
.def
efin
ineC
eCir
ircl
cle(
e(<o
<opti
ption
on>)
>) Meth
Method
od for
for defi
defini
ning
ng a pick
pick sseq
eque
uenc
nce
e to defi
define
ne a arc
arc ob
obje
ject
ct
using the graphics.
 Ar gu men t (Op ti on ) Desc ri pt io n

3pnt Derives an arc passing through 3 position picks.

diameter3D Derives an arc whose diameter and X axes is through the
first two positional picks. The third positional pick defines the
relative Y axes of the arc definition.
radius3D Derives an arc which is centred about the first positional pick,
the second positional pick defines the radius and X-axes.
 The third positional pick defines the relative Y axes of the arc
definition.

3:19 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

fi x e d R a d i u s 3 D Defines an arc ce
centred oon
n th
the first po
position pi
pick, wh
where th
the
second and third positional pick defines the X and Y axes
respectively. Radius is specified via the automatically
displays input form.
fixedDiameter3D Defi
fin
nes an arc centred on the fir
first position pic
pick, where
ere the
the
second and third positional pick defines the X and Y axes
respectively. Diameter is specified via the automatically
displays input form.
diameter2D Derives an arc lying on the active working plane, where the
diameter and X axes is through the two positional picks.
radius2D Derives an arc lying on the active working plane, centred
about the first positional pick, the second positional pick
defines the radius and X-axes.
fixedRadius2D Defines an arc lying on the active working plane, centred
about the positional pick. Radius is specified via the
automatically displays input form.

fixedDiameter2D Defines an
an ar
arc ly
lying o
on
n tth
he a
acctive wo
working pl
plane, cce
entred
about the positional pick. Diameter is specified via the
automatically displays input form.
fillet Defines an arc of radius specified via the automatically
displays input form, that lies tangentially to the two picked
lines.
tanTan Defines an arc of radius specified via the automatically
displays input form, that is tangential to the two picked arc
elements. The third pick (positional) define the centre side of 
the arc.
pntTan Defines an arc centred on the first pick (positional) which is
tangential to the second pick (curved element).
fi
fixe
xedR
dRad
adiu
iusP
sPn
ntTan
tTan Defin
efines
es an ar
arcc wit
with
h rad
radiu
iuss su
supp
pplilied
ed by the
the aut
autom
omat
atic
ica
ally
lly
displayed input form, which lies on the line between the first
pick (positional) and the picked curved element.
fi
fixe
xedR
dRad
adiu
iusP
sPnt
ntPn
Pntt Defi
Define
ness an ar
arcc ce
cent
ntre
red
d on the
the firs
firstt posi
positi
tion
onal
al pick
pick whic
which
h is
tangential to the second pick on a curved element.
derive Derives an arc from the picked element.
tan3Lines Derives an arc which fits between the three lines picked.
Pac k et Mem b er s Set t i n g s

.description Defined by option.

.priority 0.
.remove True.
 .input
Ret u r n A r r ay Des c r i p t i o n

[1] arc Standard arc object.

3:20 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Met h o d Nam e Des c r i p t i o n

.d
.def
efin
inePo
ePoin
int(
t(<o
<opti
ption
on>)
>) Meth
Method
od for
for de
defifini
ning
ng a p
pic
ickk seq
seque
uence
nce to d
def
efin
ine
e a pur
pure
eppos
osit
itio
ion
n
object definition.
 Ar gu men t (Op ti on ) Desc ri pt io n

pnt Derives an position at the derived positional.

Pac k et Mem b er s Set t i n g s

.description Defined by option.

.priority 0.
.remove True.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] position Standard position object.

Met h o d Nam e Des c r i p t i o n

.d
.def
efin
ineL
eLin
ine(
e(<o
<opt
ptio
ion>
n>)) Meth
Method
od for
for defi
defini
ning
ng a pick
pick sequ
sequen
ence
ce to d
def
efin
ine
e a llin
ine
eoobj
bjec
ectt
definition.
 Ar gu men t (Op ti on ) Desc ri pt io n

p n tP n t Defines a line between the two positional picks.

angl e Defines a line based on the first pick (line element), which
angled by value supplied via the input form the line towards
the second pick (positional). The third pick (positional)
defines the start of the line definition.
derive Defines a line derived from the picked element.
pntTan Defines a line from the first pick (positional) to the nearest
tangent point of the second pick (curve element).
tanTan Defines a line to the nearest tangent points on the two curves
picked.
bi s ec t Defines a line that bisect the two lines picked, line is based
on the first line picked.
twoPlanes Defines a line that is at the intersection of the two picked
plane elements.
shortest Defies a line that is between the two closest points of the
graphical entities picked. Where the two items are parallel,
 then the line is from the first picked position onto the second.
Where two items converge and the line is zero length, then
an unset line is returned.

3:21 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Pac k et Mem b er s Set t i n g s

.description Defined by option.

.priority 0.
.remove True.
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] l i n e Standard line object.

Met h o d Nam e Des c r i p t i o n

.d
.def
efin
inePl
ePlan
ane(
e(<op
<optio
tion>
n>)) Metho
Method d for
for defi
defini
ning
ng a pic
pickk se
sequ
quen
ence
ce to
to defin
define
eap
pla
lane
ne o
obj
bjec
ectt
definition.
 Ar gu men t (Op ti on ) Desc ri pt io n

3pnt Derives a plane passing through the three positional picks.

The first two define the centre and the X-axes, the third
defines the relative Y-axes.
Pac k et Mem b er s Set t i n g s

.description Defined by option.

.priority 0.
.remove True.
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] p l a n e Standard plane object.

Met h o d Nam e Des c r i p t i o n

.defin
.defineMea
eMeasur
sure(<
e(<opti
option>
on>)) Method
Method for
for definin
defining
g a pick se
seque
quence
nce to de
deriv
rive
e a
measurement.
 Ar gu men t (Op ti on ) Desc ri pt io n

distance Defines a line object that equates to the distance between

the two positional picks.
shortest Defines a line object that equates to the shortest distance
between the to graphical entities picked.
angl e Defines an arc that represents the angle between the three
 positional picks. The first pick defines the point about which
the angleand
the start is, end
the second and third,
of the angle the points through which
passes.

3:22 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

lineAngle Defines a real that relates to the angle between the two
linear items picked.
Pac k et Mem b er s Set t i n g s

.description Defined by option.

.priority 0.
.remove True.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] line (distance) Standard line object.

[1] line (shortest) Standard line object.
[1] arc (a
(angle) Standard arc object (radius is u
un
nit le
length of 1000mm).
[1] real (lineAngle) Real.

Note: When defining event packets using the above methods, the method should be
applied to the object before any other member is set, as the methods will overwrite
several of the event packet members.

3.10.2 Ex am p l es
The following are several examples and descriptions for setting up some basic packets
using the standard pick sequence methods.

Single Element Pick

The Single Element Pick defines an event packet that is totally self contained, it uses no
controlling form or action macros in its definition.
The packet definition is defined so that it remembers the element the user is at when the
packet is placed in the event system. For each pick of an element in the graphics view, the
user will be navigated to the picked element, when packet is removed from the event
system (using <esc>  or being forced from the system by another event) the user will be
returned to the original element:
 3:23 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

-- Define event packet

!p
paac ket = obj ec t EDGPACKET( )
-- Define standard element pick

! packe
cket . el ement Pi ck(
ck( ' Pi ck El ement ' )

-- Remember the element when the packet was first place in the
-- event system

! pa
pac ket . i ni t i al i s at i on = ' !th
hii s . i nput [ 1]
1] = ! ! ce
c e'

-- Move to the element picked 

! pa
pac ket . ac t i on = ' ! ! ce
c e = ! t hi
hi s . r et
et ur
ur n[
n[ 1]
1] . i t em
em'

-- Set the close sequence, so that the user returns to the original
-- element

! pa
pac ket . c l os e = ' !!c
cee = ! t hi
hi s . i nput [ 1
1]]

-- Add event packet to the system

! ! edgCnt r l . add( ! packe

cket )

Repeat Element Pick

The Repeat Element Pick defines an event packet that will keep picking elements, storing
the picked element in the input member of the packet. Then, when <esc> button is pressed,
the closing action will display all the elements in the input array.

-- Define event packet

!p
paac ket = obj ec t EDGPACKET( )

-- Define standard element pick

! packe
ackett . el emen
entt Pi ck( ' Pi ck El emen
entt <esc>
esc> t o f i ni sh
sh'' )

-- Retain the element picked in the input member 

!p
pa
ac ket . ac t i on = ' ! t hi
hi s . i nput . append( ! t hi s . r et
et u
urr n[
n[ 1
1]] . i t e
emm) '

-- Display the selected element on <esc>

! pa
pac ket . c l os e = ' q var ! t hi
hi s . i nput '

-- Add event packet to the system

! ! edgCnt r l . add( ! packe

cket )
 Again, this packet does not use other objects, functions or forms in its running. However, it
could be adapted to use objects, functions or forms when running. This could allow the
elements picked twice to be removed from the list, then some special action carried out on
all elements selected on the close of the packet.

3:24 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

The following is an example of a packet definition that will run functions that store the picked
element (in a global variable), then on completion, enhance all the elements selected.
When the event is placed into the event system, it will automatically initialise the global
variable that is used to store the picked elements:
Event Packet
Packet Definitio n

-- Define event packet

!p
paac ket = obj ec t EDGPACKET( )

-- Define standard element pick

! packe
ackett . el emen
entt Pi ck( ' Pi ck El emen
entt <esc>
esc> t o f i ni sh
sh'' )

-- Initialise the global store

!p
pa
ac ket . i ni t i al i s a
att i on = ' ! ! xxxGl obal St or
o r e = ARRAY( ) '

-- Retain the element picked in the input member 

!p
pa
ac ket . ac t i on = ' ! ! x xx
xxSt o
orr e
eEEl ement ( ! t hi s . r e
ett u
urr n[
n[ 1]
1] . i t e
emm) '

-- Tag the selected element on <esc> with their names

!p
paac k
ke
et . c l os e = ' ! ! xxxTagEl ement s ( | NAME| ) '

-- Add event packet to the system

! ! edgCnt r l . add( ! packe

cket )

The following is the function definition that stores the picked element in a global variable,
enhancing the picked element. If the same element is picked twice, then it will be removed
from the list and un-enhance it:
 3:25 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Store Element
Element Funct ion

-- Function Definition

def i ne f unct i on ! ! xxxS

xxxStt or eEl
eEl ement
ent ( ! el ement
ent i s DB
DBREF)

  -- Check if element exist in the global variable

  ! i ndex = ! ! xx
xxx
xGl obal St or e. f i ndFi r st ( ! el ement )

  -- Element already is in the store

  i f ( ! i ndex. s e
ett ( ) ) t h
heen
 
-- Remove element from the list and un-enhance

  ! ! xx
xxxG
xGl ob
obal
al St ore. r emov
ove(!
e(! i ndex
ex))
UNENENH
HANCE
ANCE $! <el ement >
 
-- Add element to the list and enhance

  el
el s e
  ! ! xxxG
xxxGl ob
obal
al St or e. ap
app
pen
end
d( ! el ement
ent )
ENHANCE
ANCE $! <el ement > COL OUR RED
  end
endi f 
 
-- End of definition
endf unct i on

The following functions definition is used to tag "MARK" all the elements that are in the
global variable:

Store Element
Element Funct ion

- - Function Definition

def i ne f unct i on ! ! xx
xxxT
xTa
agEl emen
entt s( )
-- Loop through elements

  do ! i i ndi ce
ces
s ! ! xxxGl obal St or e

  -- Tag Item

  MARK $! ! <xxxGl obal

obal St or e[ $! <i >] >

  -- Unenhance element

  UNENHANCE $! ! <xxxG
xxxGll obal St or e[ $! <i >] >

  enddo
 -- End of definition
endfunction

3:26 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Simple Standard
Standard Positi
Positi on Pick (using only po sitio n data
data))
The Simple Standard Position Pick defines an event packet that uses the standard
positioning pick sequence. In this example, the packet definition has a controlling form (the
detail of the form is irrelevant) that the derived picked position writes it data to after each
pick.
When associating a form with an event packet, the developer MUST ALWAYS make sure
that the form has been build. This is because the form is passed by reference.
When the event packet is added to the edg system, the form will automatically be shown in
the top right hand corner of the screen (there is no control over this). In the case of the
positioning pick sequence, the positioning control form will also be displayed above the
event packets form.

- - Def i ne eve
even
nt pack
acket
et
!p
pa
ac ket = obj ec t E
ED
DGPACKET( )

- - Def i ne st an
and
dard el
el emen
entt pi ck
! p ac
ac ke
ket . def i nePos i t i on( ' Pi c k Pos i t i on' )

- - Ret ai n t he el ement
ent pi cked i n t he i nput
nput member
ber
!p
pa
ac ket . ac t i on = ' ! ! xx
x xxFor m. pos i t i on( ! t hi s . r et
et ur
ur n[
n[ 1
1]] . pos i t i on) '

- - Bui l d f or m i f r e
eqqui r ed
ed
i f ( undef i ned( ! ! xx
xxxF
xFo
or m) ) t hen
  pml r el oad f or m ! ! xx
xxx
xFo
Forr m
endi f 

- - As s oc
oc i at e f or m
! pa
pac ket . f o
orr m = !!x
xx
xxFor m

- - Ex
Execu
ecutt e t he f or ms t i dy met hod on compl et i on
! pa
pac ket . c
cll os e = ' ! ! xx
xxxFor m. t i dy( ) '

- - Add ev
evenentt packet
acket t o t he syst em
! ! edgCnt r l . add( ! packe
cket )

It should be noted that there

th ere are several ways in which the event packet form can be closed:
• Form
Form gadg
gadgetet,, OK/Ca
OK/Canc
ncel
el/D
/Dis
ismi
miss
ss butt
button
on or Close on pull-down
• Close from the forms pull-down, top-left-hand corner of the form
• Using the <esc> key when in a design graphics canvas
When closing the event from the from (one of the first two methods) then the event packet
MUST be removed using the event systems .remove  method, supplying the same
description that event packet was placed onto the system with:
!!edgCntrl.remove(<event
!!edgCntrl.remove(<event packet descrip tion>)
 When using the
form should <esc>
to be  in the
used. Thedesign canvas,
developer then NOT
MUST only the
userelevant tidy-up
a method thatsequence of the
has the event
systems .remove method in, this could cause problems.

3:27 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Equivalents to " VAR !<id> PIC

PICK"
K" comm ands
The following are examples of the old style PML 1 commands used to suspend the currently
active macro with a pick from the graphics canvas:
The following example equates to the old style "pick an element":

VAR !<var id> PICK

-- Define event packet

!p
paac ket = obj ec t EDGPACKET( )

- - Def i ne st an
and
dard el
el emen
entt pi ck
- - Equa
Equatt es t o ol d PRO
PROMPT OFF
-- PROMPT L OAD ESCAPE ' <pr ompt >'
! packe
cket . el ement Pi ck ( ' I dent i f y el ement ' )

-- Defines action on completion of the pick, passing complete

-- pick data

! pa
pac ket . ac t i on =' ! a
ac
c t i on( ! t hi
hi s . r et
et ur
ur n[
n[ 1
1]] ) '

-- Add event packet to the system

-- Equate to old VAR !varID PICK  

! ! edgCnt r l . add( ! packe

cket )

The following example equates to the old style "pick a pline of a section":

VAR ! <varid> PICK PLINE

-- Define event packet

!p
pa
ac ket = obj ec t E
ED
DGPACKET( )

-- Define standard element pick

- - Equat e
es
s t o ol d PROMPT OFF
-- PROMPT L OAD ESCAPE ' <pr ompt >'
! p ac
ac ke
ket . pl i nePi c k ( ' I dent i f y pl i ne of s ec
ec t i on)

-- Defines action on completion of the pick, passing complete

-- pick data

! pa
pac ket . a
acc t i on =' ! ac
ac t i on( ! t hi
hi s . r et
et ur
ur n[
n[ 1]
1] ) '

-- Add event packet to the system

-- Equate to old VAR !varID PICK PLINE  

! ! edgCnt r l . add( ! packe

cket )
 The following example equates to the old style "pick a ppoint of an element":

3:28 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

VAR ! <varid> PICK PLINE

- - Def i ne eve
even
nt pack
acket
et

!p
pa
ac ket = obj ec t E
ED
DGPACKET( )

-- Define standard element pick

-- Equates to old PROMPT OFF 
-- PROMPT LOAD ESCAPE '<prompt>'

! pack
cke
et . pl i nePi ck ( ' I dent i f y e
ell ement ppoi nt )

-- Defines action on completion of the pick, passing complete

-- pick data

! pa
pac ket . a
acc t i on =' ! ac
ac t i on( ! t hi
hi s . r et
et ur
ur n[
n[ 1]
1] ) '

-- Add event packet to the system

-- E
Eq
quate to
to o
ol
ld VAR !v
!varID PI
PICK POINT  

! ! edgCnt r l . add( ! packe

cket )

Notes:
1. With the EDG system,
system, it is
is not possi
possible
ble to instigate
instigate an event
event and sus
suspend
pend the currently
currently
active macro then return to the same point in the macro, once the pick is completed. If 
the developer wants to simulate the suspension of a macro, i.e. wait for the pick on the
graphics canvas. Then, the invocation of the event packet MUST be the last command
within the file and the action to be carried out after the pick, MUST be in the function/
method defined in the .action  member.
Command defined after the invocation of an event packet within the same macro,
MUST NOT rely on the pick data of the event. Also it should be noted that any changes
to the packet definition WILL NOT have any effect on the event packet that has been
added to the system.
2. All of the above will
will automat
automaticall
icallyy use the standard
standard filters set via
via the filter utility
utility with
within
in
the application. If an event packet is required that has a specific type of pick filter and
the standard filters are to
t o be ignored, see below.

3.10.3 Lim
Limit
ita
atio
tions
ns and Restri
stricti
ctions
ons
Currently there are no methods on the event packet object for passing data down into the
lower level objects used by the system. This means that if there are requirement for a pick
sequence, pick type or actual pick to act differently than those defined by the currently
available pick sequence methods, the developer will have to define their own object
definition for the event packet in full.
It should also be noted that once an event is placed on the event stack, modifying the packet
that was originally passed to the system WILL NOT change the packet that is held within the
event system.
It is not possible to define an event packet, which comprises of a single specific type of pick,
followed by an unspecified one of the same type of pick.
 It is not possible to define an event packet that triggers a subsequent event packet off, on
the completion of another, i.e. don't have an !!edgCntrl.add(<edgPacket>)  within the
.close action of the first packet. As adding a new packet in the close sequence, will actually

3:29 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

stack the packet that is running, only removing it from the system, once the subsequent
packet has finished.

3.11 Pick Packet

cket (edgPickP
dgPickPa
acket)
cket)
Whereas the event packet edgPacket   defines what happens before and after a pick or 
picks have been performed, the pick packet defines the actual pick sequence and types of 
pick that are to be performed before the action of the event packet is executed.
A pick packet can be defined simple as a single basic pick, pick element, pline, ppoint, etc.
etc. Or it can be used to define several consecutive picks, either of the same time or of 
different types.
Only when all picks within a pick packet have been performed, will the system return control
to the owning event packet. This allows the developer to define a standard set of picks
required for an interaction, without the need to handle every graphic canvas pick in the utility
they are writing.
Similar to the event packet, the pick packet object can be broken down into several
components, these are:
• Admi
Admini
nisstrat
tratio
ion
n dat
data
• Actions
• Pick
Pick se
sequ
quen
ence
ce defi
defini
niti
tion
onss
• Input Data
• Output Data
Currently the main interface into the object is via members, however, there are several
methods available for defining the most common pick types.

 Ad mi ni st rat io n Data

Dat a
Unlike the administrative members of the event object, these members of this object are
only for interrogation by the developer and do not perform or define any characteristics of 
the pick packet, they are only for information.

 Ac ti on s
There is only one action member of the pick packet object .action  this defines the action
that is carried out once all the picks within the pick packet definition have been completed.
Where a developer wish to define an action that is triggered on the completion of all picks,
then refer to the event packet action section, as the same principles apply to the de
definition
finition of 
the pick packet action.

Pick Sequence Definition

Definition s
For each pick required by the pick packet, the sequence definition array .picks , must
contain one or more pick type objects edgPickType, which define the pick to be carried out
by the system. This means that where a pick packet requires two pick, then the sequence
definition array .picks  will contain two entries.
 There are several predefined methods available to the object that allows commonly required
pick sequences to be defined. The defined methods describe the pick packet object in their 
entirety and should not require any modification.

3:30 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

In most instances the predefined methods within the object can be used via a method on the
event packet object edgPacket  (refer to Pick Sequence Methods). Therefore, in most cases
the use of the pick packet predefined methods should not be required.

Input Data
Data
The input data mechanism is identical to that of the event packet input mechanism, i.e. if 
data is to be passed about within the pick packet definition, then it should be via the .input
array (refer to Input Data).
Even though the input member has been included in the system, it currently has not been
used within any of the EDG developed so far. Therefore, even though the mechanism is
available it has not been extensively tested.

Output Data
Data
The output data mechanism is identical to that of the event packet object (refer to Output
Data).

3.11.1 Pub
ubli
lish
sheed IInt
nteerf
rfaace
There are two main components to the pick packet object, these are the member and
methods.

Members
The following are published member interface into the object, members not defined within
this table are internal to the object and should never be set by the developer.

Nam e Ty p e Action

.description STRING Description of the event packet.

.key STRING Single word identifier.
.prompt STR
STRIN
ING
G Prim
Primar
aryy pro
promp
mptt (sh
(show
own
naatt the
the begi
beginn
nnin
ing
gooff the
the prom
prompt
pt
status line.

.picks ARRAY Picks types edgPickType defining the pick sequence.

.action STR
STRIN
ING
G Acti
Action
on car
arri
ried
ed out
out a
affter
ter a
alll tth
he p
pic
icks
ks withi
ithin
n tthe
he pick
pick
sequence have been completed.
.input ARRA
ARRAY
Y Cont
Contai
ains
ns in
info
form
rmat
atio
ion
n to
to b
be
ehhe
eld loca
locall to
to the
the pick
pick packe
acket,
t,
which can be used during it execution.

Methods
There are several methods that can be used to define a standard pick packet, the following
are the ones currently supported:

Nam e Action
 .stdGphWindow(<prompt>) Standard graphical window pick (only screen position
used).
.stdScreen(<prompt>) Standard screen pick.
.stdView(<prompt>) Standard screen pick.

3:31 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

.stdElement(<prompt>) Standard element pick.

.stdAny(<prompt>) Standard element pick.

.stdPpoint(<prompt>) Standard ppoint pick.

.stdPline(<prompt>) Standard pline pick.
.stdAid(<prompt>) Standard aid element pick.
.stdGraphic(<prompt>) Standard graphical pick.
.direction(<prompt>) Standard derive direction pick.
.measureDistance() Standard distance measure.
.measureAngle() Standard angle measure between three point.
.measureLineAngle() Standard angle measure between two lines.
.stdPosition(<prompt>) Standard 3D single position pick.
.circle3pnts() Circle through 3 points.
.circleDia3d() Circle through 2 Positions (diameter defined) 3D.
.circleRad3D() Circle define centre and radius + control point 3D.
.circleFixRad3D(<any>) Circle centred of defined radius 3D.
.circleFixDia3D(<any>) Circle centred of defined diameter 3D.
.circleDia2D(<any>) Circle through 2 Positions (diameter defined) 2D.
.circleRad2D(<any>) Circle define centre and radius + control point 2D.
.circleFixRad2D(<any>, Circle define centre and radius + control point 2D.
<any>)

.circleFixDia2D(<any>, Circle centred of defined diameter 2D.

<any>)

.circleFillet(<any>) Fillet circle of defined radius.

.circleTan3Lines() Circle tangential to 3 lines.
.circleTanTan(<any>) Circle tangential to two other circles.
.circlePntTan() Circle, centred and tangential to another circles.
.circleFRadPntTan(<any>) Circle, centred and tangential to another circles of fixed
radius.
.circleFRadPntPnt(<any>) Circle going through two points + polar control point.
.circleDerive() Derive a circle from a DB element.
.pointPnt() Define working point in 3D space.
.linePntPnt() Define a line.
 .lineAngle(<any>) Line offset by an angle from the picked line, towards the
second pick.
.lineDerive() Derive a line from a db element.

3:32 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

.linePntTan() Line between point an tangent of arc.

.lineTanTan() Line between tangent points of two arcs.

.lineBisect() Line bisecting two other lines (smallest angle side).

.lineTwoPlanes() Line at intersection of two planes.
.lineShortest() Shortest Line between to picked items.
.plane3pnts() Define a plane through 3 Positions.
.plane2pnts(<position>) Define a plane through 3 Positions.
.planeDerive() Derive a plane from a db element.

Note: Where pick packet definitions are supplied with arguments with a specific data type,
then these values have to be supplied before the event packet is placed in the event
system. However, where pick packets have an <any>  argument type, the can be
supplied as a pointer (expression) that evaluates into the correct data type when the
action of the pick is evaluated.

The following are the standard available methods and their default settings that can be
modified or used by the developer. Members not shown in the list, but which are available
for the developer, should be left as defined by the method.

Met h o d Nam e Des c r i p t i o n

.st
.stdGp
dGphWin
hWindow
dow(<p
(<promp
rompt>)
t>) Stand
Standard
ard graph
graphica
icall win
window
dow p
pick
ick..
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Picks Types Description.
[1] stdScreen Pick a position on the graphics canvas (First point).
[2] stdScreen Pick a position on the graphics canvas (Second point).

Pi c k Pac k et Mem b er s Set t i n g s

.description Standard Graphical window pick.
.k e y StdGphWindow.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] ARC Arc defining the plane of view and extremities of the pick.

Met h o d Nam e Des c r i p t i o n

.std
.stdScr
Scree
een(
n(<pr
<prom
ompt
pt>)
>) St
Stan
anda
dard
rd gr
grap
aphi
hica
call can
canva
vass pick
pick,, used
used to deri
derive
ve posi
positi
tion
on in
 the selected view.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

3:33 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Picks Types Description.

[1] stdScreen Pick a point on the graphical canvas.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Standard Screen Pick.
.k e y StdScreen.
.input
Ret u r n A r r ay Des c r i p t i o n

[1
[1]] POIN
POINTV
TVEC
ECT
TOR Cont
Contai
ains
ns di
dire
rect
ctio
ion
n of
of the
the vi
view
ew pick
picked
ed and
and tthe
he posi
positi
tion
on on the
the
view plane (normal to direction of view, through the centre of 
view limits).

Met h o d Nam e Des c r i p t i o n

.std
.stdVi
View
ew(<
(<pr
prom
ompt
pt>)
>) Stand
tandar
ard
d vi
view
ew pick
pick,, used
used to dete
determ
rmin
ine
e grap
graphi
hicc vi
view
ew pick
picked
ed..
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Pi c k s Ty p es Des c r i p t i o n

[1] stdView P i c k v i e w g a d g e t.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard View Pick.

.k e y stdView.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] GADGET Pointer to view gadget picked.

Met h o d Nam e Des c r i p t i o n

.std
.stdEle
Eleme
ment
nt(<p
(<pro
romp
mpt>)
t>) Stand
tandard
ard elelem
emen
entt p
pic
ick,
k, pick
pickss dat
datab
abas
ase
e el
elem
ement
ent form
form
graphical view.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Picks Types Description.
 [1] stdElement Pick database element.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Standard Element Pick.

3:34 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

.k e y stdElement.
.input

Ret u r n A r r ay Des c r i p t i o n
[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.stdAny
Any(<p
<prrompt>) Pi
Picck an
any el
element di
displayed in
in th
the g
grraphical vviiew.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Pi c k s Ty p es Des c r i p t i o n

[1] stdAny Pick any graphical element type.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Standard Any Pick.
.k e y stdAny.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.std
.stdPp
Ppoi
oint
nt(<
(<pr
prom
ompt
pt>)
>) Pi
Pick
ck a p
ppo
poin
intt of
of an
an e
ele
leme
ment
nt in the
the g
gra
raph
phic
ical
al vi
view
ew..
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Pi c k s Ty p es Des c r i p t i o n

[1] stdPpoint P i c k a ppoi nt .

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard Ppoint Pick.

.k e y stdPpoint.
.input
Ret u r n A r r ay Des c r i p t i o n
 [1] edgPickData Standard event pick return object.

3:35 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Met h o d Nam e Des c r i p t i o n

.s
.sttdPli
dPlin
ne(
e(<p
<pro
romp
mpt>
t>)) Pi
Pick
ck a pl
plin
ine
e of an elem
elemen
entt in the
the grap
graphi
hica
call vi
view
ew..
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Pi c k s Ty p es Des c r i p t i o n

[1] stdPline Pick a structural pline.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard pline Pick.

.k e y stdPline.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.stdAid
Aid(<promp
ompt>) Pi
Picck a re
registered
red gr
graphical ai
aid e
ellement fr
fro
om tth
he gr
graphical
view.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Pi c k s Ty p es Des c r i p t i o n

[1] stdAid Pick graphical aid.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Standard Aid Element Pick.
.k e y stdAid.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

 .std
.stdGr
Grap
aphi
hic(
c(<p
<pro
rompt
mpt>)
>) Pick
Pick gra
graphi
phica
call com
compopone
nent
nt of any
any e
ele
lemen
mentt in
in tthe
he grap
graphi
hical
cal
view, i.e. point, line or plane.
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

3:36 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Pi c k s Ty p es Des c r i p t i o n

[1] stdGraphics Pick graphical entity.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Standard Graphic Pick.
.k e y stdGraphic.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] edgPickData Standard event pick return object.

Met h o d Nam e Des c r i p t i o n

.d
.dir
irec
ecti
tion
on(<
(<pr
prom
ompt
pt>)
>) Deri
Derive
ve di
dire
rect
ctio
ion
n fro
from
m gra
graph
phic
ical
al enti
entity
ty pick
picked
ed in the
the vvie
iew
w.

 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.
Picks Types Description.
[1] stdGraphics Pick graphical entity.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard Derive Direction Pick.

.k e y direction.
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] D
DIIRECTION Standard di
direction ob
object co
containing th
the di
direction o
off gr
graphical
item picked.

Met h o d Nam e Des c r i p t i o n

.m
.mea
easu
sure
reD
Dis
isttance
ance()
() Standa
andard
rd liline
near
ar meas
measur
ure
e of to deri
derive
ved
dppos
osit
itio
ions
ns..
Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition Positional pick, start of measure.

[2] stdPosition Positional pick, end of measure.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard Distance Measure.

 .k e y measureDistance.
.prompt Measure distance.
.input

3:37 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object, contains the start point and end point.
.length()
To extract the distance  is used on the element.

Met h o d Nam e Des c r i p t i o n

.measureAngle() Standard me
measure of
of an angle between three po
position iin
n
space.
Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition Positional pick, root of angle.

[2] stdPosition Positional pick, first point.
[3] stdPosition Positional pick, second pick.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard Angle Measure.

.k e y measureAngle.
.prompt Measure angle.
.input
Ret u r n A r r ay Des c r i p t i o n

[1] ARC Standard arc object, centred on the root of the angle. To
extract the angle .angle() is used on the element.

Met h o d Nam e Des c r i p t i o n

.m
.mea
easu
sure
reLi
Line
neAn
Angl
gle(
e()) Stand
tandar
ard
d mea
measu
sure
re of an angl
angle
ebbet
etwe
ween
en tw
two
o gra
graph
phic
ical
al line
line..
Pi c k s Ty p es Des c r i p t i o n

[1] stdGraphics Pick graphical line entity, first line.

[2] stdGraphics Pick graphical line entity, second line.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard Line Angle Measure.

.k e y measureLineAngle.
.prompt Measure angle between lines.
.input
 Ret u r n A r r ay Des c r i p t i o n

[1] REAL Angle between the two picked lines.

3:38 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Met h o d Nam e Des c r i p t i o n

.std
.stdPo
Posi
siti
tion
on(<p
(<prom
rompt
pt>)
>) St
Stan
anda
dard
rd deriv
derive
e posi
positi
tion
on from
from grap
graphi
hica
call pick
pick..
 Ar gu men ts Desc ri pt io n

<prompt> Primary display prompt.

Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition P o s i ti o n a l p i c k .
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard single position Pick.

.k e y stdPosition.
.input
Ret u r n A r r ay Des c r i p t i o n

[1
[1]] edg
edgPo
Posi
siti
tion
onDa
Data
ta Ev
Even
entt pic
picke
ked
d posi
positi
tion
on retu
return
rn obje
object
ct,, con
conta
tain
inss all
all pic
pickk data
data and
and
derived position from the pick.

Met h o d Nam e Des c r i p t i o n

.circle3Pnts() Define a circle (arc) through point in 3D space

Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition Positional pick, first point (start of arc).

[2] stdPosition Positional pick, second point (point on circumference).
[3] stdPosition Positional pick, third point (end of arc).

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Circle through 3 Points.
.k e y circle3Pnts.
.prompt Circle (three points).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

 Met h o d Nam e Des c r i p t i o n

.circleDia3D() D efine aby

defined ciraclthird.
e (arc) of diameter between two picks in a plane

Pi c k s Ty p es Des c r i p t i o n

3:39 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

[1] stdPosition Positional pick, first point (start of arc).

[2] stdPosition Positional pick, second point (diameter).

[3] stdPosition Positional pick, control point (Y).

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle derive diameter.

.k e y circleDia3D.
.prompt Circle (derive diameter).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.circleRad3D() Define a circle (arc) of radius between two p
piicks in a plane
defined by a third.
Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition P o s i ti o n a l p i c k , c e n tr e .
[2] stdPosition Positional pick, radius through point (X axes).
[3] stdPosition Positional pick, control point (Y).
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle centred, derived radius.

.k e y circleRad3D.
.prompt Circle (derive radius).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.ci
.circl
rcleFi
eFixRa
xRad3D
d3D(<an
(<any>)
y>) Define
Define a cir
circle
cle (arc)
(arc) with
with suppli
supplied
ed rradi
adius
us ccent
entred
red on the first
first
point, orientated by the second and third points.
 Ar gu men ts Desc ri pt io n
 <any> Any data type that must equate to a real value (radius).
Pi c k s Ty p es Des c r i p t i o n
[1] stdPosition P o s i ti o n a l p i c k , c e n tr e .

3:40 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

[2] stdPosition Positional pick, first control point (X).

[3] stdPosition Positional pick, second control point (Y).

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Circle Centre, defined radius.
.k e y circleFixRad3D.
.prompt Circle (defined radius).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.cir
.circl
cleF
eFix
ixDi
Dia3
a3D(
D(<an
<any>)
y>) Defi
De
firstfine
ne a cir
point, corientated
ircl
cle
e (arc
(arc)) by
with
with
thesup
suppl
plie
ied
secondd and
di
diame
amete
terr points.
third ce
centr
ntred
ed on
on th
the
e

 Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a real value (diameter).
Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition P o s i ti o n a l p i c k , c e n tr e .
[2] stdPosition Positional pick, first control point (X).
[3] stdPosition Positional pick, second control point (Y).
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle Centre, defined diameter.

.k e y circleFixDia3D.
.prompt Circle (defined diameter).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.c
.ciircle
rcleDi
Dia2
a2D
D(<
(<an
anyy>) Defi
Define
ne a ci
circ
rcle
le (ar
(arc)
c) wit
with
h d
dia
iame
mete
terr b
bet
etw
ween
een th
the
e tw
two
o pic
picke
ked
d
positions, mapped onto the passed plane.
  Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a plane object.

Picks Types Description.

3:41 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

[1] stdPosition Positional pick, first point (start & X axes).

[2] stdPosition Positional pick, second point (diameter).

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Circle derived diameter.
.k e y circleDia2D.
.prompt Circle (derived diameter).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.cir
.circl
cleR
eRad
ad2D
2D(<
(<an
any>
y>)) Deri
Derive
ve a mapped
positions, cir
circl
cle
e (ar
(arc)
c) with
ontowithe
th passed
radi
radius
us betw
betwee
een
plane. n tthe
he tw
two
o pic
picke
ked
d

 Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a plane object.

Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition P o s i ti o n a l p i c k , c e n tr e .
[2] stdPosition Positional pick, radius through point (X axes).
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle centred, derived radius.

.k e y circleRad2D.
.prompt Circle (derived radius).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.circleFixRad2D(<any>,<a Derive a circle (arc) with specified radius centred on the

ny>) picked positions, mapped onto the passed plane.
 Ar gu men ts Desc ri pt io n
 <any> Any data type that must equate to a plane object.
<any> Any data type that must equate to a real (radius).
Pi c k s Ty p es Des c r i p t i o n

3:42 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

[1] stdPosition P o s i ti o n a l p i c k , c e n tr e .
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle Centre, defined radius.

.k e y circleFixRad2D.
.prompt Circle (defined radius).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.circleFixDia2D(<any>,<an Derive a circle (arc) with specified diameter centred on the

y>) picked positions, mapped onto the passed plane.
 Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a plane object.

<any> Any data type that must equate to a real (diameter).
Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition P o s i ti o n a l p i c k , c e n tr e .
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle Centre, defined diameter.

.k e y circleFixDia2D.
.prompt Circle (defined diameter).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.c
.cir
ircl
cleF
eFilille
let(
t(<a
<any
ny>)
>) Deri
Derive
ve a ccir
ircl
cle
e (arc
(arc)) of
of su
supp
pplilied
ed radi
radius
us betw
betwee
een
n two
two pick
picked
ed
lines.
 Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a real (diameter).

 Pi c k s Ty p es Des c r i p t i o n

[1 ] p o s i ti o n L i n e a r Pick linear items and position on it, first line.

[2 ] p o s i ti o n L i n e a r Pick linear items and position on it, second line

3:43 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Fillet Circle of defined radius.

.k e y circleFillet.
.prompt Circle (Fillet).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.c
.cir
ircl
cleT
eTan
an3L
3Lin
ines
es()
() Deri
Derivve a ci
circ
rcle
le (arc
(arc)) whic
which
h is tange
angent
ntia
iall to the
the thre
three
e pick
picked
ed
graphical lines.
Pi c k s Ty p es Des c r i p t i o n

[1 ] p o s i ti o n L i n e a r Pick linear items and position on it, first line.

[2] po
positionLinear Pick lilinear iittems an
and position o
on
n itit, se
second liline.
[3 ] p o s i ti o n L i n e a r Pick linear iittems and position on itit, third line.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle tangential to 3 lines.

.k e y circleTan3Lines.
.prompt Circle (Tan. To 3 lines).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.cir
.circl
cleT
eTan
anT
Tan
an(<
(<any
any>)
>) Deriv
Derivee a ci
circ
rcle
le (arc)
(arc) of suppl
supplie
ied
d radi
radius
us whic
which
h is tang
tangent
entia
iall to
the two circular elements picked, with centre towards the
third positional pick.
 Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a real (radius).

Pi c k s Ty p es Des c r i p t i o n
 [1] positionArc Pick arc items and position on it, first circle.

[2] positionArc Pick arc items and position on it, second circle.
[3] stdPosition Position pick, centre side.

3:44 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle tangential to two other circles.

.k e y circleTanTan.
.prompt Circle (tangential).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.circlePntTan() Derive a circle (arc) with radius from first positional pick to
nearest tangent on picked circular element.
Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition Position pick, centre.

[2] positionArc Pick arc items and position on it, circle.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle, centred and tangential to another circle.

.k e y circlePntTan.
.prompt Circle (point - tangent).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.circleFRadP
.circleFRadPntT
ntTan(<an
an(<any>)
y>) Derive
Derive a circle
circle (arc) of specified
specified radius
radius which lies on the
the line
from the first positional pick to the centre of arc of the second
pick.
 Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a real (radius).

Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition Position pick, control point.

 [2] positionArc Pick arc items and position on it, circle.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Circle, centred and tangential to another circle of fixed
radius.

3:45 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

.k e y circleFRadPntTan.
.prompt Circle (point - tangent).

.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.circleFRadP
.circleFRadPntPnt(<
ntPnt(<any>)
any>) Derive a circle
circle (arc) of specifi
specified
ed rad
radius
ius tthat
hat p
passes
asses through
the first two positional picks, the third defines the direction of 
the "bulge".
 Ar gu men ts Desc ri pt io n

<any> Any data type that must equate to a real (radius).

Pi c k s Ty p es Des c r i p t i o n
[1] stdPosition Position pick, start point.
[2] stdPosition Position pick, end point.
[3] stdPosition Position pick, polar control point.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Circle, through 2 points + polar control point.

.k e y circleFRadPntPnt.
.prompt Circle (through 2 points).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.circleDerive() Derive a circle (arc) from the picked database element.

Pi c k s Ty p es Des c r i p t i o n

[1] dbCircle Pick database element that can be interpreted as an arc.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Derive a Circle from a db Element.

 .k e y circleDerive.
.prompt Circle (derived).
.input

3:46 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Ret u r n A r r ay Des c r i p t i o n

[1 ] A R C Standard arc object.

Met h o d Nam e Des c r i p t i o n

.pointPnt() Derive a point in space.

Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition P o s i ti o n p i c k .
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Define Working Point.

.k e y p o i n tP n t.
.prompt Working Point (position).

.input
Ret u r n A r r ay Des c r i p t i o n

[1] POSITION Standard position object.

Met h o d Nam e Des c r i p t i o n

.linePntPnt() Derive a line between two points in space.

Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition Position pick, start.

[2] stdPosition Position pick, end.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Line between two points.
.k e y linePntPnt.
.prompt L i ne.
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

 Met h o d Nam e Des c r i p t i o n

.lineAngl
ngle(
e(<
<any>) Derive a liline of
offs
fse
et by
by tth
he ssu
uppl i ed a
an
ngle ((ttowards tth
he fifirs
rstt
positional pick) starting at the second positional pick.
 Ar gu men ts Desc ri pt io n

3:47 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

<any> Any data type that must equate to a real (angle).

Pi c k s Ty p es Des c r i p t i o n

[1 ] p o s i ti o n L i n e a r Pi
Picck linear
ear items and position on it, line to be copie
pied.
[2] st
stdPosition Position p
piick, po
position a
an
ngle is
is tto
owards ((w
wrt to
to or
original).
[2] stdPosition Position pick, start position (copied line).
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Line offset by angle from another.

.k e y lineAngle.
.prompt Line (offset angle).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

Met h o d Nam e Des c r i p t i o n

.lineDerive() Derive a line from the picked database element.

Pi c k s Ty p es Des c r i p t i o n

[1] dbLine Pick database element that can be interpreted as an line.

Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Derive a line from a db element.

.k e y lineDerive.
.prompt Line (derive).

.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

Met h o d Nam e Des c r i p t i o n

.linePntTan() Derive a line between a point and the nearest tangent point
on a picked arc.
Pi c k s Ty p es Des c r i p t i o n
 [1] stdPosition Position pick, start.
[2] positionArc Pick arc items and position on it, circle/arc.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Line between point and tangent of arc.

3:48 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

.k e y linePntTan.
.prompt Line (point - tangent).

.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

Met h o d Nam e Des c r i p t i o n

.lineTanTan() Derive a line between the nearest tangent points on the arcs
pick.
Pi c k s Ty p es Des c r i p t i o n

[1] positionArc Pick arc items and position on it, first circle/arc.
[2] positionArc Pick arc items and position on it, second circle/arc.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Line between tangents of two arcs.

.k e y .lineTanTan.
.prompt Line (tangent - tangent).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

Met h o d Nam e Des c r i p t i o n

.lineBisect() Derive a line that bisects the two lines picked.

Pi c k s Ty p es Des c r i p t i o n

[1 ] p o s i ti o n L i n e a r Pick linear iittems and position on it, first line.

[2] po
positionLinear Pick lilinear iittems an
and position o
on
n itit, se
second liline.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description L i n e b i s e c ti o n tw o l i n e s .
.k e y .lineBisect.
.prompt Line (bisect).
 .input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

3:49 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Met h o d Nam e Des c r i p t i o n

.lineTwoPlanes() Derive a line at the inter

tersection of the two picked plane.
Pi c k s Ty p es Des c r i p t i o n

[1 ] p o s i ti o n P l a n e Pick planar items and position on it, first plane.

[2 ] p o s i ti o n P l a n e Pick planar items and position on it, second plane.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Line at intersection of 2 planes.

.k e y lineTwoPlanes.
.prompt Line (2 planes).
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

Met h o d Nam e Des c r i p t i o n

.lineShortest() Derive the shortest line between two graphical entities,

parallel items will start at the position of the first pick.
Pi c k s Ty p es Des c r i p t i o n

[1] stdGraphics Pick graphical entity, from.

[2] stdGraphics Pick graphical entity, to.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Standard Parallel Distance Measure.

.k e y .lineShortest.
.prompt Measure distance.
.input
Ret u r n A r r ay Des c r i p t i o n

[1 ] L IN E Standard line object.

Met h o d Nam e Des c r i p t i o n

 .plane3Pnts() Derive a plane that passes through the three positions
picked.
Pi c k s Ty p es Des c r i p t i o n

[1] stdPosition Position pick, first point (centre of the plane).

3:50 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

[2 stdPosition Position pick, second point (X axes).

[3 stdPosition Position pick, third point (Y axes).
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s
.description Plane through 3 Positions.
.k e y plane3Pnts.
.prompt Plane (three points).
.input
Ret u r n A r r ay Des c r i p t i o n

[1] PLANE Standard plane object.

Met h o d Nam e Des c r i p t i o n

.plane
.plane2Pnt
2Pnts(<
s(<pos
positi
ition>)
on>) Derive
Derive a plan
planee that
that is cen
centre
tred
d o
on
n the
the passed
passed pos
positio
ition
n a
and
nd
orientated to the two positional picks.
 Ar gu men ts Desc ri pt io n

<position> Position of plane origin.

Picks Types Description.
[1] stdPosition Position pick, X through point.
[2] stdPosition Position pick, Y through point.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Plane through 2 Positions (supplied position is centre).

.k e y plane2Pnts.

.prompt Plane (two points).

.input
Ret u r n A r r ay Des c r i p t i o n

[1] PLANE Standard plane object.

Met h o d Nam e Des c r i p t i o n

.planeDerive() Derive a plane from the picked database element.

Pi c k s Ty p es Des c r i p t i o n
 [1] dbPlane Pick database element that can be interpreted as an plane.
Pi c k Pa
Pac k et Me
Mem b er s Set t i n g s

.description Derive a plane from a db element.

.k e y derivePlane.

3:51 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

.prompt Derive plane.

.input
Ret u r n A r r ay Des c r i p t i o n
[1] PLANE Standard plane object.

Note: When defining pick packets using the above methods, the method should be applied
to the object before any of the other members are set, as the methods will overwrite
several of the pick packet members.

3.11.2 Exa
xample
mples
s (D
(De
efining P
Pick
ick S
Se
eque
quence
nces)
s)
The following are some examples and description of using some of the basic pick packet
methods and defining event pick sequences that are not catered for by the standard
methods.
Note: The definitions of the event packets that the pick packet is to be applied to are not
shown. See below for how the pick packet can be defined with respect to an event
packet (refer to Examples (Using Pick Packets).
Standard
Standard Element
Element Method
Method
The Standard Element Method example shows how to use the standard element pick
sequence, the same sequence can be applied to any of the other standard events.

-- Define pick packet

!p
!pic
ickP
kPac
acke
kett = obj
objec
ectt EDG
EDGPI
PICK
CKP
PACKE
ACKET(
T())

-- Define line between two points

!pickPacket. stdElement ('Pick element')

Standard
Standard Lin e between
between two p oint Method
The Standard Line between two point Method example shows how to define a pick that
derive a line between two points within 3D space, the resultant line can then be used for any
linear based item, SCTN, line, distance measurement. In this example we've change the
prompt so that we are asking to defined a linear measurement, this is basically the same as
the standard .measureDistance()  method is defined.

-- Define pick packet

!p
!pic
ickPa
kPack
cket
et = ob
obje
ject
ct EDGPI
EDGPICK
CKP
PACKET
ACKET()
()

-- Define line between two points

!pickPacket.linePntPnt()
 -- Modify the prompt
!t
!thi
his.
s.pr
prom
ompt
pt = 'M
'Mea
easu
sure
re di
dist
stan
ance
ce''

3:52 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

Element-Position Picking
The Element-Position Picking example shows how the developer can define a pick
sequence that firstly asks for an element to be picked, then for a derived position to be
picked.
This type of pick sequence can be used to identify an element, then reposition it in a new
place.

-- Define pick packet

!pickPacket = object EDGPICKPACKET()

-- Define information
!pickPacket.key = 'el
'element-position'
!pickPacket.description = 'Pick an element then a positions'

-- Define primary prompt

!p
!pic
ickP
kPac
acke
ket.
t.pr
prom
ompt
pt = ''Mo
Move
ve el
elem
emen
ent'
t'

-- Declare first pick (element)

!p
!pic
ickPa
kPack
cket
et.p
.pic
icks
ks[1]
[1] = ob
obje
ject
ct EDGPI
EDGPICKCKTYP
TYPE(
E())
!pickPacket.picks[1].stdElement('(Pick element to move)')

-- Declare second pick (position)

!pickPacket.picks[2] = object EDGPICKTYPE()
!pickPacket.picks[2].stdPosition('(New position)')

Note: No action is carried out within the pick packet, therefore, all the data will be returned
from each of the pick and will be passed back up the event system to the event
packet unmodified.

Definin
Definin g Fixed Radius Circl e
The Defining Fixed Radius Circle example shows how a fixed radius circle can be defined
so that the radius can be defined via an input gadget of a form, even after the event packet
has been placed on the event system.

-- Check to make sure controlling form has been defined

if(undefined(!!xxxRadius)) then
pml reload form !!xxxRadius
endif

-- Define pick packet, passing pointer to value of the text

 Define pick packet, passing pointer to value of the text
-- input gadget of the controlling form

!packet.pickPacket.circleFixRad3d('!!xxxRadius.radius.val')

3:53 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Note: If the pointer to the gadget was unquoted, i.e. passed as a REAL value. The current
value of the form gadget would be used and changing the value on the form would
have no effect when the pick packet action is executed.

Whereas, passing the pointer to the form gadget as a string, take the string and
evaluate it at the action time.

3.11.3 Exa
xample
mples
s ((U
Using Pick Packe
ckets)
ts)
The following examples show how a pick packet can be either defined directly to an event
packet (edgPacket ) or defined as a method against an object or form to be applied to an
event packet within a utility.
utility.

 Ap pl ied to an Ev ent Pack et

The Applied to an Event Packet example shows how a standard pick packet can be defined
while defining an event packet.

-- Define event packet

!packet = ob
object EDGPACKET(
ET()

-- Set Members
!p
!pac
acke
ket.
t.de
desc
scri
ript
ptio
ion
n = 'T
'Tes
estt Pa
Pack
cket
et''
!packet.key = 'testPacket'
!packet.priority =1

-- Defines action on completion of the pick

!packet.action ='!action(!this.return[1])'

-- Define pick sequence

!packet.pickPacket.stdElement('Pick Element')

-- Add event packet to the system

!!edgCntrl.add(!packet)

The pick packet definition can be either done using a standard method on the object (as
above) or defined fully, where there is no standard method.

Method Definition
The Method Definition example is where an object/form has a method(s) that defines a pick
packet sequence that can be applied to a standard event packet within the object/form.
The following is the definition of the method that defines the pick packet:
 Method Definition

3:54 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

-- Define Method

define method .elementMove() is EDGPICKPACKET

-- Define pick packet

!pickPacket = object EDGPICKPACKET()

-- Define information
!pickPacket.key = 'element-position'
!pickPacket.
!pickPacket.descri
description
ption = 'Pick an element
element then a positions'
positions'

-- Define primary prompt

!pi
picckP
kPac
acke
ket.
t.pr
prom
ompt
pt = 'Mo
'Move
ve el
elem
emen
ent'
t'

-- Declare first pick (element)

!p
!pic
ickPa
kPack
cket
et.p
.pic
icks
ks[1
[1]] = objec
objectt EDGPIC
EDGPICKTY
KTYPE(
PE())
!pickPacket.picks[1].stdElement('(Pick element to move)')

-- Declare second pick (position)

!pickPacket.picks[2] = object EDGPICKTYPE()
!pickPacket.picks[2].stdPosition('(New position)')

-- Return
return !pickPacket

-- End method definition

endmethod

The following is an extract on how the above method would be used within the owning
object/form:
 3:55 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

-- Define Packet

!packet = object EDGPACKET()

.
.
.

-- Test for method

if(!option eq 'MOVE") then
!packet.p
!packe t.pick
ickPack
Packet
et = !this.
!this.ele
elemen
mentMo
tMove()
ve()
else
!pac
!packe
ket.
t.pi
pick
ckPac
Packe
kett = !!th
this
is.e
.ele
leme
ment
ntBY(
BY())
endif 

-- Add event to the system

!!edgCntrl.add(!packet)
-

3.11.4 Lim
Limit
ita
atio
tions
ns and Restr
strict
iction
ionss
The current event packet object only contains a basic set of pick sequence definitions, but it
is thought that these should allow the developer a broad set that they can use with little or 
no modification
Currently many of the utilities within the standard AppWare use these methods in their 
interaction with, e.g. 3D Construction Aids, Measurement utilities, etc.
Similar to the event packet, modifying the original definition of a pick packet WILL NOT
update the definition, once it has been placed on the event stack.

3.12 Pick Type

Type (edgPick
dgPickTType)
ype)
The pick type object defines the basic types of picks that can be performed by the system.
Whereas the pick packet defines how many and what types of pick are required for a pick
sequence.
There are two main objects the pick type object returns to the calling objects, these are:
• edgPickData   this object contains all the information about the pick on the graphical
canvas, without the data being post processed to derive a position, etc.
• edgPositionData  this object is basically the same data as the edgPickData   but the
data has been processed either by the edg positioning control object, to determine the
derived position of the picked item or the position picked on the items has been derived
using some basic rules.
 In some instances, certain pick type methods return only a basic object, e.g.
POINTVECTOR, etc.

This section of the document DOES NOT give a detailed explanation of the members and
principles of this object. As in most cases, changing any of the members will seriously affect
the workings of the object.

3:56 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

3.12.1 Pub
ubli
lish
sheed IInt
nteerf
rfaace
The following are the main basic types of method interface into the pick type object.

All "<prompts>" are secondary prompts, these are displayed on the prompt line of the
graphic views after the primary prompt which is defined in the pick packet object. These are
used to signify which prompt within the prompt sequence the user is up to.

Position Picking
The following methods are used to define a specific type of filtered pick which returns an
edgPositionData object, the position member of the return object is populated:

Nam e Acti on

stdPosition(<prompt>) Standard positioning pick type, derives the position from

the graphical pick (pick type and method are controlled by
the positioning control form).
The initial position derived, will then be mapped against the
active working plane (when set) then the currently defined
offset method will be applied to the position.
positionLinear(<prompt>) Positioning pick for linear elements, converts picked item
into a linear element, then derives the position on the linear 
item.
positionArc(<prompt>) Positioning pick for arc elements, converts the picked item
into an arc, then derives the position on the arc.
positionPlane(<prompt>) Positioning pick for plane elements, converts the picked
item into a plane, then derives the position onto the plane.

General
General Item Pickin g
The following methods are used to define a specific type of filtered pick which returns an
edgPickData  object.

Nam e Act ion

stdElement(<prompt>) Standard element pick type, this will only pick database
element in the graphic views.
By default the standard element filters will be applied to the
pick, only allowing those elements that conform to the define
rule for the filter.
stdAny(<prompt>) Standard any pick type, this will allow elements, plines,
ppoints and graphical aids to be in the graphic views.
By default all the standard filters will be applied to the pick.
stdPpoint(<prompt>) Standard element pick type, this will only allow elements
 containing ppoints or design points to be picked in the
graphic views.
By default the standard ppoint filters will be applied to the
pick.

3:57 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

stdPline(<prompt>) Standard element pline type, this will allow only elements that
have plines to be picked from in the graphic views.

By default the standard pline rules will be applied.

stdAid(<prompt>) Standard Aid element pick type, this will allow all graphical
aids to be picked from the graphical views. However, graphic
aids not registered within the "Construction Aid" utility will
return an error.
stdScreen(<prompt>) Standard screen pick, this will allow a pick anywhere within
the graphical view to be performed. This can considered as a
2D pick within the 3D view.
stdGraphics(<prompt>) Standard graphics pick, this will allow any graphical entity to
be picked within the graphics view, i.e. database element,
graphical aid, ppoint or pline. All elements, will be
decomposed into one of three basic types:
vertex
vertex single
single p
poin
ointt at the cconv
onverg
ergence
ence o
off edges
edges

edge
edge boun
bounda
dary
ry bet
betwe
ween
en fa
face
cets
ts
face
facett pl
plan
anar
ar surf
surfac
acee of
of an
an item
item

Database Element Interpretation

The following methods are used to define a specific type of filtered pick which returns an
edgPositionData  object, however, the position member of the return object is NOT
populated:

Nam e Act ion

dbLine(STRING) Setup for picking a linear db item, this will always try and
convert the picked database element into a line. The method
will try and populate the .line member of the return object.
dbCircle(STRING) Setup for picking a circular db item, this will always try and
convert the picked database element into an arc. The
method will try and populate the .arc   member of the return
object.
dbPlane(STRING) Setup for picking a plane db item, this will always try and
convert the picked database element into a plane. The
method will try and populate the .plane  member of the return
object.

Miscellaneous
The following methods are used to define a specific type of filtered pick which returns an
edgPositionData  object, however, the position member of the return object is NOT
populated:
 Nam e Act ion

stdView(STRING) Standard view pick, this returns the view gadget the pick is
performed in.

3:58 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

3.12.2 Ex am p l es
As there is not member that should be defined by the developer, the example for the
definition of pick packets will suffice as on how to use the pick type methods. Refer to
Examples (Defining Pick Sequences).

3.12.3 Lim
Limit
ita
atio
tions
ns and Restri
stricti
ctions
ons
The current pick type object contains only the basic pick types. Other pick types of more
complexity will be required for better interaction, however, this will only be possible with
enhancements to the underlying core facilities.

3.13 Pi ck
ck (ed gP
gPi c k)
k)
The event pick is the lowest component of the event system, this object maps directly onto
the underlying core event handlers.
The majority of the members and methods are private to the object and the event system,
and should never need to modify by the developer. However, there are two members that
the developer may wish to change for special types of picking, these are to control the
filtering of the picks.

3.13.1 Pi ck
ck Fi lt
lt eri
erinng
There are two members that are used to control the pick filtering:

.input This is an array member, containing the qualifiers used to define the
filtering when picking from the graphics view. Each element of the
array relate to a specific type of item, which can be picked, these
are:
[1] Pline, filter applied to display only plines of structural elements
that conform to the defined rule.
[2] Ppoint , filter applied to display only ppoint of elements that
conform to the defined rule.
[3] Element , filter applied to only allow elements that conform to the
defined rule to be picked.
[4] Design Aid , filter applied to only allow design aids that conform
to the defined rule to be picked.
[5] Tubing , filter applied to only allow implied tubing conforming to
the defined rule to be picked.
[6] Graphical Entity, allow only the graphical entities defined in the
member to be pick, these are, VERTEX, EDGE or FACET. If no
entry is defined, then all graphical entities are pickable.
 Note: The filtering rules are evaluated as the cursor passed the
item in the graphic view.

3:59 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Rules for design elements and tubing are evaluated on only the
design element that can be picked, primitive, piping component,
SCTN, etc. Whereas the rules for ppoints and plines are evaluated
at the point of definition, i.e. on the catalogue definition of them, this
means that information pertaining to the ppoint or pline when in the
design space CAN NOT BE USED.
Element rules are always evaluated before the ppoint and pline
rules, therefore, if an element rule excludes anything that has a
pline, e.g. TYPE eq 'BOX', then the user will not be able to select a
element to pick.
.modifiable If this member is set to true this applies the standard filter to the pick
when the pick becomes active. When false, the currently defined
local rules within the .input  member are used.
Note: If you have defined some input rule, this member MUST BE
set to false, otherwise the rules defined within the standard
filtering utility will over-ride the settings when the pick
becomes active.

3.13.2 Rule
ule Combi
ombina
natio
tion
n
The following table show the rules can be used together:

Pl i n e Pp o i n t El em en t Aid Tu b i n g Gr a p h i c s

Pline y es y es
Ppoint y es y es
Element y es y es y es y es
 Ai d yes
Tubing y es y es
Graphics y es y es y es yes y es

Even though some combination of rules are permissible, the actual usefulness of the
combination is limited.
Note: Dependent on the underlying pick method used, some of the rules will have no effect,
e.g. setting a graphic pick filter when using the pick elements handler, has not
meaning.
 3:60 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

3.13.3 Pub
ubli
lish
sheed IInt
nteerf
rfaace
The following are the two members of the pick object used to control the pick filtering:

Nam e Ty p e A c tio n

.input ARRAY Picking qualifiers to restrict the data that can be

graphically picked.
.modifiable BOOLEAN True if the ssttandard filtering utilities are to be
applied to the pick when it is active or added
onto the pick stack.

3.13.4 Ex am p l es
The following are examples show how to set the pick filter, the first example shows how the
filter is set from the event packet level. All subsequent examples show what filter rules that
can be applied.

Setting Filter fro m Event Packet

The Setting Filter from Event Packet example shows how the element filter can be set, so
that only element beneath an equipment or sub-equipment can be picked.

-- Define event packet

!packet = ob
object EDGPACKET(
ET()

-- Define standard element pick

!packet.elementPick('Pick Element')

-- Define Rule
!rule = 'T
'TYP
YPE
E of OWNER inset (|EQUI|,|SUBE|
BE|)'

-- Set the pick filter for element to only equip and subequip
!packet.pickPacket.picks[1].pick.input[3] = !rule

-- Set the modifiable flag, so that the rule is used

!packet.pickPacket.picks[1].pick.modifiable = false

-- Add event packet to the system

!!edgCntrl.add(!packet)
 Note: As only certain element types can be actually picked from the graphic canvases, e.g.
primitives, tubing, etc. Then the rule MUST in this case check whether the parent of 
the element is either an equipment or sub-equipment.

3:61 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Filter Plines for Structural Beams

The following example shows how a pick filter can be setup, so that only certain plines of 
structural sections (SCTN and GENSEC) flagged as a BEAM are allowed to be picked.
The example could be used to pick only the plines on beam section that are on the outer 
faces of flange or wed.

-- Define Element Rule

!e l e m e n t = 'TYPE of OWNER inset (|SCTN|,|GENSEC|) and $
 GTYPE eq |BEAM|'

-- Define Pline Rule

!pline = 'PKEY inset (|TOS|,|BOS|,|NAR|,|NAL|)'

-- Set the pick filter for element to only equip and subequip
!packet.pickPacket.picks[1].pick.input[1] = !pline
!packet.pickPacket.picks[1].pick.input[3] = !element

-- Set the modifiable flag, so that the rule is used

!packet.pickPacket.picks[1].pick.modifiable = false

Note: The pline rule relates to the attribute that is on the catalogue definition of the section
profile.

Filter Tubing
Tubing for Br anches
The following example show how a pick filter can be defined to allow only vertical legs in a
pipe branch which are have a tube length greater than a specific value.
This example might be used when trying to insert a check valve, of a given length, in the
vertical leg of a pipe, which includes a clearance on either side of the valve.
 3:62 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

-- Define Element Rule

!e l e m e n t = 'TYPE eq |TUBING|'

-- Element Length + Clearance

!l e n g th = !!vvalveLength + !clearance * 2

-- Define Tubing Rule

!t
!tub
ubin
ing
g = ''GR
GRAD
ADIE
IENT
NT eq 1000
100000
00 and
and ITL
ITLEN
ENG
GTH gt ' & !len
!lengt
gth
h
 
-- Set pick filters
!packet.pickPacket.picks[1].pick.input[3] = !element
!packet.pickPacket.picks[1].pick.input[5] = !tubing

-- Set the modifiable flag, so that the rule is used

!packet.pickPacket.picks[1].pick.modifiable = false

Note: The rule (expression) must always be defined as a string.

3.13.5 Lim
Limit
ita
atio
tions
ns and Restri
stricti
ctions
ons
Currently there is no interface to set the filter rules from any other level within the system,
e.g. from event packet, pick packet or pick type objects. The filter has to be set using all the
variable parentage.

3.14 Pick Data (edgPickD

dgPickDa
ata)
ta)

The pick Whereas

handler. data object
thebasically maps
underlying on the
system returnthe
returns datapick
object
dataofvia
thean
underlying
array, thecore
pickevent
data
object assigns the data to members with some meaningful names.

3.14.1 Pub
ubli
lish
sheed IInt
nteerf
rfaace
The pick data object can be classed as being only a read-only objects, as setting the
members within the object will have no effect on the operation of the event picking.

Method
The pick data object only has one method, this returns the pick data object as a picked
position object.
 Nam e Res u l t Action

.positionData() ed
edgPo
gPosi
sitio
tionD
nDat
ata
a Conv
Convert
ertss the
the pick
pick dat
data
a in
into
to a sta
stand
ndar
ard
d ev
even
entt
position data object.

3:63 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

Members (General Picks)

The following are the definition of the members that are common to all the available picking
types:

Nam e Ty p e Action

.type STR
STR IN G Bas
Basic type o
off p
piick on the
the graphics canvas, e.g
e.g.
ELEMENT,, PLINE, PPOINT
ELEMENT PPOINT,, etc., etc.
.tubing STRING Tube type adjacent to the .item  member, i.e. HEAD or 
LEAVE.
.item DBREF Database element picked.
.point REAL Ppoint or graphical aid number picked.
.pline STRING Structural pline picked.
.aidType STR
STR IN G Basic gr
gra
aphi c al aid
aid type pick
cke
ed, e .g . LINE
INE,
CYLINDER, etc.

.pickLine POINT- Pick vector when picking an item, i.e. direction of view
VECTOR and the position of the direction on the viewing plane.

Members
Members (Graphic Entity Picks )
The following are the definition of the members that are only populated by the graphical
entity picks, these members define the basic graphical components of the item under the
pick cursor:

Nam e Ty p e Action

.vertexCount REAL Number of vertices, usually only 1, zero if a graphical

edge or facet is picked.
.vertices ARRAY Position of vertex picked.
.lineCount REAL Number of edges/lines at the vertex point, 1 if only a
graphical edge is picked, zero if a facet is picked.
.lines ARRAY Paired po
positions d
de
e fi n i n g e
ea
ach ed
edge/line.
.facetCount REAL Number of facets bounding the picked line or vertex,
1 if only a facet is picked.
.facets ARRAY Positions
ons of eac
each of the
the corners
ners of the
the facets, four
our per 
facet.

3.15 Picked
icked Position
Position Data (edgPositionD
dgPositionDa
ata)
ta)
The Pick Position Data object basically maps on the return data object of the underlying
 core event handler. Whereas the underlying system returns the pick data via an array, the
pick data object assigns the data to members with some meaningful names.

3:64 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
Event Driven Graphics

3.15.1 Pub
ubli
lish
sheed IInt
nteerf
rfaace
Similar to the pick data object, this object can be classed as being only a read-only objects,
as setting the members within the object will have no effect on the operation of the event
picking.

Members
The following are the definition of the members:

Nam e Ty p e Ac tion

.type STRING The is normally the same as the original type, but
in certain instances the can be changed by some
secondary process.
.originalType STRING Basic type of pick on the graphics canvas, e.g.
ELEMENT,, PLINE, PPOINT
ELEMENT PPOINT,, etc., etc.
.position POSITION Derived position.

.direction DIRECTION Derived di

direction.
.pointVector  POINTVE
POINTVECT
CTOR
OR Pick
Pick vecto
vectorr when
when pick
picking
ing an iitem
tem,, i.e.
i.e. d
dire
irecti
ction
on o
of 
f 
view and the position of the direction on the
viewing plane.
.line L IN E Picked element interpreted as a line.
.plane PLANE Picked element interpreted as a plane.
.arc ARC Picked element interpreted as a arc.
.item DBREF Item picked, in case of multiple pick the last item.
.items ARRAY All items picked in the pick.
.ppoint REAL Ppoint or graphical aid number picked.
.pline STRING Structural pline picked.
.tubing STRING Tube type adjacent to the .item   member, i.e.
HEAD or LEAVE.

Methods
There are several methods avail these are:

Nam e Res u l t Action

.line() MODIFIES Evaluate line definition for current data.

.arc() MODIFIES Evaluate arc definition for current data.
 .plane() MODIFIES Evaluate plane definition for current data.
.getline() LINE Return evaluated line definition for current data,

without modifying the member.

3:65 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
Event Driven Graphics

.getarc() ARC Return evaluated arc definition for current data,

without modifying the member.

.getplane() PLANE Return evaluated plane definition for current data,

without modifying the member.
 3:66 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

 A PML 1 Exp
Exprr es
esssions

This appendix explains the PML 1 expressions package. These facilities are needed within
AVEVA
AVEV A products, for example, to define report templates in PDMS.
Note: Generally
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 + t ex
ext 1 $

However, both of the following expressions are valid:

x +y $ adds the values of the numeric variables.

 Text 1 + t ext 2 $ concatenates the two text strings.

The following types of expressions are available:

Expression
Logical Expressions
Logical Array Expressions
Numeric (Real) Expressions
Real Arrays
Text Expressions

 A.1
 A .1 For
Fo r m at o f Exp
Ex p r ess
es s i o n s
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:

‘ Th
Thi s i s t ex
ext ’

 A: 1 12 Series

 Soft ware Customis ation Reference

Reference Manual
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:

SI N( 30)

In general, you do not need spaces before or after brackets, except when a 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 )

 A.1.1 Oper
Operato
ato r Pr eced enc e
Operators are evaluated in the order of the following list: the ones at the top of the list are
evaluated first.

Op er at o r Co m m en ts

BRACKETS 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

 A.1.2 Nest in g Ex pr ess

essio
io ns
Expressions can be nested using brackets. For example:

( ( SI
SI N(
N( ! angl eA) * 2) / SI N(
N( ! angl eB) )
  A.2
 A .2 L o g i c al Exp
Ex p r ess
es s i o n s
Logical expressions can contain:
• Attribu
Attributes
tes of typ
type
e logic
logical
al e.g.
e.g. BUIL
BUILTT.
• Logical constants.
constants. The co
constant
nstantss available
available are: TRUE,
TRUE, ON
ON,, YES for
for true
true,, and FAL
FALSE,
SE,
OFF,, NO for false.
OFF

 A: 2 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

• Logi
Logiccal ope
operator
orss.
• Logi
Logiccal fu
functions.

 A.2.1 Lo gi cal Oper

Operato
ato rs
The logical operators available are:

Op er at o r Co m m en ts

AND
EQ, NE The operators EQ and NE may be applied to any pair  
of values of the same type.
GT, GE, LE, LT 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 .

NOT
OR

Note: The operators EQ,

E Q, NE, LT,
LT, GT,
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 l og1
og1 AND l og2
og2 - > l ogi
ogi cal
Description Perform the logical AND between two logical values. Treats
unset values as FALSE.
Side Effects If one of the values is undefined and the other one is FALSE,
the result is FALSE.
Example  TRU
 TRUE and FALSE - > FALSE
  A: 3 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

EQ and NE

Synopsis ( number 1 EQual number 2) - > l ogi cal

cal
( t ext 1 EQual t ex
ext 2 ) - > l ogi c al
( lo
og
g1 EQual l og
og2 ) - > l og
ogi c
caal
( i d1 EQual i d2 ) - > l ogi cal
cal
( pos 1 EQual po
pos 2 ) - > l og
ogi ca
c al
( di r 1 EQual di r 2 ) - > l ogi cal
cal
( or i 1 EQual or i 2 ) - > l ogi cal
cal
( pp1 EQual pp
pp2 ) -> l o
og
gi ca
cal
( number 1 NEqual number 2 ) - > l ogi cal
cal
( t ex
ext 1 NEqual t ex
ext 2 ) - > l ogi c al
( l og
og1 NEqual l o
ogg2 ) ->lo
oggi c
caal
( id
d1
1 NEqual i d2
d2 ) - > l og
ogi ca
cal
( po
pos 1 NEqual pos 2 ) - > l ogi c al
( di r 1 NEqual di
di r 2 ) - > l og
ogi ca
c al
( or i 1 NEqual or
or i 2 ) - > l og
ogi ca
c al
( pp1 NEqual pp
pp2 ) - > l og
ogi ca
c al
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.
Side Effects If two positions have no common coordinate, for example,
’ N 10 ne U 10’ , the result is undefined. Units are
consolidated across comparisons.
Example ( 1. 0 eq 2.
2. 0) - > FA
FALS
LSE
E
Errors None.
  A: 4 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

GT, GE, L E and

an d LT

Synopsis ( num
number 1 GT num
number 2 ) > l ogi cal
( pos1 GT pos2 ) > l ogi
ogi cal
( number 1 GE number 2 ) > l ogi c al
( pos 1 GE pos 2 ) > l ogi c al
( number 1 L E number 2 ) > l ogi c al
( pos 1 L E pos 2 ) > l ogi c al
( number 1 L T number 2 ) > l ogi c al
( pos 1 L T pos 2 ) > l ogi c al
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
Side Effects If two positions have no common coordinate, the result is
undefined. For example, ’ N 10 gt U 10’.
Units are consolidated across comparisons.
Example ( 1. 0 LT 2.
2. 0) - > TR
TRU
UE
( N 0 E 10 GT N 10 E 0 ) - > FALSE
( N 0 E 10 GT N 10 E 0 ) - FALSE
Errors None.

NOT

Synopsis NOT l og1 - > l ogi c al

Description Perform the logical NOT on a logical value.
Side Effects None.
Example not TRU
TRUE - > FALSE
Errors None.
  A: 5 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

OR

Synopsis OR l og2 - > l ogi c al

Description 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 If one of the values is undefined and the other one is TRUE,
the result is TRUE.
Example  TRU
 TRUE or FALSE - > TRU
TRUE
Errors None.

 A.2.2 Lo gi cal Fun ct io ns

The logical functions available are:

Fu n c t i o n Co m m en ts

BADREF
DEFINED,UNDEFINED
CREATED
DELETED
EMPTY
MATCHWILD
MODIFIED
UNSET
VLOGICAL

BADREF

Synopsis BADREF ( i d) - > l ogi c al

Description TRUE if id  is invalid, else FALSE.
Side Effects None
 Example BADREF( TRE
TREF) -> t r ue i f TRE
TREF=nul r ef 
Errors None.

 A: 6 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

DEFINED and UNDEFINED

UNDEFINED

Synopsis DEFi ned ( va

v ar i abl e_ na
name) - > l ogi c al
DEFi ned
ned - > l ogi cal
cal
( var i abl
abl e_nam
e_name, num
number
ber )
UNDEFi ned ( var
var i abl
abl e_nam
e_name) - > l ogi
ogi cal
UNDEFi
EFi ned
ned ( var i abl
abl e_nam
e_name , - > l ogi cal
cal
number )
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.
UNDEFI NED( ! f oo ) i s equ
equi val
val ent
ent t o NOT
DEFI NED( ! f oo ) .
Side Effects None.
Example DEFI NED ( ! var ) - > TRU
TRUE
DEFI NED ( ! ar r ay ) - > TRU
TRUE
DEFI NED ( ! ar r ay[
ay[ 1] ) ) - > TRU
TRUE
DEFI NED ( ! ar r ay , 1 ) - > TRU
TRUE
DEFI NED ( ! var ) - > FALSE
FALSE
UNDEFI NED ( ! ar r ay) - > TRU
TRUE
DEFI NED ( ! ar r ay , 3 ) - > FALS
FALSE
E
Errors None.

CREATED

Synopsis CREATED - > l ogi c al

Description Returns TRUE if the element has been created since the set
date.
Side Effects None.
Example CREATED - > TRUE
 Errors None.

 A: 7 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

DELETED

Synopsis DEL ETED - > l ogi c al

Description Returns TRUE if the element has been deleted since the set
date.
Side Effects None.
Example DEL
ELETE
ETED
D - > TRUE
Errors None.

EMPTY

Synopsis EMPTY( t ext ) - > l ogi c al

Description Returns TRUE if text is a zero length string, else FALSE
Side Effects None.
Example EMPTY(
PTY( ‘ ’ ) - > TRU
TRUE
EMPTY(
PTY( ‘ not
not empt y’ ) - > FALSE
FALSE
Errors None.

MATCHWILD

Synopsis MATCHW/ I L D( t ext 1, t ext 2) - > l ogi c al

MATCH
TCHW/ I LD(
LD( t ext
ext 1, t ext
ext 2, - > l ogi cal
cal
t ext 3)
MATCH
TCHW/ I LD(
LD( t ext
ext 1, t ext
ext 2, - > l ogi cal
cal
t ext 3, t ext 4)
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

 A: 8 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

Example MATCH
TCHW/ I LD(
LD( ’ A bi g bot t l e of
beer ’ , ’ *bi
*bi g*’ ) - > TRUE

M
bA
eTCH
TC
er H
’W, /’ ??bi
I??b
LD(
LD(i ’gA
*’ b
)i g
- >bT
otRU
tE
l e of
MATCH
TCHW/ I LD( LD( ’ A bi g bot t l e of
beer ’ , ’ ???*b
???*bii g*’ ) - > FALS
FALSEE
MATCH
TCHW/ I LD( LD( ’ A bi g bot t l e of
beer ’ , ’ *bi
*bi g*be
*beer ’ ) - > TRUE
MATCHW/ I LD( ’ ** t ext ’ , ’ **! ’ , ’ ! ’ ) - > TRUE
Errors None.

MODIFIED

Synopsis
.-----------------------------------.
/ |
>- MODI FI ED- ( - +- att name - - - - - - - *- DESCENDANTS - - +- +- co com mma +- at t name - ’
| | | |
| - DESCENDANTS - . | - SI GNI FI CANT - - | |
| | | | |
| - SI GNI FI C CA ANT- - | | - PRI M MA ARY - - - - - | |
| | | | |
| - PRI MARY - - - - - | | - OF FSPRI NG- - - - - | |
| | | | |
| - OF FSPRI NG NG - - - | ‘ - - - - - - - - - - - - - - - - ’ |
| | |
| | |
| | |
‘ - - - - - - - - - - - - - - - +- - - - - - - - - - - - - - - - - - - - +- - +- - ) - OF - i d
|
‘-

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
OFFSPRING
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, this element and everything below
(descendants).
 The OF syntax may be used as for attributes.
The MODIFIED function or the GEOM, CATTEXT and
CATMOD pseudo-attributes can be used instead of the
AFTERDATE function. Refer to the Data Model Reference
Manual.

 A: 9 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

The MODIFIED, DELETED and CREATED functions may go

anywhere within a PML1 expression. i.e. after Q/VAR and
within collections
Side Effects None
Example Q MODI FI ED(
ED( ) 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 MODI FI ED( POS,
POS, ORI ) Returns TRUE if POS or ORI
modified since the comparison
date.
Q MODI FI ED(
ED( P1 POS)
POS) Returns TRUE if the position of 
P1 has changed.

Q MODI FI ED(
ED( GEOM
EOM Returns TRUE if any geometry
DESCENDANTS for item or any descendants
has changed
Q MODI FI ED(
ED( PRI MARY)
ARY) Returns TRUE if any element
for which this element is
primary, has changed.
Q MODI FI ED( ) OF / Returns TRUE if /PIPE1 has
PI PE1 been modified since the
comparison date.
Q ( BUI L OR
OR
MODI FI ED(
ED( ) OR ELECR
ELECREC
OF NEXT )
Errors None.
The MODIFIED, DELETED and CREATED functions are not implemented within PML2
expressions.

UNSET

Synopsis UNSET( val ue) - > l ogi c al

Description Returns TRUE if value is unset, else FALSE. The value can
be of any data type including ARRAYS. Normally it will be a
attribute.
 Side Effects None.

 A: 10 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

Example UNSET( DESC ) TRUE where DESC is an unset text

attribute

UNSET( CRF
CRFA) FALSE where CRFA  contains unset
reference attributes
Errors None.

VLOGICAL
VLOGICAL is used for the late evaluation of variables.

Synopsis VLOG
LOGI CAL ( var
var i abl
abl e_nam
e_name ) ) - > l ogi
ogi cal
VLOG
LOGI CAL ( var i abl
abl e_nam
e_name , - > l ogi cal
cal
number )
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
’FA’,’, ’FAL’
’FAL’,, ’FALS’ or ’FALSE’ (case
insensitive) or a numeric value equal to zero.
Scalar variables may not be indexed. For example,
VTEX var [ 1] )  will return an error.
TEXT( ! var
Array variables must have an index. For example, VTEXT
( !a r r a y )  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 If the scalar variable, the array variable, or the array variable
element does not exist, the result is undefined.
Example VLOG
LOG ( ! ar r ay[
ay[ 1] ) - > TRU
TRUE
VLOG
LOG ( ! ar r ay , 2 ) - > FALS
FALSE
E
Errors None.
  A.2.3 Lo gi cal Ar r ay Ex
Expr
pr ess io ns
Logical array expressions can contain:

• PDMS
UDA of attributes
attributes of type logical
type logical. logical array.
array. For
For example,
example, LOGARR
LOGARR where LOGARR is a
• Logical constants.
constants. The coconstant
nstantss available
available are: TRUE,
TRUE, ON
ON,, YES for
for true
true;; and FAL
FALSE,
SE,
OFF,, NO for false.
OFF

 A: 11 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

• Logi
Logica
call oper
operat
ator
ors.
s. Se
See
e Logical Operators.
Operators.
• Logi
Logica
call func
functi
tion
ons.
s. Se
See
e Logical Functions.
Functions.

 A.3
 A .3 Num
Nu m eri
er i c (Real)
(Real ) Exp
Ex p r ess
es s i o n s
In expressions, integers are treated as reals; they are fully interchangeable. Numeric
expressions can contain:
• Numb
Number ers,
s, for
for e
exam
xampleple:: 32,
32, 10
10.1.1..
• Number
Numberss can be be given
given as as inteinteger
ger expon
exponent
ents,
s, for e
examp
xample:
le: 10
10 exp 5, a
and
nd 5 E 6.
• Numb
Number erss be
be qual
qualif
ifie
ied
d by ununit
it na
namemes.s.
• Attribu
Attributes
tes of typ
typee numbe
numberr, for
for eexam
xample
ple:: XLEN.
XLEN.
• Position,
Position, direction
direction and orienta
orientation
tion attribut
attributes
es which
which have
have a subscri
subscript
pt to indicate
indicate wh
which
ich
part of the array is required. For example, PO S[ 2]  means the second element of the
POS[
POSITION attribute; that is, the northing. Note that position, direction and orientation
attributes without subscripts can only be used in number array expressions.
• Th
Thee ke
keyw
ywor
ord
d PI (3
(3.1
.142
42).
).
• Nume
Numeri
ricc oper
operat
ator
ors.
s.
• Nume
Numeri
ricc func
functi
tion
ons.
s.

 A.3.1 Real Ph
Phys
ys ic al Qu ant i ti es w it h Un it
itss
Numbers can be qualified by an appended unit string. Most common are the standard MM,
M/etres, IN/ches, FT. However any of the standard units supported by the system (refer to
Database Management Reference Manual) can be used together with most combinations of 
them in compound unit strings. Feet and inches can also be shown as in 10'6.
Such values are always internally converted to internal database units so that any
processing, comparison etc., done with these values is always done consistently and in the
same units.
Function arguments if not purely numeric must be consistent with each other and the
function itself. For example trigonometric functions (SIN, COS etc.) must have arguments
defined in angle units (in any at all). General functions like MIN, MAX must have all
arguments which have units consistent with the same physical quantity (e.g. units of length).
Arithmetic expressions must add and subtract unit consistent quantities.
Multiplication and division will generate reals of the same physical quantity (but scaled) if 
only one value has units, or a real of a new physical quantities if both have. For example
there is a difference between (5 * 10inch) and (5mm * 10inch) which are 50inch and 1.9685
square inches respectively.
respectively.
When numbers have units that are not consistent with each other, or the function or 
expression they are being used then warnings, and sometimes (for serious problems) errors
are raised.
  A: 12 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

 A.3.2 Num eri c (Real ) Oper ato r s

The numeric operators available are:

Op er at o r Co m m e n t s

+ Addition.
- Subtraction.
* Multiplication.
/ Division.

 A.3.3 ADD an
andd SUB TRACT (+ an
andd -)

Synopsis number + number - > number

number - number - > number
+ number - > number
- number - > number
Description Add or subtract two numbers. They can also be used as
unary operators at the beginning of a parenthesised sub-
expression.
Side Effects Units are consolidated across add and subtract.
Example 1 + 2 - > 3. 0
1 - 2 - > 1. 0
+ 1 - > 1. 0
- 1 - > - 1. 0
Errors Floating point underflow.

 A.3.4 MULTIPL
MULTIPLY
Y 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 sub-
expression. Numeric underflow is not considered to be an
error and neither is it flagged as a warning. The result returned
is zero.

 A: 13 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

Side Effects Units are consolidated across Multiply and Divide. The
dimension of the result of the expression is determined from
the combination of all the values being combined. For 
example 1kg / (1m * 1m *1m ) will give a density of 1kg/m3.
Example 2 * 3 - > 6. 0
2 / 3 - > 0. 6666
666666
6666
666
6
Errors Divide by zero.

 A.3.5 Num eri c (Real ) Fun ct io ns

The numeric functions available are:
Fu n c t i o n Co m m en ts
ABS
ABS ( number 1 ) Gives the absolute value of a number 
ACO
ACOS ( number 1 ) Gives the arc cosine of a number, in degrees.
ASI N ( number 1 ) Gives the arc sine of a number, in degrees.
ATAN
ATAN ( number 1 ) Gives the arc tangent of a number, in degrees.
ATAN
ATANT ( number 1, number 2 ) Gives the arc tangent of number1/number2, in
degrees, with the appropriate sign.
ALOG
ALOG ( number 1 ) Gives the exponential function (natural anti-log)
of a number.
ARRAY( pos or 
  di
di r or 
  or
or i ) Converts a position, direction or orientation
value or attribute into three numbers.
ARRAYSI
YSI ZE ( var i abl
abl e- nam
name Gives the size of an array variable.
)
ARRAYWI DTH(
TH( var i abl e- name Gives the largest display width of any string in
) array variable-name.
COMPON
PONENT
ENT di r OF pos 2 Gives the magnitude of a vector drawn from E0
N0 U0 to pos2, projected in the direction dir1.
I NT ( num
number 1 ) Gives the truncated integer value of a number.
SI N ( num
number 1 ) Gives the sine, cosine or tangent value of a
number (considered to be in degrees).
COS ( number 1 ) Gives the sine, cosine or tangent value of a
number (considered to be in degrees).
 TAN
 TAN ( num
number 1 ) Gives the sine, cosine or tangent value of a
number (considered to be in degrees).
 LENG
LENGTH ( t ext 1 ) Gives the length of text1.
L OG ( number 1 ) Gives the natural logarithm of a number.

MATCH
TCH ( t ext
ext 1, t ext
ext 2 ) Gives the position of the beginning of the
leftmost occurrence of text2  in t e x t 1. If text2
does not occur in text1, 0 is returned.

 A: 14 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

Fu n c t i o n Co m m en ts

MAX ( number 1, number 2[ , Gives the maximum value of the arguments.

number 3 [ . . . ] ] ) )
MI N ( num
number 1, num
number 2[ , Gives the minimum value of the arguments.
number 3 [ . . . ] ] ) )
NEGATE Multiply a number by -1.0.
NI NT ( number 1 ) 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.
OCCUR ( t ext
ext 1, t ext
ext 2 ) Gives the number of times string text2 occurs in
string text1.
REAL ( t ext
ext 1 ) Try to read a number at the beginning of text1.
POW
POWER ( number 1, number 2 ) Gives the value of number1 raised to the power 
number2.

SQRT ( number 1 )
SQRT Gives the square root of a number.
VVALUE
LUE ( var i abl
abl e- nam
name ) Used for late evaluation of variables. Gives a
real value.

 AB S

Synopsis ABS
ABS ( number 1 ) - > number
Description Returns the absolute value of a real.
Side Effects None.
Example ABS ( - 3. 2 ) - > 3. 2
Errors
None.

 ACOS, A SIN, ATAN and AT

ATANT
ANT

Synopsis ASI N ( number 1 ) - > number

ACOS ( number 1 ) - > number
ATAN ( number 1 ) - > number
ATAN
TANT ( num
number
ber 1, num
number
ber 2 ) - > num
number
ber
  A: 15 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

Description Return the arc-cosine, arc-sine or arc-tangent of a number, in

degrees.

ATANT returns the arc-tangent of number 1/ number 2  with

the appropriate sign. ATANT
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)
ATAN) will indicate an error when trying to
divide by zero.
Side Effects None.
Example ACOS ( 0. 8660
866025
254
4 ) - > 30
Errors Argument of ACOS or ASIN out of range [-1.0,+1.0]
TANT ( 0. 0, 0. 0)  is undefined.
ATAN

 AL OG

Synopsis AL OG ( number 1 ) - > number

Description Return the exponential function (natural anti-log) of a number.
Side Effects Numeric underflow causes the result to be set to zero.
Example ALOG
LOG( - 0. 7 ) - > 0. 49
496
65853
5853
Errors Floating point overflow.
ove rflow.

 ARRAY

Synopsis ARRAY( pos or di r or 

  or
or i ) - > number
Description Converts a position, direction or orientation value or attribute into
three numbers.
Side Effects None
Example ARRAY( e100 ) - > 100 0 0
Errors None.

 ARRAYSIZE
 Synopsis ARRAYSi ze ( var i abl e- name ) - > number
Description Give the size of an array variable.
Side Effects If the array variable does not exist, the result is undefined.

 A: 16 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

Example ARRAYSI
YSI ZE( ! ar r ay)
ay) - > 2. 0
Errors 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 ARRAYWI DTH ( var

var i abl
abl e- name ) - > number
Description Give the largest display with of any string in array variable_name.
Side Effects None.
Example If an array contains the following values:
! ARRAY[ 1] ’ Br ead
ead’

! ARRAY[ 2] ’ i s’
! ARRAY[ 3] ’ f or ’
! ARRAY[ 4] ’ l i f e, ’
! ARRAY[ 5] ’ not ’
! ARRAY[ 6] ’ j ust ’
! ARRAY[ 7] ’ f or ’
! ARRAY[ 8] ’ br eakf ast ’
Then
ARRA
ARRAYW
YWI DTH(
TH( ! ARRA
ARRAY
Y -> 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 COMPonent di
di r 1 OF pos 2 - > t ex
ext
Description Returns the magnitude of a vector drawn from E0 N0 U0 to pos2,
projected in the direction dir1.
Side Effects None.
Example COMP E 45 N of N 0 E 100 U 50 - > 70. 710
 Errors None.

 A: 17 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

SINE, COSINE and TANGENT

Synopsis SI Ne ( number 1 ) - > number

COSi ne
ne ( number 1 ) - > number
 TAN
 TANgent
gent ( num
number 1 ) - > number
Description Return the sine, cosine or tangent value of a number (considered
to be in degrees).
Side Effects None.
Example COS ( 0. 0 ) - > 1. 0
 TAN
 TAN ( 45.
45. 0 ) - > 1. 0
Errors Division by zero for TAN if the sine is (nearly) equal to zero.

INT

Synopsis I NT ( number 1 ) - > number

Description Return the truncated integer value of a number.
Side Effects None.
Example I NT ( 1. 6 ) - > 1. 0
I NT ( - 23. 7 ) - > - 23. 0
Errors Integer overflow.

LENGTH

Synopsis LENgt
LENgt h ( t ext 1 ) - > num
number
ber
Description Return the length of text1.
Side Effects None.
Example LENGTH ( ’ abcd
LEN abcde
ef ’ ) - > 6. 0
LEN
LENGTH ( ’ ’ ) - > 0. 0
Errors None.
  AL OG

Synopsis L OG ( number 1 ) - > number

Description Return the natural logarithm of a number..

 A: 18 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

Side Effects None.

Example LOG
LOG( 3 ) - > 1 098612
0986123
3
Errors Negative arguments.

MATCH

Synopsis MATc h ( t ex
ext 1 , t ex
ext 2)
2) - > 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
Side Effects None.
Example MATCH ( ’ abcde
cdef ’ , ’ cd’
cd’ ) - > 3. 0
MATCH ( ’ abcde
cdef ’ , ’ x’ ) - > 0. 0

MATCH ( ’ abcde
cdef ’ , ’ ’ ) - > 1. 0
Errors None.

MAX and MIN

Synopsis MAX ( number 1 , number 2 [ , - > number

ber
number 3 [ . . . ] ] )
MI N ( num
number 1 , nu
num
mber
ber 2 [ , - > number
ber
number 3 [ . . . ] ] )
Description Return the maximum or minimum value of the arguments.
Side Effects None.
Example MAX ( 1 , 3. 4 ) - > 3. 4
MI N ( 7. 6 , - 12. 33 , 2. 3 ) - > - 12. 33
Errors None.

NEGATE

Synopsis NEGat e ( number 1 ) - > number

 Description Multiply a real by -1.0.
Side Effects None.
Example NEG ( 1 ) - > - 1. 0
Errors None.

 A: 19 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

NINT

Synopsis NI NT ( number 1 ) - > number

Description Return the nearest integer to a real. NI NT( N+0. 5)  is equal to
N+1 if N is positive or equal to zero, to N if N is negative.
Side Effects None.
Example NI NT ( 1. 1 ) - > 1. 0
NI NT ( - 23. 7 ) - > - 24. 0
NI NT ( 1. 5 ) - > 2. 0
NI NT ( - 11. 5 ) - > - 12. 0
Errors Integer overflow.

OCCUR

Synopsis OCCUR(text1, text2) - > i nt ege

eger
Description Counts the number of times string text2 occurs in string text1
Side Effects None.
Example OCCUR ( ’ ABBACC
ACCBBBBBAB’ , ’ BB’ ) - > 3
OCCUR( ’ ZZZZZZZZZZZ’ , ’ A’ ) - > 0
Errors None..

REAL

Synopsis REAL ( t ext 1 ) - > number

Description 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.
Example REAL ( ’ 12. 34’ ) - > 12. 34
REAL ( ’ 7. 23 E 3 met er s’ ) - > 7. 23
 REAL ( ’ - 12E- 1 met er s ’ ) - > - 1. 2
Errors Unable to convert the text into a real number.

 A: 20 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

POWER

Synopsis POWer ( number 1 , number 2 ) - > r eal

Description Return the value of number1 raised to the power number2.
Side Effects Units are consolidated across POWER. The dimension of the
result of the function is determined from the input quantities.
Example POWER ( 2i nch, 3) = 8cubi
cubi c i nch or
or 8i n3
Errors Floating point overflow.
Zero first argument and non-positive second argument
(effectively divide by zero).
Negative first argument and non-integer second argument.

SQRT

Synopsis SQr t ( number 1 ) - > number

Description Return the square root of a real.
Side Effects Units are consolidated across SQRT. The dimension of the
result of the function is determined from the input quantities.
Example SQRT
SQRT ( 16METRE2) = 4Met r e
Errors Negative argument.

VVALUE
REAL(string) and VVAL(!stringvar) functions:
These will return the value of the number in the string IGNORING any unit qualifier.
The unit qualifier must still be a valid unit qualifier. This is done so that output from $! and
VAR ! combinations of commands can still be accepted by the REAL function and other 
functions with or without unit qualifiers appended
VVALUE is used for the late evaluation of variables.

Synopsis VVAL ue( var i abl e_ na

name ) - > number
VVALue(
Lue( var i abl
abl e_name , - > num
number
ber
number )
  A: 21 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

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 element

corresponding to the index number as a number.
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.
Example VVAL ( ! ar r ay[ 1] ) - > 1. 0
VVAL ( ! ar r ay , 2 ) - > 0. 0
Errors Scalar variable may not be indexed. For example, VTEXT
( ! v a r [ 1 ] ) )  will return an error.
Array variable must have an index. For example, VTEXT
( !a
arr r ay
ay ) )  will return an error.
The string can not be converted to a number.

 A.3.6 Real A r ray s

Real array expressions can contain attributes
at tributes of type real array, for example: DESP.

 A.4
 A .4 Usi
Us i n g IDs i n Ex
Expp r ess
es s i o n s
IDs can be used in expressions. IDs can be any of the following:
• Eleme
Element nt na
name
me,, for
for ex
exam
amplple:
e: /VESS1
/VESS1..
• Refn
Refno,o, for
for exa
examp
mple le:: =23
=23/4
/456
56..
• Element
Element type
type furt
further
her up up the hier
hierarch
archyy, for exam
exampleple:: SIT
SITE.
E.
• Numb
Number er wit
withi
hin
n membe
memberr list,list, for e
exa
xampl
mple: e: 3.
• Type
Type anandd number
number within
within memb
member er list
list,, for
for exampl
example: e: BBOX
OX 3.
• NEXT,
NEXT, PREV for for next,
next, previous
previous within
within current
current list.
list. O
Optiona
ptionally
lly wi
with
th a count
count and
and/or 
/or 
element type, for example: NEXT 2 BOX, LAST CYL.
• NEXT,
NEXT, PREV MEMBER MEMBER for for next,
next, previous
previous within
within member
member list.
list. OOptiona
ptionally
lly w
with
ith a ccount
ount
and/or element type.
• If the elem
elementent type
type given
given is only
only valid
valid as a membememberr then MEMBE
MEMBER R is assumed
assumed.. For 
example, NEXT BOX at an EQUIPMENT will assume MEMBER.
• FIRST,
FIRST, LAST for first first and last in in current
current list.
list. Optional
Optionallyly wit
withh a count
count and/
and/or
or element
element
type.
 • FIRST,
FIRST, LAST MEMBER
MEMBER for for first
first and last
last in member list. If the element
element type given is onl
onlyy
valid as a member then MEMBER is assumed.
• END
END toto n
navi
aviga
gate
te up
up fro
from
m ccur
urren
rentt lis
list.
t.

• END is similar
GROUP simila r to owner
MEMBER, owner
and but notbeen
it has quite
quite reached
the same. Forthe
from example,
exaGROUP
mple, iiff the
thenccurrent
urrent element
elemen
END will t istoa
return
the group but OWNE will go to the true owner.
• Att
Attri
ribu
bute
te of
of type
type ref,
ref, for
for ex
exam
ampl
ple:
e: CRE
CREF F

 A: 22 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

• SAME
SAME to
to m
mean
ean la
last
st cu
curre
rrent
nt el
elem
emen
entt
• NULREF to me
mean =0
=0/0

• CE fo
forr the
the cu
curr
rren
entt ele
eleme
ment
nt
• ’OF’
’OF’ may bebe used toto nest
nest the option
optionss indefi
indefinit
nitely
ely.. For examp
example:
le:
SPEC OF SPREF OF FL AN 1 OF NEXT BRAN.
• This
This denotes
denotes the
the SPEC elem
element
ent owing
owing the
the SELE
SELE ele
elemen
mentt pointed
pointed tto
o by the S
SPREF
PREF
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 TUB
TUBE OF / BRAN1.
• An error
error will
will occur
occur ifif there
there is no impli
implied
ed tube
tube for tthe
he ele
elemen
mentt concer
concerned
ned..
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.

 A.5
 A .5 Pos
Po s i t i o n s , Dir ect
ec t i o n s and
an d Or
Orii en
entat
tatii o n s i n
Expressions (PDMS only)

 A.5.1 Usi ng Pos

Posii ti on s i n Ex pr ess
essii on s
The basic ways of defining a position are:
• Positio
Position
n attrib
attribute
ute plus
plus opti
optiona
onall WRT
WRT. For exam
example
ple::
POS OF / VESS1 WRT / * or P1 POS OF / CYL 2
• Cart
Cartes
esia
ian
n pos
positi
ition
on.. For
For examp
example
le::
N 45 W 20
20000 U 1000
• Cartes
Cartesian
ian positi
position
on from
from an elem
element.
ent. For exampl
example:
e:
N 1000 FRO
FROM / ATEST.
• Cartes
Cartesian
ian positi
position
on from
from a ppoi
ppoint.
nt. For exampl
example:
e:
N 1000 FROM P1 OF / BOX2.
• Cartes
Cartesian
ian positi
position
on from
from an
an attrib
attribute
ute.. For
For exa
exampl
mple:
e:
N 1000 FRO
FROM POSS OF / SCTN1
• Any numeric
numeric value within
within a positio
position
n may itsel
itselff be an expressi
expression.
on. For
For exa
example:
mple: the
following is a valid position expression
N ( DE
DESP[ 1]
1] + 10) E
The Cartesian position may optionally be followed by WRT to specify the axis system. See
 WRT (PDMS Only).

 A.5.2 WRT (PDMS Onl

Only)
y)
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

 A: 23 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

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 / EQUI P1 $ will return the position of EQUIP1 relative to its

$ owner.

If we require the result in some other axis system then the WRT keyword is used. For 
example:

Q POS
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 element’s axis system. This
absolute position can be expressed in different coordinate systems: the default is again the
owner’s axis system.
Note: The CONSTRUCT syntax uses the world as the default axis

Example

It em Co m m en ts

A SITE at (0,0,0) With default (World) orientation

A ZONE at (100,0,0) With default (World) orientation
An EQU
EQUIPM
IPMENT
ENT at (100,0,
,0,0) Wi
With
th orientation ’N IS E
A BOX at (-100,0,0) With default (World) orientation
  A: 24 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

Fi
Figu
gure
re A:1.
A:1. Re
Resu
sult
lts
s of WR
WRT
T

The result of Q ( N 100 WRT / BOX1) , shown as ⊗ in , will depend on the current element.

L o c at i o n Res u l t

World (300,100,0), in World coordinates.

Site (300,100,0) in World coordinates because the World
is the owner of the current element.
Zone (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.
Equipment (200,100,0), which is the position relative to its
owner, the Zone.

Box (100,100,0) which is the position relative to its owner,

the Equipment.

WRT can be further qualified by FROM.

 A.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.

 A: 25 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

Consider the following:

It em Co m m en ts

A SITE at (0,0,0) With default (World) orientation

A ZONE at (100,0,0) With default (World) orientation
An EQ
EQUIPMENT at
at (1
(100,0,0) With or
orientation ’N
’N IS E
A BOX at (-100,0,0) With default (World) orientation

Fi
Figu
gure
re A:2.
A:2. The
The E
Eff
ffec
ectt o
off F
FRO
ROM
M

The result of Q ( N 100 WRT / * FRO

FROM / BOX1) ,  shown as ⊗ in , will depend on the
current element.

L o c at i o n Res u l t

World, Site, and Zone (200,200,0) ssiince th

th e o
offfset o
off N
N1
100 iiss a
ap
pplied iin
n
world axis rather than /BOX1 axis.
Equipment (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.

 A: 26 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

The result of ’ Q ( N 100 WRT / BOX1 FRO

FROM / * )  is different:

L o c at i o n Res u l t

Site and Zone ( 1 0 0 ,0 ,0 )

Equipment ( 0 ,0 ,0 )
Box (0, -100, 0), because the axis for the result is the
Equipment.

The result of ’ Q ( N 100 FR

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.

Figu
Figure
re A:
A:3.
3. Varyin
rying
gWWR
RT

L o c at i o n Res u l t

Site and Zone (0,100,0)

Equipment (-100,100,0), because the default result axis is the
Zone.
Box (0, -100, 0), because the axis for the result is the
Equipment.
  A.5.4 Com par
parin
in g Po si ti on s

Two
only positions
comparedcan
in be
thecompared
coordinatewith EQ,forNE,
axes GT
GT,, LT,
which LT
the, GE
twoorpositions
LE. The pairs of coordinates
are defined. are
A position
attribute always has all three coordinates defined.

 A: 27 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

For positions entered by the user, only those coordinates which are given by the user are
defined. For example:

’ N10U3’
10U3’ $ 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),
(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.
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 W1S2D
1S2D3’ $ This evaluates to true only if POS of the current $
element is (-1,-2,-3).

’ POS GT N10’ or ’ N10 L E $ Only the second coordinate of POS is compared;

POS’
$ if it is greater than 10, then the result is true.

’ E10N10 GT E0N0’ $ 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’ $ Is false because the Y components are different $

axes.

’ E10N0 GT E0U100’ $ 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,

Comparisons, for tolerances in comparing numbers.

 A.5.5 POLA
POLARR
 The POLAR keyword allows positions to be defined in terms of a distance in a particular 
direction from a point.

 A: 28 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

The syntax is:

dir  expr   pos

POLAR DI STan
STance
ce -+
| - FROM - + |- - - - - - .|
| ‘ -  point - - - |
| |
‘ - - - - - - - - - - - - - - - - - - - - +- - - >

If FROM is not specified the

t he default is the origin of the owner.
For example:

POL AR N 45 E DI ST 20M FROM U 10 M

POL AR AXES PL OF PREV DI ST ( ABORE * 10 ) FROM PL OF PRE V

 A.5.6 Dir ect io n

The basic ways of defining a direction are:
• Direct
Direction
ion attr
attribu
ibute
te plus
plus option
optional
al WRT
WRT. For examp
example,
le,
HDI R OF / PI PE1 WRT / *
• Cart
Cartes
esia
ian
n dir
direc
ecti
tion.
on. For
For exam
exampl
ple,
e,
N 45 W
• Cart
Cartes
esia
ian
n dire
direct
ctio
ion
n WRT
WRT to an
an elem
element
ent..
• All Cartesia
Cartesian
n directions
directions are returned
returned in the axis of the owner of the current element
element.. For 
example:
( U WRT CE )
• will
will return
return the
the Z axis
axis of the
the current
current elem
element
ent relat
relative
ive tto
o its owne
owner.
r.
Q ( Z WRT / SC
SCTN )
• will return the Z axis
axis direction
direction of /SCTN
/SCTN relative
relative to the ow
owner
ner of the cu
current
rrent element.
element. For 
example, if the result is required in world coordinates the current element must be the
World or a Site.
• FROM
FROM pos2pos2 TO pos2
pos2.. For
For exa
examp
mple
le
FROM N 50 WRT CE TO N 100
• Keywo
Keyword
rd AX
AXES
ES foll
follow
owed
ed by
by a p-poi
p-point
nt or
or plin
pline.
e.
  A: 29 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

• The CLOSEST
CLOSEST keywor
keyword,
d, which
which will
will find
find the
the closest
closest element
element in a parti
particular
cular direction.
direction.
The syntax is:

>- CLOSEST t y
yppe - +- WI TH exp - .
| |
‘ - - - - - - - - - - - - +- DI RECTI ON di r - +
+-- EXTENT val - .
| |
‘ - - - - - - - - - - - - - - +- - > c ont

c ont i nued >- +- AFTER val - .

| |
‘ - - - - - - - - - - - - - +- FROM ? - .
| |
‘ - - - - - - - - - - +-
+- - >

• In th
the
e abov
abovee grap
graph h the
the ke
keyw
ywor
ords
ds are:
are:
• EXTENT,
EXTENT, which
which is how farfar to search in the
the direction
direction specified,
specified, defaul
defaultt 10M
• AFTER, or the distance
distance along
along vector after which to start
start ssearch,
earch, defaul
defaultt 0M
• FROM, which
which specifie
specifiess an alternat
alternative
ive start
start point
point othe
otherr than current element.
element. This is of 
particular use for a branch where you might want to specify the HPOS or TPOS.
• Examples ar are:
CLOSEST DI R E
CL OSEST BOX WI TH ( PURP EQ ’ FL OO’ ) DI R D WRT /
* EXTENT 20M
CLOSEST VALVE
LVE DI R N 45 U FROM E100 N200 U300
CLOS
LOSEST BRAN HANG AFTER
FTER 2M

 A.5.7 Ori ent

entati
ati on s
The basic ways of defining an orientation are:

• Orient
Orientatio
ation
n attribu
attribute
te plus
plus option
optional
al WRT
WRT. For examp
example:
le:
ORI OF / BOX1 WRT / *
• Cart
Cartes
esia
ian
n orie
orient
ntati
ation
on.. For
For ex
exam
ampl
ple:
e:
di r I S di r AND di r I S di r
• For example
example to
to set an
an orientati
orientation
on of a
an
n element
element to that o
off a se
section,
ction, rotate
rotated
d by 9
90
0
degrees use:
( E I S U WRT / SCTN1 AND N I S E WRT / SCTN1)
• The AXES keyword,
keyword, which
which will
will allow
allow you to
to use P-points
P-points to specif
specifyy orie
orientati
ntations.
ons.
  A: 30 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

• The sy
syntax is
is:

/ - - - - <-
<- - - - - - - - - .|
  >- - AXES - - * - - - PAr r i ve - - - |
  | |
  | - - - PL eave - - - - |
  | |
  | - - - PTai l - - - - - |
  | |
  | - - - HHead - - - - - |
  | |
  | - - - HTai l - - - - - |
  | |
  ‘ - - - PPOI NT NT n - - +- - OF - <gi d> - - - - >
 

• An example is:
( AXES PL EAVE I S AXES PL EAVE OF PREV AND AXES P3 I S UP )
• This will
will orient
orient a branch component,
component, such
such as a valve,
valve, so tthat
hat it is ali
aligned
gned w
with
ith th
the
e
previous component and its P3 is up.
See also Comparing Positions.

 A.6
 A .6 Text
ex t Exp
Ex p r ess
es s i o n s
Text expressions can contain the following:
• A text stri
string,
ng, whic
whichh mus
mustt be enclos
enclosed
ed in q
quot
uotes.
es. For
For exa
exampl
mple:
e: ’F
’FRED
RED’.
’.
• A PDMS
PDMS attrib
attribute
ute of type
type text
text or w
word
ord.. For exampl
example:
e: FU
FUNC
NC
• A single
single eleme
elementnt of a word
word array
array attrib
attribute.
ute. For
For exampl
example:
e: ELE
ELEL[2
L[2].
].
• Text o
opperators
• Text functions

 A.6.1 Text Oper

Operato
ato r 
The text operator available is +, used for concatenation.

Synopsis t ex
ext 1 + t ex
ext 2 - > t ex
ext - > t ex
ext
Description Return the concatenation of two text strings.
Side Effects None.
Example ’ no’ + ’ space
space’’ - > ’ nospace
ospace’’
 Errors Text result too long.

 A: 31 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

 A.6.2 Text Fun ct i on s

The text functions available are:
Fu n c t i o n Co m m en ts
AFTER
BEFORE
DISTANCE
LOWCASE, UPCASE
PART
REPLACE
STRING
SUBS, DSUBS
TRIM
VTEXT

 AFTER
 AFT ER

Synopsis AFTER ( t ex
ext 1 , t ex
ext 2 ) - > t ex
ext
Description 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 None.
Example AFTE
FTER ( ’ abcde
cdef ’ , ’ cd’
cd’ ) - >’ ef ’
AFTER ( ’ abcde
cdef ’ , ’ x’ ) - > ’ ’
AFTE
FTER ( ’ abcde
cdef ’ , ’ ’ ) - > ’ abcde
cdef ’
Errors None.

BEFORE

Synopsis BEFORE ( t ext 1 , t ex

e xt 2 ) - > t ex
e xt
Description 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.
 Side Effects None.
Example BEFORE ( ’ abcde
cdef ’ , ’ cd’
cd’ ) - > ’ ab’
BEFORE ( ’ abcde
cdef ’ , ’ x’ ) - > ’ ’
BEFORE ( ’ abcde
cdef ’ , ’ ’ ) - > ‘ ’
Errors None.

 A: 32 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

DISTANCE

Synopsis DI STance ( number 1 ) - > t ext

ext
DI STan
Tance(
ce( number 1, l ogi
ogi cal
cal 1, - > t ext
ext
l ogi cal
cal 2, l ogi cal
cal 3, number 2,
l ogi c al 4)
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 ’aa’bb.cc/dd’. Otherwise, text is the
STRING conversion of number1.
The six-argument form is more complex. The format is:
DI ST/ ANCE ( di st ance,
ce, f eet , usf or mat ,
f r act i on, denom_or _dp,
_dp, zer
zer os)
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
feet have
have been
been outpu
output,
t, the
the inc
inches
hes will
will be at lea
least
st tw
two
o
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
been out
output
put a
and
nd tthe
he di
dista
stance
nce is a
att least
least a
an
n
inch, then the number of inches is displayed but without
any
outputpreceding spaces.
for distances Only
of less if zeros
than is true will a 0 be
an inch.
• If inc
inche
hess hav
havee been
been o
out
utpu
putt an
and
d fraction is true, these will
be followed by a decimal point (.).

 A: 33 12 Series

 Soft ware Customis ation Reference

Reference Manual
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 fracti on 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 USUS fo format
rmat has been been se select
lected ed tthen
hen the follow
following
ing
additional rules are observed on output:
• The (’)
(’) afte
afterr the number
number of feet
feet iiss fol
follow
lowed
ed by
by a da
dash
sh
(-).
• The decim
decimal al poin
pointt sep
separa
aratin
ting
g the incinches
hes from the frac
fractio
tion
n
is replaced by a space.
• The inche
inchess andand frfract
action
ion of iinch
nches es aare
re fo
follo
llowed
wed by a
double quote(”).
Side Effects None.
Example If the current distance units are FINCH:
DI STAN
TANCE ( 17.
17. 5 ) - > ’ 1’ 5. 1/ 2’
Some examples, where the current distance units are feet and
inches:
DI ST
ST(( 34
34.. 5, TR
TRU
UE, TRU
TRUE, TRU
TRUE, 100,
100, TRU
TRUE) -> 2’ - 10.
10. 1/ 2.
DI ST
ST(( 34
34.. 5, FALSE
FALSE,, TRU
TRUE, FA
FALSE
LSE,, 1, TRU
TRUE) -> 34.
34. 5”
DI ST
ST(( 34
34.. 5, FALSE
FALSE,, TRU
TRUE, TRU
TRUE, 4, FA
FALSE
LSE)) -> 34 1/ 2”
DI ST
ST(( 12
1288. 5, TRU
TRUE, FA
FALSE
LSE,, TRU
TRUE, 2, TRU
TRUE) -> 10’
10’ 08.
08. 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(_).

Di st
stan c
ce
e Feet & In ch
ch Feet & Inc h
Feet Inches Inches Feet & Inc h
Feet
US US US US PDMS
Fraction Fraction Decimal Fraction Fraction
Denom 100 Denom 32 DP 1 Denom 2
Zeros No Zeros Zeros Denom 4 Zeros
No Zeros

128.5 10’-_8_1/2”___ 10’-_8_1/2”__ 128.5” 128_1/2” 10’08.1/2

120.0 10’-_0”_______ 10’-_0”______ 120.0” 120”____ 10’00____

11.5 0’-11_1/2”___ 11_1/2”__ 11.5” 11_1/2” 0’11.1/2

 0.75 0’-_0_3/4”___ 3/4”__ 0 .8 ” 3 /4 ” 0’01____

0.0 0’-_0”_______ ______ 0.0” ____ 0’00____

-10.0 -0’-10”_______ -10”______ -10.0” -10”____ -0’10____

Errors The value is too big to be converted.

 A: 34 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

LOWCASE and UPCASE

Synopsis UPCas e ( t ext 1 ) - > t ext

L OWCas e ( t ext 1 ) - > t ext
Description Return an upper or lower case version of text1.
Side Effects None.
Example UPCA
PCASE ( ’ Fal
Fal se’ ) - > ’ FALS
FALSE E’
LOWCASE ( ’ Fal
Fal se’
se’ ) - > ’ f al se
se’’
Errors None.

PART

Synopsis PART( t ex
ext 1,
1, nu
number 1)
1) - > t ex
ext
PART( t ext
PAR ext 1, num
number
ber 1 , - > t ext
ext
t ext 2)
Description With two arguments, returns the number 1  component of 
text1  assuming that t e x t 1  is split on any whitespace
characters. If number 1  is negative, counting of components
starts from the right.
With three arguments, as above, but use t e x t 2  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 None.
Example PART ( ’ x- y- z ’ , 1, ’ - ’ - > ’ x’
PART ( ’ a b c d e’ , 4- 4- > ’ d’
d’
PART ( ’ / PI PE45/ B9’ , - 1, ’ / ’ ) - > ’ B9’
PART( ’ aa bb cc’ , 2) - > ’ bb’
PART( ’ aa- bb- c c’
c’ , 3, ’ - ’ ) - > ’ c c’
c’
Errors None.

REPLACE
 Synopsis Lace ( t ext 1, t ext 2, t ext 3) - > t ext
REPLace ext
REPLace
Lace(( t ext 1, t ext 2, t ext 3, i
nt 1) - > t ext
ext
Lace(( t ext 1, t ext 2, t ext 2, i - > t ext
REPLace ext
nt 1, i nt 2)

 A: 35 12 Series

 Soft ware Customis ation Reference

Reference Manual
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 None.
Example Three arguments:
REPLAC
LACE ( ’ cat
cat dog cat
cat cat
cat dog ’ , ’ cat
cat ’ ,
’ dog’
dog’ ) - > ’ dog
dog dog
dog dog
dog dog
dog dog’
dog’
All occurrences of ’cat’ are replaced with ’dog’.
Four arguments: start occurrence given:
REPLAC
LACE ( ’ cat
cat dog cat
cat cat
cat cat
cat dog’ , ’ cat
cat ’ ,
’ dog’
og’ , 2) - > ’ cat dog dog dog dog dog
All occurrence of ’cat’ from the second occurrence onwards
are replaced with ’dog’
REPLAC
LACE( ’ cat
cat dog cat
cat cat
cat dog’ , ’ cat
cat ’ ,
dog’
og’ , - 2 - > ’ dog dog dog cat dog’
og’
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:
REPLA
PLACE ( ’ cat dog cat cat cat cat ,
’ cat
cat ’ , ’ dog’ , 2, 2) - > ’ cat
cat dog dog dog cat
cat ’
Replace two occurrences in backwards direction starting at
the second occurrence:
REPLAC
LACE ( ’ cat
cat dog catcat cat
cat cat
cat ’ , , ’ cat
cat ’ ,
’ dog’ , 2, - 2) - > ’ dog dog dog cat
cat cat
cat ’
Replace two occurrences in forwards direction starting at
second occurrence from the end of the string:
REPLAC
LACE ( ’ cat
cat cat
cat cat
cat cat
cat dog’ , ’ cat
cat ’ ,
’ dog’ , - 2, 2) - > ’ cat
cat cat
cat dog dog dog’
Replace two occurrences in backwards direction starting at
 second occurrence from the end of the string.
REPLAC
LACE ( ’ cat
cat cat
cat cat
cat cat
cat dog’ , ’ cat
cat ’ ,
’ dog’ , - 2, - 2) - > ’ cat
cat dog dog catcat dog’

 A: 36 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

The following examples all give the same result:

REPLAC
PLACE( ’ cat 1 ca
catt 2 ca
catt 3 ca
catt 4 ca
catt 5 ca
catt 6 ca
catt 7 ca
catt 8
ca
att 9 c a
att 10’ , ’ c a
att ’ , ’ dog’ , 4, 2)
REPLAC
PLACE( ’ cat 1 ca catt 2 ca
catt 3 ca
catt 4 ca
catt 5 ca
catt 6 ca
catt 7 ca
catt 8
ca
att 9 c a
att 10’ , ’ c a
att ’ , ’ dog’ , 5, - 2)
REPLAC
PLACE( ’ cat 1 ca catt 2 ca
catt 3 ca
catt 4 ca
catt 5 ca
catt 6 ca
catt 7 ca
catt 8
ca
att 9 c a
att 10’ , ’ c a
att ’ , ’ dog’ , - 6, - 2)
REPLAC
PLACE( ’ cat 1 ca catt 2 ca
catt 3 ca
catt 4 ca
catt 5 ca
catt 6 ca
catt 7 ca
catt 8
ca
att 9 c a
att 10’ , ’ c a
att ’ , ’ dog’ , - 7, 2)

in each case, the output string is

’ cat 1 cat
cat 2 cat
cat 3 dog
dog4
4 dog
dog5
5 cat
cat 6 ca
catt 7 cat
cat 8 ca
catt 9
cat 10’
10’
If the replacement string text3  is a null string the required
number of occurrences of the search string text2  are
removed. For example:
REP
EPLA
LAC
CE ( ’ AAABBABZ’ , ’ B’ , ’ ’ ) - > ’ AAAAZ’
REPLAC
LACE ( ’ AAABBABZ’ , ’ B’ , ’ ’ , - 1, - 1) - >
’ AAAB
AAABBA BAZ’
Z’
Errors If the input string text1 is a null string or an unset text attribute,
the input string text1 is returned unchanged. For example:
REPL ACE ( ’ ’ , ’ A’ , ’ B’ ) -> ’’
If the search string text2 is longer than the input string text1,
the input string text1 is returned unchanged. For example:
REPLAC
LACE( ’ AA’ , ’ AAAAA’ , ’ B’ ) - > ’ AA’
If no occurrence of the search string text2 is found, the input
string text1 is returned unchanged. For example:
REPLAC
LACE( ’ AAAAAA’ , ’ B’ , ’ C’ ) ->
’ AAAA
AAAAAA
AA
If required occurrence int1 is not found the input string text1 is
returned unchanged. For example:
REPLAC
LACE( ’ AAAAAA’ , ’ A’ , ’ B’ , 10 ) ->
’ AAAA
AAAAAA
AA’’
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
t he string
( or beginning in backwards mode). For example:
REPLAC
LACE( ’ AAAAAA’ , ’ A’ , ’ B’ , 2,
2, 8)
8) ->
’ ABBB
ABBBBB
BB’’
REPLAC
LACE ( ’ AAAAAA’ , ’ A’ , ’ B’ , - 3, 8) ->
’ BBBB
BBBBAA
AA’’
  A: 37 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

STRING

Synopsis STRi ng ( any s c

caal ar t ype ) - > t ext
STRi ng ( number , t ext 1 ) - > t ext
STRi ng ( po
pos , t ex
ext 1 ) - > t ex
ext
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
• Logi c al
• 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
t he
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 None.

Example ST
STR
RI NG ( 1 ) - > ’ 1’
STRI NG ( 1 , ’ D3’ ) - > ’ 1. 000’
STR
STRI NG ( 1. 23
2345
4567
6789
89 ) - > ’ 1. 2345
23457’
7’
STR
STRI NG( 1. 12
1230
3000
000)
0) - >’ 1. 123’
123’
ST
STR
RI NG ( 1. 23
2345
456
6789
789 , ’ D3’ ) - > ’ 1. 235’
235’
ST
STR
RI NG ( 9*9 LT 1 100
00)) - > ’ TRU
TRUE’
STRII NG ( OWN OF C
STR CE)
E) - > ’ / PI PE1’
STRII NG( POS) - > ’ W1000
STR 1000 N N200
2000000 U
U180
18000’
00’
STRII NG( POS, ’ D4’ ) - > ’ W1000
STR 10000.
0. 1234
1234 N2000
20000.
0. 1234
1234
U18000
18000.. 1234’
 ST
STR
RI NG( HDI R OF / PI PE1-
PE1- 1) - > ’ D’
ST
STR
RI NG( E 22.
22. 01
0125
25 N, ’ D2’ ) - > ’ E 2
22.
2. 01 N’
STRII NG ( ORI OF N
STR NEX
EXT)
T) - > ’ Y I S D AND Z I S U’
U’

Errors

 A: 38 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

SUBSTRING

Synopsis SUBSt r i ng ( t ex
e xt 1 , number 1 ) - > te
exxt
SUBSt r i ng ( t ext 1 , number 1 , - > t ext
ext
number 2 )
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.
Side Effects None.
Example
S
SU
UB
BS
ST
TR
RII N
NG
G (( ’’ ab
abcd
abcde
abcde
eff ’’
cde ,, - 3
3 )) -- >
> ’’ cde
cd
abef ’’
abcd
cd’
SUBSTRI NG ( ’ ab
abcd
cde
ef ’ , 3 , 2 ) - > ’ cd’ cd’
SUBSTRI NG ( ’ abcde
cdef ’ , - 3, 2 ) - > ’ de’
SUBSTRI NG ( ’ abcde
cdef ’ , 3 , - 2 ) - > ’ bc’
SUBSTRI NG ( ’ ab
abcd
cde
ef ’ , 10 ) - > ’ ’
SUBSTRI NG ( ’ ab
abcd
cde
ef ’ , - 10 , 2 ) - > ’ ab’ ab’
Errors None.

TRIM

Synopsis  TRI M ( t ext 1 )

 TRI - > t ext
 TRII M ( t ext 1, t ext 2 )
 TR - > t ext
 TRII M ( t ext 1, t ext 2, t ext 3 )
 TR - > t ext
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 None.

 A: 39 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

Example  TRI M ( ’ How now, br own cow ’ , ’ LRM’ ) - >

 TRI
’ How now, br own cow
c ow’
 TRII M ( ’ 10.
 TR 10. 3000
3000’’ , ’ R’ , ’ 0’ ) - > ’ 10.
10. 3’
Errors None.

VTEXT
VTEXT is used for the late evaluation of variables.

Synopsis VTEXT ( va
var i abl e- name ) - > t ex
e xt
VTEX
TEXT ( var
var i abl
abl e- name , - > t ext
ext
number )
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 If the scalar variable, the array variable or the array variable
element does not exist, the result is undefined.
Example VTEXT ( ! var ) - > ’ hel l o’
VTEXT ( ! ar r ay[ 1] ) - > ’ 1. 00’
VTEXT ( ! ar r ay , 2 ) - > ’ 0. 00’
Errors Errors Scalar variable may not be indexed (e.g. VTEXT
(!var[1]) ).
Array variable must have an index (e.g. VTEXT ( !array ) ).
VTEXT

 A.7
 A .7 L ate
at e Eval
Ev alu
u ati
at i o n o f Vari
ar i abl
ab l es i n Ex
Expp r ess
es s i o n s
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
t o output a logical variable and VTEXT
VTEX T to output
a text variable.

 A: 40 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

 A.8
 A .8 A t t r i b u t es i n Ex
Expp r ess
es s i o n s
All
mayattributes and by
be followed pseudo-attributes
’OF’ to denote may be recognised
a different element within
to the expressions.
current one; Optionally
e.g. POS OFthey/
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. Attributes are
described in the Data Model Reference Manual.

 A.9
 A .9 Quer
Qu ery
y i n g Exp
Ex p r ess
es s i o n s
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 PPOI NT n
• Q POS or c aarr t es i an pos i t i on
• Q ORI or c aarr t es i an or i ent at i on
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 ).

 A.10
 A .10 Uni
Un i ts i n Exp
Ex p r ess
es s i o n s
When a user enters a literal value then the units are not necessarily known. The units for 
PML variables may not be known if not input initially. Where units are known, then all
internal values are set to database units (mm for distances). 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.
The internal settings for units are as follows:

Set t i n g Co m m en ts

NONE No units. e.g. attribute OBS.

UNKN Unknown units. e.g. 10.
 MM Dist/bore attribute if units are MM, or literal e.g. 10 mm.
INCH Dist/bore attribute if units are INCH/FINCH, or literal e.g. 10’.
SQIN Multiply two INCH values together, or literal e.g. 10 sq in.

CUIN 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

 A: 41 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions

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:
( XL EN 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 * XLENXLEN)  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)
LEN)  we assume that the 10 is in inches rather than none.

 A.1
 A .11
1 Prec
Pr ecii s i o n o f Com
Co m pari
par i s o n s
To allow for small losses of accuracy,
accuracy, the following tolerances are used.

Ob j ec t To l er an c e

Number 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.
• (1.0000
(1.000001
01 GT
GT 1) is FALSE
FALSE as itit co
consi
nsiders
ders 1.00000
1.000001;
1;
and 1 to be equal;
• (1
(1.0
.000
0000
0022 GT
GT 1) is TR
TRUE
UE..
Position Considered to be equal if within 0.5 mm of one another.
Direc
irecti
tion
on or Or
Orie
ient
ntat
atio
ion
n Co
Cons
nsid
ider
ered
ed to be
be equ
equal
al if va
vallues
ues ar
are
e wit
withi
hin
n00.0
.00
05.

 A.12
 A .12 Und
Un d efi
ef i n ed Val
aluu es
In order to permit expressions like ( ( DI AM GT 20200. 0) OR ( TY PE EQ ’ BOX’ ) ) ,
TYPE
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
arguments are defined; and OR which
returns TRUE if any of its arguments is TRUE. For example, consider applying
applying the above
 expression when the current element is a box. DIAM is undefined; therefore ( DI AM GT
0. 0)  is also undefined. However, ( TYPE EQ ’ BOX’ )  is certainly true and so the final
200.
20
result of the whole expression evaluates to TRUE.
An undefined result occurs when:
• One of the operands
operands or arguments
arguments of a function
function (except
(except some cases of AND and OR)
OR) is
undefined.
• An attrib
attribute
ute is unav
unavail
ailabl
able
e for the
the corresp
correspond
onding
ing e
eleme
lement
nt (e
(e.g.
.g.’ DI AM OF OW
OWNER
ER’’
when the current element is a box).

 A: 42 12 Series

 Soft ware Customi sation Reference

Reference Manual
Manual
PML 1 Expressions

• An ele
eleme
ment
nt is
is unde
undefi
fine
nedd (e.g
(e.g.. ’ OWNER’ when the current element is the WORLD).
• An attri
attribute
bute is unset
unset (e.g
(e.g.. tex
textt att
attrib
ribute
ute or
or UDA of
of length
length 0
0).
).

• A var
varia
iabl
ble
e is
initialised). is und
undef
efin
ined
ed (e .g.
(e.g ’ VVAL( ! ARC6) ’   where !ARC6  has never been
• Two
Two position
position constant
constantss are compared
compared with
with GT
GT, GE, L
LT
T or LE and they hav
have
e no common
common
coordinates (e.g. ’ N10 EQ E5’ ).
• If the resu
result
lt of the
the whole
whole expre
expressi
ssion
on is undef
undefine
ined,
d, an er
error
ror o
occu
ccurs.
rs.

 A.13
 A .13 Uns
Un s et Val
aluu es
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:

Op er at o r Wh en A p p l i ed t o an UNSET

EQ, GT, GE, LT, LE Results in FALSE.

NE Results in TRUE.
OR , AND Values are treated as FALSE.

For example, if DESP(2) and LVAL(3) are unset then:

( DE
DESP( 2)
2) GT 99) - > Fal s e
( DE
DESP( 2)
2) NE 33) - > Tr ue
ue

( : L VAL ( 3) AND TRUE) - > Fal s e

  A: 43 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual
PML 1 Expressions
  A: 44 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual

Index

 A COSINE  . . . . . . . . . . . . . . . . . . . . . . . . A:18
CREATED  . . . . . . . . . . . . . . . . . . . . . . . A:7
ABS  . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:15
ACOS  . . . . . . . . . . . . . . . . . . . . . . . . . . A:15
ADD  . . . . . . . . . . . . . . . . . . . . . . . . . . . A:13
D
AFTER  . . . . . . . . . . . . . . . . . . . . . . . . . A:32 DEFINED  . . . . . . . . . . . . . . . . . . . . . . . . A:7
ALOG  . . . . . . . . . . . . . . . . . . . . . A:16, A:18 DELETED . . . . . . . . . . . . . . . . . . . . . . . . A:8
AND  . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:3 DISTANCE  . . . . . . . . . . . . . . . . . . . . . . A:33
AREA command ( Design and )   . . . . . 2:200 format . . . . . . . . . . . . . . . . . . . . . . . A:33
Area view gadget  . . . . . . . . . . . . . . . . 2:200 US format . . . . . . . . . . . . . . . . . . . . A:33
Area view setup mode  . . . . . . . . . . . . 2:200 DIVIDE  . . . . . . . . . . . . . . . . . . . . . . . . . A:13
ARRAY  . . . . . . . . . . . . . . . . . . . . . . . . . A:16
ARRAYSIZE   . . . . . . . . . . . . . . . . . . . . . A:16
E
ARRAYWIDTH   . . . . . . . . . . . . . . . . . . . A:17
ASIN  . . . . . . . . . . . . . . . . . . . . . . . . . . . A:15 EMPTY  . . . . . . . . . . . . . . . . . . . . . . . . . . A:8
ATAN   . . . . . . . . . . . . . . . . . . . . . . . . . . A:15 EQUAL  . . . . . . . . . . . . . . . . . . . . . . . . . . A:4
ATANT  . . . . . . . . . . . . . . . . . . . . . . . . . A:15 Event
Attributes Control System  . . . . . . . . . . . . . . . . 3:6
in expressions  . . . . . . . . . . . . . . . . A:41 Flow  . . . . . . . . . . . . . . . . . . . . . . . . . 3:5
Packet  . . . . . . . . . . . . . . . . . . . . . . . 3:5
B Event Driven Graphics  . . . . . . . . . . . . . . 3:1
Event Packet  . . . . . . . . . . . . . . . . . . . . 3:11
BADREF  . . . . . . . . . . . . . . . . . . . . . . . . . A:6 Example
BEFORE  . . . . . . . . . . . . . . . . . . . . . . . . A:32 Defining Pick Sequences  . . . . . . . . 3:52
Boolean operators . . . . . . . . . . . . . . . . . . A:3 Repeat Element Pick  . . . . . . . . . . . 3:24
Single Element Pick  . . . . . . . . . . . . 3:23
 C Using Pick Packets  . . . . . . . . . . . . 3:54
Expressions
COLUMNFORMAT  . . . . . . . . . . . . . . . . 2:35 directions in  . . . . . . . . .A:28
. A:28, A:29, A:31
Comparator operators  . . . . . . . . . . . . . . . A:3 format . . . . . . . . . . . . . . . . . . . . A:1, A:2
Comparison precision
in expressions   . . . . . . . . . . . . . . . . A:42 IDS in  . . . . . . . . . . . . . . . . . . . . . . . A:22
logical . . . . . . . . . . . . . . . . . . . . . . . . A:2
Components  . . . . . . . . . . . . . . . . . . . . . . 3:3 logical array  . . . . . . . . . . . . . . . . . . A:11
Main  . . . . . . . . . . . . . . . . . . . . . . . . . 3:3 nesting  . . . . . . . . . . . . . . . . . . . . . . . A:2
Secondary  . . . . . . . . . . . . . . . . . . . . 3:3 numeric  . . . . . . . . . . . . . . . . . . . . . A:12

Index page i 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual

PML  . . . . . . . . . . . . . . . . . . . . . . . . . A:1 LE  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5

positions in  . . . . . . . . . . . . . . . . . . . A:23 LENGTH . . . . . . . . . . . . . . . . . . . . . . . . A:18
precision of comparisons  . . . . . . . . A:42 Logical functions  . . . . . . . . . . . . . . . . . . A:6
real  . . . . . . . . . . . . . . . . . . . . . . . . . A:12 LOWCASE  . . . . . . . . . . . . . . . . . . . . . . A:35
real array  . . . . . . . . . . . . . . . . . . . . A:22 LT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5
types  . . . . . . . . . . . . . . . . . . . . . . . . . A:1
M
F
MATCH  . . . . . . . . . . . . . . . . . . . . . . . . A:19
format distances  . . . . . . . . . . . . . . . . . . A:33 MATCHWILD  . . . . . . . . . . . . . . . . . . . . . A:8
FROM  . . . . . . . . . . . . . . . . . . . . . . . . . . A:25 MAX  . . . . . . . . . . . . . . . . . . . . . . . . . . . A:19
Functions MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:19
logical  . . . . . . . . . . . . . . . . . . . . . . . . A:6 MODIFIED  . . . . . . . . . . . . . . . . . . . . . . . A:9
numeric  . . . . . . . . . . . . . . . . . . . . . . A:14 Multi Discipline Route Manager   . . . . . 2:106
real  . . . . . . . . . . . . . . . . . . . . . . . . . A:14 MULTIPLY  . . . . . . . . . . . . . . . . . . . . . . A:13

G N

Gadget
2D Screen Position  . . . . . . . . . . . . . 2:10 NEGATE   .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .A:19
NEQUAL A:4
Anchoring  . . . . . . . . . . . . . . . . . . . . . 2:7 NINT  . . . . . . . . . . . . . . . . . . . . . . . . . . . A:20
BAR  . . . . . . . . . . . . . . . . . . . . . . . . 2:25 NOT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5
BUTTON  . . . . . . . . . . . . . . . . . . . . . 2:29 NUMBER (REAL)  . . . . . . . . . . . . . . . . . A:20
COMBOBOX  . . . . . . . . . . . . . . . . . 2:37 Numeric expressions  . . . . . . . . . . . . . . A:12
CONTAINER  . . . . . . . . . . . . . . . . . 2:41 Numeric operators  . . . . . . . . . . . . . . . . A:13
Docking  . . . . . . . . . . . . . . . . . . . . . . 2:7
FRAME  . . . . . . . . . . . . . . . . . . . . . . 2:68 O
LINE  . . . . . . . . . . . . . . . . . . . . . . . . 2:76
LIST  . . . . . . . . . . . . . . . . . . . . . . . . 2:88 OBJECT  . . . . . . . . . . . . . . . . . . . . . . . 2:113
OPTION  . . . . . . . . . . . . . . . . . . . . 2:113 Object
PARAGRAPH  . . . . . . . . . . . . . . . . 2:118 ALERT  . . . . . . . . . . . . . . . . . . . . . . 2:11
Positioning  . . . . . . . . . . . . . . . . . . . . 2:8 ARC  . . . . . . . . . . . . . . . . . . . . . . . . 2:12
RTOGGLE  . . . . . . . . . . . . . . . . . . 2:161 ARRAY  . . . . . . . . . . . . . . . . . . . . . 2:20
SELECTOR  . . . . . . . . . . . . . . . . . 2:168 BANNER  . . . . . . . . . . . . . . . . . . . . 2:24
SLIDER  . . . . . . . . . . . . . . . . . . . . 2:173 BLOCK . . . . . . . . . . . . . . . . . . . . . . 2:27
Syntax Graphs  . . . . . . . . . . . . . . . . . 2:6 BOOLEAN   . . . . . . . . . . . . . . . . . . . 2:27
Tagwidth  . . . . . . . . . . . . . . . . . . . . . 2:10 BORE . . . . . . . . . . . . . . . . . . . . . . . 2:28
TEXTPANE   . . . . . . . . . . . . . . . . . 2:188 Classification  . . . . . . . . . . . . . . . . . . 2:1
TOGGLE  . . . . . . . . . . . . . . . . . . . 2:190 COLLECTION  . . . . . . . . . . . . . . . . 2:33
Width and Height  . . . . . . . . . . . . . . . 2:9 COLUMN  . . . . . . . . . . . . . . . . . . . . 2:34
GE  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5 DATEFORMAT  . . . . . . . . . . . . . . . 2:42
Graphical Selection  . . . . . . . . . . . . . . . . 2:72 DATETIME . . . . . . . . . . . . . . . . . . . 2:43
GT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5 DB  . . . . . . . . . . . . . . . . . . . . . . . . . 2:45
DBREF . . . . . . . . . . . . . . . . . . . . . . 2:47
I DBSESS  . . . . . . . . . . . . . . . . . . . . 2:48
 DIRECTION  . . . . . . . . . . . . . . . . . . 2:48
IDList  . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:74 EXPRESSION   . . . . . . . . . . . . . . . . 2:50
IDs in expressions . . . . . . . . . . . . . . . . . A:22 FILE  . . . . . . . . . . . . . . . . . . . . . . . . 2:51
INT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:18 FMSYS  . . . . . . . . . . . . . . . . . . . . . 2:53
FORM  . . . . . . . . . . . . . . . . . . . . . . 2:56
L FORMAT  . . . . . . . . . . . . . . . . . . . . 2:65
LINE  . . . . . . . . . . . . . . . . . . . . . . . . 2:77
Late evaluation of expressions  . . A:21, A:40 LINEARGRID  . . . . . . . . . . . . . . . . . 2:86
Late evaluation of variables  . . . . . . . . . A:40 LOCATION  . . . . . . . . . . . . . . . . . . 2:93

Index page ii 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual

MACRO  . . . . . . . . . . . . . . . . . . . . . 2:95 Prompts

MDB  . . . . . . . . . . . . . . . . . . . . . . . . 2:95 Change  . . . . . . . . . . . . . . . . . . . . . . 3:9
MEASURE  . . . . . . . . . . . . . . . . . . . 2:97 Published Interface  . . . . . . . . . . . . . . . 3:15
MENU  . . . . . . . . . . . . . . . . . . . . . . . 2:99
NUMERICINPUT  . . . . . . . . . . . . . 2:111 Q
ORIENTATION  . . . . . . . . . . . . . . . 2:117
PLANE  . . . . . . . . . . . . . . . . . . . . . 2:120 Querying
PLANTGRID  . . . . . . . . . . . . . . . . . 2:124 variables and expressions  . . . . . . . A:41
POINTVECTOR  . . . . . . . . . . . . . . 2:131
POSITION  . . . . . . . . . . . . . . . . . . 2:134 R
POSTEVENTS   . . . . . . . . . . . . . . . 2:139
PROFILE  . . . . . . . . . . . . . . . . . . . 2:141 REAL  . . . . . . . . . . . . . . . . . . . . . . . . . . A:20
PROJECT  . . . . . . . . . . . . . . . . . . . 2:140 Real arrays in expressions  . . . . . . . . . . A:22
RADIALGRID  . . . . . . . . . . . . . . . . 2:151 Real expressions  . . . . . . . . . . . . . . . . . A:12
REAL  . . . . . . . . . . . . . . . . . . . . . . 2:153 Relational operators  . . . . . . . . . . . . . . . . A:3
REPORT  . . . . . . . . . . . . . . . . . . . 2:158 REPLACE  . . . . . . . . . . . . . . . . . . . . . . A:35
SESSION   . . . . . . . . . . . . . . . . . . . 2:171 Rule Combination . . . . . . . . . . . . . . . . . 3:60
STRING  . . . . . . . . . . . . . . . . . . . . 2:175
TABLE
TEAM   . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. 2:182
2:184 S
Type Details  . . . . . . . . . . . . . . . . . . 2:11 Section Plane  . . . . . . . . . . . . . . . . . . . 2:163
UNDOABLE  . . . . . . . . . . . . . . . . . 2:192 Manager  . . . . . . . . . . . . . . . . . . . . 2:165
UNIT  . . . . . . . . . . . . . . . . . . . . . . . 2:193 SINE  . . . . . . . . . . . . . . . . . . . . . . . . . . . A:18
USER  . . . . . . . . . . . . . . . . . . . . . . 2:195 SQRT  . . . . . . . . . . . . . . . . . . . . . . . . . . A:21
XYPosition  . . . . . . . . . . . . . . . . . . 2:206 STATE  . . . . . . . . . . . . . . . . . . . . . . . . 2:182
Objects STRING  . . . . . . . . . . . . . . . . . . . . . . . . A:38
Forms and Menus  . . . . . . . . . . . . . . 2:4 SUBSTRING  . . . . . . . . . . . . . . . . . . . . A:39
Methods Available  . . . . . . . . . . . . . . 2:3 SUBTRACT  . . . . . . . . . . . . . . . . . . . . . A:13
OCCUR  . . . . . . . . . . . . . . . . . . . . . . . . . A:20
Operators T
logical  . . . . . . . . . . . . . . . . . . . . . . . . A:3
numeric  . . . . . . . . . . . . . . . . . . . . . . A:13 TANGENT  . . . . . . . . . . . . . . . . . . . . . . A:18
text  . . . . . . . . . . . . . . . . . . . . . . . . . A:31 Text functions  . . . . . . . . . . . . . . . . . . . . A:32
OR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:6 Text operator   . . . . . . . . . . . . . . . . . . . . A:31
TRIM  . . . . . . . . . . . . . . . . . . . . . . . . . . A:39
P
U
Packet
Add  . . . . . . . . . . . . . . . . . . . . . . . . . . 3:8 UNDEFINED  . . . . . . . . . . . . . . . . . . . . . A:7
Remove  . . . . . . . . . . . . . . . . . . . . . . 3:9 Undefined values
PART  . . . . . . . . . . . . . . . . . . . . . . . . . . A:35 in expressions  . . . . . . . . . . . . . . . . A:42
Pick  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:59 Units
Filtering  . . . . . . . . . . . . . . . . . . . . . . 3:59 in expressions  . . . . . . . . . . . . . . . . A:41
Pick Data . . . . . . . . . . . . . . . . . . . . . . . . 3:63 UNSET  . . . . . . . . . . . . . . . . . . . . . . . . . A:10
Pick Packet  . . . . . . . . . . . . . . . . . . . . . . 3:30 Unset values
 Pick Sequence  . . . . . . . . . . . . . . . . . . . . 3:5 in expressions  . . . . . . . . . . . . . . . . A:43
Pick Type  . . . . . . . . . . . . . . . . . . . . . . . 3:56 US format distances  . . . . . . . . . . . . . . . A:33
Picked Position Data  . . . . . . . . . . . . . . . 3:64
PLATFORMGRID  . . . . . . . . . . . . . . . . 2:125 V
PMLSECURELOGIN
PMLUSERLOGIN  . . . .. .. .. .. .. .. .. .. .. .. .. .. .. 2:130
2:131 VERIFY  . . . . . . . . . . . . . . . . . . . . . . . 2:196
Positions View
comparing  . . . . . . . . . . . . . . . . . . . . A:27 the Stack  . . . . . . . . . . . . . . . . . . . . 3:10
POWER  . . . . . . . . . . . . . . . . . . . . . . . . A:21 VIEW Gadget

Index page iii 12 Series

 Soft ware Customis ation Reference

Reference Manual
Manual

AREA View  . . . . . . . . . . . . . . . . . . 2:199

PLOT View  . . . . . . . . . . . . . . . . . . 2:201
VOLUME Views  . . . . . . . . . . . . . . 2:203
View Gadget
ALPHA Views  . . . . . . . . . . . . . . . . 2:198
ViewFinder   . . . . . . . . . . . . . . . . . . . . . 2:196
VLOGICAL  . . . . . . . . . . . . . . . . . . . . . . A:11
VTEXT  . . . . . . . . . . . . . . . . . . . . . . . . . A:40
VVALUE  . . . . . . . . . . . . . . . . . . . . . . . . A:21

W
WRT  . . . . . . . . . . . . . . . . . . . . . . . . . . . A:23