About Automation

Configuration 5
 of KwrProfilesDesignTable.xls
applied to KwrBottleProfiles.CATPart

A macro is a way to store instructions intended to be repeated many times. It can also be a good means to store intricate interactions or describe a document in a clear text file easy to edit and requiring less memory than a document. Knowledgeware automation provides you with a way to store operations in the form of a .CATScript file. In this chapter we discuss the macro used to create the assembly in About Rule Firing, then we introduce the knowledgeware automation objects. We will not dwell on the part which consists in creating an assembly as this guide deals more specifically with knowledgeware techniques. If you need a brush up on how to create an assembly, see the Assembly User's Guide.

Creating an Assembly using a CATScript Macro

A CATScript macro is written in a language similar to the Visual Basic language. You can record a CATScript macro, then replay it later on or write it from scratch. The recommended method is to start from a record then, depending on your needs, edit and modify the pre-recorded macro.

Recording the CATScript Macro

To record the macro used in About Rule Firing:

  1. Close all the documents open in your session.

  2. Select the Tools->Macro->Start Recording... command from the standard menu bar then in the Record Macro dialog box displayed, specify the path of an external file. Press the Start button to start the macro recording. From now on, all the interactions are recorded in the CATScript file you have just specified.

    Start of recording

    1. Select the Start->Infrastructure->Product Structure command from the standard tool bar. The product1 root product is created. 

    2. Select the Components->Existing Component... command from the root product contextual menu to add the KwrTipCreateAssembly.CATPart component then the KwrCap1.CATPart component.

    3. In the Assembly Design workbench, specify an offset constraint of 1 mm between the Plane.1 plane of the bottle and the Pad.2 surface. Refer to the figure below to see how to select the elements to be constrained.

    4. Specify a coincidence constraint to make the cap and the bottle axes coaxial. For more information, refer to the Assembly User's Guide. If need be, update the document.

    End of recording

  3. Select the Tools->Macro->Stop Recording command from the standard tool bar. This closes the file which records all the interactions described above.

Taking a Look at the Macro

The CATScript macro you have just recorded is similar to the one below. For the sake of clarity and to make lines shorter:

  • Some objects have been declared while others have been renamed 
  • The arguments passed in functions using the generic naming method are written in italics.

Before replaying this macro, you should replace the path specified as the argument of the AddComponentsFromFiles method.

Dim PrDoc0 As Document
Set PrDoc0 = CATIA.Documents.Add("Product") 

Dim Prod1 As Product
Set Prod1 = PrDoc0.Product  
Dim  var1 ( 0 ) 
' Replace the path below before replaying the macro
var1 ( 0 )  = "E:\...\KwrCap1.CATPart"
Prod1.Products.AddComponentsFromFiles var1, "*"

Dim  var2 ( 0 ) 
' Replace the path below before replaying the macro
var2 ( 0 )  = "E:\...\KwrTipCreateAssembly.CATPart"
Prod1.Products.AddComponentsFromFiles var2, "*"

Dim CstS1 As Collection
Set CstS1 = Prod1.Connections("CATIAConstraints") 

Dim Ref1 As Reference
Set Ref1 = Prod1.CreateReferenceFromName(Plane.1) 

Dim Ref2 As Reference
Set Ref2 = Prod1.CreateReferenceFromName(Pad.2 face) 

Dim Cst2 As Constraint
Set Cst2 = CstS1.AddBiEltCst(1, Ref1, Ref2) 
Cst2.Dimension.Value = 1.000000
Cst2.Orientation = 2

Dim Ref3 As Reference
Set Ref3 = Prod1.CreateReferenceFromName(Bottle axis) 

Dim Ref4 As Reference
Set Ref4 = Prod1.CreateReferenceFromName(Cap axis) 

Dim Cst3 As Constraint
Set Cst3 = CstS1.AddBiEltCst(2, Ref3, Ref4) 


This macro can be started from a rule (see About Rule Firing) or directly by selecting the Tools->Macro->Run command from the standard menu bar. 

About CATIA Automation Learning

