Contents
1
Introduction
1.1
1.2
Basic Principles ................................................................................................................. 1 —1
How to Use This Manual ................................................................................................. 1—2
1.3
1.4
A Serious Warning Concerning Software Customisation ............................................. 1—2
Minimising Problems for Future Upgrades ................................................................... 1—3
Part I
Macros and Programmable Macros
2
The Command Processor
2.1
2.2
The Escape Character and Escape Codes ..................................................................... 2—4
Finding what Commands are Available ($Q) ................................................................. 2—4
3
Recording and Saving Command Line Inputs ($R and
Synonyms)
3.1
Introduction ........................................................................................................................ 3—1
3.2
Recording Command Input/Output ............................................................................... 3—1
3.2.1
The General Principles ..................................................................................... 3—1
3.2.2
Recording Command Inputs Only ................................................................... 3—2
3.3
3.2.3
Recording Command Inputs and Resulting Outputs ..................................... 3—4
Standard Synonyms ........................................................................................................... 3—4
3.3.1
Defining and Recalling Synonyms ................................................................... 3—4
3.3.2
Nested Synonyms ............................................................................................... 3—6
3.3.3
3.3.4
3.4
New Lines in Synonym Definitions ................................................................. 3—6
Arguments in Synonyms ................................................................................... 3—7
3.3.5
Examining, Redefining or Deleting Synonyms ............................................... 3—8
3.3.6
Disabling Synonym Translation ....................................................................... 3—9
3.3.7
Restrictions on Synonym Use ........................................................................... 3—10
Global Synonyms ............................................................................................................... 3—10
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4
User-Definable Variables
4.1
Local and Global Variables ............................................................................................. 4—1
4.2
4.1.1
Global Variables ............................................................................................... 4—1
4.1.2
Local Variables ................................................................................................. 4—1
Setting Variables ................................................................................................................ 4—2
4.2.1
4.2.2
4.2.3
4.2.4
4.3
4.4
4.5
4.6
4.7
Setting Variables to Text Strings ..................................................................... 4—2
Setting Variables to Expressions ..................................................................... 4—3
Setting Variables to Database Values ............................................................. 4—3
Setting Variables to Following Input ............................................................... 4—3
4.2.5
Defining Variables as Date and Time ............................................................. 4—4
Using Variables ................................................................................................................. 4—4
Querying Variables ........................................................................................................... 4—5
4.4.1
Querying the Current Settings of Variables ................................................... 4—5
4.4.2
Querying if a Named Variable is Set ............................................................... 4—5
Defining Variables for Late Evaluation ......................................................................... 4—6
Cancelling or Deleting Variables ..................................................................................... 4—6
Array Variables ................................................................................................................. 4—7
4.7.1
4.7.2
Setting Array Variables ..................................................................................... 4—8
Selecting Array Variables (PDMS Users Only) ............................................. 4 - 9
4.7.3
4.7.4
Evaluating Array Variables for Selected Elements (PDMS Users Only) .. 4—11
Accessing Array Variables ............................................................................... 4—12
4.7.5
Sorting Arrays ................................................................................................... 4—12
4.7.6
4.7.7
4.7.8
Subtotalling Array Variables ........................................................................... 4—16
Querying Array Variables ................................................................................. 4—17
Deleting Array Variables ................................................................................. 4—17
4.7.9
Handling Line Feeds and Consecutive Spaces ............................................... 4—19
5
Expressions
5.1
Format of Expressions ..................................................................................................... 5 —1
5.1.1
Operator Precedence ....................................................................................... 5—2
5.2
5.3
5.4
5.5
5.1.2
Nesting Expressions ......................................................................................... 5—2
5.1.3
Values in Mathematical Expressions ............................................................... 5—2
Logical Expressions ........................................................................................................... 5—2
5.2.1
Logical Operatorss ........................................................................................... 5—3
5.2.2
Logical Functions ............................................................................................. 5—5
5.2.3
Logical Array Expressions ............................................................................... 5—7
Numeric (Real) Expressions ........................................................................................... 5—7
5.3.1
Numeric (Real) Operators ............................................................................... 5—8
5.3.2
Numeric (Real) Functions ............................................................................... 5—9
5.3.3
Real Arrays ......................................................................................................... 5 —14
Using IDs in Expressions ................................................................................................. 5 —14
Positions, Directions and Orientations in Expressions (PDMS Only) ....................... 5 —15
5.5.1
ii
Using Positions in Expressions
CADCENTRE
Protected by copyright: see frontispiece
5 —15
CADCENTRE Software Customisation
Reference Guide
Issue 1095
5.5.2
5.5.3
5.5.4
5.6
WRT (PDMS Only) ........................................................................................... 5 - 1 6
FROM ............................................................................................................... 5 - 1 7
Comparing Positions ......................................................................................... 5—20
5.5.5
Directions ........................................................................................................... 5—21
Text Expressions ............................................................................................................... 5—22
5.6.1
Text Operator ..................................................................................................... 5—22
5.6.2
Text Functions ................................................................................................... 5—23
5.7
5.8
Late Evaluation of Variables in Expressions ................................................................. 5—30
PDMS Attributes ............................................................................................................... 5—31
5.9
5.10
5.11
5.12
Querying Expressions ....................................................................................................... 5—31
Units in Expressions ......................................................................................................... 5—31
Precision of Comparisions ............................................................................................... 5—32
Undefined Values ............................................................................................................. 5—33
5.12.1 Uuset Values ..................................................................................................... 5—33
6
Basics of Using Macros
6.1
Using Macros ..................................................................................................................... 6—1
6.2
6.3
6.4
Creating Macro Files ....................................................................................................... 6—1
Naming and Running Macros ......................................................................................... 6—2
Facilities Available When Using Macros ....................................................................... 6—2
6.5
6.6
6.7
6.4.1
6.4.2
6.4.3
6.4.4
The File End Marker ....................................................................................... 6—2
Nesting Macros ................................................................................................. 6—3
Interrupting Macro Execution ......................................................................... 6—3
Comment Lines in Macro Files ....................................................................... 6—4
6.4.5
6.4.6
Prompts and Messages From Within Macros ................................................. 6—4
General Editing Facilities ................................................................................. 6—5
6.4.7
Significant Line Length ................................................................................... 6—6
Parameterised Macros ..................................................................................................... 6—7
6.5.1
Macro Arguments ............................................................................................. 6—7
6.5.2
User-Definable Variables in Macros ............................................................... 6—9
Useful Query Facilities with Macros ............................................................................... 6—10
Examples of Some Simple PDMS Macros ..................................................................... 6—11
6.7.1
6.7.2
6.7.3
A Drawing Macro ............................................................................................. 6—11
An Equipment Construction Macro ............................................................... 6—11
A Component Selection Macro ....................................................................... 6—13
7
Programmable Macros and PML
7.1
Introducing PML ............................................................................................................... 7—1
7.2
Conditional Branching ..................................................................................................... 7—2
7.2.1
Defining a Conditional Construct ................................................................... 7—2
7.2.2
Nesting Conditional Constructs ....................................................................... 7—3
7.3
DO Loop Iterations ......................................................................................................... 7—3
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
iii
7.4
7.3.1
7.3.2
Defining a DO Loop ......................................................................................... 7—3
Leaving a DO Loop ......................................................................................... 7—4
7.3.3
7.3.4
7.3.5
7.3.6
Breaking Out From DO Loops ....................................................................... 7—4
Skipping DO Loop Iterations ......................................................................... 7—5
Nesting DO Loops ........................................................................................... 7—5
Using Elements of Array Variables to Control DO Loops ........................... 7—5
7.3.7
Accessing Gadget Values ................................................................................. 7—7
7.3.8
Example of a Simple DO Loop Macro ........................................................... 7—7
Jumping to Specific Command Lines ............................................................................. 7—7
7.4.1
7.4.2
Inserting a Label ............................................................................................... 7—7
Jumping to a Label ........................................................................................... 7—8
7.4.3
Examples ........................................................................................................... 7—8
7.5
7.6
Ending a PML Sequence ................................................................................................. 7—9
Constraints in Macros ....................................................................................................... 7—9
8
Handling Errors in Programmable Macros
8.1
8.2
The Principles of Error Handling ................................................................................... 8—1
Handling Specified Errors ............................................................................................... 8—1
8.3
Handling Unspecified Errors ........................................................................................... 8—3
8.3.1
Jumping to a Label ........................................................................................... 8—3
8.4
8.5
8.3.2
Continuing Macro Execution ........................................................................... 8—4
8.3.3
Pausing Macro Execution ................................................................................. 8—4
8.3.4
Terminating Macro Execution ......................................................................... 8—5
Handling Errors in Nested Macros ................................................................................. 8—5
Ending Programmable Macro Files ................................................................................. 8—6
8.6
8.7
A Summary of Error Handling Logic ............................................................................. 8—7
Handling Errors in Form Initialisation Macros ............................................................. 8—8
9
Reading/Writing External Files
9.1
9.2
9.3
9.4
Identifying Files ................................................................................................................. 9—1
Opening a File ................................................................................................................... 9—1
Writing to a File ............................................................................................................... 9—2
Reading from a File ......................................................................................................... 9—2
9.5
9.6
9.7
Closing a File ..................................................................................................................... 9—3
Querying the Status of Open Files ................................................................................. 9—3
Error Handling When Accessing Files ........................................................................... 9—3
10 Reference Section
10.1
10.2
Escape Codes ..................................................................................................................... 10—2
$R — Recording Command Input/Output ................................................................. 10—3
10.3
10.4
$S and $G — Synonyms ................................................................................................. 1 0 - 4
Operators ........................................................................................................................... 1 0 - 5
iv
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
10.5
10.6
10.7
10.4.1
10.4.2
Mathematical ..................................................................................................... 10—5
Logical ............................................................................................................... 10—6
10.4.3
Text ..................................................................................................................... 1 0 - 7
Variables ............................................................................................................................. 10-9
Array Variables ................................................................................................................. 10—10
Macros ................................................................................................................................ 10-12
10.7.1
10.7.2
10.7.3
10.8
Editing Macros ................................................................................................. 10-12
Running Macros ............................................................................................... 10—12
Programming Macros (PML) ........................................................................... 10—13
File Handling ..................................................................................................................... 10—16
Part II
User Interface Customisation
11 Introducing GUI Customisation
11.1
11.2
11.3
What It Means ................................................................................................................... 11 —1
Before You Start ............................................................................................................... 1 1 - 1
How Part II Is Set Out ..................................................................................................... 11—2
12 A Summary of the Graphical User Interface
12.1
12.2
12.3
The Menus and Forms Structure ..................................................................................... 12—1
Form Gadgets ................................................................................................................... 12—2
View Gadgets ..................................................................................................................... 12—4
12.4
12.5
12.6
Alert Forms ....................................................................................................................... 12—5
Loading the User Interface ............................................................................................. 1 2 - 5
General Start— Up Applications ..................................................................................... 1 2 - 6
12.6.1
12.6.2
FMINFO Command ......................................................................................... 1 2 - 6
SWAP Command ............................................................................................... 1 2 - 7
13 Naming Forms, Menus and Gadgets
14 Defining Forms
14.1
14.1 Entering and Leaving Form Setup Mode ........................................................... 14—1
14.2
14.3
14.2 Copying an Existing Form ..................................................................................... 14—2
14.3 Setting the Form’s Attributes ............................................................................... 1 4 - 2
14.3.1 Specifying the Form’s Type ............................................................................... 1 4 - 2
14.3.2 Specifying the Form’s Minimum Dimensions ............................................... 14—2
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
V
14.4
14.3.3 Specifying a User-Resizeable Form ................................................................. 1 4 - 3
14.3.4 Specifying the Form’s Screen Position ........................................................... 14—3
14.3.5 Concluding Form Attribute Setting ................................................................. 14—3
14.4 Giving the Form a Title ......................................................................................... 1 4 - 3
14.5
14.6
14.5 Specifying a Title for the Form’s Icon ................................................................. 1 4 - 4
14.6 Defining the Form’s Initial Settings ..................................................................... 14—4
14.7
14.8
14.7 Setting Revision Status Text ................................................................................. 1 4 - 4
14.8 Example ................................................................................................................... 14—5
15 Defining Menus
15.1
Defining a Menu Bar ....................................................................................................... 15 —1
15.1.1 Entering Menu Bar Setup Mode ..................................................................... 1 5 - 1
15.1.2 Adding Menu Bar Options ............................................................................... 1 5 - 1
15.1.3 Adding Help to the Menu Bar ......................................................................... 15—2
15.1.4 Leaving Menu Bar Setup Mode ..................................................................... 15—2
15.2
Defining a Pull-Down Menu ........................................................................................... 15—3
15.2.1 Entering Menu Setup Mode ........................................................................... 15—3
15.3
15.4
15.2.2 Adding Pull-down Menu Fields ....................................................................... 1 5 - 3
15.2.3 Leaving Menu Setup Mode ............................................................................. 1 5 - 4
Defining a Submenu ......................................................................................................... 15—4
Displaying and Using Menus ........................................................................................... 15—5
16 Defining Gadgets
16.1
16.2
16.3
Types of Gadget .................................................................................................................. 16—1
Gadget Tags or Pixmaps ................................................................................................... 16—1
Gadget Callback Strings ................................................................................................... 1 6 - 2
16.4
Positioning Gadgets Within Forms ................................................................................. 16—2
16.4.1 The Form Layout Grid ..................................................................................... 16—2
16.4.2 Positioning Gadgets Absolutely ....................................................................... 16—3
16.4.3
16.4.4
16.5
16.5
16.5.1
16.5.2
16.5.3
Specifying Relative Alignment of Gadgets ..................................................... 1 6 - 4
Positioning Gadgets on a Defined Path ......................................................... 16—6
Button Gadgets ..................................................................................................... 1 6 - 8
Defining Standard Buttons ............................................................................... 16—8
Defining Control Buttons ................................................................................. 1 6 - 9
Defining Dismiss Buttons for Retained Forms ............................................. 16—10
16.6
16.7
16.8
16.6 Text Entry Field Gadgets ....................................................................................... 16—10
Text Pane Gadgets ............................................................................................................. 16—12
Toggle Gadgets .................................................................................................................. 16—12
16.9
16.10
16.11
16.12
Radio Group Gadgets ....................................................................................................... 16—13
List Gadgets ....................................................................................................................... 16—14
Selector Gadgets ............................................................................................................... 16-15
Option Gadgets ................................................................................................................. 16-17
vi
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
16.13 Paragraph Gadgets ........................................................................................................... 16—18
16.14 Userdata Facilities ........................................................................................................... 16-19
16.15
View Gadgets ..................................................................................................................... 16-20
16.15.1
16.15.2
16.15.3
16.15.4
Creating View Gadgets ..................................................................................... 16-20
Cursor Types ..................................................................................................... 16—21
Defining Alpha Views ....................................................................................... 1 6 - 2 2
Defining Volume Views ................................................................................... 16—22
16.15.5 Defining Area Views ......................................................................................... 16—25
16.15.6 Defining Pixmap Views ..................................................................................... 16—26
16.15.7 Defining Plot Views ........................................................................................... 16—27
16.16 Editing View Gadget Attributes ..................................................................................... 16—28
16.16.1 Keyboard Focus ................................................................................................. 16-28
16.16.2 Gadget Status ..................................................................................................... 16-29
16.17 Updating Views and Selectors ......................................................................................... 16—29
17
Displaying and Using Forms
17.1
Initialising an Application ............................................................................................... 17—1
17.2
Controlling the Display of Forms ................................................................................... 17—1
17.2.1 Displaying Forms Explicitly ............................................................................. 17—2
17.2.2 Checking Form Validity ................................................................................... 17—2
17.3
17.4
17.2.3 Hiding Displayed Forms ................................................................................... 1 7 - 3
Deleting Forms ................................................................................................................. 17—3
Handling Data Using Form Variables ............................................................................. 17—3
17.4.1
17.4.2
17.4.3
17.5
17.6
Setting Values for Single-Valued Gadgets ....................................................... 17—4
Setting Values for List Gadgets ....................................................................... 17—4
Setting Values for Selector Gadgets ............................................................... 17—6
17.4.4 Setting Values for Userdata Facilities ............................................................. 17—6
17.4.5 Reading Data from List Gadget Values ......................................................... 17—8
Querying Form and Gadget Attributes ........................................................................... 17—8
Defining Alert Forms ....................................................................................................... 17—10
17.6.1 Defining an Error Alert ................................................................................... 17—10
17.6.2 Defining a Confirmation Alert ....................................................................... 17—11
17.6.3
Defining a Prompt Alert ................................................................................... 17—11
18
Hints for Successful User Interface Design
18.1
18.2
18.3
Before You Begin ............................................................................................................. 18—1
The Principles of Form Design ....................................................................................... 18—2
Choosing and Using Gadgets ........................................................................................... 18—3
18.3.1
18.3.2
Form Control Buttons ....................................................................................... 18—3
Push Buttons ..................................................................................................... 1 8 - 4
18.3.3
18.3.4
Text Entry Field Gadgets ................................................................................. 1 8 - 4
Toggle Gadgets ................................................................................................... 1 8 - 4
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
vii
18.3.5
18.3.6
18.3.7
One-of-Many Selection Gadgets ..................................................................... 1 8 - 5
Multiple Choice Lists ....................................................................................... 1 8 - 6
Paragraph Gadgets ........................................................................................... 18—6
19 Examples of Some Typical Applications Macros
19.1
19.2
19.3
Macro File Headings ....................................................................................................... 19—1
A Menu Bar, Pull-Down Menus and Submenus ........................................................... 1 9 - 2
A Database Members List (PDMS Only) ..................................................................... 1 9 - 5
19.4
19.5
A Form for Creating Graphical Views (PDMS Only) ................................................... 19—6
A Form for Modifying a Draw List ................................................................................. 19—7
20 Conventions in Customised Macros
20.1
20.2
Naming Conventions ....................................................................................................... 20—1
20.1.1 Macros ............................................................................................................... 20—2
20.1.2 Default Files ....................................................................................................... 20-3
20.1.3 Variables ............................................................................................................. 20-3
Some General Style Guides ............................................................................................. 20—4
20.2.1 Designing Pull-Down Menus and Submenus ................................................. 20-4
20.2.2
20.2.3
20.2.4
Designing Forms ............................................................................................... 20—4
Some Miscellaneous Rules for Designing Forms ........................................... 20—6
Some Miscellaneous Rules for Writing Macros ............................................. 20—6
21 Command Reference Section
21.1
21.2
21.3
How the Command Syntax is Represented ................................................................... 21 —1
Command Arguments ....................................................................................................... 21—3
Subsidiary Syntax Diagrams ............................................................................................. 21-3
21.3.1
21.3.2
21.3.3
21.4
<gid> General Element Identifier ............................................................... 21—3
<pml> Programmable Macro Language Commands ................................. 21-4
<uval> Value with Associated Unit of Measurement ................................. 21—4
<xypos> 2D Screen Position ........................................................................... 21-4
21.3.4
<fmpos> 2D Form Position (for Gadget positioning) ................................. 21-5
21.3.5
<vshap> Dimensions of a View ..................................................................... 21-7
21.3.6
The Commands ................................................................................................................. 21—8
ACTIONS (PDMS only) ................................................................................................. 21-9
ALPHA options ................................................................................................................. 21-10
AREA options (DRAFT only) ....................................................................................... 21 —11
BAR .................................................................................................................................... 21-13
BUTTON ............................................................................................................................ 21-14
CONFIRM .......................................................................................................................... 21-16
CURSORTYPE ................................................................................................................. 21-17
EDIT .................................................................................................................................. 21-18
ERROR .............................................................................................................................. 21-21
viii
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
EXIT .................................................................................................................................... 21-22
FMINFO ........................................................................................................................... 21-23
HALIGN ........................................................................................................................... 21-24
HDISTANCE ................................................................................................................... 21-25
HIDE .................................................................................................................................. 21-26
ICONTITLE ..................................................................................................................... 21-27
INITIALISE ..................................................................................................................... 21-28
KILL .................................................................................................................................... 21-29
LIST .................................................................................................................................... 21-30
MENU ................................................................................................................................ 21-31
OPTION ............................................................................................................................. 21-32
PARAGRAPH ................................................................................................................... 21-33
PATH .................................................................................................................................. 21-34
PIXMAP options ............................................................................................................... 21-35
PLOT options ................................................................................................................... 21—36
PROMPT ........................................................................................................................... 21-38
RADIOGROUP ............................................................................................................... 21-39
REFRESH ......................................................................................................................... 21-40
REVISION ....................................................................................................................... 21-41
SELECTOR ....................................................................................................................... 21-42
SETUP FORM ................................................................................................................. 21-44
SHOW ................................................................................................................................ 21-45
SWAP .................................................................................................................................. 21-46
TEXT .................................................................................................................................. 21-47
TEXTPANE ....................................................................................................................... 21-49
TITLE ................................................................................................................................ 21-50
TOGGLE ........................................................................................................................... 21-51
VALIGN ............................................................................................................................. 21-53
VARIABLE ....................................................................................................................... 21-54
VARIABLE LIST ............................................................................................................. 21-55
VARIABLE PICK ............................................................................................................. 21-57
VARIABLE SELECTOR ............................................................................................... 21-57
VARIABLE USERDATA ............................................................................................... 21-59
VDISTANCE ..................................................................................................................... 21-60
VIEW .................................................................................................................................. 21-61
VOLUME options (PDMS DESIGN only) ................................................................... 21-62
WAITON ........................................................................................................................... 21-6
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
ix
Part III
Using Query
22
Using QUERY to Communicate With Data Servers
22.1
22.2
Directing Commands to the Data Server ....................................................................... 22—1
Connecting CADCentre Query to a Data Server ......................................................... 22-2
22.3
22.4
22.5
Sending Commands to a Data Server ............................................................................. 22-3
Setting Variables from the Data Server Responses ....................................................... 22—4
Specifying the Data Field Delimiter ............................................................................... 22—6
22.6
22.7
22.8
Handling Returned Errors ............................................................................................... 22—7
Toggling Server Daemon Tracing Facilities ................................................................... 22—9
Command Arguments ....................................................................................................... 22—12
22.9
The Commands ................................................................................................................. 22—12
CLOSE ................................................................................................................................ 22-13
DELIMIT ........................................................................................................................... 22-14
END .................................................................................................................................... 22-15
EXTERNAL ..................................................................................................................... 22-16
GET .................................................................................................................................... 22-17
OPEN .................................................................................................................................. 22-18
SEND .................................................................................................................................. 22-19
START ................................................................................................................................ 22-20
TOGGLE ........................................................................................................................... 22-21
Part IV
Product Specific Information
Communicating with PEGS
A.l Directing Commands to PEGS ........................................................................................... A— 1
A.2 Setting Connections Between FmLayer and PEGS ......................................................... A— 1
A.3 Sending Commands to PEGS ............................................................................................. A— 2
A.4 Some Special Fmlayer Commands ..................................................................................... A— 4
A.5
Handling Errors Returned from PEGS ............................................................................. A— 4
A.6 A Sample Application ......................................................................................................... A— 5
B
Communicating With REVIEW
B. l Invoking the Command Line Interface ............................................................................. B—1
B.2 Directing Commands to REVIEW ................................................................................... B— 1
B.3 Sending Commands to REVIEW ....................................................................................... B— 2
B.4 Errors Resulting from the Application-to-REVIEW Link ............................................. B— 3
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
B.5 Sample Application .............................................................................................................. B— 3
B.5.1
Progress Monitoring ......................................................................................... B— 4
B.5.1.1 Engineering Data ............................................................................................. B— 4
B.5.1.2 Maintenance ..................................................................................................... B— 4
B.6
Using the Sample Application ........................................................................................... B— 5
B.6.1
Start— Up ........................................................................................................... B— 5
B.6.1.1
B.6.1.2
Progress Monitoring........................................................................................... B— 6
Engineering Data ............................................................................................. B— 6
B.6.1.3
Maintenance ..................................................................................................... B— 8
B.7 A Summary of the Application Data ..................................................................... B— 12
B.7.1
Progress Monitoring ......................................................................................... B— 12
B.7.1.1 Engineering Data ............................................................................................. B— 12
B.7.1.2 Maintenance ..................................................................................................... B— 13
B.8 The Application Files Supplied ............................................................................. B— 14
B.8.1
The ADMIN Directory ..................................................................................... B-15
B.8.1.1 The ENGDATA Directory ............................................................................... B-15
B.8.1.2 The PROGRESS Directory ............................................................................. B-15
B.8.1.3
B.8.1.4
The MAINTAIN Directory ............................................................................. B-15
The DATA Directory ....................................................................................... B— 16
Index
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
xi
Part I
Macros and Programmable Macros
1
Introduction
Most CADCENTRE products make use of a Graphical User Interface (GUI) to drive the
software. The interfaces provided with your CADCENTRE software are designed to apply to a
wide range of situations and business needs. However, as you become more experienced with
CADCENTRE products you may wish to design an interface which is more closely related to your
requirements.
The GUI consists of menus, which you can select from, and forms, which you can fill in. When a
form is actioned, one or more macros (command sequences) are run which translates the
information on the form into a series of text commands which are sent to the CADCENTRE
command processor.
Part I of this manual describes the CADCENTRE Command Processor. It tels you how to record
command sequences, and describes how to use variables, expressions and macros. Part II, User
Interface Customisation, describes how to customise a GUI.
Before you begin, you must have a good working knowledge of the command syntax for the product
you are working with. The commands are described in detail in the reference guides for the
products. You should study these guides carefully before attempting to use the command
processor directly.
1.1
Basic Principles
There are a number of ways you can customise your software to improve your work. In increasing
order of complexity these are:
•
Create synonyms, macros and batch files to store often repeated commands, and then input
them automatically when required.
•
Create intelligent macros (using the CADCENTRE Programmable Macro Language or
PML) using conditional statements and do loops.
•
Use macros to create a new user interface (with forms, menus, gadgets and the like) that
precisely matches your requirements.
•
If you have bought the CADCENTRE product Query, you can use a combination of the above
to access and interrogate external (non-CADCENTRE) databases.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
1 —1
Introduction
1.2
How to Use This Manual
The contents of this manual follow the structure:.
•
Part I : Macros and Programmable Macros. This part contains all the information you need
to create synonyms, macros and programmable macros. If you do not wish to customise your
Interface, or you have not bought the Query product, you may not need to read any of the
other chapters.
•
Part II : User Interface Customisation. Part II contains all the information you need to create
your own interface of forms and menus. Before using this section you must have an extensive
knowledge of the application you wish to customise, and of how macros and programmable
macros work. Because of this, you should have already studied Part I before attempting to
read these chapters.
•
Part III : Using QUERY to Communicate With Data Servers. Part III is only relevant if you
have purchased the CADCENTRE Query product, which allows you to communicate with
other databases.
•
Part IV : Reference Appendices. These appendices contain information that is specific to
certain CADCENTRE products. Most of this information will be of most use to Query users.
However, we advise that you examine the appendices relevant to your products to see if they
hold anything of interest to you.
1.3
A Serious Warning Concerning Software Customisation
The ability to customise individual Applications to suit your own specific needs gives you great
flexibility in the ways in which you use your system. But it also introduces the risk that your
modified macros may not be compatible with future versions of of the software, since they are no
longer under CADCENTRE’s control. Your own Applications may diverge from future standard
versions and may not take advantage of product enhancements incorporated into the standard
product. To minimise this risk, it is most important that your in-house customisation policies
constrain any changes which you make to the Applications so that they retain maximum
compatibility with the standard product at all times. Remember that CADCENTRE Ltd can give
you full technical support only for products over which it has control. It can not guarantee to solve
problems caused by software which you have written yourself.
1—2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Introduction
1.4
Minimising Problems for Future Upgrades
When future versions are released, the product documentation will identify which macro files and
which parts of the directory hierarchy have been modified. You must then decide on one of three
courses of action for dealing with any customised macros which you may have been using:
•
Run your existing macros, thereby ignoring any enhanced features which may have been
incorporated into the standard versions.
•
Revert to using standard macros instead of your customised versions.
•
Update your customised macros to take advantage of any enhanced features now available.
In order to minimise any problems resulting from the latter choice, you should adopt the following
key principles as part of your customisation policy:
•
The directory which holds the macro files associated with your Applications is divided into
two main areas: a standard product area and a user area. You should make changes only in
the User area using only copies of the standard Application macros. You should never modify
the original files, so that you can always revert to using these if things go wrong.
•
When writing your own Application macros, follow the styles and conventions used in the
standard macros.
•
Ensure that the names of any new forms which you create can not conflict with the names of
any standard forms which may be used in the CADCENTRE Applications.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
1-3
2
The Command Processor
When an application with a GUI is running, you can type commands into the command
input/output window, which can be displayed from the main menu bar. You may type in any
command sequence which applies to your software, as described in the relevant Reference Guide.
Each part of the command line may be one of two types:
•
A command word
This is the actual process you wish to be carried out.
•
A command argument
This gives more details on how the command should be
carried out. For example, what filename to use, what
position to begin at, what length something is, and so on.
These terms are sometimes jointly referred to as command atoms.
everything which you have entered since the command prompt will be passed to the Command
Processor. This analyses your instructions and tries to convert them into a form which the software
can obey.
When you press RETURN, each command line will be checked in turn by the Command Processor
to see if it conforms to the command syntax. The command syntax comprises a rigid set of rules
defining what sort of input is expected at that point in the command line.
If the command atoms are all recognised by the Command Processor and occur in an expected
order, the meaning of the command line will be passed to the data-handling parts of the system and
the command will be acted upon.
There are several methods of entering commands as well as typing them in directly. These
alternative techniques are all designed to speed up the input of long sequences of commands by
avoiding unnecessary repetition. They mostly do this by storing such sequences, in various ways,
the first time you enter them. You may then re-enter the same sequence at a later time simply by a
reference to the stored information. The techniques differ only in the way in which the information
is stored and accessed.
The techniques available are described below in order of increasing complexity. They include the
following:
•
Recording Command Input — You can record the commands you enter into the command
line. This gives you an easy method of capturing long command sequences for conversion into
synonyms, or for incorporating into macros. For more information about macros, see Section
3.2.
CADCENTRE Software Customisation
I Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
2 —1
Synonyms — Character sequences which occur repeatedly in command inputs may be
allocated short identifiers known as synonyms. You may then use the synonym in a command
line wherever the corresponding sequence is to be input. For further details, see Section 3.3.
•
Variables — You can use variables in command lines. Global variables retain their settings
throughout a working session; the settings of local variables are applicable only within a
restricted context (usually within an individual macro). For further details, see Chapter 4.
•
Expressions — You can use expressions in command lines. An expression is a calculation
which will provide a unique result when calculated. Expressions can be mathematical, textual
or logical, depending on their type of output. When a command line containing an expression
is acted upon, the command processor first evaluates the expression and then replaces the
entire expression by its result. For more information, see Chapter 5.
•
Macros — These are command sequences which are stored as text file To access a macro file
and input the command sequence to your program, you run the macro which has exactly the
same effect as if you were typing the lines in from a keyboard. Macro files may include
references to other fast input techniques, such as synonyms and user-defined variables. For
further details, see Chapter 6.
Macros may also incorporate decision-making logic, based upon the Programmable Macro
Language (PML). For details of this facility, see Chapter 7.
Macros are particularly important when designing your own, customised GUI for your system
(see below).
•
Menus and Forms — The forms and menus of a GUI are a way of inputting commands to the
command processor. Most menu and form actions will run a macro which sends commands to
the command processor. For further details of designing forms and menus, see Chapters 11
to 19.
2.1
The Escape Character and Escape Codes
Several command inputs are preceded by a special character which alerts the command processor
to the fact that the specification which follows conforms to its own built-in code. This character,
which is known as the Escape character, is defined as the dollar ($) symbol.
Escape codes, that is command codes prefixed by the Escape character, are defined within the
command processor itself. They are directly accessible from within any part of a program.
Details of the use of specific Escape codes will be found in appropriate sections of this guide. The
main areas in which such information will be found are as follows:
2 —2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
$R
$S
$G
$H
$V
$! or $!!
$M
$P
$W
$Q
For recording command line input. See Section 3.2
For standard synonym instructions; see Section 3.3
For global synonym instructions; see Section 3.4
For on-line help about recording See Section 3.2
For recalling user-definable numbered variables; see Section 4.3
For recalling user-definable named variables; see Section 4.3
For entering macro instructions (i.e. running macros); see Chapter 6
For the display of prompting messages; see Section 6.4.5
For specifying the maximum numbers of characters on a line. See Section 6.4.7
For finding what commands are available. See below.
NOTE: The Escape character must not be confused with the ESCAPE key which is present on
most keyboards.
2.2
Finding what Commands are Available ($Q)
When you are typing commands into a macro or into a command line, you may not remember
exactly what arguments are available or what other commands are related. You will find full details
in the appropriate Reference Manuals to the module, but you can also ask the Command
Processor what sort of command(s) it is expecting next by typing:
$Q
This will produce a list of every valid command word or argument type that you may enter next.
The list may be long, and it may be necessary to scroll your display backwards (if your terminal
allows this) in order to read it all. If you give the $Q command immediately after the command
prompt, you will generate a list of every valid command for the module that you are in.
By default, the displayed list is tabulated into columns such that each command or argument is
allocated a width of 15 characters in a maximum line length of 79 characters (giving 5 items per
line). To change this format, use the command:
$QFm/n
where m defines the column width and n defines the line length. For example
$QF10/70
will cause subsequent $Q requests to list the commands and arguments in columns 10 characters
wide, with 7 items on each line.
You may limit the number of commands listed if you do not wish to see all of them, or for modules
which do not page, by specifying the range required. For example:
$Q 1–22
$Q 23–45
etc.
will list one screenfull at a time on most terminals. You will often find what you want in the first 20
or so options.
CADCENTRE Software Customisation
I Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
2 —3
To interrupt the output of a very long list, press CTRL— C.
The $Q facility is particularly useful when you think you have entered a valid command sequence
but have received a Syntax Error message in response. The program will redisplay the valid part of
your command sequence followed by the characters
. You can then type:
$Q
to see what should be entered next. For example, if you want to use the SYSCOMMAND option to
list an OS directory, but you forgot to enclose the system command between quotes. The
interactive sequence might be as follows:
You type
The computer responds with
Meaning
**SYNTAX ERROR** <CP3A12>
Error message from Command
Processor
Indication of error location
Redisplay of correct part of command
SYSCOM Is
SYSCOM ^^ls
SYSCOM
$Q
TEXT
SYSCOM
Only a text argument is valid
Redisplay of correct part of command
A listing of your current directory
’ls’
2—4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
3
Recording and Saving Command Line
Inputs ($R and Synonyms)
3.1
Introduction
Whenever you enter commands into a command line, you can choose to record the commands you
enter. The system will then memorise your commands until you tell it to stop. This facility is a
useful tool for creating synonyms (see below) and macros (see Section 6). It is also a useful tool for
tracking down errors.
Synonyms represent the simplest way of speeding up your command line input. If you find that you
are often typing in the same commands, you can replace those commands with synonyms. A
synonym is a short code which can be used to replace inputting commands. Once you have created
the synonym, all you need to do enter its short code to activate the commands it represents.
Detailed descriptions of recording input and synonyms are given in the sections that follow.
3.2
Recording Command Input/Output
3.2.1
The General Principles
There are two different types of record which you can make of your command line activities:
•
A log of your input commands only. This can be used to create a synonym or macro file while
testing the effects of the command sequence at the same time.
•
A log of your input commands and of the responses generated by the software. This creates a
complete record of all inputs and outputs in an interactive session. Such a record is
particularly useful when you, or your support team, are trying to diagnose the cause of an
unexpected result or an error.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
3-1
3.2.2
Recording Command Inputs Only
Input from any source (keyboard, macro file etc.) can be recorded using the command:
$R number filename
where number is an odd number which specifies the option to be used and filename is the name of
the file to which the logged data is to be sent.
An alternative form of the command
$R number
where number is even, causes the selected input to be echoed to your screen.
filename is only applicable when number is odd.
NOTE:
To calculate the option definition number, add together the following component parts:
add 1
add 2
add 4
add 8
add 16
Copy input commands to file (useful for creating synonyms and
macros)
Echo input commands to terminal (useful if running a macro. See
Section 6.3).
Record inputs from file (macros) only (‘indirect input’ in examples)
Record inputs from keyboard only (‘direct input’ in examples)
Expand synonyms and macro parameters before recording inputs
(useful when running synonyms and macros)
The effects of combining these options are best shown by example:
Number
Effect
6
(2+4)
9
(1 + 8)
Displays the commands in a macro on the terminal line-by-line during
execution of the macro
Copies direct input to file. Any synonyms are recorded as their
entered codes (not the commands they represent)
Copies direct input to file. Any synonyms are expanded first
Copies direct and indirect input to file and echoes all input to
terminal. Synonyms and macro parameters are expanded first
25 (1 + 8+16)
31 ( 1 + 2 + 4 + 8 + 1 6 )
►
To see an on-line summary of the way of calculating number, enter
$HR
►
To find out the current recording status, enter
$QR
You may specify up to three levels of recording in action at the same time by giving $R commands at
different levels (known as nesting). For example, the following sequence of commands:
3-2
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
$R6
$R13 /IPLOG1
$R29 /IPLOG2
1st level
2nd level
3rd level
sets up the following recording levels simultaneously:
Level 1 — All macro input echoed to terminal
Level 2 — All macro and keyboard/tablet input recorded in file /IPLOG1 without expansion of
synonyms and macro parameters
Level 3 — All macro and keyboard/tablet input also recorded in file /IPLOG2, but after expansion
of synonyms and macro parameters
NOTE: Each level operates in addition to any lower levels.
►
To suspend the most recent level, enter
$R-
►
To reinstate a suspended level, enter
$R +
►
To cancel the highest current level completely (until it is redefined), enter
$R
The effects of these options are illustrated in the following sequence:
$R6
$R13 /IPLOG1
$R29 /IPLOG2
$R
$R–
$R+
$R15 /IPLOG3
$R
$R
$R
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Switch on level 1 recording
Switch on level 2 recording
Switch on level 3 recording
Cancel level 3 recording
Temporarily suspend level 2 recording
Restart level 2 recording with the same definition as before
Switch on newly-defined level 3 recording
Cancel level 3 recording
Cancel level 2 recording
Cancel level 1 recording
CADCENTRE
Protected by copyright: see frontispiece
3-3
3.2.3
Recording Command Inputs and Resulting Outputs
You can copy all input and output strings from your alpha terminal to a named log file in the host
computer’s OS. To create and/or open such a file, use one of the command formats
ALPha LOG filename
ALPha LOG filename OVERwrite
ALPha LOG filename APPend
where filename is the pathname of the log file in the OS directory.
If the file specified by filename already exists, APPEND causes the new data to be added to the end
of the file’s existing contents, while OVERWRITE causes the new data to overwrite the existing
contents.
To close a log file, use the command
ALPha LOG END
NOTE: See also the ALPHA FILE command described in Chapter 21. The difference is that
ALPHA FILE saves the alphanumeric outputs only, but ALPHA LOG saves both inputs and
outputs in the same file.
3.3
Standard Synonyms
Each synonym represents, by a short name, all or part of a command string. Its use enables any
repeated command string to be entered in full only once and then to be re-entered when required
by means of a short code.
All standard synonym handling commands incorporate the $S escape code.
3.3.1
►
Defining and Recalling Synonyms
To define a synonym, use the $S command format
$S synjiame = repjext
where :
The synonym name, synjiame, defines the short form for future input. This name consists of
all the characters between the $S and the = sign. It must contain letters only.
The replacement text, repjext, defines the full command sequence which the synonym
represents. This text consists of all characters between the = sign and the Return which ends
the definition. It may contain any legal command syntax (command words and/or arguments),
including instructions to run macros (see Chapter 4).
3-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
► To use the synonym, enter its name, synjiame, at the appropriate point in your command
input. The result will be exactly the same as if you had entered the full text, repjext, at that point.
As an example, suppose you wish to draw a number of squares, each of side 10 units, at specified
centres — say at (100,100), (200,100), (100,200), and so on.
Assume that the command sequence to do this is as follows:
MOVE TO X100 Y100
MOVE BY X–5 Y–5
LINE BY X10 BY Y10 BY X–10 BY Y–10
MOVE BY X5 Y5
Move pen to centre of first square
Move pen to bottom left-hand corner of
square
Draw four sides of square (clockwise)
Move pen back to centre
MOVE TO X200 Y100
MOVE BY X–5 Y–5
LINE BY X10 BY Y10 BY X–10 BY Y–10
MOVE BY X5 Y5
Move pen to centre of second square
as before
as before
as before
MOVE TO X100 Y200
MOVE BY X–5 Y–5
...
Move pen to centre of third square
as before
and so on.
This command sequence is highly repetitive (even though it could be shortened by abbreviating the
command words). In particular, the command lines
MOVE BY X–5 Y–5
LINE BY X10 BY Y10 BY X–10 BY Y–10
MOVE BY X5 Y5
Move to corner of square
Draw square
Move to centre of square
are repeated for each square.
To define synonyms to simplify this input, you might type:
$S CORN = MOVE BY X–5 Y–5
$S SQUA = LINE BY X10 BY Y10 BY X–10 BY Y–10
$S CENT = MOVE BY X5 Y5
where the chosen synonym names are CORN, SQUA and CENT.
The command sequence to draw the same squares then reduces to
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
3-5
MOVE TO X100 Y100
CORN
SQUA
CENT
MOVE TO X200 Y100
CORN
SQUA
CENT
etc.
3.3.2
Nested Synonyms
Synonym definitions may include the names of other synonyms within their replacement text.
These are known as nested synonyms. Thus the basic pen moving and line drawing commands in
the example of Section NO TAG could be defined by the synonyms
$S MB = MOVE BY
$S LB = LINE BY
and the definitions of CORN, SQUA and CENT could then be specified by
$S CORN = MB X–5 Y–5
$S SQUA = LB X10 BY Y10 BY X–10 BY Y–10
$S CENT = MB X5 Y5
Synonyms may be nested up to a maximum of 10 deep.
NOTE: Synonym definitions may also include commands to run macros; see Chapter 6.
3.3.3
New Lines in Synonym Definitions
Since the replacement text is ended by pressing Return, multiple command lines cannot be
specified in synonym definitions in this way.
►
To specify a new command line, insert the characters
$/
For example, the three synonym definitions CORN, SQUA and CENT, given in Section NO TAG,
could be replaced by a single synonym, thus:
$S BOXDRAW = MB X–5 Y–5 $/ LB X10 B Y10 B X–10 B Y–10 $/ MB X5 Y5
3-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
3.3.4
Arguments in Synonyms
Arguments may be included in synonyms, enabling data or command words to be entered within
the expanded command sequence when the synonym is used.
When you define a synonym, denote any arguments by the characters
$Sn
where n is a digit (1 to 9 inclusive).
For example, the following synonym might be used to set the dimensions of a BOX:
$S DBOX = XLEN $S1 YLEN $S2 ZLEN $S3
where the arguments $S1, $S2 and $S3 (representing the X, Y and Z dimensions, respectively) will
be given specific values when the synonym name is used in a subsequent command.
Then the command
NEW BOX DBOX 100 500 300
would create a new BOX with the dimensions 100 x 500 x 300 (in the current units).
The digits used to identify the arguments in a synonym definition may be specified in any order.
Note, however, that when you use the synonym you must supply at least as many arguments as the
highest-numbered argument in the definition.
For example:
$S DBOX = XLEN $S6 YLEN $S1 ZLEN $S4
DBOX 200 0 10 300 11000 100
corresponds to the command sequence
XLEN 100 YLEN 200 ZLEN 300
► To allocate default values to synonym arguments, specify the values immediately after the
synonym name. Each value must be followed by a space.
For example, the definition
$S DBOX 100 200 300 = XLEN $S1 YLEN $S2 ZLEN $S3
followed by the use of this synonym without any arguments, thus
DBOX
would produce the sequence
XLEN 100 YLEN 200 ZLEN 300
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
3-7
► To include embedded spaces in a synonym argument, enclose the argument between the
characters
$< $>
when its content (probably text) is specified.
For example, the following synonym definition might be used to simplify the creation of a number
of Equipment elements. It includes arguments representing the name of the element and its
Function attribute (a text string describing the use of the Equipment). You must specify these each
time the synonym is used.
$S EQDEF = EQUIP $S1 FUNC $S2 ORI Y IS N AND Z IS U
Then, in an appropriate program, the command
NEW EQDEF /VESS–1 <CHEMSOL 26 Feed Tank>
would create a new Equipment element named /VESS— 1, orientated as predefined, and with the
descriptive text ‘CHEMSOL 26 Feed Tank’ in its Function attribute.
3.3.5
Examining, Redefining or Deleting Synonyms
To list all currently defined synonyms in your synonym library, enter
$QS
The synonyms will be output in the format in which they were defined, but note that all nested
synonyms will be replaced by their fully expanded definitions in the listing.
► To redefine a synonym, enter the new definition as if the synonym did not currently exist. The
old definition will be deleted and replaced by the new one.
► To delete a synonym from the library, redefine it as nothing. For example, to delete the
definition of the synonym EQDEF, enter
$S EQDEF =
►
To delete all currently defined synonyms, enter
$SK
►
To prevent deletion of a synonym which has already been defined, enter
$U synjiame
where synjiame identifies the synonym which is to be protected, or combine this with the
original definition thus
$SU synjiame = repjext
3-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
This facility is particularly useful if you are writing application macros (which include
synonyms) for use by others, since the use of $SK could have disastrous consequences for the
macro execution.
You can only delete a synonym which has been protected by the $U option by explicitly
redefining it as nothing; that is, by using
$S synjiame =
Synonyms protected by $U are identified in a $QS output list by a U at the beginning of the
output line.
►
To mark a defined synonym so that it is expanded only when it occurs at the beginning of a line,
enter
$O synjiame
where synjiame identifies the synonym which is to be marked in this way, or combine this with
the original definition thus
$SO synjiame — repJext
This facility can speed up processing, since a word is then checked against the synonym library
only if it occurs at the beginning of a command line.
Synonyms marked by $0 are identified in a $QS output list by an O at the beginning of the
output line.
NOTE: A synonym may be both protected against accidental deletion and marked as valid only at
the beginning of a line. In this case the synonym will be identified by both U and O at the
beginning of the $QS output.
3.3.6
Disabling Synonym Translation
When synonym translation is in force, every atom in a command line is checked against the current
synonym library to see if it needs to be expanded to a replacement text before the command line is
actioned. If you know that the command input will not contain any synonyms, you can disable
synonym translation and so speed up the processing. Enter:
$SSynonym translation will remain disabled for the rest of your current session unless you reinstate it
by entering
$S+
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
3-9
3.3.7
Restrictions on Synonym Use
Synonym definitions apply only during your current working session.
There is room in the synonym library for approximately 10000 characters in total. The maximum
number of individual synonym definitions therefore depends on the sums of the lengths of the
replacement texts and of the synonym names chosen. (The synonym names are not usually a
limiting factor since, if they are not short, the objective of using synonyms is partially defeated.)
A synonym name must form a whole number of individual command atoms in a command line.
Synonym names cannot, therefore, form parts of filenames or text strings; they can, however,
comprise or include complete filenames or text strings.
Since synonyms operate by a text replacement mechanism, you must be careful that a command
line containing synonyms (particularly nested ones) does not exceed the input buffer limit of 120
characters when expanded.
You must avoid recursion when defining a synonym; that is, the name of the synonym must not be
used within the definition of its replacement text. For example, if you define the following
synonym:
$S Q = Q MEMBERS
the command
will try to expand to the line
Q MEMBERS MEMBERS MEMBERS MEMBERS ... MEMBERS
which would be of infinite length since each initial
3.4
►
expands to Q MEMBERS
Global Synonyms
To define a global synonym, use the $G command format
$G synjiame = repjext
where the definition comprises the following two parts:
•
The synonym name, synjiame, which defines the short form for future input. This name
comprises all characters between the $G and the = sign. It may contain any alphanumeric
characters.
•
The replacement text, repjext, defines the full command sequence which the synonym
represents. This text comprises all characters between the = sign and the Return which ends
the definition. It may contain any legal command syntax (command words and/or arguments).
Global synonyms may be used to overcome two of the limitations of standard synonyms:
•
They may be incorporated at any point within a command line, not necessarily as separate
command atoms. Thus, they may be incorporated into filenames or text strings of which they
form only a part.
3-10
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
•
Their names may include non-alphabetic characters.
► To use global synonyms, follow the same principle as for standard synonyms (as explained in
Section 15.1.1) but enclose the synonym names between the escape codes
$:
$:
in order for the command processor to recognise them. It is this use of delimiters which enables
them to be embedded within command atoms.
For example, a global synonym representing the commands to specify your input and output
devices might be defined by
$G SET2015 = DEV W2015 WI ANSI AND TAB GTA
To use the synonym in any future command line, specify its name in the form
$:SET2015$:
The following querying and editing facilities for global synonyms are much like those described for
standard synonyms in Section 3.3.
►
To list all currently defined global synonyms, enter
$QG
► To redefine a global synonym, enter the new definition and the old definition will be
overwritten.
► To delete a global synonym from the library, redefine it as nothing. For example, to delete the
definition of SET2015, type
$G SET2015 =
►
To delete all currently defined global synonyms, enter
$GK
►
To prevent deletion of a global synonym which has already been defined, enter
$U synjiame
where synjiame identifies the global synonym which is to be protected, or combine this with
the original definition thus
$GU synjiame = repjext
This facility is particularly useful if you are writing application macros (which include global
synonyms) for use by others, since the use of $GK could have disastrous consequences for the
macro execution.
You can only delete a global synonym which has been protected by the $U option by explicitly
redefining it as nothing; that is, by using
$G synjiame =
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
3-11
Global synonyms protected by $U are identified in a $QG output list by a U at the beginning of
the output line.
►
To mark a defined global synonym so that it is expanded only when it occurs at the beginning of
a line, enter
$ 0 synjiame
where synjiame identifies the global synonym which is to be marked in this way, or combine
this with the original definition thus.
$G0 synjiame = repjext
This facility can speed up processing, since a word is then checked against the global synonym
library only if it occurs at the beginning of a command line.
Synonyms marked by $0 are identified in a $QG output list by an O at the beginning of the
output line.
NOTE: A global synonym may be both protected against accidental deletion and marked as valid
only at the beginning of a line. In this case the synonym will be identified by both U and O
at the beginning of the $QG output.
3-12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
4
User-Definable Variables
This Chapter describes how to use PML variables. The The VARiable command is used to manage
variables, but for basic tasks such as setting varibles, the VAR command can be omitted.
4.1
Local and Global Variables
PML variables can be local or global.
4.1.1 Global Variables
•
A global variable retains its settings throughout a working session (unless you reset it). Global
variables are identified by names of the format:
! [name
or
Ninteger
which defines a named global variable,
which defines a numbered global variable
The characters following the exclamation marks may be any combination of the characters A— Z
and 0—9 and can include full stops (.) , up to a maximum of 16 characters. The names are
case-independent. For example, !fred and !FRED are the same variable.
The number used in an identifier for a numbered variable must be an integer in the range 1 —119.
As you will see from the following section, when you set a numbered variable you identify it by its
number alone. When you recall the content of the variable you prefix the number with the letter V.
NOTE: Numbered variables have exactly the same properties as global named variables except
for their identifiers. The V prefix in the identifier is used only when the variable is used,
not when the variable is set.
4.1.2 Local Variables
A local variable is accessible only within the part of the command sequence where it is set (usually
in a macro). If the setting of a variable is derived from the content of a database, it retains the value
which applied when set, regardless of future modifications to that database. Local variables are
identified by names of the format:
\name
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-1
The characters following the exclamation mark may be any combination of the characters A— Z
and 0—9 and can include full stops (.) , up to a maximum of 16 characters. The names are
case-independent. For example, !fred and !FRED are the same variable.
A named variable can hold a single value or it can contain several values, in which case it is known
as an array variable. See Section 4.2, Setting Variables for more information.
4.2
Setting Variables
To set a named variable, give one of the commands:
[name =definition
Wname =definition
number =definition
Where definition can be any of the following:
•
•
•
•
A text string
A mathematical, logical or text expression
The name of an attribute or other part of a database. The setting of the attribute will be the
value of the variable
A command to read the next input string.
The maximum length of data that can be stored in a variable is 119 characters.
You can also use the VARiable command to set variables:
VAR [name =definition
VAR Wname =definition
VAR number =definition
Variables can be set to single values or to arrays of several values. For more information about
array variables, see Section 4.7.
4.2.1
Setting Variables to Text Strings
NOTE: The examples given in the following subsections show, in most cases, the setting of local
named user-definable variables only. Global variables are set in the same ways.
A variable can be set to any text. The text must be enclosed in single quotes (’text’) or vertical bars
( | text | ). The vertical bars are useful if the text includes an single quote character, such as a closing
quotation mark or a foot length symbol. For example:
!MAXH = | Maximum Height 6’9” |
4-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
sets the contents of the variable !MAXH to the text string specified. This string will then be
substituted wherever the identifier $!MAXH occurs in a command line.
4.2.2 Setting Variables to Expressions
A variable may be set to the result of any expression. These expressions may themselves include
predefined variables. For example, the sequence
!SUM = ( 7.2 + $V7)
!ANG=( ATANT($!SUM, $V13) )
first sets named variable !SUM to the sum of 7.2 and the current setting of numbered variable V7.
It then sets named variable !ANG to the angle whose tangent is the ratio !SUM/V13.
4.2.3 Setting Variables to Database Values
A variable may be defined as the setting of any part of a database which is accessible for reading in
the current module; that is, any part which can be queried by using the Query command.
Attribute data may be extracted from any element by accessing that element and setting the chosen
variable to the required attribute’s name:
!name = attributename
sets the local variable !name to the value of the attributename attribute of the Current Element.
NOTE: This setting of !name will be retained, even if you subsequently change the value of the
attributename attribute, unless you reissue the variable setting command. For example:
NEXT
!TYP.2=TYPE
which sets !TYP2 to the TYPE of the next element.
You can set a variable to the value of a coordinate on a specified axis (E, N, U etc.). For example, if
the origin of the current element is at N1000 E2000, the command
!EAST=E
sets !EAST to 2000; that is, it sets the value but not the direction letter. The variable may therefore
be specified directly as a value in a calculation.
4.2.4
Setting Variables to Following Input.
A variable may be set to whatever input string, terminated by a Return, follows the VARIABLE
command.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-3
If you are going to enter the definition from a keyboard or if it is to be input using a macro, use one
of the command formats:
VAR \name READ
VAR Wname READ
VAR number READ
All input which follows the command, up to the next Return, will be used as the setting of the
variable.
For example, the input sequence
VAR 9 READ
263.6
sets numbered variable V9 to the value 263.6.
NOTE: When using the VAR ... READ command in an interactive macro, the $P or WRITE
options (see Section 6.4.5) are useful to output a prompt that a particular type of input is
awaited or to confirm the data entered.
4.2.5
Defining Variables as Date and Time
You can set a variable to the current date and/or time using the syntax:
VAR \name CLOCK
VAR \name CLOCK TIME
VAR number CLOCK DATE
Sets \name to the current date and time.
Sets \name to the current time.
Sets \name to the current date.
So, the command:
VAR !TIME CLOCK
Would set the variable !TIME to the current date and time.
4.3
Using Variables
To use a variable, prefix the variable’s identifier with the $ character. Numbered variables must
also have their number prefixed with V:
$!name
$!!name
$Vnumber
NOTE: If the variable has never been given a value, or if it has been deleted, an error will occur
when you try to use it. Otherwise, the value of the variable will be substituted before the
command is processed.
4-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
4.4
Querying Variables
4.4.1
Querying the Current Settings of Variables
To query the settings of one or more specific variables, enter
Query VAR varjd( s)
where varjd(s) are the identifiers of the variables.
For example
Q VAR !!PIPE1.BORE
Q VAR 3 7
(returns the settings of V3 and V7)
To query the settings of all local named variables (either within a macro or at command level),
enter
Query VAR LOCal
To query the settings of all global named variables (either within a macro or at command level),
enter
Query VAR GLObal
To query the settings of all numbered variables, enter
Query VAR
4.4.2
Querying if a Named Variable is Set
Although you cannot query directly whether or not a given named variable has a current setting,
you can incorporate the result of such a query into an expression (see Chapter 5). To do so, use the
syntax
(DEFined ( varjd ))
where varjd is the identifier of a named variable. For example
VAR !QDEF (DEFINED(!variable))
sets !QDEF to 1.0 (True) if [variable has been set or to 0.0 (False) if [variable remains unset.
You may also use a converse expression to confirm that a variable is not set. This has the syntax
(UNDEFined ( v a r j d ) )
such that (UNDEFINED(!variable)) is equivalent to (NOT DEFINED(!variable)).
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-5
The result of this expression is 0.0 (False) if !variable has been set or 1.0 (True) if !variable remains
unset.
NOTE: The DEFINED/UNDEFINED operators may be used only with named variables, not with
numbered variables.
4.5
Defining Variables for Late Evaluation
Generally, variable definitions are expanded by the system’s command processor (see Chapter 2)
before being passed on to the application. This means that the command processor actually sets
the value for a variable.
For example:
SET COLOUR $!COLOUR
would be expanded by the command processor to be (for example)
SET COLOUR RED
before the line was passed on to the application.
In most cases this situation is fine. However, this can cause problems if the variable contains
characters that the command processor would normally act upon (for example, dollar sign $,
quotes ’ and lines | ). In this case, you want the application to expand the variable definition and not
the command processor.
To use late evaluation of variables, you use the functions:
WALue < variablename >
VTEXt < variablename >
VLOGical < variablename >
For example:
VAR !APOS (MATCH(|$!TEXT|, |’|)
would be fine, unless !TEXT contained | characters. If it did, the command processor would think
the character had to be acted upon, and this would cause problems.
In this case, the line:
VAR !APOS (MATCH(VTEXT(!TEXT), |’|)
would cause the line to be ignored by the command processor, and expanded by the application
itself, thereby ignoring the problem.
4.6
Cancelling or Deleting Variables
The settings of variables may be removed in one of two ways:
•
•
4-6
By deleting the variable identifiers
By retaining the allocated identifiers for the variables, but setting them to have blank contents
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
If a variable recalled in a macro has a blank setting, your program will substitute a single space in the
command line at that point and, assuming that this conforms with the local command syntax, will
continue to run normally (perhaps using a default setting for the omitted data).
NOTE: If you attempt to use a variable after it has been deleted, or if you try to use a variable that
has never been created, the system will generate an error.
►
To delete one or more specific variables, enter
VAR var_id(s) DELETE
where var_id(s) are the identifiers of the variables.
For example
VAR !!PIPE1.BORE DELETE
VAR 3 7 DELETE
►
(deletes V3 and V7)
To delete all numbered variables, enter
VAR ALL DELETE
►
To set to blank one or more specific variables, enter
VAR var_id(s) BLANK
where var_id(s) are the identifiers of the variables.
For example
VAR !!PIPE1.BORE BLANK
VAR 3 7 BLANK
►
(gives V3 and V7 blank settings)
To set to blank all numbered variables, enter
VAR ALL BLANK
4.7
Array Variables
A named variable can hold a single value or it can contain several values, in which case it is known
as an array variable. The elements of array variables are identified by an index (also known as a
subscript), enclosed in square brackets. Note that there must be no space between the end of the
array name and the start of the array index:
!name[index]
Array variables are created by setting each element in turn. For example, to define a real array
variable named !ARRAY with three elements set to 100, 200 and 300 respectively:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4—7
!ARRAY[1] = 100
!ARRAY[2] = 200
!ARRAY[3] = 300
An array variable may be either local or global in scope and may be given any identifier which is
valid for a simple named variable; for example !ARRAY (local) or !!ARRAY (global).
The index can be any of the following types:
•
An integer, which may be positive, zero or negative; for example, !LENGTH[1]. There is no
limit on the size of the index integer.
•
A reference to a variable, whose current setting determines the index value. For example,
!LENGTH[$!X]. The variable used to define the index must have a numeric value. If this value
in not an integer, the nearest integer will be used to set the index. Note also that the indexing
variable may not be another array variable or an element of an array variable.
•
An expression, whose result determines the index value. For example, !LENGTH[ $!X+1 ].
4.7.1
Setting Array Variables
You can set an individual element of an array variable in any of the ways that you would use to set a
simple variable. For example,
!arrayname
attributename
will create an array variable as named (if it does not already exist) and will set element 1 of that
array to the value of attributename of the Current Element. If \arrayname already exists as a simple
variable, an error message is output and the command not actioned.
The individual elements of an array variable can be set independently and in any order. Thus you
can set !X[1] and !X[10] without setting any of the intervening elements !X[2] to !X[9].
In addition to the setting options common to simple variables, you can also use the following two
additional facilities for setting array variables:
►
Appending a new element to an existing array
To set a new element at the end of an existing array without needing to know which elements are
already set, use the APPEND command thus:
VAR !ARRAY APPEND LENG
The new array element to be created is determined automatically by adding 1 to the highest
existing index for the array !ARRAY. If JARRAY does not yet exist, it is created and the data is
stored in !ARRAY[1]. If JARRAY exists but has no elements, the data is stored in !ARRAY[1]. If
JARRAY exists but is a simple variable, an error message is output and the command is not
actioned.
4-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
►
Splitting a text string into array element components
You can split a text string into its component fields, as determined by a delimiting character, and
store each field in a separate array element. This can be useful after reading a record from a file
into a variable. By default, the delimiter is any white-space character (Tab, Space or Carriage
Return/Line Feed), but you can redefine this within the command line.
To use this facility, use the SPLIT command thus:
VAR !FIELDS SPLIT ’123 345
678 ’
In this example the delimiter is, by default, the white-space character. This is a special case, since
consecutive occurrences of the white-space are treated as a single delimiter and white-spaces at the
start or finish of the string are ignored. The result is to create the array variable [FIELDS (if it does
not already exist) with the element !FIELDS[1] set to T23’, !FIELDS[2] set to ’345’, and
!FIELDS[3] set to ’678’.
To specify a different delimiter, define the required (single) character after the string which is to be
split, thus:
VAR !FIELDS SPLIT ’123 ,345 ,,678’ ’,’
In this example the delimiter is defined as a comma. The result is to create the array variable
[FIELDS (if it does not already exist) with the element !FIELDS[1] set to T23 ’, !FIELDS[2] set to
’345 ’, !FIELDS[3] created but set to zero length, and !FIELDS[4] set to ’678’. Note that in this
case, unlike the white-space delimiter, consecutive occurrences of the comma define empty
elements.
NOTE: The only way to set the special white-space delimiter is by default. That is, by not
specifying any delimiter on the command line. If a space is specified explicitly as the
delimiter (as ’ ’), it will behave in the same way as other delimiters.
You can combine the APPEND and SPLIT facilities in a single command line to append the fields of
a text string to the end of an existing array variable, thus:
VAR !FIELDS APPEND SPLIT ’123, 345’ ’,’
(See also Section 4.7.9.)
4.7.2
Selecting Array Variables (PDMS Users Only)
You can create an array which includes a number of elements which all satisfy specific selection
criteria, as defined by yourself. This is a useful way of collecting information on particular
elements.
You use the syntax:
VAR varjd COLLECT select
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-9
Where:
varjd
Is the name of the array that will be created to contain the elements selected
within select.
select
Is the selection criteria
The following general criteria can be used to define the selection, select'.
•
•
•
•
a class of elements or element types
a logical expression to be satisfied at all selected elements
a physical volume in which all selected elements must lie
a point in the hierarchy below which all selected elements must lie
All criteria (except for class) are optional.
►
Class is essentially a list of element types (or possibly of actual elements). This list can be
optionally qualified to indicate whether members should be included, or whether only ‘items’
(that is, the lowest level components in the hierarchy below a given element) should be
included.
For example:
ALL
selects all elements
ALL FRMW
selects all framework elements
ALL BRANCH MEMBERS
selects all piping components
ITEMS OF EQUI /VESS1
selects all primitives below /VESS1
( /PIPE1 /PIPE2 )
selects only /PIPE1 and /PIPE2.
So, the command:
VAR !PIPECOMPS COLLECT ALL BRANCH MEMBERS
Would create the array !PIPECOMPS and set it to contain the reference numbers of every piping
component in the multi— database.
►
Logical expressions are those which return True or False. They are most likely to be used to
check the value of an attribute for collection. The WITH or WHERE options introduce the
expression. For example:
VAR !LENGTHS COLLECT ALL WITH ( XLEN * YLEN 8 ZLEN GT 1000 )
would collect all elements for which the attributes XLEN, YLEN and ZLEN match the criteria in
the array !LENGTHS.
►
Volume is defined by the WITHIN keyword, you can define the volume either in terms of two
diagonally opposite points of an enclosing box, or as a volume around an element (with an
optional clearance around the box which contains the element). For example:
VAR !VOLUME COLLECT ALL WITHIN W800N17000U1000 TO W1400N13500U1200
collects all elements in the defined volume into the array !VOLUME.
4-10
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
VAR !PIPES COLLECT ALL PIPE EXCLUSIVE WITHIN VOLUME /PUMP1 1500
collects all piping components within the volume defined by a box ‘drawn’ 1500mm around
/PUMP1 and puts them into the array !PIPES.
The EXCLUSIVE keyword indicates that only the chosen elements exclusively within the given
volume are to be selected.
►
Hierarchy criteria can be defined by the FOR keyword, It identifies a list of elements below
which all selected elements must occur. You can also include an exclusion list. For example:
VAR !BRANCH COLLECT ALL BRANCH MEMBERS FOR /PIPE1 /PIPE2 EXCLUSIVE BRAN 1 OF /PIPE2
You can append the results of such a collection to an existing array using the APPEND keyword.
For example:
VAR !BENDS APPEND COLLECT ALL ELBOWS
Would add the references for all elbows to the array !BENDS.
You can also overwrite elements in the array by specifying the first index in the array which you
want to be overwritten. The specified index, and the indexes following it, will be overwritten by the
results of the . For example:
VAR !BENDS[99] COLLECT ALL ELBOWS
Would place the reference for the first ELBOW selected at position 99 in the array !BENDS,
overwriting any existing data, and subsequent selections in the array elements that follow.
4.7.3
Evaluating Array Variables for Selected Elements (PDMS Users Only)
Using the facilities described here you can create an expression and have it evaluated for all
elements which satisfy particular selection criteria. The results of the expression are then placed in
a named array.
The command syntax you use is:
VAR varjd EVALUATE expression
select COUNTvar varcount
Where:
varjd
Is the name of the array that will be created to contain the results of
expression for all the elements selected within select.
expression
Is the expression that will be carried out for all the elements that match the
select criteria.
select
Is the selection criteria (see above, and the relevant Reference Manual for
your product for details of selection criteria)
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-11
COUNTvar is an optional command which allows you to record how often the expression is
calculated in varcount (which is increased by one each time the expression is evaluated).
You can append the results of such an evaluation to an existing array using the APPEND keyword.
For example:
VAR !BOXES APPEND EVALUATE ( XLEN*YLEN ) FOR ALL BOXES
Would add the values calculated from the expression for all BOXES to the (already existing) array
BOXES.
You can also overwrite elements in the array by specifying the first index in the array which you
want to be overwritten. The specified index, and the indexes following it, will be overwritten by the
results of the evaluation. For example:
VAR !BOXES[99] EVALUATE ( XLEN*YLEN ) FOR ALL BOXES
Would place the result of the first evaluation for the selected elements at index 99, overwriting any
existing item, and the following results in the subsequent array elements.
4.7.4
Accessing Array Variables
You use the setting of an array variable in a command line by prefixing the array element identifier
by a $, as for a simple variable. For example,
SIZE $!PUMP[1]
If you try to access an array variable without specifying an index, an error message will be output.
4.7.5
Sorting Arrays
The SORT option of the VARiable command allows you to take an array (or number of arrays),
and sort their indices into a defined order. These sorted indices are held in a new array.
The SORT option also allows you to remove duplicated entries in arrays, and remove empty and
unset values.
The syntax for the command is:
VAR <index_id> SORT <gen_options> <varidl > <suboptionsl > <varid2> <suboptions2>
Where:
<index_id >
<gen_options>
The name of the array which will be created and contain the sorted indices
for the named arrays.
General options composed of:
UNIque
only one instance of a duplicate element will be indexed
NOUNset no unset elements will be indexed
NOEMpty no empty elements will be indexed
4-12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
<varidl>, <varid2> etc.
The arrays that are to be sorted. The first array (varid!) will be used as the
primary sort key. Only if there are duplicate elements in varidl will varid2
be referenced (and so on for subsequent arrays).
<suboptionsl > ,<suboptions2 > etc.
The format of these suboptions is:
type direction FIRST!ngroup varidfirst LAST!ngroup varidlast
Where:
type
is the type of sort, being made up of:
ASCII
(case dependent ASCII. This is the default)
Cl AsciI
(case independent ASCII)
NUMERIC (numeric)
direction
is the direction of the sort:
ASCEnding
DEScending
(default)
<varidfirst>
If FIRSTingroup is used, varidfirst will be created as a sparsely populated
array that has an entry each time a group of identical elements in the sort
begins. The entry will contain the group number. This array might be used,
for example, if only the first member of a group of identical entries is to be
used in (say) a report.
<varidlast>
If LASTingroup is used, varidLAST will be created as a sparsely populated
array that has an entry for the last member of a group of identical elements.
This variable could be used to determine when to output subtotalling in a
report.
NOTE: The length of the generated index array will be the length of the longest array being sorted
(unless one of the general options is used). If the arrays being sorted are sparsely
populated or contain empty strings, these elements are indexed last.
To use some simple examples, imagine we had the array [ANIMALS which contained:
[1]
[2]
[3]
[4]
[5]
Wombat
Kangaroo
Gnu
Aardvark
Antelope
The command:
VAR !INDEX SORT !ANIMALS
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-13
Would sort !ANIMALS and create the array !INDEX from the sort. !INDEX would look like:
[1]
[2]
[3]
[4]
[5]
4
5
3
2
1
The command:
VAR !INDEX SORT DESCENDING !ANIMALS
Would result in !INDEX looking like:
[1]
[2]
[3]
[4]
[5]
1
2
3
5
4
Using a different examples, look at the arrays ICAR , !COLOUR and IYEAR:
!CAR
CHARIOT
FORD
VAUXHALL
FORD
FORD
(unset)
ford
(unset)
vauxhall
FORD
[1]
[2]
[3]
[4]
[5]
[6]
(7]
[8]
[9]
[10]
!COLOUR
MUD
RED
YELLOW
YELLOW
(unset)
BLUE
GREEN
(unset)
YELLOW
YELLOW
!YEAR
26
1978
1990
1993
1986
1993
(unset)
(unset)
1994
1993
If you want to sort the arrays by car model, then on colour, and then on year, you would give the
command:
VAR !INDEX SORT !CAR CIASCII !COLOUR !YEAR NUMERIC
The resulting !INDEX array would look like:
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
[10]
4-14
1
7
2
4
10
5
3
9
6
8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Note the use of the CIASCII option, which tells the sort to ignore the difference between UPPER
and lower case, and the NUMERIC option which forces a numerical sort.
If you did not want to include every instance of duplicated data, use the UNIQUE option:
VAR !INDEX SORT UNIQUE !CAR CIASCII !COLOUR !YEAR NUMERIC
Resulting in:
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
1
7
2
4
5
3
9
6
8
with only one reference to a 1993 yellow Ford.
To strip out all the unset values (in 5, 6 and 8), use the NOUNSET option:
VAR !INDEX SORT NOUNSET !CAR CIASCII !COLOUR !YEAR NUMERIC
The result would be:
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
1
7
2
4
10
5
3
9
6
To sort these arrays so that only the first mention of each of the car groupings were mentioned, use
the FIRSTINGROUP option:
VAR !INDEX SORT !CAR FIRSTINGROUP !FIRST
This would create [INDEX as normal, which would look like:
[1]
[2]
[3]
[4]
[5]
[6]
1
2
4
5
10
3
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-15
[7]
[8]
[9]
[10]
7
9
6
8
It would also create the array !FIRST, which would look like:
!FIRST[1]
!FIRST[2]
!FIRST[6]
!FIRST[7]
!FIRST[8]
!FIRST[9]
1
2
3
4
5
6
corresponding to the first of CHARIOTs
corresponding to the first of FORDs
corresponding to the first of VAUXHALLs
corresponding to the first of fords
corresponding to the first of vauxhalls
corresponding to the first of (unset)s
NOTE: The SORT option is important when you want to calculate subtotals for array variables
(see section 4.7.6).
4.7.6
Subtotalling Array Variables
The VARIABLE command gives you the facility to create subtotals for your array variables. You
will usually need to SORT the arrays you need to subtotal (see above) to get the information you
need for the subtotalling. The principles are described below.
The syntax for subtotalling is as follows:
VARiable <subtotals>S\JBtOte\<values> <order> <wanted>
Where:
<subtotals>
is an array which will contain the calculated subtotals at the positions
specified by the <wanted> parameter.
<vallies >
is the array containing the values to be sub— totalled.
<order>
is an array containing the order in which <values> are to be sorted. This
array is usually created using the SORT (see section 4.7.5).
<wanted>
is the array that will hold the calculated subtotals at positions usually
defined using the LASTINGROUP option (see section 4.7.5).
Suppose you had the array !VALUE which looked like this:
!VALUE[1]
!VALUE[2]
!VALUE[3]
!VALUE[4]
!VALUE[5]
!VALUE[6]
!VALUE[7]
!VALUE[8]
4-16
10.0
20.0
30.0
40.0
50.0
60.0
70.0
80.0
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
The array !ORDER which looked like:
!ORDER[1]
!ORDER[2]
!ORDER[3]
!ORDER[4]
!ORDER[5]
!ORDER[6]
!ORDER[7]
!ORDER[8]
8
7
6
5
4
3
2
1
And the array ISUBTPOS which looked like:
!SUBTPOS[4]
!SUBTPOS[6]
!SUBTPOS[8]
true
true
true
You could then give the command:
VARIABLE SSUBTOTS SUBTOTAL SVALUE JORDER SSUBTPOS
which would take values from the !VALUE array, in the order specified by !ORDER, and calculate
subtotals at the positions specified by ISUBTPOS in the array !SUBTOTS. The !SUBTOTS array
would look like:
!SUBTOTS[1]
!SUBTOTS[2]
!SUBTOTS[3]
!SUBTOTS[4]
!SUBTOTS[5]
!SUBTOTS[6]
!SUBTOTS[7]
!SUBTOTS[8]
4.7.7
’’
’’
’’
’260.0’
’’
’70.0’
’’
’30.0’
Querying Array Variables
Querying the Current Settings
►
To query the setting of a specific element of an array variable, specify its indexed name, thus:
Q VAR !PUMP[1]
►
To query the settings of all elements of an array variable, specify the array name only, thus:
Q VAR !PUMP
The name of each defined element will be output, together with its current setting.
Querying the Length of an Array Variable
To query the current length of an array variable, use the ARRAYSIZE function. This returns the
total number of elements which exist within the array variable, regardless of their indexes or
settings.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-17
If, for example, the array variable !PUMP has only the elements !PUMP[1], !PUMP[10] and
!PUMP [20] defined, then the result of the command
VAR !LENGTH [ARRAYSIZE((PUMP])
will be to set the value of the simple variable !LENGTH to 3.
If you are trying to format a table (for example, when producing a report], the length of the longest
element in an array is a useful thing to know. You can do this using the ARRAYWidth function. The
syntax is:
ARRAYWidth <array >
This returns the length of the longest element in the <array>.
For example, in the array !LIST:
!LIST[1] ’One’
!LIST[2] ~Two‘
!LIST[3] ‘Three‘
The command:
!WIDTH=ARRAYWIDTH( !LIST )
would assign the value 5 to !WIDTH (corresponding to the length of the longest element in !LIST,
which is ’Three’ ).
Querying if an Array Variable is Defined
The DEFINED and UNDEFINED functions described in Section 4.4.2 also apply to array variables.
► To query if an array variable is currently defined at all, regardless of whether or not it has any
defined elements within it, specify the array name only, thus:
VAR !QD [DEFINED(!PUMP)]
VAR !QU [UNDEFINED(!PUMP)]
► To query if a specific element of an array variable is currently defined, specify its indexed
name, thus:
VAR !QD [DEFINED(!PUMP(10))]
VAR !QU [UNDEFINED(!PUMP(10))]
4-18
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
4.7.8
►
Deleting Array Variables
To delete a specific element of an array variable, specify its indexed name, thus:
VAR !PUMP[1] DELETE
►
To delete a complete array variable, specify the array name only, thus:
VAR !PUMP DELETE
Note that an array variable may exist without any elements.
4.7.9
Handling Line Feeds and Consecutive Spaces
Programs which use the forms and menus interface (e.g. the PDMS DESIGN, DRAFT and
ISODRAFT modules) strip out line feeds and compress consecutive spaces to a single space
before text strings are assigned to array variables. If this is not the effect you want, you can suppress
this automatic editing by including the RAW command into the variable-setting command line for
these programs.
The syntax for setting array variable elements to ‘unedited’ text strings is
VAR varjd (RAW] (APPEND] (SPLIT] ...
where ... represents any of the standard ways of setting variables.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
4-19
5
Expressions
An expression consists of operators and operands. For example, 2 + 3 is an expression, where 2
and 3 are the operands, and + is the operator. The result of the expression is 5.
Expressions can (and normally do) contain variables and, in PDMS, expressions will often contain
names of PDMS element types, attributes and pseudo-attributes. Expressions can also contain
functions. For example, SIN is a trigonometric function. Often, expressions will contain logical
functions. For example GT (greater than) can be used in comparisons.
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 andy, and two text strings textl and text2, the following expression is
meaningless:
x + textl
However, both of the following expressions are valid:
x+y
Has the effect of adding the values of the numeric variables.
textl + text2
Has the effect of concatenating (joining) the two text strings.
The following types of expressions are available:
Logical expressions
Logical array expressions
Real expressions
Real array expressions
Text expressions
5.1
See Section 5.2.
See Section 5.2.3
See Section 5.3
See Section 5.3.3
See Section 5.6
Format of Expressions
The format of an expression, for example the use of brackets, spaces and quotes, is important. If
you do not follow the rules given below you will get error messages:
•
Text must be enclosed in quotes. For example:
’This is text ’
•
There must be a space between each operator and operand. For example:
x+y
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-1
Use round brackets to control the order of evaluation of expressions and to enclose the
argument of a function. For example:
SIN(30)
In general, you do not need spaces before or after brackets, except when a PDMS name is followed
by a bracket. If there is no space, the bracket will be read as part of the name. For example:
(NAME EQ /VESS1 )
5.1.1 Operator Precedence
Operators are evaluated in the order of the following list: the ones at the top of the list are
evaluated first.
Brackets
Functions
* I
+ EQ, NEQ, LT, LE, GE, GT
NOT
AND
OR
Brackets can be used to control the order in which operators are evaluated, in the same way as in
normal arithmetic.
5.1.2 Nesting Expressions
Expressions can be nested using brackets. For example:
( (SIN(!angleA) * 2) / SIN(!angleB) )
5.2
Logical expressions
Logical expressions can contain:
•
PDMS attributes of type logical e.g. BUILT.
•
Logical constants. The constants available are:
TRUE, ON, YES for true
FALSE, OFF, NO for false
•
Logical operators
•
Logical functions
5—2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
5.2.1 Logical Operators
The logical operators available are:
AND
EQ, NE
GT, GE, LE, LT
NOT
OR
The operators EQ and NE may be applied to any pair of values of the same type.
The operators GE, LE, GT and LT may only be used with numbers and positions. For more
information, see Section 5.5, Using Positions, Directions and Orientations in Expressions.
NOTE: The operators EQ, NEQ, LT, GT, LEQ and GEQ are sometimes referred to as comparator
or relational operators; NOT, AND and OR are sometimes referred to as Boolean
operators.
See also Section 5.11, Precisions of Comparisons for tolerances in comparing numbers.
AND
Synopsis
logl AND log2 — > logical
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
TRUE and FALSE - > FALSE
EQ and NE
Synopsis
CADCENTRE Software Customisation
Reference Guide
Issue 1095
( numberl EQual number2 )
( textl EQual text2 ) — > logical
( logl EQual log2 )
— > logical
( idl EQual id2 )
— > logical
( posl EQual pos2 ) — > logical
( dirl EQual dir2 )
— > logical
( oril EQual ori2 )
— > logical
( ppi EQual pp2 )
— > logical
( numberl NEqual number2 )
( textl NEqual text2 ) — > logical
( logl NEqual log2 ) — > logical
( idl NEqual id2 )
— > logical
( posl NEqual pos2 ) — > logical
( dirl NEqual dir2 ) — > logical
( oril NEqual ori2 ) — > logical
( ppi NEqual pp2 )
— > logical
CADCENTRE
Protected by copyright: see frontispiece
— > logical
— > logical
5-3
Description
Compare two values. A special feature is used for the positions, only the
coordinates specified are compared. See Section 5.5.4 for more
information. Unset values result in FALSE across EQ, TRUE across
NE.
Example
( 1.0 eq 2.0) — > FALSE
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.
GT, GE, LE and LT
Synopsis
( numberl GT number2 )
( posl GT pos2 )
( numberl GE number2 )
( posl GE pos2 )
( numberl LE number2 )
{posl LE pos2 )
( numberl LT number2 )
( posl LT pos2 )
Description
Compare two values. A special feature is used for positions: only the
coordinates specified are compared. See Section 5.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.
Examples
( 1.0 LT 2.0)
( N 0 E 10 GT N 10 E 0 )
( N 0 E 10 GT N 10 E 0 )
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.
Synopsis
NOT logl —> logical
Description
Perform the logical NOT on a logical value.
Example
not TRUE - > FALSE
Synopsis
logl OR log2 — > logical
Description
Perform the logical inclusive OR between two logical values. (The
exclusive OR is defined by using NE.) Allows numbers instead of
logicals.
Side effects
If one of the value is undefined and the other one is TRUE, the result is
TRUE.
Example
TRUE or FALSE - > TRUE
— > logical
— > logical
— > logical
— > logical
— > logical
— > logical
— > logical
— > logical
- > TRUE
- > FALSE
- > FALSE
NOT
OR
5-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
5.2.2 Logical Functions
The logical functions available are
BADREF
DEFINED,UNDEFINED
EMPTY
MATCHWILD
UNSET
VLOGICAL
BADREF
Synopsis
BADREF (id)
—> logical
Definition
Returns true if id is invalid, else false.
Example
BADREF(TREF) - >
’true’ if TREF=nulref
DEFINED and UNDEFINED
Synopsis
Description
DEFined ( variable jiame )
— > logical
DEFined ( variable jiame , number ) — > logical
UNDEFined ( variable jiame )
— > logical
UNDEFined ( variable jiame , number )
— > logical
With one argument, DEFINED is true only if the scalar variable, the
array variable or the array variable element exists.
With two arguments, DEFINED is true only if the first argument is an
array variable which has a value for the index denoted by the second
argument.
UNDEFINED( Ifoo ) is equivalent to NOT DEFINED( Ifoo ).
Example s
DEFINED ( Ivar )
DEFINED ( !array )
DEFINED ( !array[l] )
DEFINED ( !array , 1 )
DEFINED ( Irav )
UNDEFINED ( lyarra )
DEFINED ( !array , 3 )
- > TRUE
- > TRUE
- > TRUE
- > TRUE
- > FALSE
- > TRUE
- > FALSE
EMPTY
Synopsis
EMPTY (text)
—> logical
Definition
Returns true if text is a zero length string, else false.
Example s
EMPTY (”)
EMPTY(’ABC’)
->
->
TRUE
FALSE
MATCHWILD
Synopsis
CADCENTRE Software Customisation
Reference Guide
Issue 1095
MATCHW/ILD( textl,text2)
MATCHW/ILD( textl,text2,text3)
MATCHW/ILD( textl ,text2 ,text3 ,text4)
CADCENTRE
Protected by copyright: see frontispiece
5-5
Description
Matches string text2 to sting textl . If the same then returns true, else
false. text2 may contain wildcard characters. The defaults for wildcards
are
*
for any number of characters
?
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.
Example
MATCHW/ILD(’A big bottle of beer’,’*big*’)
MATCHW/ILD(’A big bottle of beer’,’??big*’)
MATCHW/ILD(’A big bottle of beer’,’???*big*’)
MATCHW/ILD(’A big bottle of beer’,’*big*beer’)
MATCHW/ILD(’** text’,’**!’,’!’)
- > TRUE
- > TRUE
- > FALSE
- > TRUE
->TRUE
UNSET
Synopsis
UNSET ( value )
— > logical
Definition
Returns true if value is unset, else false, value can be of any data type
including arrays. Normally it will be a PDMS attribute.
Examples
UNSET( DESC ) — > ’true’ where DESC is an unset text attribute
UNSET(CRFA) — > ’false’ where CRFA contains unset reference
attributes
VLOGICAL
VLOGICAL is used for the late evaluation of variables.
5-6
Synopsis
VLOGICAL ( variable _name )
VLOGICAL ( variable jiame , 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, ’FAL, ’FALS’ or ’FALSE’ (case
insensitive) or a numeric value equal to zero.
Examples
VLOG ( !array[l] ) - > TRUE
VLOG ( \array , 2 ) - > FALSE
Side effects
If the scalar variable, the array variable or the array variable element
does not exist, the result is undefined.
CAD CENTRE
Protected by copyright: see frontispiece
— > logical
— > logical
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Errors
Scalar variables may not be indexed. For example, VTEXT (!var[l]) )
will return an error.
Array variables must have an index. For example, VTEXT ( !array ) )
will return an error.
The value cannot be translated into a logical.
See also:
VTEXT, used for late evaluation when a text result is required.
VVALUE, used for late evaluation when a numeric result is required.
5.2.3 Logical array expressions
Logical array expressions can contain:
•
•
•
•
5.3
PDMS attributes of type logical array. For example, :LOGARR where :LOGARR is a UDA
of type logical.
Logical constants. The constants available are:
TRUE, ON, YES for true
FALSE, OFF, NO for false
Logical operators. See Section 5.2.1.
Logical functions. See Section 5.2.2.
Numeric (Real) Expressions
In PDMS expressions, integers are treated as reals; they are fully interchangeable. Numeric
expressions can contain:
•
Numbers, for example: 32, 10.1.
Numbers can be given as as integer exponents, for example:
10 exp 5
5E6
Numbers can contain units. The valid units are MM, M/ETRES, IN/CHES, FT, FEET. These
may be preceded by SQU/ARE, CUBIC, CUB/E to denote non-linear values. For example:
100 mm, 10 exp 5 cubic feet. Feet and inches can be shown as, for example, 10’6.
2.54 EXP 6
2.54 EXP –6
(81 / 3) EXP 2 IN
2.54 x 10 6 = 2540000
2.54 x 10- 6 = 0.00000254
81/3 x 10 2 inches = 2700 inches
•
PDMS attributes of type number, for example: XLEN.
•
Position, direction and orientation attributes which have a subscript to indicate which part of
the array is required. For example, POS[2] means the second element of the POSITION
attribute, that is, the northing. Note that position, direction and orientation attributes without
subscripts can only be used in number array expressions.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-7
The keyword PI (3.142).
Numeric operators.
Numeric functions.
5.3.1 Numeric (Real) Operators
The numeric operators available are:
+
Add
—
Subtract
*
Multiply
I
Divide
ADD and SUBTRACT (+ and - )
Synopsis
number + number
number — number
— number
+ number
Description
Add and subtract two numbers. They can also be used as unary
operators at the beginning of a parenthesised subexpression.
Examples
1 + 2 - > 3.0
1 - 2 - > -1.0
+ 1 - > 1.0
- 1 - > -1.0
Side effects
Units are consolidated across add, subtract.
Errors
Floating point overflow.
— > number
— > number
— > number
— > number
DIVIDE and MULTIPLY (/ and * )
Synopsis
number * number — > number
number / number — > number
Description
Multiply or divide two numbers.
Examples
2 * 3 - > 6.0
2 / 3 - > 0.666666666
Side effects
Numeric underflow is not considered to be an error and neither is it
flagged as a warning. The result returned is zero.
Units are consolidated across Multiply and Divide.
Errors
Floating point overflow.
Divide by zero.
5.3.2 Numeric (Real) Functions
The numeric functions available are:
ABS ( numberl )
ACOS ( numberl )
ASIN ( numberl )
5-8
Gives the absolute value of a number
Gives the arc cosine of a number, in degrees.
Gives the arc sine of a number, in degrees.
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
ATAN ( numberl )
Gives the arc tangent of a number, in degrees.
ATANT ( numberl, number2 ) Gives the arc tangent of numberl /number2, in degrees, with the
appropriate sign.
ALOG ( numberl ) Gives the exponential function (natural anti-log) of a number.
ARRAY(pos or dir or ori)
Converts a position, direction or orientation value or attribute into
three numbers.
ARRAYSIZE ( variable-name )
Gives the size of an array variable.
ARRAYWIDTH( variable-name )
Gives the largest display width of any string in array variable-name.
COMPONENT dir OF pos2
Gives the magnitude of a vector drawn from E0 NO U0 to pos2,
projected in the direction dirl.
INT ( numberl )
Gives the truncated integer value of a number.
SIN ( numberl )
Gives the sine, cosine or tangent value of a number (considered to be
in degrees).
COS ( numberl )
Gives the sine, cosine or tangent value of a number (considered to be
in degrees).
TAN ( numberl )
Gives the sine, cosine or tangent value of a number (considered to be
in degrees).
LENGTH ( textl )
Gives the length of textl .
DLENGTH ( textl ) Gives the length of textl. DLENGTH is used with characters which have
a displayed width that is different from standard characters, such as
Japanese.
Gives the natural logarithm of a number.
LOG ( numberl )
MATCH ( textl, text2 )
Gives the position of the beginning of the leftmost occurrence of
text2 in textl. If text2 does not occur in textl, 0 is returned.
DMATCH ( textl, text2 )
Gives the position of the beginning of the leftmost occurrence of
text2 in textl . If text2 does not occur in textl , 0 is returned.
DMATCH is used with characters which have a displayed width that is
different from standard characters, such as Japanese.
MAX ( numberl, number2[ , number?) [. . .]]) )
Gives the maximum value of the arguments.
MIN ( numberl, number2[ , number3 [. . .]]) )
Gives the minimum value of the arguments.
NEGATE
NINT ( numberl )
Multiply a number by —1.0.
Gives the nearest integer to a real. NINT(N+0.5) is equal to N+l if
N is positive or equal to zero, to N if N is negative.
OCCUR ( textl, text2 )
Gives the number of times string text2 occurs in string textl .
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-9
REAL ( textl )
Try to read a number at the beginning of textl .
POWER ( numberl, number2 )
Gives the the value of numberl raised to the power number2.
SORT ( numberl )
Gives the square root of a number.
VVALUE ( variable-name )
Used for late evaluation of variables. Gives a real value.
ABS
Synopsis
ABS ( numberl ) — > number
Description
Return the absolute value of a real.
Example
ABS ( — 3.2 ) — > 3.2
ACOS, ASIN, ATAN and ATANT
Synopsis
ASIN ( numberl )
ACOS ( numberl )
ATAN ( numberl )
ATANT ( numberl , number2 )
— > number
— > number
— > number
— > number
Description
Return the arc-cosine, arc-sine or arc-tangent of a number, in degrees.
ATANT returns the arc-tangent of numberl Inumber2 with the
appropriate sign. ATANT is useful where the second value is near or
equal to zero. For example,
(6 0 ATANT) will give the correct result of 90 degrees,
(6 0 D ATAN) will indicate an error when trying to divide by zero.
Example
ACOS ( 0.8660254 ) - > 30
Errors
Argument of ACOS or ASIN out of range [—1.0, + 1.0]
ATANT (0.0,0.0) is undefined.
Synopsis
ALOG ( numberl ) — > number
Description
Return the exponential function (natural anti-log) of a number.
Example
ALOG ( -0.7 ) - > 0.4965853
Side effects
Numeric underflow causes the result to be set to zero.
Errors
Floating point overflow
ALOG
ARRAY
5-10
Synopsis
ARRAY(pos or dir or or!)
— > number
Definition
Converts a position, direction or orientation value or attribute into
three numbers.
Examples
ARRAY(elOO) - > 100 0 0
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
ARRAYSIZE
Synopsis
ARRAYSize {variable-name ) — > number
Description
Give the size of an array variable.
Example
ARRAYSIZE(!array) - > 2.0
Side effects
If the array variable does not exist, the result is undefined.
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
ARRAYWidth ( variable-name ) — > number
Description
Give the largest display with of any string in array variable_name.
Example
If an array contains the following values
!ARRAY[1]
’Bread’
!ARRAY[2]
’is’
!ARRAY[3]
’for’
!ARRAY[4]
’life,’
!ARRAY[5]
’not’
!ARRAY[6]
’just’
!ARRAY[7]
’for’
!ARRAY[8]
’breakfast’
then
ARRAYWIDTH(!ARRAY)
would return 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 dirl OF pos2 — > text
Description
Returns the magnitude of a vector drawn from E0 NO U0 to pos2,
projected in the direction dirl.
Example
COMP E 45 N of N 0 E 100 U 50 - > 70.710
SINE, COSINE and TANGENT
Synopsis
SINe ( numberl ) — > number
COSine ( numberl ) — > number
TANgent ( numberl ) — > number
Description
Return the sine, cosine or tangent value of a number (considered to be
in degrees).
Examples
COS ( 0 . 0 ) - > 1.0
TAN ( 4 5 . 0 ) - > 1.0
Errors
Division by zero for TAN if the sine is (nearly) equal to zero.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-11
INT
Synopsis
INT ( numberl ) — > number
Description
Return the truncated integer value of a number.
Examples
INT ( 1.6) - > 1.0
INT ( - 2 3 . 7 ) - > -23.0
Errors
Integer overflow.
LENGTH and DLENGTH
Synopsis
LENgth ( textl ) — > number
DLENgth ( textl ) — > number
Description
Return the length of textl. DLENGTH is for use with characters which
have a displayed width that is different from standard characters, such
as Japanese.
Examples
LENGTH ( ’abcdef’ ) - > 6.0
LENGTH (” ) - > 0 . 0
Synopsis
LOG ( numberl ) — > number
Description
Return the natural logarithm of a real.
Example
LOG ( 3 ) - > 1.0986123
Errors
Negative argument.
LOG
MATCH and DMATCH
Synopsis
MATch ( textl , text2 ) — > number
DMATch ( textl , text2 ) — > number
Description
Return the position of the beginning of the leftmost occurrence of text2
in textl. If text2 does not occur in textl, 0 is returned
DMATCH is for use with characters which have a displayed width that
is different from standard characters, such as Japanese.
Examples
MATCH ( ’abcdef’ , ’cd’ ) - > 3.0
MATCH ( ’abcdef’ , ’x’ ) - > 0.0
MATCH ( ’abcdef’ , ” ) - > 1 . 0
MAX and MIN
Synopsis
MAX ( numberl , number2 [ , number?) [ . . . ] ] ) — > number
MIN ( numberl , number2 [ , number? [•••]]) — > number
Description
Return the maximum or minimum value of the arguments.
Examples
MAX ( 1 , 3 . 4 )
MIN ( 7.6 , - 12.33 , 2.3 )
— > 3.4
- > - 12.33
NEGATE
5-12
Synopsis
NEGate ( numberl ) — > number
Description
Multiply a real by —1.0.
Example
N E G ( l ) - > -1.0
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
NINT
Synopsis
NINT ( numberl ) — > integer
Description
Return the nearest integer to a real. NINT(N+0.5) is equal to N+l if N
is positive or equal to zero, to N if N is negative.
Examples
NINT ( 1 . 1 )
NINT ( - 2 3 . 7 )
NINT ( 1 . 5 )
NINT ( - 1 1 . 5 )
Errors
Integer overflow.
->1.0
- > -24.0
— > 2.0
- > -12.0
OCCUR
Synopsis
OCCUR(tex/7, text2)
— > integer
Definition
Counts the number of times string text2 occurs in string textl .
Examples
OCCUR (’ABBACCBBBBBAB’, ’BB’)
OCCUR(’ZZZZZZZZZZZ’, ’A)
Synopsis
REAL ( textl ) — > number
Note: this function was formerly called NUMBER.
Description
Try to read a real number at the beginning of textl.
Examples
REAL ( T2.34’)
- > 12.34
REAL ( ’ 7.23 E 3 meters’ )
- > 7.23
REAL ( ’ —12E— 1 meters ’ )
— > —1.2
Note that if text is in the form of an exponent, (— 12E— 1 in the third
example), there must be no spaces in it.
Errors
Unable to convert the text into a real number
- > 3
-> 0
REAL
POWER
Synopsis
POWer ( numberl , number2 ) — > real
Description
Return the value of numberl raised to the power number2.
Side effects
Numeric underflow causes the result to be set to zero.
Units are consolidated across POWER.
Example
POWER ( - 2 , 3 ) - > - 8
Errors
Floating point overflow.
Zero first argument and non-positive second argument (effectively
divide by zero).
Negative first argument and non-integer second argument
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-13
SQRT
Synopsis
SQrt ( numberl ) — > number
Description
Return the square root of a real.
Example
SQRT ( 4 ) - > 2.0
Side effects
Units are consolidated across SQRT.
Errors
Negative argument.
VVALUE
VVALUE is used for the late evaluation of variables.
Synopsis
VVALue ( variable_name )
— > number
VVALue ( variable _name , number ) — > number
Description
With one argument, returns the value of the scalar variable or the value
of the array variable element as a number.
With two arguments, returns the value of the element corresponding to
the index number as a number.
Examples
VVAL ( !array[l] ) - > 1.0
VVAL ( !array , 2 ) - > 0.0
Side effects
If the scalar variable, the array variable or the array variable element
does not exist, the result is undefined.
Errors
Scalar variable may not be indexed. For example, VTEXT (!var[l]) )
will return an error.
Array variable must have an index. For example, VTEXT ( !array ) )
will return an error.
The string can not be converted to a number.
See also:
VLOGICAL
VTEXT
used for late evaluation when a
used for late evaluation when a text result is required.
5.3.3 Real Arrays
Real array expressions can contain attributes of type real array, for example: DESP.
5.4
Using IDs in Expressions
IDs can be used in expressions. IDs can be any of the following:
•
Element name, for example: /VESSI.
•
Refno, for example: =23/456.
•
Element type further up the hierarchy, for example: SITE.
•
Number within member list, for example: 3.
5-14
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Type and number within member list, for example: BOX 3.
•
NEXT, PREV for next, previous within current list. Optionally with a count and/or
element type, for example: NEXT 2 BOX, LAST CYL.
NEXT, PREV MEMBER for next, previous within member list. Optionally with a count
and/or element type. If the element type given is only valid as a member then MEMBER is
assumed. For example, NEXT BOX at an EQUIPMENT will assume MEMBER.
FIRST, LAST for first and last in current list. Optionally with a count and/or element type.
FIRST, LAST MEMBER for first and last in member list. If the element type given is only
valid as a member then MEMBER is assumed.
END to navigate up from current list. END is similar to owner but not quite the same. For
example, if the current element is a GROU MEMBER, and it has been reached from the
GROUP then END will return to the group but OWNE will go to the true owner.
•
Attribute of type ref, for example: CREF
•
SAME to mean last current element
•
NULREF to mean =0/0
•
CE for the current element
’OF’ may be used to nest the options indefinitely. For example:
SPEC OF SPREF OF FLAN 1 OF NEXT BRAN.
This denotes the SPEC element owing the SELE element pointed to by the SPREF attribute on the
first FLANGE of the next BRANCH. ILEAVE TUBE, IARRIV TUBE, HEAD TUBE, TAIL
TUBE can be added to denote tube. For example:
HEAD TUBE OF /BRAN1
An error will occur if there is no implied tube for the element concerned.
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.
ID arrays can also be used in expressions. For example, CRFA.
5.5 Positions, Directions and Orientations in Expressions (PDMS
only)
5.5.1 Using Positions in Expressions
The basic ways of defining a position are:
•
Position attribute plus optional WRT. For example:
POS OF /VESS1 WRT /* or Pl POS OF /CYL2
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-15
•
Cartesian position. For example:
N 45 W 20000 U 1000
•
Cartesian position from an element. For example:
N 1000 FROM /ATEST.
•
Cartesian position from a ppoint. For example:
N 1000 FROM Pl OF /BOX2.
•
Cartesian position from an attribute. For example:
N 1000 FROM POSS OF /SCTN1
•
Any numeric value within a position may itself be an expression. For example:
’ N (DESP[1] + 10) E’
is a valid position expression.
•
The cartesian position may optionally be followed by WRT to specify the axis system. See
Section 5.5.2.
5.5.2 WRT (PDMS Only)
The ’WRT’ keyword is used to toggle between absolute and relative units. When we specify an
element (or attribute of an element) we are specifying an absolute point in world space. The point
can be given in world space or some other axis. Normally the answer is required relative to the
owner axis system and this is taken as the default. For example:
’Q POS’
will return the position of the current element relatively to its owner.
’Q POS OF/EQUIP1’
will return the position of EQUIP1 relative to its owner. If we require the result in some other axis
system then the WRT keyword is used. For example:
’Q POS WRT /*’
for the position in world coordinates.
When we specify a Cartesian coordinate we are dealing with a relative position. For example, ’N
10’ is meaningless until we specify the axis system, or default to an axis system. Again we use ’WRT’
to do this, although it is important to note that in this case we are going from a relative position to
an absolute position (in the previous example WRT was used to go from an absolute position to a
relative one). For example:
’N 100 WRT/BOX1’
specifies an absolute position in world space which is N100 of /BOX1. The default is that Cartesian
coordinates are in the owning element’s axis system. This absolute position can be expressed in
different coordinate systems: the default is again the owner’s axis system.
5-16
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
NOTE: The CONSTRUCT syntax uses the world as the default axis.
Example
Consider the following:
A SITE at (0,0,0) with default orientation
A ZONE at (100,0,0) with default orientation
An EQUIPMENT at (100,0,0) with orientation ’N IS E’
A BOX at (—100,0,0) with default orientation
See Figure 5—1.
point (300, 100) wrt World
W
N
Box origin
(–100, 0) wrt Equipment
(100, 100) wrt Zone
(200, 100) wrt World
N
N
E
World origin
Site origin
W
E
N
Zone origin
(100, 0) wrt World
Equipment origin
(100, 0) wrt Zone
(200, 0) wrt World
Figure 5 — 1
The result of ’Q (N 100 WRT /BOX1)’, shown as * in the picture, will depend on the current
element:
•
•
•
•
At the World, the result is (300,100,0), in World coordinates.
At the Site, the result is (300,100,0) in World coordinates because the World is the owner of
the current element.
At the Zone the result is (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.
At the Equipment the result is (200,100,0), which is the position relative to its owner, the
Zone. At the Box the result is (100,100,0) which is the position relative to its owner, the
Equipment. WRT can be further qualified by FROM.
5.5.3 FROM
In some cases we require an offset from a fixed point, other than the position of an item. For
example, a ppoint or attribute. The FROM syntax is used for this. We may still use WRT in
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-17
combination with FROM, but in this case the WRT is only used to determine the axis direction and
not the offset, since the offset is specified by the FROM part.
Consider the following:
A SITE at (0,0,0) with default orientation
A ZONE at (100,0,0) with default orientation
An EQUIPMENT at (100,0,0) with orientation ’N IS E’
A BOX at (—100,0,0) with default orientation
See Figure 5—2.
Example 2
The result of ’Q (N 100 WRT /* FROM /BOX1 )’, shown as * in Figure 5—2, will depend on the
current element:
•
At world, Site, Zone the result is (200,200,0) since the offset of N100 is applied in world axis
rather than /BOX1 axis.
•
At the equipment the result is (100,200,0). Note: the default axis for the result is the zone.
•
At /BOX1 the result is (200,0,0), because the default axis for the result is the equipment.
Example 3
’Q (N 100 WRT /BOX1 FROM /* ) gives the same absolute position as the ZONE.
•
At the Zone and SITE the result is (100,0,0)
•
At EQUI the result is (0,0,0)
•
At BOX1 the result is (0,-100,0), remembering that the result axis is the EQUI.
5-18
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
point (200, 200) wrt World
W
N
Box origin
(–100, 0) wrt Equipment
(100, 100) wrt Zone
(200, 100) wrt World
N
N
E
World origin
Site origin
W
E
N
Zone origin
(100, 0) wrt World
Equipment origin
(100, 0) wrt Zone
(200, 0) wrt World
Figure 5—2
Example 4
’Q (N 100 FROM /* )’
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 Figure 5—3, and for
the BOX the point coincides with the ZONE.
•
•
•
At SITE, ZONE the result is (0,100,0)
At EQUI the result is (—100,100,0), remembering the default result axis is the zone
At BOX1 the result is (0,-100,0), as for Example 2.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-19
point (200, 0) wrt World
W
N
Box origin
(–100, 0) wrt Equipment
(100, 100) wrt Zone
(200, 100) wrt World
N
N
E
World origin
Site origin
W
E
N
Zone origin
(100, 0) wrt World
Equipment origin
(100, 0) wrt Zone
(200, 0) wrt World
Figure 5—3
5.5.4 Comparing positions
Two positions can be compared with EQ, NE, GT, LT, GE or LE. The pairs of coordinates are only
compared in the coordinate axes for which the two positions are defined. A position attribute
always has all three coordinates defined. For positions entered by the user, only those coordinates
which are given by the user are defined. For example, in
’N10U3’
only the Y and Z coordinates are defined, while the X coordinate remains undefined. For the EQ
operator, all the pairs of defined coordinates should be equal. For NE, only one pair of defined
coordinates need be different. For GT (LT,GE,LE), all the defined coordinates of the first position
should be greater than (less than, greater than or equal to, less than or equal to) the defined
coordinates of the second position. This means that GE is not the opposite of LT and LE is not the
opposite of GT.
If no coordinate of the two positions are defined for a common axis (e.g. ’N10’ and ’W4D7’), the
result of the comparison is undefined.
Examples:
’POS EQ W1S2D3’
This evaluates to true only if POS of the current element is ( - 1 , - 2 , — 3).
5-20
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
’POS GT N10’ or ’N10 LE POS’
Only the second coordinate of POS is compared; 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 in 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 Section 5.11, Precisions of Comparisons for tolerances in comparing numbers.
5.5.5 Direction
The basic ways of defining a direction are:
•
Direction attribute plus optional WRT For example,
HDIR OF /PIPE1 WRT /*
•
Cartesian direction. For example,
N45 W
•
Cartesian direction WRT to an element.
•
FROM pos2 TO pos2. For example,
FROM N 50 WRT CE TO N 100
All Cartesian directions are returned in the axis of the owner of the current element. For example:
(U WRT CE ) will return the Z axis of the current element relative to its owner.
Q ( Z WRT /SCTN )
will return the Z axis direction of /SCTN relative to the owner of the
current element. For example, if the result is required in world
coordinates the current element must be the World or a Site.
5.5.6 Orientations
The basic ways of defining an orientation are:
•
Orientation attribute plus optional WRT. For example:
ORI OF /BOX1 WRT /*
•
Cartesian orientation. For example:
dir IS dir AND dir IS dir
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-21
For example:
(E IS U WRT /SCTN1 AND N IS E WRT /SCTN1)
to set an orientation of an element to that of a section, rotated by 90 degrees.
See also Section 5.5.4, Comparing Positions .
5.6
Text Expressions
Text expressions can contain the following:
•
•
•
•
•
A text string, which must be enclosed in quotes. For example: ’FRED’.
A PDMS attribute of type text or word. For example: FUNC
A single element of a word array attribute. For example: ELEL[2].
Text operators
Text functions
5.6.1
Text Operator
The text operator available is + , used for concatenation
5.6.2
Synopsis
textl + text2 — > text
Description
Return the concatenation of two text strings,
Example
’no’ + ’space’ — > ’nospace’
Errors
Text result too long.
Text F u n c t i o n s
The text functions available are:
AFTER
BEFORE
DISTANCE
LOWCASE, UPCASE
PART
REPLACE
STRING
SUBS, DSUBS
TRIM
VTEXT
5-22
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
AFTER
Synopsis
AFTER ( textl , text2 ) — > text
Description
Return the substring of textl which is after the leftmost occurrence of
text2 in textl .
If text2 does not occur in textl, the null string is returned.
Examples
AFTER ( ’abcdef’ , ’cd’ ) - > ’ef’
AFTER ( ’abcdef’ , ’x’ ) - > ”
AFTER ( ’abcdef’ , ” ) - > ’abcdef’
BEFORE
Synopsis
BEFORE ( textl , text2 ) — > text
Description
Return the substring of textl which is before the leftmost occurrence of
text2 in textl. If text2 does not occur in textl, textl is returned.
Examples
BEFORE ( ’abcdef’ , ’cd’ ) - > ’ab’
BEFORE ( ’abcdef’ , ’x’ ) - > ”
BEFORE ( ’abcdef’ , ” ) - > ”
DISTANCE
Synopsis
DISTance ( numberl ) — > text
DISTance( numberl, logical!, logical!, logical!, number2, logical'!') —>
text
Definition
One argument. If the current distance units are FINCH, text is the
conversion of the decimal inches value numberl into the format
’aa’bb.cc/dd’. For example:
DISTANCE ( 17.5 )
is converted to
T’5.1/2’
Otherwise, text is the STRING conversion of numberl.
Six arguments. The format is:
DIST/ANCE (distance, feet, usformat, fraction, denom_or_dp, zeros)
where:
distance
is the numeric distance in inches that is to be formatted.
feet
is a logical flag set to true if output is to be in feet and inches
and to false if output is to be in inches.
usformat
is a logical set to true if US format is to be used or false if
PDMS format is to be used.
fraction
is a logical set to true if the fractional component is to be
output as a fraction or false if to be output as a decimal
denom_or_dp
is a number representing the largest denominator if fraction is
true or representing the number of decimal places if it is false.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-23
zeros
is a logical set to true if zeros are to be shown when that
component of the output has no value.
For both US and PDMS formats the following rules are observed:
•
If distance is negative, the first symbol is a minus sign.
•
If/eet is true and the distance is at least a foot, then the number of feet is output next, followed
by a single quote (’)• Only if zeros is true will the number of feet be output as 0 for distances less
than a foot. Otherwise the feet will be omitted.
•
If feet have been output, the inches will be at least two characters wide. Numbers less than ten
will be preceded by a space if US format is being used or a zero if PDMS format is used. A zero
will be output if there are no whole inches.
•
If no feet have been output and the distance is at least an inch, then the number of inches is
displayed but without any preceding spaces. Only if zeros is true will a 0 be output for distances
of less than an inch.
•
If inches have been output and fractions is true, these will be followed by a decimal point (.).
•
If fractions 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 fractions is false and the number of decimal places is greater than zero, then the decimal
point (.) is displayed followed by the remainder up to the appropriate number of decimal
places. If the number of decimal places is 0 then the decimal point is not shown either.
If US format has been selected then the following additional rules are observed on output:
•
The (’) after the number of feet is followed by a dash ( - ) .
•
The decimal point separating the inches from the fraction is replaced by a space.
•
The inches and fraction of inches are followed by a double quote(”).
Example 1. One argument:
DIST ( 76.23 )
— > ’6’4.15/64’ if the current distance unit is FINCH, otherwise
- > ’76.23’
Example 2. Six arguments:
The following table below 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(_).
5-24
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Distance
Feet & Inch
US
Fraction
Denom 100
Zeros
Feet & Inch
US
Fraction
Denom 32
No Zeros
Inches
US
Decimal
DP 1
Zeros
Inches
US
Fraction Denom
4
No Zeros
Feet & Inch
PDMS
Fraction
Denom 2
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.
More examples:
As an example, if the current distance units are feet and inches, then the expression
(DIST(34.5,TRUE,TRUE,TRUE,100,TRUE))
will result in the text string 2’ —10.1/2.
If the expression was:
(DIST(34.5,FALSE,TRUE,FALSE,1,TRUE))
the resulting output would be 34.5”
If the expression was:
(DIST(34.5,FALSE,TRUE,TRUE,4,FALSE))
the resulting output would be 34 1/2”
If the expression was (note the different distance value):
(DIST(128.5,TRUE,FALSE,TRUE,2,TRUE))
the resulting output would be 10’08.1/2”
LOWCASE and UPCASE
Synopsis
UPCase ( textl ) — > text
LOWCase ( textl ) — > text
Description
Return an upper or lower case version of textl .
Example
UPCASE ( ’False’) - > ’FALSE’
LOWCASE ( ’False’) - > ’false’
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-25
PART
Synopsis
PART(textl , number1 )
PART(text/, number1 , text2)
Description
With two arguments, returns the numberl component of textl assuming
that textl is split on any whitespace characters. If numberl is negative,
counting of components starts from the right.
With three arguments, as above, but use text2 as the separator on which
splitting takes place.
If the user gives a part number higher than the number of components
in the string, the function returns an empty string.
Examples
PART (’x— y— z’, 1, ’ —
PART (’a b e
d e’, 4)
PART (7PIPE45/B9’, - 1, ’/’)
PART(’aabbcc’,2)
PART(’aa-bb-cc’,3,’-’)
— > ’x’
- > ’d’
- > ’B9’
-> W
- > ’cc’
Synopsis
REPLace(textZ ,text2 ,text3)
REPLcice(textl ,text2,text3,inti)
REPLace(tex/7 ,text2,text2,intl ,int2)
—> text
—> text
—> text
Definition
Replace search string text2 in input string textl with replacement string
text3. If inti 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, inti and/or int2 may be negative to indicate that
the direction is backwards.
REPLACE
Example 1. 3 arguments:
REPLACE (’cat dog cat cat cat dog ’, ’cat’, ’dog’ )
— > ’dog dog dog dog dog dog’
All occurrences of ’cat’ are replaced with ’dog’
Example 2. 4 arguments: start occurrence given:
REPLACE (’cat dog cat cat cat dog’, ’cat’, ’dog’, 2)
— > ’cat dog dog dog dog dog
All occurrence of ’cat’ from the second occurrence onwards are
replaced with ’dog’
REPLACE(’cat dog cat cat cat dog’ ,’cat’, dog’, —2)
— > ’dog dog dog dog cat dog’
All occurrences starting at the second occurrence from the end of the
string and moving backwards are replaced
Note that a negative fourth argument without a fifth argument implies
backwards mode.
5-26
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Example 3. 5 arguments: start occurrence and number of replacements given:
REPLACE (’cat dog cat cat cat dog’, ’cat’,’dog’, 2,2)
— > ’cat dog dog dog cat dog’
Replace two occurrences of ’cat’ starting at second occurrence
REPLACE (’cat dog cat cat cat dog’, ,’cat’, ’dog’, 2, —2)
— > ’dog dog dog cat cat dog’
Replace two occurrence in backwards direction starting at the second
occurrence
REPLACE (’cat dog cat cat cat dog’, ’cat’, ’dog’,— 2,2)
— > ’cat dog cat dog dog dog’
Replace two occurrences in forwards direction starting at second
occurrence from the
end of the string
REPLACE (’cat dog cat cat cat dog’,’cat’, ’dog’, —2, —2)
— > ’cat dog dog dog cat dog’
Replace two occurrence in backwards direction starting at second
occurrence from the end of the string
The following examples all give the same result:
REPLACE(’catl cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 catlO’, ’cat’,
’mouse’, 4, 2)
REPLACE(’catl cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 catlO’, ’cat’,
’mouse’, 5, —2)
REPLACE(’catl cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 catlO’, ’cat’,
’mouse’,— 6, —2)
REPLACE(’catl cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 catlO’, ’cat’,
’mouse’, —7, 2)
In each case, the output string is
’catl cat2 cat3 mouse4 mouse5 cat6 cat7 cat8 cat9 catlO’
Notes:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
If the replacement string text3 is a null string the required number of
occurrences of the search string text2 are removed. For example:
REPLACE (’AAABBABZ’, ’B’, ”)
- > ’AAAAZ’
REPLACE (’AAABBABZ’, B’, ”, - 1 , - 1 ) - >
’AAABBAZ’
CADCENTRE
Protected by copyright: see frontispiece
5-27
Errors
If the input string textl is a null string or an unset text attribute, the
input string textl is returned unchanged. For example:
REPLACE (”, ’A,’B’) - >
”
If the search string text2 is longer than the input string textl, the input
string textl is returned unchanged. For example:
REPLACE(’AA, ’AAAAA , ’B’)
- > ’AA
If no occurrence of the search string text2 is found, the input string textl
is returned unchanged. For example:
REPLACE( ’AAAAAA,’B’,’C ’)
- > ’AAAAAA
If required occurrence inti is not found the input string textl is returned
unchanged. For example:
REPLACE(’AAAAAA, ’A, B’, 10 )
- > AAAAAA
If the number of replacements required int2 is greater than the actual
number of occurrence from the specified start occurrence, replacements
are made up to the end of the string ( or beginning in backwards mode).
For example:
REPLACE( AAAAAA, ’A, B’, 2, 8) - > ABBBBB’
REPLACE (’AAAAAA, A, ’B’, -3, 8) - > ’BBBBAA
STRING
Synopsis
Description
STRing ( any scalar type )
STRing ( number , textl )
STRing ( pos , textl )
— > text
— > text
— > text
Turns a value into a text string.
With a single argument the STRING function can be applied to the
following scalar data types:
numeric
logical
id
position
direction
orientation
With only one argument, decimal places are output to give a maximum
of 6 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 textl, which may take any
of the values between ’DO’ and ’D6’ (or ’d0’ and ’d6’), where the
number indicates the number of decimal places.
Note:
5-28
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.
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Examples
STRING ( 1 )
->T
STRING ( 1 , ’D3’ )
- > T.000’
STRING ( 1.23456789 )
- > ’1.23457’
STRING(1.1230000) ->’1.123’
STRING ( 1.23456789 , ’D3’ )
- > ’1.235’
STRING (9*9 LT 100)
- > ’TRUE’
STRING (OWN OF CE)
- > ’/PIPE1’
STRING(POS)
- > ’W1000 N20000 U18000’
STRING(POS, ’D4’ )
- > ’W10000.1234 N20000.1234 U18000.1234’
STRING(HDIR OF /PIPE1- 1)
- > ’D’
STRING(E 22.0125 N, ’D2’)
- > ’E 22.01 N’
STRING (ORI OF NEXT)
- > ’Y IS D AND Z IS U’
SUBSTRING and DSUBSTRING
Synopsis
SUBString ( textl , numberl )
— > text
SUBString ( textl , numberl , number2 )
DSUBString ( textl , numberl )
— > text
DSUBString ( textl , numberl , number2 )
— > text
— > text
Description
With two arguments, return the substring of textl beginning at the
position numberl to the end of textl .
With three arguments, return the substring of textl beginning at the
position numberl and of length number2. If numberl is negative, then
counting of characters starts from the RHS of the input string. If
number2 is negative, then characters up to and including the start
position are returned.
DSUBSTRING used with characters which have a displayed width that
is different from standard characters, such as Japanese.
If the chosen range is outside the original string, an empty string is
returned.
Examples
SUBSTRING ( ’abcdef’ , 3 )
SUBSTRING ( ’abcdef’ , - 3 )
SUBSTRING ( ’abcdef’ , 3 , 2 )
SUBSTRING ( ’abcdef’ , -3, 2 )
SUBSTRING ( ’abcdef’ , 3 , - 2 )
SUBSTRING ( ’abcdef’ , 10 )
SUBSTRING ( ’abcdef’ , -10 , 2 )
- > ’cdef’
- > ’abed’
- > ’cd’
- > ’de’
- > ’be’
- > ”
- > ’ab’
Synopsis
TRIM ( textl )
TRIM ( textl, text2 )
TRIM ( textl, text2, text3 )
— > text
— > text
— > text
TRIM
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-29
Definition
When only one argument is supplied, TRIM removes all spaces to the
left (leading) and right (trailing) of text! and returns the answer in text.
When two arguments are supplied, lexl2 specifies where the spaces
should be removed from: either ’E or ’1’ 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.
Examples
TRIM ( ’ How now, brown cow ’, ’LRM’ )
— > ’How now, brown cow’
TRIM ( TO.3000’, ’R’, ’0’ )
- > T0.3’
VTEXT
VTEXT is used for the late evaluation of variables.
Synopsis
VTEXT ( variable-name )
VTEXT ( variable-name , number )
— > text
— > text
Description
With one argument, get the value of the scalar variable or the value of
the array variable element.
With two arguments, get the value of the element corresponding to the
index number.
The value is returned as a text string.
Examples
VTEXT ( !var) - > ’hello’
VTEXT ( !array[l] ) - > ’LOO’
VTEXT ( !array , 2 ) - > ’0.00’
Side effects
If the scalar variable, the array variable or the array variable element
does not exist, the result is undefined.
Errors
Scalar variable may not be indexed (e.g. VTEXT (!var[l]) )
Array variable must have an index (e.g. VTEXT ( !array ) )
See also:
5.7
VLOGICAL
VVALUE
used for late evaluation when a logical result is required.
used for late evaluation when a numeric result is required.
Late Evaluation of Variables in expressions
The functions VVALUE, VLOGICAL and VTEXT are used for late evaluation of PML variables,
that is, they enable you to specify PML variables in expressions which will not be evaluated until the
expression is evaluated. For example, when you are creating a report template, you are actually
creating a macro which will run when a report is generated. All variables in a report template must
5-30
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
therefore be preceded by a suitable late evaluation operator, otherwise the system will try to
substitute a value for the variable when it is entered on the form. The difference between the
operators is the type of output. VVALUE is used to output a numeric value, VLOGICAL to output
a logical variable and VTEXT to output a text variable.
5.8
PDMS Attributes in Expressions
All PDMS attributes and pseudo-attributes may be recognised within expressions. Optionally they
may be followed by ’OF’ to denote a different element to the current one. e.g. POS OF /VESS1.
Brackets may be used to denote an element of an array, for example DESP[8 + 1] for the ninth
value of DESP. Since syntax clashes are possible, the keyword ATTRIB may be used to denote that
an attribute follows. For example, ATTRIB E will denote the pseudo-attribute EAST as opposed
to the start of a position or direction. PDMS attributes are described in the relevant manuals.
Pseudo-attributes which can be used in expressions are listed in Section 10.8.
5.9
Querying Expressions
All expressions may be queried. Arrays are always concatenated into a single variable. Imperial
values are always output as inch to variables. This preserves maximum accuracy. To output in finch,
then the distance function must be used. In general expression do not have to be enclosed in
brackets, but to be sure that other queries are not picked up by mistake then it is advisable to do so.
Particular queries which could lead to confusion are those available both outside and inside
expressions. These are:
Q PPOINT n
Q POS or cartesian position
Q ORI or cartesian orientation
The functionality may vary between outside and inside expression queries. For example, ’Q N 100
FROM /POSS’ is not valid. It must be entered as Q (N 100 FROM /POSS )’
5.10 Units in Expressions
When a user enters a literal value then the units are not necessarily known. The units for
PML variables are also unknown. Where units are known, then all internal values are set to
mm. The value is then converted to the target (local) units on assignment to a variable or on
output.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5 31
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:
NONE
UNKN
MM
INCH
SQIN
CUIN
no units, e.g. attribute OBS
unknown units, e.g. 10
dist/bore attribute if units are MM, or literal .e.g. 10 mm.
dist/bore attribute if units are INCH/FINCH, or literal . e.g. 10’
Multiply two INCH values together, or literal e.g. 10 sq in.
Multiply SQIN by INCH, or literal e.g. 10 cu in
On comparison, addition or subtraction of two values the following assumptions are made. If one
of the units is unknown and the other is anything other than UNKN, then the unknown value is
assumed to have the same units as the known units. A suitable conversion is then done if the known
units is INCH or SQIN or CUIN.
For example:
(XLEN GT 10).
If we are working in distance units of inches, it is known that XLEN is a distance value. Internally
the value is held in mm, but the units are held as INCH. The units for TO’ are held as unknown. On
doing the comparison, the TO’ is assumed to be inches, and thus multiplied by 25.4 to ensure that
the comparison works as expected.
Special action is also taken to preserve the correct units across multiplication, division, POWER
and SQRT, in particular the maintenance of SQIN and CUIN. In these situations, units of
%UNKN are treated as none. For example, (10 * XLEN) is assumed to result in INCH rather than
SQIN. An exception is made when a reciprocal would result from division. For example: for (10 1
XLEN) we assume that the 10 is in inches rather than none.
5.11 Precision of Comparisons
To allow for small losses of accuracy, the following tolerances are used.
Number
Tolerance factor of 0.000001. i.e. 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.000001 GT 1)
is false as it considers 1.000001 and 1 to be equal
(1.000002 GT 1)
is true
Position
Considered to be true if within 0.5 mm of one another.
Direction or Orientation
Considered to be equal if values are within 0.005
5 — 32
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
5.12 Undefined Values
In order to permit expressions like ((DIAM GT 200.0) OR (TYPE EQ ’BOX’)), expressions must
be able to cope with undefined values. Generally, applying an operator to one or more undefined
arguments has an undefined result. Two exceptions are: the use of the AND operator with a false
argument, will result in false, regardless of whether or not the remainder of the arguments are
defined; and OR which returns true if any of its arguments is true. For example, consider applying
the above expression when the current element is a box. DIAM is undefined, therefore (DIAM GT
200.0) is also undefined. However, (TYPE EQ ’BOX’) is certainly true and so the final result of the
whole expression evaluates to true.
An undefined result occurs when:
•
•
•
•
•
•
One of the operands or arguments of a function (except some cases of AND and OR)
is undefined.
An attribute is unavailable for the corresponding element (e.g.’DIAM OF OWNER’ when
the current element is a box).
An element is undefined (e.g. ’OWNER’ when the current element is the WORLD).
An attribute is unset (e.g. text attribute or UDA of length 0).
A variable is undefined (e.g. ’VVAL(!ARC6)’ where !ARC6 has never been initialised).
Two position constants are compared with GT, GE, LT or LE and they have no
common coordinates (e.g. ’N10 EQ E5’).
If the result of the whole expression is undefined, an error occurs.
5.12.1 Unset Values
A particular class of undefined values are unset values. The concept exists for attributes which are
valid for a given element, but for which no value has been assigned. Typically these may be
elements of an array, or ’word’ attributes. References of value =0/0 are also treated as unset.
Unset values are propagated as for undefined values (except for Boolean operations- see below).
Undefined values take precedence over unset. There is a specific logical function UNSET to test if
a values is unset.
Across comparisons, unset values are not propagated, but are treated as follows: —
EQ, GT, GE, LT, LE Results in false
NE
Results in TRUE.
OR , AND
Unset values are treated as false.
For example, if DESP(2) and :LVAL(3) are unset then:
(DESP(2) GT 99)
- > False
(DESP(2) NE 33)
- > True
(:LVAL(3) AND TRUE)
- > False
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
5-33
6
Basics of Using Macros
Macros are command sequences which are stored as text files. To access a macro file and input the
command sequence to your program, you run the macro. Thhe file is scanned line-by-line, with
exactly the same effect as if you were typing the lines in from a keyboard. Macro files may include
references to other fast input techniques, such as synonyms and user-defined variables. They may
also act on data which you define when you give the command to run the macro (parameterised
macros). Macros are permanent records which may be called from within any working session of a
program.
This chapter explains the principles underlying the use of basic macros and the ways of
incorporating standard commands into macro files.
Some more advanced macro facilities, involving the use of the Programmable Macro Language
(PML) and its associated error handling functions, are described in Chapters 7 and 8.
6.1
Using Macros
A macro is simply a sequence of command inputs stored in a file. The command and data format in
the file is exactly the same as that which you would input in an interactive working session. Such a
file does not usually form part of the specific program directory; it is held in an operating system
directory and is read from there, as input, by your program.
The process of reading the contents of a macro file as program input is known as running the
macro. The program does not discriminate between command inputs received directly from a
keyboard and those received when a macro file is being run.
6.2
Creating Macro Files
You usually create a macro by entering the command lines directly, using any standard text editing
facilities available on your computer, and saving the file thus produced. This method creates a text
file independently of any specific program with which the macro is to be associated (although the
lines of the macro must represent valid command syntax for such a program).
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
6 1
Section 6.7 contains examples showing what the contents of some simple macros might comprise.
Your program installation may already incorporate a number of standard administrative macros,
supplied as part of the overall software package, which enable the program to be set up and used
with a minimum of effort.
6.3
Naming and Running Macros
A file containing a macro can be given any filename which conforms to the pathname conventions
of the operating system.
NOTE: When referenced from within your program, the filename must always be preceded by a /
(slash) character. This character is not part of the filename as listed in the operating
system directory; it tells the program that what follows is a name.
It is sensible to give macro files names which indicate their functions, since this makes it easier to
remember the name when you want to run a macro. The suffix .mac is often used to indicate that
the filename is that of a macro, but this is optional. Typical names might include pump.mac (to
create a standard design of pump from Equipment primitives); draw.mac (to generate a plotfile for
a drawing using a standard layout and captions); and so on.
►
To run a macro from within your program, enter
$M I filename
where filename is the pathname of the macro file in the operating system directory structure. If just
the name of the file is given, the program will look for it in the current operating system directory;
that is, the directory from which you entered the program.
An error message will be output if the file cannot be found and opened for reading.
6.4
Facilities Available When Using Macros
6.4.1
The File End Marker
When a macro is run, the program will read the input file line by line (where each line is ended by a
Return) until it reaches a file end marker. This is the escape code
$.
NOTE: The full stop is part of the code, not punctuation.
This code must be the last item in the file, and should be on a separate line.
6—2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
When the end marker has been read, the program will return control to whatever source of input
was operating when the macro was called (which may be another macro; see Section 6.4.2).
If the file end marker is omitted, the program assumes that the macro has ended when it can read
no more data. Control passes back to the current input device, in the normal way, but the message
END OF FILE
is output as a warning of a possible error.
6.4.2
Nesting Macros
Nesting macros means that one macro may include a command to run a second macro, the second
macro may include a command to run a third, and so on. You can do this with up to the eight levels
of macro.
As an example, you may need to write a new macro to carry out some repetitive design operations.
One or more of these design operations may be common to other design jobs and macros may
already exist for them. You can call upon these existing macros, by name, from appropriate points
in your new macro.
In practice, a library of standard ‘sub-macros’ will be developed as a project progresses. These will
then be run from within other controlling macros for specific purposes.
6.4.3
►
Interrupting Macro Execution
To interrupt the running of a macro and then restart it, use the escape codes
$M$M +
When the code $M — is encountered in a running macro, execution of the macro is suspended and
control is returned to your terminal. You may then work in interactive mode until you enter the
code $M+ to restart the macro execution. The macro will restart from the point at which it was
interrupted. This allows you to mix macro and direct user processing.
► To abandon the running of a macro and, if required, any macros from which the interrupted
macro was called, use the escape codes
$MK
$MK//
$MK-n
where n is an integer.
The effects of the three forms are as follows:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
6-3
$ M K terminates all macros currently running or paused
•
$MK/z terminates all macros after the nth macro currently running. For example, if MAC1
called MAC2 which called MAC3, and MAC3 had been interrupted by a $M — command, then
entering $MK2 would terminate MAC3 and return to the line in MAC2 after the call to
MAC3. Entering $MK1 would terminate MAC2 and MAC3 and return control to MACl.
•
$M K— n terminates the n most recent macros. For example, in the previous situation, entering
$MK— 1 would terminate the last macro and return control to MAC2.
►
To query which macros are currently being run, use the escape code
$QM
This will list, on your screen, the name of each macro, the line number reached in its execution, and
whether or not it has been interrupted.
6.4.4
Comment Lines in Macro Files
Any lines of the macro which are enclosed between the characters
$(
$)
are ignored by the program when the macro is run. These delimiters may therefore be used to
insert explanatory comments into macros.
You are strongly recommended to put comment lines at the beginning of every macro to
summarise its function. It is also helpful to insert comments at appropriate stages throughout the
file which will make it easier for a new user, or for yourself at a later date, to understand the
purpose of each group of commands.
Comments may include new lines, and they may be nested. For example,
$( A simple comment $)
$( A comment containing
more than one line $)
$( A comment containing $( a nested $) comment $)
An alternative escape code which may be used for comments is
$*
All characters between the $* code and the end-of-line Return are ignored by the command
processor.
For example,
NEW GASK BEFORE SEL $* Adds gasket in front of current element
6-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
6.4.5
Prompts and Messages From Within Macros
It is often useful to output a prompting message or a note of explanation to the terminal from
within a running macro; either to ask for a data input or to indicate that the execution of the
program has reached a particular stage.
To do so, use the either the WRITE command:
WRITE 'message'
For example,
WRITE ’Your data is about to be verified; please be patient’
Or use the processor escape code:
$P message
where message does not require any delimiters
$P PLEASE ENTER POSITION OF EQUIPMENT
A prompting message is particularly useful following a command to set a variable to the next input
(see Section 4.2.4).
For example, the sequence
$P Please enter length in mm
VAR !SIZE READ
outputs a message to tell you that the program is waiting for you to enter a length (which will be
stored as the value of the local variable ISIZE). The program automatically generates the message
(Macro) Variable*
at this point, but this does not tell you what sort of data it is expecting. Note that your own message
should be generated before the VAR READ command, otherwise the message will not be output
until after you have complied with its request!
Any variables or macro arguments (see Section 6.5.1) within a $P message are expanded before the
message is output, whereas synonyms are not expanded.
For example, the macro line
$P COLUMN HEIGHT IS SET TO $V12 mm
will produce the message
COLUMN HEIGHT IS SET TO 21000 mm
if the numbered variable V12 has previously been defined as 21000.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
6-5
6.4.6
General Editing Facilities
The following editing facilities are available during interactive input. They are all based on Escape
codes, and may be used during the creation of a macro file:
►
To delete an individual character in an input line, follow the character by the code
$C
For example, the input WXX$CYZ will be read as WXYZ.
You may repeat the $C code if you wish to delete two or more consecutive characters.
For example, the input WXXX$C$CYZ will be read as WXYZ.
►
To delete the whole input line up to a specified point, input the code
$L
For example, the input ABCD$LWXYZ will be read as WXYZ.
To rewrite an edited line (which may include, for example, $C and $L codes) so that it is easier
for you to read and check, input the code
$=
For example, the input ABCD$LWXX$CYZ$= will output the edited equivalent WXYZ.
► To include a literal $ symbol within a command line so that the Command Processor will not
try to interpret it as an Escape character, input the double characters
$$
For example, the macro line
$P UNIT COST IS $$$V3
will produce the message
UNIT COST IS $25
if the numbered variable V3 has previously been set to 25.
6.4.7
Significant Line Length
You may specify the maximum number of significant characters in each command line by using the
escape code
$Wn
where n is an integer (not less than 10) which specifies the line length. Any characters after the nth
in a command line will be ignored by the command processor. This setting will remain in force
throughout your current program working session unless you reset it.
6-6
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
This gives a further method of including comments in a macro file (see Section 6.4.4); namely, by
adding the comment text after the nth position in a command line.
It also enables you to write multi-function macros. If you set out your commands in a macro file in a
tabular format, you may choose which commands are to be obeyed, when the macro is run, by
setting $Wn to an appropriate value.
For example, consider the following command lines in a pipework design macro:
...
NEW VALV /VALV–A SEL WITH STYP GATE
...
NEW VALV /VALV–B SEL WITH STYP GLOB
...
which add two new valves into a Branch at different points in the piping sequence.
If the command line length has not been restricted, or if it has been set to 36 or more, /VALV— A
will be a Gate Valve and /VALV— B will be a Globe Valve.
If you enter the command
$W20
before you run the macro, all input after SEL will be ignored on each line and both valves will be of
the default type.
To query the current line length limit, enter
$QW
The resulting output will be of the form
Maximum input width is n
NOTE: Care is needed when using this facility, since synonyms and user-definable variables are
expanded to their defined settings before the line length is truncated. This can cause
errors if you do not allow for it when calculating $W settings.
6.5
Parameterised Macros
It is often convenient to write a macro in a generalised form, using parameters to represent
dimensions, part numbers etc., and to assign specific values to those parameters only when the
macro is to be run.
6.5.1
Macro Arguments
In the simplest case, parameters are allocated positions in the command lines as macro arguments
by inserting escape codes of the form
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
6 7
$n
where n is an integer in the range 1 to 9. These arguments are then specified as part of the command
to run the macro. They follow the macro name, with spaces separating the individual arguments.
For example, if a macro named beam.mac includes the command line
NEW BOX XLEN $1 YLEN $2 ZLEN $3
then the macro call
$M/BEAM.MAC 5000 200 300
will run the macro and will set the lengths defined as $1, $2, $3 to 5000, 200 and 300 respectively.
The arguments may be referenced as often as you wish within a macro file.
Arguments may be either values or text, but note that a space in a text string will be interpreted as a
separator between two different arguments. Apostrophes in text arguments are treated as parts of
the arguments, not as separators between them. For example, if a demonstration macro arg.mac
includes the lines
$P First Argument is $1
$P Second Argument is $2
$P Third Argument is $3
and is called by the command
$M/arg.mac ’Arg1a Arg1b’ ’Arg2’ ’Arg3’
the resulting output will be
First Argument is ’Arg1a’
Second Argument is ’Arg1b’
Third Argument is ’Arg2’
whereas the intended output was
First Argument is ’Arg1a Arg1b’
Second Argument is ’Arg2’
Third Argument is ’Arg3’
If you need to include spaces or newlines in an argument, you must enclose the argument between
the escape codes
$<
$>
The correct form for the preceding example is therefore
$M/arg.mac $<’Arg1a Arg1b’$> ’Arg2’ ’Arg3’
As an alternative, you may redefine the separator between arguments to be the escape code
6-8
CAD CENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
$,
instead of a space.
If you do this, you must end the argument list with the escape code
$.
(Note: The full stop is part of the escape code, not punctuation)
Using this convention, the preceding example becomes
$M/ARG.MAC $,’Arg1a Arg1b’$,’Arg2’$,’Arg3’$.
If an argument is omitted when a macro is called, the $n in the macro command line is ignored.
Whether or not this leaves a valid command depends upon the syntax which applies.
To avoid possible errors, a default setting may be defined for each argument. If the argument is
omitted when the macro is called, the default setting will be used.
To define an argument’s default setting, use the command
$D/7 = default_string
where n is the argument number (1—9) and default_string is any sequence of characters ended by
Return.
The default setting may be specified at any point in the macro, but it will only be applied from that
point onwards. It is usually best, therefore, to define any defaults at the beginning of the macro. If
an argument has been specifically defined, a subsequent default specification is ignored.
Arguments may be omitted in the following ways:
•
If the normal macro calling sequence is used (spaces as separators, Return as end-of-line
marker), trailing arguments may simply be omitted
•
If a non-trailing argument is to be omitted, the escape code $ < $ > must be used to replace the
argument which is not required
•
If the $, argument separator is being used, the argument may be omitted from the list
For example, if the macro demo.mac expects three arguments, the following calls to run the macro
all omit one of the arguments:
Command
Effect
$M/demo.mac arg1 arg2
$M/demo.mac arg1 $<$> arg3
$M/demo.mac $,$,arg2$,arg3$.
Omits third argument
Omits second argument
Omits first argument
6.5.2
User-Definable Variables in Macros
Parameters in macro files may be represented by user-definable variables in exactly the same way
as for interactive inputs. The settings of the variables, to be substituted in the command lines when
the macro is run, may be defined in any of the usual ways. See Chapter 4 for a full explanation.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
6 9
If a variable is defined before the macro is called, its setting will be used automatically when the
$var id identifier occurs.
If the macro includes a command line of the form
VAR varjd READ
execution will pause at that stage until the required data is entered. It is usually a good idea to send
a prompting message to the terminal at this point, as discussed in Section 6.4.5, to remind you what
sort of input the program is expecting.
For example, part of a macro file might include the sequence
...
$P Input height of column in mm
VAR 99 READ
$P Height is $V99
...
6.6
Prompts for input data
Macro stops until data has been entered
You enter height here; Return restarts
macro
Message enabling you to check data
Useful Query Facilities with Macros
The following query Escape codes are available:
$QLM
$QLR
$QLS
$QL
6-10
displays maximum macro nesting depth
displays various recording limits for recording commands
displays space taken up by existing synonyms
shows all of the above
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
6.7
Examples of Some Simple PDMS Macros
This section lists some short PDMS macros which illustrate the main features. In practice, macros
are likely to be much longer and more complex than these examples.
Note that these macros are for PDMS only. However, users of other applications should still find
the logic behind their construction of use.
6.7.1
A Drawing Macro
During the course of a design, a particular drawing format may be used repeatedly, either for
drawing given views of the same group of items as the design progresses, or for drawing similar
views of different groups of items. It is often convenient to define the viewing commands and
drawing layout instructions in a macro. A simple drawing macro is given here as an example:
FILE /AREA3.PLT A1 OVER
FRAME
FRAME 10
PLAN THROUGH WEST 109100 NORTH 111500 UP O
ONTO XR.6 YR.7
SCALE 1/50
DRAW /AREA3–BOUND
DRAW /GR–AREA3–EQ /GR–AREA3–STR
$.
The commands in this macro cause the following actions:
•
Specify output to file; paper size to be Al for subsequent plotting
•
Draw two frames, one 10mm inside the other
•
Draw plan views of the elements /AREA3— BOUND, /GR— AREA3— EQ and
/GR— ARE A3— STR, viewed through a given point in space, to scale 1/50, centred at a given
point on the paper or screen.
Drawing macros are commonly used for setting up drawing annotation, including the title block.
6.7.2
An Equipment Construction Macro
Parameterised macros are useful for constructing Equipment elements when several items of
equipment are similar but have different dimensions. In the following example, the macro dmcol,
in a directory called mrc, could be run in DESIGN to construct a fractionation column of given
name, height and diameter, as shown in Figure 5—1. The column consists of two cylinders, a dished
end and five nozzles.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
6-11
/COL12/N1
COLUMN /COL12 ($3)
/COL12/N2
$1 (5000)
/COL12/N4
1250
/COL12/N5
Figure 5—1
Equipment created by macro /mrc/dmcol
$( dmcol = MACRO FOR FRACTIONATION COLUMN DESIGN $)
$( ARGUMENTS: HEIGHT, DIAMETER, NAME $)
NEW EQUIP $3
NEW CYLI DIAMETER $2 HEIGHT 1250 MM AT UP 625 MM
NEW CYLI DIAMETER $2 HEIGHT $1 CONNECT P2 TO P1 OF PREVIOUS CYLI
NEW DISH DIAMETER $2 HEIGHT ($2 / 4) RADIUS ($2 / 0.06)
CONNECT P2 TO P1 OF PREVIOUS CYLI
NEW NOZZLE $3/N1 CATREF /NFROU HEIGHT 200 MM
ORIGIN P1 IS UP POSITION P2 AT P1 OF DISH 1
NEW NOZZLE $3/N2 CATREF /NFROU HEIGHT 200 MM ORIGIN P1 IS EAST
POSITION P2 POLAR EAST FROM CYLI 2 BEHIND CYLI 2 BY DOWN ($1 / 3)
NEW NOZZLE $3/N3 CATREF /NFNOU HEIGHT 150 MM ORIGIN P1 IS WEST
POSITION P2 POLAR WEST FROM CYLI 2 BEHIND CYLI 2
NEW NOZZLE $3/N4 CATREF /NFLOU HEIGHT 150 MM ORIGIN P1 IS EAST
POSITION P2 POLAR EAST BEHIND CYLI 1 BY UP 1000 MM
6-12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
NEW NOZZLE $3/N5 CATREF /NFLOU HEIGHT 150 MM ORIGIN P1 IS EAST
POSITION P2 POLAR EAST BEHIND CYLI 1 BY UP $1 BY DOWN 1050 MM
$.
The macro has three arguments:
$1 is the height of the main cylinder
$2 is the column diameter
$3 is the name of the column
All others dimensions are calculated automatically when the macro is run.
The macro would be run by using a command such as
$M /mrc/dmcol 5000 1000 /COL12
This would create an Equipment item named /COL12, with a diameter of Im, a central cylinder
height of 5m, and five nozzles named /COL12/N1 to /COL12/N5.
Note the following points:
•
The cylinders and the dished end are all of the same diameter, given by the parameter $2
•
One cylinder is of fixed height (1250mm), while the height of the other is determined by the
parameter $1
•
The elliptical cross-section of the dished end is derived from the diameter and is calculated
using the following expressions (see Section NO TAG)
HEIG ($2 / 4)
RADI ($2 / 0.06)
•
height = diameter/4
radius = diameter/0.06
The nozzles are automatically named column_name/Nl, etc.
6.7.3
A Component Selection Macro
Sets of components may occur regularly throughout a design. For example, the combination
FLANGE— GASKET— VALVE— GASKET— FLANGE may often occur in a piping run. A good
way of speeding up the input of the components associated with the valve is to have a macro which
you can run after the valve has been created, selected, positioned and oriented in the design. The
following example shows such a macro:
$(MACRO TO PUT FLANGES AND GASKETS EACH SIDE OF A VALVE $)
$($)
NEW GASKET BEFORE SELECT
CONNECT TO NEXT
$($)
NEW FLANGE BEFORE SELECT
CONNECT TO NEXT
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
6-13
NEXT 2
$($)
NEW GASKET COPY PREVIOUS GASKET
CONNECT
$($)
NEW FLANGE COPY PREVIOUS FLANGE
CONNECT
$.
If this macro is in a file called flanges in a directory called pipe.macs, it can be called up in
DESIGN, after the valve has been positioned, by using the command
$M /pipe.macs/flanges
NOTE: The lines $($) are simply empty comment lines. These are useful for separating the
various sections of long macros in order to make the macro listings easier to read. (They
are included in this short macro only to demonstrate the principle.)
6-14
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
7
Programmable Macros and PML
This chapter describes how you can write programmable macros using PML, the Programmable
Macro Language.
7.1
Introducing PML
PML is an extension of your program’s command syntax. It is a simple high-level programming
language which allows you to input macro command sequences which can make and act upon
logical decisions during their execution.
A programmable macro is a self-contained sequence of commands which behaves like a subroutine
in standard programming terms. It is executed separately within the main command sequence and
can return a result at the point from which it was run, so that the calling command sequence ‘sees’
the result (which may be a number, a text string, a logical True or False, etc.) in place of the
programmable macro sequence.
PML provides four basic types of decision-making function for use within a macro. These are:
•
•
•
Conditional branching via the IF family of commands
Iteration or looping via the DO command and its associated BREAK and SKIP commands
Jumping to specified command lines via the GOLABEL and LABEL commands
•
Error handling logic based around the HANDLE family of commands
Each self-contained sequence of commands relating to one of these types of function is referred to
as a construct in the descriptions which follow.
NOTE: Constructs using these programming commands are valid only within macros; an error
message is output if you try to enter the syntax at normal program command level.
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
7.2
Conditional Branching
Conditional branching causes program execution to follow different paths, depending on the
results of logical expressions (see Section NO TAG). In its simplest form: if a logical expression is
TRUE the command sequence follows one path; if the logical expression is FALSE the command
sequence follows a different path.
7.2.1
Defining a Conditional Construct
The full command syntax for a conditional construction, as it would be incorporated into a macro,
is as follows:
IF (logical!) THEN
block!
ELSEIF (logical) THEN
block2
ELSEIF (logicaln) THEN
blockn
ELSE
block_default
ENDIF
where each logical is a logical expression and each block is a sequence of valid program commands.
The effects are as follows:
•
If logical! is TRUE, then block! is executed and everything else up to ENDIF is ignored.
•
If logical! is FALSE and logical2 is TRUE, then block! is ignored and block2 is executed.
Everything else up to ENDIF is ignored.
•
The preceding principle is applied until either one (and only one) block has been executed or
ELSE is reached. If logical! to logicaln all evaluate to FALSE and ELSE is reached, then
block_default is executed.
The ELSEIF and ELSE commands are optional, so that the simplest conditional sequence is
IF (logical) THEN
block
ENDIF
For example:
IF ( TYPE INSET ( ’EQUI’, ’SITE’, ’ZONE’, ’PIPE’ ) ) THEN
GOLABEL /ELEMENT
ENDIF
7-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
In this example, the macro would jump to the label /ELEMENT (see Section 7.4) only if the
current type was on of the list specified.
NOTE: You may not concatenate the commands into one line, so the following is not allowed:
IF (logical) THEN block ENDIF
7.2.2
Nesting Conditional Constructs
Any block may contain further IF... ENDIF conditional sequences, allowing you to nest conditional
constructs, as long as the total number of conditionals, DO loops and macro calls (HANDLE calls
etc.; see Chapter 9) does not exceed 20.
(See also ‘Nesting DO Loops’ in Section 7.3.5.)
7.3
DO Loop Iterations
A DO loop enables a sequence of commands (the body of the loop) to be executed more than once.
The number of times the loop is executed is normally controlled by a counter which is reset after
each execution cycle in accordance with a predefined condition. When the counter reaches a
specified value, control passes to the command line which follows the loop construct rather than
back to the beginning of the loop.
7.3.1
Defining a DO Loop
The full command syntax for a DO loop, as it would be incorporated into a macro, is as follows:
DO [counter] [FROM start] [TO finish] [BY stepsize]
block
ENDDO
where the arguments, all of which are optional and take default settings if omitted, are as follows:
•
counter defines the name of the variable which determines how many times the command
sequence block is executed (a numbered variable is not permissible here). This variable is
accessible, for reading only, from within the loop. If counter is not specified, an inaccessible
internal loop counter is used.
•
start defines the value of counter when the loop is entered. If start is not specified, it defaults to
1.
•
finish defines the value of counter which will cause the loop to be left. If finish is not specified, it
defaults to either infinity (if counter is not specified) or the maximum integer which the host
computer can represent (if counter has been named).
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
7~ 3
•
stepsize defines the increment (positive or negative) by which the value of counter is changed
each time the loop is cycled. If stepsize is not specified, it defaults to 1.
NOTE: Any of the numeric arguments {start, finish, stepsize} may be specified as an expression (as
long as it gives a numeric result). Any real value (e.g. 3.4) is rounded to the nearest
integer value before being used as a DO loop parameter.
ENDDO identifies the end of the DO loop. When the loop is left, control passes to the following
line.
7.3.2
Leaving a DO Loop
Each time the loop is cycled, the value of counter is tested to determine whether the loop should be
continued or left. The test is one of the following:
•
If stepsize is positive and counter is greater than/mzsZz, then the loop is left.
•
If stepsize is negative and counter is less than/znw/i, then the loop is left.
•
If counter has a value between start and finish, inclusive, then block is executed, the value of
counter is incremented by stepsize, and the tests are repeated.
NOTE: If start is equal to finish, blockvAW be executed once. Since the test to leave the DO loop is
performed at the top of the loop, it’s possible to leave the loop without it being used.
7.3.3
Breaking Out From DO Loops
If finish has the default setting of infinity, block will be repeated indefinitely if no action is taken
inside block to terminate the DO loop.
To terminate a DO loop (whether infinite or not) and transfer control to the line following ENDDO,
include the command
BREAK [IF (logical)]
within the block command sequence.
When BREAK is encountered:
•
If the optional ‘IF (logical)’ condition is included and if the expression logical gives a TRUE
result, then the DO loop will be left. If logical gives a FALSE result, then the DO loop will
continue as normal.
•
If no condition is included, the DO loop will be left immediately.
(To terminate a DO loop and transfer control to a specified command line, see the GO LABEL
command in Section 7.4.)
7—4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
7.3.4
Skipping DO Loop Iterations
You can control the way in which block is executed during any given iteration of the DO loop by
including the command
SKIP [IF (logical)]
within the block command sequence.
When SKIP is encountered:
•
If the optional ‘IF (logical)’ condition is included and if the expression logical gives a TRUE
result, then the current iteration of the DO loop will be aborted and the next iteration (if any)
will be carried out with counter updated. If logical gives a FALSE result, then the DO loop will
continue as normal.
•
If no condition is included, the DO loop will start its next iteration, with counter updated,
immediately.
7.3.5
Nesting DO Loops
Any block may contain further DO...ENDDO constructs, allowing you to nest DO loops. You may
also nest IF...ENDIF conditional constructs within DO loops and you may nest DO...ENDDO loops
within conditional constructs, as long as the total number of conditionals, DO loops and macro
calls (HANDLE calls etc.; see Chapter 9) does not exceed 20.
7.3.6
Using Elements of Array Variables to Control DO Loops
You can use the elements of an array variable (see Section 4.7) to control DO loop iterations in
either of the following ways:
•
•
By setting counter to each index of a named array variable in turn
By setting counter to the value stored in each element of an array variable in turn (the
iterations being carried out in the order determined by the indexes of the elements)
►
Using the array variable index
The relevant syntax has the format
DO counter INDexes (or INDices) arrayname
block
ENDDO
As the DO loop is executed, counter takes the values of each of the indexes in arrayname in
numerical order. For example,
VAR !PUMP[1] ’FRED’
VAR !PUMP[20] ’45
VAR !PUMP[10] ’JIM’
Sets elements 1, 20 and 10 of !PUMP
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
7~ 5
DO !I INDEXES !PUMP
$P Current index is $!I
ENDDO
would give the output
Current index is 1
Current index is 10
Current index is 20
►
Using the values stored in the array elements
The relevant syntax has the format
DO counter VALues arrayname
block
ENDDO
As the DO loop is executed, counter takes the values of each of the elements in arrayname in
numerical order of the corresponding indexes. For example,
VAR !PUMP[1] ’FRED’
VAR !PUMP[20] ’45
VAR !PUMP[10] ’JIM’
Sets elements 1, 20 and 10 of !PUMP
DO !I VALUES !PUMP
$P Value stored in array element is $!I
ENDDO
would give the output
Value stored in array element is FRED
Value stored in array element is JIM
Value stored in array element is 45
►
(index 1)
(index 10)
(index 20)
Accessing both the index and the value
The following example illustrates how you can access both the index and value for each array
element in turn using a DO loop.
VAR !PUMP[1] ’FRED’
VAR !PUMP[20] ’45
VAR !PUMP[10] ’JIM’
Sets elements 1, 20 and 10 of !PUMP
DO !I INDEXES !PUMP
$P Value in element $!I is $!PUMP[$!I]
ENDDO
would give the output
Value in element 1 is FRED
Value in element 10 is JIM
Value in element 20 is 45
7-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
7.3.7 Accessing gadget values
The following command is used to set variable-name to the value of all currently selected elements
in the multiple choice list uunname in turn:
DO variable-name LIST uuname
block
ENDDO
The following command is used to set variable-name to the value of all currently selected lines in
the text pane uunname in turn:
DO variable-name PANE uuname
block
ENDDO
7.3.8
Example of a Simple DO Loop Macro
The following macro prints a conversion table between degrees Centigrade and degrees
Fahrenheit. The table goes from 0 OC upwards in steps of 100. The table finishes when the
temperature goes above 300 OF.
$* set up infinite loop incrementing by 10
DO !CENT FROM 0 BY 10
$* calculate Fahrenheit value from Centigrade value
VAR !FAR ((9 / 5) * $!CENT + 32)
$* write out a line of the table
WRITE ’$!CENT $!FAR’
$* if the Fahrenheit entry is above 300 finish the DO loop
BREAK IF ($!FAR GT 300)
ENDDO
7.4
Jumping to Specific Command Lines
The LABEL and GO LABEL commands in PML allow you to jump to any specific point in the
command sequence. They play a similar role to the GOTO command which you may have
encountered in other programming languages.
7.4.1
Inserting a Label
To identify a specific point in a macro command sequence, insert the line
LABEL name
where name has a maximum length of 16 characters, excluding the slash character (/).
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
7A.2
Jumping to a Label
To jump directly to a labelled line, use the syntax
GOLABEL name
IF {logical}]
where name must correspond to an existing label.
When GOLABEL is encountered:
•
If the optional ‘IF logical’ condition is included and if the expression logical gives a TRUE
result, then macro execution jumps to the specified label and continues from the line following
that label. If logical gives a FALSE result, then macro execution continues without jumping.
•
If no condition is included, macro execution jumps to the specified label immediately.
There maybe more than one GOLABEL command jumping to the same LABEL, and jumps maybe
either forwards or backwards in the command sequence.
NOTE: GOLABEL may only cause a jump within or out of a command block, including a
conditional or DO loop construct. It may not cause a jump into such a block from outside.
7.4.3
Examples
The following sequence, which illustrates the use of GOLABEL to jump out of nested DO loops
when a specified condition arises, is valid:
...
DO !A
WRITE ’Processing $!A’
DO !B TO 3
VAR !C ($!A * $!B)
WRITE ’Product is $!C’
GOLABEL /FINISHED IF ($!C GT 100)
ENDDO
ENDDO
LABEL /FINISHED
...
The following sequence, which attempts to jump into a DO loop, is not valid:
...
GOLABEL /ILLEGAL
DO !COUNT TO 5
WRITE ’$!COUNT’
LABEL /ILLEGAL
ENDDO
...
7-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
7.5
Ending a PML Sequence
To exit a macro, use:
RETURN
This command causes control to be passed immediately from the current macro to the calling
macro (or to command level if there is no calling macro).
You should use RETURN is preference to the file end marker $. used in ordinary macros (see
Section 6.4.1).
You will find more information about the RETURN command in Chapter 9.
7.6
Constraints in Macros
The following restrictions apply to the use of macros:
•
Macros may be nested (that is, macros may call other macros) to a maximum depth of eight
(8)-
•
The maximum permitted total for all concurrently executing DO loops, IF/ELSEIF/ELSE
blocks and macro calls (of the types described in Chapter 9) is 20.
•
The maximum permitted number of LABELs in all concurrently executing macros is 40.
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
7—9
8
8.1
Handling Errors in Programmable Macros
The Principles of Error Handling
At interactive command level, program error handling takes place in two parts:
•
•
That performed by the program itself to diagnose and indicate an error.
That subsequently performed by you to remedy the cause of the error.
For example, suppose you tried to access a file called TESTI that either did not exist, or wasn’t
located where you thought it was. On diagnosing the problem, the system would stop processing
the command line and write out an error message, such as:
(41,323) Could not find file TEST1
The system would then resume its normal operation and wait for your next command. Note that it
takes no further action to deal with the error. You will usually react to the error message by, for
example, locating where the file actually exists or going through the process of creating it.
Within a macro, error handling is complicated by the fact that the macro command sequence
cannot intervene to correct an unforeseen error in the above manner. The default action when an
error is encountered in a macro command is the output of an error message and immediate
termination of the macro. Control is then returned to interactive command level. You can,
however, insert commands into a macro which, when an error occurs, immediately pass control to
another sequence of commands specifically provided to complete the handling of the error. The
rest of this chapter describes the latter facilities, based on the HANDLE and ONERROR families of
commands.
8.2
Handling Specified Errors
If you know which errors are most probable at given points in the command sequence, you can
anticipate these by specifying how they are to be handled within the macro execution. You can
specify different handling sequences for different errors which may be generated by a common
command line. You do this by using the HANDLE family of commands, which have the following
syntax:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
8-1
program_command
HANDLE <errorspecl>
blockl
ELSEHANDLE <errorspec2>
block2
ELSEHANDLE <errorspec3>
block3
ENDHANDLE
where program _command is a macro command line within which specific errors are foreseen and
each errorspec specifies a set of errors to be handled by the block of commands which follows it.
The form of errorspec may be any combination of the following:
•
•
•
•
One or more program error numbers, e.g. (41,323), such as are output at the start of error
messages sent to the screen. (For a listing of the corresponding message texts, see the
Reference Manual for the relevant program.)
One or more special error numbers which have been defined in the macro, e.g. 1 (see Section
8.5).
The command word NONE, meaning that the associated block is to be executed when no error
has occurred in executing program_command.
The command word ANY, meaning that the associated block is to be executed when any error
has occurred in executing program_command.
NOTE: The error message which would normally result is not output when an error is handled by
a HANDLE sequence. The relevant error message is, however, stored in the global
variable !!ERROR.TEXT, the content of which may then be output to display the error
message if required.
As an example, consider the following macro:
$* Open file holding data to be read in
$P Please input name of file to be read
VAR !NAME READ
OPENFILE $!NAME READ !INFILE
HANDLE (41,323)
$P File $!NAME does not exist; please try again
VAR !NAME READ
OPENFILE $!NAME READ !INFILE
ENDHANDLE
This macro (an amended part of the example macro contained in Section 9.7) askes the user to
input the name of a file which contains data to be read in to the system. If the file doesn’t exist, error
41,323 is returned and the HANDLE command instructs the program to pass control to the code
within the following block. The block sequence prompts the user to try again.
8—2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
If no error occurs, then the HANDLE block is not executed and the macro continues normally from
the line following ENDHANDLE.
If any error other than (41,323) occurs, then the HANDLE block is not executed and the program
continues with its standard error handling procedure, namely:
•
•
•
The macro is terminated.
The appropriate error message is output.
A ‘macro traceback’ is output, giving the macro line number at which the error occurred.
8.3
Handling Unspecified Errors
As well as allowing you to control the handling of specified errors at particular lines in a macro, as
explained in Section 8.2, PML allows you to determine the action to be taken when an error occurs
anywhere else in the macro (other than the default action of simply terminating the macro
execution). To do this you use one of the ON ERROR options described in the following
subsections.
NOTE: An ON ERROR setting applies to the macro in which it is specified and it is also inherited
by any called macros nested within it (unless reset specifically in the called macro). Only
one of the following options may be in force in any individual macro.
8.3.1
Jumping to a Label
This option uses the LABEL/GOLABEL facility (see Section 18.4) to transfer macro execution to a
labelled command line when any error occurs which is not specifically dealt with by a HANDLE
command. The syntax is
ONERROR GOLABEL name
where name must correspond to an existing label.
The label name should be immediately followed by a HANDLE sequence to complete handling of
the error, thus allowing you to centralise your error handling.
When the GOLABEL command has been carried out, ONERROR RETURN is set (see Section
8.3.4).
As an example, consider the following macro:
$* Open file holding data to be read in
LABEL /TRY.AGAIN
$P Please input name of file to be read
VAR !NAME READ
OPENFILE $!NAME READ !INFILE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
8-3
HANDLE (41,323)
$P File $!NAME does not exist; please try again
GOLABEL /TRY.AGAIN
ENDHANDLE
If any error occurs, control passes to the label /TRY.AGAIN and is then dealt with by the
subsequent HANDLE commands. This prompts the user to enter another filename, and will carry
on doing this so long as error 42, 323 is returned.
If any error other than (41,323) occurs, then HANDLE block is not executed and PDMS continues
with its standard error handling procedure, namely:
•
•
•
The macro is terminated.
The appropriate error message is output.
A ‘macro traceback’ is output, giving the macro line number at which the error occurred.
8.3.2
Continuing Macro Execution
If any error occurs which is not specifically dealt with by a HANDLE command, this next option
causes the error message to be output but allows macro execution to continue as if the error had not
occurred. The syntax is
ONERROR CONTINUE
The effects of enforced continuation will depend upon the nature of the error and the types of
command which occur in the rest of the macro. These effects may be unpredictable, so you should
use this option with caution.
As an example, consider the following macro:
ONERROR CONTINUE
VAR !INTRO ’My name is ’
VAR !NAME ’Colin’
WRITEFILE $!FILE1 ’Test for errors’
WRITEFILE $!FILE2 ’Second test for errors’
If any error occurs, the error message is output and then the macro continues to execute normally.
If, for example, !FILE1 already exists, the error 41,324 would be output for that command line.
After outputting the error message, the system would carry on to the next macro line and attempt
to write !FILE2. In this case, only !FILE2 would be written.
8.3.3
Pausing Macro Execution
This option causes execution of the macro to pause, such that interactive control is restored
temporarily, when an unhandled error occurs. The syntax is:
ONERROR PAUSE
8-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
The effect is as though a $M— command had been issued (see Section 6.4.3). You can then attempt
to remedy the error by entering commands interactively, and can then continue macro execution
by entering a $M + command. Alternatively, further execution of the macro may be abandoned by
entering a $MK command.
As an example, consider the following macro:
$P Please input name of file to be read
VAR !NAME READ
OPENFILE $!NAME READ !INFILE
ONERROR PAUSE
WRITEFILE $!INFILE ’Test for errors’
RETURN
If any error occurs, the appropriate error message is output, followed by a message stating that
macro execution has been paused due to an unhandled error. If, for example, the file doesn’t exist
at the location specified, you could enter a new filename and then enter $M+ to continue the
macro.
NOTE: This option is intended primarily for your own use during the development stages of a
new macro. Its use is not recommended in ‘production’ macros for use by others.
8.3.4
Terminating Macro Execution
The final option in this section corresponds to the default error handling process. The syntax is:
ONERROR RETURN
If any error occurs which is not specifically dealt with by a HANDLE command, the program
continues with its standard error handling procedure, namely:
•
•
•
8.4
The macro is terminated.
The appropriate error message is output.
A ‘macro traceback’ is output, giving the macro line number at which the error occurred.
Handling Errors in Nested Macros
Suppose that a macro named MAC_B calls another macro named MAC_A (via a $M/MAC_A
command line), such that MAC_A is nested within MAC_B. You may treat the whole of MAC_A
simply as a complex programming ‘command’ in MAC_B, and you can thus arrange for any error
generated in MAC_A to be handled by its calling macro MAC_B.
Any error in MAC_A may be handled in MAC_B by any of the methods described in Sections 8.2
and 8.3, using the HANDLE or ONERROR functions.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
8-5
Errors may be handled at any level in a stack of nested macros using this principle.
As an example, consider the following nested macros:
MAC_A (taken from the example in Section 8.2):
LABEL /TRY.AGAIN
$P Please input name of file to be read
VAR !NAME READ
OPENFILE $!NAME READ !INFILE
HANDLE (41,323)
$P File $!NAME does not exist; please try again
GOLABEL /TRY.AGAIN
ENDHANDLE
MAC_B (which has MAC_A nested within it):
$M/MAC_A
HANDLE (41, 321)
$P Read access not allowed – macro aborted
RETURN
ENDHANDLE
The error handling logic is as follows:
•
If error (41,323) occurs in MAC_A, it is handled within that macro as explained in Section 8.2.
•
If any error other than (41,323) occurs in MAC_A, execution of MAC_A is terminated and
control passes back to MAC_B.
•
If the error number returned to MAC_B by MAC_A is (41,321), this is handled within
MAC_B (by outputting the error message and stopping the macro).
•
If any error other than (41,321) is returned to MAC_B by MAC_A, the program continues
with its standard error handling procedure.
8.5
Ending Programmable Macro Files
To exit from your macro, use the command
RETURN
You may extend the RETURN syntax so as to define your own error number and associated
message when returning from a macro. This gives you greater scope when defining how errors
should be handled by the HANDLE command, as explained in Section 8.2.
To define such an error number and associated message, use the syntax
8-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
RETURN ERROR n [text]
where n is an integer which is to act as the error number and the optional text is an error message.
This facility allows you to raise a special error (as opposed to allowing the program to raise an
error) while returning to the calling macro. The error can then be handled in a calling macro. If the
error is not handled successfully, then control returns to command level and the error message
defined by text is output.
A short form of this syntax, namely
RETURN ERROR
causes the most recently raised error (which the program has already handled) to be raised again.
This allows you to perform some actions (via HANDLE or ONERROR) after an error and then pass
the error handling back to the program. On returning to the calling macro, the program resumes its
error handling as if you had not intervened.
As an example, the macro MAC_B from Section 8.4 could be rewritten:
$M/MAC_A
HANDLE (41,12)
DELETE BRAN
RETURN ERROR
ENDHANDLE
If error (41,12) occurs during the execution of MAC_A and is passed back to the calling macro
MAC_B, then the HANDLE command deletes the Branch and returns error handling to the
program. The program will then continue with its standard error handling procedure, namely:
•
•
•
8.6
The macro is terminated.
The appropriate error message is output.
A ‘macro traceback’ is output, giving the macro line number at which the error occurred.
A Summary of Error Handling Logic
The following sequences summarise the logic followed by the error handling system when an error
is raised at a given line in a macro. They are written in ‘program format’, using conditional
constructs as described in Section 7.2.
•
The Main Error Sequence
CHECK HANDLE
IF (error is still raised) CHECK ONERROR
The steps within the main error sequence are:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
8-7
Check H A N D L E
IF (HANDLE occurs on next non-blank non-comment line) THEN
IF (HANDLE handles the error) THEN
flag error as having been handled
execute HANDLE’s block of commands
ELSEIF (any ELSEHANDLE handles the error) THEN
flag error as having been handled
execute appropriate block of commands for ELSEHANDLE
ENDIF
ENDIF
•
Check O N E R R O R
IF (ONERROR GOLABEL is in force) THEN
GOLABEL to specified label
set ONERROR RETURN
re-run MAIN ERROR SEQUENCE
ELSEIF (ONERROR CONTINUE is in force) THEN
output error message and macro traceback
flag error as having been handled
continue this macro
ELSEIF (ONERROR PAUSE is in force) THEN
output error message and macro traceback
flag error as having been handled
output message that macro execution is pausing
pause macro and await interactive command input
ELSEIF (ONERROR RETURN is in force)
return from this macro and keep error raised
ENDIF
The main error sequence is repeated at each macro level until interactive command level is
reached. If, when control returns to command level, the error is still raised, then both the program
error message and a macro traceback are output.
8.7
Handling Errors in Form Initialisation Macros
NOTE: This section is intended only for those writing initialisation macros, which are run when a
form is to be displayed as part of a ‘menus and forms’ graphical user interface (see Part II
of this guide). If you are not writing application macros of this type, you may ignore this
section.
A form initialisation macro which handles specific errors must return with an error condition
raised if display of the form is to be prohibited. If the error has resulted from an intentional user
action, such as pressing ‘Cancel’ when asked to identify an item, the relevant error message should
still be written to the macro traceback log, but no error alert should be presented to the user.
To achieve this, the error handling syntax is:
8-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
RETURN ERROR [n [text}} NOALERT
where n is an integer which is to act as the error number and text is the corresponding error message
(see Section 8.5 for the basic principles).
If, when a form is being initialised (as a result of a SHOW, WAITON or FORM command), an error
occurs, this RETURN ERROR option allows you to replace the handled error returned by the
macro with a named condition of your own. The NOALERT command ensures that an error alert is
not displayed when the macro is terminated (cancelling the display of the form).
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
8-9
9
Reading/Writing External Files
This chapter tells you how to open and close external text files from within your program, so that
you can read and/or write their contents. Note that these are operating system functions rather
than program-specific operations.
9.1
Identifying Files
When you open a file from within your program, you identify the required file by specifying its
pathname in the operating system directory structure (or just its name if it is in your current OS
directory). If the named file already exists, it will be opened so that its current contents can be read
or modified; if the named file does not exist, a new file will be created.
When a file is opened, it is allocated a unique file token which is used for all subsequent references
to that file until it is closed. You do not need to know what the value of the token is (and cannot
easily find out): you simply allocate it to a named variable by trapping it within the file opening
action. You then use the name of the variable for subsequent reference to the file.
9.2
Opening a File
To open a file, use the command syntax
O P E N F I L E filename mode file-token
where filename is the OS pathname of the file, mode defines the type of operation which you will be
able to carry out on the open file, and file_token specifies the named variable which will be set to the
file token value when the file is opened.
The choices of mode are as follows:
READ
— Allows the file’s contents to be read but not modified.
WRITE
— Allows you to write data to a new file. The named file must not exist already.
Allows you to write data after the existing contents (if any) of the named file. If the
file does not yet exist, the data will be appended to the null contents of a new file (that is, the same
effect as for the WRITE option).
APPEND
OVER Write
-
— Allows you to write data to an existing file in such a way that it overwrites the
original contents of that file. The original contents are deleted when the file is opened.
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
9— 1
For example, the command
OPENFILE /data READ !FILE1
opens the file /data (in the current directory) in Read mode and allocates the file token to the
variable !FILE1. From now on, this file will be identified in your program as $!FILE1.
The maximum number of files which may be open simultaneously is 10.
9.3
Writing to a File
Before you can write to a file, the file must have been opened in WRITE, APPEND or OVERWRITE
mode, as explained in Section 9.2.
To write data to an open file, use the command syntax
WRITEFILE file_ token text
where filejoken recalls the named variable which identifies the file and text is a string which is to
written to the file record at the current file position. Each file record represents a single text string,
as defined by the usual
delimiting characters.
For example, the commands
VAR !INTRO ’My name is ’
VAR !NAME ’Colin’
WRITEFILE $!FILE1 ’Author Identification’
WRITEFILE $!FILE1 ’$!INTRO$!NAME’
will add two records to the file represented by !FILE1, namely ’Author Identification’ ’My name is
Colin’.
9.4
Reading from a File
Before you can read from a file, the file must have been opened in READ mode, as explained in
Section 9.2.
To read a record from an open file, use the command syntax
READFILE file_ token named jariable
where filejoken recalls the named variable which identifies the file and named jariable is the
name of a variable which is to hold the data read from the file. This command reads the record at
the current file position and then moves this position on by one (ready to read the next record).
For example, the command
READFILE $!FILE1 !RECORD1
will read a record from the file represented by !FILE1 and will store the result in !RECORD1.
9-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
9.5
Closing a File
It is assumed that the file to be closed has previously been opened and allocated a file token by
using one of the OPEN FILE modes described in Section 9.2.
To close a file, use the command syntax
CLOSEFILE file_ token [KEEP or DELETE]
whexQ fileJoken recalls the named variable which identifies the file. The supplementary command
words KEEP or DELETE allow you to specify whether the closed file is to be kept or deleted,
respectively. The default option, if neither is specified, is to keep the file.
For example, the command
CLOSEFILE $!FILE1
will close (and keep) the file represented by !FILE1.
9.6
Querying the Status of Open Files
To query which files are currently open, use the command
Query OPENFiles
9.7
Error Handling When Accessing Files
All of the errors which you encounter while accessing external files (such as trying to open a file for
which you have entered an invalid pathname, or trying to read another record from a file when you
are already at the last record) can be handled by using the standard PML error handling facilities,
as described in Chapter 8.
The main error messages which you will see are as follows:
(41,319) Error – Cannot access file
(41,320) Error – No write access to file filename
(41,321) Error – No read access to file filename
(41,323) Error – Could not find file filename
(41,324) Error – File filename already exists. Use OVERWRITE option
(41,325) Error – End of file found – filename
(41,326) Error – Unable to close file filename
(41,327) Error – File token token is invalid
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
9-3
The following example illustrates how some are these errors may be handled. This macro prompts
the user for a filename. The specified file is expected to have two space-separated columns of
values; for example:
10.5
20
40
12.5
29.6
10
The macro reads each line of the file, adds the two values together, and writes the sum to a new file.
$* Open file holding data to be read in
LABEL /TRY.AGAIN
$P Please input name of file to be read
VAR !NAME READ
OPENFILE $!NAME READ !INFILE
HANDLE (41,323)
$P File $!NAME does not exist; please try again
GOLABEL /TRY.AGAIN
ENDHANDLE
$* Open file for writing results to
OPENFILE /RESULTS WRITE !OUTFILE
HANDLE ANY
$P FATAL ERROR – Cannot open file /RESULTS in WRITE mode
$* Close input file before finishing
CLOSEFILE $!INFILE
RETURN ERROR
ENDHANDLE
$* For each file record, read both fields, add them together,
$* and write the result to /RESULTS
DO !LINE.NUMBER
READFILE $!INFILE !RECORD
$* If this is the last record, break out of the loop
HANDLE (41,325)
BREAK
ENDHANDLE
9-4
$*
$*
Extract the two values from the record and store them in
the elements of an array variable
VAR !ARRAY SPLIT ’$!RECORD’
$*
Add the two values together
VAR !SUM ( $!ARRAY[1] + $!ARRAY[2] )
$*
Write the result to the /RESULTS file
WRITEFILE $!OUTFILE ’$!SUM’
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
HANDLE ANY
$P FATAL ERROR while writing to /RESULTS
$*
Close input and output files before finishing
CLOSEFILE $!INFILE
CLOSEFILE $!OUTFILE
RETURN ERROR
ENDHANDLE
ENDDO
$* Close all files after successful completion
CLOSEFILE $!INFILE
CLOSEFILE $!OUTFILE
$P File /RESULTS contains the required sums
RETURN
CADCENTRE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Protected by copyright: see frontispiece
9-5
10
Reference Section
This chapter contains Z>ne/details of the commands and information given in the previous chapters
of this section.
It is designed for reference use only. It assumes that you know basically what you want to do, and so
gives you the basic information on how to do it.
The full instructions for carrying out the functions given in this guide are in the previous chapters.
If you are looking for a specific item of information, we strongly recommend that you first consult
the index. This should give you the location of the information you need, or at least give you an idea
of where you might find it.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10-1
10.1 Escape Codes
$R
$S
$G
$V
$! or $!!
$M
$P
For recording command line input.
For standard synonym instructions
For global synonym instructions
For recalling user-definable numbered variables
For recalling user-definable named variables
For entering macro instructions (i.e. running macros)
For the display of prompting messages
NOTE: The Escape character must not be confused with the ESCAPE key which is present on
most keyboards. The two terms are not related.
10-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
10.2 $R - Recording Command Input/Output
NOTE: You can have up to three levels of nested recordings.
Command
Effect
$R number filename
records command input to a file, if number is an odd number
which specifies the option to be used, filename is the name of
the file in the computer’s OS to which the logged data is to be
sent.
$R number
echoes input to your terminal, if number is even
Options:
add 1
add 2
add 4
add 8
add 16
Copy input commands to file (useful for creating synonyms and
macros)
Echo input commands to terminal (useful if running a macro. See
Section 6.3).
Record inputs from file (macros) only (‘indirect input’ in examples)
Record inputs from keyboard only (‘direct input’ in examples)
Expand synonyms and macro parameters before recording inputs
(useful when running synonyms and macros)
$HR
displays an on-line summary of the way of calculating number
$QR
query current recording status
$R—
suspend highest (most recent) recording level
$R+
reinstate a suspended level
$R
cancel the highest current level completely (until it is
redefined)
ALPha \_QQi filename
record command inputs and resulting outputs to logfile
filename
ALPha LOG filename OVERwrite
record command inputs and resulting outputs to the existing
logfile filename, overwriting any existing contents
ALPha \_QGi filename APPend
record command inputs and resulting outputs to the existing
logfile filename, appending to any existing contents
ALPha LOG END
close a log file
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10-3
10.3 $S and $G - Synonyms
NOTE: Command syntax for global synonyms ($G) is as for local synonyms ($S).
Command
Effect
$S synjiame = repjext
define a synonym
$/
specify a new command line
$< $>
include embedded spaces
$QS
list all currently defined synonyms in your synonym library
$SK
delete all currently defined synonyms
$U synjiame
prevent deletion of a synonym which has already been defined
$0 synjiame
mark a defined synonym so that it is expanded only when it
occurs at the beginning of a line
$S-
disable synonym translation
$S+
enable synonym translation
10-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
10.4 Operators and Functions
10.4.1
Numeric Operators and Functions
+
*
/
add
subtract
multiply
divide
sine; angle in degrees
SINe
cosine; angle in degrees
COSine
tangent; angle in degrees
TANgent
sin- 1 (arc sin); returns angle in degrees
ASIN
cos- 1 (arc cos); returns angle in degrees
ACOS
tan- 1 (arc tan); returns angle in degrees
ATAN
tan- 1; where tangent is expressed as the ratio of two lengths
ATANT
natural log (i.e. log to base e)
LOG
antilog
ALOG
absolute value; i.e. without regard to sign
ABS
square root
SQrt
POWer
raise to the power of
multipy by —1
NEGate
INT
truncated integer; rounded down
NINT
nearest integer; rounded up or down
minimum of two or more listed values
MIN
maximum of two or more listed values
MAX
COMPonent dir OF pos
OCCUR
REAL
gives the magnitude of a vector drawn from E0N0U0 to posl, projected in
the direction dirl
gives the length of a text string
gives the length of a text string of characters with different displayed width
gives the position of the beginning of a text string in another text string
gives the position of the beginning of a text string in another text string.
Used with characters with different displayed width.
gives the number of times a text string occurs in another text string,
trys to read a number at the beggining of a text string
ARRAY
ARRAYSIZE
ARRAYWIDTH
gives sign of array variable
gives size of array variable
gives largest display width of any string in array variable
LENGTH
□LENGTH
MATCH
□MATCH
W A L u e ( variable )
allows for late evaluation of a variable. Returns a number.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10 — 5
When combined in a single expression, the algebraic operators are executed in the following order:
( )
* I
EQ NEQ
NOT
AND
OR
GT LT GEQ LEQ
Operators which have equal priority are executed in the order in which they occur in the expression
(i.e. from left to right).
Additional pairs of parentheses may be inserted to make the expression easier to read, or to force
the order in which the operators are executed (since expressions containing nested pairs of
parentheses are evaluated from the innermost pair outwards).
NOTE: The algebraic operators + — * / must have at least one space on each side, when
used in an expression, to distinguish them from other uses of the same characters. A —
character immediately preceding a value is interpreted as a negative sign.
10.4.2
Logical Functions and Operators
A logical expression is one which tests the truth of a specified condition and returns one of two
possible values: 1.0 if the condition is True; 0.0 if the condition is False.
The logical operators are as follows:
EQ
NEQ
LT
GT
LEQ
GEQ
test for equality of two values; returns 1 if equal, 0 if not
test for inequality of two values; returns 0 if equal, 1 if not
test for first value less than second; returns 1 if true, 0 if false
test for first value greater than second; returns 1 if true, 0 if false
test for first value less than or equal to second; returns 1 if true, 0 if false
test for first value greater than or equal to second; returns 1 if true, 0 if false
NOT
AND
logical negation; reverses result of logical comparison
logical AND; returns true result (i.e. 1) only if both of two logical
comparisons are true
logical OR; returns true result (i.e. 1) if either (or both) of two logical
comparisons is true
OR
BADREF
DEFINED
UNDEFINED
EMPTY
MATCHWild
INSET
UNSET
returns true if an element identifier is invalid
returns true if variable exists
returns true if variable does not exist
returns true if text string is zero length
returns true if two text strings, including wildcard characters, match
test for presence of particular value within given list
test for unset value
VLOGical ( variable )
allows for late evaluation of a variable. Returns a logical value.
10-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
NOTE: The operators EQ, NEQ, LT, GT, LEQ and GEQ are sometimes referred to as comparator
or relational operators; NOT, AND and OR are sometimes referred to as Boolean
operators.
10.4.3
Text Functions and Operators
NOTE: Items appearing in square brackets are optional.
(AFTer (stringl, string2))
Searches for the leftmost occurrence of string2 in stringl and
returns as its result that part of stringl which follows that
occurrence. If string2 does not occur in stringl, the result is a
null string; that is, the empty string ’’
(BEFore (stringl, string2))
Searches for the leftmost occurrence of string2 in stringl and
returns as its result that part of stringl which precedes that
occurrence. If string2 does not occur in stringl, the result is
stringl.
DISTance
Converts distances to text strings. For more information, see
Section 5.6.2.
REPLACE
Replaces one text string with another.
(SUBString (stringl, valuel [, value2] ))
Returns that part of stringl which starts at the position valuel
and extends for a length of value2 characters. If you omit
value2, the resulting string continues to the end of stringl.If
valuel is negative, the count starts from the right hand end of
the string. If value2 is negative, that number of characters up to
the valuel position is returned. DSUBS is used for characters
that have a different display width.
(UPCase (string))
Converts string into an equivalent text string in which all the
characters are uppercase. This affects only the alphabetic
characters; numeric and symbols characters are not changed.
(LOWCase (string))
Converts string into an equivalent text string in which all the
characters are lowercase. This affects only the alphabetic
characters; numeric and symbols characters are not changed.
(STR ing (value [
Converts the real value value (usually the result of some other
expression) into a corresponding text string.
text] ))
The resulting string of numeric characters represents value to a
maximum accuracy of six decimal places (unless you specify
less), with trailing zeros removed, and with no decimal point if
it is a whole number.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10—7
The optional argument text allows you to specify the number of
decimal places. The format of text is n , where n (an integer
between 0 and 6 inclusive) is the required number of decimal
places.
(TRIM {string [, options} [, character} ))
Removes unwanted characters (most commonly used for
spaces) from string.character defines a single character which is
to be removed. The default is the space character. If you
specify more than one character, only the first character listed
will be removed.
options can have either of the following forms:’E, ’R’ or ’LR’ (or
’1’, ’r’ or Tr’) specifies from which end of string the characters
are to be removed (the default is ’LR’, which removes
unwanted characters from both the left and right ends of string)
’M’ (or ’m’) reduces consecutive occurrences of character to a
single occurrence anywhere in string.
(PART( stringl, partno, delimiter))
This extracts a given item {partno) from a text string {stringl),
where each field is bounded by a given delimiter character
{delimiter). In most cases the string would probably be stored in
a variable or attribute.
If a negative value is given for partno, the selection is counted
from the right end of the text string.
The default delimiter characters are Tab, newline or space (or
any multiple thereof). However if you define a delimiter
explicitly, multiple occurrences of that delimiter are treated
separately.
VTEXt ( variable )
10-8
allows for late evaluation of a variable. Returns a text string.
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
10.5 Variables
The identifiers allocated to user-definable variables may be one of three types:
•
•
•
iname identifies a local named variable.
! [name identifies a global named variable.
Ninteger identifies a numbered (global) variable.
Command
Effect
iname =definition
to define a local named variable
V.name =definition
to define a global named variable
number =definition
to set a numbered variable
VAR iname READ
sets the local variable to input from the keyboard
VAR iiname READ
sets the global variable to input from the keyboard
VAR number READ
sets the numbered variable to input from the
keyboard
VAR iname CLOCK
sets iname to the current date and time.
VAR iname CLOCK TIME
sets iname to the current time.
VAR number CLOCK DATE
sets iname to the current date.
10.5.1 Array Variables
Array variables may be set by:
•
•
\name\index\ identifies a local named array variable.
\\name\index\ identifies a global named array variable.
Command
Effect
\name\index\ =definition
to define a local named array variable
iiname [index] =definition
to define a global named array variable
VAR APPEND Iname element
appends named element to array Iname
VAR Iname SPLIT string
splits string into component fields (determined by
white— space delimiting characters) and stores
each resulting field in a separate array element.
VAR Iname COLLECT select
collects elements which match the select criteria
and creates array Iname which contains the
selected elements.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10— 9
NOTE:
See your application Reference Guide for full details of the select command syntax.
VAR '.name EVALUATE expression FOR select COUNTvar varcount
evaluates expression for all elements in !name that
meet the requirements of select. The optional
COUNTvar command records how often the
expression is calculated in the variable varcount.
VAR <index_id> SORT <gen_options> <varidl > <suboptionsl > <varid2> <suboptions2>....
sorts named arrays varidl, varid2 etc and sort their
indices into defined order, and held in array
index jd.
gen_options general options composed of:
UNIque
only one instance of a duplicate
element will be indexed
NOUNset no unset elements will be indexed
NOEMpty no empty elements will be indexed
suboptions made up of:
type direction FIRSTingroup varidfirst LASTingroup varidlast
Where:Zypeis the type of sort, being made up of:
(case dependent ASCII. This is the
default)
CIAscii
(case independent ASCII)
NUMERIC (numeric)
ASCIi
direction
is the direction of the sort:
ASC Ending (default)
DEScending
<varidfirst> If FIRSTingroup is used, varidfirst
will be created as a sparsely populated array that
has an entry each time a group of identical
elements in the sort begins. The entry will contain
the group number.
<varidlast> If LASTingroup is used, varidlast will
be created as a sparsely populated array that has an
entry for the last member of a group of identical
elements.
VARiable <subtotals>S\JSX.Q\a\<values> <order> <wanted>
Where <subtotals> is an array which will contain
the calculated subtotals at the positions specified
10-10
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
by the <wanted> parameter.
<values>is the array containing the values to be
sub— totalled.
<order>is an array containing the order in which
<values> are to be sorted. This array is usually
created using the SORT.
<wanted > is the array that will hold the calculated
subtotals at positions usually defined using the
LASTINGROUP option.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10-11
10.6 Macros
10.6.1
Editing Macros
Command
Effect
$C
delete an individual character in an input line
$L
delete the whole input line
$=
rewrite an edited line
$$
include a literal $ symbol
$WZ2
specify the maximum number of significant characters in each
command line
$QW
query the current line length limit
$.
file end marker
$(
$)
(text in brackets represent comment lines)
$P message
display message on terminal when macro is run
macroname$n
specify macro arguments, where n is an integer in the range 1 to
9
$D/z = default_string
define an argument’s default setting
10.6.2
Running Macros
Command
Effect
$M /filename
run a macro
$M-
interrupt the running of a macro
$M +
restart an interrupted macro
$MK
terminates all macros currently running or paused
$MK/z
terminates all macros after the nth macro currently running
$MK-n
terminates the n most recent macros
$QM
query which macros are currently being run
10-12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
10.6.3
Programming Macros (PML)
DO Constructs
DO [counter] [FROM start] [TO finish] [BN stepsize]
block
ENDDO
each time the loop is cycled, the value
of counter is tested to determine
whether the loop should be continued
or left. See also BREAK and SKIP.
DO counter INDexes (or INDices) arrayname
block
ENDDO
sets counter to each index of a
named array variable in turn
DO counter VALues arrayname
block
ENDDO
sets counter to the value stored in
each element of an array variable in
turn (the iterations being carried out in
the order determined by the indexes of
the elements)
DO variable-name LIST uuname
block
ENDDO
sets variable-name to the value of all
currently selected elements in the
multiple choice list uunname in turn
DO variable-name PANE uuname
block
ENDDO
sets variable-name to the value of all
currently selected lines in the text pane
uunname in turn
BREAK [IF logical]
within block of a DO construct. Leaves
DO loop if logical is true.
SKIP [IF logical]
within block of a DO construct. Aborts
current iteration if logical proves true.
If no logical, immediately starts next
iteration with counter updated.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10-13
IF....THEN Constructs
IF logicall THEN
blockl
ELSEIF logical THEN
block2
where each logical is a logical
expression and each block is a sequence
of valid program commands.
Any block may contain further
IF... ENDIF conditional sequences,
allowing you to nest conditional
(HANDLE calls etc.; see Chapter 9)
does not exceed 20.
ELSEIF logicaln THEN
blockn
ELSE
block_default
ENDIF
HANDLE Constructs (Specified Errors)
where programyommand is a macro
command line within which specific
errors are foreseen and each errorspec
specifies a set of errors to be handled by
the block of commands which follows it.
programyommand
HANDLE <errorspecl>
blockl
ELSEHANDLE <errorspec2>
block2
ELSEHANDLE <errorspec3>
block3
ENDHANDLE
The form of errorspec may be any combination of the following:
•
•
•
•
One or more program error numbers, e.g. (41,8), such as are output at the start of error
messages sent to the screen. (For a listing of the corresponding message texts, see the
Reference Manual for the relevant program.)
One or more special error numbers which have been defined in the macro, e.g. 1 (see Section
8.5).
The command word NONE, meaning that the associated block is to be executed when no error
has occurred in executing program_command.
The command word ANY, meaning that the associated block is to be executed when any error
has occurred in executing program_command.
10-14
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Effect
Command
JUMP Constructs
LABEL name
identify a specific point in a macro
GOLABEL name [IF logical]
go to named label if logical true
ONERROR Constructs (Unspecified Errors)
ONERROR GOLABEL name
where name must correspond to an
existing label.
ONERROR CONTINUE
continues running of macro
ONERROR PAUSE
pauses macro
ONERROR RETURN
stops macro
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
10-15
10.7 File Handling
Command
Effect
OPENFILE filename mode file-token
opens a file, where filename is the
pathname of the file, mode defines the
type of operation which you will be able
to carry out on the open file, and
filejoken specifies the named variable
which will be set to the file token value
when the file is opened.
The choices of mode are as follows:
READ
allows the file’s contents to be read but
not modified.
WRITE
allows you to write data to a new file.
The named file must not exist already.
APPEND
Allows you to write data after the
existing contents (if any) of the named
file. If the file does not yet exist, the
data will be appended to the null
contents of a new file (that is, the same
effect as for the WRITE option).
OVERWrite
allows you to write data to an existing
file in such a way that it overwrites the
original contents of that file. The
original contents are deleted when the
file is opened.
The maximum number of files which may be open
simultaneously is 10.
WRITEFILE filejoken text
writes data to an open file
READFILE filejoken named jariable
reads a record from an open file
CLOSEFILE filejoken [KEEP or DELETE]
closes a file
Query OPENFiles
tells you which files are currently open
10-16
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
10.8 PDMS Pseudo-attributes
The following pseudo attributes are allowed in expressions:
All element types:
’NAMN’ or ’NAM/E NOPREF’
Text
FLNM’ or ’FULLNAME’
’FULLT/YPE’
’SEQ/UENCE’ or ’ORDER’
’LIS/T’
’OLIS/T’
’HLIS/T’
’QUAN/TITY’
’DBNU/MBER’
’MCOU/NT’ noun
Text
Treename, e.g. ’’BOX 1 OF /PUMP1”.
Word
Similar to TYPE, but more than 4 chars.
Integer
Position in member list of owner.
Word(38) Possible types in member list.
Word(200) Possible types of owner.
Word(200) Possible Higher element types in hierarchy.
Integer
Number of elements, currently always 1.
Integer
DB number
Integer
Count of element type in members list. If no
’noun’ is given that the total member list
count is returned.
Integer
Database depth below world (world at 0, Site
at 1 etc)
’DDEP/TH’
Name without prefix (preceding
Most DESI element types:
’E/AST’ or ’X’
’W/EST’
’N/ORTH’ or Y’
’S/OUTH’
’U/P’ or Z’
’D/OWN’
’DDES/PARAM’
Real
Real
Real
Real
Real
Real
Real(50)
WVOL
Real(6)
East/X component of position.
West component of position.
North/Y component of position.
South component of position.
Up/Z component of position.
Down component of position.
Return desparam as a distance, converted to
local units
World volume
DESI elements with a catalogue or spec, ref.:
’STYP/E’
’CAT/REFERENCE’
’SPR/EFERENCE’
’PAR/AM’
’IPAR/AM’
’TPAR/AM’
’PTRE/FERENCE’
’GMRE/FERENCE’
DTRE/FERENCE’
’MTXR/EFERENCE’
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Word
Ref
Ref
Real(30)
Real(30)
Real(30)
Ref
Ref
Ref
Ref
Spec answer for STYPE. question .
Catalogue reference.
Spec. ref.
Parameters of the catalogue component.
Parameters of the insulation cat.comp.
Parameters of the tracing cat. comp.
Point set ref.
Geometry set ref.
Data set ref.
Material text ref.
CADCENTRE
Protected by copyright: see frontispiece
10-17
’MTXX’
Text
Material XTEXT.
’MTYX’
Text
Material YTEXT.
’MTZX’
Text
Material ZTEXT.
’DETR/EFERENCE’
Ref
Detail text ref.
DTXR’
Text
Detail RTEXT.
Text
Detail STEXT.
’DTXS’
’DTXT’
Text
Detail TTEXT.
’ISPR/E’
Ref
Insulation spec, component ref.
’ICA/TREFERENCE’
Ref
Insulation cat. component ref.
’IDE/TAIE
Ref
Insulation detail text ref.
’IDRT’
Text
Insulation detail RTEXT.
’IDST’
Text
Insulation detail STEXT.
’IDTT’
Text
Insulation detail TTEXT.
’IMAT’
Ref
Insulation material text ref.
IMXT’
Text
Insulation material XTEXT.
IMYT’
Text
Insulation material YTEXT.
’IMZT’
Text
Insulation material ZTEXT.
’TSPR/E’
Ref
Tracing spec, component ref.
’TCA/TREFERENCE’
Ref
Tracing cat. component ref.
’TDE/TAIL’
Ref
Tracing detail text ref.
’TDRT’
Text
Tracing detail RTEXT.
’TDST’
Text
Tracing detail STEXT.
’TDTT’
Text
Tracing detail TTEXT.
’TMAT’
Ref
Tracing material text ref.
’TMXT’
Text
Tracing material XTEXT.
’TMYT’
Text
Tracing material YTEXT.
Tracing material ZTEXT.
’TMZT’
Text
’PROP/ERTY word’
text
Data set property value for ’word’
Query property purpose
text
’PRPU word’
Query property title
’PRTI word’
text
Query property description
’PRDES word’
text
’PRLS’
word(100) List of data set properties for element
’MAXB/ORE’
Real
Maximum bore for all ppoints
’P/POINT <n> BOR/E’ or ’PPBOR/E <n>’
Real
Bore at P— point <n>.
’P/POINT <n> CON/NECTION’ or ’PPCO/NN <n>’
Connection type at P— point <n>.
Word
’P/POINT <n> POS/ITION’ or ’PP/OSITION <n>’
Position at P— point <n>.
Pos
’P/POINT <n> DIR/ECTION’ or ’PDI/RECTION <n>’
Dir
Direction at P— point <n>.
’P/POINT <n> GRAD/IENT’ or ’PGRAD <n>’
Real
Gradient at P— point <n>.
’P/POINT <n> BOP’ or ’PBOP <n> ’
Position of bottom of pipe at P— point <n>
Pos
10-18
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
’P/POINT <n> TOP’ or ’PTOP<n>’
Pos
’P/POINT <n> OD’ or’POD <n>’ Real
’PPLIST’
Real
’PPSKEY <n>’ or ’P/POINT<n> PSKEY’
word
’PPURP <n>’ or ’P <n> PURP’
word
’PDESC <n>’ or ’P <n> DESC’
text
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Posn. of top of pipe at P— point <n>.
Outside diameter at P— point <n>.
For list of valid ppoint numbers
ppoint <n> Pskey
ppoint <n> Purpose
ppoint <n> description
CADCENTRE
Protected by copyright: see frontispiece
10-19
Part II
User Interface Customisation
11
Introducing GUI Customisation
11.1
What It Means
The CADCentre products graphical user interface (GUI) enables you to carry out tasks by
selecting functions from menus displayed on your screen, and by entering data into forms.
Whatever is selected from a menu or entered into a form is then translated into appropriate
software commands and acted upon by the system’s command processor. This means that the user
does not have to remember any complex commands and their syntax.
The software supplied to you will incorporate all the menus and forms needed for general use of
the applications. Instructions for using the application through the standard interface are given in
the relevant Application User Guides and the online help.
However, you may find that the standard GUI for an application does not do quite what you want it
to do, or you may feel the need to include specially designed functions, unique to your system, into
the interface.
This manual tells you how to customise the graphical user interface of your applications to meet
your precise working needs. You can create new forms and menus which, when chosen, activate
processes within the application specified by you.
11.2
Before You Start
Before you begin to customise your application’s GUI, you must be an experienced user with a
good understanding of the underlying principles behind the applications. You must also have a
good understanding of the command syntax for the application, as described in the application’s
Reference Guide.
Menus and forms carry out actions by running macros. While some experience of writing macros,
preferably with an understanding of the Programmable Macro Language (PML), would be an
advantage, the macro commands which relate to menu and form creation can be relatively simple,
prior experience is not essential for understanding this manual. However, you should study Part I
Macros and Programmable Macros carefully before you start work.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
11-1
Introducing GUI Customisation
11.3
How Part II Is Set Out
Part II is organised in the following way:
•
Chapter 12 summarises the main features of the graphical user interface. For a more detailed
introduction, see an appropriate Application User Guide.
•
Chapter 13 defines the rules which apply to the naming of forms and gadgets.
•
Chapter 14 explains how you create and design new forms.
•
Chapter 15 tells you how to add horizontal menu bars and vertical pull-down menus to your
forms.
•
Chapter 16 explains the features of the various types of form gadget and tells you how to
incorporate the gadgets into your form design.
•
Chapter 17 explains how you can control the ways in which forms are displayed during a
working session. It also explains the ways in which data may be stored in, and read back from,
the various types of gadget by using form variables.
•
Chapter 18 gives you some general hints on how to design a user interface which is both
efficient and easy to use.
•
Chapter 19 gives some examples of typical menus and forms and of the macro files used to
define them.
•
Chapter 20 summarises the main conventions followed in the compilation of macros. This
information will allow you to maintain maximum compatibility between your customised
macros and the standard ones.
•
Chapter 21 is the Command Reference Section. This summarises all the commands you will
need when customising your application’s interface.
11-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
12
A Summary of the Graphical User Interface
This chapter summarises those features of the graphical user interface (GUI) with which you
should be familiar before you attempt to define your own version. It introduces most of the
GUI-specific terminology (shown in bold typeface) used throughout the rest of the manual.
12.1
The Menus and Forms Structure
The entire user interface which you see on your screen is made up of a number of forms. Each form
occupies a screen window, which has its own control menu for popping, pushing, moving, etc, as
defined by the window manager of the workstation on which you are running your applications.
Each form may own a menu bar, comprising a horizontal list of options across the top of the form.
Each of these options identifies a pull-down menu, which is displayed vertically below the menu
bar when the option is selected with the mouse. When selected, each field in a pull-down menu
carries out one of the following functions:
•
If the field contains plain text only, it executes a command.
•
If the field text ends with an ellipsis (three dots), thus: Drawlist... , it opens (by
convention) another form on which you may enter detailed command options.
•
If the field ends with a triangular pointer, thus:
Create
r
, it displays a lower level
submenu.
The following illustration shows a typical sequence of menu bar, pull-down menu and submenu:
Menu bar
System
Design
Display
Model
Query
Goto
Options
Create
Representation...
Pull-down menu
Limits
CE
Drawlist...
Owner
Grid...
Members...
Colour
Explicit...
Submenu
File
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
12-1
A Summary of the Graphical User Interface
In practice, it is best if only a minimum number of forms contain a menu bar (since too many
separate menus can make the interface complicated to use). However, the form displayed in the
default main window, which appears automatically when you first enter an application, always
incorporates a menu bar giving access to some general system functions. This form cannot be
closed while you remain working in the session, although you may change its content and layout if
you wish.
If the amount of data needed to fully specify a complex command is too great to enter sensibly on a
single form, a subsidiary child form may be used to handle the excess input. Such a child form will
only be displayed as a result of a selection from the main parent form, and the command eventually
sent to the application can combine the settings from both forms.
Forms are of two basic types:
•
Blocking forms demand immediate attention, so that you must take whatever action the form
requires (or cancel the form) before you can do anything else.
•
Non-blocking forms remain displayed, so that you can modify them as and when you wish,
until they are either cancelled or removed automatically by the application.
The two types are usually distinguishable on screen by being displayed in different colours
(typically grey for blocking forms and blue for non-blocking forms).
12.2
Form Gadgets
When a form is displayed, you may enter further instructions by using the interactive gadgets
incorporated into the form’s layout. These gadgets are used to obtain information which is needed
to complete the command which was initiated by the preceding menu selection(s). The various
types of gadget available are designed to allow for the input of different types of information: to
enter textual or numeric data; to control application states; or to select application command
functions. When you are satisfied with the gadget settings, you may send the corresponding
instructions for processing. If you change your mind, you may either cancel the form without
further effect, or you may (in some cases) return the gadgets to the settings which they had when
the form was first opened.
Most gadgets may have an associated callback string. This callback string may be either a direct
command or a call to run a macro (which may, in turn, set values in other forms if required). When
such a gadget has its setting changed interactively on a displayed form, its callback string is
executed.
Data stored in gadgets may be set or read at any time, regardless of whether the form is being
displayed, by using form variables.
The principal types of gadget which you will encounter are:
•
Button gadgets (also known as control buttons) — These do not store data settings, but
either send an immediate command or display a subsidiary child form. Button gadgets look
like this:
12-2
Cancel
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
A Summary of the Graphical User Interface
Text entry field gadgets (also known as text-entry boxes or text-boxes) — These allow you to
type in alphanumeric data. Text entry field gadgets look like this:
Title IPDMS 3D View|
Text pane gadgets — These are similar to text entry gadgets, but they also allow you to type in a
number of lines of alphanumeric data into a field.
Toggle gadgets (also known as toggle buttons) — These allow you to choose between two
settings (On/Off). Toggle gadgets may be set independently of each other. They look like
this:
r
On
J
Off
Radio group gadgets (also known as radio buttons) — These, which are variants of toggle
gadgets, also allow you to choose between two settings (On/Off). However, radio group
gadgets are mutually exclusive, in that they allow only one of the group to be On at any time:
setting one of the group to On sets all others to Off automatically. Radio group gadgets look
like this:
On
Off
List gadgets (also known as scrollable lists) — These hold a set of display texts from which
you may select one (or, in some cases, more than one) option. Each display text is linked to a
corresponding replacement text which forms the gadget’s setting. Scroll bars are
incorporated into list gadgets to enable long lists to be accommodated. List gadgets look like
this:
100.00
125.00
150.00
175.00
200.00
Selector gadgets — These are a special case of the list gadget, normally used to display a list
of elements in the current DB. They can show just the elements at the current level in the DB
hierarchy, or they may also show the Members and/or Owner of the current element. The
display may be updated automatically as you navigate about the DB.
Option gadgets (also known as list buttons) — These are compact forms of single-choice
lists. Only one option field is normally visible, showing the current selection. When the gadget
is picked with the mouse, the full list of options is displayed. When a new choice has been
selected, the list disappears and the new selection is shown on the gadget. Option gadgets look
like this:
Grey
Paragraph gadgets (also known as labels) — These are passive gadgets which allow you to
display alphanumeric text strings or pixmaps on forms. They are mainly used to add clarifying
text to forms, making it easier for you to know what data to enter where.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
12-3
A Summary of the Graphical User Interface
Userdata facilities — Not strictly gadgets in the same sense as the others, since they are
never displayed, userdata facilities may be used to hold lists of text strings associated with
individual forms. These strings may be written to or read from by your macros, using form
variables . They allow you to associate hidden data settings with a form, so that they cannot be
directly modified by the user.
12.3
View Gadgets
View gadgets, although strictly speaking another type of form gadget, behave somewhat differently
from the types of interactive gadget listed in Section 12.2. View gadgets have only very restricted
user-input functions. They are used primarily for displaying alphanumeric or graphical output.
(Their main input function is for picking elements in interactive graphical views, allowing you to
navigate around the database.)
The available types of view gadget are as follows:
•
Alpha views — These display scrollable alphanumeric text, showing either input commands
and any resulting error messages or the outputs resulting from queries.
•
Volume views — If your software is capable of this feature (particularly PDMS and Review),
these display one or more interactive 3D graphical views of the design model, so that you may
see the effects of your commands immediately.
•
Area views — These display interactive 2D graphical views in the DRAFT module.
•
Plot views — These display passive 2D graphical views. They are used for displaying existing
plot files.
•
Pixmap views — These display bit-mapped images which have been generated in
independent drawing packages. They are typically used to display logos or other icons.
NOTE: Because of problems with software packages that create pixmaps, using a Pixmap view
could cause you problems when you come to edit it in the future. CADCentre
recommends that you use Paragraph gadgets for incorporating pixmaps, rather than
Pixmap views.
12-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
A Summary of the Graphical User Interface
12.4
Alert Forms
Alert forms (usually abbreviated to alerts) are special types of forms with predefined formats.
They are used for passing information from the application to the user, usually advising of actual or
potential problems.
The available types of alert are as follows:
•
Error alerts — These are blocking forms which tell you that an error has occurred. You must
acknowledge the error message before you can do anything else.
•
Confirmation alerts — These are blocking forms which ask you to confirm a potentially
dangerous command (such as deletion of an element from a database). You must confirm or
cancel the command before you can do anything else.
•
Prompt alerts — These are non-blocking forms which remind you that the application
expects you to take a particular action as a result of a preceding command. As an example, if
you specify an operation on a displayed element which you have opted to identify using the
cursor, a prompt alert will remind you to pick a suitable element.
12.5
Loading the User Interface
Your user interface is loaded via initialisation macros for your application. These are located in the
ADMIN directory for your application. The ADMIN directory for each module area contains the
following three files:
•
START — An ‘intelligent’ start-up macro which determines what types of relevant files are
accessible and uses them to load the application macros in the most efficient manner.
•
USETUP — A file which holds user-configurable settings.
•
VARS — A file which defines global synonyms and global variables.
To load the graphical user interface for any given application, you must run the START macro for
the corresponding module. For example, to load the PDMS DESIGN module’s graphical user
interface, enter the command
$M /%PDMSUI%/DES/ADMIN/START
To load the interface automatically when a module is first entered, include the command to run
START in the module’s initialisation macro. For example, to load the graphical user interface
when you enter DRAFT, edit (in ADMIN) the DRAFT initialisation macro thus:
EDIT MODULE DRAFT I /%PDMSUI%/DRA/ADMIN/START
When run, START initiates the USETUP and VARS macros to set up the configuration
parameters. It looks for compiled, binary files first (as these are quicker to load and run), and then
looks for ASCII definition files. The process is:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
12-5
A Summary of the Graphical User Interface
1.
It first looks in the user area for two binary files with names of the formats‘module_user.bin’
and ‘ module_user.disp’. For example, the DRAFT START macro would look for the binary
files DRAFTCSI.bin and DRAFTCSI.disp (for user CSI) from which to load a previously
saved form definition and screen layout.
2.
If no appropriate files were found in Step 1, START next looks in the defaults directory for a
binary file with a name of the format 'module .bin’. For example, the DRAFT START macro
would look for the binary file DRAFT.bin.
3.
If no appropriate file was found in Step 2, START loads the form and menu definitions by
running the INIT macro file for the relevant application. This process is considerably
slower than loading from binary files (as in Step 1 or 2).
12.6
General Start-Up Applications
There are a number of generalised applications you can start up (typically from an applications
START macro) that are useful when running a Forms and Menus system.
12.6.1
FMINFO Command
The FMINFO command gives you the ability to supply general information about the application
and detailed instructions about its use.
The general information concerns the applications version number, and can be started up in the
following syntax:
FMINFO APPWARE |Version 10.4.1|
Together with this information, all CADCentre Applications are able to access on-line help. You
can write and access on-line help for your own, customised forms and menus.
Users can access the help system via one of two methods:
•
Help buttons — These buttons can be included on each form. Associated with the button is
help text relevant to the owning form. This allows the user to display information relevant to
their current operation immediately.
•
Help menus — A help menu gives you the user a set of options, and allows them to access all
the features of the help system.
The features that are available when you are designing on-line help will depend on the help
system you are using. However, the files you need to reference are accessed by the FMINFO
command, in the syntax:
FMINFO \AE\-P filename Xrefname
12-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
A Summary of the Graphical User Interface
Where:
filename
is the name of the application help file needed by your help
system. This is the file that holds the help text
Xrefname
name of the application cross-reference file needed to link
form and gadget names to specific help texts
Information on these files, and how the cross-references work between help text and the help
system, can be found in the instruction guides for your help system.
12.6.2
SWAP Command
You can define which form is to be the application’s main form by the SWAP command:
SWAP MAINform TO uname
Where:
uname
CADCENTRE Software Customisation
Reference Guide
Issue 1095
is the name of the form that is to be the main form for the
application
CADCENTRE
Protected by copyright: see frontispiece
12-7
13
Naming Forms, Menus and Gadgets
The names used to identify forms, menus and gadgets are made up of alphanumeric strings called
uname atoms. A uname must consist of an underscore character, followed by a letter, followed by
up to 15 further characters which may include any combination of letters, digits, commas and full
stops.
Examples of valid unames include:
FORMNAME
PIPE.65A4
_STEEL.BEAMS,COLS
Examples of invalid unames include:
/FORMNAME
.FORMNAME
_PIPE:65A4
STEEL.BEAMS,COLUMNS
(first character must be an underscore)
(second character must be a letter)
(colon is not a valid character)
(too many characters)
NOTE: Alphabetic characters in unames are not case sensitive on most systems; _formname and
_FORMNAME represent the same uname. Uppercase is used by convention.
A form name always comprises a single uname.
A gadget name or a menu name usually comprises a double uname, known as a uuname. The first
part of the uuname is the uname of the gadget’s ‘owning’ form; the second part is the uname of the
menu or gadget itself.
NOTE: Where the current context makes the form name unambiguous, the first part of the
uuname may be omitted and the menu or gadget may be identified by a single uname.
Examples of valid uunames include:
FORMNAMEGADGETNAME
BRANCH.5A7VALVE3
GADGETNAME
(only valid during form definition, where the uname
of the current form is unambiguous)
Examples of invalid uunames include:
FORMNAME GADGETNAME (space not allowed)
(only two unames allowed)
FORM1FORM2GADGET2
GADGETNAME
(invalid if the context has no ‘current form’ concept)
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
13-1
14
Defining Forms
This chapter tells you how to create and lay out new ‘empty’ forms. Details of how to add menus
and gadgets to the forms are given in Chapters 15 and 16, respectively.
Although a form can be defined interactively, it is usual to store the form definition commands in a
macro so that the form is displayed consistently each time it is opened. Such a macro can define:
•
The type of form (blocking or non-blocking)
•
Whether or not the form is resizeable by the user
•
The form’s initial size and position
•
The title for the form’s banner (shown at the top of the form when displayed normally)
•
The title for the form’s icon (shown when the form is minimised)
•
Administrative text showing the form’s revision status etc.
•
The layout and initial settings of any gadgets included on the form
Each command which you can use for overall form definition is explained in this chapter. The full
syntax of these commands is given in Chapter 21.
14.1
Entering and Leaving Form Setup Mode
You can define forms only while in a special Form Setup mode. To enter this mode, type
SETUP FORM formname
where formname is the form’s uname (see Chapter 13). For example,
SETUP FORM _REPRESENT
To leave Form Setup mode and revert to normal operation, type
EXIT
NOTE: The form definition syntax described in the following sections is available only while you
are in Form Setup mode; that is, between your SETUP FORM and EXIT commands.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
14-1
Defining Forms
14.2
Copying an Existing Form
It is sometimes convenient to use a copy of an existing form as a basis for the design of a new form.
To create such a copy, use the command format
COPY oldform
where oldform is the uname for the form to be used as a template. For example,
SETUP FORM _REPRES2 COPY _REPRES1
would make the new form _REPRES2 a copy of the existing form _REPRES1.
You may then modify the attributes of the new form as required.
1 4.3
Setting the Form’s Attributes
A form has a number of attributes which define its overall appearance and behaviour. These are:
•
•
•
•
Its type; that is, whether it is blocking or non-blocking
Its minimum dimensions
Whether or not it is resizeable by the user
Its position on the screen
The commands which set these attributes form part of the SETUP FORM ... command line.
By default, a newly-created form is of non-blocking type, is not user-resizeable, and has a
predefined position just below the top-centre of the screen.
14.3.1
Specifying the Form’s Type
To change the form’s type to blocking, simply include the command BLOCKING.
(There is no corresponding non-blocking specification, so if you change your mind you must start
the setup procedure again.)
14.3.2
Specifying the Form’s Minimum Dimensions
To specify the minimum size of screen area to be occupied by the form, include the SIZE command,
thus:
... SIZE 25 10
where the two values define the width and height measured in character widths and line heights,
respectively. A form’s size must be at least large enough to incorporate its menu bar (if it has one)
and any gadgets within its layout.
14-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Forms
14.3.3
Specifying a User-Resizeable Form
To specify that the form is to be user-resizeable, include the command RESIZEABLE. The
displayed form will then incorporate 'resize brackets’ in the corners of its borders and will be
resizeable by using the appropriate window manager options.
14.3.4
Specifying the Form’s Screen Position
To define the position of the form on the screen when first opened, include the AT command, thus:
... AT XR 0.25 YR 0.5
to define the coordinates of the top left-hand comer of the form in terms of the screen proportions
(i.e. on scales of 0 - 1 along the X and Y axes).
The default setting, if you do not use the AT command, positions the top centre of the form (not the
top left-hand corner) at the screen coordinates (0.5, 0.15).
NOTE: If the specified size and position would cause part of the form to lie outside the screen
boundaries, the position will be modified automatically so that the whole form will, if
possible, be displayed.
14.3.5
Concluding Form Attribute Setting
The commands described in Sections 14.1 —14.3 define the form as whole; that is, simply as a
rectangular area on the screen. These commands may be listed consecutively, in any order, in the
SETUP FORM ... line in the macro. Before you begin to define the form’s internal content and
layout, you must conclude the attribute-setting sequence with a newline (RETURN) entry.
1 4.4
Giving the Form a Title
To define the title which is to appear in the banner across the top of the form, use the TITLE
command, thus:
TITLE |Representation|
where the title text is enclosed between delimiters (preferably vertical bars) in the usual way.
Should you wish to change the title of a form, you can use the EDIT command to overwrite the
current setting at any time, thus:
EDIT formjiame TITLE newjext
where formname is the form’s uname and newjext defines the new title.
You do not have to enter Form Setup mode in order to edit an existing title.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
n /i o
14-3
Defining Forms
14.5
Specifying a Title for the Form’s Icon
To define the title which is to be displayed against the form’s icon when the form is minimised on
the screen, use the I C O N T I T L E command, thus:
ICONTITLE |REPRES|
This will display the title REPRES against the form’s icon, regardless of the form’s imame and of
the banner title shown when the form is displayed full size (as defined in Section 14.4).
Should you wish to change the form’s icon title, you can use the EDIT command to overwrite the
current setting at any time, thus:
EDIT formjiame I C O N T I T L E new_text
where formname is the form’s uname and newjext defines the new icon title.
You do not have to enter Form Setup mode in order to edit an existing icon title.
14.6
Defining the Form’s Initial Settings
You can specify a callback text for each form, known as the initialisation text, which is to be read
back each time the form is opened. This text, usually a call to run a macro, allows you to introduce
context-dependent checking of the validity of opening the form, to control the initial settings of any
gadgets on the form, and so on.
To specify the initialisation text for a form, use the INITIALISE command, thus:
INITIALISE |$$M /INITMAC2|
where /INITMAC2 is here a macro file containing all the form initialisation commands.
Note that the macro call within the initialisation text begins with a doubling of the ‘$’ character.
This ensures that the returned text begins with a literal ‘$M’, so that /INITMAC2 is run only when
the form is opened (i.e. when the initialisation text is interpreted), rather than when the form
definition macro is being set up. (See Part I Macros And Programmable Macros if you are unsure
about the use of escape characters in macros.)
14.7
Setting Revision Status Text
To store a text string in the form’s REVISION attribute, use the R E V I S I O N command, thus:
REVISION |Version 2.3, 21 December 1994|
Although intended primarily to hold revision data, as a management/documentation aid for macro
source and binary file control, this attribute may be set to any string which you wish to read later for
administrative purposes. The command to read back the attribute setting is
Query FORM uname REVision
14-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Forms
14.8
Example
The following simple macro, which incorporates all of the commands described in this chapter,
defines a form which is blank except for the title banner. In practice this sequence would be
followed by other command lines (where denoted by the ellipsis ...) defining the menu and/or
gadgets to be added to the form.
SETUP FORM _REPRESENT BLOCKING SIZE 25 10 RESIZEABLE AT XR 0.5 YR 0.5
TITLE |Representation|
ICONTITLE |REPRES|
INITIALISE |$$M /INITMAC2|
REVISION |Version 2.3, 21 January 1993|
...
EXIT
$.
The resulting (empty) form would look like this:
This corner at
centre of screen
(0.5, 0.5)
Representation
Title banner
Resize brackets
at corners of
- borders
When iconised, the corresponding icon would have the title REPRES.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
14-5
15
Defining Menus
This chapter tells you how to add horizontal menu bars and/or vertical pull-down menus to your
forms.
Each command which you can use for the menu definitions is explained in this chapter. The full
syntax of these commands is given in Appendix A.
NOTE: The form definition syntax described in this chapter is available only while you are in
Form Setup mode; that is, between your SETUP FORM and EXIT commands. The term
‘current form’ in this chapter means that form whose uname formed part of the SETUP
FORM command line (see Section 14.1). Since all menu definitions apply to the current
form, menus are referenced in this chapter by a uname only, rather than by a full uuname
(see Chapter 13 for details of naming conventions).
15.1
Defining a Menu Bar
A menu bar comprises a horizontal list of texts, immediately below the form’s title banner, each of
which is linked symbolically to a vertical pull-down menu which may be displayed below it.
15.1.1
Entering Menu Bar Setup Mode
To define a menu bar across the top of the current form, you must first enter Menu Bar Setup mode
(from within Form Setup mode). To do so, enter the command BAR.
NOTE: The menu bar does not have any identifying uname, since you can have only one menu bar
per form. Compare this with pull-down menus, which must be named since one form may
contain several such menus.
15.1.2
Adding Menu Bar Options
To add one or more menu bar options to the list, use the ADD command. This has the format
ADD displayJext menujiame
where displayJext defines the text which is to be shown in the menu bar and menujiame is the
uname of the pull-down menu which is to be displayed when this option is picked with the mouse.
The pull-down menu menujiame need not exist when the menu bar is being defined, but it must
exist before the menu bar is displayed, otherwise you will see an error message.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
15-1
Defining Menus
As an example,
ADD |Display| _VIEWSETTINGS
adds the heading ‘Display’ to the menu bar which, when picked using the mouse, displays the
pull-down menu named _VIEWSETTINGS (see Section 15.2.1). The display text and its linked
pull-down menu might appear thus when ‘Display’ is selected within a typical menu bar:
Menu bar
System
Design
Display
Model
Query
Goto
Options
Create
Representation...
Pull-down menu
Limits
(with the uname
Drawlist...
VIEWSETTINGS
Grid...
in this example)
Colour
File
Repeated use of the ADD command builds up the row of menu bar display texts, starting from the
left-hand side of the form, with predefined spaces separating the individual entries.
15.1.3
Adding Help to the Menu Bar
You can add a standard help option to the menu bar using the ADD HELP command:
ADD HELP
This gives a standard help option at the right of your menu bar.
15.1.4
Leaving Menu Bar Setup Mode
To leave Menu Bar Setup mode (but remain in Form Setup mode), enter the command EXIT.
(To leave Form Setup mode as well, repeat the EXIT command.)
15-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Menus
15.2
Defining a Pull-Down Menu
A pull-down menu is, strictly, a specific type of gadget (a menu gadget) within the parent form. It
comprises a vertical list of menu selection fields, each of which is one of the following types:
•
A command field — contains text or pixmap — executes a callback text as soon as it is picked.
•
A form field — contains text followed, conventionally, by an ellipsis — displays a form when
picked.
•
A submenu field — contains text plus a triangular continuation marker — displays a
submenu (a lower level vertical menu) when picked.
•
A separator field — contains some type ofvisual divider, such as a horizontal line — used to
divide the vertical list into logical groups.
15.2.1
Entering Menu Setup Mode
To define a pull-down menu for the current form, you must first enter Menu Setup mode (from
within Form Setup mode). To do so, use the MENU command, thus:
MENU _VIEWSETTINGS
where _VIEWSETTINGS is the uname of the pull-down menu.
15.2.2
Adding Pull-down Menu Fields
To add one or more pull-down menu fields to the list, use the ADD command. The syntax depends
upon the type of field to be added, as explained in the following paragraphs:
►
To add a command field, use the format
ADD displayJext callbackJext
where displayJext defines the text which is to be shown in the menu and callbackJext defines the
command to be executed, or the macro to be run, when the field is picked. For example,
ADD |Abandon Design| |QUIT|
adds the menu field
execution.
►
Abandon Design
which, when picked, sends the command QUIT for
To add a form field, use the format
ADD displayJext FORM uname
where displayJext defines the text which is to be shown in the menu and uname identifies the form
which is to be opened when the field is picked. For example,
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
15-3
Defining Menus
ADD |Representation...| FORM _REPRESENT
adds the menu field
to be displayed.
►
Representation...
which, when picked, causes the form -REPRESENT
To add a submenu field, use the format
ADD displayJext MENU uname
where displayJext defines the text which is to be shown in the menu and uname identifies the
submenu which is to be displayed when the field is picked. For example,
ADD |Limits| MENU _LIMITS
adds the menu field
displayed.
►
Limits
r
which, when picked, causes the submenu _LIMITS to be
To add a separator field, use the format
ADD SEPARATOR
The visual appearance of the separator field is determined automatically by the workstation
system under which you are operating.
15.2.3
Leaving Menu Setup Mode
To leave Menu Setup mode (but remain in Form Setup mode), enter the command EXIT.
(To leave Form Setup mode as well, repeat the EXIT command.)
15.3
Defining a Submenu
You define a submenu in exactly the same way as a pull-down menu, as detailed in Section 15.2.
Pull-down menus and submenus are actually identical types of menu gadget; the only difference is
in the way in which they are called. Pull-down menus are called from menu bar options, while
submenus are called from pull-down menu fields. Any specific menu gadget, identified by a unique
uuname, may be used both as a pull-down menu and as a submenu, depending on the context from
which it is called.
15-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Menus
15.4
Displaying and Using Menus
A menu bar is displayed automatically as part of the form which contains it. When a menu bar
option is picked, it always displays the associated pull-down menu.
A menu gadget (a pull-down menu or a submenu) may be displayed only as a result of being
referenced either from a menu bar or from a submenu field in another menu gadget.
All menu gadgets are blocking inputs, so that when a menu field is selected (highlighted) you are
restricted to the following choices of action:
•
Action the current selection and, if this a command field or a form field, close the menu (by
releasing the mouse button with the selection still highlighted).
•
Change to a different selection in the same menu (by moving the mouse without releasing the
button).
•
Cancel all selections and close the menu (by moving the cursor away from the menu, so that no
fields are highlighted, and then releasing the mouse button).
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
15-5
16
Defining Gadgets
This chapter tells you how to add any of the available types of gadget to your forms (except menu
gadgets, which are explained in Chapter 15). It also tells you how to edit existing view gadgets.
Each command which you can use for gadget definition is explained in this chapter. The full syntax
of these commands is given in Appendix A.
NOTE: The gadget definition syntax described in this chapter is available only while you are in
Form Setup mode; that is, between your SETUP FORM and EXIT commands. The term
‘current form’ in this chapter means that form whose uname formed part of the SETUP
FORM command line (see Section 14.1). Since most gadget definitions apply to the
current form, gadgets are referenced in this chapter by a uname only, rather than by a full
uuname (see Chapter 13 for details of naming conventions).
16.1
Types of Gadget
The principal types of gadget available for you to add to your forms are buttons, text entry fields,
text panes, toggles, radio groups, lists (scrollable lists), selectors (space-separated lists), options
(list buttons), paragraphs, and the various types of view. See Chapter 12 for a summary of their
characteristics.
The commands for specifying tags, callback strings and positions for gadgets are explained first in
the following sections, since these apply to most types of newly created gadget. The later sections
explain the specification of individual types of gadget.
16.2
Gadget Tags or Pixmaps
Most types of gadget may have an optional tag associated with them. Such a tag is displayed on, or
next to, the gadget when its parent form is opened, and serves to identify the gadget’s purpose when
the form is being completed. It has no link with the current setting of the gadget, which is stored
independently by using a form variable.
Alternatively, you can associate a picture (known as a pixmap) with most gadgets to indicate its
purpose. With most gadgets you must also specify the required maximum size of the pixmap in
pixels. If you don’t specify a size, a default of 32x32 pixels is assumed.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-1
Defining Gadgets
NOTE: Beware of using a lot of pixmaps in your applications, as they take up large amounts of
storage space.
To define a tag, simply append the tag text to the appropriate gadget-creation command (as
described in Sections 16.4—16.16). For example, the command
TOGGLE _TOGGLENAME |Border|
adds a toggle gadget thus:
Border
To define a button pixmap:
BUTTON _BUTTONNAME BUTTONPIX WIDTH 26 HEIGHT 26
adds a button gadget with the BUTTONPIX pixmap at 26x26 pixels.
16.3
Gadget Callback Strings
You can associate a callback string with most types of gadget. When such a gadget on a displayed
form is accessed and its setting is changed, its callback string is executed immediately. The callback
string is usually either a single command or a call to run a macro. Such a macro, which can
incorporate any standard command syntax (including PML commands — see Part I Macros and
Programmable Macros), may read or set data in other form gadgets, thus allowing a high degree of
context-specific interdependence between gadgets.
To define a callback string, append to the appropriate gadget-creation command (as described in
Sections 16.4-16.16) a CALLBACK command giving the required text string. For example,
TOGGLE _TOGGLENAME CALLBACK |$$M /TOG1.MAC|
Note that the macro call begins with a doubling of the tf$’ character. This ensures that the returned
text string begins with a literal ‘$M’, so that /TOG1.MAC is run only when the gadget is selected
(i.e. when the callback string is interpreted), rather than when the gadget is being defined.
16.4
Positioning Gadgets Within Forms
16.4.1
The Form Layout Grid
You specify the positions of gadgets on a form by reference to an imaginary grid. This grid, which
has its origin at the top left-hand corner of the form, has a horizontal pitch of one character width
and a vertical pitch of one line height (the precise dimensions which correspond to these are
dependent on your workstation).
16-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
0
1
2
3
4
5
6
7
0 1 2 3 4 5 6 7 8 9 — X
1 character width per unit
1 line height per unit
Y|
The position of each gadget is defined in terms of the gadget origin, which is the top left-hand comer
of the area assigned to the gadget. This point depends on the design of the gadget, and may not
correspond exactly to a corner of the displayed gadget. For example, the origin of a radio group
gadget is at the corner of the enclosing square, thus:
origin
solid outline = displayed radio group gadget
broken outline = area assigned to gadget
When you are designing a form, you may specify the position of each new gadget either absolutely,
in terms of its grid coordinates, or relative to the position of an existing gadget. You may specify the
relative positions of gadgets in one of two ways:
•
By specifying the alignment of each new gadget relative to one of the extremities of an existing
gadget.
•
By defining a path direction (the direction in which consecutive gadgets are to be positioned)
and a separation distance (the horizontal or vertical spacing between the origins of adjacent
gadgets).
In practice, you will probably find it best to position the first gadget absolutely (usually at the
form’s origin) and to then position subsequent gadgets relative to one another.
NOTE: You may position gadgets anywhere on the grid, not only at the grid intersection points.
16.4.2
Positioning Gadgets Absolutely
To specify the origin of a newly created gadget at an absolute position on the form, append to the
appropriate gadget-creation command (as described in Sections 16.4—16.16) an AT command
giving the grid coordinates. For example, any of the commands
TOGGLE _TOGGLENAME AT 3 3.5
TOGGLE _TOGGLENAME AT X 3 Y 3.5
TOGGLE _TOGGLENAME AT Y 3.5 X 3
positions a new toggle gadget with its origin at grid coordinates (3, 3.5), thus:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-3
Defining Gadgets
Q0
1 2 3 4 5 6 7 8 9 -> X
1 ------------------------------------2 ------------------------------------------------------3 ---------4 ----------------------5 ------------------6 ----------------7 ---------------------
p_
1-
16.4.3
Specifying Relative Alignment of Gadgets
The area of the form occupied by an existing gadget may be referenced in terms of its horizontal
and vertical extremities. These are identified by the coordinates XMIN, XMAX, YMIN, and
YMAX thus:
() 0
l 2 3 4 5 6 7 8 9 -► X
YMIN
1
2
3
4
5
YMAX
XMIN
XMAX
To specify the origin of a new gadget relative to an extremity of an existing gadget, append to the
appropriate gadget-creation command (as described in Sections 16.4—16.16) an AT command
giving any required offset, as shown in the following examples.
Example 1 :
TOGGLE _TOGGLENAME AT XMIN YMAX+1
aligns the new toggle gadget with respect to the extremities of the previously-created gadget (since
no uname is specified in the AT command). The new gadget’s origin is at the coordinates (XMIN,
YMAX+1), thus:
() 0
1 2 3 4 5 6 7 8 9 -► X
1
2
3
4
5
6
previously-created gadget used as reference
YMAX
YMAX+1
Y|
XMIN
16-4
new _togglename gadget
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
Example 2:
TOGGLE _TOGGLENAME AT XMIN_GADGET1 YMAX_GADGET1+1
aligns the new toggle with respect to the extremities of GADGETl. The effect is similar to that
illustrated in Example 1, except that _GADGET1 can have been created at any time before
_TOGGLENAME, not necessarily immediately before it.
Example 3:
TOGGLE _TOGGLENAME AT XMIN_GADGET1–2 YMAX_GADGET1+1
aligns the new toggle to the left of GADGETl (since the specified X offset is negative), thus:
Q0
1 2 3 4 5 6 7 8 9 — X
1
2
3
4
5
6
XMIN-2 XMIN
---------- existing gadget used as reference
YMAX
YMAX+1
new _togglename gadget
You may extend this principle further by specifying different reference gadgets for the X and Y
alignments within a single command; for example,
TOGGLE _TOGGLENAME AT XMAX_GADGET1 YMAX_GADGET2
NOTE: The new gadget need not be adjacent to the referenced gadget(s). The same rules apply
even if there are other gadgets positioned between them. You will probably find form
design easier, however, if you add gadgets in two directions only (right and down, say),
rather than in a more random order.
You can also position a new gadget relative to the current size of the form (FORM), and the
current size of the gadget (SIZE). This means that you can right align gadgets to any desired point
on the form.
For example, if you to place an OK button at the extreme righthand, bottom corner of the form, you
would use the commands:
BUTTON_OK AT XMAXFORM–SIZE YMAXFORM–SIZE OK
This refers to the XMAX and YMAX coordinates for the entire form so far, and calculates the
gadget position by subtracting its current size from these coordinates. The result would be:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-5
Defining Gadgets
0
1
2
3
4
5
6
7
0123456789
B U T T O N O K gadget
16.4.4
Positioning Gadgets on a Defined Path
When adding a sequence of gadgets to a form, you may position each new gadget automatically by
predefining its location relative to the preceding gadget. You do this by setting the following
options:
•
•
•
The direction along which new gadgets are to be added, known as the gadget path.
The distance between adjacent gadgets.
The alignment of the edges of adjacent gadgets.
► To specify the direction along which gadgets are to be added, use one of the following PATH
commands:
PATH RIGHT
PATH LEFT
PATH UP
PATH DOWN
The path direction thus set remains in force (as the current path) until you override it with a
different PATH command. The default path direction is Right.
► To specify the horizontal and vertical distance between the closest sides of adjacent gadgets,
use the HDISTANCE and VDISTANCE commands, respectively. For example,
HDISTANCE 4
VDISTANCE 2
where the clearance distances are specified in grid units. The default, if no clearance distance is
specified, gives a small separation which is dependent on your workstation.
Note that these specify clearance distances between gadgets (for example, the distance between the
XMAX of one gadget and the XMIN of the next), not the distance between gadget origins, thus:
GADG2
GADG1
HDISTANCE
VDISTANCE
GADG3
16-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
► To specify horizontal and vertical alignments of adjacent gadgets, use the HALIGN and
VALIGN commands, respectively. The options are:
HALIGN LEFT
HALIGN RIGHT
VALIGN TOP
VALIGN BOTTOM
The defaults are HALIGN LEFT and VALIGN TOP.
The precise position of a new gadget relative to the preceding one is determined by a combination
of the current path, clearance distances and alignments. For horizontal paths (Left or Right), the
horizontal distance and vertical alignment apply; for vertical paths (Up or Down), the vertical
distance and horizontal alignment apply.
The following diagram shows the effects of all possible combinations of path and alignment
settings (with a fixed clearance distance D in each direction):
VALIGN BOTTOM
VALIGN TOP
PATH RIGHT
D
last
next
next
last
C
PATH LEFT
last
next
next
last
HALIGN LEFT
last
PATH DOWN
HALIGN RIGHT
last
D
D
PATH UP
next
next
next
next
D
D
last
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
last
16-7
Defining Gadgets
Combinations of path, distance and alignment commands allow you to set up correctly aligned
rows and columns of gadgets without the need to calculate any grid coordinates. For example, the
command sequence:
TOGGLE _TOG1 AT 0 0
PATH DOWN
VDIST 1
TOGGLE _TOG2
PATH RIGHT
HDIST 3
TOGGLE _TOG3
TOGGLE _TOG4 AT XMIN_TOG2 YMAX+2
TOGGLE _TOG5
gives the following layout of toggle gadgets:
TOG1 has its origin specifically positioned at (0,0)
TOG1
TOG2
TOG4
_TOG3
_TOG5
_TOG2 defined by Path Down/VDist 1 wrt _TOG1
_TOG3 defined by Path Right/HDist 3 wrt _TOG2
_TOG4 has its origin aligned with XMIN of
_TOG2 and offset by 2 from YMAX of
_TOG3 (since ref. defaults to previous gadget if
uname omitted)
TOG5 defined by Path Right/HDist 3 wrt _TOG4
(since these are still the current settings)
(Alignment commands are not needed here, since all the toggle gadgets are the same size.)
16.5
Button Gadgets
Button gadgets (or control buttons) are named, interactive gadgets which, when selected, may
generate a callback string and/or display a child form. They do not have any values associated with
them. The tag for a button gadget is displayed within the rectangular button’s area.
Button gadgets may either act independently, simply returning their callback strings each time
they are selected, or they may act on the form as a whole, when they are referred to as control
buttons.
16.5.1
►
Defining Standard Buttons
To define a new button gadget, use the BUTTON uname command.
► To specify a tag, pixmap, callback string or position for the gadget, extend the BUTTON
command as explained in Sections 16.2, 16.3 and 16.4, respectively. If no tag or pixmap is specified,
the gadget name is used by default.
16-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
► To specify the name of a child form which is to be opened when the button gadget is selected,
append the command FORM uname to the BUTTON command line.
As an example, the command
BUTTON
_MOD |Modify| CALLBACK |$$M /UPDATE.MAC| FORM _MODS
creates a button labelled with the text ‘Modify’. When selected, the child form _MODS is
displayed, allowing you to enter subsidiary data, and the callback string causes the macro
/UPDATE.MAC to be run.
16.5.2
Defining Control Buttons
You may set an optional form control attribute for a button gadget, which is actioned before the
callback string is sent. Such attributes, each of which may be assigned to only one button (except for
APPLY, which can be assigned to a number of buttons) on the form, affect the form as a whole. The
effects of these attributes are as follows:
•
The OK attribute confirms that the content of the form (and any child form), as defined by the
current settings of all gadgets, is acceptable. When a gadget with this attribute is selected, the
form (and any child form) is removed from the display and the callback string is sent.
•
The APPLY attribute works in the same fashion as the OK attribute, in that it confirms the
contents of the form as defined by the current settings of all gadgets. However, when APPLY is
actioned the form remains displayed on the screen. The APPLY attribute also alters the action
of RESET (see below).
•
The RESET attribute causes all gadget values on the form (but not on any child forms) to be
reset to the values they had when the form was displayed (i.e. after the initialisation macro was
run; see Section 12.5), unless an APPLY has been actioned to confirm the values (in which case
RESET will restore the values to their state at the last APPLY). The callback string allows you
to return the application to their original state, if necessary reversing any actions caused by
other gadget callbacks since the form was displayed or the last APPLY.
•
The CANCEL attribute shows that the content of the form (and any child form) is not
acceptable. When a gadget with this attribute is selected, all gadget values on the form are
reset to the values they had when the form was displayed (i.e. after the initialisation macro was
run; see Section 12.5), or when APPLY was last used. The form (and any child form) is
removed from the display. The callback string allows you to return the application to the state
it was at when the form was displayed, if necessary reversing any actions caused by other
gadget callbacks since the form was displayed.
•
The HELP attribute causes the button to become a help button with the label ’Help’. When
clicked, this will action the on-line help system (see Section 12.6.1)
►
To assign a form control attribute to a button gadget, append one of the commands OK,
APPLY, RESET, HELP or CANCEL to the BUTTON command line. (Remember that, apart from
APPLY, you may only have one button with each attribute on any given form.)
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-9
Defining Gadgets
You will usually, but not necessarily, give the button gadget a tag which matches its form control
attribute. Thus a button with an OK attribute assigned to it might be defined by the command
BUTTON _OK |OK| CALLBACK |$$M /READ.MAC| OK
where
is the gadget’s uname,
defines the label which appears on the button, and the final
OK assigns the form control attribute.
16.5.3
Defining Dismiss Buttons for Retained Forms
The control button Apply is used on forms that are to remain on the screen after their contents have
been confirmed. In this case the standard convention is to assign a Dismiss button to remove the
form from the display.
►
To define a Dismiss button, use a definition command of the format
BUTTON _DISMISS |Dismiss| CANCEL
Note that this definition does not specify a callback string, so that, when the button is selected, the
only effect (due to the CANCEL attribute) is to remove the form from the display. The settings
which resulted from the last use of the Apply button remain in force.
16.6
Text Entry Field Gadgets
Text entry field gadgets (or text-boxes) are named, interactive, single-valued gadgets. The gadget’s
value is entered (as a text string) by typing in the required data from the keyboard and is displayed
within the rectangular area of the gadget. The data thus entered is validated only when the Return
key is pressed, allowing entries to be edited as necessary. The tag, if any, for a text entry field gadget
is displayed immediately to the left of the text field.
When defining a text entry field gadget, you must specify the field width to be displayed for the text
field (as a number of characters) and the field type (which determines how the input text string is to
be interpreted as a value). You may also, optionally, specify the maximum scrollable length of the
text string which can be entered into the gadget, such that the field width acts as a scrollable
‘window’ along this length.
► To define a new text entry field gadget, use the TEXT uname command, including the
maximum field width and specific field type and, optionally, the maximum scrollable length. For
example:
TEXT _DATA WIDTH 12 SCROLL 48 STRING Interprets data as a literal text string.
Accepts any printing characters.
Displays 12 characters at a time from a
scrollable length of 48 characters.
j ~
TO
1U
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
TEXT _NAME WIDTH 10 NAME
Interprets data as a Name.
Accepts any printing characters excluding
embedded spaces.
TEXT _VALUE WIDTH 8 NUMERIC
Interprets data as a real value.
Accepts any real, integer or exponential
number.
TEXT _VALUE WIDTH 8 NUMERIC MIN 5.0 MAX 25.5
Interprets data as a real value.
Accepts only real, integer or exponential
numbers within the specified limits.
TEXT _VALUE WIDTH 8 INTEGER
Interprets data as an integer value.
Accepts any integer number.
TEXT _VALUE WIDTH 8 INTEGER MIN 5 MAX 25
Interprets data as an integer value.
Accepts only integer numbers within the
specified limits.
TEXT _VALUE WIDTH 8 ISOU
Interprets data as an ISO (International
Standards Organisation) dimensional unit.
Examples of valid input data are:
5
5’
5’3
3/16
3.3/16
5’3.3/16
5 inches or 5 mm (current units)
5 feet
5 feet 3 inches
3
/i6 inch
33/i6 inches
5 feet 33/i6 inches
(Note that the entry 5’3.3/16 in the last example takes up the maximum permitted field width of 8
characters. It would be more sensible in this case to allow a field width of, say, 14, so that lengths
such as 1000’11.13/16 could also be displayed.)
NOTE: The maximum scrollable length which the syntax allows is 132 characters. Remember,
however, that the maximum length which you can read into a PML text variable is 120
characters.
► To specify a tag, callback string or position for the gadget, extend the TEXT command as
explained in Sections 16.2, 16.3 and 16.4, respectively, noting that these command options come
between the TEXT command and the WIDTH command.
As an example, the command
TEXT _SIZE |Height| CALLBACK |$$M /SIZE.MAC| WIDTH 8 NUMERIC MIN 0 MAX 100
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-11
Defining Gadgets
creates a text entry field gadget labelled with the text ‘Height’. When selected, the gadget allows
you to type in any value between 0.0 and 100.0. Although the stored input maybe of any length, only
the first 8 characters will be displayed (including, for example, a decimal point). The value thus
entered would normally be used as a parameter in the macro /SIZE.MAC, which is run by the
callback string.
► To set a default value for a text field entry gadget, to be shown in the text field when the gadget
is first displayed, set the corresponding form variable to the required value in the form’s
initialisation macro.
► To create a text field entry gadget that does not display any text entered (when entering
passwords, for example), use the NOECHO option:
TEXT _DATA WIDTH 12 NOECHO STRING
16.7
Interprets data as a literal text string.
Accepts any printing characters.
Displays 12 characters at a time, without
displaying the text entered.
Text Pane Gadgets
Text pane gadgets are multi— line text entry fields. The user can enter text either directly or by cut
and paste.
To create a text pane gadget use the TEXTPane uname command. For example:
TEXTPANE _DAT |Comments|
Creates a text pane gadget for user
comments.
You can also use PML to set the contents of the pane from an array variable or from some query
function. This facility makes use of the VARIABLE TEXTPANE command, described in Appendix
A.
16.8
Toggle Gadgets
Toggle gadgets are named, interactive, single-valued gadgets which can be toggled between two
states.
The value of the gadget is defined as its current state, each state being represented by a
case-independent text string. By default, these states are On (visual representation shows toggle
button pressed down, thus r
j
) and Off (visual representation shows toggle button raised, thus
), but you may specify different values, such as Up and Down, if you wish.
16-12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
The tag, if any, for a toggle gadget is displayed at the right-hand side of the gadget.
You can specify pixmap files to provide illustrations indicating the condition of the toggle. If you
require this, you must provide and specify two pixmaps (one for On and one for Off, obviously).
► To define a new toggle gadget, use the TOGGLE uname command, including, if required,
alternatives to the On and Off states (which must be specified in that order). For example:
TOGGLE _TOG1
TOGGLE _TOG2 STATES |Head| |Tail|
► To specify a tag, pixmaps, callback string or position for the gadget, extend the TOGGLE
command as explained in Sections 16.2, 16.3 and 16.4, respectively, noting that these command
options come between the TOGGLE command and the STATES command.
As an example, the command
TOGGLE _MODE |Mode| CALLBACK |$$M /ROUTE.MAC| STATES |Forward|
|Backward|
creates a toggle gadget labelled with the text ‘Mode’. When On, the gadget is set to the value
‘Forward’; when Off, the gadget is set to the value ‘Backward’. The value thus set would normally
be used as a parameter in the macro /ROUTE.MAC, which is run by the callback string.
► The default state, when a toggle is first defined, is that corresponding to Off. To change this,
set the corresponding form variable in the form’s initialisation macro.
16.9
Radio Group Gadgets
Radio group gadgets are special groups of toggles (radio buttons) which always have one, and only
one, member of each group set to On. Pressing any Off toggle first causes the current On toggle to
revert to Off (accompanied by execution of its callback string) and then sets the pressed toggle to
On (accompanied by execution of its callback string).
Each group is displayed as either a horizontal row or a vertical column of diamond-shaped radio
buttons, depending on the current path direction (see Section 16.4.1). As with the independent
toggle gadgets described in Section 16.8, the visual appearance of each radio button shows its
current state, thus:
►
On
Off •
To define a new radio group gadget, use the following sequence:
4.
Enter Radio Group Setup mode by using the command RADIOGROUP.
5.
Use the TOGGLE command syntax, as explained in Section 16.8, to define each
individual radio button within the group.
6.
Leave Radio Group Setup mode by using the command EXIT (which returns you to the
normal Form Setup mode).
NOTE: A radio group does not have its own identifying uname', it simply comprises a functional
grouping of individually named toggles.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-13
Defining Gadgets
► To specify a tag, callback string or position for an individual radio button within a radio group
gadget, extend the TOGGLE command as explained in Section 16.4. Note, however, that the
position of the radio group as a whole is defined by the position of the first radio button only and
subsequent buttons are aligned relative to this; positions specified for buttons other than the first
will be ignored.
► The default state, when a radio group is first defined, is for t Iie /z/:s7 toggle (radio button) to be
On and, hence, for all others to be Off. To change this, set the corresponding form variables in the
form’s initialisation macro.
16.10
List Gadgets
List gadgets are named, interactive, single-valued or multi-valued gadgets which allow you to
select from a range of predefined values. Single choice lists allow you to select only one value at a
time; selecting a new value deselects any previous choice automatically. Multiple choice lists allow
you to have several values selected at the same time.
A list gadget holds a set of display texts which are shown as a vertical list to prompt you when
making your selection(s), together with a set of associated replacement texts (one for each display
text). When a line of display text is selected (as shown in the display by highlighting), it is the
replacement text for that selection which is returned as the required value.
When defining a list gadget, you must specify the field width to be allowed for the display texts (as a
number of characters) and the list length (as the number of display text lines to be shown in the
vertical list). The displayed list gadget will include vertical and horizontal scroll bars, so that you
can bring into view any parts of the actual display texts which exceed the predefined width and/or
length limits.
The tag, if any, for a list gadget is displayed at the top left-hand corner of the gadget.
NOTE:
This section explains how to define the presentation of a list within its owning form. The
individual display texts and replacement texts are defined as form variables, as described
in Chapter 17. If replacement texts are not defined, they default to the same settings as
the corresponding display texts.
► To define a new list gadget, use the LIST uname command. The command line may optionally
specify a single choice or multiple choice list, and must specify the width and length of the display
text area. For example:
LIST _COLOUR MULTIPLE WIDTH 12 LENGTH 8
► To specify a tag, callback string or position for the gadget, extend the LIST command as
explained in Sections 16.2, 16.3 and 16.4, respectively, noting that these command options come
between the LIST command and the SINGLE/MULTIPLE command or, if the latter are omitted, the
WIDTH command.
16-14
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
As an example, the command
LIST _TYPE |Type| CALLBACK |$$M /TYPE.MAC| WIDTH 15 LENGTH 8
creates a single choice list gadget (by default) labelled with the text ‘Type’. When the owning form
is displayed, eight lines of display text will be shown in an area 15 characters wide. When a display
text is selected (highlighted), the corresponding replacement text will normally be used as a
parameter in the macro /TYPE.MAC, which is run by the callback string.
► The default list type, if neither SINGLE nor MULTIPLE is specified, is a single choice list. This
must always have one value selected, as defined by the current setting of the corresponding form
variable.
NOTE: The gadget value can be accessed using the DO LIST command, see Section 7.3.6.
16.11
Selector Gadgets
NOTE: CADCENTRE recommends that you use Selector Gadgets only if you genuinely require
the database features describe below. In most cases, List Gadgets provide a more
efficient solution.
Selector gadgets are variants of list gadgets (as described in Section 16.10). They differ in having
only a single list of values; they do not have separate display texts and replacement texts.
General-purpose selectors may be set to any values, as for list gadgets; database selectors are set
automatically to show the names of elements in the current DB hierarchy (thus displaying a
database Members List).
Single choice selectors allow you to select only one value at a time; used, for example, to select a
new current element during database navigation. Multiple choice selectors allow you to have
several values selected at the same time; used, for example, to show and select for modification the
results of querying attributes.
By default, a database selector displays a static ‘snapshot’ of the current position within the
database when the gadget is first displayed. You may explicitly update the contents of such a gadget
later by refreshing the display (see Section 16.17). You may, alternatively, specify automatic
updating of the database selector, such that its contents always show the elements immediately
above and below the current element as you navigate around the database.
By default, a database selector displays both the owner and members of the current element. You
may, if you wish, specify that only the owner or the members be shown.
When defining a selector gadget, you must specify the field width (as a number of characters) and
the list length (as the number of items to be shown in the vertical list) for displaying the current
settings. The displayed selector gadget will include vertical and horizontal scroll bars, so that you
can bring into view any parts of the list which exceed the predefined width and/or length limits.
The tag, if any, for a selector gadget is displayed at the top left-hand corner of the gadget.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-15
Defining Gadgets
NOTE:
This section explains how to define the presentation of a selector within its owning form.
The individual settings of general-purpose selectors are defined as form variables, as
described in Chapter 17. The settings of database selectors are taken directly from the
database hierarchy.
► To define a new selector gadget, use the SELECTOR uname command. The command line
may optionally specify a single choice or multiple choice selector, and must specify the width and
length of the displayed list area. For example:
SELECTOR _SETTINGS MULTIPLE WIDTH 12 LENGTH 8
creates a multiple-choice general-purpose selector gadget; its values must be set separately by
defining the corresponding form variables.
SELECTOR _MEMBERS WIDTH 12 LENGTH 8 DATABASE
creates a single-choice (by default) database selector gadget; its values will be set automatically to
show the position in the database hierarchy when the gadget is displayed..
► To specify a tag, callback string or position for the gadget, extend the SELECTOR command
as explained in Sections 16.2, 16.3 and 16.4, respectively, noting that these command options come
between the SELECTOR command and the SINGLE/MULTIPLE command or, if the latter are
omitted, the WIDTH command.
As an example, the command
SELECTOR _MEMS |Members| CALLBACK |$$M /MEM.MAC| WIDTH 15 LENGTH 8 DATA
creates a single choice database selector gadget labelled with the text ‘Members’. When the owning
form is displayed, eight lines will be shown in an area 15 characters wide. Changes to the selection
are handled by the macro /MEM.MAC which is run by the callback string.
► To specify how the DB hierarchy is to be shown in a database selector, qualify the DATABASE
part of the command, thus:
SELECTOR ... ... LENGTH 8 DATABASE
(i.e. with no qualifier)
will show both the owner and the members of the current (highlighted) element.
SELECTOR ... ... LENGTH 8 DATABASE MEMBERS
will show only the members of the current (highlighted) element; i.e. only items below the current
element in the DB hierarchy.
SELECTOR ... ... LENGTH 8 DATABASE OWNERS
will show only the owner of the current (highlighted) element; i.e. only items above the current
element in the DB hierarchy.
► To set automatic updating of a database selector gadget, so that the displayed members list
changes to maintain the correct owner/member relationships as you change the selected element
j ~
TO
~
ID
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
(i.e. as you navigate around the DB), end the SELECTOR command line with the AUTO
command. For example,
SELECT _MEMS |Members| CALL |$$M /MEM.MAC| WIDTH 15 LENGTH 8 DATABASE
AUTO
will create a single-choice members list which will always display both the members and owner of
whichever element is currently selected.
NOTE: Some combinations of SELECTOR options are not allowed. For example, you may not
specify a multiple choice database selector with automatic updating. If you specify an
invalid combination you will receive an error message.
16.12
Option Gadgets
Option gadgets are compact forms of single choice lists (see Section 16.10) which show only one
display text at a time. When displayed, an option gadget looks similar to a button gadget (it is
distinguished by a bar symbol), the text label in the button area showing the current list selection.
When picked (by holding down the mouse button with the cursor on the gadget), the full list of
display texts is shown and a new selection may be made by ‘dragging’ the highlight to the required
line.
The tag, if any, for an option gadget is displayed to the left of the gadget. (Remember that the text
shown within the gadget is the currently selected display text, not the gadget’s tag.) You can also
associate a pixmap with an option gadget.
► To define a new option gadget, use the OPTION uname command. The command line must
specify the width of the display text area. For example:
OPTION _COLOUR WIDTH 12
► To specify a tag, pixmap, callback string or position for the gadget, extend the OPTION
command as explained in Sections 16.2, 16.3 and 16.4, noting that these command options come
between the OPTION command and the WIDTH command.
As an example, the command
OPTION _COLOUR |Colour| CALLBACK |$$M /COLOUR.MAC| WIDTH 12
creates an option gadget labelled with the text ‘Colour’. When the owning form is displayed, the
display text corresponding to the current setting of the variable will be shown in a gadget area 12
characters wide. When a new display text is selected by dragging with the mouse, the corresponding
replacement text will normally be used as a parameter in the macro /COLOUR.MAC, which is run
by the callback string, and the new display text will appear in the gadget field.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-17
Defining Gadgets
16.13
Paragraph Gadgets
Paragraph gadgets are named, passive, valueless gadgets which allow either a paragraph of text or
a pixmap to be displayed on a form. The setting of a paragraph gadget may be defined either when
the gadget is created or by setting the corresponding form variable dynamically from within the
system. If text is wanted, this is fitted into the gadget area starting from the top left-hand corner.
NOTE: CAD CENTRE recommends that you use Paragraph Gadgets whenever you want to
place pixmaps, rather than Pixmap View gadgets.
A paragraph gadget has no tag and no callback string.
A paragraph text gadget has a fixed width (as a number of characters) and a fixed length (as a
number of lines). These limits may either be specified directly or by implication (by defining the
content of the gadget as part of its initial definition). When explicit limits have been specified, text
is positioned in the paragraph gadget in accordance with the following rules:
•
Text is entered from top left to bottom right as ‘words’, where a word is any sequence of
non-space characters terminated by a space (or by end of text). Control characters (e.g.
carriage return, line feed, tab) are treated as spaces and have no special effect, so that you
cannot override the default formatting.
•
If the text will fit into one line, it appears exactly as defined (i.e. unformattedO.
•
A word is split across lines only if it is longer than the specified gadget width.
•
Typically, a line begins and ends with a word, with adjacent words separated by at least one
space. Extra spaces are distributed evenly (as far as possible) over the line length in order to
justify the text over the whole gadget width. The distribution of excess spaces proceeds in
opposite directions on alternate lines. Multiple spaces in the original text are not retained.
•
The last line of text has only single space separations; that is, the line is not justified.
•
If there is more source text than will fit into the specified gadget dimensions, the excess text is
not displayed. No error message is generated.
►
To define a new paragraph gadget, use the PARAGRAPH uname command. For example:
PARAGRAPH _PARA2 TEXT |Enter opposite corners of box|
creates a single line paragraph gadget of width 29 characters, into which the text fits thus:
Enter opposite corners of box
PARAGRAPH _PARA3 TEXT |Enter opposite corners of box| WIDTH 15 LINES 3
creates a paragraph gadget of width 15 characters and length 3 lines, into which the text fits thus:
Enter opposite
corners of box
16-18
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
PARAGRAPH _PARA4 WIDTH 30 LENGTH 6
creates an empty paragraph gadget of width 30 characters and length 6 lines, the content of which
may be defined during a session by setting the corresponding form variable.
PARAGRAPH _PARA4 PIX parapic
creates a paragraph gadget using the picture ‘parapic’.
► To specify a position for the gadget, extend the PARAGRAPH command as explained in
Section 16.4, noting that the AT command option comes between the PARAGRAPH command and
the TEXT or WIDTH command.
16.14
Userdata Facilities
Each form incorporates an ‘invisible’ gadget with the reserved uname _USERDATA. This
provides a method of storing any text string which is to be associated with that form, either
permanently or temporarily.
User data may be entered into, or read from, _USERDATA by means of form variables and your
macros may, in this way, store, read or delete strings as required. A person using the interface
cannot, however, access Userdata settings from within the form to which the gadget belongs.
Although _USERDATA appears as a single valued gadget when data is read to it or from it, it is
actually a special type of list gadget which always has one current field, and it is this current field
which is written to or read from as the gadget’s current value.
You can select any field (that is, make it current) by specifying its field number or by adding a new
field to the gadget; a newly added field becomes current by default.
You may overwrite the value of the current field, or any specified field, simply by redefining it. You
may also delete the current field, or any specified field, in which case all following fields are
renumbered automatically.
The Userdata gadget behaves like a single choice list in most respects, with one notable
exception — USERDATA
has at least one field, even though the content of that field may
be blank. When a form is first created, or when the Userdata gadget for a form is cleared of all data
settings, _USERDATA contains a single field which is both blank and current. If you append data
to an ‘empty’ gadget, the new data is stored in field 2; not in field 1 as would be the case for an empty
list gadget. To store the new value in field 1, you must overwrite the current blank value in field 1.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-19
Defining Gadgets
16.15
View Gadgets
NOTE: View Gadgets are application specific. Therefore, these gadgets may not be applicable to
your application.
View gadgets are named gadgets which are used to display alphanumeric or graphical views. There
are five basic types which are directly relevant: alpha views can display only alphanumeric text;
volume views can display one or more interactive 3D graphical views of a design model (primarily
used for DESIGN applications); area views can display interactive 2D graphical views (primarily
used for DRAFT applications); pixmap views can display only bit-mapped images (used for
displaying logos indicating the current application status); and plot views can display only passive
2D plotfiles.
The overall command for creating any type of view gadget is described in Section 16.15.1. The
more detailed commands needed to define the specific types of view are described in Sections
16.15.3 to 16.15.7. Section 16.16 explains how you can edit the attributes of existing view gadgets.
16.15.1
Creating View Gadgets
► To create a new view gadget, use the VIEW command to specify the type of view required and,
optionally, its labelling tag and its position within the form (view gadgets do not have callback
strings). You must then immediately define the attributes for the particular type of view created, as
explained in Sections 16.15.3 to 16.15.7. For example:
VIEW _VIEW1 ALPHA
(define attributes as described in Section 16.15.3)
VIEW _VIEW2 VOLUME
(define attributes as described in Section 16.15.4)
VIEW _VIEW3 AREA
(define attributes as described in Section 16.15.5)
VIEW _VIEW4 PIXMAP
(define attributes as described in Section 16.15.6)
VIEW _VIEW5 PLOT
(define attributes as described in Section 16.15.7)
► To specify a tag, pixmap or position for the gadget, extend the VI EW command as explained in
Sections 16.2 and 16.4, respectively, noting that these command options come between the VIEW
command and the command (ALPHA/VOLUME/AREA/PIXMAP/PLOT) which specifies the view
type.
NOTE:
If the current form is resizeable, it can own only one view gadget. Furthermore, no other
gadgets should be positioned below or to the right of this single view gadget. When such a
form is resized, the view gadget’s origin (i.e. its top left-hand corner) remains unchanged
while its area is adjusted automatically to fill the available space.
If the current form is not resizeable, it can own any number of view gadgets (and other
gadgets), each of which will have a fixed position and size.
16-20
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
16.15.2
Cursor Types
When a screen cursor enters a view, the View gadget determines what cursor type should be
displayed for the user, or the representation to be assumed during a graphical interaction.
You can specify the initial setting for the cursor type in a view when you define the gadget, or when
you edit the gadget.
The types of cursor available are:
POINTER
NOCURSOR
PICK
PICKPLUS
CROSSHAIR
The default value for initial cursor types for the various view subtypes are:
3D view gadgets
2D view gadgets
subtype
DESIGN
PLOT
DRAFT
ISOSPOOL
COMPARATOR
PIXMAP
POINTER
CROSSHAIR
CROSSHAIR
CROSSHAIR
POINTER
NOCURSOR
You use the CURSortype typename command to set an initial cursor type. For example:
CURS POINTER
NOTE:
Initial settings for cursor types are not currently supported for DESIGN or PIXMAP
views.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-21
Defining Gadgets
16.15.3
Defining Alpha Views
The command VIEW uname ALPHA (see Section 16.15.1) puts you into Alpha View Setup mode.
You must then define the attributes relevant to the newly created alpha view gadget.
►
To define the dimensions of the alpha view gadget, combine the WIDTH, HEIGHT and
ASPECT commands in any of the following ways:
WIDTH 35
HEIGHT 10
WIDTH 50 HEIGHT 20
HEIGHT 20 WIDTH 50
WIDTH 50 ASPECT 1.4
HEIGHT 20 ASPECT 1.4
defines width of view gadget (as number of characters)
defines height of view gadget (as number of lines)
|
combines both dimensions in a single command line
defines width and aspect ratio of gadget
defines height and aspect ratio of gadget
Note that the area thus defined applies only to the alphanumeric text display area w/rm the overall
alpha view gadget. The complete view gadget also incorporates a border area with space for the tag
(if any) and for the vertical and horizontal scroll bars. This border area cannot be switched off. The
ASPECT command specifies the aspect ratio (Width/Height).
► To define the data channel via which the gadget is to derive the alphanumeric data which is to
be displayed, use the CHANNEL command thus:
CHANNEL |COMMANDS|
CHANNEL |REQUESTS|
sets the view to display command lines and error messages
sets the view to display output resulting from queries
► To leave Alpha View Setup mode (but remain in normal Form Setup mode), enter the
command EXIT.
16.15.4
Defining Volume Views
The command VIEW uname VOLUME (see Section 16.15.1) puts you into Volume View Setup mode
(relevant primarily in the DESIGN module). You must then define the attributes relevant to the
newly created volume view gadget.
NOTE: The attribute settings defined at the form creation stage apply to the gadget when it is first
displayed. In practice, you will usually set up menu options which allow you to change
most of these settings from within the opened form (using the editing facility described in
Section 16.16).
►
To define the dimensions of the volume view gadget, combine the WIDTH, HEIGHT and
ASPECT commands in any of the following ways:
WIDTH 50
HEIGHT 20
WIDTH 50 HEIGHT 20
HEIGHT 20 WIDTH 50
16-22
defines width of view gadget (as number of characters)
defines height of view gadget (as number of lines)
J combines both dimensions in a single command line
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
WIDTH 50 ASPECT 1.4
defines width of gadget and aspect ratio of 2D drawing area
HEIGHT 20 ASPECT 1.4 defines height of gadget and aspect ratio of 2D drawing area
Note that the area thus defined is the overall area of the view gadget, including any border areas
used for the tag (if any) and for the vertical and horizontal rotation sliders. If the border is switched
off, the actual display area expands to fill the available space. The ASPECT command specifies the
aspect ratio (Width/Height) of the actual drawing area, i.e the area within the borders. If using
standard ISO drawing sheet sizes, you will usually set the aspect ratio to 1.414 (landscape format)
or 0.7071 (portrait format).
►
To define whether or not the gadget borders are displayed, use one of the commands
BORDERS ON
BORDERS OFF
►
(default)
To define the background colour of the volume view gadget, use the command
SETCOLOUR colour_number
where colour jiumber represents any standard DESIGN colour definition (see the DESIGN
Reference Manual).
► To define the highlight colour for the volume view gadget (that is, the colour in which items
are displayed when picked using the left-hand mouse button), use the command
SETCOLOUR colour_number
where colourjiumber represents any standard DESIGN colour definition (see the DESIGN
Reference Manual).
► To define whether the displayed 3D graphics are shown in wireline or colour shaded
representation, use one of the commands
SHADING ON
SHADING OFF
CADCENTRE Software Customisation
Reference Guide
Issue 1095
colour shaded representation (on suitable hardware)
wireline representation (default)
CADCENTRE
Protected by copyright: see frontispiece
16-23
Defining Gadgets
►
To define the view direction, use one of the following command formats:
LOOK EAST
LOOK N45W75D
LOOK THROUGH E100 N500 U850
LOOK THROUGH /A1
LOOK THROUGH ID @
LOOK THROUGH ID VALV @
LOOK FROM E100 N500 U850
LOOK FROM /A1
LOOK FROM ID @
LOOK FROM ID VALV @
LOOK TOWARDS E100 N500 U850
looks towards the East (cf. ELEVATION command)
looks towards specified direction
looks through specified point
looks through named element
prompts for cursor-identified through point
prompts for cursor-identified Valve for through point
looks from specified point (defines eye position)
looks from named element (defines eye position)
prompts for cursor identified from point
prompts for cursor identified Valve for from point
looks towards the given direction
looks towards named element
looks in specified isometric direction
looks Down (default)
looks from the East (cf. LOOK command)
LOOK TOWARDS /A1
ISOMETRIC 3
PLAN
ELEVATION EAST
PERSPECTIVE ON
WALKTHROUGH ON
RADIUS 100
enables perspective view
enables walkthrough mode
specifies the radius of the view — an imaginary sphere
centred around the through point, with the radius value
being in the current default units
specifies the step distance for walkthrough mode
specifies the distance of the from point from the through
point
STEP 25
RANGE 500
Each volume view needs to know what region of the design model is to be displayed (the 3D view
limits). Unless you specify otherwise, the limits set for a new view gadget will be the current view
limits (as set by, say, DESIGN’S LIMITS or AUTOLIMITS commands). In addition, each volume
view has an AUTO flag associated with it, which determines whether or not that view will be
updated automatically whenever the current view limits are changed.
► To define the view limits and the way in which they are to be updated, use one of the following
command formats:
LIMITS AUTO
display limits updated automatically to match current view limits
(default)
LIMITS LOCAL
display limits initially set to current view limits and not updated
automatically
LIMITS LOCAL N1000 E2500 U0 TO N3000 E5000 U2000
display limits initially set to specified positions and not updated
automatically
LIMITS LOCAL /EQUI2 /EQUI4
display limits initially set to origins of specified elements and not
updated automatically
16-24
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
You may change the current limits at any time by using one of the command formats
AUTOLIMITS N1000 E2500 U0 TO N3000 E5000 U2000
AUTOLIMITS /EQUI2 /EQUI4
Any volume views which have LIMITS AUTO set will be redrawn to match the new limits.
► To leave Volume View Setup mode (but remain in normal Form Setup mode), enter the
command EXIT
16.15.5
Defining Area Views
The command VIEW uname AREA (see Section 16.15.1) puts you into Area View Setup mode
(relevant primarily in the DRAFT module). You must then define the attributes relevant to the
newly created area view gadget.
NOTE: The attribute settings defined at the form creation stage apply to the gadget when it is first
displayed. In practice, you will usually set up menu options which allow you to change
most of these settings from within the opened form (using the editing facility described in
Section. 16.16).
► To define the dimensions of the area view gadget, combine the WIDTH, HEIGHT and
ASPECT commands in any of the following ways:
WIDTH 50
defines width of view gadget (as number of characters)
HEIGHT 20
defines height of view gadget (as number of lines)
WIDTH 50 HEIGHT 20 | combines both dimensions in a single command line
HEIGHT 20 WIDTH 50
WIDTH 50 ASPECT 1.4 defines width of gadget and aspect ratio of 2D drawing area
HEIGHT 20 ASPECT 1.4 defines height of gadget and aspect ratio of 2D drawing area
Note that the area defined by the WIDTH and HEIGHT commands is the internal area of the overall
view gadget, excluding any border areas. The ASPECT command specifies the aspect ratio
(Width/Height) of the actual drawing area, i.e the area within the borders. If using standard ISO
drawing sheet sizes, you will usually set the aspect ratio to 1.414 (landscape format) or 0.7071
(portrait format).
►
To define the background colour of the area view gadget, use the command
SETCOLOUR colour_number
where colourjiumber
Reference Manual).
represents any standard DRAFT colour definition (see the DRAFT
► To define the highlight colour for the area view gadget (that is, the colour in which items are
displayed when picked using the left-hand mouse button), use the command
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-25
Defining Gadgets
SETCOLOUR colour_number
where colour jiumber represents any standard DRAFT colour definition (see the DRAFT
Reference Manual}.
►
To define the content to be displayed in the drawing area, use the PUT command thus
PUT CE
PUT /SITE1/SHEET
draws the current element
draws the named Sheet element
The content specified may be any valid 2D graphical element, such as a DRAFT Sheet, View,
Library, etc.
If you put new content into an area view which already contains a drawing, the original content will
be replaced by the new, not added to it.
► To define limits for the drawing, such that only part of the specified content is drawn (giving,
in effect, a window on the overall content area), use the LIMITS command thus
LIMITS 200 100 TO 600 500
where the limits define two opposite corners of the required area in sheet coordinates.
►
To define whether or not the gadget borders are displayed, use one of the commands
BORDERS ON
BORDERS OFF
(default)
► To leave Area View Setup mode (but remain in normal Form Setup mode), enter the
command EXIT.
16.15.6
Defining Pixmap Views
NOTE: CADCENTRE recommends that you use Paragraph Gadgets whenever you want to
place pixmaps, rather than Pixmap View gadgets, because of possible difficulties with
editing Pixmap View gadgets.
The command VIEW uname PIXMAP (see Section 16.15.1) puts you into Pixmap View Setup mode.
You must then define the attributes relevant to the newly created pixmap view gadget. In practice,
all you need to do is specify the name of the file which holds the bit-mapped image which you wish
to display in the view.
The pixmap view gadget is of fixed size, so that the usual dimensioning commands are not
applicable.
►
To add a bit-mapped image to the gadget’s display area, use the PUT command thus
PUT /LOGO_EQUI
16-26
adds the named image file
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Defining Gadgets
16.15.7
Defining Plot Views
The command VIEW uname PLOT (see Section 16.15.1) puts you into Plot View Setup mode. You
must then define the attributes relevant to the newly created plot view gadget.
NOTE: The attribute settings defined at the form creation stage apply to the gadget when it is first
displayed. In practice, you will usually set up menu options which allow you to change
most of these settings from within the opened form (using the editing facility described in
Section 16.16).
►
To define the dimensions of the plot view gadget, combine the WIDTH, HEIGHT and
ASPECT commands in any of the following ways:
WIDTH 50
HEIGHT 20
WIDTH 50 HEIGHT 20
HEIGHT 20 WIDTH 50
WIDTH 50 ASPECT 1.4
HEIGHT 20 ASPECT 1.4
defines width of view gadget (as number of characters)
defines height of view gadget (as number of lines)
| combines both dimensions in a single command line
defines width of gadget and aspect ratio of 2D drawing area
defines height of gadget and aspect ratio of 2D drawing area
Note that the area defined by the WIDTH and HEIGHT commands is the overall area of the view
gadget, including any border areas. The ASPECT command specifies the aspect ratio
(Width/Height) of the actual drawing area, i.e the area within the borders. If using standard ISO
drawing sheet sizes, you will usually set the aspect ratio to 1.414 (landscape format) or 0.7071
(portrait format).
►
To define the background colour of the plot view gadget, use the command
SETCOLOUR colour_number
where colour jiumber is the logical number for the required colour.
► To define whether or not zoom and pan functions are available for manipulating the displayed
plot view, use one of the commands
BORDERS ON
BORDERS OFF
(default)
BORDERS ON enables users to zoom in on the plot view by pressing the centre button of the mouse
and to zoom out by pressing the right-hand button. This mode also adds horizontal and vertical pan
sliders to the borders.
BORDERS OFF disables the zoom function and removes the pan sliders from the displayed form.
►
To add a plotfile to the gadget’s display area, use the ADD command thus
ADD /PLOT1–1
CADCENTRE Software Customisation
Reference Guide
Issue 1095
adds the named plotfile
CADCENTRE
Protected by copyright: see frontispiece
16 27
Defining Gadgets
The content specified may be the name of any compatible plotfile, including P&IDs, reference
drawings, and so on.
►
To remove a plot from the current plot view, use the CLEAR command.
►
To leave Plot View Setup mode (but remain in normal Form Setup mode), enter the command
EXIT.
16.16
Editing View Gadget Attributes
The preceding sections describe the attribute setting commands in the context of the creation of
new view gadgets (in Form Setup mode). You may edit the attribute settings of any existing view
gadget without first entering Form Setup mode. You may either use this facility directly, by typing
in the editing commands during your session, or indirectly, by setting up menu options which run
macros which in turn incorporate the editing commands.
► To edit a view gadget, use the EDIT command to specify the full uuname of the view gadget
(that is, the gadget’s uname appended to the owning form’s uname) and the view gadget type, thus
EDIT _PIC1_SITE1–1 VOLUME
This command puts you into View Editing mode, with the named volume view as the current view
whose attributes are to be reset.
Once in View Editing mode, you may use any of the attribute-setting commands relevant to the
type of view gadget which you are editing, as described in Sections 16.15.3 to 16.15.7.
NOTE: The effect of editing any view gadget attribute will be shown immediately (subject to
normal screen updating rules). You do not have to exit from view editing mode to
implement the change.
It is not usually advisable to edit gadget settings from within a form initialisation macro.
►
To leave View Editing mode and return to normal command level, enter the command EXIT.
16.16.1
Keyboard Focus
You can control the keyboard focus (that is, the active window) using the EDIT FOCUS command.
The FOCUS option moves the keyboard focus to a given text input field gadget or its next or
previous neighbours, which must be text input fields. Note that the form which owns the gadget
must be currently mapped.
CADCENTRE Software Customisation
"I
TO
Oft
to
DCENTR
E frontispiece
Protected C
byAcopyright:
see
Reference
IssueGuide
1095
Defining Gadgets
16.1 6.2
Gadget Status
The EDIT STATUS command is used to control the greying-out of gadgets. The STATUS option
controls the greying out of the given gadget from the command line. However the following gadget
types may not be greyed out:
Forms
Menus
Menu items
Bars
Bar items
Graphical views
Radio group elements
Paragraphs
The greyed-out status can be queried:
Query GADGet _form_gadget STATUS
The greyed-out status can also be put into a PML variable. For example:
!stat = GADGET _form_gadget STATUS
$P $!stat
results in Inactive or Active, depending on whether the gadget is greyed out or not. The default
status of all gadgets is Active.
16.17
Updating Views and Selectors
The information displayed in a view gadget is determined by the available data when the gadget is
first displayed. The graphical display will not change its content from within a macro. Similarly, a
database selector gadget which has not been set to update automatically will display the position of
the current element in the database hierarchy when the gadget is first displayed.
To update the settings of either type of gadget, use the REFRESH command.
► To update the settings of all currently displayed graphical views and selector gadgets, enter
the command without qualification, thus
REFRESH
► To update the settings of a specific graphical view or selector gadget, give the uuname of the
gadget as part of the command, thus
REFRESH _MEMLIST_MEMS
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
16-29
17
Displaying and Using Forms
This chapter tells you how to control the ways in which forms are displayed during a working
session and the ways in which data may be stored in, and read from, the various types of form
gadget by using form variables.
17.1
Initialising an Application
Each application has one main initialisation form, with the uname _CADCSYS, which can not be
removed from the display. This form incorporates a menu bar which always includes a ‘System’
option which, in turn, always leads to a pull-down menu, _CADCMENU, containing some
essential system commands. These commands are:
•
Commands — displays a form containing a ‘Commands’ alpha view gadget
(see Section 16.15.3)
•
Requests
— displays a form containing a ‘Requests’ alpha view gadget
(see Section 16.15.3)
You cannot remove either of these options, but you can add other menu bar headings with
associated pull-down menus to suit any specific application.
This initialisation form ensures that you can always, as a minimum, control the application by
means of typed commands, even if a macro fails to run as intended.
If you wish to change the main form to another form, you should first design the form in the normal
way, and then use the SWAP command (see Chapter 21).
You can modify the _CADCSYS form only by including an appropriate SETUP FORM command
in the initialisation macro. Use of this command will clear the initialisation form of all but the
‘reserved’ gadgets, so that you may then add any other gadgets to suit your own requirements.
17.2
Controlling the Display of Forms
Forms are normally displayed automatically as a result of picking a menu field or a button gadget
within another displayed form. This allows you to set up a complex predefined interface in which
all form display possibilities are contained within the form definition macros.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
17-1
Displaying and Using Forms
There are occasions, however, when you need more flexibility than this ‘static’ interface allows;
where the form to be displayed depends in some dynamic way on the current context and data
settings. To allow for this, you can directly control the display of forms by incorporating suitable
commands into your macros.
17.2.1
►
Displaying Forms Explicitly
To display a non-blocking form, use the command
SHOW uname
Since the form is of the non-blocking type, it will remain displayed until you specifically remove it,
so that you may display several such forms simultaneously.
To specify the position at which the form is displayed, append the screen coordinates for the form’s
origin, as explained in Section 14.3.4. For example,
SHOW _COLOUR AT XR 0.5 YR 0.75
►
To display a blocking form, use the command
WAITON uname
NOTE: CADCENTRE recommends that you try to use as few blocking forms as possible. Our
experience is that these tend to frustrate the end user.
Since the form is of the blocking type, macro execution will pause at this point until the form has
been filled in and actioned. No other form can be accessed while the blocking form is displayed.
NOTE: Since no other macro can be run while the current macro is paused, any callbacks from
gadgets on the form, other than those associated with the OK or Cancel button, are
ignored.
To specify the position at which the form is displayed, append the screen coordinates for the form’s
origin, as explained in Section 14.3.4. For example,
WAITON _REPRES AT XR 0.2 YR 0.5
17.2.2
Checking Form Validity
The first action when a form is to be displayed is execution of the form’s initialisation macro (as run
by the initialisation text, if defined). This macro can be written so as to decide whether or not the
form is valid at the point in the command sequence at which the command to display it occurs. If it
is not, the macro must signal an error. The form display manager checks the macro’s error status
and, if necessary, suppresses the form display. You should ensure that the user always receives an
appropriate message if the form is suppressed, stating what has occurred and why, otherwise there
will be no feedback to show that the command was ever received.
1•
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Displaying and Using Forms
For details of the PML error-handling facilities which you can use, see Part I Macros and
Programmable Macro. In particular, refer to those sections which explain the RETURN ERROR
options for error handling.
17.2.3
Hiding Displayed Forms
A displayed form normally remains displayed until you use the OK or Cancel button to action its
callback string and remove it (whichever is appropriate). You may also remove a form from the
display by hiding it; that is, by removing it from the display without actioning its callback string.
►
To hide a displayed form, use the command
HIDE uname
17.3
►
Deleting Forms
To delete the definition of a form from the system, use the command
KILL uname
Once deleted, the form’s uname cannot be referenced in any other command, (other than in a
SETUP FORM uname command, which redefines it as though it had never existed).
Any gadgets belonging to a deleted form, that is, those whose uuname begins with the deleted
uname, are deleted automatically at the same time.
17.4
Handling Data Using Form Variables
The various items of data associated with individual forms are stored and read back by using form
variables. Form variables are not true variables in the usual sense. They are really just names for
the values held in the various form gadgets. The values of these variables may be set initially either
as part of the form definition or from the form initialisation macro, and they may be reset at any
time once the corresponding form gadgets have been defined.
Most gadgets have the concept of a current value, which can be set or read at any time after form
definition, whether or not the form is being displayed. Some passive gadgets, such as paragraphs,
can have data set but not read back.
The form variable used to hold each gadget value is identified by the gadget’s uuname. This may be
abbreviated to just the uname if the context makes this unambiguous, such as within a form
definition or initialisation macro, or within a callback from a form. The content of this form
variable is effectively a text string (or set of text strings in the case of a multiple choice list gadget).
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
17-3
Displaying and Using Forms
Gadget values are usually read back from within a macro which is run by a callback from the
displayed form. If a gadget value is modified, the displayed form will be updated visually to reflect
the change, but the new value will not be read back until the form’s callback string is actioned.
17.4.1
Setting Values for Single-Valued Gadgets
► To set a value for a single-valued gadget, such as a toggle, text entry field or paragraph gadget,
use the command format
VARIABLE uuname value-definition
where uuname (oruname) is the gadget identifier and value-definition is a text string or the name of
any database attribute whose current setting can be queried. (This syntax is effectively the same as
that used for setting any other type of variable. See Part I Macros and Programmable Macros for
further information.)
For example, the command
VAR _REPRE_PIPE.TOG1 INSUL
sets the value of the named toggle gadget to the current response to a Q INSUL query, as read from
the database; either On or Off, as the case may be.
17.4.2
Setting Values for List Gadgets
List gadgets may hold a range of value pairs, each comprising a display text and a corresponding
replacement text, each of which is located by a specific field number which indicates its position in
the list sequence. (Note that, unless specified otherwise, the replacement text is a copy of the
display text within a given pair.)
In addition, one list position (for a single choice list) or several list positions (for a multiple choice
list) may be defined as the current selection. When the list is displayed, the current selection is
highlighted and represents the setting of the list gadget as a whole.
► To begin to define the settings for a list gadget, use the VARIABLE LIST command to specify
the uuname (or uname) of the list thus
VAR LIST _LIST2
This command puts you into List Setting mode, with subsequent commands being applied to the
settings of the named list gadget.
►
To clear the list gadget of all current settings, use the command
CLEAR
17-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Displaying and Using Forms
This clears the settings of all three sub-lists; the display texts, the replacement texts, and the
current selection(s).
► To clear the list gadget’s current selection(s) only, leaving the display texts and replacement
texts unchanged, use the command
CLEAR SELECTIONS
►
To specify a single set of texts for a list, use the ADD command thus
ADD |Red| |Green| |Blue|
The specified texts will be added to the current list and will be used as both display texts and
corresponding replacement texts.
Note that the specified texts will be appended to any values already in the list. If you wish to clear the
list before adding the new values, you must first use the CLEAR command.
►
To specify pairs of texts for a list, use the PAIRS command thus
PAIRS |Red|
|R100 G0
B0|
|Green| |R0
G100 B0|
|Blue| |R0
G0
B100|
In this example, the display text ‘Red’, when selected, returns the replacement text ‘RI00 GO BO’ as
the value of the corresponding list position (and similarly for ‘Green’ and ‘Blue’).
Note that the specified pairs will be appended to any values already in the list. If you wish to clear
the list before adding the new values, you must first use the CLEAR command.
► The initial default selection in a list is the first element in the list. To specify a different initial
(default) selection(s) for a list gadget, use the SELECT command thus
SELECT 1
6
|Blue|
noting that the selected positions (for a multiple choice list in this example) may be specified either
by their field numbers (1 and 6 in the example) or by their display texts ( | Blue | in the example).
For a multiple choice list, the specified selections will be appended to any selections already in the
list. If you wish to clear the selection list before adding the new choices, you must first use the
CLEAR SELECT command (unless you use the CLEAR command to clear all settings of the current
list).
For a single choice list, only one selection can be made at any time. In the preceding example, only
the last position, namely ‘Blue’, would be selected (each selection overwriting the preceding one).
You can specify the initial selection by giving the replacement text. For example:
SELECT REPL |R0
CADCENTRE Software Customisation
Reference Guide
Issue 1095
G100 B0|
CADCENTRE
Protected by copyright: see frontispiece
17-5
Displaying and Using Forms
You can also specify the next, previous or last element in the list. For example:
SELECT NEXT
SELECT PREV
SELECT LAST
►
To leave List Setting mode and return to normal command level, enter the command EXIT
17.4.3
Setting Values for Selector Gadgets
NOTE:
For reasons of operating efficiency, CADCENTRE recommends that you use List
Gadgets rather than Selector Gadgets wherever possible. Only use Selector Gadgets
when you really need to use the Database facilities.
Database selector gadgets take their settings directly from the current database hierarchy and so
can not be explicitly set. General-purpose selector gadgets, however, must have their settings
defined as described in this section. Unlike list gadgets, selector gadgets hold only a single value in
each variable (not a pair).
► To begin to define the settings for a selector gadget, use the VARIABLE SELECTOR
command to specify the uuname (or uname) of the selector thus
VAR SELECTOR _SELEC2
This command puts you into Selector Setting mode, with subsequent commands being applied to
the settings of the named selector gadget.
►
To clear the selector gadget of all current settings, use the command
CLEAR
► To set values (i.e. the displayed list options) for a selector gadget, simply enter the required
values sequentially while in Selector Setting mode. Each new value will be appended to the current
list. You will usually set each value in the selector’s list to the result returned by one of the standard
querying commands, although any space-separated list may be used. Thus the command
NAME OWNER XLEN YLEN ZLEN ORI POS
sets the next seven values in the current selector list (that named in the VAR SELECTOR ...
command) to the current settings of these attributes in the order in which they are queried.
►
To leave Selector Setting mode and return to normal command level, enter the command
EXIT.
17.4.4
Setting Values for Userdata Facilities
A form’s userdata facility may be regarded as a non-displayed single choice list; that is, the
userdata list may contain a number of values of which only one is current (the current selection) at
any given time. The position of any value within the userdata list is referred to as that value’s index.
1 •
O
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Displaying and Using Forms
► To begin to define the settings for a userdata list, use the VARIABLE USERDATA command
to specify the uname of the form whose userdata list is to be updated, thus
VAR USERDATA _REPRES ...
and then extend this command as shown in the following paragraphs.
NOTE: The uname in this command is that of the owning form. The userdata list itself always has
the uname _USERDATA, so that the list actually accessed here is
_REPRES_USERDATA. If the form is already current, you may use the command VAR
USERDATA with no qualifying uname.
► To overwrite the value stored in the current field of a userdata list, simply redefine the value,
thus
VAR USERDATA _REPRES TRAC
The current field will be overwritten by the setting of the TRAC attribute (i.e. ON or OFF) of the
current database element.
► To overwrite an existing value stored in a specific field of a userdata list, simply follow the new
value by the index of the list position to be overwritten, thus
VAR USERDATA _REPRES TRAC 4
In this example, the setting of the TRAC attribute (i.e. ON or OFF) of the current database
element will be stored in the fourth position of the userdata list of the form _REPRES. Any data
previously stored in that position will be overwritten.
►
To append new data to a userdata list, use the ADD command thus
VAR USERDATA _REPRES ADD XLEN
In this example, the value of the XLEN attribute of the current database element is appended to
the userdata list of the current form. The added field becomes current.
NOTE: Remember that appending data to an empty userdata list (which always contains a single
blank field) puts the new data into field 2. To put the data into field 1, you must overwrite
this field by using the syntax shown in the preceding paragraphs.
► To change the current selection in the userdata list, use the SELECT command to specify the
index for the required position, thus
VAR USERDATA _REPRES SELECT 6
►
To delete a field from the userdata list, use the DELETE command thus
VAR USERDATA _REPRES DEL
VAR USERDATA _REPRES DEL 4
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Deletes current field
Deletes field number 4
CADCENTRE
Protected by copyright: see frontispiece
17-7
Displaying and Using Forms
All fields following the deleted one will be renumbered automatically. If the deleted field was
current, the new current field has the same list position but now has the setting which was
previously stored in the next-numbered field.
► To clear all settings from the userdata list (effectively a Delete All option), use the CLEAR
command thus
VAR USERDATA _REPRES CLEAR
NOTE: Remember that clearing all settings leaves the userdata list with a single blank field. You
cannot delete this last field to obtain a completely empty gadget.
17.4.5
Reading Data from List Gadget Values
► To read the current value of any single-valued gadget (toggle, text entry field, paragraph,
single choice list or userdata), simply refer to the form variable by name (prefixed by the $
character as for any other variable). Thus, any reference to the form variable _REPRES_INSU in
the format $_REPRES_INSU will be replaced by the current value of that form variable.
For example, one of the commands
VAR !XY ($_LIST1)
VAR !XY |$_LIST1|
if the gadget setting is a value (treated as an expression)
if the gadget setting is a text string
sets the user-definable variable !XY to the currently selected value from a single choice list on the
current form. (If you try to use this command to read a multiple choice list you will generate an
error.)
Similarly, one of the commands
VAR !DAT2 ($_REPRES_USERDATA)
VAR !DAT2 |$_REPRES_USERDATA|
sets !DAT2 to the currently selected value of the userdata list of form _REPRES.
► To read values from multi-valued gadgets (multiple choice lists), you must use the DO . . .
LIST command. See Section 7.3.7. For example, the command sequence
DO
!X LIST _DISP_COLOUR
COLOUR !X $!X
ENDDO
reads all selected fields from list gadget _DISP_COLOUR and sets Colour 1 to the current value
(replacement text) of field 1, Colour 2 to the value of field 2, and so on.
17.5
Querying Form and Gadget Attributes
Both forms and gadgets have certain attributes which you may query, and you may use the result of
such a query in one of two ways:
1 •
O
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Displaying and Using Forms
•
•
By writing it to the REQUESTS channel (see Section 16.15.3), by using the QUERY (Q)
command
By using it to set a variable, by using the VARIABLE command
►
To query a form attribute, use the command format
Q FORM uname attribute
The attributes applicable to forms are:
DISPLAY
REVISION
TITLE
ICONTITLE
►
Shows the state of the form (ON is form shown, OFF is form hidden)
Shows the revision status of the form
Gives the title of the form
Shows the icon title for the form
To query a view gadget attribute, use the command format
Q G A D G E T uuname type attribute
where the types applicable are:
VOLUME (i.e. a volume view gadget). The attributes of the volume view gadget which you may
query are (see Section 16.15.4 for their meanings):
Attribute
Returned values
WIDTH
HEIGHT
BORDERS
SHADING
LIMITS
AUTO
DIRECTION
BACKGROUND
HIGHLIGHT
CLIPPING
PERSPECTIVE
RADIUS
WALKTHROUGH
STEP
RANGE
THROUGH
a real value
a real value
ON, OFF
ON, OFF
a list of values for (X,Y,Z) min and (X,Y,Z) max
ON, OFF
a string defining the view direction
colour number of the background
The colour number of the highlight
ON, OFF
ON, OFF
a real value
ON, OFF
a real value
a real value
a string defining the through direction
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
"I 7 9
Displaying and Using Forms
AREA (i.e. an area view gadget). The attributes you can query are:
Attribute
WIDTH
HEIGHT
LIMITS
BACKGROUND
HIGHLIGHT
Returned values
a real value
a real value
the coordinates of the limits of the gadget
colour number of the background
the colour number
PLOT (i.e. a plot view gadget). The attributes you can query are:
Attribute
WIDTH
HEIGHT
BACKGROUND
HIGHLIGHT
Returned values
a real value
a real value
colour number of the background
the colour number
ALPHA (i.e. an alpha view gadget). The attributes you can query are:
Attribute
WIDTH
HEIGHT
Returned values
a real value
a real value
For example,
Q GADGET _COLIN_VIEW2 VOLUME AUTO
(shows ON or OFF in the Request alpha view)
VAR !LIM GADGET _COLIN_VIEW2 VOLUME LIMITS
(sets variable !LIM to a text string which lists the
coordinate limits for the displayed part of the model)
17.6
Defining Alert Forms
Alert forms are forms with predefined formats which are used to display specific types of
information. You may display them specifically, using the commands described in this section, or
they may be generated automatically by the application.
You may define the text to be displayed within the alert form and the position of the form on the
screen.
17.6.1
Defining an Error Alert
An error alert is a blocking form which displays an error message by using a paragraph gadget. It
incorporates an acknowledgement button which must be pressed to remove the alert before any
other command can be given.
17-10
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Displaying and Using Forms
If no position is specified, the error alert appears either at the current cursor position or at a
position determined by your workstation system.
►
To define an error alert, use the ERROR command thus
ERROR AT XR 0.6 YR 0.3 |Invalid Length. Must be a positive value.|
which would display an alert with the layout
ERROR
Invalid Length. Must be a positive value.
ACKNOWLEDGE
17.6.2
Defining a Confirmation Alert
A confirmation alert is a blocking form which uses a paragraph gadget to request confirmation of
an action. It incorporates two buttons giving YES and NO choices; one button must be pressed to
remove the alert before any other command can be given. The result of the selection is available
from the form variable _CALERT_USERDATA.
If no position is specified, the confirmation alert appears either at the current cursor position or at
a position determined by your workstation system.
►
To define a confirmation alert, use the CONFIRM command thus
CONFIRM AT XR 0.2 YR 0.5 |Are you sure?|
which would display an alert with the layout
CONFIRM
Are you sure?
YES
NO
NOTE: A user’s response to such a form (i.e. a YES or NO input) is stored in
_CALERT_USERDATA, from which it may be accessed as a logical value.
17.6.3
Defining a Prompt Alert
A prompt alert is a non-blocking form which usually prompts you for some expected input (which
depends on a preceding action) by using a paragraph gadget. You can turn system prompting off, so
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
17-11
Displaying and Using Forms
that your macros may take over the job of prompting in a context-specific manner. You must
dismiss any non-system generated prompts with a specific command.
If no position is specified, the prompt alert appears at a position determined by your workstation
system.
►
To define a prompt alert, use the PROMPT command thus
PROMPT AT XR 0.3 YR 0.6 |Enter diameter in inches|
which would display an alert with the layout
PROMPT
Enter diameter in inches
►
To switch system prompts Off or On, use the commands
PROMPT OFF
PROMPT ON
►
(default)
To dismiss a prompt alert from the display, use the command
PROMPT DISMISS
► PDMS Only. When defining a prompt alert which is to be displayed in response to a cursor
identification command (that is, a command of the format ID... @), it is often convenient to display
your own prompting message and to incorporate an escape route (in the form of a Cancel button)
in case no item of the expected type is currently being displayed. To do so, you must switch off the
default system prompt and load your replacement prompt definition by using the command format
PROMPT LOAD ESCAPE prompt- text
as in the following examples:
Example 1: Defining a single prompt to be used with an ID NOZZ @ command:
PROMPT OFF
PROMPT LOAD ESCAPE |Identify Nozzle Required|
ID NOZZ @
PROMPT DISMISS
PROMPT ON
When the command ID NOZZ @ is actioned, the system prompt (which you have switched off) is
replaced by your loaded prompt thus:
17-12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Displaying and Using Forms
PROMPT
Identify Nozzle Required
CANCEL
Example 2: Defining two prompts to be used with a CONN IDP @ TO IDP @ command:
PROMPT OFF
PROMPT LOAD ESCAPE |Identify first p-point|
PROMPT LOAD ESCAPE |Identify second p-point|
CONN IDP @ TO IDP @
PROMPT DISMISS
PROMPT ON
When the CONN I D P @ T O I D P @ command is actioned, the system prompts (which you have
switched off) are replaced in turn by your two loaded prompts thus:
PROMPT
PROMPT
Identify first p-point
Identify second p-point
CANCEL
CANCEL
If, having loaded your prompts in this way, a user tries but fails to identify the required item(s), an
audible alarm will be sounded (indicating ‘try again’) and the prompt will remain unchanged.
CAUTION:
You are advised not to use the PROMPT LOAD ESCAPE command in conjunction with the
option within a form initialisation macro. It can be difficult to ensure foolproof error handling
under these circumstances. If you must use this command sequence, refer to the section Part I
Macros and Programmable Macros which describes the RETURN ERROR NOALERT option for a
way of handling the problem.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
17-13
18
Hints for Successful User Interface Design
The graphical user interface (GUI) provides you with powerful facilities for designing your own
applications macros, especially when used in conjunction with the Programmable Macro
Language (PML) commands. The technical details of GUI definition are described in the rest of
this manual and the principles of macro writing, including the use of PML, are described in Part I
Macros and Programmable Macros. This chapter gives some general hints on how to design a user
interface which is both efficient and easy to use. (Chapter 20 describes the conventions used in
CADCENTRE’s macros, so that you can ensure compatibility with the standards as far as
possible.)
(Keywords are highlighted to emphasise the main principles which you should consider.)
18.1
Before You Begin
When the interface is used, the user will build up a command for a particular task by selecting from
some or all of the sequence: menu bar > pull-down menu > submenu > form > gadgets (the latter
also being used to enter data for the command parameters). Before you begin writing any macro
command lines, it is important to think about all the tasks for which the application is to be used
and to arrange these into a logical hierarchy of the actions needed to achieve them. You can then
use this hierarchic structure as the basis for allocating the corresponding commands to the
appropriate parts of the user interface.
The menu bar acts as an index to the lower-level functional commands and should be designed so as
to display a manageable number of headings (up to, say, eight in any single menu bar), each of
which represents a major functional category. This means that your initial hierarchy should have
no more top-level entries than the menu bar can conveniently accommodate. Each menu bar
option should then lead to a pull-down menu which lists all of the key commands which fall into the
corresponding category and which comprise the next level down in the hierarchic structure.
In an application, you might be able to break down the operations most commonly used into a
number of common subtasks. You will find that it is often these subtasks which determine the most
logical structure for your interface. Since it is via the forms that the user inputs data and then either
submits or rejects the new content, it follows that each subtask must be at such a level that it can be
presented within a single form. Conversely, each form must contain all the gadgets needed to input
the data required to complete the subtask which it represents.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
18-1
Hints for Successful User Interface Design
If a particular form corresponds to a subtask which has a large amount of related data (such as a
mixture of command options and numeric parameters), you should segregate the data into that
which is essential to complete the task and that which is optional. You can then relegate the
optional data to a subsidiary child form (displayed in response to a gadget selection on the main
form).
In summary, therefore, before you begin writing an application macro you should:
•
Identify all of the global tasks related to the application.
•
Break down the global tasks into subtasks, each of which can be handled by a single form.
•
Define the information requirements of each subtask (both input and output data).
•
Assign each global task to a heading in the application’s menu bar. Each heading should be
chosen carefully to give a clear indication of the family of commands which it represents.
•
Assign each subtask form to an option on a pull-down menu.
18.2
The Principles of Form Design
It is important that each form, and hence the subtask which it represents, is self-contained, so that
the data-entry operation can be completed successfully without reference outside the form.
Where possible, a form should be self-explanatory, so that it is obvious to the user what data is
required for its completion, and it should allow for changes of mind before the input is sent for
actioning by the application.
The layout of gadgets on the form should be such that data is entered in a logical sequence as you
move down the form. Where applicable, each gadget should show its current setting and this
should be set to a sensible default value when the form is initialised.
It is important to provide positive feedback to the user, confirming that any input has been
accepted, so that the user feels confident that he is in control of the application. The system has a
high degree of feedback built in (for example, buttons visibly depress when selected), but you can
enhance this by providing feedback at a higher level. A form which is actioned by an OK or Cancel
button shows, by its disappearance from the display, that the user’s instruction has been accepted.
Where a form is of a type which does not disappear after use (a ‘retained’ form), it helps the user if
you design in some visible response to his actions, perhaps by incorporating a paragraph gadget to
display a status message.
A form’s title should be related clearly to the text on the menu (or push button) which invokes it. In
many cases the title will be the same as the menu text, or an expanded version of it. For example, a
form displayed as a result of selecting ‘Create’ from the menu bar and ‘Equipment’ from the
resulting pull-down menu could be entitled ‘Create Equipment’, so that the form’s title describes
the task that the form is to perform.
In some cases, the nature of a form’s task requires one or more child forms to fully specify all the
data needed for its completion; either to prevent the parent form occupying too much screen space
18-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Hints for Successful User Interface Design
or to split up the data into manageable groups. When splitting gadgets between forms, remember
that all data which is essential for the completion of the task should be on the main form: the user
must never find that, having completed a form correctly, he still needs to open another form before
he can action the first form. Only optional data, which is likely to be entered infrequently, should
appear on child forms.
18.3
Choosing and Using Gadgets
18.3.1
Form Control Buttons
A completed form is submitted for action, or cancelled, by using form control buttons which you
should always position at the bottom of the form. The number of buttons, and their labels, will be
determined by the nature of the form.
The choice between using a non-retained form (OK/Cancel buttons) and a retained form
(Apply/Dismiss buttons) depends on the way in which the form is to be used. An infrequently used
form which sets global application options should always be non-retained, whereas a form which
performs actions which are likely to be repeated several times (perhaps on different objects)
should be retained. You must use your discretion to decide how to handle intermediate cases. In
general, forms for creating items should be non-retained, forms for modifying items should be
retained.
It is essential that the Cancel button, if used, is always able to restore the application to the state it
had before the form was displayed, so that the user can undo any changes made to the form’s
gadget settings. The easiest way to ensure this is to not let any gadget on the form (or on any child
form) alter the application until the OK button is pressed. Otherwise, any application changes
made by the form before pressing OK must be overridden by the action of the Cancel button.
The Reset button, which restores the values of the form’s gadgets to those which applied when the
form was displayed, without removing the form from the screen, is likely to be needed only on very
complex forms. A Reset button is most relevant on a retained form, allowing the form’s actions to
be applied with different settings so as to assess their effects. It is important that a Reset button on
a retained form can restore both the form and the application to their original states.
The Dismiss button on a retained form must simply remove the form from the screen; it should
never have any effect on the application. A form which requires no user input needs only a single
control button labelled ‘Dismiss’.
To maintain consistency of layout, the control buttons should be designed as follows:
OK
Position in lower left-hand corner of form. Include three spaces before and after the
OK text, thus | OK |
Cancel
Position in lower right-hand corner of form. Include one space before and after the
Cancel text, thus | Cancel |
Apply
Position in lower left-hand corner of form. Include one space before and after the
Apply text, thus | Apply |
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
18-3
Hints for Successful User Interface Design
Dismiss
Position in lower right-hand corner of form. Include no spaces before or after the
Dismiss text, thus | Dismiss |
Reset
Position mid-way between the Apply and Dismiss buttons. Include one space before
and after the Reset text, thus | Reset |
18.3.2
Push Buttons
Apart from the special case of form control buttons, push button gadgets have two main uses: to
invoke a further form (a child form) or to cause an immediate action in the application.
When used to bring up a child form, the button should be labelled with the child form’s name
(abbreviated if necessary) followed by an ellipsis (three dots), thus using the same convention as a
form field in a menu; for example, ‘Attributes...’. When used to act upon the application, the
button should be labelled with a description of that action, usually as a verb; for example, ‘
’.
When a user presses a push button, there should always be some visible effect to confirm this
action. Unless the effect is automatically visible, such as the appearance or disappearance of a
form, some other feedback must be provided; if necessary, by using a paragraph gadget whose
content is updated by the action.
Because a push button is not changed visibly after use, it is a poor choice of gadget for changing an
application’s state. It is better to use a toggle or option gadget for this purpose.
18.3.3
Text Entry Field Gadgets
The text entry field gadget is the most flexible means of entering data, and is the only method for
entering general textual or numeric data.
When you configure the gadget to accept only a specific type of input (string, integer, etc.), it is
important that you assign a tag which clearly implies the type of data expected. Where appropriate,
the text field should display the current value of the data which it represents, or a default value if no
user setting has been input. Such a default can help to show the user what type of data to enter, even
if the default value itself has no particular significance.
Ensure that the field width and scrollable length are appropriate to the intended input. It is usually
best to set a field width which is adequate for the longest input string which you anticipate, so that
scrolling is not usually necessary.
18.3.4
Toggle Gadgets
Toggle gadgets differ from push buttons in that they show the current state which they represent;
for example, On or Off. The toggle therefore serves a dual role as both a controller and an
indicator. It is important, therefore, that the toggle always correctly represents the current state of
the application (even if this is changed other than by use of the toggle).
18-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Hints for Successful User Interface Design
The use of a single toggle gadget is limited to selecting between a choice of two options. Toggles are
therefore applicable only to settings which can be represented in binary form (On/Off,
Positive/Negative, In/Out, True/False, etc.).
The tag associated with a toggle should clearly define the option which it represents, in a way which
leaves no doubt what application states are indicated by the On and Off settings. If an application
state does not have an obvious On/Off equivalent (such as the Forwards and Backwards
pipe-routing modes), it is often better to display both modes using radio buttons or a two-choice
option button.
18.3.5
One-of-Many Selection Gadgets
This heading covers three types of gadget, all of which allow the user to make a single choice from a
range of possibilities. These are:
•
•
•
the radio group gadget
the single selection list gadget
the option gadget
Despite their similar roles, each has particular advantages and drawbacks.
►
Radio Groups
Radio button groups should be used only where there are a small number of choices, since each
choice requires space on the form for a separate button. The maximum practical number in a given
case will depend on the size and layout of the individual form.
Their advantages are:
•
They show the current state which they represent. This means, therefore, that you need to
ensure that, as with toggle gadgets, this is always updated.
•
They give quick access to all the choices at once, without having to ‘open’ or scroll a list.
•
They emphasise the mutual exclusivity of the choices by visibly deselecting one choice when a
new one is made.
Their disadvantages are:
•
The range of choices cannot be updated dynamically as it can for single selection lists.
•
They take up more screen space than option buttons.
►
Single Selection Lists
Single selection lists can be used for any number of choices, the only limitation being on the number
of choices which you allow the user to see at any time without scrolling.
Their advantages are:
•
They allow you to provide a large number of choices in a relatively small screen area.
•
The choices may be updated dynamically; that is, the list of choices may be changed from
within the application.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
"18 5
Hints for Successful User Interface Design
Their disadvantages are:
•
They usually show only some of the choices available at any time. The user must scroll up or
down the list to see the other choices, and must remember what choices he has seen in other
parts of the list.
•
The current choice, although highlighted, may not be visible without scrolling.
►
Option Gadgets
Option buttons may be used for a reasonably large number of choices, the limitation being that the
whole list must fit into the available screen area when the button is accessed (since there is no
scrolling facility).
Their advantages are:
•
They occupy the least amount of screen space of all the one-of-many selection gadgets (until
they are accessed).
•
They always display the current choice in the same place (in the middle of the button). This
means, therefore, that you need to ensure that this is always updated.
Their disadvantages are:
•
The user has to hold down the mouse button continuously to see the list of choices.
•
If the list of choices is changed dynamically from within the application, the change will not be
apparent to the user and, if the current selection is removed from the list, the gadget will
become undefined.
18.3.6
Multiple Choice Lists
Multiple choice lists provide a method of selecting a group of options simultaneously. The list of
choices might comprise, for example, a number of components upon which some modification is to
be performed or a number of different options which are to be applied when the form is actioned.
If the list of options is small (say 4 or less) and constant, you should consider whether it would be
more convenient to use a number of toggle buttons.
18.3.7
Paragraph Gadgets
Paragraph gadgets are used solely to display text within a form. Such text may either be static, as set
when the gadget is first defined, or dynamic, such that it is updated from within the application.
You should use static paragraph gadgets to explain the function of the form, if it is not
self-explanatory, and to provide added annotation to individual gadgets within the form.
You may use dynamic paragraph gadgets for displaying the current status of the form or of the
gadgets within it. They are particularly useful to indicate changes of state brought about by push
buttons, which do not show the current state themselves.
It is important that the function or context of a form is never changed by an action from outside that
form, since the user might not be aware of such a change when accessing the form. Hence, a
paragraph gadget describing the function or context of a form, rather than its status, should be
changed dynamically only as a result of operations performed from within the form.
18-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
19
Examples of Some Typical Applications Macros
This chapter illustrates some ways in which the individual commands used for menu and form
design might be put together in real-life situations. Each example first illustrates a typical menu or
form and then lists the macro used to create it.
NOTE: The graphical interface is applicable to a wide range of CADCENTRE products.
Therefore, the examples used here may not be directly relevant to the application you are
currently working with. However, the general functions (creating forms, creating and
positioning gadgets etc.) are exactly the same across all products. So you should be able to
follow the examples given below, and use their ideas in your work, even though the results
do not match your specific requirements.
19.1
Macro File Headings
Macro file headings, with each line prefixed by a $* ‘comment’ code, are worth adding to your
macros. They can be used to record the origination and update history of the macro and to list any
variables and subsidiary macros to which the parent macro macro needs access when it is run.
The following example shows a typical heading layout:
$*––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
$*CADCENTRE Ltd.
|
$*Macro Name FSYSTEM
Person Colin Silk
Date 18.06.94
|
$*Revised
Person CS
Date 21.09.94
|
$*Description: System-Level Menu Definitions
|
$*Variables:
|
$*Macros Called:
|
$*––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
Such headings have been omitted from the individual macro listings in the following examples.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
19-1
Examples of Some Typical Applications Macros
19.2
A Menu Bar, Pull-Down Menus and Submenus
System
Design
Display
Query
Model
Commands
Requests
General...
Versions...
Axes...
Pins...
Construct...
Tag...
Identify...
Save Work
Structural...
Equipment...
Pipework...
Cable Trays...
End Design Session
End PDMS Session
Quit
Modules...
Create
Representation...
Limits
Drawlist...
Grid...
Colour...
File
>
Members...
Units...
Name...
Head
Tail
Same
Head Reference
Tail Reference
Jointstart
Jointend
Connection
Graphical...
Plot...
>
>
Options
Goto
Store...
Restore...
Delete...
CE
Owner
Members...
Explicit...
SETUP FORM _CADCSYS AT XR 0 YR 0
$* This form already contains the menu bar item |System| which calls
$* a pull-down menu with the options |Commands| and |Requests|
PARA _DUMMY AT 0 0 WIDTH 52 LINES 1
$* Empty paragraph gadget to set width of form to accommodate bar menu
BAR
ADD |Design| _DESIGN
ADD |Display| _VIEW
ADD |Model|
_MODEL
ADD |Query|
_QUERY
ADD |Goto|
_GOTOG
ADD |Options| _OPTIONS
EXIT
MENU _DESIGN
ADD |Save Work
ADD SEPARATOR
ADD |Structural...
19-2
|
|CALLG MSAVEW|
|
FORM _CD.STRUAPP
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Examples of Some Typical Applications Macros
FORM _CD.EQUIAPP
|
ADD |Equipment...
|SHOW _CD.PSPEC|
|
ADD |Pipework...
|SHOW _CD.CTSPEC|
ADD |Cable Trays... |
ADD SEPARATOR
ADD |End Design Session| |MONIT|
|CALLG MENDSESS|
ADD |End PDMS Session|
|CALLG MQUITW|
|
ADD |Quit
ADD SEPARATOR
FORM _CD.MODULES
|
ADD |Modules...
EXIT
MENU _VIEW
MENU _CREATE
ADD |Create|
ADD |Representation...| FORM _CD.REPRE
MENU _LIMITS
ADD |Limits|
FORM _CD.ADDREM
ADD |Drawlist...|
FORM _CD.GRIDB
ADD |Grid...|
FORM _CD.MODCOL
ADD |Colour...|
MENU _FILE
ADD |File|
EXIT
MENU _FILE
FORM _CD.SAVED
ADD |Store...|
ADD |Restore...| FORM _CD.RESTD
ADD |Delete...| FORM _CD.KILLD
EXIT
MENU _CREATE
ADD |Graphical...| FORM _CD.GRAPHV
FORM _CD.PLOTV
ADD |Plot...|
EXIT
MENU _MODEL
ADD |Axes...|
ADD |Pins...|
ADD |Construct...|
ADD |Tagging...|
ADD |Identify...|
EXIT
FORM _CD.AXES
FORM _CD.PIN
FORM _CD.CONST
FORM _CD.MARK
FORM _CD.IDENT
MENU _LIMITS
|CALLG MAUTACE|
ADD |CE|
|CALLG MAUTACE OWNER|
ADD |Owner|
ADD |Members...| FORM _CD.AUTO
ADD |Explicit...| FORM _CD.EXPA
EXIT
MENU _QUERY
ADD |General...|
ADD |Versions...|
CADCENTRE Software Customisation
Reference Guide
Issue 1095
FORM _CD.GENQ
FORM _CD.QUERYV
CADCENTRE
Protected by copyright: see frontispiece
19-3
Examples of Some Typical Applications Macros
EXIT
MENU _GOTOG
FORM _CD.GOTON
ADD |Name...|
|HEAD|
ADD |Head|
|TAIL|
ADD |Tail|
|SAME|
ADD |Same|
ADD |Head Reference| |GOTO HREF|
ADD |Tail Reference| |GOTO TREF|
|GOTO JOIS|
ADD |Jointstart|
|GOTO JOIE|
ADD |Jointend|
|CALLG ICREF|
|Connection|
ADD
EXIT
MENU _OPTIONS
ADD |Members...| |CALLG IMEMBER|
FORM _CD.UNITS
ADD |Units...|
EXIT
EXIT
$.
19-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Examples of Some Typical Applications Macros
19.3
A Database Members List (PDMS Only)
Form Title
Members
Selector gadget
Button gadget
WORL–>*
SITE
SITE
STABILISER
/CADC–SITE
Resize...
KILL _CD.MEMBER
$* Deletes any existing version of this form
SETUP FORM _CD.MEMBER AT XR 0 YR 0.12
TITLE |Members|
SELECTOR _MEMBERS CALL |$$_MEMBERS| WIDTH 30 LENGTH 10 DATABASE AUTO
PATH DOWN
VDIST 0.5
BUTTON _RESIZE |Resize...| FORM _CD.MEMRES
EXIT
SHOW _CD.MEMBER
$.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
19-5
Examples of Some Typical Applications Macros
19.4
A Form for Creating Graphical Views (PDMS Only)
Form Title
Create Graphical View
Text gadget
PDMS 3D View|
Title
Toggle
gadgets
Button
gadget
Border
Single view
Shade
Double views
Auto Update
Four views
OK
Radio Group
gadget
Cancel
KILL _CD.GRAPHV
$* Deletes any existing version of this form
SETUP FORM _CD.GRAPHV BLOCKING
TITLE |Create Graphical View|
INIT |CALLG IGRAPHV|
TEXT _TITLE |Title | AT 0 0 WIDTH 25 STRING
PATH DOWN
VDIST 0.1
HALIGN RIGHT
RADIO
TOGGLE _SINGLE |Single view | STATES |OFF| |ON|
TOGGLE _DOUBLE |Double views| STATES |OFF| |ON|
TOGGLE _FOUR
|Four views | STATES |OFF| |ON|
EXIT
TOGGLE _BORDER AT XMIN_TITLE YMAX_TITLE+0.1 | Border| STATES |OFF| |ON|
PATH DOWN
VDIST 0.1
TOGGLE _SHADE AT XMIN_TITLE YMAX_TITLE+1.1 | Shade| STATES |OFF| |ON|
TOGGLE _AUTO
AT XMIN_TITLE YMAX_TITLE+2.1 | Auto Update| STATES |LOCAL|
|AUTO|
BUTTON _OK
AT XMIN_TITLE YMAX_TITLE+4.1 |
OK
| CALL |CALLG MGRAPHV| OK
PATH RIGHT
HDIST 12
BUTTON _CANCEL | Cancel | CANCEL
EXIT
$.
19-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Examples of Some Typical Applications Macros
19.5
A Form for Modifying a Draw List
Form Title
Add/Remove Items
Members
Drawlist
WORL *
SITE SITE 2
ZONE PIPES
PIPE–>100–B–1
BRAN BRAN 1
BRAN 100–B–1–B1
BRAN 100–B–1–B2
BRAN 100–B–1–B3
None
Selector
gadget
Button
gadget
Add
Grey
Member
Remove
Drawlist
Dismiss
Option gadgets
KILL _CD.ADDREM
$* Deletes any existing version of this form
SETUP FORM _CD.ADDREM
TITLE |Add/Remove Items|
INIT |CALLG IADDREM|
SELECTOR _MEMBERS |Members| CALL |$$_MEMBERS| WIDTH 30 LENGTH 10 DATABASE AUTO
PATH RIGHT
HDIST 1
SELECTOR _DRAWLIST |Drawlist| MULTI WIDTH 20 LENGTH 10
HDIST 1
BUTTON _ADD |Add| AT XMIN_MEMBERS YMAX+1 CALL |CALLG MADD $$_ADDOPT|
PATH RIGHT
OPTION _ADDOPT WIDTH 6
VAR LIST _ADDOPT PAIRS |Member| |MEM|
|Volume| |VOL|
EXIT
OPTION _COLOUR WIDTH 9
VAR LIST _COLOUR PAIRS |Grey|
|Red|
|Orange|
|Yellow|
|Green|
|Cyan|
CADCENTRE Software Customisation
Reference Guide
Issue 1095
|1|
|2|
|3|
|4|
|5|
|6|
CADCENTRE
Protected by copyright: see frontispiece
19-7
Examples of Some Typical Applications Macros
|7|
|Blue|
|8|
|Violet|
|9|
|Brown|
|10|
|White|
|11|
|Pink|
|12|
|Mauve|
|Turquoise| |13|
|14|
|Indigo|
|15|
|Black|
|16|
|Magenta|
EXIT
BUTTON _REM |Remove| AT XMIN_DRAWLIST YMIN CALL |CALLG MREM $$_REMOPT|
OPTION _REMOPT WIDTH 8
VAR LIST _REMOPT PAIRS |Drawlist| |DRAW|
|CUR|
|Cursor|
|CE|
|Member|
|ALL|
|All|
EXIT
PATH DOWN
HALIGN RIGHT
VDIST 1
BUTTON _DISMISS |Dismiss|
CALL |SHOW _CD.MEMBER| CANCEL
EXIT
$.
19-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
20
Conventions in Customised Macros
This chapter describes how the conventions used in writing Applications macros. We advise you to
adopt the conventions in your work in order to minimise the problems of upgrading to new product
releases.
20.1
Naming Conventions
All macros, forms, variables etc. which are incorporated into the standard Applications follow
naming conventions which show their function. You are strongly advised to adopt the same
conventions when writing your own macros, so that future maintenance of your customised
Applications is made as easy as possible.
The following general principles apply to the naming of files and variables:
•
Filenames and variable names can contain the following characters:
A through Z (uppercase letters)
0 through 9
(underscore)
- (minus)
Lowercase letters, spaces and other characters which have special meanings on some
hardware should not be used.
•
Names should start with a letter. To avoid potential conflicts with names used in the standard
product macros, do not start your names with the letter C.
•
Names should be as short as possible, with a permitted maximum of 10 characters (excluding
extensions).
The rules for naming forms, menus and gadgets are explained in Chapter 13.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
20-1
Using Customised Macros in Applications
20.1.1
Macros
The first letter of a macro name should indicate its overall function. The following initial letters are
currently used in the standard application macros:
D
Definition/declaration. These contain data that is common to several disciplines, or data
that defines constants or constraints for an application.
E
External file handling. These maintain files accessed by the application.
F
Form definition. These define the appearance and functionality of individual forms.
I
Form initialisation. These contain data used to initialise forms each time they are shown.
L
Database hierarchy level checking. These check that a user is at an appropriate database
level before carrying out an element-creation command, say.
M
Form gadget callback macros. These are run when related form gadgets are used.
P
Plot data files. These reference plotfiles used by an application.
R
Local discipline routine/function. These contain subroutines or functions which are used
repetitively within a discipline-related application. (Subroutines and functions used by
different disciplines are held in the CLIB directory.)
S
These show a view.
U
Utilities. These include miscellaneous macros whose functions are not covered by any of
the other prefixes.
V
Variable definitions.
X
Bar menu execution macros. These are run when an option is picked on a bar menu,
usually to perform some type of check before a form is displayed.
After the first letter, the rest of the macro name should indicate its specific function. This part of
the name should be the same for related macros; for example, a family of macros with related
functions might be named thus:
function
Dfunction
Macro invoked from bar menu
before a form is displayed
Variable declaration macro
Pfunction
\function
Form definition macro
Form initialisation macro
function
Gadget invoked callback macro
Pfunction
Plotfile
Secondary macros should have the same name as the calling macro followed by a suffix indicating
the secondary function. For example, if a form definition macro Pfunction calls a secondary form
definition macro which is to load, say, directory data, then the secondary macro should be given a
name of the type Pfunction —DIR.
20-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Using Customised Macros in Applications
If it is specific to one form, a utility macro should be given a name which clearly links it with that
form; for example, a utility macro specific to the form _CD.SITE would be named USITE.
Usually, however, utility macros are called from a number of forms, in which case they should be
given names which clearly indicate their functions; for example, UCHKDIR might be a macro
which checks the validity of a direction.
20.1.2
Default Files
Since the default directory for your application contains all default files, regardless of the
applications to which they apply, the names of these files must show to which major application and
which functional discipline each applies.
A default file used by the whole of an application should have a name which corresponds to that
application; for example, a general default file for DESIGN would be named DES.
A default file used throughout a functional discipline should have a name indicating the
application and the discipline; for example, a default file for DESIGN’S clash-checking function
would be named DES-CLASHER.
A default file used by only part of a discipline should have a name indicating the application, the
discipline and the type of operation to which the defaults apply. For example, a default file for
setting up file handling within DESIGN’S clash-checking function would be named
DES - CLASHER- FILES .
20.1.3
Variables
Numbered variables ($Nnumber) and local variables ($!/iame) may be identified in any
convenient way, since they apply only within the macro within which they are defined. Global
variables ($!!name) must, however, follow a logical naming convention since their settings are
accessible from any macro.
The naming convention used for a global variable has four component parts:
•
A company code:
CD identifies a CADCENTRE-defined variable. You should choose a different code to
identify your own variables. It is safest if you avoid any prefix beginning with C.
•
A letter identifying the data type which the variable is intended to store:
R
Real
I
Integer
C
Character string (i.e. text)
L
Logical or Boolean (True or False)
P
Reference number or name of an element
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
20-3
Using Customised Macros in Applications
•
•
A letter identifying whether or not it is an array variable:
N
A single-valued (non-array) variable
A
An array variable
A short sequence identifying the function of the variable’s data. This part has a maximum
length of 12 characters (making a maximum for the composite name of 16 characters).
Consider the following examples:
CDPNNAME
A variable to hold the name of the current element
CDRAXYZ
An array variable to hold 3D coordinates defining a position
NOTE: The return data from any common library (CLIB) macro must be via a global variable
with a name showing its data type and ending in RTN; for example, CDLRTN is a variable
returning a logical True or False result.
Since all CLIB macros use the same return variables, the returned value must be used
immediately or assigned to another variable before it is overwritten.
20.2
Some General Style Guides
20.2.1
Designing Pull-Down Menus and Submenus
It is CADCENTRE policy to restrict the menu hierarchy to a maximum of three levels below the
main menu bar. With more than this, the interface becomes difficult to use. In practice, it is rare to
use more than two levels; one pull-down menu and one submenu.
Each menu option should, were possible, call either a submenu or a form directly. The practice of
running a macro from a menu option should be avoided. Thus the menu definition lines
ADD |File|
ADD |Colour...|
MENU _FILE
FORM _CD.MODCOL
(which calls a submenu)
(which calls a form)
are of the preferred format, whereas the menu definition line
ADD |CE|
|CALLG MAUTACE|
(which runs a macro)
is not.
20.2.2
Designing Forms
In order to make the use of the interface as flexible as possible, most forms are non-blocking. This
allows a user to, say, display a form, manipulate a view, change the Current Element, and then
20-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Using Customised Macros in Applications
return to the form to enter data. To allow the system to cope with this type of use, the following
rules must be complied with:
Macro Layout:
Since the command SHO\N formname in a macro does not stop the execution of the macro, the
result expected from running the macro must come from within the form definition rather than
from a subsequent line in the macro. For example, the macro commands
VAR _CD.SITE_NAME |unset|
SHOW _CD.SITE
NEW SITE /$_CD.SITE_NAME
will always create a site named /unset, regardless of any name entered on form _CD.SITE.
To give the intended result, the NEW SITE creation command must occur within the result macro
(MSITE) associated with the form.
Using Userdata:
The ability to navigate around the database while forms are open on the screen could cause
problems. If, for example, a user opens a form to modify the dimensions of the current element but
changes to a different element before invoking the form’s callback, the new dimensions will be
applied to the wrong element (possibly resulting in an error alert).
To avoid this situation, the form must be linked temporarily to the element which was current when
the form was displayed. You do this by setting the form’s userdata facility to the current element’s
reference number (not its name, since this can be changed by the user) from within the form’s
initialisation macro.
For example, the initialisation macro (ICBOX) for a form (_CD.CBOX) which modifies the
dimensions of a Box should first check that the current element really is a Box and should then set
the form’s userdata to the reference number of that Box, thus:
VAR USERDATA _CD.CBOX REF
The first line of any callback from the form must then be $_USERDATA. This returns the user to
the original Box, regardless of any database navigation which has taken place since the form was
opened, before any data is read back from the form.
Using a CE Button:
The disadvantage of using the userdata facility to link a form to a database item is that a user
wishing to modify a number of elements must dismiss the form, navigate to the next element, and
then reopen the form each time. To avoid this, a form which is likely to be used in this way should
incorporate a 'CE button’ whose function is to link the form to the current element. This allows a
user to modify one element, then navigate to another element, press 'CE’, and modify the new
element.
Since the form is effectively attached to a specific database item, the name of this item should
always be shown in the first line of the form to confirm which element the form will modify.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
20 5
Using Customised Macros in Applications
20.2.3
Some Miscellaneous Rules for Designing Forms
•
Line up gadgets neatly by positioning them relative to each other, rather than by giving them
explicit positions (except for the first gadget, which should be positioned at X0 Y0).
•
Never use a Paragraph gadget to label another gadget if the latter allows you to specify a tag
(otherwise the label has no logical association with the gadget it is meant to identify).
•
Set the width of ISOU gadgets to 14 characters, allowing for Feet and Inches dimensions
(e.g. 1000’11.13/64).
•
Use the vertical bar | rather than the apostrophe
confusion with Feet and Inch inputs.
20.2.4
as a text string delimiter to avoid
Some Miscellaneous Rules for Writing Macros
•
Use Algebraic notation in expressions rather than Reverse Polish.
•
Indent IF and DO constructions so as to make the macro logic easy to follow.
•
Do not nest macros to more than two levels, otherwise the logical sequences become very
difficult to follow.
•
Use comment lines frequently, so that the underlying logic of your macro may be easily
understood by others. (You may be glad of such comments yourself if you need to modify the
macro at a later date.)
•
Use Local Variables for all data which is required only within the current macro.
•
Use USERDATA in preference to Global Variables, since USERDATA settings are less likely
to be deleted inadvertently.
•
When you overwrite a system prompt, always use the PROMPT LOAD ESCAPE facility for
cursor identification of items (otherwise a user has no way to quit cursor mode if he fails to
pick an item).
20-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
21
Command Reference Section
This appendix summarises, in a standardised format, those commands which are most relevant
when writing user interface customisation macros. The conventions used in the presentation of the
command syntax are explained first, followed by details of the individual commands in alphabetic
order.
If you are not familiar with the basic principles of command syntax presentation, you should first
read the relevant chapters in your applications Reference Manuals.
NOTE: Some commands described are relevant only to specific CADCENTRE applications.
Where this occurs, it is indicated in the main title for the relevant command.
21.1
How the Command Syntax is Represented
The commands described in the main part of this appendix have their legal command and
interrogation options presented in the form of syntax diagrams. These diagrams formalise the
precise command sequences which may be used and supplement the explanations given in the
appropriate sections of this manual.
The following conventions apply to the syntax diagrams in this appendix:
•
Names written in lowercase letters enclosed in angled brackets (e.g. <gid>) represent
subsidiary syntax diagrams. Such names are used for cross-reference purposes within other
syntax diagrams.
•
Commands to be input from the terminal are shown in a combination of uppercase and
lowercase letters. In general, these commands can be abbreviated; the capital letters indicate
the minimum permissible abbreviation. (NOTE: This convention does not mean that the
second part of the command must be typed in lowercase letters; commands may be entered in
any combination of uppercase and lowercase letters.)
For example, the command
TOGgle
may be input in any of the following forms:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-1
GUI Command Reference
TOG
TOGG
TOGGL
TOGGLE
Commands shown wholly in uppercase letters cannot be abbreviated.
•
Names written in lowercase italics are command arguments.
•
Syntax diagrams are generally read from top left to bottom right.
•
Points marked with a plus sign ( + ) are option junctions which allow you to input any one of the
commands to the right of the junction. Thus
>–––+––– ABC ––––––.
|
|
|––– PQR* –––––|
|
|
|––– <dia> ––––|
|
|
‘––––––––––––––+–––>
means you may type in ABC or PQR or any command allowed by the syntax given in subsidiary
syntax diagram <dia> or just press RETURN to get the default option.
•
Options immediately followed by an asterisk (like PQR* in the preceding diagram) are the
default options which will be assumed unless you specify a different choice.
•
Points marked with an asterisk (*) are loop back junctions. Command options following these
may be repeated as required. Thus
.–––––<–––––––.
/
|
>–––*––– option1 –––|
|
|
|––– option2 –––|
|
|
‘––– option3 –––+–––>
permits any combination of optionl and/or option2 and/or option3 to be used (where the options
may define commands, other syntax diagrams, or command arguments). This may form an
exception to the rule of reading from top left to bottom right.
The simplified format
.––––<–––––.
/
|
>–––*––– name –––+–––>
means that you may type in a list of names, separated from each other by at least one space.
21-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
NOTE: The need to press the Return (or Enter) key to complete each command line is implicit in
all syntax diagrams and is not usually shown. Only in cases where the need to press
Return/Enter has some particular significance is this indicated specifically by the
abbreviation nl (New Line).
21.2
Command Arguments
These are inputs which are necessary to qualify command words (see Part I Macros and
Programmable Macros for a fuller explanation). They are distinguished by appearing in italics.
Name
Definition
Example
filename
integer
name
text
uname
uuname
value
word
nl
The pathname of a file
A positive integer
An element name
An alphanumeric string
A form or short gadget name
A full gadget name
A positive or negative number
A sequence of up to 4 letters
New line
/DATLISTS/SITE1
0,3
/ABODE
| Enclose Between Vertical Bars |
FORMNAME
FORMGADGET
3.142, -23.66, -34
NULL, VALV
Press Return or Enter key (depending on
your workstation keyboard)
Table A— 1
21.3
Examples of basic command arguments
Subsidiary Syntax Diagrams
This section contains the principal subsidiary syntax diagrams which are referred to within the
main diagrams in Section 21.4.
21.3.1
<gid>
General Element Identifier
Used to identify a specific element upon which some subsequent action is to be performed.
>–––+––– name ––––.
|
|
‘––– refno –––+–––>
For example:
/PIPE4
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-3
GUI Command Reference
21.3.2
<pml>
Programmable Macro Language Commands
Where you see this entry within a syntax diagram, you may use any of the PML commands
described in Part I Macros and Programmable Macros.
These allow you to set up logical programming constructions and to control error handling within
your application macros.
21.3.3
<uval>
Value with Associated Unit of Measurement
Used to enter a dimension using a unit of measurement which is not the current default unit.
>–––+–– value –––––.
|
|
‘–– <expres> ––+–– EXponential –– value ––.
|
|
‘––––––––––––––––––––––––––+––– MM –––––––.
|
|
|––– Metres –––|
|
|
|––– INches –––|
|
|
|––– FT –––––––|
|
|
|––– FEet –––––|
|
|
|––– text ––––––|
|
|
‘––––––––––––––+–––>
where <expres> is another subsidiary diagram representing the range of mathematical
expressions which may be used to input values and text represents a predefined 'special’ unit of
measurement.
For example:
9.75 INCH
1.5 FT
21.3.4
< x y p o s > 2D Screen Position
Used to specify a position on the screen in terms of the screen’s x-y proportions, relative to the
screen’s origin at its upper left-hand corner.
>––+–– XR value ––+–– YR value ––.
|
|
|
|
‘––––––––––––––|
|
|
‘–– YR value ––+–– XR value ––|
|
|
‘––––––––––––––+––>
21-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
For example:
XR .2 YR .8
XR 0.5
YR .5 XR .5
21.3.5
Point is 0.2 of screen width along x-axis and 0.8 of
screen height up y-axis.
Point is 0.5 of screen width along x-axis, i.e. at centre of
lower edge of screen.
Point is at centre of screen.
< f m p o s > 2D Form Position (for Gadget positioning)
Used to define the position of a gadget’s origin within a form. The position may be specified
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.
>–– AT ––+–– val –– val ––––––––––––––––––––––––––––––––––––––––––––.
|
|
|–– X val –––––––––––––––––––––––––––––––––––––––––––––––––|
|
|
|–– XMIN –.
|
|
|
|
|–– XMAX –+– sizepos ––.
|
|
|
|
|
‘–––––––––+–––––––––––––––+–– Y val –––––––––––––––––––––––|
|
|
|–– YMIN –.
|
|
|
|
‘–– YMAX –+––<sizepos> ––.
|
|
|
|
‘––––––––––––––+–––––––+––>
where <sizepos> is the graph used to set the gadget position relative to the size of the form
(FORM) and/or the size of the gadget (SIZE):
–––––+– uname –.
|
|
+––FORM–––|
|
|
‘–––––––––+– * –––+
|
|
|– + –––|
|
|
‘– – –––+– val ––+– + –.
|
|
|
|
|– – –|
|
|
|
|
|–––––+––––VAL*SIZE––––.
|
|
|
|
|
|
+–––––SIZE–––––––|
|
|
|
|
|
|
‘––––––––––––––––|
|
|
|
‘––––––––+––SIZE––––––––––––––––+–––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
Y
YMIN
YMAX etc
21-5
GUI Command Reference
For example:
AT 5 7.5
Puts gadget origin at form grid coordinates (5, 7.5).
AT X 5 Y 7.5
Same as preceding example.
AT XMIN YMAX 1
Positions new gadget with respect to previous gadget.
Gadgets have left-hand sides aligned horizontally
(X=XMIN) and a clearance of 1 grid unit between them
vertically (Y= YMAX+1).
AT XMIN_GAD1–2 YMAX_GAD2+1
Positions new gadget with respect to two existing gadgets.
Gadget is offset by 2 grid units to the left of _GAD1
(X=XMIN— 2) and 1 unit below GAD2 (Y= YMAX+1).
AT XMAX FORM–SIZE YMAX FORM–SIZE
XMAX FORM refers to the current right hand size of the
form at its current stage of definition (not its final maximum
extent). YMAX FORM refers to the 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 righthand bottom edge of the form.
The default, if no position is specified and if there is no current path set, is to position each gadget
at the form’s origin (0, 0). If a PATH and VDIST/HDIST have been set, gadgets other than the first
will be positioned according to the current settings.
21-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
21.3.6
<vshap> Dimensions of a View
Used to specify the width and height of any type of graphical view gadget.
The width and height may both be defined explicitly, or either of these dimensions may be
combined with a definition of the aspect ratio (width/height) such that the other dimension can be
derived.
>––+–– WIDth value –+– HEIght value –.
|
|
|
|
|– ASPect value –|
|
|
|
|
‘––––––––––––––––+––––––––––––.
|
|
‘–– HEIght value –+– WIDth value ––.
|
|
|
|
|
|– ASPect value –|
|
|
|
‘––––––––––––––––+–––––––––––+––>
For example:
WIDTH 25 HEIGHT 12
Sets width to 25 characters and height to 12 lines.
WID 50 ASP 1.414
Sets width to 50 characters and aspect ratio to 1.414
(which indirectly sets the height).
HEI 12 ASP 0.7071
Sets height to 12 lines and aspect ratio to 0.7071
(which indirectly sets the width)
NOTE: The precise ways in which the settings of width, height and/or aspect ratio are applied to a
particular type of view gadget depend on whether or not the view gadget incorporates
borders. The descriptions of the individual view types within the body of this manual
explain the rules applicable to each type.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-7
GUI Command Reference
21.4
The Commands
This section gives the full syntax of all the GUI customisation commands, in alphabetic order.
Some commands (for example ACTIONS) are ‘application-wide’ commands which can be used
inside or outside the interface definition mode, or even outside the application itself. Such
commands are described in the application’s Reference Manual, but are described here to save you
having to refer to another manual.
The information is given under the following headings:
Mode:
The setup mode within which the command is applicable. Note that some setup mode commands
act sequentially; for example, to enter Menu Setup mode you must have already entered Form
Setup mode. The command sequences by which you reach the various setup modes may be
summarised thus:
SETUP FORM
BAR
MENU
BUTTON
RADIOGROUP
LIST
I
______
1
OPTION
TOGGLE
AREA
PARAGRAPH
TEXT
ALPHA
TOGGLE
VIEW
PLOT
PIXMAP
VOLUME
NOTE: Except when defining the gadgets in the Button...Toggle list, you remain in each setup
mode until you specifically use the EXIT command to leave it.
Function:
A brief statement of the function of the command.
Description:
A brief explanation of what the command enables you to do and when you might use it. This
heading is omitted if the information is already provided under the Function heading.
Examples:
Examples of the permitted command variations. (Examples are omitted in trivial cases.)
Related Commands:
Commands which may be used in conjunction with, or have related effects to, the given command.
Syntax:
The full command syntax, given in the diagrammatic form explained in Section 21.1.
Defaults:
The default settings which relate to the various command options. (Some of these are also
indicated by asterisks within the syntax diagrams.)
21-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
ACTIONS (PDMS only)
Mode:
PDMS System-wide.
Function:
Controls execution of macro commands.
Description:
Allows or inhibits execution of macro commands. Switching to ‘actions off’ is
useful for checking the validity of the command syntax during the testing of new
applications macros. See Part I Macros and Programmable Macros for full details.
Examples:
ACT OFF
ACT ON
Prevents execution of macro (useful for checking syntax)
Allows execution of the macro commands (default)
Syntax:
>–– ACTions ––+–– OFf ––.
|
|
‘–– ON* ––+––>
Defaults:
ACTIONS ON
NOTE: There are other ACTIONS options for use under error conditions which, although still
valid syntax, have been superseded by PMEs error handling facilities. These are shown in
Part I Macros and Programmable Macros.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-9
GUI Command Reference
ALPHA options
Mode:
Alpha View Setup mode (see the VIEW command).
Function:
Defines an alpha view.
Description:
The VIEW ... ALPHA command puts you into Alpha View Setup mode, where you
may define an alpha view gadget using the syntax described here. You remain in
Alpha View Setup mode until you use the EXIT command.
Examples:
VIEW _COMMAND ALP
WID 25
HEI 12
CHAN COMMANDS
EXIT
Enters Alpha View Setup mode.
Sets width to 25 characters.
Sets height to 12 lines.
Sets data link to Command channel.
Returns to Form Setup mode.
(This sequence creates an alpha view with a command line input region and a
region for displaying command lines and error messages.)
VIEW _REQUEST ALP
WID 30
HEI 10
CHAN REQUESTS
EXIT
Enters Alpha View setup mode.
Sets width to 30 characters.
Sets height to 10 lines.
Sets data link to Requests channel.
Returns to Form Setup mode.
(This sequence creates an alpha view for displaying the results of querying
commands, i.e. no input region.)
Related Commands:
EXIT VIEW
Syntax:
.–––––––––––––––––––––––––––––––––––.
/
|
(ALPha) ––*–– <vshap> –––––––––––––––––.
|
|
|
|
|–– CHAnnel ––+–– COMMANDS ––|
|
|
|
|
|
|
‘–– REQUESTS ––+–– nl ––|
|
|
|–– <pml> ––––––––––––––––––––––––––––’
|
‘–– EXIT ––>
21-10
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
AREA options (DRAFT only)
Mode:
Area View Setup mode (see the VIEW command.).
Function:
Defines an area view.
Description:
The VI EW ... AREA command puts you into Area View Setup mode, where you may
define an area view gadget using the syntax described here. You remain in Area
View Setup mode until you use the EXIT command.
Examples:
VIEW _DWG AREA
WID 50 ASP 1.414
PUT /SITE/SHEET
LIM 200 100 TO 600 500
SETCOLOUR 6
SETHIGHLIGHT 3
EXIT
Enters Area View Setup mode.
Sets width to 50 characters and aspect ratio
to 1.414 (which indirectly sets the height).
Displays the named Sheet element.
Defines opposite corners of part of sheet to
be displayed (in sheet coordinates).
Defines background colour.
Defines highlight colour.
Returns to Form Setup mode.
Related Commands:
EXIT VIEW
Syntax:
.––––––––––––––––––––––––––––––––––––––––––––––––––.
/
|
(AREa) ––*– <vshap> –––––––––––––––––––––––––––––––––––.
|
|
|
|
|– PUT – <sgid> ––––––––––––––––––––––––––––––|
|
|
|
|
|– LIMits <uval> <uval> – TO – <uval> <uval> –|
|
|
|
|
|– SETColour – <colno> –––––––––––––––––––––––|
|
|
|
|
|– SETHighlight – <colno> ––––––––––––––––––––+– nl –|
|
|
|– <cursor> –––––––––––––––––––––––––––––––––––––––––|
|
|
|– <border> –––––––––––––––––––––––––––––––––––––––––|
|
|
|–– <pml> –––––––––––––––––––––––––––––––––––––––––––’
|
‘–– EXIT ––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-11
GUI Command Reference
AREA options (continued)
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.
< cursor > is the syntax for selecting the cursor type, as follows:
>–– CURSortype –––+–– POINTER ––––.
|
|
|–– NOCURSOR –––|
|
|
|–– PICK –––––––|
|
|
|–– PICKPLUS –––|
|
|
‘–– CROSSHAIR ––+––>
< border > allows control of zooming and panning:
>––– BORDers ––+–– ON ––.
|
|
‘–– OFF –+–––>
21-12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
BAR
Mode:
Form Setup mode.
Function:
Enters Menu Bar Setup mode.
Description:
The BAR command puts you into Menu Bar Setup mode, where you may add new
options to the menu bar of the current form. You remain in Menu Bar Setup mode
until you use the EXIT command.
Examples:
BAR
ADD |Display| _VIEWS
ADD |Model| _MODSET
ADD HELP
EXIT
Press RETURN to enter Menu Bar Setup mode.
Adds option ‘Display’ to menu bar. When
selected, this opens menu named _VIEWS.
Adds option ‘Model’ to menu bar. When
selected, this opens menu named _MODSET.
Adds a standard HELP option at the right of the
Menu Bar
Leaves Menu Bar Setup mode.
Related Commands:
EXIT
Syntax:
.––––––––––––––<––––––––––––––––.
.––––<––––.
|
/
/
|
|
|
>–– BAR ––*–– nl ––*–– <pml> ––’
|
|
|–– ADD––+–– text uname ––|
|
|
|
|
‘–––HELP–––––––––|
|
‘–– EXIT ––>
/
NOTE: A menu bar does not have a uname, since each form can own only one menu bar.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-13
GUI Command Reference
BUTTON
Mode:
Form Setup mode.
Function:
Defines a button gadget.
Description:
Specifies the position, tag or pixmap, callback text and control attribute of a button
gadget.
Examples:
BUTT _B1 AT 3 6 |Save| CALL |SAVEWORK|
Positions button _B1 at (3, 6), sets its tag to ‘Save’,
and sets its callback string to ‘SAVEWORK’.
BUTT _B2 |Accept Data| OK
Positions button according to current path setting,
sets its tag to ‘Accept Data’, and assigns it an OK
attribute. When selected, _B2 removes owning form
from display. No callback is sent as none was set.
BUTT _DISMISS |Dismiss| CANCEL
Button _DISMISS has the tag ‘Dismiss’. When
selected it removes its owning form from the display
(due to its CANCEL attribute). It has no callback
string, so it restores gadget settings to their previous
values.
BUTT _MOD |Modify| CALL |$$M /UPDATE.MAC| FORM _MODS
Sets tag for button _MOD to ‘Modify’ and sets its
callback string to run the macro /UPDATE.MAC.
When selected, the button displays the child form
_MODS.
BUTT _APPLY PIX apply_pic APPLY
Sets the pixmap ‘apply_pic’ to the button (the size of
the button will be determined by the size of the
pixmap). The APPLY attribute serves to confirm the
contents of the form, and leave the form displayed.
21-14
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
Syntax:
.–––––––<–––––––––––––––––––.
/
|
>–– BUTTon uname ––*–– <fmpos> ––––––––––––––––––|
|
|
|––PIXmap––name––+––<vshap>–––|
|
|
|
|
‘––––––––––––|
|
|
|–– text –––––––––––––––––––––|
|
|
|–– CALLback text ––––––––––––’
|
|–– FORM uname ––.
|
|
‘–––––––––––––––––+–– OK ––––––.
|
|
|–––APPLY––––|
|
|
|–––HELP–––––|
|
|
|–– CANCEL ––|
|
|
|–– RESET –––|
|
|
‘––––––––––––+––>
Defaults:
If no tag is specified, the tag defaults to the gadget’s uname.
The control attribute is unset unless you specifically enter OK, APPLY, HELP,
CANCEL or RESET.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-15
GUI Command Reference
CONFIRM
Mode:
Application-wide.
Function:
Defines and displays a confirmation alert form.
Examples:
CONF AT XR .6 YR .3 |Are you sure?|
Displays a confirmation alert form at the specified
screen position. The form shows the message specified
by the text string. The confirmation alert is removed
from the screen when either the ‘Yes’ or ‘No’ button is
pressed.
Related Commands:
ERROR
PROMPT
Syntax:
>–– CONfirm ––+–– AT –– <xypos> ––.
|
|
‘–––––––––––––––––––+–– text –––>
Defaults:
21-16
The default position, if the AT option is not used, is at the cursor position.
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
CURSORTYPE
Mode:
View create/edit mode
Function:
Defines a default cursor type for cursor representation in a view.
Description:
When a screen cursor enters a view, the gadget determines what cursor type should
be displayed for the user, or the representation to be assumed during a graphical
interaction. You can specify the initial setting for the cursor type in a view when you
define the gadget, or when you edit the gadget, using this command.
Examples:
CURSORTYPE POINTER
CURS CROSSHAIR
>–– CURSortype
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Sets a pointer as the default cursor type
Sets a crosshair as the default cursor type
––+–– POINTER ––––.
|
|
|–– NOCURSOR –––|
|
|
|–– PICK –––––––|
|
|
|–– PICKPLUS –––|
|
|
‘–– CROSSHAIR ––+––––>
CADCENTRE
Protected by copyright: see frontispiece
21-17
GUI Command Reference
EDIT
Mode:
Application-wide.
Function:
Enters Gadget Editing mode, allowing you to edit View Gadgets, other Gadgets
and forms.
Description:
View Editing mode allows you to edit the attributes of any existing view gadget
without first entering Form Setup mode. This is useful for changing the layout of a
view gadget interactively via the gadget’s menu bar.
When entering View Editing mode, you must specify the uuname of the view to be
edited and confirm its type. You remain in View Editing mode until you use the
EXIT command. When editing gadgets other than View Gadgets, you do not need
to use the EXIT command.
The FOCUS option moves the keyboard focus to a given text input field gadget or
its next or previous neighbours, which must be text input field. Note that the form
which owns the gadget must be currently mapped.
The STATUS option controls the greying out of the given gadget from the
command line. However the following gadget types may not be greyed out:
Forms
Menus
Menu items
Bars
Bar items
Graphical views
Radio group elements
Paragraphs
The greyed-out status can be queried:
Query GADGet _form_gadget STATUS
The greyed-out status can also be put into a PML variable. For example:
!stat = GADGET _form_gadget STATUS
$P $!stat
results in Inactive or Active, depending on whether the gadget is greyed out or
not. The default status of all gadgets is Active.
The use of gadget greying-out in this way is compatible with the greying-out of
non-graphical view gadgets of all displayed forms performed by the cursor
functions to force only graphical input. When the cursor function terminates, the
displayed forms are re-instated: only their active gadgets are greyed-in again.
(continued)
21-18
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
EDIT (continued)
Examples:
a.
EDIT _DATA_INPUT ALPH
Allows you to edit the named alpha view gadget
EDIT _VIEWS_VIEW1 VOL
Allows you to edit the named volume view gadget
EDIT _PIX_LOGO PIX
Allows you to edit the named pixmap view gadget
EDIT _HELP BUTTON CALLBACK help
Allows you to edit the callback macro help for the
button gadget _HELP.
b.
EDIT _PICS TITL |Plan View No. 3|
Edits the title banner of the named form
EDIT _PICS ICONTI |Plan3|
Edits the icon title of the named form
EDIT _PICS FOCUS HERE
Moves the keyboard focus to the named text
input gadget
EDIT _PICS FOCUS NEXT
Moves the keyboard focus to the next text
input gadget
EDIT _PICS FOCUS PREV
Moves the keyboard focus to the previous text
input gadget
EDIT _PICS STATUS INACT
Makes the named gadget inactive (greyed-out)
EDIT _PICS STATUS ACT
Makes the named gadget active
Related Commands:
a. ALPHA AREA EXIT
b. TITLE ICONTITLE
CADCENTRE Software Customisation
Reference Guide
Issue 1095
PIXMAP
PLOT
CADCENTRE
Protected by copyright: see frontispiece
VOLUME
21-19
GUI Command Reference
EDIT (continued)
Syntax:
a. Editing of gadget properties
>–– EDIT uuname ––+–– ALPha –––.
|
|
|–– AREa ––––|
|
|
|–– PLOt ––––|
|
|
|–– VOLume ––|
|
|
|–– PIXmap ––+–– nl ––––––––––––––.
|
|
|–– BUTton –– CALLback ––– text ––|
|
|
|
|
|–– FOCUS –––+––– HERE –––––––––––|
|
|
|
|
|––– NEXT –––––––––––|
|
|
|
|
‘––– PREVious –––––––|
|
|
‘–– STATUS ––+––– ACTive –––––––––|
|
|
‘––– INACTive –––––––+–––>
The ALPHA, AREA, PLOT, VOLUME and PIXMAP options take you to the specified
type of View Editing mode, ready to change the view attributes. See the
corresponding commands in this chapter.
The BUTton CALLback command allows you to edit callback macros associated
with button gadgets.
The FOCUS option moves the keyboard focus to a given text input field gadget or
its next or previous neighbours, which must be text input field gadgets. Note that
the form which owns the gadget must be currently mapped.
The STATUS option greys-out and greys-in (de-activates and activates) the
specified gadget. It only applies to Toggles, Texting, Textpanes, Buttons, Lists,
Selectors and Option Lists. Note that the form which owns the gadget must be
mapped.
b. Editing of form properties
>–– EDIT uname ––+–– TITLe ––––––.
|
|
‘–– ICONTItle ––+–– text ––––+–––>
21-20
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
ERROR
Mode:
Application-wide.
Function:
Defines and displays an error alert form.
Examples:
ERROR AT XR .6 YR .3 |Invalid Length. Must be a positive
value.|
Displays an error alert form at the specified screen
position. The form shows the message specified by the
text string. The error alert is removed from the screen
when the Acknowledge’ button is pressed.
Related Commands:
CONFIRM
PROMPT
Syntax:
>–– ERRor ––+–– AT –– <xypos> ––.
|
|
‘–––––––––––––––––––+–– text –––>
Defaults:
The default position, if the AT option is not used, is at the cursor position.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-21
GUI Command Reference
EXIT
Mode:
Any setup mode or editing mode.
Function:
Ends any form setup mode or view gadget editing mode.
Description:
Returns you from any setup mode or from editing mode to the previous command
level, thus
•
If you are in Form Setup mode, EXIT returns you to normal command level.
•
If you are in Menu Bar Setup mode, Menu Setup mode, Radio Group Setup
mode, or any of the View Setup modes, EXIT returns you to Form Setup mode.
•
If you are in List Setting mode or Selector Setting mode, EXIT returns you to
normal command level.
•
If you are in View Editing mode, EXIT returns you to normal command level.
Related Commands:
ALPHA AREA BAR EDIT MENU PIXMAP PLOT RADIOGROUP
SETUP VARIABLE LIST VARIABLE SELECTOR VIEW VOLUME
Syntax:
>–– EXIT ––>
21-22
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
FMINFO
Mode:
Forms and menus initialisation
Function:
Supplies general application information and specifies help— text files.
Description:
This is a top level command which can be called as soon as the GUI has started up.
Typically, FMINFO would be called from a START macro.
The help -text system you are using with your application will give you more
detailed information on the files you need to create, and how to do so. Briefly, the
two files are:
•
The application help -file which contains the actual text which will appear on
the screen, and the coded markup needed to access the text (in conjunction
with the second file).
•
The cross-reference file needed by the help system to link the forms and
gadgets in the GUI to the appropriate text in the help file.
Related Commands:
SWAP
Syntax:
>–– FMINFO ––+–– APPWARE –––text–––––––––––––––––––––––––––––.
|
|
‘–– HELP –– File ––filename–– Xref –––filename––+––>
Examples:
FMINFO APPW |10.4.1|
allocates version number 10.4.1 to the application
FMINFO HELP F formhelp X alias
identifies the file formhelp as the help text for the help
system, with the cross reference file alias to access the
text from the forms and menus
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-23
GUI Command Reference
HALIGN
Mode:
Form Setup mode.
Function:
Assists with layout of gadgets on a form.
Description:
Works in conjunction with current path (see PATH command). Defines how a
newly added gadget should be aligned horizontally with the preceding gadget.
Examples:
HALIGN L
HA R
Left-hand sides of gadgets are to be aligned
Right-hand sides of gadgets are to be aligned
Related Commands:
HDISTANCE
PATH
VALIGN
VDISTANCE
Syntax:
>–– HAlign ––+–– Left –––.
|
|
‘–– Right ––+––>
21-24
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
HDISTANCE
Mode:
Form Setup mode.
Function:
Assists with layout of gadgets on a form.
Description:
Works in conjunction with current path (see PATH command). Defines how a
newly added gadget should be spaced horizontally with respect to the preceding
gadget.
Examples:
HDIST 3
Distance from left-hand side of new gadget to right-hand
side of preceding gadget is to be 3 grid units (if current Path
is Right)
Related Commands:
HALIGN PATH VALIGN VDISTANCE
Syntax:
>–– HDistance value ––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-25
GUI Command Reference
HIDE
Mode:
Application-wide.
Function:
Hides a displayed form.
Description:
Removes a displayed form from the screen without actioning its callback string.
Examples:
HIDE _SELNOZ
Hides form SELNOZ.
Related Commands:
SHOW
Syntax:
>–– HIDE uname ––>
21-26
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
ICONTITLE
Mode:
Form Setup mode.
Function:
Defines the title which is displayed against the form’s icon when the form is
minimised on the screen.
Examples:
ICONTITLE |REPRES|
Syntax:
>–– ICONTItle text ––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-27
GUI Command Reference
INITIALISE
Mode:
Form Setup mode.
Function:
Defines the initialisation text for a form.
Description:
Defines the callback text which is read back each time the form is opened. This text
(the initialisation text) is usually a call to run a macro, which can then check the
form’s validity, set up the initial values of the form’s gadgets, etc.
Examples:
INIT |$$M /INIT.MAC|
where /INIT.MAC is a macro containing the
form initialisation commands
(Note that the macro call within the initialisation text begins with a doubling of the
£
$’ character. This ensures that the returned text begins with a literal ‘$M’, so that
/INIT.MAC is not run until the form is opened and the initialisation text is
interpreted by the system.)
Syntax:
>–– INITialise text ––>
21-28
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
KILL
Mode:
Application-wide.
Function:
Deletes a form definition.
Description:
Removes a form definition (including any gadgets which it owns) from the system.
Any subsequent references to these will be invalid.
Examples:
KILL _SELNOZ
Removes definition of form _SELNOZ from the
system.
Syntax:
>–– KILL uname ––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-29
GUI Command Reference
LIST
Mode:
Form Setup mode.
Function:
Defines a single-choice or multiple-choice list gadget.
Description:
Specifies the position, tag, and callback text of a list gadget. Also specifies whether
the list 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. (The actual display
texts and replacement texts which make up the list options are set as form
variables.)
Examples:
LIST _COL |Colours| MULT WID 12 LEN 8
The list gadget _COL will have the tag ‘Colours’. When
displayed, the list will show 8 lines of available options
at a time, in a field which is 12 characters wide. Other
options, if any, will be revealed by using the scroll bars.
Related Commands:
VAR
Syntax:
.–––––––<–––––––––.
/
|
>– LIST uname –*–– <fmpos> ––––––––|
|
|
|–– text –––––––––––|
|
|
|–– CALLback text ––’
|
|– SINGle* ––.
|
|
|– MULTiple –|
|
|
‘––––––––––––+– WIDth integer – LENgth integer –>
Defaults:
21-30
A single choice list.
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
MENU
Mode:
Form Setup mode.
Function:
Enters Menu Setup mode.
Description:
The MENU command puts you into Menu Setup mode, where you may add new
options to a pull-down menu (text or pixmap). You remain in Menu Setup mode
until you use the EXIT command.
Examples:
MENU _VIEWS
ADD |Plan| |LOOK D|
Press RETURN to enter Menu Setup mode.
Adds option ‘Plan’ to pull-down menu. When
selected, this returns the command LOOK D.
ADD |Colour| FORM _COLS Adds option ‘Colour’ to pull-down menu. When
selected, this opens the ‘child’ form _COLS.
ADD SEP
Adds separating line before next option.
ADD |Limits| MENU _LIMS Adds option ‘Limits’ to pull-down menu. When
selected, this displays the submenu _LIMS.
EXIT
Leaves Menu Setup mode.
Related Commands:
EXIT
Syntax:
.–––––––––––––––––––<–––––––––––––––––––––––––––––.
.–––<–––––.
|
/
/
|
|
|
>–– MENU uname ––*–– nl ––*–– <pml> ––’
|
|
|
|–– ADD ––+–– text –––––––––.
|
|
|
|
|
|––PIXmap – name –|–– text –––––––|
|
|
|
|
|
|
|– MENU uname ––|
|
|
|
|
|
|
‘– FORM uname ––|
|
|
|
|
‘–– SEParator ––––––––––––––––––––’
|
‘–– EXIT ––>
/
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-31
GUI Command Reference
OPTION
Mode:
Form Setup mode.
Function:
Defines an option gadget.
Description:
Specifies the position, tag or pixmap, and callback text of an option (or list button)
gadget. Also sets the width allowed for displaying the list options when the gadget is
selected. (The actual display texts and replacement texts which make up the list
options are set as form variables.)
Examples:
OPT _COLS |Colours| WIDTH 15
The option gadget _COLS has the tag 'Colours’. When
selected, the gadget displays the full list of preset options in
a field width of 15 characters.
Related Commands:
VAR
Syntax:
.–––––––<–––––––––.
/
|
>–– OPTion uname ––*–– <fmpos> ––––––––|
|
|
|–– text –––––––––––|
|
|
|–– CALLback text ––’
|
|–– WIDth integer ––.
|
|
‘–PIXmap–+– <vshap>–|
|
|
‘––––––––––+–––>
21-32
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
PARAGRAPH
Mode:
Form Setup mode.
Function:
Defines a paragraph gadget.
Description:
Specifies the position, dimensions (in units of character widths and line heights),
and, optionally, predefined text content for a paragraph gadget or a pixmap. Note
that a paragraph gadget has no tag and no callback string associated with it.
Examples:
PARA _MES AT X6 Y6 WID 18 LIN 4
Paragraph gadget _MES, positioned at form grid
coordinates (6,6), has a message area 18 characters wide
by 4 lines high. It has no predefined content; the content
may be set later by setting the corresponding form
variable.
PARA _BOX TEXT |Enter opposite corners of box|
Paragraph _BOX has a single-line message area of width
29 characters which displays the text ‘Enter opposite
corners of box’.
Related Commands:
VAR
Syntax:
>–– PARAgraph uname ––+–– <fmpos> ––.
|
|
‘–––––––––––––+––.
|
.––––––––––––––––<––––––––––––––––––’
|
|–––PIXmap –– name ––+–– <vshap>–––.
|
|
|
|
‘–––––––––––––+–––––––––––––––––
|
|
‘––+–– TEXT text ––+–––––––––––––––––––––––––––––––––.
|
|
|
‘–––––––––––––––+– WIDth integer – LINes integer –+––>
Defaults:
If no dimensions are specified for a paragraph containing predefined text, the
result is a single line message area of width equal to the length of the text. (If no text
is specified, the width and number of lines must be defined.)
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-33
GUI Command Reference
PATH
Mode:
Form Setup mode.
Function:
Assists with layout of gadgets on a form.
Description:
Defines the direction in which a sequence of new gadgets are to be added to a form.
The path thus set remains as the ‘current path’ until overwritten (or until you leave
Form Setup mode).
Examples:
PATH R
PATH D
Next added gadget placed to right of previous gadget
Next added gadget placed below previous gadget
Related Commands:
HALIGN
HDISTANCE
VALIGN
VDISTANCE
Syntax:
>–– PATH ––+–– Up ––––––.
|
|
|–– Down ––––|
|
|
|–– Left ––––|
|
|
‘–– Right* ––+––>
Defaults:
21-34
Path direction Right.
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
PIXMAP options
Mode:
Pixmap View Setup mode (see the VIEW command).
Function:
Defines a pixmap view.
Description:
The VIEW ... PIXMAP command puts you into Pixmap View Setup mode, where
you may define a pixmap view gadget using the syntax described here. You remain
in Pixmap View Setup mode until you use the EXIT command.
Examples:
VIEW _CADLOGO PIXMAP
PUT /cadlogo
EXIT
Enters Pixmap View Setup mode.
Adds bit-mapped image from named file.
Returns to Form Setup mode.
Related Commands:
EXIT VIEW EDIT
Syntax:
.––––––––––<––––––––––.
/
|
(PIXmap) ––*–– PUT –– name –– nl ––|
|
|
|–– <pml> ––––––––––––––’
|
‘–– EXIT ––>
NOTE: It is strongly recommended that you use the Paragraph Gadget for including pixmaps.
Also note that if you edit a Pixmap View to replace a pixmap, the replacement must be
exactly the same size as the original.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-35
GUI Command Reference
PLOT options
Mode:
Plot View Setup mode (see the VIEW command).
Function:
Defines a plot view.
Description:
The VI EW ... PLOT command puts you into Plot View Setup mode, where you may
define a plot view gadget using the syntax described here. You remain in Plot View
Setup mode until you use the EXIT command.
Examples:
VIEW _PLO2 PLOT
WID 50
HEI 20
BORD ON
SETCOL red
ADD /PLOT1–1
CLEAR
ADD /PLOT1–2
ADD /SITE–A/SHT3
EXIT
Enters Plot View Setup mode.
Sets width to 50 characters.
Sets height to 20 lines.
Enables zoom and pan, and adds sliders
Defines background colour
Adds named plotfile to the view.
Removes current content (/PLOT— 1)
Adds new plotfile to the view.
Replaces previous plot by named sheet.
Returns to Form Setup mode.
Related Commands:
EXIT VIEW
21-36
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
PLOT options (continued)
Syntax:
.––––––––––––––––––––––––––<–––––––––––––––––––––––.
/
|
(PLOt) ––*– <vshap> –––––––––––––––––––––––––––––––––––.
|
|
|
|
|– ADD – name ––––––––––––––––––––––––––––––––|
|
|
|
|
|– CLEar –––––––––––––––––––––––––––––––––––––|
|
|
|
|
|– BORDers –+– ON ––.
|
|
|
|
|
|
|
|
‘– OFF –+–––––––––––––––––––––––––|
|
|
|
|
|– SETColour – <colno> –––––––––––––––––––––––+– nl –|
|
|
|–– <cursor> ––––––––––––––––––––––––––––––––––––––––|
|
|
|–– <pml> –––––––––––––––––––––––––––––––––––––––––––’
|
‘–– EXIT ––>
where <colno> is any valid DESIGN colour definition.
< cursor > is the cursor identification syntax:
>–– CURSortype
––+–– POINTER ––––.
|
|
|–– NOCURSOR –––|
|
|
|–– PICK –––––––|
|
|
|–– PICKPLUS –––|
|
|
‘–– CROSSHAIR ––+––––>
NOTE: A Plot View can display only one plotfile at a time, so that each ADD command overwrites
any previously defined file.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-37
GUI Command Reference
PROMPT
Mode:
Application-wide.
Function:
Defines and displays a prompt alert form.
Examples:
PROMPT OFF
Switches off system prompt.
PROMPT LOAD ESCAPE |Identify first p-point|
Loads user-defined prompt with specified
message text and a ‘Cancel’ button to allow
possible escape from this point in the macro.
PROMPT LOAD ESCAPE |Identify second p-point|
CONN IDP @ TO IDP @
PROMPT DISMISS
PROMPT ON
Loads second user-defined prompt.
Any applicable commands can go here.
Removes prompts when no longer needed.
Switches system prompt back on.
Related Commands:
CONFIRM
ERROR
Syntax:
>–– PROmpt ––+–– ON* –––––––––––––––––––.
|
|
|–– OFF –––––––––––––––––––|
|
|
|–– DISmiss –––––––––––––––+––>
|
|–– AT –– <xypos> –––.
|
|
|–– LOAD –– ESCape ––|
|
|
‘––––––––––––––––––––+–– text ––>
Defaults:
21-38
Prompt On (i.e. system prompt enabled).
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
RADIOGROUP
Mode:
Form Setup mode.
Function:
Enters Radio Group Setup mode.
Description:
Puts you into Radio Group Setup mode, within which you may use the TOGGLE
command syntax (q.v.) to define individual radio buttons. The spacing and
alignment of the buttons are determined by the current PATH, HALIGN/VALIGN
and HDISTANCE/VDISTANCE settings.
You remain in Radio Group Setup mode until you use the EXIT command.
Examples:
RADIO
TOG _RAD1 ...
TOG _RAD2 ...
...
EXIT
Enter Radio Group Setup mode.
Define individual radio buttons using the
standard TOGGLE command syntax.
Return to normal Form Setup mode.
Related Commands:
EXIT TOGGLE
Syntax:
>–– RADIOgroup ––>
(leaves you in Radio Group Setup mode)
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-39
GUI Command Reference
REFRESH
Mode:
Application-wide.
Function:
Updates and redisplays the current screen.
Description:
Refreshes any gadget including the contents of graphical views and non-automatic
database selector gadgets.
Examples:
REFRESH
Refreshes all currently displayed gadgets.
REFR _form_VIEW2_VIEW2
Refreshes the named gadget only.
Syntax:
>–– REFResh ––+–– uuname ––.
|
|
‘––––––––––––+––>
21-40
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
REVISION
Mode:
Form Setup mode.
Function:
Sets the form’s REVISION attribute to any specified text string.
Description:
Although
intended
primarily
to
hold
revision
data,
as
a
management/documentation aid for macro source and binary file control, the
REVISION attribute may be set to any string which you wish to read later for
administrative purposes.
Examples:
REVISION |Version 2.3, 21 January 1993|
Syntax:
>–– REVISion text ––>
Querying:
>–– Query FORM uname REVision ––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-41
GUI Command Reference
SELECTOR
Mode:
Form Setup mode.
Function:
Defines a general-purpose or database element selector gadget.
Description:
Specifies the position, tag, and callback text of a selector gadget. 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. For a
database selector only, also allows you to specify which parts of the hierarchy are
shown and whether or not these are updated automatically during database
navigation.
Examples:
SEL _SET |Settings| MULT WID 12 LEN 10
Gadget _SET is a multiple choice general-purpose
selector with the tag ‘Settings’. It displays 10 lines at a
time, each of width 12 characters.
SEL _MEM |Members| WID 12 LEN 8 DATA AUTO
Gadget _MEM is a single choice database selector (i.e. a
Members List) with the tag ‘Members’. It displays 8
elements at a time in a field width of 12 characters. The
selector will show both members and the owner of the
current element (by default), and will be updated
automatically to reflect selection changes.
SEL _MEM |Members| MULT WID 12 LEN 8 DATA MEM
Gadget _MEM is a multiple choice database selector
with the tag ‘Members’. It displays 8 elements at a time
in a field width of 12 characters. The selector will show
only the current element and its members (not its owner)
as they are at the time when the gadget is displayed. The
list will be updated only if the gadget’s owning form is
closed and reopened or if the REFRESH command is
used.
Related Commands:
VAR
(continued)
21-42
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
SELECTOR (continued)
Syntax:
.–––––––<–––––––.
/
|
>– SELector uname –*– <fmpos> –––––––|
|
|
|– text ––––––––––|
|
|
|– CALLback text –’
|
|– SINGle* ––.
|
|
|– MULTiple –|
|
|
‘––––––––––––+– WIDth integer – LENgth integer –.
|
.––––––––––––––––––––––––––<–––––––––––––––––––––––––––’
|
‘––+– DATAbase –+– MEMbers –.
|
|
|
|
|– OWNers ––|
|
|
|
|
‘–––––––––––+– AUTO –.
|
|
|
|
‘––––––––+
|
|
‘–––––––––––––––––––––––––––––––––+––>
Defaults:
A single choice list.
If DATABASE is not qualified, default is Members plus Owners.
Auto update off.
NOTE: CAD Centre recommends that you use the List Gadget in preference to Selector
Gadgets, unless you need to use the DATAbase options.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-43
GUI Command Reference
SETUP FORM
Mode:
Application-wide.
Function:
Enters Form Setup mode ready for further definition of the form or its contents.
Description:
You must be in Form Setup mode before you can enter any commands for defining
the form itself or any of the gadgets which it is to own. Some commands used to
define the overall form properties are entered as part of the SETUP FORM
command line; others require you to press RETURN first, but to remain in Form
Setup mode. You remain in Form Setup mode until you use the EXIT command.
Examples:
SETUP FORM _A1 BLOCK RESIZE
Creates a user-resizeable blocking form named _A1.
SETUP FORM _REPRE AT XR 0.2 YR 0.6 RESIZE
Creates a user-resizeable form which has its top left-hand
corner positioned at the given screen position.
SETUP FORM _A2 SIZE 25 10 AT XR .5 YR .5
Creates a form with a width of 25 characters and a height of
10 lines, with its top left-hand corner at the centre of the
screen.
SETUP FORM _COL3 COPY _COL2 BLOCK
Creates a blocking form _COL3 with attributes (other than
being of blocking type) copied from existing form _COL2.
Related Commands:
EXIT ICONTITLE INITIALISE REVISION TITLE
Syntax:
.–––––––––<––––––––––––.
/
|
>–– SETUP FORM uname ––*–– BLOCKing ––––––––––––|
|
|
|–– RESIzeable ––––––––––|
|
|
|–– AT –– <xypos> –––––––|
|
|
|–– SIZE xvalue yvalue ––|
|
|
|–– COPY uname ––––––––––’
|
‘–– nl ––> leaves you in Form Setup mode
Defaults:
21-44
Non-blocking; non-resizeable; top centre of form at screen position XR 0.5
YR 0.15; size adjusted automatically to suit contents.
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
SHOW
Mode:
Application-wide.
Function:
Displays a non-blocking form.
Description:
Forms are normally displayed automatically as a result of picking a menu field or
button gadget. The SHOW command allows you to display a non-blocking form
explicitly from within a macro. The form remains displayed until you remove it,
allowing several forms to be shown at once.
Examples:
SHOW _SELNOZ
Shows form SELNOZ at the default
position.
SHOW _REPRE AT XR .5 YR .75
Shows form _REPRE with its top
left-hand corner at the specified screen
position.
Related Commands:
HIDE
WAITON MENU BUTTON
Syntax:
>–– SHOW uname ––+–– AT –– <xypos> ––.
|
|
‘–––––––––––––––––––+––>
Defaults:
Default position, if the AT option is not used, is with the top centre of the form at
screen coordinates (0.5, 0.15); i.e. just below top centre of screen.
NOTE: Bring up forms from nebus or buttons, rather than using SHOW or WAITON from
macros.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-45
GUI Command Reference
SWAP
Mode:
Forms and menus startup.
Function:
Specifies a form to act as the application’s main form.
Description:
Your application will have a system default main form, which will always be
displayed when you start the application. This command allows you to specify a
different form as the main form.
This is a top level command that would typically be included in a START macro.
Examples:
SWAP MAIN TO _NEWMAIN
Sets _NEWMAIN as the new main form
Related Commands:
FMINFO
Syntax:
>–– SWAP –––– MAINForm ––– TO –– uname –––>
21-46
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
TEXT
Mode:
Form Setup mode.
Function:
Defines a text entry field gadget.
Description:
Specifies the position, tag, and callback text of a text entry field gadget. Also
specifies the width of the displayed text entry area, the scrollable length of the
string which may be stored in the gadget, and the type of data which it will accept.
For numeric inputs, allows you to specify minimum and/or maximum acceptable
values. Also allows you to specify text entry that is not displayed on the screen (for
entering passwords, for example).
Examples:
TEXT _DAT WID 12 SCR 48 STR
Accepts any text string up to 48 characters
long and displays 12 characters at a time in a
scrollable window.
Data is interpreted literally.
TEXT _NAM WID 5 NAM
Input data must be a valid system Name.
TEXT _DIM WID 12 ISOU
Input data must be in a format which can be
interpreted as a valid ISO dimensional unit;
e.g. 5’3.3/16 for 5 feet 33/ i6 inches.
TEXT _VAL |Height| WID 8 NUM MIN 5 MAX 25.5
Text-entry box has the tag ‘Height’. It will
only accept numeric data with values
between 5.0 and 25.5.
TEXT _VER |Version No.| AT X 3 Y 8 WID 3 INT MIN 0
Text-entry box has the tag ‘Version No.’ and
has its origin at the form grid position (3, 8).
(continued)
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-47
GUI Command Reference
TEXT (continued)
Syntax:
.––––––––<––––––––.
/
|
>–– TEXT uname ––*–– <fmpos> ––––––––|
|
|
|–– text –––––––––––|
|
|
|–– CALLback text ––’
|
‘–– WIDth integer ––+–– SCRoll integer ––.
|
|
‘––––––––––––––––––––+–––NOEcho–––.
|
|
‘––––––––––––|
|
.––––––––––––––––––––<–––––––––––––––––––––––––––––––’
|
‘––+–– STRing –––––––––––––––––––––––––.
|
|
|–– NAMe –––––––––––––––––––––––––––|
|
|
|–– ISOu –––––––––––––––––––––––––––|
|
|
|–– NUMeric ––. .––––––––<––––––––. |
|
|/
| |
‘–– INTeger ––*–– MINimum value ––| |
|
| |
|–– MAXimum value ––’ |
|
|
‘–––––––––––––––––––––+––>
NOTE: The maximum scrollable length which the syntax allows ( SCRoll integer) is 132
characters and this is the default setting if you do not specify a length. Remember,
however, that the maximum length which you can read into a PML text variable is 120
characters, so in most cases it makes sense to set a scroll length of no more than 120.
21-48
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
TEXTPANE
Mode:
Form Setup mode.
Function:
Defines a text pane gadget.
Description:
Specifies the position and tag for a text pane gadget. 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.
Examples:
TEXTPANE _DAT |Comments|
Creates a text pane gadget for user
comments.
Syntax:
.––––––––<––––––––.
/
|
>–– TEXTPane uname ––*–– text –––––––––––|
|
|
|–– <fmpos> ––––––––’
|
‘–– <vshap> ––––––––––––––+–––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-49
GUI Command Reference
TITLE
Mode:
Form Setup mode.
Function:
Defines title of form, to be displayed in the banner across the top of the form.
Examples:
TITLE |Representation|
Syntax:
>–– TITLe text ––>
21-50
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
TOGGLE
Mode:
Form Setup mode.
Function:
Defines a toggle gadget.
Description:
Specifies the position, tag, and callback text of a toggle gadget. Also allows you to
specify different text strings for the default ‘On’ and ‘Off’ states.
Examples:
TOG _TOG1
Toggle _TOG1 has default states ‘Off’ and ‘On’.
TOG _TOG2 STATES |Head| |Tail|
Toggle _TOG2 returns the string ‘Head’ when it is
Off (raised) and ‘Tail’ when it is On (pressed down).
TOG _MODE |Mode| CALL |$$M /ROUTE.MAC| STATES |FORWARD| |BACK|
Toggle _MODE has tag ‘Mode’. When Off (raised)
value is ‘FORWARD’; when On (pressed down)
value is ‘BACK’. The value thus set would normally
be used as a parameter in the macro /ROUTE.MAC
which is run by the callback string.
Related Commands:
RADIOGROUP
Syntax:
.–––––––<––––––––––––––––––––––––––––––.
/
|
>–– TOGgle uname ––*–– <fmpos> –––––––––––––––––––––––––––––|
|
|
|–– text ––––––––––––––––––––––––––––––––|
|
|
|–– CALLback text –––––––––––––––––––––––|
|
|
|–– PIXmap –– name –– name ––+––<vshap>––|
|
|
|
|
‘–––––––––––’
|
|–– STATES text1 text2 –––––––––––––––––.
|
|
‘–––––––––––––––––––––––––––––––––––––––+––>
where textl corresponds to the Off setting _| and text2 corresponds to the On
setting
CADCENTRE Software Customisation
Reference Guide
Issue 1095
r .
CADCENTRE
Protected by copyright: see frontispiece
21-51
GUI Command Reference
TOGGLE (continued)
Defaults:
21-52
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.
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VALIGN
Mode:
Form Setup mode.
Function:
Assists with layout of gadgets on a form.
Description:
Works in conjunction with current path (see PATH command). Defines how a
newly added gadget should be aligned vertically with the preceding gadget.
Examples:
VALIGN T
VA B
Top edges of gadgets are to be aligned
Bottom edges of gadgets are to be aligned
Related Commands:
HALIGN
HDISTANCE
PATH
VDISTANCE
Syntax:
>–– VAlign ––+–– Top –––––.
|
|
‘–– Bottom ––+––>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-53
GUI Command Reference
VARIABLE
Mode:
Application-wide.
Function:
Sets values of form variables (for single-valued gadgets).
Description:
A variation of the standard VARIABLE command. Allows you to set values for
named single-valued gadgets.
Examples:
VAR _REPRE_PIPE.TOG1 INSUL
Sets value of named toggle gadget to
result of Q INSUL query (On or Off).
Related Commands:
VARIABLE LIST
VARIABLE SELECTOR
VARIABLE USERDATA
Syntax:
>–– VARiable uuname –– <varset> ––>
where <varset> represents either an explicit text string or any of the standard ways
of setting a variable (as explained in Part I Macros and Programmable Macros).
21-54
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VARIABLE LIST
Mode:
Application-wide.
Function:
Sets values of attributes for List Gadgets.
Description:
Puts you into List Setting mode, which allows you to set values for the display texts
and replacement texts of list gadgets. Also allows you to specify which options are
selected (highlighted) when the list is displayed. You remain in List Setting mode
until you use the EXIT command.
Examples:
VAR LIST _LIST2
CLEAR SEL
PAIRS |Red| |R100 G0 B0|
|Green| |R0 G100 B0|
|Blue| |R0 G0 B100|
SEL 3
ADD COL 9 COL 10
EXIT
Enters List Setting mode.
Clears all current selections. Does not affect
display or replacement texts.
Sets pairs of display texts and corresponding
replacement texts.
The third option in the list is selected when
the gadget is displayed.
Adds results of Q COL 9 and Q COL 1 0
queries to end of current list (as both display
text and replacement text).
Leaves List Setting mode.
Variations on above example'.
CLEAR
Clears all settings; i.e. current selections,
display texts and replacement texts.
SEL |Green| |Blue|
Selects options by their display texts rather
than by their list positions.
SEL NEXT
Selects the next option in a single choice list
or selector. An error will be generated if the
current field is the last.
SEL PREV
Selects the previous option in a single choice
list or selector. An error will be generated if
the current field is the first.
SEL LAST
Selects the last option in a single choice list.
Example of PML construct’.
VAR LIST _form_gadget
DO !x VALUES !array
ADD |$!x|
ENDDO
EXIT
This fills the list’s display texts from the
PML array variable Iarray.
(continued)
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-55
GUI Command Reference
VARIABLE LIST (continued)
Related Commands:
EXIT VARIABLE VARIABLE SELECTOR
VARIABLE PICK
VARIABLE USERDATA
Syntax:
.––––––––––––––––<––––––––––––––––––––.
/
|
>– VARiable LIST uuname –*– CLEar –+– SELections ––––––––––––––––|
|
|
|
|
‘– nl ––––––––––––––––––––––––|
|
|
|
.––––<–––––––––––––––.
|
|
/
|
|
|– SELect –*– integer ––––––––––––|
|
|
|
|
|
|
|– NEXT –––––––––––––––|
|
|
|
|
|
|
|– PREVious –––––––––––|
|
|
|
|
|
|
|– LAST –––––––––––––––|
|
|
|
|
|
|
|– text –––––––––––––––|
|
|
|
|
|
|
|
|–REPLacement – text ––|
|
|
|
|
|
‘– nl –––––––––––––––––+–––––|
|
|
|–––––<pml>–––––––––––––––––––––––––––––|
|
|
|
.––––––––<––––––––––.
|
|
/
|
|
|– PAIRS –*– <varset> <varset> –|
|
|
|
|
|
|
‘– nl ––––––––––––––––+–––––––|
|
|
|
.––––<–––––.
|
|
/
|
|
|– ADD –*– <varset> –|
|
|
|
|
|
|
‘– nl –––––––+––––––––––––––––––’
|
‘– EXIT –––––––––––––––––––––––––––––––––––>
where <varset> represents either an explicit text string or any of the standard ways
of setting a variable (as explained in Part I Macros and Programmable Macros').
<pml> represents any PML constructs.
NEXT allows the next field to be selected for a single valued list. If there is no
previous current field, the first will be selected.
PREVIOUS allows the previous field to be selected for a single valued list. If there
is no previous current field, an error will be generated.
LAST allows the last field to be selected for a single valued list. If the current field is
the last field, an error will be generated.
21-56
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VARIABLE PICK
Mode:
Form Setup mode.
Function:
Reads the identifier of a picked PDMS element into a variable. If the element is a
pline, the pline definition can also be stored.
Description:
The VAR command can be used to store identifiers of PDMS elements and pline
definitions in variables. The following formats of the command store values in
simple variables:
VAR varjd ID @ stores the identifier of the picked element.
VAR varjd I DPP @ stores the identifier of the picked p-point.
VAR varjd IDPL @ stores the identifier of the picked pline.
The VAR varjd PICK format of the command creates an array variable in which
the first element contains the identity of the PDMS element picked. The second
element contains the PDMS line definition of the 3D line through the PDMS
model which was used to pick the item. This line definition may be used as further
input to the CONSTRUCT command, also known as the Geometric Calculator.
You can specify whether any element can be picked, or restrict the pick to p-points
or plines.
The command VAR varjd PICK PL WITH <select> allows you to specify selection
criteria when picking plines. Only the plines which satisfy the criteria are
highlighted on the screen, and only those lines can be picked. If no criteria are
given, any pline may be picked.
When a pline is being picked, the user holds down the SELECT mouse button and
moves the cursor over a pline, the prompt box shows the PKEY attribute of the
pline. This gives information about which pline will be picked when <MB1>
(mouse button 1, i.e. the SELECT button) is released. This is important when
trying to choose between several plines which are close together.
Examples:
VAR !PLIN PICK PLINE
which prompts the user to pick any pline from all
sections (SCTNs) visible on screen;
VAR !REFLIN PICK PLINE WITH ( PURP EQ ’REFERENCE’ )
VAR !ITEM PICK
which prompts the user to pick a pline. Only plines which
have the attribute PURP equal to the value
‘REFERENCE’ in their catalogue definition will be
pickable.
which prompts the user to pick any visible item on the
screen.
Related Commands:
VARIABLE LIST
CADCENTRE Software Customisation
Reference Guide
Issue 1095
VARIABLE USERDATA
CADCENTRE
Protected by copyright: see frontispiece
VARIABLE SELECTOR
21-57
GUI Command Reference
VARIABLE PICK (continued)
Syntax:
>– VARiable <varid> ––+–– ID @ ––––––––––––––––––––––––––––––––––––+
|
|
|–– IDPLine @ –––––––––––––––––––––––––––––––|
|
|
|–– IDPPoint @ ––––––––––––––––––––––––––––––|
|
|
‘–– PICK ––––+–––––––––––––––––––––––––––––––|
|
|
|–– PPoint –––––––––––––––––––––|
|
|
‘–– PLine ––+–––––––––––––––––––|
|
|
‘––– WITH <select>––+––>
21-58
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VARIABLE SELECTOR
Mode:
Application-wide.
Function:
Sets values of attributes for selector gadgets.
Description:
Puts you into Selector Setting mode, which allows you to set values for the listed
options of selector gadgets. You remain in Selector Setting mode until you use the
EXIT command.
Examples:
VAR SELEC _SELEC3
CLEAR
OWNER CE MEM
Enters Selector Setting mode.
Clears all current settings
Sets selector options in sequence to owner of
CE, CE itself, and members of CE (i.e. sets
up a database members list).
Leaves List Setting mode.
EXIT
Related Commands:
EXIT
VARIABLE LIST
VARIABLE PICK VARIABLE USERDATA
Syntax:
.–––––<––––––.
/
|
>–– VARiable SELector uuname ––*–– CLEar –––––|
|
|
|–– <varset> ––’
|
‘– EXIT –>
where <varset> represents either an explicit text string or any of the standard ways
of setting a variable (as explained in Part I Macros and Programmable Macros).
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-59
GUI Command Reference
VARIABLE USERDATA
Mode:
Application-wide.
Function:
Setting values of data, to be stored in the _USERDATA gadget.
Description:
Sets values of the list items in a userdata gadget. Also allows you to select a specific
item in the userdata list as the current selection (referenced by its index; i.e. its
position in the list order).
Examples:
If the userdata gadget is on the current form, the form name need not be given.
VAR USER _REPRE CLEAR
Clears all settings from userdata list of form
_REPRE, leaving a single blank field.
VAR USER _REPRE |newtext|
Overwrites existing setting of current field
with string ‘newtext’. Field remains current.
VAR USER _REPRE XLEN 3
Overwrites existing setting of field 3 of
userdata list by XLEN of current element.
VAR USER ADD YLEN
Appends YLEN of current element to the
existing userdata list of current form and
makes the new data field current.
VAR USER ADD |datastring|
Appends text string ‘datastring’ to userdata
list of current form (since no uname given)
and makes the new data field current.
VAR USER SEL 2
Makes second field in userdata list on the
current form become the current selection.
VAR USER _REPRE DEL 4
Deletes fourth data field. Subsequent fields
are renumbered automatically. If fourth field
was current, fourth field remains current (but
now has value previously held by fifth field).
$_USERDATA
Reads value stored in current field of
userdata list of current form.
Related Commands:
VARIABLE LIST
21-60
VARIABLE SELECTOR
CADCENTRE
Protected by copyright: see frontispiece
VARIABLE PICK
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VARIABLE USERDATA (continued)
Syntax:
>–– VARiable USERdata –+– uname –.
|
|
‘–––––––––+– CLEar ––––––––––––––––.
|
|
|– <varset> –.
|
|
|
|
|– DELete –––+– integer –|
|
|
|
|
‘–––––––––––|
|
|
|– ADD –– <varset> ––––––|
|
|
‘– SELect integer –––––––+––>
where <varset> represents either an explicit text string or any of the standard ways
of setting a variable (as explained in Part I Macros and Programmabale Macros).
If the userdata gadget is on the current form, the form name need not be given.
NOTE: An ‘empty’ userdata gadget (such as results from a VAR USER ... CLEAR command)
always contains a single field which is current. In such a case:
•
The command VAR USER ... |string–A| will overwrite the current field and
store the text ‘string— A in field 1. Field 1 will remain current.
•
The command VAR USER ... ADD |string–B| will append a new field and will
store the text ‘string— B’ in field 2. Field 2 will become current.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-61
GUI Command Reference
VDISTANCE
Mode:
Form Setup mode.
Function:
Assists with layout of gadgets on a form.
Description:
Works in conjunction with current path (see PATH command). Defines how a
newly added gadget should be spaced vertically with respect to the preceding
gadget.
Examples:
VDIST 3
Distance from top of new gadget to bottom of preceding
gadget is to be 3 grid units (if current Path is Down)
Related Commands:
HALIGN
HDISTANCE
PATH
VALIGN
Syntax:
>–– VDistance value ––>
21-62
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VIEW
Mode:
Form Setup mode.
Function:
Enters a View Setup mode. Must be qualified by a further command word (ALPHA,
AREA, PIXMAP, PLOT or VOLUME) defining the type of view which is to be set up.
Description:
Forms part of a composite command which enters one of the View Setup modes.
You remain in the chosen View Setup mode until you use the EXIT command.
Examples:
VIEW _V1 AT X3 Y4 |Model| VOL
EXIT
Enters Volume View Setup mode.
Any definition commands listed
under VOLUME options (q.v.)
Returns to normal Form Setup mode.
Related Commands:
ALPHA
AREA
EXIT
PIXMAP
PLOT
VOLUME
EDIT
Syntax:
.–––––<–––––.
/
|
>–– VIEW uname ––*–– <fmpos> ––|
|
|
|–– text –––––’
|
See ALPHA command
|–– ALPha –– nl ––>
|
|–– AREa –– nl ––> See AREA command
|
See PIXMAP command
|–– PIXmap –– nl ––>
|
See PLOT command
|–– PLOt –– nl ––>
|
‘–– VOLume –– nl ––> See VOLUME command
These leave you in Alpha View Setup mode, Area View Setup mode, Pixmap View Setup mode,
Plot View Setup mode, or Volume View Setup mode, respectively. The command syntax available
in these modes is described separately under the headings ‘ALPHA options’, ‘AREA options’,
‘PIXMAP options’, ‘PLOT options’ and ‘VOLUME options’.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-63
GUI Command Reference
VOLUME options (PDMS DESIGN only)
Mode:
Volume View Setup mode (see the VIEW command).
Function:
Defines a volume view.
Description:
The VIEW ... VOLUME command puts you into Volume View Setup mode, where
you may define a volume view gadget using the syntax described here. You remain
in Volume View Setup mode until you use the EXIT command.
Examples:
VIEW _COMMAND VOL
WID 25
HEI 12
BORD OFF SHAD ON
SETC RED
SETHI 5
LIM AUTO
LOOK THROUGH /NOZZA
EXIT
Enters Volume View Setup mode.
Sets width to 25 characters.
Sets height to 12 lines.
Sets display options.
Defines background colour.
Defines highlight colour for ‘picked’ items.
Sets automatic updating of limits.
Sets through point for view direction.
Returns to Form Setup mode.
Related Commands:
EXIT VIEW
(continued)
21-64
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VOLUME options (continued)
Syntax:
.––––––––––––––––––––––<––––––––––––––––––––––.
/
|
(VOLume) ––*–– <vshap> –––––––––––––––––––––––––––––.
|
|
|
|
|–– BORDers ––––––.
|
|
|
|
|
|
|–– SHADing ––––––+–– ON –––.
|
|
|
|
|
|
|
|
‘–– OFF ––+––––––––––––|
|
|
|
|
|–– LIMits ––+–– AUTO* –––––––––––––––. |
|
|
|
| |
|
|
‘–– LOCAL ––+–– <lims> ––+––|
|
|
|
|
|–– SETColour –– <colno> ––––––––––––––––|
|
|
|
|
|–– SETHighlight –– <colno> –––––––––––––|
|
|
|
|
|–– <cursor> ––––––––––––––––––––––––––––|
|
|
|
|
|–– <viewdir> –––––––––––––––––––––––––––+– nl –|
|
|
|–– <pml> ––––––––––––––––––––––––––––––––––––––’
|
‘–– EXIT ––>
<lims> either specifies two opposite corners of a limits box explicitly, or
calculates the limits box needed to completely contain one or more named design
elements. It has the syntax
>––+–– <pos> –– TO –– <pos> ––>
|
|
.––––<––––.
|
/
|
‘––*–– <gid> ––+––>
e.g.
N1000 E2500 U0 TO N3000 E5000 U2000
/EQUI2 /EQUI4 /BRAN2–1
<viewdir>, which defines the view direction for the displayed model, has the
syntax
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
21-65
GUI Command Reference
VOLUME options (continued)
>––+–– LOok ––+–– <dir> –––––––––––––––––––––.
|
|
|
|
|–– THRough–––.
|
|
|
|
|
|
|–– FROM –––––|
|
|
|
|
|
|
‘–– TOWards ––+–– <pos> ––––. |
|
|
| |
|
|–– <gid> ––––| |
|
|
| |
|
‘–– ID @ nl ––+––|
|
|
|–– ISOmetric ––+–– value ––.
|
|
|
|
|
|
‘–––––––––––+–––––––––––––|
|
|
|–– PLAN –––––––––––––––––––––––––––––––––|
|
|
|–– ELEVation –– (one of N/S/E/W/X/Y) ––––|
|
|
|–– CLIPping –––––+–– ON ––.
|
|
|
|
|
|
‘–– OFF –+––––––––––––––|
|
|
|–– CAPping ––––––+–– ON ––.
|
|
|
|
|
|
‘–– OFF –+––––––––––––––|
|
|
|–– PERSPective ––+–– ON ––.
|
|
|
|
|
|
‘–– OFF –+––––––––––––––|
|
|
|–– WALKthrough ––+–– ON ––.
|
|
|
|
|
|
‘–– OFF –+––––––––––––––|
|
|
|––RADius ––– value ––––––––––––––––––––––|
|
|
|––STEP ––––– value ––––––––––––––––––––––|
|
|
‘––RANGE –––– value ––––––––––––––––––––––+–––>
<colno> is any valid DESIGN colour definition; either a colour description or a
colour number.
< cursor > controls the cursor type:
>–– CURSortype
21-66
––+–– POINTER ––––.
|
|
|–– NOCURSOR –––|
|
|
|–– PICK –––––––|
|
|
|–– PICKPLUS –––|
|
|
‘–– CROSSHAIR ––+––––>
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Command Reference Section
VOLUME options (continued)
Defaults:
Borders:
Shading:
View direction:
Limits:
CADCENTRE Software Customisation
Reference Guide
Issue 1095
On.
Off.
Plan or Look Down.
Auto (set to current view limits).
CADCENTRE
Protected by copyright: see frontispiece
21-67
GUI Command Reference
WAITON
Mode:
Application-wide.
Function:
Displays a blocking form.
Description:
Forms are normally displayed automatically as a result of picking a menu field or
button gadget. The WAITON command allows you to display a blocking form
explicitly from within a macro. Macro execution will pause at this point until the
form has been actioned and removed.
Examples:
WAIT _SELNOZ
Shows form SELNOZ at the default
position.
WAIT _REPRE AT XR .5 YR .75
Shows form _REPRE with its top
left-hand corner at the specified screen
position.
Related Commands:
SHOW MENU BUTTON
Syntax:
>–– WAITon uname ––+–– AT –– <xypos> ––.
|
|
‘–––––––––––––––––––+––>
Defaults:
Default position, if the AT option is not used, is with the top centre of the form at
screen coordinates (0.5, 0.15); i.e. just below top centre of screen.
NOTE: CADCentre recommends that you bring up forms from menus and buttons rather than
using WAITON (or SHOW) from macros.
21-68
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Part III
Using Query to Communicate with
Data Servers
22
Using QUERY to Communicate With Data
Servers
This chapter explains the commands available within CADCentre Query for accessing data in a
remote source via a data server; either to read data settings from, or to write data settings to, the
data server. It also explains how you can store and manipulate the results of querying such data
within CADCentre Query.
NOTE: In order to use the facilities described in this chapter, a server daemon must have been
built for each type of server with which you wish to communicate. Such daemons must
conform to the standards described in the Query Daemon Toolkit Reference Manual. The
maximum number of communication channels which may be open simultaneously is
controlled by the terms of your site licence.
22.1
Directing Commands to the Data Server
In order to direct any command line from CADCentre Query to a data server, prefix the line with
the word
EXTERnal
The remaining part of the line may comprise either:
•
A command to create a connection between CADCentre Query and the data server
•
A command sequence for reading from or writing to the data server
This prefix in incorporated into all commands described in the remainder of this chapter.
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-1
22.2
Connecting CADCentre Query to a Data Server
Before commands can be sent from CADCentre Query to any data server, a link must be set up
between the two.
► To connect CADCentre Query to a data server which is installed on the same machine, use
one of the commands
EXTERnal OPEn synonym token_yar
EXTERnal OPEn synonym token_yar [AS connect_string]
where synonym is a text string which identifies the server daemon through which communication is
to be channelled (and which therefore identifies the data server required); token_var is the name of
a PML variable into which a token for the connection is to be written; and (if your data server
requires login data) connect_string is a text string which confirms your access rights (such as your
username and password). For example,
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT AS ’silk/colin’
► To connect CADCentre Query to a data server which is installed on a different machine, use
the extended form of the command
EXTERnal OPEn synonym token_yar ON host [AS connect jitring]
where synonym is a text string which identifies the server daemon through which communication is
to be channelled (and which therefore identifies the data server required); token_yar is the name of
a PML variable into which a token for the connection is to be written; host is a text string which
identifies the node on the network on which the server daemon resides; and connect _string is a text
string which confirms your access rights to the data (such as your username and password). For
example, to connect to a data server on a machine called sg35, enter
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT ON ’sg35’ AS ’silk/colin’
or, alternatively, a generalised version such as
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT ON ’sqlnet’ AS ’silk/colin’
where the alias ‘sqlnet’ has been defined so as to point to the current host for, say, an SQL database
server.
► To disconnect CADCentre Query from a data server to which it is currently connected, use the
command
EXTERnal CLOse token
where token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token_yar variable). For example,
EXTERnal CLOse $!!MAINT
22-2
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
(Note the $ prefix used to expand the variable HMAINT to give the token value.)
22.3
Sending Commands to a Data Server
NOTE: It is assumed that you are already familiar with the commands for communicating with
your data server; for example, the SQL commands needed to interact with an SQL
database.
You may send commands to the data server in one of two ways:
•
As individual command lines, each of which is sent as soon as the newline character is entered
to terminate the command line.
•
In continuous mode, such that a sequence of command lines is concatenated and sent as a
single command string. The maximum length for an individual command line is 120
characters; continuous mode allows you to send longer command sequences.
►
To send an individual command line to the data server, simply prefix the command text thus:
EXTERnal SENd token commandJext
where token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token jar variable) and commandJext is the
command string to be sent to the data server. For example,
EXTERNAL SEND $!!MAINT ’commit’
►
To send a continuous command sequence to the data server, use the syntax
EXTERnal SENd token STArt
command Jext _1
commandJext _2
END
where token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token jar variable) and commandJext J etc. are
the command strings to be sent to the data server. For example,
EXTERNAL SEND $!!MAINT START
’select refno, description, datedue’
’from maintdata’
’where datedue<sysdate+7’
END
where each line of command text is terminated by a newline character.
When the END command is reached, all text lines entered since START are concatenated, with a
space separator between each, and sent to the data server as a single command.
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-3
NOTE: Command texts may include references to PML variables.
The maximum length for a single text line is 120 characters.
The maximum total length for the overall text string (that is, all lines between the START
and END commands) is 4095 characters., including the separating spaces.
22.4
Setting Variables from the Data Server Responses
All of the standard syntax for setting variables, as described in Part I of this guide, is available for
use within CAD Centre Query. In addition, CAD Centre Query incorporates extra syntax for
setting variables to data values returned from a data server.
To set a variable to the result of a data server query, use the syntax
VAR vamame EXTERnal GET token NEXT
where token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token_yar variable). The variable vamame will be
interpreted automatically as an array variable and each data item will be stored in a separate
element of the array. (The PML SPLIT command is not required here; splitting is carried out
automatically.)
NOTE: No data field should be longer than 120 characters, since this is the maximum permitted
length that can be stored in a variable. If a data field exceeds 120 characters, nothing will
be returned by the query.
As an example, the querying command
EXTERNAL SEND $!!MAINT ’select refno, servint, lastserv from maintdata’
VAR !datarow EXTERNAL GET $!!MAINT NEXT
might return the following results:
$!datarow[1]
$!datarow[2]
$!datarow[3]
C1101
182
22–AUG–94
(first value of field refno)
(first value of field servint)
(first value of field lastserv)
Repeating the command
VAR !datarow EXTERNAL GET $!!MAINT NEXT
will retrieve the next data record, which will progressively overwrite the current settings of the
array element elements. For example,
$!datarow[1]
$!datarow[2]
$!datarow[3]
22-4
E1201
31
07–JUL–94
CADCENTRE
Protected by copyright: see frontispiece
(second value of field refno)
(second value of field servint)
(second value of field lastserv)
Issue 1194
CADCentre Software Customisation
Reference Guide
and so on for subsequent data records. If the newly read record has less completed fields than the
preceding record, some elements of the array variable will remain with their previous settings
unchanged.
You can control the writing of data to an array variable explicitly by using the variable-setting
syntax described in Part I of this guide. For example, to read in a record such that its first field is
stored in element 10 of the array variable, rather than starting from element 1 by default, you could
use the syntax
VAR !datarow[10] EXTERNAL GET $!!MAINT NEXT
To read a record and append the resulting data to the array variable, rather than overwriting the
current settings of the array elements, you could use the syntax
VAR !datarow APPEND EXTERNAL GET $!!MAINT NEXT
and so on.
The most convenient way to retrieve multiple data records is usually to incorporate the NEXT
command into a PML ‘infinite’ DO loop construct, reading one data record during each cycle of the
loop. When the last record has been read in, the next cycle of the loop will generate the message
(79, 10) No more data
(see Section 8.2) which can be dealt with by using the PML HANDLE facility. For example:
EXTERNAL SEND $!!MAINT ’select * from maintdata’
DO
VAR !datarow EXTERNAL GET $!!MAINT NEXT
HANDLE (79, 10)
BREAK
ENDHANDLE
PML commands
...
ENDDO
(These facilities are explained more fully in Part I of this guide, Macros and Programmable Macros.)
► To store the column headings returned by a data server query in an array variable, use either
version of the following syntax:
VAR vamame EXTERnal GET tote RESult
VAR vamame EXTERnal GET/oAm HEADer
These commands always return the first row of the result of the last request sent to the data server
identified by token (typically, but not necessarily, header information resulting from an SQL
database SELECT command).
For example, the querying command
EXTERNAL SEND $!!MAINT ’select * from maintdata’
VAR !header EXTERNAL GET $!!MAINT RESULT
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-5
might return the following results:
$!header[1]
$!header[2]
$!header[3]
refno
servint
lastserv
NOTE: As with the data fields, no heading should be longer than 120 characters. If a heading
exceeds 120 characters, nothing will be returned by the query.
22.5
Specifying the Data Field Delimiter
When data is sent from a data server to CADCentre Query, it is sent as a single data block. Each
data field within the block is delimited by a special character; by default, this is the ~ (tilde)
character. When CADCentre Query receives the block, it uses the delimiter character to
determine the points at which to split the data into individual fields. If your data includes the
delimiter character within a text field, CADCentre Query will split the data block at the wrong
point.
For example, the data stored in the following fields:
Area
Plant
Code
Catalytic Cracker
Reflux~Heater
DES21142
would be received by CADCentre Query, using the default
delimiter, as the data block
Catalytic Cracker~Reflux~Heater~DES21142
and would be split, incorrectly, into the fields
$!a[1]
$!a[2]
$!a[3]
$!a[4]
Catalytic Cracker
Reflux
Heater
DES21142
To prevent this effect, you can redefine the delimiter character to be any single character which is
not used within any database field. To do so, use the command
EXTERnal DELImit token text_char
where token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token_yar variable) and text_char is the required
data field delimiter character.
For example, the specification
EXTERNAL DELIMIT $!!MAINT ’&’
22-6
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
would cause the data block from the preceding example to be received as
Catalytic Cracker&Reflux~Heater&DES21142
which would be correctly split at the points identified by the & characters.
22.6
Handling Returned Errors
Errors which can be trapped and handled specifically by CADCentre Query may result in one of
the following error messages (where info represents any supplementary information about the
error which is generated by the data server or the communications software).
Server Daemon Messages:
(79, 3)
Cannot initialise server daemon: info
For example, the server daemon executable cannot be found via any of the
expected directory paths
(79, 4)
Cannot connect to data server: info
For example, an invalid password has been used
(79, 5)
Cannot send request to data server: info
For example, a networking problem has interrupted communications (info will
show the request that has failed)
(79, 6)
Error returned: info
Reason appended to the message by the data server
(79, 7)
Request failed: info
For example, an invalid data server command has been entered
(79, 8)
Cannot fetch next row: info
For example, a network interruption or a data server error has occurred while
waiting for the result of an EXTERNAL GET ... NEXT request (see Section 22.2)
(79, 9)
Command is too long
The command has exceeded the limit of 4095 characters (don’t forget the
separating spaces when summing the lengths of the individual command strings)
(79, 10) No more data
For example, the most recent EXTERNAL GET ...NEXT command has failed
because there are no more rows of data to retrieve. This is a very useful error
number to trap, since it allows you to use an infinite DO loop to retrieve
consecutive rows from a table of any length and then to escape when all the rows
have been read; you will find an example of the syntax for doing this in Section
22.2.
The text of a data server error message is usually explicit, since it is generated from the database,
and so its meaning, and the method of resolving it, should be clear. For example, if you are
communicating with an ORACLE database, the command
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-7
EXTERNAL SEND $!!MAINT ’select * from emp’
could result in the error
(79, 7) Request failed: ORA–00942: table or view does not exist
Similarly, the command
EXTERNAL SEND $!!MAINT ’seelect * from emp’
could result in the error
(79, 7) Request failed: ORA–00904: invalid SQL statement
Communications Software Messages:
NOTE: These are most likely to be caused by general network problems rather than by
CADCentre Query itself.
(79, 51) Cannot initialise remote process query
(79, 52) Connected to data server
(79, 53) Data server released
For information only;
cannot be ‘handled’
(79, 54) Cannot set delimiter character: info
(79, 55) Cannot terminate server daemon: info
(79, 56) Daemon file incorrect or missing
(79, 57) Unknown daemon synonym: info
Check that you have entered the required synonym correctly and that it is included
in the daemon_file
(79, 58) Cannot toggle tracing in server daemon: info
(79, 59) No licences available for remote process query
The maximum number of communication channels (daemons) permitted by your
licence are already open. Close an unwanted channel if possible
(79, 60) Remote process query security error: info
Contact CADCentre Support for advice
(79, 63) Server daemon has shut down because a FATAL error was detected
22-8
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
22.7
Toggling Server Daemon Tracing Facilities
To toggle on or off any tracing facilities built into a server daemon, use the command
EXTERnal TOGgle token TRAce
where token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token_yar variable).
EXTERNAL TOGGLE $!!MAINT TRACE
(This facility is provided as an aid for developers using the CADCentre Query Daemon Toolkit.)
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-9
Command Reference Section
This section gives detailed information on how to use the relevant commands for using
CADCentre Query to communicate with other data servers.
The commands described in the main part of this appendix have their legal command and
interrogation options presented in the form of syntax diagrams. These diagrams formalise the
precise command sequences which may be used and supplement the explanations given in the
appropriate sections of this manual.
The following conventions apply to the syntax diagrams in this appendix:
•
Names written in lowercase letters enclosed in angled brackets (e.g. < direction >) represent
subsidiary syntax diagrams. Such names are used for cross-reference purposes within other
syntax diagrams.
•
Commands to be input from the terminal are shown in a combination of uppercase and
lowercase letters. In general, these commands can be abbreviated; the capital letters indicate
the minimum permissible abbreviation. (NOTE: This convention does not mean that the
second part of the command must be typed in lowercase letters; commands may be entered in
any combination of uppercase and lowercase letters.)
For example, the command
CONnect
may be input in any of the following forms:
CON
CONN
CONNE
CONNEC
CONNECT
Commands shown wholly in uppercase letters cannot be abbreviated.
•
Names written in lowercase italics are command arguments.
•
Syntax diagrams are generally read from top left to bottom right.
•
Points marked with a plus sign ( + ) are option junctions which allow you to input any one of the
commands to the right of the junction. Thus
>–––+––– ABC –––––.
|
|
|––– PQR –––––|
|
|
|––– <dia> –––|
|
|
‘–––––––––––––+–––>
means you may type in ABC or PQR or any command allowed by the syntax given in subsidiary
syntax diagram <dia> or just press RETURN to get the default option.
22-10
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
•
Points marked with an asterisk (*) are loop back junctions. Command options following these
may be repeated as required. Thus
.–––––<–––––––.
/
|
>–––*––– option1 –––|
|
|
|––– option2 –––|
|
|
‘––– option3 –––+–––>
permits any combination of optionl and/or option2 and/or option3 to be used (where the options
may define commands, other syntax diagrams, or command arguments). This may form an
exception to the rule of reading from top left to bottom right.
The simplified format
.––––<–––––.
/
|
>–––*––– name –––+–––>
means that you may type in a list of PDMS names, separated from each other by at least one space.
NOTE: The need to press the Return (or Enter) key to complete each command line is implicit in
all syntax diagrams and is not usually shown. Only in cases where the need to press
Return/Enter has some particular significance is this indicated specifically by the
abbreviation nl.
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-11
22.8
Command Arguments
These are inputs which are necessary to qualify command words. They are distinguished by
appearing in italics.
Name
filename
int
name
nodeid
text
val
varid
nl
22.9
Deflnition
The pathname of a file
A positive integer
An element name
A host machine identifier
An alphanumeric string
A positive or negative number
A variable identifier
New line
Example
/DATLISTS/SITE1
0, 3
/ABCD
’sg36’
’Enclose between quote marks’
3.142, -23.66, -34
3, !NAME
Press Return or Enter key (depending on
your workstation keyboard)
The Commands
The information is given under the following headings:
Description:
A brief explanation of what the command enables you to do and when you might use it.
Example:
Examples of the permitted command variations. (Examples are omitted in trivial cases.)
Syntax:
The full command syntax, given in diagrammatic form.
22-12
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
CLOSE
Description: Disconnects CADCentre Query from a specified data server (to which it is currently
connected, via a server daemon, as a result of an OPEN command).
Example:
EXTERNAL CLOSE !!MAINT
Syntax:
>–– EXTERnal –– CLOse –– token ––>
where:
token is the token for the communication channel which was supplied by a successful OPEN
command and which is stored in a variable.
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-13
DELIMIT
Description: Allows you to specify the delimiting character which separates the individual data
fields when querying a specified data server. The default delimiter is the ~ (tilde)
character.
Example:
EXTERNAL DELIMIT $!!TOK_VAR ’&’
Syntax:
>–– EXTERnal –– DELImit –– server_token –– text_char ––>
where serverJoken is an integer identifying the required data server channel and text is a single
character only.
NOTE: You must choose a delimiting character which does not occur within any data, otherwise
CADCentre Query will split the incoming data string in the wrong place.
22-14
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
END
Description: Terminates the sending of a long command string to a data server.
All command lines following a START entry will be concatenated to form a
composite command of any required length until terminated by a corresponding
END entry.
The maximum length for a single query line is 120 characters.
The maximum total length for the overall query string (i.e. all lines between the
START and END commands) is 4095 characters.
Example:
EXTERNAL SEND $!!MAINT START
’select refno, servint, lastserv from maintdata’
’where elementtype = ’’EQUIPMENT’’’
END
Note the use of multiple delimiting
characters for nesting text within text in this example.
You could, alternatively, write the example using ‘vertical bar’ text delimiters, thus:
EXTERNAL SEND $!!MAINT START
|select refno, servint, lastserv from maintdata|
|where elementtype = ’EQUIPMENT’|
END
Syntax:
.–––––<–––––––.
/
|
>–– EXTERnal –– SENd –– server_token –– START ––*–– text – nl ––+–– END ––>
where serverjoken is an integer identifying the required data server channel.
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22 — 15
EXTERNAL
Description: Allows you to send to a specified data server any valid text string which represents a
command to read from, or write to, a database.
For details of subsidiary commands relevant to EXTERNAL mode, see under the
following headings:
CLOSE
DELIMIT
END
GET
OPEN
SEND
START
TOGGLE
Example:
EXTERNAL SEND $!!MAINT ’select * from maintdata’
This sends the specified text string to the data server whose channel token is stored in the
variable HMAINT.
Syntax:
>–– EXTERnal –– ... ––>
22-16
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
GET
Description: Allows you to set to data values returned from a data server (using NEXT). Note that
all of the standard syntax for setting variables, as described in Part I of this guide, is
available for use within CADCentre Query.
Also allows you to store the column headings returned by a data server query in an
array variable (using RESULT or HEADER).
Example:
VAR !datarow EXTERNAL GET $!!MAINT NEXT
VAR !header EXTERNAL GET $!!MAINT RESULT
Syntax:
>– VAR – varname – EXTERnal – GET – token –+– NEXT –––––––.
|
|
|– RESult –––––|
|
|
‘– HEADer –––––+–––>
where:
token is the token for the communication channel which was supplied by a
successful EXTERNAL OPEN command (and stored in the token_yar variable).
vamame will be interpreted automatically as an array variable and each data item
will be stored in a separate element of the array. (The PML SPLIT command is not
required here; splitting is carried out automatically.)
NOTE: RESULT and HEADER commands always return the first row of the result of the last
request sent to the data server identified by token (typically, but not necessarily, header
information resulting from an SQL database SELECT command).
As with the data fields, no heading should be longer than 120 characters. If a heading
exceeds 120 characters, nothing will be returned by the query.
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-17
OPEN
Description: Connects CADCentre Query to a specified data server (via a server daemon).
Many communication channels may be open concurrently, each being identified by a
token (an integer) which is returned by the server and stored in a named variable for
subsequent reference.
Example:
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT AS ’silk/colin’
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT ON ’sg35’ AS ’silk/colin’
Syntax:
>– EXTERnal – OPEn – synonym – token_var –+– ON – hostid –.
|
|
‘–––––––––––––––+– AS – connect_string –.
|
|
‘–––––––––––––––––––––––+–>
where:
synonym is a text string which identifies the server daemon through which communication is to
be channelled. The synonyms must be defined in the daemon Jile — see Appendix B.
token_yar identifies a variable to be used to store the integer token returned by the server
when the communication channel is successfully opened. You use the setting of this variable
for all subsequent references to that server daemon.
hostid is a text string which identifies the node on which the server daemon resides (not
required if the daemon is running on the same node as CADCentre Query).
connect_string is any text string needed to allow you to connect/login to the data server
(typically a username and password).
22-18
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
SEND
Description: Allows you to send a command string to a specified data server.
You can send short command strings (up to 120 characters) within the SEND
command line, or you can concatenate multiple command strings by using the
START and END commands (g.v.).
Example:
EXTERNAL SEND $!!MAINT ’commit’
Syntax:
>–– EXTERnal –– SENd –– server_token –– text ––>
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-19
START
Description: Allows you to send a long command string to a specified data server (by extending
the SEND command).
All command lines following a START entry will be concatenated to form a
composite command of any required length until terminated by a corresponding
END entry.
The maximum length for a single query line is 120 characters.
The maximum total length for the overall query string (i.e. all lines between the
START and END commands) is 4095 characters.
Example:
EXTERNAL SEND $!!MAINT START
’select refno, servint, lastserv from maintdata’
’where elementtype = ’’EQUIPMENT’’’
END
Note the use of multiple delimiting
characters for nesting text within text in this example.
You could, alternatively, write the example using ‘vertical bar’ text delimiters, thus:
EXTERNAL SEND $!!MAINT START
|select refno, servint, lastserv from maintdata|
|where elementtype = ’EQUIPMENT’|
END
Syntax:
.–––––<–––––––.
/
|
>–– EXTERnal –– SENd –– server_token –– START ––*–– text – nl ––+–– END ––>
where serverjoken is an integer identifying the required data server channel.
22-20
CADCENTRE
Protected by copyright: see frontispiece
Issue 1194
CADCentre Software Customisation
Reference Guide
TOGGLE
Description: Allows you to toggle on or off any tracing facilities built into a server daemon.
(This facility is provided as an aid for developers using the CADCentre Query
Daemon Toolkit.)
Example:
EXTERNAL TOGGLE $!!MAINT TRACE
Syntax:
>–– EXTERnal –– TOGgle –– server_token –– TRAce ––>
Issue 1194
CADCentre Software Customisation
Reference Guide
CADCENTRE
Protected by copyright: see frontispiece
22-21
Part IV
Appendices
Product Specific Information
Appendix A
Communicating with PEGS
This chapter explains how to send commands to PEGS from the UI module FMLayer, and how to
handle any responses to these commands which may be returned from PEGS to FMLayer.
The PEGS commands available from FMLayer cover the full PEGS functionality, together with
some special commands for connecting to PEGS and for sending commands in batches.
A.1 Directing Commands to PEGS
In order to direct any command line to PEGS, prefix the line with the command
PEGS
The remaining part of the line may comprise either:
•
A command to create a connection between FMLayer to a current PEGS process
•
Any standard PEGS command sequence
This prefix is incorporated into all commands described in the remainder of this chapter.
A.2 Setting Connections Between FMLayer and PEGS
Before commands can be sent to PEGS from FMLayer, a link must be set up between the two
processes. Communication takes place by means of pairs of named Unix pipes, which are the
communication channels via which data is sent to and from PEGS. These connections will
normally be made by the UI macros.
PEGS CONNECT integer COMMANDS text
creates a connection to pipe number integer, with the pipe name text, for sending commands to
PEGS. Pipe integer becomes the current connection.
PEGS CONNECT integer RECORDING text
creates a connection to pipe number integer, with the pipe name text, for receiving commands from
PEGS. Pipe integer becomes the current connection.
CADCENTRE Software Customisation
Reference_Guide
CADCENTRE
Protected by copyright: see frontispiece
A-<
A —1
PEGS DISCONNECT integer
closes the connection to pipe number integer.
PEGS RECONNECT integer
changes the current pipe to number integer when more than one connection is active at the same
time.
A.3
Sending Commands to PEGS
All messages received while communicating with PEGS are echoed to the command window by
default (you can switch this off by using the PEGS ECHO OFF command). Some PEGS modules
will, however, send messages from their startup sequences before you enter any commands from
an application. In order to receive such messages, enter the command
PEGS STARTRECORDING
as your first input.
► To send any command directly to PEGS, simply enclose the command string between closing
quotes and prefix it with the word PEGS, thus:
PEGS ’command _string >
The responses received are stored in PML variables and array variables, from which the data can
be read and handled by the application macros. The variables used are as follows:
IIPEGS.RESULT
An array variable holding the whole of the response from PEGS in the
format ‘one message line per array element’.
IIPEGS.PROMPT
A variable holding the last line of the response only. By convention, this
often contains a context prompt to indicate the current PEGS command
status.
IIPEGS.QUERY
An array variable holding accumulated query lines selected from the
response to a PEGS command. This is only valid while PEGS is operating
in a question/answer sequence instead of the normal command processor
mode, such as when running a report interactively. The content of
!!PEGS.QUERY forms a text description of the next input required from
the user, such as ’output filename’. The answer will be sent to PEGS as the
next command. The end of the question/answer sequence is indicated by
!!PEGS.QUERY becoming unset after a question has been answered.
!!PEGS.NAME
A variable holding the last-but-one line of the response. By convention,
this often contains an element name to indicate the current PEGS
command status.
A-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
e ere
|ssue 1095
IIPEGS.ERROR
►
An array variable which holds error message lines selected from the
response to a PEGS command. That is, it holds those lines from
!!PEGS.RESULT which describe an error condition, if any.
To create a copy of the response to a PEGS command, use the command format
PEGS variable jd
5
command _string’
where variablejd defines an array variable. In this case variablejd will contain a copy of the
contents of ! JPEGS.RESULT, so that you can process the data in different ways within the
application macros..
► To instruct PEGS that the response to a command is required in a terse form only (that is, as
unformatted raw data), use the command formats
PEGS RAW 'command_strmg’
PEGS RAW variablejd 'command _string’
You might, for example, use this option with the P O S I T I O N command, from which an application
might need only the position-defining numbers without the usual associated text. The PEGS
command would then take the form
PEGS RAW ’POS’
► To send a sequence of PEGS commands in batch mode, rather than sending them one at a time
as they are entered, prefix each command with BATCH. Each such batch command is stored in a
buffer until a non-batch command is entered, at which point all commands from the buffer are sent
to PEGS in the order in which they were entered.
Batch mode entry provides a way of improving performance when entering a sequence of
commands which do not make enquiries of PEGS; that is, commands which do not generate output
messages which must be received back from PEGS. For example, the following batch sequence
adds Line elements to a PIDRAFT drawing:
PEGS BATCH ’ED’
PEGS BATCH ’LIN’
PEGS BATCH ’AT 100 100’
PEGS BATCH ’AT 100 400’
PEGS BATCH ’AT 400 400’
PEGS BATCH ’AT 400 100’
PEGS BATCH ’AT 100 100’
PEGS ’AT 100 100’
CADCENTRE Software Customisation
Reference Guide
Issue 1095
(non-batch command sends sequence to PEGS)
CADCENTRE
Protected by copyright: see frontispiece
A— 3
A.4 Some Special FMLayer Commands
In addition to the standard PEGS commands, there are some special commands as follows:
► To specify whether or not messages received from PEGS are echoed to the command window,
enter
PEGS ECHO ON
PEGS ECHO OFF
The default is PEGS ECHO ON.
►
To query the current state of a PEGS communication pipe, enter
PEGS LIST integer
where integer is the pipe number. The result gives details of the specified pipe and of the current
pipe; for example:
Command pipe is 1
#1 Command: Pipe.in
►
Recording: Pipe.out
To query the current state of all PEGS communication parameters, enter
PEGS LIST ALL
The result will have the following format:
Command pipe is 1
Echo on, Batch mode off, Results off
Sync Data on, Sync GUI on
#1 Command: Pipe.in
Recording: Pipe.out
(The Sync Data and Sync GUI settings are relevant for maintenance purposes only and may be
ignored.)
A.5 Handling Errors Returned from PEGS
The response from PEGS to an FMLayer command always includes the error status, which is made
up of nn, is the PEGS module number and mmmm, the error number. If the command produced no
errors, both nn and mmmm are set to zero.
If an error message is received, the application converts the PEGS error into an FMLayer error
with the standard format (78, m m m m m ) ... which can then be handled by the application macros.
For example, the PIDRAFT error message
PID7003 WARNING: Flow reversed at attachment point
A-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
is converted into the error message
(78,147003) WARNING: Flow reversed at attachment point
since PIDRAFT has the module number 14.
The PEGS module numbers returned in this way are as follows:
1
3
4
6
7
9
10
12
14
15
16
18
21
A.6
ACCESS (ACS)
PEGS Conversion Program (PCP)
DICTIONARY (DIC)
FORMFILLER (FOR)
LIBRARIAN (LIB)
LOOKUP (LUP)
MANAGER (MAN)
AUTONUMBER (AUT)
PIDRAFT (PID)
PLOT (PLO)
REPORT GENERATOR (REP) (compilation errors; RGC)
REPORT GENERATOR (REP) (interpretation errors; RGI)
SYMBOL EDITOR (SYM)
A Sample Application
The sample application displays the database attributes of the current edit context in PIDRAFT
and allows the attribute values to be modified. The application’s main form could be used for any
engineering item. The example used is of an equipment.
The example consists of:
•
A form definition macro to display the attributes form.
•
An initialisation macro to populate the form with data gathered from the PEGS database.
•
An action macro to set attribute values and delete attributes.
The form will only be displayed if the PIDRAFT current edit context is appropriate i.e. a
recognised engineering type. If the current context is not an item, the user is informed and the UI
returns to await further input.
If the current context is appropriate, the form initialisation macro obtains a listing of the item’s
attributes by issuing PEGS commands and displays them in the form using string manipulation and
Forms and Menus commands. The form has a ’current selection’, shown as the highlighted list
item, whose attribute name and value are displayed in the text edit boxes. The current selection can
be changed by clicking a different list item with the mouse.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
A— 5
The current selection can be altered by typing a new string into the edit box. This data will be set as
the new attribute value by issuing the appropriate PEGS command and the list will be updated to
reflect the change. Data whose type does not match the attribute definition is rejected.
The form has a ’CE’ button. If the user displays this form and then navigates elsewhere in the
database, the form still displays the attributes of the original context. On editing an attribute value
the change will still be applied to the original context. The CE button will update the form to the
current context. The macro calls to store and restore edit context can be seen in the listings. The
save and restore macros themselves are not shown. The ’Project’ button displays a child form
listing the project level attributes of the item.
A.6.1
Form definition listing
$(H
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
Copyright CADCentre Ltd 1994
Macro:
Author:
FATTRS
Phill Theze
$Revision: 3.1 $
Modified:–
Macro Generic Type: Form Definitions
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
$)
$(D
Form layout for the Attributes form
$)
KILL _PID.ATTRS
SETUP FORM _PID.ATTRS
TITLE |Attributes|
INIT |CALLPID IATTRS|
button _ITNAME | Item Name | call |CALLPID FNAME|
path right
para _DESC text || width 40 lines 1
path down
para _NULL
text _ATTR
string
path right
para _NAME
text _VALU
string
A-6
text ||
|| at x0 ymin+1 call |callpid MATTRS $<ATTR$>| width 12
width 25 lines 1
call |callpid MATTRS $<VALU$>| width 26 scroll 119
||
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
para
para
para
_ATTRT at xmin_ATTR
_NAMET at xmin_NAME
_VALUT at xmin_VALU
ymin–1 text |Attribute |
ymin
text |Description|
ymin
text |Value|
$* main ’panel’ gadget.
SELECTOR _MEM || at xmin_ATTR ymax_ATTR+.2 call |CALLPID MATTRS
$<SEL$>| WIDTH 70 LENGTH 14
path down
vdist0.5
path right
$* control buttons
BUTTON _DELE |Delete Attribute| at x0 ymax_MEM CALL |callpid MATTRS
$<DEL$>|
BUTTON _CE |CE| at xmax form * 0.5 – 0.5 * size ymin_DELE call |callpid
XATTRS|
BUTTON _PROJ |Project| at xmax form–size ymin_CE call |callpid XPATTRS|
BUTTON _DISMISS |Dismiss| at xmax form–size ymax_DELE+.5 call |hide
_PID.ATTRS| CANCEL
EXIT
$* End of Code
$.
A.6.1.1
initialisation macro listing
$(H
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
Copyright CADCentre Ltd 1994
Macro:
Author:
IATTRS
Phill Theze
$Revision$
Modified:–
Macro Generic Type: Initialisation
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
$)
$(D
Initialisation for Attributes form
$)
$* Initialiase Variables
var list _PID.ATTRS_MEM clear
exit
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
A— 7
VAR !!PEGS.RESULT DELETE
VAR !!ATTRS DELETE
!BLANK = |
|
$*Check We Have Something Selected
if (match(|$!!PEGS.NAME|,|Layer|) neq 0) then
return error 1 |Nothing Selected|
endif
$* return to original edit context
callpid USAVECE _PID.ATTRS
PEGS ECHO OFF
PEGS RAW !ATTRS ’IDENTIFY ATTRIBUTES’
$**************************************************************
$*****************
set form paras *************************
$* Get Key Attributes
PEGS ’IDENTIFY ATTRIBUTES’ $* !!PEGS.NAME not set by raw.
PEGS ECHO ON
var !PEGS.NAME (before(|$!!PEGS.NAME|,|ROTATION=[|))
var !KEY split |$!PEGS.NAME| |:|
var !REF
var !TYPE
(before(after(|$!KEY[1]|,|(|),|)|))
(trim(before(after(|$!KEY[1]|,|)|),|:|)))
$* Need to check for unnamed entities such as connections
$* Nozzles with a description
if(defined(!KEY[8]))then
var !PNMSRT (2)
elseif(defined(!KEY[7]))then
if ((|$!TYPE| eq |NZE| ) or $
(|$!TYPE| eq |NZA| ) or $
(|$!TYPE| eq |NOZ| ) or $
(|$!TYPE| eq |TER| )) then
var !PNMSRT (1)
var !KEY[1] |$!TYPE|
var !TYPE ||
else
var !PNMSRT (2)
endif
$* Connections without a name
elseif (undefined(!KEY[2])) then
var !KEY[2] |CON|
var !KEY[3] ||
var !KEY[4] ||
var !KEY[5] ||
var !KEY[6] ||
var !KEY[7] ||
var !PNMSRT (2)
A-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
else
var !PNMSRT (1)
var !KEY[1] |$!TYPE|
var !TYPE ||
endif
|$!KEY[$!PNMSRT]|
var !PTYPE
|$!!PROJ|
var !PROJ
($!PNMSRT + 1)
var !INDX
|$!KEY[$!INDX]|
var !AREA
($!PNMSRT + 2)
var !INDX
|$!KEY[$!INDX]|
var !CODE
($!PNMSRT + 3)
var !INDX
var !SERIAL |$!KEY[$!INDX]|
($!PNMSRT + 4)
var !INDX
var !SUFFIX |$!KEY[$!INDX]|
($!PNMSRT + 5)
var !INDX
var !SBREF |$!KEY[$!INDX]|
var _PID.ATTRS_DESC |($!REF)
$!PTYPE$N:$!PROJ$N:$!AREA$N:$!CODE$N:$!SERIAL$N:$!SUFFIX$N:$!SBREF|
set form paras *************************
$*****************
$**************************************************************
if (match(|$!ATTRS[1]|,|––>Text|) neq 0) then
var !!TEXTVAL delete
var !!TEXTVAL split |$!ATTRS[3]| |_|
do !INDEX from ( arraysize(!!TEXTVAL) – 2 ) to $!!LTEXTL
var !!TEXTVAL APPEND ’’
enddo
hide _PID.ATTRS
show _PID.LTEXT
return
endif
$* Get Attributes for form
if (match(|$!!PEGS.PROMPT|,|GE|) neq 0) then
PEGS ’OWNER’
endif
var !COUNT (0)
$*** Unowned GE’s have no attributes.
if (match(|$!!PEGS.PROMPT|,|GE|) neq 0) then
error |Can’t display attributes for an
unowned Graphical Element.|
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
A— 9
return
endif
$* first two entries are item name + ref. no.
$* last two are name + prompt.
do !X from 3 to (arraysize(!ATTRS) – 7) by 7
var !ATTNAME (before(trim(|$!ATTRS[$!X]|), | |))
skip if (|$!ATTNAME| eq |CODE|)
skip if (|$!ATTNAME| eq |SERIAL|)
skip if (|$!ATTNAME| eq |SUFFIX|)
skip if (|$!ATTNAME| eq |.SBREF|)
!TEMP = (!X + 2)
var !ATTVALUE split |$!ATTRS[$!TEMP]| |_|
!TEMP = (!X + 1)
!ATTDESC = |$!ATTRS[$!TEMP]|
$* Assemble text string.
do !I indices !ATTVALUE
!SEND = (substring(|$!ATTNAME$!BLANK|, 1, 12))
!SEND = |$!SEND : $!ATTDESC|
!SEND = (substring(|$!SEND$!BLANK|, 1, 40))
!SEND = |$!SEND : $!ATTVALUE[$!I]|
!ATTDESC = ( trim ( before ( |$!ATTDESC|,|#| ) ) )
!TEMP = (!I + 1)
!ATTDESC = |$!ATTDESC #$!TEMP|
var list _PID.ATTRS_MEM add |$!SEND| exit
$* Need to keep array of attributes for checking later
var !!ATTRS append |$!SEND|
enddo
enddo
$* Add First value into text gadgets
var list _PID.ATTRS_MEM sel 1 exit
handle (61,122)
$* empty list
golabel /END
var _PID.ATTRS_ATTR ||
var _PID.ATTRS_NAME ||
var _PID.ATTRS_VALU ||
endhandle
var !FIRSTATT split |$_PID.ATTRS_MEM| |:|
if (arraysize(!FIRSTATT) ge 3 ) then
var _PID.ATTRS_ATTR (trim(|$!FIRSTATT[1]|))
A— 10
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
var _PID.ATTRS_NAME (trim(|$!FIRSTATT[2]|))
var _PID.ATTRS_VALU (after(after(|$_PID.ATTRS_MEM|,|:|),|:|))
endif
label /END
$* restore CE callback to original
edit _pid.attrs_ce button call |callpid XATTRS|
$* >>>>>>>>>>>>>>> End of Code IATTRS <<<<<<<<<<<<<<<<<<
$.
A.6.1.2
action macro listing
$(H
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
Copyright CADCentre Ltd 1993
Macro:
Author:
MATTRS
Phill Theze
$Revision$
Last modified:
Macro Generic Type:
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
$)
$(D
Callback macro for the Attributes form
$)
$:debug$:
$* Initialise Variables
var !EXIST |FALSE|
var !TYPE |$1|
var !ATTR (trim(|$_PID.ATTRS_ATTR|))
$* return to original edit context
!FORREF = (before(after(|$_pid.attrs_desc|,|(|),|)|))
!CEREF = (before(after(|$!!PEGS.NAME|,|(|),|)|))
if (|$!FORREF| ne |$!CEREF|) then
callpid URESTCE _PID.ATTRS
endif
if (|$!TYPE| EQ |DEL|) then
$* Delete Attribute
var _VALU | |
callpid MATTRS $<VALU$>
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
A— 11
callpid MATTRS $<SEL$>
var _ATTR ||
var _NAME ||
elseif (|$!TYPE| EQ |SEL|) then
$* Load gadgets with data from list
if ( match ( |$_PID.ATTRS_MEM|,|:| ) eq 0 ) then
$* have picked multiline attr value
var _ATTR ||
var _NAME ||
var _VALU ||
return
endif
var !ATTRSS split |$_PID.ATTRS_MEM| |:|
var _ATTR (trim(|$!ATTRSS[1]|))
var _NAME (trim(|$!ATTRSS[2]|))
$* attribute vaue with colon e.g. GRASYM
if (defined(!ATTRSS[4])) then
var _VALU (trim(|$!ATTRSS[3]:$!ATTRSS[4]|))
else
var _VALU (trim(|$!ATTRSS[3]|))
endif
elseif (|$!TYPE| EQ |VALU|) then
$* Set Attribue with value
if (|$_ATTR| EQ ||) then
error |Attribute Name Not Defined|
var _NAME ||
var _VALU ||
return
endif
PEGS |$_ATTR ’$_VALU’|
handle (78,147018) $* attribute changed
elsehandle (78,248005)
error |Attribute needs to be numeric|
var _VALU ||
return
elsehandle (78,148031) $* attribute not defined 8031
var _ATTR ||
error |Attribute Not Defined|
var _NAME ||
var _VALU ||
return
elsehandle (78,248004)
error |$!!PEGS.ERROR[1]|
var _VALU ||
return
endhandle
$* Rebuild Form
if (defined(!!ATTRS)) then
A— 12
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
$* save selection
!SELECT = (1)
do !X indices !!ATTRS
if (|$_pid.attrs_mem| eq |$!!ATTRS[$!X]|) then
!SELECT = ( $!X )
endif
enddo
$* rebuild
var list _pid.attrs_mem clear
exit
if (|$_VALU| eq ||) then
$* remove deleted attribute from list
var !!ATTRS[$!SELECT] delete
!SELECT = ( $!SELECT + 1 )
if (undefined(!!ATTRS[$!SELECT])) then
!SELECT = (1)
endif
else
var !BITS split |$!!ATTRS[$!SELECT]| |:|
if (|$!BITS[1]| ne |$_attr|) then
do !X values !!ATTRS
if (|$!BITS[1]| eq |$_attr|) then
!SELECT = ( $!X )
!EXIST = |TRUE|
break
endif
enddo
if (|$!EXIST| eq |FALSE|) then
callpid IATTRS
endif
endif
!!ATTRS($!SELECT) = |$!BITS[1]:$!BITS[2]: $_pid.attrs_valu|
endif
var list _pid.attrs_mem add
do !X values !!ATTRS
add |$!X|
enddo
exit
else
callpid IATTRS $<NOT$>
endif
LABEL /LOOP
if (defined(!!ATTRS[$!SELECT])) then
var list _pid.attrs_mem sel $!SELECT exit
else
!SELECT = ( $!SELECT – 1 )
GOLABEL /LOOP
endif
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
A— 13
elseif (|$!TYPE| EQ |ATTR|) then
$* check user supplied attribute name, get value
if (|$!ATTR| EQ ||) then
Error |Attribute Name Not Defined|
var _NAME ||
var _NAME ||
var _ATTR ||
return
endif
$* check if Attribute already Exists
do !COUNT indices !!ATTRS
var !ATTRSS split |$!!ATTRS[$!COUNT]| |:|
if (match(|$!ATTRSS[1]|,(upcase(|$_ATTR|))) NEQ 0 ) then
var _NAME (trim(|$!ATTRSS[2]|))
var _VALU (trim(|$!ATTRSS[3]|))
var !EXIST |TRUE|
endif
enddo
if (|$!EXIST| NEQ |TRUE| ) then
$* attribute doesn’t exist
var _NAME ||
var _VALU ||
$* Need to Check valid attribute
PEGS ’$_ATTR ’
handle any $* attribute not defined 8031
var _ATTR ||
error |Attribute Not Defined|
endhandle
endif
$* Get to correct place in list
do !VALUE values !!ATTRS
var !ATTRSS split |$!VALUE| |:|
if (match(|$!ATTRSS[1]|,(upcase(|$_ATTR|))) NEQ 0 ) then
var !EXIST |TRUE|
var list _PID.ATTRS_MEM SEL |$!VALUE| exit
handle any $* if error go to top of list
var list _PID.ATTRS_MEM SEL 1 exit
endhandle
break
endif
enddo
endif
A— 14
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
$* reset the callback in the CE button – changed by MSCP etc.
edit _pid.attrs_ce button call |callpid XATTRS|
return $* >>>>>>>>>>>>>>>>>> End of Code MATTRS <<<<<<<<<<<<<<<<<<<
$.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
A— 15
Appendix B
Communicating With REVIEW
This chapter describes the sample application provided with REVIEW, and should be read in
conjunction with the REVIEW User Guide, where the commands available from the command line
for controlling REVIEW are explained. It also explains the responses to these commands which
may be returned from REVIEW
The REVIEW commands available constitute a subset of the full REVIEW functionality, together
with some special commands for sending commands in batches.
B.1 Invoking the Command Line Interface
You invoke the command line interface in REVIEW via the Applications icon in the REVIEW
user interface.
B.2
Directing Commands to REVIEW
In order to direct any command line to REVIEW, prefix the line with the command
REVIEW
The remaining part of the line may comprise either:
•
A command sequence for controlling one or more of REVIEW’S functions
•
An instruction to send one or more preceding command lines to REVIEW
This prefix is incorporated into all commands described in the remainder of this chapter.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
B-1
B.3
Sending Commands to REVIEW
You may send command lines to REVIEW in one of two ways:
•
Automatically, as soon as the newline character is entered to terminate the command line
•
In batch mode, by entering an explicit instruction to send one or more previously entered
command lines
REVIEW refreshes its display every time a received instruction has been completely processed,
which can make the automatic sending of each command line inefficient compared with batch
mode operation (where the display is refreshed only once for the whole command sequence).
To initiate automatic sending of commands on a line-by-line basis, use the command
REVIEW AUTOsend ON
► To stop the automatic sending of commands and revert to batch mode (which is the default),
use the command
REVIEW AUTOsend OFF
► To pass a batch of commands to REVIEW explicitly (only valid with Autosend mode Off), use
the command
REVIEW SEND
This command will send all command lines which have been entered since the preceding REVIEW
SEND command. Consider, for example, the following command lines (which are numbered for
reference purposes only):
1.
2.
3.
4.
5.
REVIEW MATERIAL 1 RGB 10 10 10
REVIEW ELEMENT /C1101 MATERIAL 1
REVIEW SEND
REVIEW ELEMENT /C1002 MATERIAL 1
REVIEW SEND
By default, batch mode is in operation (i.e. Autosend mode is Off). Therefore lines 1 and 2, which
hold REVIEW functional commands, are not passed to REVIEW until the explicit command to
do so is given in line 3.
Similarly, the command in line 5 causes line 4 (only) to be passed to REVIEW.
B-2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
B.4 Errors Resulting from the Application-to-REVIEW Link
The following error messages result from problems with (a) the application module, or (b) the
communications link between applications and REVIEW, rather than from the results of
commands transmitted along that link.
(a)
(79, 101)
(79, 102)
Environment variable CADC_IPCDIR unset
Cannot start communications: error
(79, 201)
(79, 202)
(79, 203)
(79, 204)
(79, 205)
(79, 206)
(79, 207)
(79, 208)
(79, 209)
Commands sent automatically as AUTOSEND is enabled
Cannot connect to Review: error
Cannot start command transfer to Review: error
No commands to send to Review
Cannot send commands to Review: error
Cannot end transfer to Review: error
Cannot start transfer from Review: error
Cannot receive reply from Review: error
Cannot receive the error message from Review: error
(b)
B.5
Sample Application
NOTE: The sample application supplied is for demonstration purposes only. By default it uses flat
files as the source of data. Note that you should cancel the Login form displayed when the
demonstration application is run.
The first stage of the sample application is concerned with progress monitoring, covering both the
design and construction phases. It uses the sample model to give a clear presentation of the current
status of the project, which is particularly useful during concurrent design and construction.
The second stage focuses on extracting a range of engineering data available from the model,
including the display of P&IDs, vendor drawings and scanned images, data sheets, and reports.
The third part of the application focuses on the operating life of the plant, such that items requiring
maintenance can be interrogated by reference to a timebase. Maintenance history can be studied
for past problems and recommendations; maintenance procedures can be displayed to show the
scope of the work involved. Cost benefits can be seen by obtaining the isolation group associated
with a given element; for example, the Main Separator Tower may be highlighted together with an
adjacent control valve which is to be maintained at the same time.
A set of fully documented forms and macros are supplied to support these engineering
applications, based around the Stabiliser model. These applications are summarised in more
detail in the following sections.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
B —3
B.5.1
Progress Monitoring
The Progress Monitoring application is based on the need to view different engineering disciplines
of a plant that are at various stages of completion. Relevant information can then be displayed and
highlighted within REVIEW
The engineering disciplines recognised by the application are:
Piping
Mechanical
Vessels
Structural
Instruments
For each discipline, the completion status, each of which is displayed within REVIEW in a
different colour, may be any of the following:
Completion Status
Preliminary Design
Final Design
Fabricated
Erected
Tested
B.5.1.1
Display Colour
Green
Cyan
Blue
Purple
Brown
Engineering Data
The Engineering Data application is based on the need to derive engineering data which relates to
a graphical element selected within the REVIEW display; for example:
Purchase order data
Descriptions
Document availability and viewing capability
Once this data has been supplied, a further selection can be made to display related documents and
drawings through other applications. Examples supplied will allow access to plotfiles, ASCII and
scanned image files.
B.5.1.2
Maintenance
The Maintenance application is based on the need to view different types of plant element which
require maintenance at different time intervals. Maintenance activities can then be selected for
further data analysis and display within REVIEW.
The types of design element recognised by the application are:
Vessels
Exchangers
Mechanical
B-4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Instruments
All
For each element type, the maintenance interval, specified in terms of the date when maintenance
is next due, may be any of the following:
Overdue
Due today
Due next week
Due next month
When applied for a selected Element Type and Due On, all available data will be displayed to show
which elements require maintenance and when. These elements can then be selected for further
maintenance enquiries by selecting one or more the following options:
Maintenance schedule
Maintenance history
Parts inventory
Isolation list
B.6 Using the Sample Application
B.6.1
Start-Up
First ensure that all software has been installed as explained in the REVIEW Installation Guide.
Then open a window and type
% run_demo
NOTE: The file run_demo is located under the demo directory where the software was installed.
Read the rvq_docs/README file for hints on how (if you’re an experienced Query
Toolkit user) you can customise the application for use with an external database.
REVIEW will load its graphics and the sample model onto the screen. Click on the Application’s
icon
to start the demonstration.
You will then see a Data Server Login form, which you should cancel for this flat file
demonstration.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
B— 5
B.6.1.1
Progress Monitoring.
Select Applications> Progress Monitoring.
A form will be displayed, as shown in Figure B.l, to enable you to access data relevant to the
completion status for a particular discipline.
Progress Monitoring
Make
Apply
Figure B.l
The Progress Monitoring form
Use the two option gadgets on this form to set the required combination of design Discipline (e.g.
Piping) and corresponding completion Status (e.g. Erected).
Click the Apply button to highlight items meeting the selection criteria within the REVIEW
model. Different colours will be used for the various Status options.
Click the Make Display Translucent button to reset all materials in the REVIEW display to
translucent to enable different Discipline/Status combinations to be selected and viewed.
Progress Monitoring Examples:
Select and then apply the following combinations:
Discipline= Piping and Status = Erected
Discipline= Vessels and Status = Delivered
Discipline= Vessels and Status = Installed
Discipline=Structural and Status = Erected
Discipline= Instr/Elect and Status = Fabricated
Discipline= Mechanical and Status=Tested
Pipes are displayed in purple
Vessels are displayed in blue
Vessels are displayed in purple
Steelwork is displayed in purple
Instrument Cabinets are displayed in blue*
Pumps are displayed in brown*
(* Select Look>ISO>One from the REVIEW bar menu for the best display.)
B.6.1.2
Engineering Data
Select Applications> Engineering Data.
A form will be displayed, as shown in Figure B.2, to enable you to extract engineering data relevant
to the model.
In the REVIEW display, select the central upright vessel (/Cl 101) using the cursor and left-hand
mouse button. Now select the Name field on the Engineering Data form and paste in the name of
the selected vessel by clicking the right-hand mouse button.
B-6
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Name
Document
ID1537851
D1537852
Weld
D89234872
D456826
D8728372
Process
IDPL123
P&ID
Document
Apply
Figure B.2
The Engineering Data form
Click the Apply button to display data for the specified vessel against the headings Purchase
Order and Description.
A list of associated documents will be shown under the Document and Description headings. To
display such a document, first select the line for that document in the scrollable list and then click
the View Document button. The resulting document display may be:
•
•
•
a text file, using the system editor
a plotfile representation of orthogonal views of a drawing
a scanned image of a drawing
NOTE:
Any external application may be used to display documents.
Any number of documents may be selected simultaneously for viewing.
Document Examples
Names can be selected graphically (as explained above) or by entering an explicit name.
Name:
/C1101
D1537851
DPL123
Name:
Fabrication Drawing
P&ID sheets 1 - 3
/P1501A
D8428797
2D Drawing
D43173298
Bill of materials
ER3245— 001 Cable List Report
Name:
displays a plotfile of the Main Separation Tower
each displays a P&ID plotfile
displays a set of orthogonal views
displays a BOM report for Pump P1501A
displays a cable connection list report
/V-70
D7862134
Cross Sectional View
CADCENTRE Software Customisation
Reference Guide
Issue 1095
displays a scanned image of a the valve
CADCENTRE
Protected by copyright: see frontispiece
B— 7
B.6.1.3
Maintenance
Accessing the Maintenance Data
Select Applications> Maintenance.
A form will be displayed, as shown in Figure B.3, to enable you to access data relating to those
items which require maintenance within specific time periods.
Maintenance
Type
Due When
Due
Name
/CHOI
week
Date
APR
Maintenance Schedule
Maintenance
Apply
Figure B.3
The general Maintenance form
Use the two option gadgets on this form to set the required combination of item Type (e.g.
Vessels) and time when next maintenance operation is due, shown as Due When (e.g. Due in next
week).
Click the Apply button to highlight items meeting the selection criteria within the REVIEW
model.
To make it easier to see the selected item in the REVIEW display, click the Setup camera view
button. This sets up Camera One such that the through point is at the item of interest, with a field of
view of 60°.
The Name, Description and Inspection Date for each relevant item will be listed on the form
under the corresponding headers. To obtain detailed maintenance data for any item, select the
item in the scrollable list and then click the appropriate button under the heading Further data for
selected item. The data available comes under the following headings:
Maintenance Schedule
Maintenance History
Parts Inventory
Isolation List
B-8
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Maintenance Schedule
The Maintenance Schedule form, as illustrated in Figure B.4, allows you to view the maintenance
procedures that have been generated for a named model item.
Maintenance Schedule
Name
Order
CTZ234
due
No
[02 Mai
PR1874
09
PR2319
Routine
flpplij
Figure B.4
The Maintenance Schedule form
To display any of the maintenance procedures listed for the current item, select the procedure in
the scrollable list and then click the View Procedure button. The selected report will be displayed
(in read-only mode) to show details of the maintenance procedures.
To list the available maintenance procedures for a different model item without returning to the
general Maintenance form, enter the new item name and click the Apply button.
Maintenance History
The Maintenance History form, as illustrated in Figure B.5, allows you to view the maintenance
history reports that have been generated for a named model item.
To display any of the maintenance reports listed for the current item, select the report in the
scrollable list and then click the View Report button. The selected report will be displayed (in
read-only mode) to show details of the maintenance history.
To list the available maintenance reports for a different model item without returning to the
general Maintenance form, enter the new item name and click the Apply button.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
B— 9
Maintenance History
Name
Order
02 May
09
CTZ234
Report No
RP1874
Additional
Report
RP2319
Routine
Report
RP2756
Routine
Report
90
RP9055
Routine
89
RP9078
Routine
Report
Report
Apply
Figure B.5
The Maintenance History form
Parts Inventory
The Parts Inventory form, illustrated in Figure B.6, allows you to view supplier details that have
been generated for a named model item.
Parts inventory
Name
Order
CTZ234
No.
IMP-031
GASK-17-918
Qty
Quota
Pump/Gearbox
JB-*
flpplij
Figure B.6
B— 10
The Parts Inventory form
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
To display details of any part listed for the current item, select the part in the scrollable list and then
click the Supplier Details button. Supplier information for the selected part will be displayed (in
read-only mode).
To list the available supplier details for a different model item without returning to the general
Maintenance form, enter the new item name and click the Apply button.
Isolation List
The Isolation List form, illustrated in Figure B.7, allows you to view details of maintenance
isolation lines that have been generated for a named model item.
Isolation List
Name
Order
Name
.-Bl
-M3
Manhole
-Ml
Manhole
-M2
Manhole
Sample
/100-B-1-B1
Apply
Figure B.7
The Isolation List form
The scrollable list shows all associated items which make up the isolation line related to the current
item. The complete isolation line will be highlighted in the REVIEW display.
To list the isolation line details for a different model item without returning to the general
Maintenance form, enter the new item name and click the Apply button.
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
B— 11
B.7 A Summary of the Application Data
As a guide to the data available within the example supplied, the following tables show the data
which may be extracted by using the various applications.
B.7.1
Progress Monitoring
Preliminary
Final Design
Fabricated
Erected
Tested
Delivered
Installed
Excavated
Foundations
Oversite
B.7.1.1
Piping
no
yes
yes
yes
yes
n/a
n/a
n/a
n/a
n/a
Meeh.
no
no
n/a
n/a
yes
no
no
n/a
n/a
n/a
Vessels
no
no
n/a
n/a
yes
yes
yes
n/a
n/a
n/a
Civil
no
no
n/a
n/a
n/a
n/a
yes
no
no
yes
Structural
no
no
no
yes
yes
n/a
n/a
n/a
n/a
n/a
HVAC
no
no
no
no
no
n/a
n/a
n/a
n/a
n/a
Instr./Elec.
no
no
yes
yes
no
n/a
n/a
n/a
n/a
n/a
Engineering Data
The engineering data extracted from the data source (flat file or database tables) is based on the
following PDMS elements:
/C1101
/P1502A
/V— 70
B— 12
Main Separator Tower
Secondary Backup Pump
Manual Shutdown Valve
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
B.7.1.2
Maintenance
Vessels
Overdue
no
no
no
no
no
Due today
no
no
no
no
no
next week
yes
yes
yes
yes
yes
next month
yes
yes
yes
yes
yes
Overdue
no
no
no
no
no
Due today
no
no
no
no
no
next week
no
no
no
no
no
next month
yes
no
no
no
no
Overdue
yes
no
no
no
no
Due today
yes
no
no
no
no
next week
yes
no
no
no
no
next month
yes
no
no
no
no
Primary data
Schedule
History
Parts inventory
Isolation list
Overdue
no
no
no
no
no
Due today
no
no
no
no
no
next week
no
no
no
no
no
next month
yes
no
no
no
no
Primary data
Schedule
History
Parts inventory
Isolation list
Overdue
yes
no
no
no
no
Due today
yes
no
no
no
no
next week
yes
yes
yes
yes
yes
next month
yes
yes
yes
yes
yes
Primary data
Schedule
History
Parts inventory
Isolation list
Exchangers
Primary data
Schedule
History
Parts inventory
Isolation list
Mechanical
Primary data
Schedule
History
Parts inventory
Isolation list
Instruments
All
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
-13
NOTE: Most of the data extracted from the data source (flat file or database tables) is based on
the following PDMS elements:
Main Separator Tower
Secondary Backup Pump
Storage Tank
Manual Shutdown Valve
Manual Shutdown Valve
/C1101
/P1501A
/E1301
/V121
/V— 70
There are instances where data extracted is not consistent with that of the model. In such
cases the following message will be displayed:
data ignored not in review model
B.8 The Application Files Supplied
For convenience, the sample application files are supplied under a function-related directory
hierarchy, thus:
demo
rvq_docs ADMIN
PROGRESS ENGDATA MAINTAIN
DATA
run_demo
README rvq files
These directories/files have the following functions:
ADMIN
PROGRESS
ENGDATA
MAINTAIN
DATA
run_demo
A general directory for startup and initialisation of Query
A directory for the progress monitoring applications
A directory for the engineering data applications
A directory for the maintenance applications
A directory containing data for use by the applications
A script to run the REVIEW demonstration application
The files which are supplied within each of these directories are listed in the following sections.
NOTE: The names of many of the files begin with a prefix which indicates the file’s function, thus:
' filename denotes a form definition
Mfilename denotes a macro definition
XJfilename denotes a utility macro
Ifilename denotes a form initialisation macro
All other filenames denote general files which are not specifically used in form creation.
B— 14
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
B.8.1
The ADMIN Directory
CONFIG
FORACLE
FSYSTEM
FVERSION
IORACLE
FVERSION
MORACLE
MVERSION
RPODESC
START
UCAMERA
UORACLE
UQUIT
URESET
UVIEWDOC
VAR2ENV
B.8.1.1
The ENGDATA Directory
FENGDATA
FPLOTVIEW
IENGDATA
MENGDATA
UNEXTPLOT
UPREVPLOT
B.8.1.2
Form definition macro for engineering data
Form definition macro for plotfile viewer
Initialisation macro for engineering data
Result macro for engineering data
Utility macro to view next plot
Utility macro to view previous plot
The PROGRESS Directory
FPROGRESS
IPROGRESS
MPROGRESS
UDISCIP
UTRANSLU
B.8.1.3
User-specified configuration; e.g. database server node
Form definition macro for RDBMS connection
Form definition macro for main system menu
Form definition macro for versions
Initialisation macro for RDBMS connection
Initialisation macro for versions
Result macro for RDBMS connection
Result macro for versions
Utility macro to set purchase order number and description
Query start-up macro
Utility macro to set up camera 1
Utility macro to invoke RDBMS connection form
Utility macro to quit Query
Utility macro to reset observer materials
Utility macro to view documents (plotfiles and other formats)
Utility macro to convert %Variable% to environmental variable
Form definition macro for progress monitoring
Initialisation macro for progress monitoring
Result macro for progress monitoring
Utility macro to set status list for selected discipline
Utility macro to make display translucent
The MAINTAIN Directory
FHISTORY
FINVENT
FISOLATE
FMAINTAIN
FSCHEDULE
FSUPPLY
IHISTORY
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Form definition macro for maintenance history
Form definition macro for parts inventory
Form definition macro for isolation list
Form definition macro for maintenance requirements
Form definition macro for maintenance schedule
Form definition macro for supplier details
Initialisation macro for maintenance history
CADCENTRE
Protected by copyright: see frontispiece
D — 15
IINVENT
IISOLATE
IMAINTAIN
ISCHEDULE
ISUPPLY
MHISTORY
MINVENT
MISOLATE
MMAINTAIN
MSCHEDULE
UMSHOW
B.8.1.4
The DATA Directory
DOCDATA
NAMEDATA
SUPPLIERDATA
ISOLATEDATA
PARTSINVDATA
MAINHDATA
MAINSDATA
MAINTDATA
PROGRESSDATA
oracle_data
sybase_data.ksh
CllOl.plot
C1101020592.asc
C1101091092.asc
C1101111091.asc
C1101121089.asc
C1101141090.asc
EI3245.pIot
EI3246.pIot
V— 7O.spec
P1501A.bom
P1501A.plot
cablelist..rep
panel.rep
pfd.plot
pidl.plot
pid2.plot
pid3.plot
v-70.tif
xtiff
B-16
Initialisation macro for parts inventory
Initialisation macro for isolation list
Initialisation macro for maintenance requirements
Initialisation macro for maintenance schedule
Initialisation macro for supplier details
Result macro for maintenance history
Result macro for parts inventory
Result macro for isolation list
Result macro for maintenance requirements
Result macro for maintenance schedule
Utility macro to show and apply one of the maintenance forms
Document data for engineering application
Element names against description data
Supplier data containing names, addresses and telephone No.
Isolation elements against primary element data
Parts inventory and supplier names against element data
Maintenance history data and reports against element data
Maintenance service data and reports against element data
Maintenance schedules and due dates against element data
Progress monitoring data type against completion state
An ORACLE data file in the form of tables for loading into ORACLE
(Table contents and names are consistent with those of the above flat files)
A Shell script for loading demo tables into Sybase RDBMS
(Table contents and names are consistent with those of the above flat files)
Plotfile of 2D drawing of the Stabiliser
Maintenance report
Maintenance report
Maintenance report
Maintenance report
Maintenance report
Electrical drawing plotfile
Electrical drawing plotfile
Valve specification
Pump bill of materials
Plotfile of 2D drawing of Pump
Electrical cable list report (PEGS-generated)
Electrical panel report (PEGS-generated)
Process flow diagram plotfile
P&ID sheet 1 for plant
P&ID sheet 2 for plant
P&ID sheet 3 for plant
Scanned image of a valve (sectioned drawing)
Utility to display scanned images
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Index
!!name, 10—9
$R+, 3-3, 1 0 - 3
!!name(index), 10—9
$ R - , 3-3, 1 0 - 3
!name, 1 0 - 9
$S, 3-4, 1 0 - 4
!name(index), 10—9
$S + , 3-9, 1 0 - 4
$ (Escape character), 2-2, 3-8, 6-8, 1 0 - 4
$S-, 3-9, 1 0 - 4
6-2, 6-9, 10-12
$„ 6 - 9
$:, 3 - 1 1
$($), 6-4, 10-12
$SK, 3-8, 1 0 - 4
$Snumber, 3—7
$U, 3 - 1 1
$W, 6-6, 10-12
$$, 6-6, 1 0 - 1 2
A
$/, 3-6, 1 0 - 4
$=, 6-6, 10-12
ABS, 5 - 1 0
$C, 6-6, 10-12
ACOS, 5-10
$D, 6-9, 1 0 - 1 2
ACTIONS command (PDMS only), 21-9
$G, 3-10, 1 0 - 4
$GK, 3 - 1 1
$HR, 3-2, 1 0 - 3
$L, 6-6, 1 0 - 1 2
$M, 6-2, 1 0 - 1 2
ADD, 5 - 8
ADD command
List definition, 17—5, 21-55
Menu definition, 15 —1, 15—3, 21—31
Plot view definition, 16—27
Userdata setting, 17—7
ADD HELP, 1 5 - 2
$M+, 6-3, 1 0 - 1 2
AFTER, 5 - 2 3
$M— , 6-3, 10-12
Alert forms, 12—5
$MK, 6-3, 10-12
ALOG, 5 - 1 0
$number, 6—8, 10—12
ALPHA command, 21 —10
$O, 3-9, 3 - 1 2
ALPHA Log, 1 0 - 3
$P, 6-5, 10-12
Alpha view gadget, 12—4, 16—22, 21 —10
$Q command, 2—3
Alpha view setup mode, 16-22, 21-10
$QG, 3 - 1 1
AND, 5 - 3
$QM, 6-4, 10-12
ANY command (PML error handling), 8—2,
10-14
$QR, 3-2, 1 0 - 3
$QS, 3-8, 1 0 - 4
$R, 3-1, 3-2, 1 0 - 3
CADCENTRE Software Customisation
Reference Guide
Issue 1095
APPEND command, 10—9
APPEND command (file handling), 9—1,
10-16
CADCENTRE
Protected by copyright: see frontispiece
lndex-1
Apply button, 18—3
Plot view, 16—27
Volume view, 16—23, 16—26
AREA command (PDMS Design and
DRAFT), 21-11, 21-12
BREAK command (PML), 7—4
Area view gadget, 12—4, 16—25, 21 —11, 21-12
BUTTON command, 16-8, 21-14
Area view setup mode, 16—25, 21 —11, 21 —12
Button gadget, 12—2, 16—8, 21 —14
ARRAY, 5 - 1 0
BY command (PML), 7-3, 10-13
Array variables, 4—7
accessing, 4—12
deleting, 4-19
evaluating (PDMS only), 4—11
querying, 4-17
selecting (PDMS only), 4 - 9
setting, 4—8
sorting, 4—12
subtotalling, 4—16
CALLBACK command, 1 6 - 2
ARRAYSIZE, 5 - 1 1
CANCEL command, 16—9
ARRAYSIZE operator (array variables), 4—17
CHANNEL command, Alpha view, 16—22
ARRAYWIDTH, 5 - 1 1
Child form, 12—2, 18—2
ARRAYWIDTH function, 4-18
CLEAR command
List definition, 17—4
Plot view, 16-28
Selector definition, 17—6
Userdata setting, 1 7 - 8
c
Callback string, 12—2, 16—2
CANCEL attribute, 16—9
Cancel button, 18—3
AS command, 22— 2, 22— 18
ASIN, 5 - 1 0
AT command
Form positioning, 14—3
Gadget positioning, 16—3
CLOCK command, 4-4, 10-9
CLOSE command, 22—2, 22—13
ATAN, 5 - 1 0
CLOSEFILE command, 9-3, 10-16
ATANT, 5 - 1 0
COLLECT, 4 - 9
AUTO command, Selector gadget definition,
16-17
COLLECT command, 10—9
Command abbreviations, 22—10
AUTO flag, Volume view, 16—24
AUTOLIMITS command, Volume view,
16-25
AUTOSEND command, B— 2
Command atom, 2—1
Command help facility, 2—3
Command processor, 2 - 1
Command syntax, 2—1
B
Commands form, 17—1
COMP . . . OF, 5 - 1 1
Background colour
Area view, 16—25
Plot view, 16-27
Volume view, 16—23
Comparator operators, 5—3, 10—7
BADREF, 5 - 5
CONFIRM command, 17-11, 21-16
BAR command, 15 —1, 21 —13
Confirmation alert, 12—5, 17—11, 21 —16
BATCH command, A— 3
CONNECT command, A - l
BEFORE, 5 - 2 3
CONTINUE command (PML), 8-4, 10-15
BLOCKING command, 1 4 - 2
Control button. See Button gadget
Blocking form, 12—2, 17—2
COPY command, 14—2
Boolean operators, 5—3, 1 0 - 7
COSINE, 5 - 1 1
BORDERS command
Counter (PML DO loop), 7 - 3
Index-2
Comparision precision, in expressions, 5—32
Conditional construct (PML), 7—2
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Error messages
PEGS, A - 4
Server daemon, 22-7
Cursor picking, 21—57
CURSORTYPE command, 21-17
Escape character, 2—2
D
Escape codes, 2—2, 10—2
DATABASE command, Selector gadget,
16-16
EVALUATE, 4 - 1 1
Defaults files, 20—3
Evaluating array variables, 4—11
DEFINED, 5 - 5
EXIT command, 21—22
DEFINED operator (variables), 4— 5, 4— 18
Expressions, 2—2, 5—1
directions in, 5—21
format, 5 - 1
IDS in, 5 - 1 4
logical array, 5—7
nesting, 5 - 2
numeric, 5 - 7
positions in, 5 —15
precision of comparisions, 5 - 3 2
real, 5—7
real array, 5 —14
text, 5 - 2 2
types, 5 - 1
DELETE command, Userdata setting, 17—7
DELETE command (file handling), 9—3,
10-16
Deleting variables, 4 - 6
DELIMIT command, 22—6, 22—14
DISCONNECT command, A - 2
Dismiss button, 16—10, 18—3
Display text, List gadget, 16-14, 17—4
DISTANCE, 5 - 2 3
PDMS format, 5—24
US format, 5—24
EVALUATE command, 10—10
EXTERNAL command, 22—1, 22—16
DIVIDE, 5 - 8
DLENGTH, 5 - 1 2
DMATCH, 5 - 1 2
File token, 9—1
DO command (PML), 7—3, 10—13
FMINFO command, 12-6, 21-23
DO loop construct )PML), 7 - 3
Focus, keyboard, 16-28
DSUBSTRING, Japaneses characters, 5 - 2 9
Form attributes, 14—2, 17-9
FORM command, Button gadget, 16-9
Form control attribute, 16—9
E
Form setup mode, 14—1, 21—44
ECHO command, A— 4
EDIT command, 14—3, 14—4, 16—28, 21 —18
Form variables, 12—2, 17—3, 17-8, 21—54,
21-55, 21-57, 21-59, 21-60
ELSEHANDLE command (PML), 8—2,
10-14
FROM, 5 - 1 7
ELSEIF command (PML), 7-2, 10-14
Functions
logical, 5—5
numeric, 5—8
real, 5 - 8
summary of, 10—5
text, 5 - 2 2
EMPTY, 5 - 5
END command, 22—3, 22—15
ENDDO command (PML), 7-3, 10-13
ENDHANDLE command (PML), 8 - 2 , 10-14
FROM command (PML), 7-3, 1 0 - 1 3
ENDIF command (PML), 7-2, 10-14
G
EQUAL, 5 - 3
Error alert, 12—5, 17—10, 21—21
Gadget status, 16—29
ERROR command, 17—11, 21—21
Gadget values, reading into variables, 17—8
ERROR command (PML), 8—7
GE, 5 - 4
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
lndex-3
GET command, 22—4, 22—5, 22—17
Global variables, 12—5, 20—3
GOLABEL command (PML), 7—8, 8—3,
10-15
Label. See Paragraph gadget
LABEL command (PML), 7—7
Late evaluation of expressions, 5 - 6
Graphical user interface
forms, 2—2
menus, 2—2
Late evaluation of variables, 4 - 6
Late evalutation of expressions, 5 —14
Greying-out, 16—29
Late evauation of expressions, 5—30
Grid (for form layout), 16—2
Later evaulation of expressions, 5—30
GT, 5 - 4
LE, 5 - 4
LENGTH, 5 - 1 2
H
HALIGN command, 16—7, 21—24
LIMITS command
Area view, 16—26
Volume view, 16-24
HANDLE command (PML), 8-2, 10-14
Line feeds, 4—19
HDISTANCE command, 16—6, 21—25
List attribute, 17—9
HEADER command, 22—5, 22—17
List button. See Option gadget
LIST command, 16—14, 21—30, A— 4
Help button, 12—6
LIST command (PML), 7-7, 1 0 - 1 3
Help facility ($Q), 2—3
List gadget, 12-3, 16—14, 17—4, 18-5, 18—6,
21-30, 21-55
Display text, 1 2 - 3
Replacement text, 12—3
Help menus, 12—6
HELP system, 12—6
HIDE command, 17—3, 21—26
List setting mode, 17—4
Highlight colour
Area view, 16—25
Volume view, 16-23
LOG, 5 - 1 2
Logical, Operators, 10—6
Logical functions, 5—5
LOWCASE, 5 - 2 5
LT, 5 - 4
ICONTITLE command, 14—4, 21—27
IDs in expressions, 5 - 1 4
M
IF command (PML), 7-2, 10-14
INDEXES command (PML), 7—5, 10—13
INDICES command (PML), 7-5, 1 0 - 1 3
Macros, 2—2, 6—1
MATCH, 5 - 1 2
MATCHWILD, 5 - 5
Initialisation text, 14—4
INITIALISE command, 14-4, 21-28
MAX, 5 - 1 2
INSET operator, example, 7—2
Menu. See Menu bar, Pull-down menu or
Submenu
INT, 5 - 1 2
Menu bar, 12—1, 15 —1, 18—1
Menu bar setup mode, 15-1, 21-13
K
MENU command, 15— 3, 21— 31
KEEP command (file handling), 9—3, 10—16
Keyboard focus, 16—28
KILL command, 17— 3, 21— 29
Index-4
Menu selection field
Command field, 15—3
Form field, 15—3
Separator field, 15—3, 15—4
Submenu field, 15-3, 1 5 - 4
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
precedence, 5—2
summary of, 10—5
text, 5 - 2 2
Menu setup mode, 15— 3, 21— 31
MIN, 5 - 1 2
Multiple choice list, 16—14, 18—6
OPTION command, 16-17, 21-32
Multiple choice selector, 16—15
Option gadget, 12—3, 16—17, 18—6, 21—32
MULTIPLY, 5 - 8
OR, 5 - 4
OVERWRITE command (file handling), 9 —1,
10-16
N
Names
Files, 20-1, 20-3
Forms, 1 3 - 1
Gadgets, 13 —1
Macros, 20-2
Menus, 1 3 - 1
Variables, 20—1, 20—3
p
PAIRS command, List definition, 17—5
PANE command (PML), 7-7, 10-13
PARAGRAPH command, 16-18, 21-33
Paragraph gadget, 12—3, 16—18, 18—6, 21—33
NEGATE, 5 - 1 2
Parent form, 12—2
NEQUAL, 5 - 3
PART, 5 - 2 6
Nesting, 3 - 2
PATH command, 16—6, 21—34
NEXT command, 22—4, 22—17
PAUSE command (PML), 8-4, 10-15
NINT, 5 - 1 3
PDMS attributes, in expressions, 5 - 3 1
Non-blocking form, 12—2, 17—2
NONE command (PML error handling), 8—2,
10-14
PDMS format distances, 5—24
PEGS command, A— 1
NOT, 5 - 4
pixmap, 1 6 - 1
NUMBER (REAL), 5 - 1 3
PIXMAP command, 21—35
Numbered variable, 10—9
Pixmap view gadget, 12-4, 16—26, 21—35
Numeric expressions, 5—7
Pixmap view setup mode, 16—26, 21—35
PLOT command, 21—36, 21—37
Numeric operators, 5—8
Plot view gadget, 12—4, 16—27
Plot view setup mode, 16-27, 21-36, 21—37
o
Positions, comparing, 5—20
OCCUR, 5 - 1 3
POWER, 5 - 1 3
OK attribute, 16—9
Programmable Macro Language (PML), 7—1
OK button, 1 8 - 3
Prompt alert, 12-5, 17—11, 21—38
OK command, 16—9
PROMPT command, 17-12, 21-38
ON command, 22—2, 22—18
Prompts (in macros), 6—5
ONERROR command (PML), 8 - 3 , 8 - 4 ,
8-5, 10-15
Pull-down menu, 12—1, 15—3, 18—1, 21—31
OPEN command, 22—2, 22—18
OPENFILE command, 9—1, 10—16
PUT command
Area view, 16—26
Pixmap view, 16-26
Operands, 5 —1
Operators, 5—1
logical, 5 - 3
Logical expressions, 10—6
numeric, 5 - 8
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Q
QUERY VAR command, 4—5
Querying, variables and expressions, 5 - 3 1
CADCENTRE
Protected by copyright: see frontispiece
lndex-5
R
Radio button. See Radio Group gadget
Radio Group gadget, 12-3, 16-13, 18—5,
21-39
RADIOGROUP command, 16-13, 21-39
RAW command, A— 3
RAW operator (array variables), 4-19
READ command, 4—4, 1 0 - 9
READ command (file handling), 9—1, 10—16
READFILE command, 9—2, 10—16
Reading data from gadget values, 17—8
REAL, 5 - 1 3
Real arrays in expressions, 5 —14
Real expressions, 5—7
RECONNECT command, A— 2
Recording Command Input, 2—1
Recording Command Line Input, 3—1
Recording Command Line Inputs, 3 —1
Recording Output, 3-1, 3—10, 3 - 1 1
REFRESH command, 16-29, 21-40
Relational operators, 5 - 3 , 1 0 - 7
REPLACE, 5-26
Replacement text, List gadget, 16—14, 17—4
Requests form, 17—1
RESET attribute, 16—9
Reset button, 18—3
RESET command, 16—9
RESIZEABLE command, 14—3
RESULT command, 22—5, 22—17
Result, of expression, 5 —1
RETURN command (PML), 7-9, 8-5, 8-6,
10-15
REVIEW command, B—1
REVISION command, 14-4, 21-41
s
SCROLL command
Text gadget, 16-10
Text gadget definition, 21-47
Scrollable list. See List gadget
Index-6
SELECT command
List definition, 1 7 - 5
Userdata setting, 1 7 - 7
Selecting array variables, 4 - 9
Selection criteria, 4-10
SELECTOR command, 16-16, 21-42
Selector gadget, 12—3, 16—15, 17—6, 21—42,
21- 59
Selector setting mode, 1 7 - 6
SEND command, 22—3, 22—15, 22—19,
22- 20, B— 2
SETUP FORM command, 14-1, 21-44
Shaded representation, Volume view, 16—23
SHOW command, 17-2, 21-45
SINE, 5-11
Single choice list, 16—14, 1 8 - 5
Single choice selector, 16—15
SIZE command, 14—2
SKIP command (PML), 7 - 5
SORT command, 10—10
SORT option, 4—12
Sorting arrays, 4-12
Spaces, 4-19
SPLIT command, 10—9
SPLIT operator (array variables), 4 - 9
SORT, 5 - 1 4
START command, 22—3, 22—20
START macro, 12—5
STARTRECORDING command, A - 2
Status, of gadget, 16—29
STRING, 5 - 2 8
Submenu, 12—1, 15—4
SUBSTRING, 5 - 2 9
SUBTOTAL command, 10-10
SUBTOTAL option, 4-16
Subtotalling arrays, 4-16
SUBTRACT, 5 - 8
SWAP command, 12—7, 21—46
Synonym (data server), 22—2, 22-18
Synonyms, 2-2, 3 —1
Global, 3 - 1 0
Standard, 3—4
Tags (for gadgets), 16—1
TANGENT, 5 - 1 1
TEXT command, 16—10, 21—47
Text Entry Field gadget, 12—3, 16—10, 18—4,
21-47
CADCENTRE
Protected by copyright: see frontispiece
CADCENTRE Software Customisation
Reference Guide
Issue 1095
Text functions, 5—22
VARIABLE command, 17-4, 21-54
Text operator, 5—22
VARIABLE LIST command, 17-4, 21-55
Text Pane gadget, 21—49
VARIABLE PICK command, 21-57
Text pane gadget, 1 2 - 3
VARIABLE SELECTOR command, 17-6,
21-59
TEXTPANE command, 21-49
THEN command (PML), 7-2, 10-14
TITLE command, 14—3, 21—50
TO command (PML), 7—3, 10—13
TOGGLE command, 16-13, 21-51, 22-9,
22-21
Toggle gadget, 12-3, 16-12, 18-4, 21-51
VARIABLE USERDATA command, 17-7,
21-60
Variables
See also User definable variables
deleting, 4—6
PEGS message recording, A— 2
Setting from data server, 22—4
VARS file, 1 2 - 5
token, 22—17
VDISTANCE command, 16-6, 21-62
Token (data server), 22—2, 22—18
VIEW command, 16—20, 21—63
TRACE command, 22—9
View direction, 16—24
TRIM, 5 - 2 9
View editing mode, 16—28
u
View gadget, 12—4, 16—20, 21—63
VLOGICAL, 5 - 6
uname, 13 —1
VLOGICAL command, 4—6
UNDEFINED, 5 - 5
VOLUME command (PDMS DESIGN),
21-64
UNDEFINED operator (variables), 4—5,
4-18
Undefined values, in expressions, 5 - 3 3
Units, in expressions, 5 - 3 1
Volume view gadget, 12—4, 16—22
Volume view setup mode, 16—22, 21—64
VTEXT, 5 - 3 0
UNSET, 5 - 6
VTEXT command, 4—6
Unset values, in expressions, 5—33
VVALUE, 5 - 1 4
UPCASE, 5-25
VVALUE command, 4—6
US format distances, 5 - 2 4
User-definable variables, 2—2
Arrays, 4—7
global, 2—2
local, 2—2
w
WAITON command, 17-2, 21-68
Userdata, 12-4, 16—19, 17-6, 21-60
USETUP file, 1 2 - 5
WIDTH command, Text gadget definition,
16-10, 21-47
uuname, 13—1
Wireline representation, Volume view, 16—23
WRITE command, 6—5
V
WRITE command (file handling), 9—1, 10—16
WRITEFILE command, 9-2, 10-16
VALIGN command, 16-7, 21-53
WRT, 5-16
VALUES command (PML), 7—6, 10—13
CADCENTRE Software Customisation
Reference Guide
Issue 1095
CADCENTRE
Protected by copyright: see frontispiece
lndex-7