vdp programmable macro language
DESCRIPTION
pmlTRANSCRIPT
-
VPDProgrammable Macro Language PML & PML2
-
2Agenda
Introductions Objectives Course Format Prerequisites
-
3Introductions
Who am I? Who are you?
Company Job Description Knowledge of PDMS Expectation of course
-
4Prerequisites
Text editor Notepad UltraEdit Emacs
PDMS Environment PMLLIB work area PDMS project
Knowledge of PDMS PDMS 11.4 or above
-
5Objectives
Broad overview of the PML language Basic coding practices and conventions How PML interacts with the Design model How Forms and Menus work with PML
-
6Course Format
Overview of language syntax Terminology Examples Practical Exercises
-
7Course Contents
Day 1 - PML Overview and Program Flow Control
Day 2 - PML2 Overview - Functions, Forms and Objects
Day 3 - Form Creation
Day 4 - More Form Creation and User Defined Objects
Day 5 Collections and View Gadgets
-
8Day 1
PML Overview and Program Flow Control
-
9PML Overview
Macros - What macros are and how to use them PML - Programmable Macro Language (two parts) PML1 - First version of PML including loops, if
statements, string handling, labels etc. PML2 - Object orientated language builds on PML1
and extends the facilities to be like other object based languages (VB, Smalltalk)
Forms Most applications are driven by forms and menus. Most PML will be based on a form.
-
10
PML Programmable Macro Language
Macros are text files containing PDMS commands in sequence
PML1 macros are text files containing program statements such as IF statements and DO loops
Macros & PML1 Macros are run in PDMS by $m/FILENAME Arguments may be passed to a macro on the command line:
$M/BUILDBOX 100 200 300 means that the extra 3 values after the macro name are treated as arguments 1, 2 and 3These can be used within the macro to set PDMS attributes or to perform calculations
-
11
PML2 is an Object Oriented Language
PML2 is more like other modern languages
Typically, fewer lines of code needed with PML2
Designed to be easier to read and easier to write
PML2 allows more powerful and sophisticated applications to be written
-
12
PML 2 Jargon
OOP
METH
ODS
Objects
Functions
Object BlocksPMLLIB
Variable T
ypes
Tooltips
Frames
Rgroups
.pmlfnc
.pmlfrm.pmlobj
-
13
Features Of PML2
Variable Types - STRING, REAL, BOOLEAN &ARRAY
Built in methods for commonly used actions Functions accept arguments and return results User Defined Object Types PML Search Path (%PMLLIB%) Dynamic Loading of Forms, Functions and Objects New Aid objects for geometric modelling
-
14
PML1: A Simple Macro
NEW EQUIP NEW EQUIP //FREDFREDNEW BOXNEW BOXXLEN XLEN 300300 YLEN YLEN 400400 ZLEN ZLEN 600600NEW CYL DIA NEW CYL DIA 400400 HEI HEI 600600CONN PCONN P11 TO PTO P22 OF PREVOF PREV
Text filemyFile.mac
To run a macro use the PDMS command line
-
15
NEW EQUIP / $1NEW BOXXLEN $2 YLEN $3 ZLEN $4NEW CYL DIA $3 HEI $4CONN P1 TO P2 OF PREV
Macros can be parameterised:
To run a macro with parameters:
text filemyFile.mac
$M/myFile.mac V1001 300 400 600
PML1: A Simple Macro with Parameters
-
16
PML1: More on macros
Macros may have up to 9 parameters separated by space$M/FRED HELLO HOW ARE YOU 55 66 77 88 99
1 2 3 4 5 6 7 8 9 text strings may be entered as a single parameter using
$< and $> to enclose the string:$M/FRED $< HELLO HOW ARE YOU $> 55 66 77 88 99
1 2 3 4 5 6 $< $> act as delimiters and anything in between is interpreted
as a single parameter
-
17
PML1: Synonyms
Synonyms are abbreviations of longer commands they are created as follows:$SXXX=NEW ELBO SELECT WITH STYP LR ORI P1 IS N
Synonyms can be parameterised$SYYY=NEW BOX XLEN $S1 YLEN $S2 ZLEN $S3
To call this: YYY 100 300 2000 This would expand the command YYY to the new box
command and interpret the three input values as parameters just like a macro
-
18
PML1: More on Synonyms
Synonyms may be recursive Example - To change parameter number 6 on a range of
components:$SXXX=PARAM N6 462 $/ NEXT $/ XXX
NOTE: $/ ACTS AS A RETURN CHARACTER To kill a synonym $SXXX= To kill all synonyms $sk BEWARE: this will stop the
AVEVA applications from working properly! To switch synonyms off and on $S- and $S+
-
19
Exercise 1
Before starting this exercise copy the pmllib directory identified by your trainer to your C: drive. Then edit the evars.bat file in the %pdmsexe% directory to include your c:\pmllib directory in the
%pmllib% environment variable.
You can now enter PDMS
-
20
PML1: Numbered Variables
Numbered Variable types. var 1 name var 2 hello var 3 (99) var 4 (99 * 3 / 6 + 0.5) var 117 pos in site var 118 (name of owner of owner) var 119 hello + world + how are you
-
21
PML1 & PML2: Named Variables
Named variables !variablename or !!variablename single ! Means a local variable double !! Means a global variable
variable names may be up to 16 characters long and the names can contain alpha and numeric characters
NEVER start a variable name with a number NEVER use . (dot or period) In variable names
-
22
PML1: Setting Named Variables
VAR !FRED NAMETakes the current elements (ce) name
VAR !POS POS IN WORLDTakes ce position relative to world coordinates VAR !x NAMESets the variable to the text string NAME NOTE: Quotes or vertical bars | | may be used as text delimiters
-
23
VAR !temp (23 * 1.8 + 32)Calculate a value using the expression VAR !list collect all ELBOW for CEMakes a string array of database references
PML1: Setting Named Variables (Contd)
-
24
PML2: Variable Data Types
There are four basic variable data types:
STRING ANY ALPHA NUMERIC CHARACTERS REAL ANY REAL NUMERIC VALUE BOOLEAN TRUE or FALSE ARRAY ANY COMBINATION OF THE ABOVE
Arrays in PML are sparsely populated and heterogeneous
-
25
PML2: Setting Variables
To create a LOCAL, STRING variable!Name = Fred
To create a GLOBAL, REAL variable: !!Answer = 42
To create a GLOBAL, BOOLEAN variable: !!Flag = TRUE
To create a LOCAL empty ARRAY!Values = ARRAY()
To create a LOCAL ARRAY with one entry!newarray.append(xxx)
-
26
PML1: Example of LOCAL vs- GLOBAL Variables
Run this macro on the command line and see the effect:
$m/c:\pmllib\mac1
-
27
PML1 & PML2: Using Variables in PDMS Command Syntax
To expand PML variables in a PDMS command you need to use a $ infront of the variable name:
!XLEN = 1000!YLEN = !XLEN + 100!ZLEN = !XLEN + 1000
NEW BOX XLEN $!XLEN YLEN $!YLEN ZLEN $!ZLEN
-
28
PML1 & PML2: Expressions
Expressions are calculations using PML variables
Using PML1:VAR !Z ( $!X + $!Y )
NOTE: all PML1 variables are STRING data types
Using PML2:!Z = !X + !Y
-
29
PML2: Expression Examples
Expression operators + - / * LT GT EQ NE LE GE NOT AND OR SIN COS TAN SQR POW NEGATE ASIN ACOS ATAN LOG ALOG ABS INT NINT
!s = 30 * sin(45)!t = pow(20,2) - raise 20 to the power of 2!f = (match(name of owner,LPX) gt 0)
-
30
PML1 & PML2: Operator Precedence
()* /+ -EQ NE GT LT GE LENOT ANDOR
Example:(60 * 2 / 3 + 5) = 45
-
31
PML2: Expressions (Contd)
May be of any complexity May contain calls to PML Functions and Object Methods May include Form gadget values ,object members and
methods.
For example:
!NewVal = !!MyFunc(!x) * !!Form.length.val / !MyArray.size()
-
32
PML2: Using Variables in Expressions
$ and quotes are not necessary when using the value of a variable in a PML2 expression:!X = 64 instead of VAR VAR !!X X ((6464)) !Y = 32!Z = !X + !Y
!Z would be set the the REAL value 96
The same expression PML1:VAR !Z ( $!X + $!Y )
Remember all PML1 variables are STRINGs so in the above example !Z would be the STRING value 96 not a REAL
-
33
Arrays
!x[1] = Hello!x[2] = World!y[1] = fred!y[2] = cup!z[1] = !x!z[2] = !yq var !z[1][2] Worldq var !z[2][2] cup
An ARRAY variable can contain many values, each of whichis called an array element
An array is created automaticallyby creating one of its array elements
An array element may itself be an array: Multi - dimensional Arrays
-
34
Exercise 2
-
35
DO !ppoint FROM 1 TO 6PDMS/PML Syntax
ENDDO
Open Do Loops:
DO PDMS/PML SyntaxBreak condition
ENDDO
Do loops
BREAK IF (!COUNT GT 12)
IF (!X EQ !Y) THENBREAK
ENDIF
-
36
Do loops (contd)
It is possible to skip part of the do loop using the skipcommand
DO PDMS/PML SyntaxSKIP condition
ENDDO IF(!X = !Y)THENSKIPENDIF
SKIP IF (!COUNT GT 12)
-
37
Do Index and Do Values are ways of looping through arrays
DO !X values !ARRAY!X takes each ARRAY element value
ENDDO
DO !X Index !ARRAY!X takes a number from 1 to !ARRAY size
ENDDO
Do loops (contd)
-
38
Do Loops Examples
var !Zones collect all zones for sitevar !name evaluate (Name) for all from !Zones
DO !x values !name OR DO !x index !name$!x $!name[$!x]new text name $!x-AAA new text name $!name[$!x]-AAA
ENDDO ENDDO
-
39
IF Statements
The IF statement is a construct for conditional execution of commands
The simplest form of the IF construct is:
IF (expression) THENPDMS/PML Syntax
ENDIF
-
40
IF Statements
IF ( expression ) THENPDMS/PML Syntax
ELSEIF ( expression ) THENPDMS/PML Syntax
ELSEPDMS/PML Syntax
ENDIF
The ELSEIF statements allow for further conditions to be tested. Once the IFor one of the ELSEIFstatements has been found to be TRUE, any remaining ones are ignored.
The ELSE statement is used as a catch-all, if none of the IF/ELSEIFstatements was satisfied the commands in the ELSE block are used.
-
41
Branching
PML provides a way of jumping from one part of a program to another using golabel
The next line to be executed will be the line followingLABEL /FRED, which could be before or after theGOLABEL command.
PDMS/PML SyntaxGOLABEL /FRED PDMS/PML SyntaxLABEL /FRED PDMS/PML Syntax
-
42
Conditional Branching
If the expression is TRUE there will be a jump to LABEL /FREDif the expression is FALSE, PML will executethe More PDMS/PML Syntax
PDMS/PML SyntaxGOLABEL /FRED IF (!x.eq(100)) More PDMS/PML SyntaxLABEL /FRED PDMS/PML Syntax
-
43
Conditional Branching (Contd)
Do !A$P Processing $!Ado !B to 10
!C = !A * !Bgolabel /finished if (!C.gt(100))$P Product $!C
enddoenddolabel /finished$P Finished with processing = $!A Product = $!C
-
44
Errors & Error Handling
An error condition can occur because a command could not complete successfully or because of a syntax error in a macro or function. An error normally has three effects:
An Alert form appears which the user must acknowledge. An error message is output to the commands/requests
form with a trace-back of any calling macros or functions. Any current running or nested PML macros and functions are terminated
-
45
Format of an Error Code
This example of an error is caused by an attempt to use a PML variable which does not exist:
(46,28) ERROR - Variable FRED not defined.
The 46 is the Module or program section which identified the error and 28 is the Error Code itself.
-
46
Error Handling
If the input line was part of a PML macro or function the error may optionally be HANDLED.
e.g. Checking if a named element exists in PDMS:
/FRED Handle (2,109) $* Undefined name -- pml code executed when /FRED does not exist Elsehandle NONE -- pml code executed when /FRED does exist and no error occurs Endhandle
-
47
Error Handling (Contd)
An example containing multiple error handle, handle ANY and handle NONE:
$!ItemNameOrRefHandle (2,107) (2,109) $* Undefined name or reference
-- code to take action if these errors occurelsehandle any
-- An ANY Handle Block is processed for any errors. -- In this situation it would handle ANY errors other than (2,107) and (2,109)
elsehandle NONE-- A NONE Handle Block is processed only if there were no errors
endhandle
-
48
Day 2
PML2 Overview - Functions, Forms and Objects
-
49
The & STRING Concatenation Operator
Values to be concatenated are automatically converted to STRINGby the & operator. This example sets !Z to the STRING 64mmx32mm!X = 64!Y = 32!m = mm
!Z = !X & !m & x& !Y & !m Compare this which sets !Z to the REAL value 96
!X = 64!Y = 32
!Z = !X + !Y
-
50
PML1: PDMSUI Macro Hierarchy
PDMSUI environment variable setenv PDMSUI c:\AVEVA\PDMS11.5\pdmsui
$S CALLP=$M/%PDMSUI%/DES/PIPE/$s1CALLP MPIPE
DES
GEN ADMIN PIPE EQUI.
DRA ADMIN CLIB.
MPIPE
-
51
PMLLIB environment variable Pml.index file contains list of functions, forms & objects
3 New file extensions .pmlfnc .pmlfrm .pmlobj NOTE: All file names must be lower case! The pml.index file is created using the syntax:
PML REHASH and PML REHASH ALL
PML2: PMLLIB Hierarchy
pmllib
functions forms
xxx.pmlfnc xxx.pmlfrm
objects
xxx.pmlobj
-
52
The !!CE Object
A special GLOBAL PML variable !!CE always points to the current PDMS element and its attributes:
!BranchHeadBore = !!CE.Hbore!HeadPosition = !!CE.Hposition!Easting = !HeadPosition.East
To find a position with respect to another element you can use the .wrt() method for position object:
!PosWRTValve = !HeadPosition.WRT(!Valve)
-
53
The !!CE Object (Contd)
You can set attributes using the PML2 dot syntax. The format of the command is:
dbref.attributeName = PMLvariable For example: !!ce.poss = !pos
!dbref.name = '/PIPE-100'!!CE.Built = TRUE
You can even assign a PML object, such as POSITION, where this corresponds to the type of the attribute:!!CE .Position = !NewPosition
-
54
The !!CE Object (Contd)
Note that where the type of an attribute is a PML object, it is not possible to set an object member value directly it must be done in two stages:
!Pos = !!CE.Position!Pos.Up = 2000!!CE.Position = !Pos
-
55
PML2 Functions
Functions are new style macros which are called by name -call !!FunctionName()
Functions can have arguments and may return a result value:define function !!Area(!Radius is REAL) is REAL!CircleArea = !Radius.Power(2) * 3.142 or ( PI)return !CircleArea
endfunction Functions can be used in expressions:
!CylinderVolume = !!Area(2.3) * !HeightNOTE: Synonyms are disabled inside functions
-
56
Dynamic loading of Objects, Forms and Functions PML will automatically load an Object or FORM from file when
first used:!Person = object PRIMEMINISTER()show !!MyInputForm
To redefine an object once loaded:pml reload form !!MyInputForm pml reload object PRIMEMINISTER()
To recognise new files added after entering PDMS:pml rehash build index for first path in %PMLLIB%
or pml rehash all - build index for all paths in %PMLLIB%
-
57
Exercise 4
-
58
Using Methods
Once created, variables cannot change type. To translate one variable type into another, methods are
used.!x = 56 creates a string variable!y = (!x.real() * 2) creates a real using !xmethods can also be used in a comparison.If (!x.real().eq(56)) then
Other translation methods are string() and boolean()!z = !y.string()
Creates a new string variable !z from the real variable !x
-
59
Method Concatenation
Any number of methods can be combined providing the passed data is valid at each stage.!line = 'hello,world,how,are,you'!newline = !line.upcase().split(,).sort()q var !newline
[1] 'ARE'[2] 'HELLO' [3] 'HOW'[4] 'WORLD'[5] 'YOU'
-
60
Boolean Expressions and IF Statements
Expressions based on the logical methods such as EQ and GT give a BOOLEAN result which can be used directly in a PML if expression.
if ( !Value.ge(99)) then-- if !value is greater than or equal to 999 then-- execute this block of PML code
else-- otherwise execute this block of PML code
endif
-
61
Boolean Expressions and IF Statements
The expression can be a simple variable provided it is a BOOLEAN type variable:
!GreaterThanZero = !SomeValue.gt(0)if (!GreaterThanZero ) then
-- some PML code is executed if !SomeValue is greater -- than zeroendif
The expression could be a user-defined PML function that returns a BOOLEAN result:
if ( !!MyFunction() ) then
-
62
Converting a value to BOOLEAN
There is a built-in PML method for converting a value to a BOOLEAN:
!MyString = TRUEif ( !MyString.Boolean() ) then ...
-
63
Alert Forms
-
64
Alert Forms (Contd)
There are 3 types of alert to display text to the user in an Alert form:
!!Alert.Error( You cannot do this! )!!Alert.Message( Saving your data now' )!!Alert.Warning( Do not press this button again!' )
By default, all alert forms appear with the relevant button as near to the cursor as possible. To position an alert specifically, X and Y values can be specified as a proportion of the screen size
!!Alert.Error( You cannot do this! , 0.25, 0.1)
-
65
Alert Forms (Contd)
There are 2 types of alert which return a result, confirm, and question:
Confirm Alerts!Answer = !!Alert.Confirm( Are you sure! )
Confirm alerts return YES or NO as strings
Question Alerts!Answer = !!Alert.Question( OK to delete Site? )
Answer alerts return YES or NO or CANCEL as strings
-
66
Forms Are Global Objects
Forms are global variables and are referenced using the double exclamation mark !!
Querying a forms members can be done by:q var !!formnameTry Q var !!cdcmember on the command line
Querying a gadget can be done in a similar way:q var !!formname.gadgetnameq var !!formname.gadgetname.val
-
67
Form Definition
setup form !!myform!this.formTitle = My Form Title!!myform.initcall = !this.init()..
exit
define method .init().....endmethod
-
68
Showing and Hiding Forms
The PMLLIB search-path mechanism means that pre-loading each form is not necessary.
To show a form use:show !!formname This will load the form
definition and show it in one operation! Sometimes it is useful to have the form loaded so you can
use the forms gadgets to store data without the form being shown or used directly by the user (a hidden admin form)
To load a form and not show it:loadform !!secretAdminForm
-
69
Built-in Methods for Forms
A variety of useful method have been provided: To show a form:
!!Myform.Show()
To hide a form:!!Myform.Hide()
To query whether a form is currently shown:if ( !!Myform.Shown() ) then:endif
-
70
Form Gadgets
There are many kinds of form gadgets as you will see on the following slides.
When you are defining gadgets on a form, there are two common aims. Define the area to be taken up on the form Define the action to be taken if the gadget is selected
Each gadget size and position determines the area taken up The action is defined by the gadgets CALLBACK
-
71
Built-in Methods for Gadgets
Gadgets are form member objects each with their own members (attributes) and a variety of useful built-in methods:
To grey-out a button set the Active member to FALSE:
!!Myform.myButton.Active = FALSE
To move the keyboard focus to a gadget use the .setFocus()method:
!!Myform.myTextField.setFocus()
-
72
Callbacks
Any selectable gadget has a callback which is defined at the time the gadget is created.
The callback can do one of three things: show a form execute a command directly run a function or method
button .opt |Options| call |show !!optionsform| button .del |Delete| call |delete equipment|button .apply |Apply| call |!!Myfunction()|button .apply |Apply| call |!this.MyMethod()|
-
73
Form Callbacks (Initcall)
The forms initialisation callback allows the forms gadgets to be initialised to reflect the current state of the application. This callback is used each time the form is shown.
You can set the callback by assigning to the forms initcall member:
!this.initcall = Callbackstring
Note: The callback must NOT attempt to display another form!
-
74
Form OK Callback
A forms OK callback is typically used when the form interaction is complete and the user hits the OK button.
You can assign to the forms OKCALL member using the syntax:
!this.OKCALL = !this.myFormOK()The above example calls a form method .myFormOK()
This callback would be actioned from a button defined with the ok syntax in its definition:
button .ok OK at xmax ymin ok
-
75
Form CANCEL Callback
A forms CANCEL callback is typically used when the form is no longer required and the user hits the Cancel button.
You can assign to the forms CANCELCALL member using the syntax:
!this.CANCELCALL = !this.myFormCancel()The above example calls a form method .myFormCancel()
This callback would be actioned from a button defined with the cancel syntax in its definition:
button .cancel Cancel at xmax ymin cancel
-
76
A Simple Form
setup form !!hello!this.formTitle = myFirstFormparagraph .Message text Hello worldbutton .bye Goodbye ok
exit
File: c:\pmllib\hello.pmlfrm
-
77
Gadget Positioning
Gadgets are positioned on a form from top left
Form Origin
Gadget Origin
-
78
Each Gadget has four label points XMIN, XMAX YMIN YMAX
These can be used for positioningAt Xmin .apply Ymax - 0.5at yminat xmax .frame1 + 4
To position a gadget in the bottom right of the form, use-at xmax form - size
Gadget Positioning (Contd)
YMIN
YMAX
XMIN
XMAX
-
79
Relative to the Last Gadget
Toggle .OnOff at XMIN YMAX+1
Relative Gadget Positioning
-
80
Relative to Specific Prevoius Gadgets
Toggle .OnOff at XMIN .Gadget1-size YMAX .Gadget1 +1
Relative Gadget Positioning (Contd)
-
81
Gadget Positioning : Path and Align
The path command can be used to define the logical position of subsequent gadgets.PATH DOWN means that the next gadget will be below the current one, PATH RIGHT means that the next gadget will be to the right of the current one.
The spacing between gadgets is controlled by VDIST and HDIST for vertical and horizontal spacing.
There are settings of HALIGN and VALIGN which can set the alignment LEFT,RIGHT,TOP and BOTTOM.
-
82
Gadget Positioning Example
-
83
Paragraph Gadgets
Paragraph gadgets are simple named gadgets which allow a piece of text or a PIXMAP to be displayed on a form.
Para .cwd at X0 Y0 Text 'Current directory'
-
84
Button Gadgets
Button .Button Pop Form FORM !!PopForm Button .Calculate Calculate Callback !!MyFunctionName()Button .Apply Apply Callback !!MyFunction()Button .ok OK Callback !!MyFunction() OKButton .cancel Cancel Callback !!MyFunction() CANCELButton .reset Reset Callback !!MyFunction() RESETButton .help Help Callback !!MyFunction() HELPButton .dismiss Dismiss OK
-
85
Button Gadgets (Contd)
Change the background colour of a button:
!!ex5.Apply.Background = 2
Add a picture to a button:
Button .Apply pixmap /c:/pmllib/aveva.bmp
-
86
Frame Gadgets
A Frame is a cosmetic gadget which is used to surround a group of similar gadgets.
The syntax is:
frame .myFrame My Frame at X0 Y3button .b1 Press Herebutton .b2 Or Press Here
exit
-
87
Text Gadgets
A text input gadget provides a place on a form into which the user may type a value.
Text .DirName callback '!This.TopDir()' AT X 0 Width 50 is String
-
88
List Gadgets
A list gadget allows the user to make a single or multiple choice from many alternatives.
List .SubDirs 'Sub Dirs CallBack '!This.SDirs() Width 60 Hei 4
-
89
Textpane Gadgets
A TEXTPANE gadget provides an area on a form into which a user may type and edit multiple lines of text. This gadget could also be used to display the contents of a text file. Textpane .textp Table at x3y6 width 50 hei 6
-
90
Exercise 5
-
91
Day 3
Form Creation
-
92
Exercise 6
-
93
Form INITIALISATION and CONSRUCTOR Methods Form initialisation and gadget callbacks as methods:
Setup form !!myform!this.initcall = !this.init().....Exit
Define method .myform() - - Constructor Method.. -- (called ONCE on form definition)Endmethod
Define method .init() - - Initialisation Method.. -- (called EACH TIME form is shown)Endmethod
-
94
Form INITIALISATION and CONSRUCTOR Methods Example:
setup form !!myform!!myform.initcall = '!!myform.init()'button .but 'Press me' Call ' ' at x 0
exit
define method .myform()$P The Form is now defined ready for use, but not visible
endmethod
define method .init()$P The Form is displayed to the user
Endmethod
-
95
Array Declaration
It is not possible to create a new array using the append mechanism. The array must be declared
!MyArray.append(Hello) would not work unless the array had been declared!
!MyArray = Array() declare array first!MyArray.append(Hello) now you can append an
element to the array
-
96
Methods for PML Arrays
Array methods are a powerful feature, they are built-in functions for performing a variety of operations on the array or returning information from the array
!NumberOfNames = !NameStrings.Size()
This method sets !NumberOfNames to the number of elements currently in the array. This is an example of a NO EFFECT method which does not alter the array but returns a REAL result assigned to !NumberOfNames.
-
97
Methods for PML Arrays (Contd)
Here is a method which does change the array:
!MyArray.Clear()
This method MODIFIES the array by deleting all the array elements but returns NO RESULT, so there is nothing to assign to another variable.
-
98
Methods for PML Arrays (Contd)
Here is a method which both changes the array and returns a result:
!NewArray = !OldArray.RemoveFrom(5,10)
The method result MODIFIES the array by removing 10 elements, starting at element 5. The ARRAY RESULT value !NewArray contains the 10 removed elements.
-
99
Methods for PML Arrays (Contd)
If not required, the result can be simply discarded by invoking the method as a command and not assigning the result to a variable:
!OldArray.RemoveFrom(5,10)
Always use an ARRAY METHOD, if one is available, in preference to constructing a DO LOOP as it is far more efficient.
-
100
Exercise 7
-
101
Methods for Objects
A large number of methods have been provided for the built-in PML data types: For example, for STRING objects, you will find a method named Length.
!Name = Nicole Kidman!NumberOfLetters = !Name.Length()
This method returns a REAL value (the number of characters in the string), but has NO EFFECT on the variable itself.
-
102
Methods for Objects (Contd)
Notice the dot . separator between the name of the variable and the name of the method.
Also note the brackets () following the name of the method. The brackets are used to enclose the arguments of the method. If there are no arguments for a method they must be present.
The following method creates an ARRAY of STRINGS:e.g. !NameStrings = !Name.Split()
!NameStrings = !Name.Split(%)
-
103
Form Gadget Tooltips
Tooltips are small help messages which pop-up when you move the mouse over a form gadget.
To create a tooltip:
button .modelEditor TOOLTIP TOOLTIP Model EditorModel Editor
Tooltips can be used for BUTTONS, TEXT, TOGGLE and OPTION gadgets only
-
104
Toggle Gadgets
Toggle gadgets are used for independent on/off settings.
...Toggle .bold Bold Call '!this.boldSelect()Toggle .italic Italic Call '!this.italicSelect()Toggle .underline Underline' Call '!this.underlineSelect()
-
105
Toggle Gadgets (Contd)
The value of a toggle gadget is set and used via the .valmember which is a BOOLEAN value:
if (!this.Bold.val.eq(true)) then-- some pml codeendif
The default value for a toggle is FALSE.
-
106
Rgroup Gadgets
A Radio Group (Rgroup) gadget is used to give the user a single choice between a small fixed number of options. It is displayed as a horizontal or vertical line of toggles each with a tag name displayed to the right of each toggle.
There is always one current selection forThe group.
-
107
Rgroup Gadget Callback
Normally there will be a single callback specified for the radio group as a whole
rgroup .vert |Alignment| FRAME vertical callback !this.vertSelect()add tag Left select Leftadd tag Centre select Cadd tag Right select R
exit
Sometimes you may need separate callback e.g.add tag Right select R callback !this.vertRightSelect()
-
108
Rgroup Select Keyword
The select keyword in the add command for each button defines its replacement text string (Rtext)
add tag Left select Left When you query the current selection using the gadgets
selection() method, q var !!Myform.vert.selection()it will return Rtext of the currently selected tag as a STRING.You could use this method in an expression like this:.if ( !this.vert.selection().eq(Left) ) then.
-
109
Rgroup .val member
The .val member of the Rgroup refers to the currently selected toggle within the group.
For example: !!Myform.vert.val = 2sets toggle 2 to be the Rgroups current selection.You could use this method in an expression like this:.if ( !this.vert.val.eq(2) ) then.
-
110
Exercise 9
-
111
Option Gadgets An option gadget offers a single choice from a list of items.
The items in the list can be either pixmaps or text strings, but not a mixture. The gadget displays the current choice in the list.
When the user selects the option gadget, the entire list of options appear as a drop-down list. The user can then select the required option with the cursor.
-
112
Option Gadgets (Contd)
The width of a text option gadget must be specified. A tag name is optional and is displayed to the left of the gadget.
option .Colour Colour width 10
The option gadget actually contains two parallel arrays of information. The display strings (Dtext ) and the replacement strings (Rtext ).
-
113
Option Gadgets (Contd)
The list of display values must be supplied by assigning an array of strings to the gadgets Dtext (Display text) member. This is the list of choices displayed to the user.
!ColourArray[1]=Black...!ColourArray[5]=Blue
!This.Colour.Dtext = !ColourArray
-
114
Exercise 10
-
115
Day 4
More Form Creation and User Defined Objects
-
116
Form Member Variables
A form can have variables associated with the form when it is built.
The form variables can be thought of as global variables stored in the form definition.
These local variables are called form member variables.
-
117
Form Member Variables (Contd)
Form member Variables may be of any data type:setup form !!Myformmember .CE is DBREFmember .String is STRINGmember .Values is ARRAY..
Exit
Form members are in effect GLOBAL variables:
!!Myform.Values.Append(!NewValue)
-
118
The CE button A CE button typically calls the form initialisation method to
reset the form for the current element in the database.
setup form !!myFormmember .CEREF is DBREF!this.initcall = |!this.init()|button .ce CE callback '!this.init()'para .cename width 30 height 1
exitdefine method .init()
!this.CEREF = !!CE!this.cename.val = fullname
endmethod
-
119
Formatted Text Gadgets
The FORMAT object controls the display format for REAL text gadget values. An example of this is imperial feet&inch units for distances, or imperial inch units for bores.
First, you would create a FORMAT object for a specific data type. This would normally be a global PML variable and would be used for all text input gadgets of that type.
-
120
Formatting Text Gadgets (Contd)
A text gadget can be automatically formatted using a FORMAT object:
!!FormatLength = object FORMAT()!!FormatLength.Units = FINCH
setup form !!Formattext .dist Distance is REAL format !!FormatLength
exit
-
121
Cadcentre Standard Format Variables
Cadcentre appware writers use four format objects as global variables. If you need to use a formatted text gadget you are recommended to use these supplied format objects:
!!DistanceFmt For distance units!!BoreFmt For Bore Units!!RealFmt To give a consistent level of
decimal places on real numbers!!IntegerFmt To force real numbers to be
integers(0 dp Rounded)Note: Using these global format objects will ensure your forms
will work in the project units specified by the settings>Units form.
-
122
Bar Menus
Forms may have a bar menu gadget which appears as a row of menus across the top of a form.
A bar menu is defined within the form definition. There are two reserved menu names: Window and Help which reference standard window and help menus respectively.
Here is an example of a Bar menu definition:Setup Form !!Test Dialog size 30 5
bar!This.bar.add('Choose','Menu1')!This.bar.add('Window','')!This.bar.add('Help','')
exit
-
123
Defining a Menu Object
Within the form definiton the menu sub-command creates a named menu object. You can then use the menus add method to add named menu fields. A menu field can do one of three things:
Execute a callback Display a form Display a sub-menu
-
124
Menu Object (Contd)
You can also add a visual separator between fields.menu .menu1!This.menu1.add(CALLBACK,Query,q ban)!This.menu1.add(FORM,Hello, hello)!This.menu1.add(SEPARATOR')!This.menu1.add(MENU,Pull-right1,Pull1)
Creates a menu menu1 with 3 fields Query, Hello and Pull-right1 and a separator between the last two fields
-
125
Exercise 11
-
126
Built in PML OBJECT Types
There are a large number of standard objects within PML2.
These are:All Variable types, BORE, DIRECTION, DBREF, FORMAT, MDB, ORIENTATION, POSITION, FILE, PROJECT, SESSION, TEAM, USER, ALERT, FORM, all form Gadgets and various graphical aid objects.
Each object has a set of built in methods for setting or formatting the object contents.
-
127
PML Built-in Objects
ARRAY Items underlined have already BLOCK been covered in the course BOOLEAN REAL STRING DATETIME FILE FORMAT
-
128
PDMS Objects
BORE DB DBREF DIRECTION MDB ORIENTATION POSITION PROJECT TEAM USER
-
129
Forms and Menus Objects (Gadgets)
ALERT ALPHA BAR BUTTON FORM FMSYS FRAME LIST MENU
OPTION PARAGRAPH RGROUP TEXT TEXTPANE TOGGLE VIEW 2D VIEW 3D VIEW
-
130
3D Geometry Objects
ARC LINE LINEARGRID PLANE PLANTGRID POINTVECTOR RADIALGRID XYPOSITION
-
131
The File Object
The old openfile, readfile, writefile and closefilesyntax has been superseded by a file object.
You can read or write files in one operation. To create a file object:!input = object file(C:\FileName)!output = object file(C:\FileName.out)
To Open a file in WRITE mode:!output.open(WRITE)
Options are: READ, WRITE, OVERWRITE, APPEND
-
132
Using File Objects
To read a line from file:!line = !input.ReadRecord()
To write a line to file:!line = !input.WriteRecord()
To read all the input file:!filearray = !input.ReadFile()
To write all of the data to file!output.WriteFile(WRITE,!filearray)
Files must be open
Files are opened andclosed automatically
-
133
File Object Methods
File objects extend the functionality of PML1, New Features include:
File type checking - File or Directory File open query - Is open ? File Owner Query File path array Files can now be moved to different directories File size can now be read Plus others..
-
134
Exercise 12
-
135
User Defined Objects
User Defined Objects Can contain any variable or object type as members.When an object is defined a variable needs to be set to create an instanceinstance of that object.
define object VIEWCLIPDATAmember .Pos is POSITIONmember .XLen is REALmember .YLen is REALmember .ZLen is REALmember .Ori is ORIENTATIONendobject !fr
ed = object viewclipdata()
-
136
User Defined ObjectsExample: Defining an Object:
define object ELEMENTmember .Type is STRINGmember .Material is STRING
endobject
Using an Object (creating an instance):!Item = object ELEMENT()!Item.Type = Flange!Item.Material = Carbon Steel
-
137
User Defined Methods Defining an object with a method:
define object ELEMENTmember .Type is STRINGmember .Material is STRING
endobjectdefine method .FullDesc() is stringreturn !this.Type & & !this.Material
endmethod Using an object method:
!Item = object ELEMENT() create an instance of ELEMENT! Item .type = FLANGE set the type! Item .material = Carbon Steel set the material!Name = !Item.FullDesc() call the method for full description
-
138
A Constructor METHOD
A Method with no arguments but the same name as the type of the object is called the default constructor method.define object LIFE
member .Answer is REALendobject
define method .Life()!This.Answer = 0
endmethodContd over
-
139
Method Overloading
A method of an object have the same name but a different signature i.e. different arguments in its definitiondefine method .Life()
!this.answer = 0endmethod
define method .Life(!Value is REAL)!this.answer = !Value
endmethod
-
140
Using Objects and Methods
!Marvin = object LIFE() The method .Life() is called automatically and the value
!marvin is 0!myLife = object LIFE()q var !myLife.Answer 0
Create new instance of object with Answer set to a value!myLife = object LIFE(40)q var !myLife.Answer 40
Answer member is now 40 because the 2nd constructor method was used with a parameter to set the initial value
-
141
Example User Defined Object
Take a look at the box.pmlobj file in your pmllib directory
Create an instance of a BOX Create an instance of a BOX with a predefined size Try using the volume and surfaceArea methods
Create a new user defined object for a CYLINDER Create methods for volume and surface area
-
142
Day 5
Collections and View Gadgets
-
143
The Collection Syntax
A very powerful feature of the PDMS database is the ability to collect and evaluate data according to rules.
Var !zone collect all zones for sitevar !name eval name for all from !zonevar !elbo coll all elbo with spref eq /A300/EL100Var !box coll all box for cevar !volume eval (xlen * Ylen * zlen) for all from !box
Note: Because this uses the var command, all collected items are STRING data types not DBREFs
-
144
The Compose Command
It is sometimes necessary to arrange text in multiple columns, reports are an example. The PML1 COMPOSEcommand will help you do this.
Compose always returns an array with at least one element. The number of the array elements depends on the length of the text strings supplied and the width of each column.
-
145
The Compose Command
E.g VAR !OUTPUT COMPOSE $$!name WIDTH 20 SPACE 1 $$!area WIDTH 14 SPACE 1 RIGHT $$!code WIDTH 4 LEFT
The result of a compose is an array !!!!!!VAR !X COMPOSE HELLO HOW ARE YOU WIDTH 5Q VAR !X!X[1] HELLO!X[2] HOW !X[3] ARE !X[4] YOU
-
146
View Gadgets
View gadgets are named gadgets which are used to display graphical data.
Plot View Volume View (Design) Area View (Draft)
-
147
Plot View
Plot View Example
setup form !!view View .view1 plot width 41 hei 25
exitexitdefine method .view()
!this.view1.borders = false!this.view1.add(c:/ladder.plt)
endmethod
-
148
Exercise 13 (part I)
-
149
Exercise 13 (part II)Time permitting
-
150
End of Course