There is a lot to be learned before you can write a complete macro in Visual Basic, but once you understand the basics of the language, you can be up and running in no time at all. Visual Basic is based on objects which have their own methods and properties. To set the value of a property, you follow the reference to an object with a period, the property name, an equal sign (=), and the new property value. At first sight, it is simple. The tedious thing when you have no previous programming skills is that the macro you record is a raw macro with objects and properties chained in one statement as in the extract below:

Dim ProductDocument0 As Document
Set ProductDocument0 = CATIA.Documents.Add ( "Product" ) 
Dim var1 ( 0 ) 
var1 ( 0 ) = "E:\...\KwrTipCreateAssembly.CATScript"
ProductDocument0.Product.Products.AddComponentsFromFiles var1, "*"

When you tackle automation, there are two ways to proceed:

  • You already have a background in Visual Basic and you can refer to the list of Programming Interfaces provided with the CATIA documentation to write a macro or interpret a pre-recorded macro
  • You are a beginner and just record a scenario. You must replay it to check whether the scenario has been actually recorded.

About Generic Naming

Generic naming is a CATIA technique which creates a label whenever an element has been selected interactively. This label is a coded description of the selected element. 

This generic naming label appears when you record a .CATScript macro by using the Tools->Options->Macros command.
If you perform interactions such as selecting an edge or a face, the value specified for the arguments of some methods are written using generic naming. When you take a look at the macro, you can see arguments which are neither Visual Basic objects nor usual data. These arguments are written in a form similar to the simple example below:

You don't have to worry much about generic naming as the definitions relying on this technique are automatically inserted in CATIA macros.

Knowledgeware Automation

The objects below can be created and managed in a .CATScript macro:

  • Parameters
  • Formulas
  • Design tables
  • Rules and checks

Creating Knowledgeware Objects

The knowledgeware features are created from the collection which refers to their type. For example, to create a relation in a Part type feature, you must first retrieve the collection object containing the Part relations by using the Relations method on the Part object. To create a parameter in a Part, you must retrieve the collection object containing the Part parameters by using the Parameters method on the Part object.

Modifying Knowledgeware Objects

To manipulate a knowledgeware object, you just have to use the methods and properties of the relevant object.

An Example

Open the KwrTipCreateAssembly.CATPart document and run the KwrRelations.CATScript macro. 

Sub CATMain()

' Retrieve your active document - CATIA is your application 
' You get the active document by using the ActiveDocument property
' on your application object
Dim myDoc As Document 
Set myDoc = CATIA.ActiveDocument 

' Check whether the document is a CATPart
' Analyse the pathname of the document 
' If the extension .CATPart is not found, a message is displayed
' but you exit the procedure
' InStrRev is a standard VB function
Dim strPartName, strCATPart, myPos
strPartName = myDoc.Name 
if (InStrRev(strPartName,".CATPart",-1) = 0)_
then MsgBox("Your document should be a .CATPart") : Exit Sub 

' Retrieve the collection object which contains
' all the document relations
' Activate all the relations
' Display the relation names in a message box
' Note: Statements below could not be applied to a CATProduct 
Dim strRel0 As String
Dim strRel1 As String
strRel1 = "Here is the list of relations" & vbCrLf & strRel0
Dim myRelCol As Relations
Set myRelCol = myDoc.Part.Relations
For Each myRel in myRelCol
strRel1 = strRel1 & vbCrLf & myRel.Name
Msgbox strRel1 

' Make the configuration 4 active
Dim des1 As Relation
For Each myRel in myRelCol
  if myRel.Name  = "DesignTable.1"_
  then Set des1 = myRelCol.Item("DesignTable.1"): des1.Configuration = 4 
End Sub 

This macro displays the list of relations within the document, changes the design table configuration and updates the document. 


Operations that Cannot be Recorded

There are some operations that cannot be recorded but that can be programmed in a macro (the activation or deactivation of a relation for example). The list of objects, methods and properties you can actually use when writing a macro is given in the Programming Interfaces. Access to this documentation is provided on the CATIA documentation home page.

Retrieving Collections

Collections such as the Relations and Parameters objects can only be retrieved from a CATPart document. Prior to retrieving these collections, it is better to check the document type in your script, otherwise the macro crashes.

Retrieving a Collection Object

When retrieving a collection object by its name, it is better to check whether the object exists, otherwise the macro crashes.