VB Scripting for CATIA V5: Email Course by Emmett Ross

Lesson #2 - CATIA Macro Basics

Syntax is defined as the ordering of and relationship between the words and other
structural elements in phrases and sentences. You can think of it as a particular layout of
words and symbols. Each programming language is composed of its own syntax. Learning
the syntax of each programming language is crucial to creating successful macros. Think of
it like this: when you see an email address (emmett@scripting4v5.com) you immediately
identify it as an email address. Why is this? An email address has a correct structure in the
language of the internet, its syntax. Syntax enables the programming language to
understand what it is you are trying to do. Listed below are some of the key syntax features
of CATIA macro programming:

 Case Sensitivity: By default, VBA is not case sensitive and does not differentiate
between upper-case and lower-case spelling of words.
 Comments: Add comments to your statements using an apostrophe ('), either at the
beginning of a separate line, or at the end of a statement. It is recommended that you
add comments wherever possible to make your scripts easier to understand and
maintain, especially if another user has to make changes to it later on down the
road.
 Indentation: Indent or out dent script to reflect the logical structure and nesting of
the statements to make it easier to read. Indentation is not required but is extremely
helpful. Please note: there are some codes in this text where the indentation has been
modified or deleted. This has been done to conserve as much paper as possible.
 Parentheses: It is important to use parentheses correctly in any statement to
achieve the desired result and to avoid errors.
 Semicolon (:): Inserting a semicolon allows you to write multiple commands on the
same line of code.
 Single Quotation(‘): To return a single quotation mark which does not indicate a
comment (needed in a formula for example), you'll have to use the Chr function.
Chr() is a built-in VBA function that returns the character that corresponds to the
numeric value of its argument using the ASCII coding scheme (pronounced “ask-
key”). If you provide Chr with an integer value (such as 39) it will report back the
character that corresponds to that value. The ASCII value of 39 is the single quote
mark. Chr(34) is for the double quote mark. Examples of use can be seen later on in
this text.
 Commonly Used ASCII Characters
Chr(#) Description Chr(#) Description
0 Null 13 Carriage return
9 Horizontal tab 32 Space
10 New line 34 Double quote (")
11 Vertical tab 39 Single quote (')

 Spaces: Add extra blank spaces to your script to improve clarity. These spaces are
ignored by VBA.
 Text Strings: When a value is entered as a text string you must add quotation marks
before and after the string. You can concatenate, or combine, multiple strings using a
plus (+) or ampersand (&) sign: txtString = “This value is “+ TestValue. Return the
left, middle, or right of a string using: left(sting, digits), mid(string, digits), or
right(string, digits). Get the complete length of a string with len(string). To figure
out if a string contains another string use Instr(). Convert numeric strings and vice
versa using str(num) or val(string).
 Underscore(_): Carry over to next line (line concatenation symbol).

Syntax is often the most frequent cause of a macro program not working and throwing an
error. There is a correct way to write your code. It takes practice, patience, and persistence
to understand but over time it will become second nature to you. If you follow the rules the
programming languages will understand you otherwise you will get errors.

Dealing with syntax can be tough which is why programmers have developed tools to help
create programs correctly. These are called IDE, or integrated development environments
(remember that definition defined earlier?). The Visual Basic editor in CATIA is the perfect
example (open it with Alt+F11). It contains a built-in syntax checker and works much like
a grammar checker found in software like Microsoft Word and will even give you hints
about what it thinks you meant.

Program Structure and Format

Macros in CATIA use sequential programming, meaning when you run your macro
program, the code will be read by the computer line by line, generally from top to bottom
and from left to right, just like reading a book. The program flows down the code until it
hits a decision point where it may have to jump to a different portion of the program or
rerun lines of code that it already read. The program chooses what lines of code to execute
based on the state of the variables you have defined.
Macros can also be event driven meaning the execution of the program depends on an
event, such as a user clicking a button with the mouse, an object being selected, certain text
or characters being typed into a form, etc. One common decision point is an If...Else
statement. If the variable equals x then do y, else do z. Another one is the while loop which
will execute the lines of code within the loop over and over until the condition becomes
false. There are more examples of decision points and control structures but we’ll get to
those later on in the text.

It’s a good idea to maintain the same format and order on every single program you create.
It’s very useful to keep your code clean and tidy, especially if other programmers are going
to work on it later. Remember; keep the code as simple as possible. Always try to use as
few lines of code as possible (which you’ll be glad you did when you have to troubleshoot
one of your macros). You can reduce the number of lines of code using a colon (:). A
common macro format may look something like this:

'FILENAME :
'VERSION :
'AUTHOR :
'DATE LAST REVISED :
'DESCRIPTION : Describe what the macro does, who the code is intended for
'COMMENTS : Any notes or additional information here, like inpus that need
'to be created prior to running the macro
'MODIFICATIONS : A list of revisions to track the history of the macro
'=====================SEPARATOR=========================================
Main code begins here, usually with Sub CATMain
-define variables, constants, etc. (Dim statements)
-error handling (On Error Resume Next)
-check if part or product is in design mode or not
-update part, drawing, etc.
-double check to make sure all loops are closed (Next, End If, etc).
End Sub

Macro Recording

One method for creating macros is by recording your mouse actions. For macros recorded
in a folder or in a CATPart or CATProduct, Dim statements (declarations) will be recorded
for CATScript but not for MSVBScript. For macros recorded in a .catvba library, "MS VBA"
is the only choice. Macros cannot be recorded while in the drafting workbench. A few
things to keep in mind when recording a macro:
  DON'T: Switch workbenches while recording a macro.
 DON'T: Record more than is absolutely necessary.
 DON'T: Use the UNDO button when recording a macro.
 DO: Be aware of CATSettings when recording.
 DO: Exit sketches before stopping recording.
 DO: Check each macro after it's recorded.

Always UNDO what you just recorded and run the macro (you are able to undo CATIA
macros after you’ve run them which is a good way to check if they work as expected or
not). If the macro works from within CATIA and repeats what you just did, then the macro
obviously works fine. If it does NOT work from within CATIA, you need to fix it. If it does
NOT work from within CATIA it will NOT work once you cut and paste it into a VB
application.

Look through the recorded macro. Many times extra lines of code are added which are not
necessary. This is based on the order of steps that you do as you record the macro. These
unnecessary lines can be removed. Recorded macros do not contain any comments or
explanations of what is happening in the code and input parameters are never recorded.
For example, if a macro is recorded to zoom in and then zoom out it might display the
following code:

Dim viewpoint3D As viewpoint3D

Set viewpoint3D = Viewer3D.viewpoint3D
Viewer3D.ZoomIn
Set viewpoint3D = Viewer3D.viewpoint3D
Viewer3D.ZoomOut
Set viewpoint3D = Viewer3D.viewpoint3D

Notice how the "Set Viewpoint" command appears multiple times? This is unnecessary in
this situation. The viewpoint only needs to be set once after the Dim statement (setting and
declaring will be explained in more detail soon).

Often times you might record a macro with a CATPart active and open it in its own window.
All goes smoothly and the macro replays fine. Then, the next day you replay the macro
again but this time you may have some other document type open or maybe a part is open
but it is in a product assembly. Usually, the macro will fail because when the code was
recorded a CATPart was the active document but now it is not. You need to add your own
error handling to the code to ensure this doesn’t happen. This is one advantage to writing
custom code and knowing the fundamentals of CATIA macro programming.
Tutorial: Record a macro

In this tutorial you’ll record some actions then examine the recorded code.

1. Open a new CATPart. The name of the part doesn’t matter.

2. Start recording a macro by going to: Tools > Macro > Start Recording.
3. Set the current macro library to the directory you setup in Tutorial #1. Choose
CATScript as the language used and give your macro a name, such as
FirstRecordedMacro.CATScript, then click start to begin recording your mouse
actions.

4. CATIA is now recording all of your actions. Create a plane, offset 20mm from the
default yz plane.

5. Click the Stop Recording button to stop recording the macro.

6. Click the Undo button to undo the plane creation macro you just recorded.
7. Alt+F8 to open the macros window. Select your FirstRecordedMacro code then click
Run. The macro should re-create a 20mm offset plane just as you did before.
8. If you open the macro window again but this time select edit, the code should look
something like this:
Language="VBSCRIPT"
Sub CATMain()

Dim partDocument1 As Document

Set partDocument1 = CATIA.ActiveDocument

Dim part1 As Part

Set part1 = partDocument1.Part

Dim hybridShapeFactory1 As Factory

Set hybridShapeFactory1 = part1.HybridShapeFactory

Dim originElements1 As OriginElements

Set originElements1 = part1.OriginElements
Dim hybridShapePlaneExplicit1 As AnyObject
Set hybridShapePlaneExplicit1 = originElements1.PlaneYZ
Dim reference1 As Reference
Set reference1 = part1.CreateReferenceFromObject(hybridShapePlaneExplicit1)
Dim hybridShapePlaneOffset1 As HybridShapePlaneOffset
Set hybridShapePlaneOffset1 = hybridShapeFactory1.AddNewPlaneOffset(reference1,_
20.000000, False)

Dim hybridBodies1 As HybridBodies

Set hybridBodies1 = part1.HybridBodies

Dim hybridBody1 As HybridBody

Set hybridBody1 = hybridBodies1.Item("Geometrical Set.1")

hybridBody1.AppendHybridShape hybridShapePlaneOffset1
part1.InWorkObject = hybridShapePlaneOffset1 part1.Update
End Sub

Congratulations! You’ve recorded your first macro. But what does all the code mean? How
do you make sense of it? Hopefully by the end of this book you’ll understand every line of
code and will be able to recreate the program without using the macro recorder.

###
Stay tuned for Lesson #3!
Questions or comments? Contact me: Emmett@scripting4v5.com
Can’t wait for the next lesson? Buy VB Scripting for CATIA V5 and continue learning now!