CATIA V5
00_Ziethen_FM_pi-xx.indd 1
12/28/12 6:05 PM
About the Author
Dieter R. Ziethen is a CAD Systems Engineer and technical IT process consultant at
MAN Truck and Bus AG. He also teaches CATIA V5 at the Munich University of Applied
Sciences.
00_Ziethen_FM_pi-xx.indd 2
12/28/12 6:05 PM
CATIA V5
Macro Programming with
Visual Basic Script
Dieter R. Ziethen
Translated by Kyle E. Brand
New York Chicago San Francisco
Lisbon London Madrid Mexico City
Milan New Delhi San Juan
Seoul Singapore Sydney Toronto
00_Ziethen_FM_pi-xx.indd 3
12/28/12 6:05 PM
Copyright © 2012 by The McGraw-Hill Companies, Inc. All rights reserved. Except as permitted under the United
States Copyright Act of 1976, no part of this publication may be reproduced or distributed in any form or by any means,
or stored in a database or retrieval system, without the prior written permission of the publisher.
ISBN: 978-0-07-180003-7
MHID: 0-07-180003-4
The material in this eBook also appears in the print version of this title: ISBN: 978-0-07-180002-0,
MHID: 0-07-180002-6.
McGraw-Hill eBooks are available at special quantity discounts to use as premiums and sales promotions, or for use in
corporate training programs. To contact a representative please e-mail us at bulksales@mcgraw-hill.com.
All trademarks are trademarks of their respective owners. Rather than put a trademark symbol after every occurrence of
a trademarked name, we use names in an editorial fashion only, and to the benefit of the trademark owner, with no
intention of infringement of the trademark. Where such designations appear in this book, they have been printed with
initial caps.
Information has been obtained by McGraw-Hill from sources believed to be reliable. However, because of the possibility
of human or mechanical error by our sources, McGraw-Hill, or others, McGraw-Hill does not guarantee the accuracy,
adequacy, or completeness of any information and is not responsible for any errors or omissions or the results obtained
from the use of such information.
TERMS OF USE
This is a copyrighted work and The McGraw-Hill Companies, Inc. (“McGraw-Hill”) and its licensors reserve all rights
in and to the work. Use of this work is subject to these terms. Except as permitted under the Copyright Act of 1976 and
the right to store and retrieve one copy of the work, you may not decompile, disassemble, reverse engineer, reproduce,
modify, create derivative works based upon, transmit, distribute, disseminate, sell, publish or sublicense the work or any
part of it without McGraw-Hill’s prior consent. You may use the work for your own noncommercial and personal use;
any other use of the work is strictly prohibited. Your right to use the work may be terminated if you fail to comply with
these terms.
THE WORK IS PROVIDED “AS IS.” McGRAW-HILL AND ITS LICENSORS MAKE NO GUARANTEES OR
WARRANTIES AS TO THE ACCURACY, ADEQUACY OR COMPLETENESS OF OR RESULTS TO BE OBTAINED
FROM USING THE WORK, INCLUDING ANY INFORMATION THAT CAN BE ACCESSED THROUGH THE
WORK VIA HYPERLINK OR OTHERWISE, AND EXPRESSLY DISCLAIM ANY WARRANTY, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. McGraw-Hill and its licensors do not warrant or guarantee that the functions
contained in the work will meet your requirements or that its operation will be uninterrupted or error free. Neither
McGraw-Hill nor its licensors shall be liable to you or anyone else for any inaccuracy, error or omission, regardless of
cause, in the work or for any damages resulting therefrom. McGraw-Hill has no responsibility for the content of any
information accessed through the work. Under no circumstances shall McGraw-Hill and/or its licensors be liable for any
indirect, incidental, special, punitive, consequential or similar damages that result from the use of or inability to use the
work, even if any of them has been advised of the possibility of such damages. This limitation of liability shall apply to
any claim or cause whatsoever whether such claim or cause arises in contract, tort or otherwise.
Contents
Preface............................................................................................ xvii
1
Basics................................................................................................... 1
1.1
Definition of CATScript and CATVBS...................................................................................... 1
1.2
Definition of Nomenclature.................................................................................................... 3
1.3
Definition of Object, Class, and Object Path.......................................................................... 4
1.3.1 Object and Class.........................................................................................................4
1.3.2 Object Path.................................................................................................................4
1.3.3 Root Class and Base Classes......................................................................................5
1.4
Basic Example of a Macro..................................................................................................... 6
1.5
Selecting a Macro Editor....................................................................................................... 8
1.6
Storage of a Macro................................................................................................................ 9
1.6.1 Storage in a CATIA Document............................................................................... 10
1.6.2 Storage in a Separate File....................................................................................... 10
1.7
Starting a Macro from a Button........................................................................................... 11
1.7.1 Assigning a Macro to a Button............................................................................... 12
1.7.2 Creating a Toolbar................................................................................................... 12
1.7.3 Assigning a Button to a Toolbar............................................................................. 14
1.8
Blocks of a Macro................................................................................................................ 14
1.8.1 Head of a Macro...................................................................................................... 15
1.8.2 Declaration of Global Variables and Objects......................................................... 16
1.8.3 CATMain, Subroutines, and Functions................................................................. 17
1.9
Branches and Loops............................................................................................................ 19
1.9.1 If-Then-Else............................................................................................................. 19
1.9.2 Select-Case-Else...................................................................................................... 20
00_Ziethen_FM_pi-xx.indd 5
12/28/12 6:05 PM
vi Contents
1.9.3 For-Next.................................................................................................................. 21
1.9.4 Do-While................................................................................................................. 21
1.9.5 Do Until................................................................................................................... 22
1.10
Anchor Objects of CATScript................................................................................................ 23
1.10.1
1.10.2
1.10.3
1.10.4
CATIA-Application.................................................................................................. 23
CATIA Documents “CATPart” and “CATProduct”................................................. 24
Geometry Containers in CATParts........................................................................ 25
Structural Information and Metadata................................................................... 26
1.11
Using the Macro Recorder................................................................................................... 28
1.12
Additional Information......................................................................................................... 29
2
Communicating with the Environment............................................ 31
2.1
Screen Output and Input...................................................................................................... 31
2.1.1 Screen Output......................................................................................................... 31
2.1.2 Screen Input............................................................................................................ 33
2.2
Create, Load, and Save CATIA Documents........................................................................... 34
2.2.1 Creating Documents............................................................................................... 35
2.2.2 Loading Documents................................................................................................ 36
2.2.3 Saving Documents.................................................................................................. 37
2.3
User Selection of CATIA Elements....................................................................................... 38
2.3.1 Selection before Starting a Macro.......................................................................... 39
2.3.2 Selection during the Execution of a Macro........................................................... 40
2.4
Searching and Recognizing Elements................................................................................. 41
2.4.1 Search...................................................................................................................... 41
2.4.2 Recognize................................................................................................................ 42
2.5
Color and Hide Elements..................................................................................................... 44
2.5.1 Coloring Elements.................................................................................................. 44
2.5.2 Hiding Elements..................................................................................................... 45
2.6
Reading and Writing Data.................................................................................................... 46
2.6.1 Create or Declare a File........................................................................................... 46
2.6.2 Reading Data........................................................................................................... 47
2.6.3 Writing Data............................................................................................................ 48
2.7
Executing External Programs and CATScripts..................................................................... 48
2.7.1 External Program.................................................................................................... 49
2.7.2 External CATScript................................................................................................. 49
2.8
00_Ziethen_FM_pi-xx.indd 6
Reading Environment Variables........................................................................................... 50
12/28/12 6:05 PM
Contents vii
3
Components of CATParts................................................................. 53
3.1
Attributes............................................................................................................................. 53
3.1.1 Standard Attributes................................................................................................ 54
3.1.2 Custom Attributes.................................................................................................. 54
3.2
Origin Elements................................................................................................................... 55
3.3
Bodies, Geometrical Sets, and Ordered Geometrical Sets................................................... 55
3.3.1
3.3.2
3.3.3
3.3.4
Bodies...................................................................................................................... 56
Geometrical Sets..................................................................................................... 58
Ordered Geometrical Sets...................................................................................... 59
Boolean Operations between Bodies..................................................................... 61
3.4
Parameters and Relations................................................................................................... 65
3.4.1 Parameter................................................................................................................ 65
3.4.2 Design Table............................................................................................................ 66
3.4.3 Formulas.................................................................................................................. 68
3.5
References.......................................................................................................................... 69
3.5.1
3.5.2
3.5.3
3.5.4
References to Geometry......................................................................................... 70
References to Objects............................................................................................. 70
References to Object Names................................................................................... 70
References to the Name of the Boundary Representation................................... 71
3.6
Direction Definition.............................................................................................................. 74
3.6.1 Direction Defined by a Vector................................................................................ 75
3.6.2 Direction Defined by an Object.............................................................................. 75
4
Components of CATProducts.......................................................... 77
4.1
Attributes............................................................................................................................. 77
4.2
Parameters and Formulas................................................................................................... 78
4.3
Assembly Structure............................................................................................................. 78
4.3.1
4.3.2
4.3.3
4.3.4
Analyzing an Existing Structure ........................................................................... 78
Adding Elements..................................................................................................... 79
Replacing Elements................................................................................................. 80
Deleting Elements................................................................................................... 80
4.4
Constraints.......................................................................................................................... 81
5
2D Wireframe Geometry................................................................... 83
5.1
Sketch References and Sketch Objects.............................................................................. 83
5.2
Creating Sketch Geometry................................................................................................... 85
00_Ziethen_FM_pi-xx.indd 7
12/28/12 6:05 PM
viii Contents
5.3
Defining Construction Elements and the Rotation Axis....................................................... 88
5.4
Creating Constraints............................................................................................................ 89
6
3D Wireframe Geometry and Surfaces........................................... 91
6.1
General Procedure............................................................................................................... 91
6.2
Points................................................................................................................................... 93
6.2.1 Methods for Creating Points.................................................................................. 93
6.2.2 Case Studies: Points................................................................................................ 95
6.3
Lines.................................................................................................................................... 96
6.3.1 Methods for Creating Lines.................................................................................... 97
6.3.2 Case Studies: Lines.................................................................................................. 99
6.4
Planes................................................................................................................................ 101
6.4.1 Methods for Creating Planes................................................................................ 101
6.4.2 Case Studies: Planes.............................................................................................. 102
6.5
Curves............................................................................................................................... 104
6.5.1 Methods for Creating Curves............................................................................... 106
6.5.2 Case Studies: Curves............................................................................................. 109
6.6
Surfaces............................................................................................................................ 111
6.6.1 Methods for Creating Surfaces............................................................................. 112
6.6.2 Case Studies: Surfaces.......................................................................................... 113
6.7
Transformations................................................................................................................. 115
6.7.1 Methods for Creating Transformations.............................................................. 116
6.7.2 Case Studies: Transformations............................................................................ 117
6.8
Operations......................................................................................................................... 118
6.8.1 Methods for Creating Operations........................................................................ 119
6.8.2 Case Studies: Operations...................................................................................... 121
7
Solids................................................................................................ 123
7.1
General Procedure............................................................................................................. 124
7.2
Sketch-Based Solids......................................................................................................... 125
7.2.1 Methods for Creating Sketch-Based Solids......................................................... 126
7.2.2 Case Studies: Sketch-Based Solids....................................................................... 127
7.3
Surface-Based Solids........................................................................................................ 129
7.3.1 Methods for Creating Surface-Based Solids........................................................ 129
7.3.2 Case Studies: Surface-Based Solids...................................................................... 130
00_Ziethen_FM_pi-xx.indd 8
12/28/12 6:05 PM
Contents ix
7.4
Transformation-Based Solids............................................................................................ 132
7.4.1 Methods for Creating Transformation-Based Solids.......................................... 133
7.4.2 Case Studies: Transformation-Based Solids........................................................ 135
7.5
Operations......................................................................................................................... 137
7.5.1 Methods for Creating Operations on Solids........................................................ 138
7.5.2 Case Studies: Operations...................................................................................... 139
8
Featured Object Classes................................................................ 143
8.1
8.2
8.3
8.4
8.5
8.6
8.7
8.8
8.9
8.10
8.11
8.12
8.13
8.14
8.15
8.16
8.17
8.18
8.19
8.20
8.21
8.22
8.23
8.24
8.25
8.26
8.27
8.28
8.29
8.30
8.31
8.32
Add.................................................................................................................................... 143
Angle................................................................................................................................. 143
AngularRepartition............................................................................................................. 144
AnyObject.......................................................................................................................... 144
Application......................................................................................................................... 145
Assemble........................................................................................................................... 149
Axis2D............................................................................................................................... 149
Bodies................................................................................................................................ 150
Body.................................................................................................................................. 150
BooleanShape................................................................................................................... 151
BoolParam......................................................................................................................... 152
CATBaseDispatch............................................................................................................... 152
Chamfer............................................................................................................................. 152
Circle2D............................................................................................................................. 154
CircPattern......................................................................................................................... 155
CloseSurface..................................................................................................................... 157
Collection........................................................................................................................... 157
ConstRadEdgeFillet........................................................................................................... 158
Constraint.......................................................................................................................... 159
Constraints........................................................................................................................ 163
ControlPoint2D................................................................................................................... 164
Curve2D............................................................................................................................. 165
DesignTable....................................................................................................................... 167
Dimension......................................................................................................................... 169
Document.......................................................................................................................... 169
Documents........................................................................................................................ 173
Draft................................................................................................................................... 174
DraftDomain...................................................................................................................... 175
DraftDomains..................................................................................................................... 176
DressUpShape................................................................................................................... 177
EdgeFillet........................................................................................................................... 177
Ellipse2D............................................................................................................................ 178
00_Ziethen_FM_pi-xx.indd 9
12/28/12 6:05 PM
x Contents
8.33
8.34
8.35
8.36
8.37
8.38
8.39
8.40
8.41
8.42
8.43
8.44
8.45
8.46
8.47
8.48
8.49
8.50
8.51
8.52
8.53
8.54
8.55
8.56
8.57
8.58
8.59
8.60
8.61
8.62
8.63
8.64
8.65
8.66
8.67
8.68
8.69
8.70
8.71
8.72
8.73
8.74
8.75
00_Ziethen_FM_pi-xx.indd 10
FaceFillet........................................................................................................................... 179
Factory.............................................................................................................................. 179
Factory2D.......................................................................................................................... 180
File..................................................................................................................................... 182
FileComponent.................................................................................................................. 182
Files................................................................................................................................... 183
FileSystem......................................................................................................................... 183
Fillet................................................................................................................................... 185
Folder................................................................................................................................ 186
Folders............................................................................................................................... 186
Formula............................................................................................................................. 186
GeometricElement............................................................................................................. 187
GeometricElements........................................................................................................... 187
Geometry2D....................................................................................................................... 187
Groove............................................................................................................................... 188
Hole................................................................................................................................... 188
HybridBodies..................................................................................................................... 192
HybridBody........................................................................................................................ 192
HybridShape...................................................................................................................... 193
HybridShape3DCurveOffset............................................................................................... 194
HybridShapeAffinity........................................................................................................... 195
HybridShapeAssemble...................................................................................................... 196
HybridShapeAxisLine......................................................................................................... 200
HybridShapeAxisToAxis..................................................................................................... 201
HybridShapeBlend............................................................................................................. 202
HybridShapeBoundary....................................................................................................... 208
HybridShapeCircle............................................................................................................. 209
HybridShapeCircle2PointsRad........................................................................................... 211
HybridShapeCircle3Points................................................................................................. 213
HybridShapeCircleBitangentPoint..................................................................................... 214
HybridShapeCircleBitangentRadius................................................................................... 216
HybridShapeCircleCenterAxis............................................................................................ 218
HybridShapeCircleCenterTangent...................................................................................... 219
HybridShapeCircleCtrPt..................................................................................................... 221
HybridShapeCircleCtrRad.................................................................................................. 223
HybridShapeCircleExplicit................................................................................................. 224
HybridShapeCircleTritangent............................................................................................. 225
HybridShapeCombine........................................................................................................ 227
HybridShapeConic............................................................................................................. 228
HybridShapeConnect......................................................................................................... 232
HybridShapeCorner........................................................................................................... 234
HybridShapeCurveExplicit................................................................................................. 237
HybridShapeCurvePar....................................................................................................... 237
12/28/12 6:05 PM
Contents xi
8.76 HybridShapeCurveSmooth................................................................................................ 240
8.77 HybridShapeCylinder......................................................................................................... 243
8.78 HybridShapeDirection........................................................................................................ 244
8.79 HybridShapeExtract........................................................................................................... 246
8.80 HybridShapeExtractMulti................................................................................................... 248
8.81 HybridShapeExtrapol......................................................................................................... 252
8.82 HybridShapeExtremum...................................................................................................... 254
8.83HybridShapeExtremumPolar.............................................................................................. 255
8.84 HybridShapeExtrude.......................................................................................................... 257
8.85 HybridShapeFactory.......................................................................................................... 258
8.86 HybridShapeFill................................................................................................................. 288
8.87 HybridShapeFilletBiTangent.............................................................................................. 292
8.88 HybridShapeFilletTriTangent.............................................................................................. 295
8.89 HybridShapeHelix.............................................................................................................. 296
8.90 HybridShapeIntegratedLaw............................................................................................... 299
8.91 HybridShapeIntersection................................................................................................... 302
8.92 HybridShapeInverse.......................................................................................................... 303
8.93 HybridShapeLawDistProj................................................................................................... 304
8.94 HybridShapeLineAngle...................................................................................................... 306
8.95 HybridShapeLineBisecting................................................................................................ 308
8.96 HybridShapeLineBiTangent............................................................................................... 310
8.97 HybridShapeLineExplicit.................................................................................................... 311
8.98 HybridShapeLineNormal.................................................................................................... 312
8.99 HybridShapeLinePtDir........................................................................................................ 313
8.100 HybridShapeLinePtPt......................................................................................................... 315
8.101 HybridShapeLineTangency................................................................................................ 317
8.102 HybridShapeLoft................................................................................................................ 319
8.103 HybridShapeNear.............................................................................................................. 325
8.104 HybridShapeOffset............................................................................................................. 326
8.105 HybridShapePlane1Curve.................................................................................................. 327
8.106 HybridShapePlane1Line1Pt............................................................................................... 328
8.107 HybridShapePlane2Lines................................................................................................... 328
8.108 HybridShapePlane3Points................................................................................................. 329
8.109 HybridShapePlaneAngle.................................................................................................... 329
8.110 HybridShapePlaneEquation............................................................................................... 331
8.111 HybridShapePlaneExplicit.................................................................................................. 332
8.112 HybridShapePlaneMean.................................................................................................... 332
8.113 HybridShapePlaneNormal.................................................................................................. 333
8.114 HybridShapePlaneOffset.................................................................................................... 334
8.115 HybridShapePlaneOffsetPt................................................................................................ 335
8.116 HybridShapePlaneTangent................................................................................................ 335
8.117 HybridShapePointBetween................................................................................................ 336
8.118 HybridShapePointCenter................................................................................................... 337
00_Ziethen_FM_pi-xx.indd 11
12/28/12 6:05 PM
xii Contents
8.119
8.120
8.121
8.122
8.123
8.124
8.125
8.126
8.127
8.128
8.129
8.130
8.131
8.132
8.133
8.134
8.135
8.136
8.137
8.138
8.139
8.140
8.141
8.142
8.143
8.144
8.145
8.146
8.147
8.148
8.149
8.150
8.151
8.152
8.153
8.154
8.155
8.156
8.157
8.158
8.159
8.160
8.161
00_Ziethen_FM_pi-xx.indd 12
HybridShapePointCoord..................................................................................................... 337
HybridShapePointExplicit.................................................................................................. 338
HybridShapePointOnCurve................................................................................................ 338
HybridShapePointOnPlane................................................................................................. 340
HybridShapePointOnSurface............................................................................................. 341
HybridShapePointTangent................................................................................................. 342
HybridShapePolyline.......................................................................................................... 343
HybridShapePositionTransfo.............................................................................................. 344
HybridShapeProject........................................................................................................... 347
HybridShapeReflectLine.................................................................................................... 348
HybridShapeRevol............................................................................................................. 350
HybridShapeRotate............................................................................................................ 351
HybridShapes.................................................................................................................... 353
HybridShapeScaling.......................................................................................................... 353
HybridShapeSection.......................................................................................................... 354
HybridShapeSphere........................................................................................................... 354
HybridShapeSpine............................................................................................................. 356
HybridShapeSpiral............................................................................................................. 358
HybridShapeSpline............................................................................................................ 360
HybridShapeSplit............................................................................................................... 365
HybridShapeSurfaceExplicit.............................................................................................. 368
HybridShapeSweep........................................................................................................... 368
HybridShapeSweepCircle.................................................................................................. 369
HybridShapeSweepConic.................................................................................................. 375
HybridShapeSweepExplicit................................................................................................ 380
HybridShapeSweepLine.................................................................................................... 386
HybridShapeSymmetry...................................................................................................... 395
HybridShapeThickness...................................................................................................... 396
HybridShapeTranslate....................................................................................................... 397
HybridShapeTrim............................................................................................................... 399
Hyperbola2D...................................................................................................................... 402
Intersect............................................................................................................................ 403
IntParam............................................................................................................................ 404
KnowledgeObject.............................................................................................................. 405
KnowledgeActivateObject.................................................................................................. 405
Length............................................................................................................................... 406
Limit.................................................................................................................................. 406
Line.................................................................................................................................... 407
Line2D............................................................................................................................... 408
LinearRepartition............................................................................................................... 408
Loft.................................................................................................................................... 409
Mirror................................................................................................................................. 409
OrderedGeometricalSet..................................................................................................... 410
12/28/12 6:05 PM
Contents xiii
8.162
8.163
8.164
8.165
8.166
8.167
8.168
8.169
8.170
8.171
8.172
8.173
8.174
8.175
8.176
8.177
8.178
8.179
8.180
8.181
8.182
8.183
8.184
8.185
8.186
8.187
8.188
8.189
8.190
8.191
8.192
8.193
8.194
8.195
8.196
8.197
8.198
8.199
8.200
8.201
8.202
8.203
8.204
00_Ziethen_FM_pi-xx.indd 13
OrderedGeometricalSets................................................................................................... 411
OriginElements.................................................................................................................. 412
Pad.................................................................................................................................... 412
Parabola2D........................................................................................................................ 413
Parameter.......................................................................................................................... 413
Parameters........................................................................................................................ 415
Part.................................................................................................................................... 417
PartDocument.................................................................................................................... 421
Pattern............................................................................................................................... 422
Plane.................................................................................................................................. 423
Pocket................................................................................................................................ 424
Point.................................................................................................................................. 425
Point2D.............................................................................................................................. 425
Prism................................................................................................................................. 426
Product.............................................................................................................................. 427
ProductDocument.............................................................................................................. 430
Products............................................................................................................................ 431
RealParam......................................................................................................................... 433
RectPattern........................................................................................................................ 434
Reference.......................................................................................................................... 437
References........................................................................................................................ 437
Relation............................................................................................................................. 437
Relations............................................................................................................................ 439
Remove.............................................................................................................................. 440
RemoveFace...................................................................................................................... 441
Repartition......................................................................................................................... 442
ReplaceFace...................................................................................................................... 442
Revolution.......................................................................................................................... 443
Rib..................................................................................................................................... 443
Rotate................................................................................................................................ 444
Scaling............................................................................................................................... 445
Scaling2............................................................................................................................. 445
SelectedElement............................................................................................................... 446
Selection............................................................................................................................ 447
SewSurface....................................................................................................................... 452
Shaft.................................................................................................................................. 453
Shape................................................................................................................................ 453
ShapeFactory.................................................................................................................... 453
Shapes............................................................................................................................... 467
Shell.................................................................................................................................. 468
Sketch............................................................................................................................... 469
SketchBasedShape........................................................................................................... 471
Sketches............................................................................................................................ 471
12/28/12 6:05 PM
xiv Contents
00_Ziethen_FM_pi-xx.indd 14
8.205
8.206
8.207
8.208
8.209
8.210
8.211
8.212
8.213
8.214
8.215
8.216
8.217
8.218
8.219
8.220
8.221
8.222
8.223
8.224
8.225
Slot.................................................................................................................................... 472
SolidCombine.................................................................................................................... 472
Spline2D............................................................................................................................ 473
Split................................................................................................................................... 474
Stiffener............................................................................................................................. 474
StrParam........................................................................................................................... 475
SurfaceBasedShape.......................................................................................................... 476
Sweep............................................................................................................................... 476
Symmetry.......................................................................................................................... 479
SystemService................................................................................................................... 479
TextStream........................................................................................................................ 481
Thickness.......................................................................................................................... 482
ThickSurface..................................................................................................................... 483
Thread............................................................................................................................... 484
TransformationShape........................................................................................................ 485
Translate............................................................................................................................ 486
Trim................................................................................................................................... 486
TritangentFillet................................................................................................................... 487
UserPattern........................................................................................................................ 488
VarRadEdgeFillet............................................................................................................... 489
VisPropertySet................................................................................................................... 490
9
Featured VBScript Commands...................................................... 497
9.1
9.2
9.3
9.4
9.5
9.6
9.7
9.8
9.9
9.10
9.11
9.12
9.13
9.14
9.15
9.16
9.17
9.18
9.19
Abs.................................................................................................................................... 497
Asc..................................................................................................................................... 497
Boolean............................................................................................................................. 498
Byte................................................................................................................................... 498
CBool................................................................................................................................. 498
CByte................................................................................................................................. 498
CDate................................................................................................................................. 499
CDbl................................................................................................................................... 499
Chr..................................................................................................................................... 499
CInt.................................................................................................................................... 500
CLng.................................................................................................................................. 500
Const................................................................................................................................. 500
Cos..................................................................................................................................... 501
CSng.................................................................................................................................. 501
CStr.................................................................................................................................... 501
Date................................................................................................................................... 502
Day.................................................................................................................................... 502
Dim.................................................................................................................................... 502
Dim ()................................................................................................................................. 503
12/28/12 6:05 PM
Contents xv
9.20
9.21
9.22
9.23
9.24
9.25
9.26
9.27
9.28
9.29
9.30
9.31
9.32
9.33
9.34
9.35
9.36
9.37
9.38
9.39
9.40
9.41
9.42
9.43
9.44
9.45
9.46
9.47
9.48
9.49
9.50
9.51
9.52
9.53
9.54
9.55
9.56
9.57
9.58
9.59
9.60
9.61
9.62
9.63
00_Ziethen_FM_pi-xx.indd 15
Double............................................................................................................................... 503
Do-Until............................................................................................................................. 503
Do-While............................................................................................................................ 503
Empty................................................................................................................................ 503
End.................................................................................................................................... 504
Err...................................................................................................................................... 504
Exit..................................................................................................................................... 504
Exp..................................................................................................................................... 504
Fix...................................................................................................................................... 505
For-Next............................................................................................................................. 505
Function............................................................................................................................. 505
Hour................................................................................................................................... 505
If-Then-Else....................................................................................................................... 506
InputBox............................................................................................................................ 506
InStr................................................................................................................................... 506
Int...................................................................................................................................... 506
Integer............................................................................................................................... 507
IsDate................................................................................................................................ 507
IsEmpty.............................................................................................................................. 507
IsNull................................................................................................................................. 508
IsNumeric.......................................................................................................................... 508
Join.................................................................................................................................... 508
LCase................................................................................................................................. 509
Left.................................................................................................................................... 509
Len..................................................................................................................................... 509
Log..................................................................................................................................... 510
Long................................................................................................................................... 510
LTrim.................................................................................................................................. 510
Mid.................................................................................................................................... 511
Minute............................................................................................................................... 511
Mod................................................................................................................................... 511
Month................................................................................................................................ 512
MsgBox.............................................................................................................................. 512
Now................................................................................................................................... 512
Null.................................................................................................................................... 512
On Error Resume Next....................................................................................................... 513
Randomize......................................................................................................................... 513
ReDim................................................................................................................................ 513
Rem................................................................................................................................... 514
Right.................................................................................................................................. 514
Rnd.................................................................................................................................... 514
RTrim................................................................................................................................. 514
Second.............................................................................................................................. 515
Select Case........................................................................................................................ 515
12/28/12 6:05 PM
xvi Contents
9.64
9.65
9.66
9.67
9.68
9.69
9.70
9.71
9.72
9.73
9.74
9.75
9.76
9.77
9.78
Set..................................................................................................................................... 515
Sin..................................................................................................................................... 515
Single................................................................................................................................ 516
Sgn.................................................................................................................................... 516
Sqr..................................................................................................................................... 516
StrReverse......................................................................................................................... 517
String................................................................................................................................. 517
Sub.................................................................................................................................... 517
Tan..................................................................................................................................... 517
Time................................................................................................................................... 518
Timer................................................................................................................................. 518
TimeValue.......................................................................................................................... 518
Trim................................................................................................................................... 519
UCase................................................................................................................................ 519
Year................................................................................................................................... 519
Index............................................................................................................ 521
00_Ziethen_FM_pi-xx.indd 16
12/28/12 6:05 PM
Preface
Among today’s computer-aided design (CAD) systems, CATIA (Computer-Aided Threedimensional Interactive Application) is one of the most widely used in the world. CATIA
V5 allows users to automatically create components and reduce repetitive tasks through
macros. With pure parametric 3D models this functionally is simply not possible. Unfortunately, there are few books that address the specific concerns of macro programming
with CATIA V5. The help documentation of the CATIA V5 macro interface is often too
narrow and incomplete. This practical book provides an introduction to the automated
creation of CATParts, CATProducts, and geometry. The questions a beginner will face during
the process of macro programming are answered clearly and efficiently. An advanced user
will find many suggestions in the macro examples, explained in detail and documented
with in-depth descriptions. This book deals with the macro programming of CATScript and
CATVBS languages, an extension of Microsoft’s “Visual Basic Script” (MS VBScript).
Therefore CATScript and CATVBS are platform-independent and run on Windows and
UNIX.
Readers of this book should have a basic knowledge of CATIA V5. The focus is on users of
CATIA V5 applications who want to automate repetitive tasks of daily work.
Knowledge in the following areas is recommended for beginners (Table 0.1):
� Basic knowledge of modeling with CATIA V5 Part Design (PDG), Assembly Design
(ASD), Wireframe & Surface Design (WSD), or Generative Shape Design (GSD)
� Basic knowledge of any programming language
Table 0.1 Scope of V5 Macro Programming in This Book
Part Design
00_Ziethen_FM_pi-xx.indd 17
Wireframe & Surface
Design
Generative Shape
Design
Assembly
Design
12/28/12 6:05 PM
xviii Preface
This book is organized into sections, from the requirements of a beginner to that of an
advanced user. The following topics will be covered:
� Basics
� Communication with the Environment
� Components of CATParts
� Components of CATProducts
� 2D Wireframe Geometry
� 3D Wireframe Geometry and Surfaces
� Solids
� Featured Object Classes
� Featured VBScript Commands
The chapter “Basics” gives an introduction to how V5 macros are created. It contains
the fundamental knowledge that is required for macro programming. It shows how macros
are created, stored, and executed as well as interactions with the user for input and
output.
The chapter “Communication with the Environment” is based on practical examples
of how V5 macros can communicate with the system environment or the user. Through
clear descriptions, it is also possible for a beginner to develop their macros involving a
user.
The chapters “Components of CATParts” and “Components of CATProducts” explain how to create a macro and the requirements for creating geometry. This is the foundation of all Bodies, Geometrical Sets, and Product Structures.
The chapters “2D Wireframe Geometry,” “3D Wireframe Geometry and Surfaces,”
and “Solids” provide the foundation of how geometry can be created by a V5 macro.
Numerous case studies illustrate these important concepts and best practices.
If readers have worked through the previous chapters and case studies, the last two chapters
“Featured Object Classes” and “Featured VBScript Commands” allow them to solve
their own practical tasks.
The theory of this book is supported in many places with sample macros. Many of the
examples are available online at www.mhprofessional.com/catiav5 for download. Examples that can be downloaded from the Internet are identified by a yellow round stamp with
“WWW” inside.
The contents of this book are based on the software version “V5R19.” It is important to
note that with each release, Dassault Systémes adds more methods of programming, but
existing methods are only very rarely changed. This book can be used with higher software
versions.
Gröbenzell
00_Ziethen_FM_pi-xx.indd 18
Dieter R. Ziethen
12/28/12 6:05 PM
CATIA V5
00_Ziethen_FM_pi-xx.indd 19
12/28/12 6:05 PM
This page intentionally left blank
00_Ziethen_FM_pi-xx.indd 20
12/28/12 6:05 PM
1
Basics
This chapter will introduce users to programming macros in CATIA V5 with Visual Basic
Script (VBScript). The following topics are covered:
ƒƒ Basic concepts of VBScript
ƒƒ General structure of a macro
ƒƒ Icons and storage of a macro
ƒƒ Macro editor
ƒƒ Macro recorder
„„ 1.1 Definition of CATScript and CATVBS
CATScript and CATVBS are both VBScript programming languages. Both macro languages
work with objects and methods. An object is a container that stores information. This
information could be a CATPart, a line, or a surface. A method is an instruction from
which an object is created or modified, or from which information is read.
CATVBS is a type of Microsoft VBScript (MS VBScript) that is extended to objects and
methods of CATIA V5. Up to V5R7, CATVBS only ran on Windows machines. From V5R8
on, Dassault Systémes have expanded their programming so that CATVBS also operates
on UNIX workstations.
CATScript is a variant of MS VBScript that is designed to run on UNIX and Windows.
CATScript was able to run on both platforms prior to V5R8.
CATScript and CATVBS are interpreter languages that serve as the foundation for programming macros in CATIA V5. Macros that are written in CATScript or CATVBS can be
used on Windows 7, Vista, XP, NT, 98 and 2000, and UNIX operating systems.
01_Ziethen_Ch01_p001-030.indd 1
12/28/12 10:17 AM
2 1 Basics
TABLE 1.1 Overview of the Macro Languages in CATIA V5
Language
File Format
Description
Application
CATScript
*.CATScript
Reduced VBScript
Interpreter (Windows, UNIX)
Macros (Win and UNIX), CATIA
Knowledgeware
CATVBS
*.catvbs
Complete VBScript Interpreter
(Windows, UNIX, since 5R8)
Macros (Win and UNIX), CATIA
Knowledgeware
CATVBA
*.catvba
Visual Basic for Applications
Compiler (Win)
Menu-based
Applications (Win)
Programming CATIA macros with Visual Basic for Applications (CATVBA) offers more
capabilities for CATIA V5. CATVBA has a compiler and provides many tools for designing
user interfaces. These two points distinguish it from CATScript and CATVBS. An overview of all three languages is shown in Table 1.1.
The program syntaxes of CATScript, CATVBS, and CATVBA are very similar. By making
slight changes, program components are very easily transferred from one platform to
another, as long as other methods and objects in that platform are available. In most
cases, the three languages differ only in the way that variables, functions, and procedures
are defined. An overview of these differences is illustrated with a small sample program in
Table 1.2. The differences are highlighted in bold.
TABLE 1.2 Differences between CATScript, CATVBA, and CATVBS
CATScript and CATVBA
CATVBS
Sub CATMain ()
‘ Create New CATPart -------Dim D As Document
Set D = CATIA.Documents.Add (“Part”)
‘ Create Open Body ---HB Dim As HybridBody
Set HB = HBodyCreate(D)
Set Wzk3D = D.Part.HybridShapeFactory
‘ Create Points -------------Dim I As Integer
For i - l To 100
Dim P As HybridShapePointCoord
Set P = Wzk3D.AddNewPointCoord (I *
10, 0, 0)
HB.AppendHybridShape P
Next
D.Part.Update
End Sub
Sub CATMain ()
‘ Create New CATPart -------Dim D
Set D = CATIA.Documents.Add (“Part”)
‘ Create Open Body ---Dim HB
Set HB = HBodyCreate(D)
Set Wzk3D = D.Part.HybridShapeFactory
‘ Create Points --------------Dim I
For I = l To 100
Dim P
Set P = Wzk3D.AddNewPointCoord (I
* 10, 0, 0)
HB.AppendHybridShape P
Next
D.Part.Update
End Sub
Function HBodyCreate (D As Document) As
HybridBody
HB Dim As HybridBody
Set HB = HB = D.Part.HybridBodies.Add
Set HBodyCreate = HB
End Function
Function HBodyCreate (D)
Dim HB
Set HB = D.Part.HybridBodies.Add
Set HBodyCreate = HB
End Function
01_Ziethen_Ch01_p001-030.indd 2
12/28/12 10:17 AM
1.2 Definition of Nomenclature 3
Since CATScript through its history has the closest connection with CATIA V5, all programming examples and source code in this book are based on CATScript. Through the
differences shown in Table 1.2, the examples can very easily be transferred into CATVBS.
„„ 1.2 Definition of Nomenclature
Nomenclature explains the definition of terms used in the following sections. This book
outlines how instructions are used by CATScript. An instruction may be:
ƒƒ A general description
ƒƒ An example of the source code in a macro
A general description provides all the capabilities of the commands in an instruction. One
example describes a string that is used in a specific application.
Word
An instruction is usually composed of several words. A word is the smallest unit of an
instruction. Two words are separated, depending on the application, by a period, a comma,
or a space. Important words in a general description and in examples are highlighted in
bold.
Example 1.1: Highlighting Important Words
Line.Length = 100
Additional information of a general description can be enclosed in square brackets or
braces.
A square bracket encloses words that can be defined by a programmer. A self-defined word
can be a name or the contents of memory location. If the memory location is defined by a
programmer, it is called a Variable. A memory location for an object or a subroutine is
called a Parameter. The information following a square bracket with the keyword “As”
determines the type of variable or parameter. If several variables or parameters have the
same type, they can be listed within the same square bracket.
[Self-defined word]
Example 1.2: Description of Variables and Parameters
General Description:
Definition.TwoLines [Line l, Line 2] As Line
Code in the macro:
Definition.TwoLines Center_Line, Drawing_Direction
A curly brace encloses optional words that do not need to be written. A programmer can
determine the number of words that are shown by a comma and three periods.
01_Ziethen_Ch01_p001-030.indd 3
{Optional word}
12/28/12 10:17 AM
4 1 Basics
Example 1.3: Optional Words
General Description:
Definition.Lines [{Line 1{, Line 2, ...}] As Line
Code in the macro:
Definition.Lines Center_Line
„„ 1.3 Definition of Object, Class, and Object Path
CATScript is an object-oriented programming language, so in order to program CATScript
it is necessary to understand a few basic principles of an object-oriented language.
1.3.1 Object and Class
An Object is a container that stores information. Each object is assigned a class. A Class
is a description of the information structure of objects of the same object type. Within a
class’s properties and methods, each object has a class.
A Property is a characteristic of an object. A property is usually being read or changed
through the value of its parameter. Some properties can only be read but not changed. In
this case the property is referred to as having “read only” access.
A Method is an instruction used to modify an existing object or create a new one. A
method can have multiple input parameters and output parameters. An output parameter
is the result of applying a method. If a method has an output parameter, then it is called
either a function (Func) or a subroutine (Sub).
Example 1.4: Properties and Methods of the “Line” Class
Properties: Start Point, End Point, Length (Read Only)
Methods: Sub Set _Start Point, Sub Set _End Point
Each object of the “Line” class has a start point and an end point that can be assigned. The
length of a line can be read but not written. Both methods do not have an output parameter because they are subroutines.
1.3.2 Object Path
The classes of CATScript are hierarchically structured. A hierarchical structure has
parent and child classes. A parent class summarizes a group of child classes and provides the basic methods and properties available for these classes. The deeper a class is
01_Ziethen_Ch01_p001-030.indd 4
12/28/12 10:17 AM
1.3 Definition of Object, Class, and Object Path 5
placed, the more specialized are its objects. An object can access all properties and
methods of its class and the parent classes. This dependency describes the object path
of an object. An Object Path is the explanation of the dependencies of an object from
its class and parent classes. In the case of an object path, classes are separated by periods, and child classes are written to the right:
Class hierarchy 0.Class hierarchy 1. ... .Class hierarchy n
Example 1.5: Object Path of Pads and Pockets
Class hierarchy n:
Class hierarchy n+1:
Class hierarchy n+2:
Object Paths:
Solid
Contour-based Solid
Pad, Pocket
... .Solid.Contour-based Solid.Pad
... .Solid.Contour-based Solid.Pocket
An object of the “Pad” class can use the properties and methods of the “Solid,” “Contourbased Solid,” and “Pad” classes but not the “Pocket” class. The hierarchy is illustrated in
Table 1.3.
TABLE 1.3 Example of a Class Hierarchy
Hierarchy 0 to n-1
... Other Higher-Level Classes ...
Hierarchy n
Solid
Hierarchy n+1
Contour-based Solid
Hierarchy n+2
Pad
Pocket
1.3.3 Root Class and Base Classes
A complete object path begins with a root class. A Root Class is the class that stands on
the top hierarchy level and from which all other classes and objects are derived.
The root class of all objects in CATScript is the CATBaseDispatch class (Section 8.12).
CATBaseDispatch has no properties or methods. From CATBaseDispatch, the two
subordinate base classes are derived from AnyObject for individual objects and
Collection for list objects (Table 1.4). In the case of an object’s path, the root class
CATBaseDispatch is typically not written but started directly with a base class.
TABLE 1.4 Root Class and Base Classes of CATScript
CATBaseDispatch
AnyObject
Collection
(Individual Objects)
(List Objects)
An Individual Object is a container for geometry or other information. Each object path
of an individual object begins with the base class AnyObject (Section 8.4). AnyObject
provides basic methods for each individual object.
01_Ziethen_Ch01_p001-030.indd 5
12/28/12 10:17 AM
6 1 Basics
A List Object is a collection of individual objects. Each object path of list objects begins
with the base class Collection (Section 8.17). Collection provides basic methods for
each list object.
Example 1.6: Object Paths for Individual and List Objects
AnyObject.Constraint
AnyObject.GeometricElement.Geometry2D.Point2D.ControlPoint2D
Collection.Parameters
Collection.Relations
„„ 1.4 Basic Example of a Macro
For a practical understanding of the sections below, the foundational theory of programming is started with a basic example. In the “GreetingMacro.CATScript” macro, a user is
greeted with the text “Hello.” In order to prepare the input of the macro, follow these
steps:
ƒƒ Start CATIA V5
ƒƒ Create new CATPart via “File/New”
ƒƒ Select “Tools/Macro/Macros” (or press ALT+F8) from the menu bar
The “Macros” window (Figure 1.1) shows all the macros that are available for immediate
execution. The window is fully explained in Section 1.6. Initially the list is empty.
FIGURE 1.1
Macros window
The next step is to create a new macro and name it “GreetingMacro.CATScript”
(Figure 1.2):
ƒƒ Select the “Create…” button
ƒƒ Select “CATScript” as the Macro language
ƒƒ Enter “GreetingMacro.CATScript” as the Macro name
ƒƒ Select the “OK” button
01_Ziethen_Ch01_p001-030.indd 6
12/28/12 10:17 AM
1.4 Basic Example of a Macro 7
FIGURE 1.2 “Create
a new macro” window
Now the “GreetingMacro.CATScript” macro has been created and will appear in the
“Macros” window (Figure 1.3).
FIGURE 1.3 “Macros”
window with the
“Greeting-Macro.
CATScript” macro
A macro can be edited using the internal V5-Editor. The V5-Editor is a simple text entry
tool, comparable to “Notepad” in Windows.
ƒƒ Select the “Edit…” button
CATIA V5 opens the V5-Editor and the source code
of the macro, “GreetingMacro.CATScript,” is shown
(Figure 1.4).
The main part of a macro is defined at the beginning
and the end of the source code with the following
expressions:
Sub CATMain ()
...
End Sub
FIGURE 1.4 Internal
V5-Editor
All commands between or above these two lines are run each time a macro is called. To
complete the macro, the word “Hello” is added to a command, generating a dialog box. The
commands for input and output on the screen are explained in detail in Section 2.1.
Sub CATMain ()
MsgBox (“Hello!”)
End Sub
A macro can be saved by selecting the disk icon of the V5-Editor. The macro “GreetingMacro.CATScript” is stored, in this case, in the current document “Part1.CATPart”
(Figure 1.3). The V5-Editor will close, and the macro can be run.
01_Ziethen_Ch01_p001-030.indd 7
12/28/12 10:17 AM
8 1 Basics
ƒƒ Select the “Save” button (disk icon)
ƒƒ Select “File/Exit” in the V5-Editor
ƒƒ Select the “Run” button in the “Macros” window
This will start the macro. During the execution, a review of the program logic and syntax
will be made. Since it is an interpreted language, the macro is executed line by line. If the
interpreter finds an error, the macro is canceled during the run. If the source code of the
macro is correct, the greeting “Hello!” will be seen on the screen (Figure 1.5).
FIGURE 1.5 Output
of the macro
“GreetingMacro.
CATScript”
With this basic example, all steps are shown that are necessary for the entry and execution of a macro. The following sections show how to edit, load, save, and run a macro.
„„ 1.5 Selecting a Macro Editor
In the previous section, the Internal V5-Editor was used. The internal V5-Editor is a very
simple text editor, which is granted as the default editor in CATIA V5. It is utilized automatically when a macro is being processed. An overview of the functionality is provided in
Table 1.5.
TABLE 1.5 Functionality of the internal V5-Editor
Button
01_Ziethen_Ch01_p001-030.indd 8
Description
New File
Closes a current file and opens a blank macro-document.
Open File
Opens a dialog box to open a macro file.
Save File
Opens a dialog box for saving a macro-document—or if a
file already exists, saves a macro-document.
Go to Line
Asks for a line number and jumps to the appropriate line.
Search
Asks for a string and looks for it in the macro-document.
Insert Object Resolution
Adds code in a macro-document that declares a reference to
an object at the location of the cursor line (see Section 3.5).
The object can be selected interactively.
Object Browser
Opens the object browser, which provides an overview of the
classes of CATScript.
12/28/12 10:17 AM
1.6 Storage of a Macro 9
It is possible to choose a different editor to edit a macro. During the execution of a CATIA
V5 macro, the editor will start automatically and is defined by the options in V5. The
options window is found under “Tools/Options/General/Macros” (Figure 1.6).
FIGURE 1.6 Options
window to select a
macro editor
For smaller macros, the internal V5-Editor is quite sufficient. However, for intensive macro
work, it can be convenient to have a more powerful editor. Select the “Change editor”
button to choose a different editor. The “Default editor” button resets the editor option
back to the original state, as shown in Figure 1.6.
„„ 1.6 Storage of a Macro
A macro can be stored in two ways:
1. storage in a CATIA document (*.CATPart, *.CATProduct, *.CATDrawing)
2. storage in a separate file (*.CATScript)
In the first case, a macro is stored inside of a CATIA document. Thus, a macro and a CATIA
document are closely linked. A CATIA document is a part, product, or a drawing. It can
contain multiple macros.
In the second case, a macro is stored inside a folder with the file type “*.CATScript” and
can be used independently of a CATIA document.
01_Ziethen_Ch01_p001-030.indd 9
12/28/12 10:17 AM
10 1 Basics
1.6.1 Storage in a CATIA Document
In the “Macros” window and from the “Current macro library or document:” drop-down
(Figure 1.7), select a CATIA document. A macro that is created via the “Create…” button
is stored in this document. A list of “Available macros” in the “Macros” window shows all
the macros that are stored in the selected document. The “Run” button starts the selected
macro.
FIGURE 1.7
“Macros” window and
available macros in a
CATIA document
1.6.2 Storage in a Separate File
If a macro is stored in a separate file, you should define a macro library before you create
the macro. A Macro Library is a directory where macros are stored, and CATIA is directed to their location. By using a macro library, a user receives quick access to all of the
macros within the selected directory.
FIGURE 1.8 “Macro
libraries” window with
a list of current
libraries
A macro library is created in the “Macro libraries” window (Figure 1.8). It appears by
clicking the “Macro libraries” button in the “Macros” window. If programmed with
CATScript as the library type, it is seen in the “Directories” drop-down. The other types are
based on programming with VBA (see Section 1.1). The list in the “Current libraries:” field
displays all currently defined macro libraries of one library type. To add a new directory to
the list, select the “Create new library…” button.
01_Ziethen_Ch01_p001-030.indd 10
12/28/12 10:17 AM
1.7 Starting a Macro from a Button 11
In the “Macros” window, a macro library can be selected from the “Current macro library
or document:” drop-down (Figure 1.9). The list of “Available macros:” shows all macros in
a macro library.
FIGURE 1.9
“Macros” window
with a macro in the
macro library
“C:\Temp”
To create a new macro and add it to a macro library, select the “Create…” button. This
opens the “Create a new macro” window (Figure 1.10), which defines a new macro. Select
“OK” to store the macro in the current macro library.
FIGURE 1.10
“Create a new
macro” window
To run a macro from a separate file, open the “Macros” window, choose the appropriate
macro from the list, and select “Run.”
When using macros extensively, it can be repetitive to always open the “Macros” window
and select the appropriate macro library and macro. A shorter way is to run a macro from
a button.
„„ 1.7 Starting a Macro from a Button
A macro that is stored in a separate file (see Section 1.6.2) can be assigned to a button.
A button can be added to a toolbar and displayed on the user interface of CATIA. A toolbar
is a group of icons that is defined by a user via the command “View/Toolbars.” Toolbars
can be shown or hidden.
01_Ziethen_Ch01_p001-030.indd 11
12/28/12 10:17 AM
12 1 Basics
To show a macro as a button on the user interface, follow these steps:
1. Assign a macro to a button
2. Create a toolbar
3. Assign the button to the toolbar
1.7.1 Assigning a Macro to a Button
A macro can be assigned to a button:
FIGURE 1.11
Customize window
with “Commands”
current macros list
Select “Tools/Customize” from the menu bar and then move over to the “Commands”
tab. In the “Categories” column, scroll down and select “Macros.” In the “Commands”
column on the right, a list of all macros in the currently selected library will be displayed (Figure 1.11). If no macros are visible, review the selected macro library (see
Section 1.6.2). An icon can be assigned to a macro button by highlighting the desired
macro in the “Commands” list and selecting the “Show Properties” button. Pick an icon
from the “Icon Browser” button, or navigate to an icon through the button folder. Selecting an icon automatically assigns it to the macro button. Selecting “Reset…” returns
the macro’s button icon to the original state.
1.7.2 Creating a Toolbar
A toolbar displays a group of buttons and is always assigned to a work environment.
01_Ziethen_Ch01_p001-030.indd 12
12/28/12 10:17 AM
1.7 Starting a Macro from a Button 13
FIGURE 1.12
Customize window
“Toolbars” tab
A work environment is a workbench (e.g. “Part Design,” for the modeling of solids).
A workbench is the workspace that is active in the CATIA session. By assigning a toolbar
to a workbench, the toolbar is available and can be controlled by users.
FIGURE 1.13 “New
Toolbar” window
The list of all toolbars in the current work environment is located in the “Toolbars” tab of
the “Customize” window (Figure 1.12). The window will open with the command “Tools/
Customize.”
By selecting “New,” a new toolbar is created in the current workbench and the “New Toolbar”
window opens (Figure 1.13). This is a toolbar, which can be given a descriptive name.
The “OK” button closes the window, and the new toolbar is added to the “Toolbars” tab of the
“Customize” window (Figure 1.14).
01_Ziethen_Ch01_p001-030.indd 13
12/28/12 10:17 AM
14 1 Basics
1.7.3 Assigning a Button to a Toolbar
Assigning a button to a toolbar is controlled through the “Customize” window with the
“Toolbars” tab. In the “Toolbars” tab, select a toolbar and then add a button by selecting
the “Add commands…” button (Figure 1.14).
FIGURE 1.14
“Customize” window,
Toolbars tab with
user-defined toolbar
“My Macros”
This will open the “Commands list” window, and then the
desired command can be assigned (Figure 1.15). The macros
of the current macro library are listed in the “Commands
list.” Click “OK” to add the macro button to the toolbar and
complete the process.
FIGURE 1.15
“Commands list”
window
„„ 1.8 Blocks of a Macro
A Block is a group of instructions in the source code of a macro. Together they include
organizational or logical commands. The source code of a macro is usually composed of
the following blocks:
1. Head of a macro
2. Declaration of global variables and objects
01_Ziethen_Ch01_p001-030.indd 14
12/28/12 10:17 AM
1.8 Blocks of a Macro 15
3. Main block “CATMain”
4. Subroutines and functions that are called from “CATMain”
1.8.1 Head of a Macro
The head of a macro contains descriptive information about the name, author, and function of the macro as well as important information for the maintenance of the code. This
information typically includes:
ƒƒ Macro name
ƒƒ Version description
ƒƒ Macro language
ƒƒ Brief description of what the macro does
ƒƒ Author and date of creation
ƒƒ Details of a revision (date, person modifying the code, change description)
This information is stored in comment lines. A comment line begins with a single quote
and is ignored when a macro is executed (see Section 9.58).
‘ This is the comment
You may need to tell a user what version of a macro is currently being used. In order for this
information to be understood it is recommended not to open a macro’s source code, but
instead complement the head of a macro with one line of code that displays this information. This can be done with the StatusBar property of the Application class (Section 8.5).
An object of the Application class directly represents CATIA (Section 1.10.1).
APPLICATION.StatusBar As CATBSTR
Example 1.7: Head of a Macro
At the beginning of the macro “DRILLTABLE.CATScript,” the name and version of the
macro are displayed in the status bar of CATIA (Figure 1.16).
‘ Macro:
DRILLTABLE.CATScript
‘ Version: 1.2
‘ Code:
CATIA CATScript
‘ Purpose: Creates a drill table by looking for all holes
‘
in a CATPart and reads their centers then
‘
prints the results to a text file with the
‘
name drilltable.txt.
‘ Author:
John Smith, Department XYZ, Phone 555-5555
‘ Date:
12.31.2002
‘-------------------------------------------------------‘ Change:
01.15.2003, Hugo Müller
‘
Drilling depth added to the drilling table.
‘-------------------------------------------------------CATIA.StatusBar = “DRILLTABLE.CATScript, Version 1.2”
01_Ziethen_Ch01_p001-030.indd 15
12/28/12 10:17 AM
16 1 Basics
FIGURE 1.16
Example of “Head of
a Macro”
1.8.2 Declaration of Global Variables and Objects
Global variables and objects are declared in the next block. A global variable or object is an
element that is available in all functions and subroutines of a macro.
The declaration of a single variable or an object is done via the Dim statement Dim ()
(Section 9.19). A variable or object can be single- or multi-dimensional.
Dim
Dim
Dim
Dim
[Variable1] {, [Variable2]} {As Variable Type}
[Object1] {, [Object2]} {As Class}
[Variable Field] ({Dimension}) {As Variable Type}
[Object Field] ({Dimension}) {As Class}
A list of classes is in Chapter 8. The main variable types are:
ƒƒ Boolean:
ƒƒ CATBStr:
ƒƒ CATSafeArrayVariant:
ƒƒ CATVariant:
ƒƒ Double:
ƒƒ Integer:
ƒƒ Long:
ƒƒ String:
Logical statement (“True” or “False”)
String of CATIA expressions (e.g. “Pad.1”)
Field of CATIA expressions (mostly coordinates)
Index of a list of objects (integer or object)
Floating point with double precision
Integer
Integer with an increased range
String
It is recommended to assign a start value to a global variable or an object. The assignment
of an object to a variable is made by using “=” and the command Set:
[Variable] = [Value]
Set [Object] = [Content]
Example 1.8: Declaration of Global Variables and Objects
In a macro, the global “input” and “output” variables are declared as a text, and “numbers”
are declared as integers. The global object “Document” is declared as the object type
“Document.”
01_Ziethen_Ch01_p001-030.indd 16
12/28/12 10:17 AM
1.8 Blocks of a Macro 17
... Head of the macro ...
‘ Global Declarations -------------------------------------Dim Input, Output As String
Dim Count As Integer
Dim myDocument As Document
Input = “Enter Text”
Output = “”
Count = 0
Set myDocument = CATIA.ActiveDocument
... CATMain () ...
1.8.3 CATMain, Subroutines, and Functions
The head of the macro and global declarations are followed by the macro block “CATMain,”
which contains subroutines and/or functions. CATMain and the following subroutines
and functions can include global and local variables and objects. A local variable or local
object is only valid within its respective range and is similar to a function or subroutine
that declares a global variable or a global object (Section 1.8.2).
1.8.3.1 CATMain
“CATMain” is the main block of a macro from which instructions are run each time the
macro is executed:
... Head of the macro ...
... Declaration of global variables and objects ...
Sub CATMain ()
... Declaration of local variables and objects ...
Instruction 1
Instruction 2
...
End Sub
Within “CATMain” you should place just a few critical lines of code in a macro and then access
additional code by calling subroutines (Sub) and/or functions (Function). This way the source
code is easier to read. A subroutine or function can be called multiple times by CATMain.
Calls to other subroutines and functions are possible within a subroutine or function.
1.8.3.2 Subroutines
A subroutine is a sequence of instructions that performs an action. A call is made via the
name of the subroutine followed by an optional parameter list:
Subroutine {[Parameter], ...}
01_Ziethen_Ch01_p001-030.indd 17
12/28/12 10:17 AM
18 1 Basics
Declaring a subroutine is performed between the Sub and End Sub statements:
Sub Subroutine {([Parameter] As Variable Type, ...)}
... Declaration of local variables and objects ...
Instruction 1
Instruction 2
...
End Sub
Example 1.9: Subroutine
The subroutine “MultiplicationOutput” is called several times within the “CATMain”
block. A dialog box displays the result of multiplying two integers.
Sub CATMain ()
MultiplicationOutput 1, 3
MultiplicationOutput 2, 3
MultiplicationOutput 16, 32
End Sub
Sub MultiplicationOutput (I, II As Integer)
Dim Box
Box = MsgBox (I * II)
End Sub
1.8.3.3 Functions
A function is a sequence of instructions that returns a single value. A function can be
passed to parameters while it is being called. Parameters are written after the function
name in brackets:
[Variable] = Function {([Parameters], ...)}
Declaring a function is performed between the Function and End Function statements:
Function Function {([Parameters] As Variable Type, ...)} As Variable Type
... Declaration of local variables and objects ...
Instruction 1
Instruction 2
...
[Function] = [Value]
End Function
The return value is assigned to the variable with the function name.
Example 1.10: Function
The function “Multiplication” multiplies two integers and returns the result of the multiplication. The return value is displayed in a dialog box.
Sub CATMain ()
Dim Box
Box = MsgBox (Multiplication (1, 3))
End Sub
01_Ziethen_Ch01_p001-030.indd 18
12/28/12 10:17 AM
1.9 Branches and Loops 19
Function Multiplication (I, II As Integer) As Integer
Multiplication = I * II
End Function
„„ 1.9 Branches and Loops
A branch is a control that determines the basis of testing a criterion from which instruction blocks are run in a macro. A branch is defined by the statement “If-Then-Else” or
“Select-Case-Else.”
A loop is a series of instructions that are executed repeatedly. In CATScript there are
three types of loops, which are defined by the statements “For-Next,” “Do While,” and
“Do-Until.”
1.9.1 If-Then-Else
“If-Then-Else” describes a branch that separates two instruction blocks. A branch needs a
criterion to decide whether the first or the second instruction block is executed. If the
criterion of a branch is met, the instruction block is executed after the “Then” statement.
If the test criterion is not met, the instruction is executed according to the “Else” statement. The “Else” statement is optional and can be omitted. The general syntax of the
statement “If-Then-Else” is:
If test criterion Then
Instruction 1
{Instruction 2
...
Else
Instruction 1
Instruction 2
...}
End If}
The instruction that follows is the “Then” statement next an “End If” statement, and the
“Else” statement is optional. “End If” marks the end of the “If-Then-Else” statement.
Example 1.11: If-Then-Else
a)
If A = 1 Then C = 2
b)
If (A> = 1) And (B = 2) Then
C = 2
D = 1
End If
01_Ziethen_Ch01_p001-030.indd 19
12/28/12 10:17 AM
20 1 Basics
c)
If Not
C =
Else
C =
D =
End If
((A = 1) And (B = 1)) Then
1
A * B
A - B
Several criteria can be linked by the words “And” and “Or” to other complex criteria. The
“And” statement specifies that both test criteria must be met. The “Or” statement specifies that one criterion must be met by either instruction. The word “Not” negates a criterion. Multiple criteria can also be nested in brackets. Examples are given in Table 1.6.
TABLE 1.6 Examples of Criteria
Criterion
Result of “True”
Result of “False”
(A = 1) And (B = 1)
A = 1; B = 1
A = 2; B = 1
(A = 1) Or (B = 1)
A = 2; B = 1
A = 2; B = 2
(A = 1) And ((B = 1) Or (C = 1))
A = 1; B = 2; C = 1
A = 1; B = 2; C = 2
Not (A = 1)
A=2
A=1
1.9.2 Select-Case-Else
“Select-Case-Else” describes a branch separated by two or more instruction blocks.
“Select-Case-Else” is more powerful than an “If-Then-Else” statement. The instruction
block begins with the keyword “Case.” The keyword is followed by the test criterion and
the instruction block itself. The criterion is a test value or a list of multiple test values. An
instruction block is executed only if the test value or one of the test values matches the
keyword “Case.” If no matching value is found, the “Case Else” statement is run if it exists;
otherwise the macro runs through the instruction block.
Select Case [Variable]
Case Value1 {,Value2 {,...}}
Statement Block 1
{Case ... }
{Case Else
Statement Block n}
End Select
Example 1.12: Select-Case-Else
Dim Input
Input = InputBox (“Enter a number between 0 and 2:”, 0)
Select Case Input
Case “0”
MsgBox (“Number = 0”)
Case “1”, “2”
MsgBox (“Number > 0”)
Case Else
MsgBox (“Wrong Input”)
End Select
01_Ziethen_Ch01_p001-030.indd 20
12/28/12 10:17 AM
1.9 Branches and Loops 21
1.9.3 For-Next
“For-Next” describes a loop that is controlled by a counter. The counter has an initial and
a final value. The counter begins with an initial value, which is incremented by a fixed step
size value toward a final value. If no increment is defined, the step size value is equal to 1.
“Next” indicates the end of the loop. The general syntax for a “For-Next” loop is:
For [Counter] = [Initial Value] To [Final Value] {Step [Increment]}
Instruction 1
{Instruction 2
...}
Next
The “Exit For” statement terminates the loop. With this statement the macro moves to
the next statement after the line “Next.” To keep the code organized, this statement
should be rarely used.
Example 1.13: For-Next
This example demonstrates a loop that adds up the numbers “1” to “10” and stores the
value in the variable “Sum.”
Sub CATMain ()
Dim I, Sum As Integer
Sum = 0
For I = 1 To 10 Step 1
Sum = Sum + i
Next
MsgBox(Sum)
End Sub
1.9.4 Do-While
“Do-While” describes a loop with an input criterion that runs as long as the test criterion
of the loop is met. The test criterion is checked at the beginning of the loop and before
each new run. Test criteria that have not fulfilled the instructions of the loop is skipped.
The “Loop” statement marks the end of the loop. The general syntax of “Do-While” is:
Do While input criterion
Instruction 1
{Instruction 2
...}
Loop
The “Exit Do” statement terminates the loop. With this statement the macro moves to the
next statement after the line “Loop.”
Example 1.14: Do-While
This example demonstrates a loop that adds up the numbers “1,” “2,” “3,” ..., as long as the
sum is less than “100.”
01_Ziethen_Ch01_p001-030.indd 21
12/28/12 10:17 AM
22 1 Basics
Sub CATMain ()
Dim I, Sum As Integer
Sum = 0
I = 1
Do While Sum <100
Sum = Sum + I
I = I + 1
Loop
MsgBox(Sum)
End Sub
The result is “105”.
1.9.5 Do Until
“Do Until” describes a loop with an initial criterion that runs until the test criterion is
met. The criterion is checked after each iteration of the loop and the loop is executed at
least once. “Loop” marks the end of the loop. The general syntax of “Do Until” is:
Do
Instruction 1
{Instruction 2
...}
Loop Until initial criterion
The “Exit Do” statement terminates the loop. With this statement the macro moves to the
next statement after the line “Loop.”
Example 1.15: Do Until
This example demonstrates a loop that adds up the numbers “1,” “2,” “3,” ..., until the sum
is greater than “50” or an addend of “10” is reached.
Sub CATMain ()
Dim I, Sum As Integer
Sum = 0
I = 1
Do
Sum = Sum + I
I = I + 1
Loop Until (Sum> 50) Or (I> 10)
End Sub
The result is “55.”
01_Ziethen_Ch01_p001-030.indd 22
12/28/12 10:17 AM
1.10 Anchor Objects of CATScript 23
„„ 1.10 Anchor Objects of CATScript
An Anchor Object is an object that is required in every macro to access the elements of
CATIA. There are four major anchor objects in CATScript when solid, wireframe, surfaces,
and product structures are created:
ƒƒ The CATIA application itself
ƒƒ A CATIA document, “CATPart,” or “CATProduct”
ƒƒ The container of the geometric elements of CATParts
ƒƒ The container for structural information and metadata of CATProducts or CATParts
1.10.1 CATIA-Application
The main anchor object is an object of the Application class (Section 8.5) that represents
the application CATIA V5. The CATIA V5 application is described with the CATIA label.
Example 1.16: Creating the Anchor Object CATIA V5
Sub CATMain ()
Dim MyCatia As Application
Set MyCatia = CATIA
End Sub
All objects are derived through this anchor object’s properties and methods. A CATIA
document and the provided communication services with an operating system are shown
in Figure 1.17.
A list of all CATIA V5 application windows are shown with the Windows property of
the anchor object (Figure 1.17, top right). The current window is accessed by the
ActiveWindow property.
APPLICATION.Windows As Windows (Read Only)
APPLICATION.ActiveWindow As Window (Read Only)
A list of all open CATIA documents in the CATIA V5 application are shown with the
Documents property (Figure 1.17, top left). The current CATIA document is accessed by
the ActiveDocument property.
APPLICATION.Documents As Documents (Read Only)
APPLICATION.ActiveDocument As Document (Read Only)
01_Ziethen_Ch01_p001-030.indd 23
12/28/12 10:17 AM
24 1 Basics
FIGURE 1.17
Content of the anchor
object in the
“Application” class
(Source: Online
Documentation of
Dassault Systémes)
The FileSystem, Printer, and SystemService properties providing communication services between the CATIA V5 application and an operating system are shown (Figure 1.17,
bottom right).
APPLICATION.FileSystem As FileSystem (Read Only)
APPLICATION.Printers As Printers (Read Only)
APPLICATION.SystemService As SystemService (Read Only)
The properties of the Application class will be explored in Chapter 2.
1.10.2 CATIA Documents “CATPart” and “CATProduct”
A CATIA document is all of the data stored in one file type, whether it is a “CATPart,”
“CATDrawing,” or “CATProduct.” The parent class of all CATIA documents is the
01_Ziethen_Ch01_p001-030.indd 24
12/28/12 10:17 AM
1.10 Anchor Objects of CATScript 25
Document class (Section 8.25). For each document type of CATIA V5, there is a
specialized class whose parent class is the Document class. For a CATPart, this is the
PartDocument class (Section 8.16.9); for a CATProduct, this is the ProductDocument class (Section 8.17.7).
If the ActiveDocument property of the Application class is declared, which is an
object of a current CATIA document (Section 1.10.1), the correct class of the document is automatically determined. For example, if a CATIA document is a CATPart, the
ActiveDocument is automatically a PartDocument. Additional information on how
to create, load, and store a CATIA document is in Section 2.2.
Example 1.17: Creating the Anchor Object of a CATIA Document
A user has opened a CATIA document, and the macro “Document” is an object of this
document. The macro assigns and displays the document name in a dialog box.
Sub CATMain ()
Dim MyDocument As Document
Set MyDocument = CATIA.ActiveDocument
MsgBox (MyDocument.Name)
End Sub
1.10.3 Geometry Containers in CATParts
The geometry of a CATPart is an object of the Part class (Section 8.168) and is assigned
to the third anchor object. The anchor object is derived using the Part property of the
PartDocument class.
PARTDOCUMENT.Part As Part (Read Only)
All other objects are derived from the geometric content of a CATPart through the
methods and properties of the third anchor object (Figure 1.18).
The origin planes and axis systems used in CATParts are accessed by the OriginElements
and AxisSystems properties (Figure 1.18, top left).
Bodies can be accessed through the Bodies properties and Geometrical Sets through
HybridBodies and OrderedGeometricalSets properties (Figure 1.18, bottom left and
top right).
Constraints, relations, and parameters (Figure 1.18 right, center) are accessed through
the Constraints, Relations, and Parameters properties.
Toolboxes are used in CATScript to create geometry. A toolbox is a class that provides
methods to create geometry. The set of all toolboxes are summarized in the Factory
class. The ShapeFactory property represents a toolbox for solid shapes, and the
HybridShapeFactory property represents a toolbox for wireframe geometry and
surfaces (Figure 1.18, bottom right).
The properties outlined in this section are explained in further detail in Chapters 3 to 7.
01_Ziethen_Ch01_p001-030.indd 25
12/28/12 10:17 AM
26 1 Basics
FIGURE 1.18
Content of an anchor
object in the
“PartDocument” and
“Part” classes
(Source: Online
Documentation of
Dassault Systémes)
1.10.4 Structural Information and Metadata
The structural information of CATProducts is the list of all elements inside of a CATProduct. The metadata of CATParts or CATProducts are general attributes such as the Transformation Matrix, Part Number, or Version. The structural information and metadata of
CATProducts or CATParts are stored in an object of the Product class (Section 8.176). An
object of the class can be derived via the Product property of the PartDocument class
(Section 8.169) and ProductDocument class (Section 8.177).
PARTDOCUMENT.Product As Product (Read Only)
PRODUCTDOCUMENT.Product As Product (Read Only)
01_Ziethen_Ch01_p001-030.indd 26
12/28/12 10:17 AM
1.10 Anchor Objects of CATScript 27
Through the methods and properties of this fourth anchor object, all other objects that
represent the attributes and product structures are defined (Figure 1.19).
FIGURE 1.19
Content of the anchor
object in the
“Product” class
(Source: Online Documentation of Dassault
Systémes)
The product structure of CATProducts is stored in a Products list object. This list object
stores the Product elements that are used in a CATProduct.
The parameters, formulas, constraints, and publications of CATProducts are stored in the
Parameters, Relations, Constraints, FixTogethers, and Publications list objects.
01_Ziethen_Ch01_p001-030.indd 27
12/28/12 10:17 AM
28 1 Basics
Other Product object properties describe the transformation matrix, which controls the
positioning of a CATParts or CATProducts within an assembly.
Metadata (e.g. Part Number, Version) of CATProducts or CATParts can be accessed
through the Part Number, Revision, Definition, Nomenclature, Source, and
DescriptionRef properties, shown in Figure 1.19.
The properties outlined in this section are explained in further detail in Chapters 3 to 7.
„„ 1.11 Using the Macro Recorder
CATIA V5 has a macro recorder that records the individual steps of a user and converts
these steps into source code. This recording may not always be complete and typically
does not meet the requirements for organized programming. However, it does record
valuable insight for objects and methods.
FIGURE 1.20
Starting the
macro recorder
The macro recorder will start from the “Tools/Macro/Start Recording…” menu
(Figure 1.20).
The macro recorder opens the “Record Macro” dialog box. Here the macro language, location, and name of the macro are defined. Select the “Start” button to begin recording
(Figure 1.21).
FIGURE 1.21
“Record macro”
dialog box
01_Ziethen_Ch01_p001-030.indd 28
12/28/12 10:17 AM
1.12 Additional Information 29
CATIA now records and converts the actions that a user performs. A recording ends with
the selection of the “Stop” button (Figure 1.22). The button is only shown during a recording and is displayed automatically.
FIGURE 1.22
Stop recording button
„„ 1.12 Additional Information
With the basics of this book, a user will quickly be able to write their own macros. If the
scope of any macro is outside of creating wireframe, surfaces, and solids, the following
sources provide additional information:
ƒƒ “Programming Interface” in the online documentation of CATIA V5 for Classes, Objects,
Properties, and Methods (Figure 1.23)
ƒƒ www.microsoft.com for commands in VBScript
FIGURE 1.23
Full-text search
of the Online
Documentation
01_Ziethen_Ch01_p001-030.indd 29
12/28/12 10:17 AM