Instantiating a User Feature From a Macro

This topic provides you with instructions concerning the instantiation of User Features from VB Macros. Two different protocols are available to instantiate User Features.

Reminder

To instantiate a User Feature from a VB macro:

Develop your macro in an editor and save it with the CATScript extension. (Read carefully the instructions below to know how to structure your script.)

From the Tools>Macro>Macros... command, access the Macros dialog box in CATIA. Click Macro libraries....

In the Macro libraries dialog box, select the Directories option from the Library type scrolling list.

In the Open a directory of macros dialog box, select the directory that contains the VB script you have created. Click OK when done. Click Close in the Macro libraries dialog box: The macro contained in this directory is displayed in the Macros dialog box.

Click Run. Your macro is run and your User Feature is instantiated.

Note that:

The instantiation has to be done entirely from the beginning to the end, following the steps indicated below. The final step of the instantiation cannot be performed unless all the required inputs are correctly valuated. Trying to do so will lead to an error message and the script execution will stop.

As the instantiation is performed programmatically, there is no possibility to intervene using the interface during the instantiation. Thus, manual reroute and orientation-handling are impossible.
It is also impossible to modify a Design Table associated with the User Feature.
The Repeat mode is unavailable. Nevertheless this can be simulated by inserting a loop inside the script.

Inputs and published parameters are referenced by name in the methods and not by position.

The instantiation is always performed after the position of the current feature (the In-work object).

First instantiation protocol

The first protocol is dedicated to User Feature instantiation only. It is defined by a single method: AddInstance (For more information about this method, see the Automation documentation).

Note that:

This method is to be used when you want to perform only one instantiation of the reference.
As the document containing the reference is released from the session at the end of the instantiation, it is not recommended to use this method if you want to perform several instantiations of the same reference in a loop. To perform a loop, use the second protocol.

The instantiation process can be broken down into the following steps:



           'Instantiation of a User Feature Reference "UserFeature2" 

           ' UserFeature2 is stored in the CATPart "e:\UserFeatureStartSweep.CATPart"

           ' It has ' 2 inputs: Center and Surface

           ' 2 published parameters: Height and Radius

           ' 1 output: Direction

           '------------------------------------------------------------

           --------------------------------------------------------------

           CATIA.SystemService.Print "Retrieve the current part"

           

           Dim PartDocumentDest As PartDocument

           Set PartDocumentDest = CATIA.ActiveDocument

           

           Dim PartDest As Part

           Set PartDest = PartDocumentDest.Part

           

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Retrieve the User Feature Reference"

           

           CATIA.DisplayFileAlerts = False

           

           Dim PartDocumentStart As PartDocument

           Set PartDocumentStart = CATIA.Documents.Read ("e:\UserFeatureStartSweep.CATPart")

           

           Dim PartStart As Part

           Set PartStart = PartDocumentStart.Part

           

           Dim reference As Object

           Set reference = PartStart.FindObjectByName("UserFeature2")

           

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Instantiate the reference in the current 
           part"

           

           Dim factory As InstanceFactory

           Set factory = PartDest.GetCustomerFactory("InstanceFactory")

           

           Dim instance As ShapeInstance

           Set instance = factory.AddInstance(reference)

           

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Set Inputs"

           

           Dim Center As Object

           Set Center = PartDest.FindObjectByName("Point.1")

           

           Dim Surface As Object

           Set Surface = PartDest.FindObjectByName("Surface.1")

           

           instance.PutInput "Center", Center

           instance.PutInput "Surface", Surface

           

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Modify Parameters"

           

           Dim param1 As Parameter

           Set param1 = instance.GetParameter("Height")

           param1.ValuateFromString("40mm")

           

           Dim param2 As Parameter

           Set param2 = instance.GetParameter("Radius")

           param2.ValuateFromString("30mm")

           

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Update"

           PartDest.Update

           

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Retrieves Inputs and Outputs"

           

           Dim inputCenter As Object

           Set inputCenter = instance.GetInput("Center")

           Dim inputSurface As Object

           Set inputSurface = instance.GetInput("Surface")

           

           CATIA.SystemService.Print "Recuperation des outputs"

           Dim outputDirection As Object

           Set outputDirection = instance.GetOutput("Direction")

           

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Close the CATPart containing the 
           reference"

           PartDocumentStart.Close

Instantiation: The current part is first retrieved then the Part is read. Use the FindObjectByName method to retrieve the inputs.
Then the User feature is instantiated using the AddInstance method.

Valuation of inputs: Use the FindObjectByName method to retrieve the inputs and the PutInput method to valuate the inputs

Parameter modification: Use the ValuateFromString method to modify the parameters.

Checking the instantiation: Use the GetInput method to retrieve the valuated inputs.

Second instantiation protocol

The second protocol is dedicated to User Features and Power Copies instantiation. It is defined by several methods that must be called in order.

Note that it is recommended to use this protocol to perform several instantiations of the same reference in a loop.

From the Instance Factory (A), the instantiation process can be broken down into 3 major steps, the second step itself being broken down into 5 different steps.

Initialization: It is the step where you define which User Feature is to be instantiated. To perform several instantiations in a loop, the reference document is locked in the CATIA session. It will be unlocked in the final step. This step must be called only once at the beginning of the instantiation whatever the number of instantiations.

Instantiation: It is the major step in which the data are copied/instantiated. It is made up of 5 different steps that must be called in the order given below.

Begin of instantiation: All the data are initialized.

Inputs valuation: Each input of the User Feature has to be valuated with a feature of the destination document.

Parameter modification: If needed, published parameters can be modified.

Instantiation: The User Feature is instantiated.

End of instantiation: After this call, the instantiation is ended, and all the links to the reference are broken.

Conclusion: This is the last step: The reference document is unlocked and released from the session.

' Instantiation of a User 
           Feature Reference "MyUserFeature2" 

           ' MyUserFeature2 is stored in the CATPart "e:\tmp\UserFeatureStartSweep.CATPart"

           ' It has

           ' 2 inputs: Center and Surface

           ' 2 published parameters: Height and Radius

           ' 1 output: Direction

           -------------------------------------------------------------

           

           ---------------------------------------------------------------

           CATIA.SystemService.Print "Retrieve the current part"

           

           Dim PartDocumentDest As PartDocument

           Set PartDocumentDest = CATIA.ActiveDocument

           

           Dim PartDest As Part

           Set PartDest = PartDocumentDest.Part

           '-------------------------------------------------------------

           CATIA.SystemService.Print "Retrieve the factory of the current part"

           

           Dim factory As InstanceFactory

           Set factory = PartDest.GetCustomerFactory("InstanceFactory")

           '--------------------------------------------------------------

           CATIA.SystemService.Print "BeginInstanceFactory"

           

           factory.BeginInstanceFactory "MyUserFeature2",

(1)

 "e:\tmp\UserFeatureStartSweep.CATPart"

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Begin Instantiation"

           

           factory.BeginInstantiate

(2)



           '--------------------------------------------------------------

           CATIA.SystemService.Print "Set Inputs"

           

           Dim Center As Object

           Set Center = PartDest.FindObjectByName("Point.1")

           

           Dim Surface As Object

           Set Surface = PartDest.FindObjectByName("Surface.1")

           

           factory.PutInputData "Point.1", Center

(3)



           factory.PutInputData "Surface.1", Surface

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Modify Parameters"

           

           Dim param1 As Parameter

           Set param1 = factory.GetParameter("Height")

(4)



           param1.ValuateFromString("40mm")

           

           Dim param2 As Parameter

           Set param2 = factory.GetParameter("Radius")

           param2.ValuateFromString("30mm")

           '--------------------------------------------------------------

           CATIA.SystemService.Print "Instantiate"

           

           Dim Instance As ShapeInstance

           Set Instance = factory.Instantiate

(5)



           '--------------------------------------------------------------

           CATIA.SystemService.Print "End of Instantiation"

           factory.EndInstantiate

(6)



           '-------------------------------------------------------------

           CATIA.SystemService.Print "Release the reference document"

           

           factory.EndInstanceFactory

(7)



           '--------------------------------------------------------------

           CATIA.SystemService.Print "Update"

           PartDest.Update

Initialization (1): Use the BeginInstanceFactory method of the CATIAInstanceFactory interface. The first argument must be the name of the User Feature. The second argument is the name of the document where this reference is stored.
For example: InstanceFactory.BeginInstanceFactory ("name_of_reference","name_of_document")

Instantiation: It is the most important part. It is broken down into 5 other steps that must be executed in the following order. These steps can be called in a loop to perform several instantiations:

Begin of instantiation: Use the BeginInstantiate method (2) of the CATIAInstanceFactory interface to initialize the data of the reference.
For example: InstanceFactory.BeginInstantiate

Valuation of inputs: Use the PutInputData method (3) of the CATIAInstanceFactory interface to set a value to any input of the reference.
For example: InstanceFactory.PutInputData "input1", selected_feature1

Parameter modification: Retrieve the published parameter using the GetParameter method (4)of the CATIAInstanceFactory interface to modify its value using the ValuateFromString method of the CATIAParameter interface.
For example: Set param = InstanceFactory.GetParameter ("published_parameter1") param.ValuateFromString ("length1")

Instantiation: Use the Instantiate method (5)of the CATIAInstanceFactory interface. It returns the created instance when it exists.
For example: Set Instance = InstanceFactory.Instantiate

End of instantiation: Use the EndInstantiate method (6) of the CATIAInstanceFactory interface to indicate that the instantiation is done.
For example: InstanceFactory.EndInstantiate

Conclusion: Use the EndInstanceFactory method (7)of the CATIAInstanceFactory interface to end the instantiation and clean the InstanceFactory. When performing several instantiations in a loop, this step must be called only once at the end of all instantiations.
For example: InstanceFactory.EndInstanceFactory

To get an example, see Instantiating a User Feature From a VB Macro.