Rules and Standards

CAA V5 Automation Coding Rules

Rules, hints and tips to write Automation code
Technical Article

Abstract

This article presents how to program scripts using Dassault Systemes V5 product lines scripting capabilities.


General Rules and Principles

This document targets scripts developed using Dassault Systemes V5 scripting languages. It does not cover all topics needed to develop a complex application using for example Visual Basic but most of the rules still apply to this kind of application.


[g1] Use Option Explicit

It prevents the compiler/interpreter to automatically create non declared variables, possibly hiding misspelled accesses to existing variables. 

It has to be the very first directive: 

Option Explicit
...

If you are using a recorded macro as a basis, remove the valuation of the "Language" variable instead of declaring it like in:

Dim Language As String ' Useless: remove
Language="VBScript"    ' Useless: remove
Metrics: Statement is present

Objective:  Y

[Top]


[g2] Handle Errors

If errors are not systematically handled which is often the case when using scripting languages a lot of unpredictable events can take place before the end user identifies a problem. As a default behavior the interpreter will stop and display an error message box whenever an error is raised. 
When you want to take corrective actions on an error, disabling the automatic error handing mechanism using "On Error Resume Next" becomes mandatory. 

Dim CATIA As Object
On Error Resume Next      ' Disable automatic error handling
    Set CATIA=GetObject(,"CATIA.Application")
    iErr = Err.Number     ' For BasicScript parser (Unix)
    If (iErr <> 0) Then   ' Manually handle all errors
       On Error Goto 0    ' Invalidates the Resume Next and clears the error
        set CATIA=CreateObject("CATIA.Application")
    End If
On Error Goto 0           ' Invalidates the Resume Next and clears the error
Metrics: Number of lines between an "On Error Resume Next" and an "On Error Goto 0" that are 
not followed by a block "If (Err.number <> 0) ... End If"

Objective:  0

[Top]


[g3] For out-process application, use CATIA as the name of the root Object

It simplifies reuse of recorded macros and reuse in an in-process context:

Dim CATIA As Object
Set CATIA=GetObject(,"CATIA.Application")
...
Metrics: Number of GetObject or CreateObject concerning CATIA for which the receiving variable is not named "CATIA"

Objective:  0

[Top]


[g4] Declare Supported Languages, And Initial Release

The following comments are Mandatory. Valid values for Language are "VBScript", "CATScripts", "VB" or "VBA",  Release identifies the first supported CAAV5 release. 

' Languages: VBScript 
' Release:   V5R6 

Look in [1] for a complete standard header.

Note that BasicScript is kept for compatibility purpose.

Metrics: The two statements are present and contain valid values

Objective:  Y

[Top]

[g5] Always type your variables (VB/VBA/CATScript)

Typing objects eases programation and debug:

Dim VariableOfTypeX As TypeX

An exception is when you need to use a method of an object that takes an array as an argument (see the About VB, VBA, Debug, and Portability article). In this case you won't be able to type your object (VB/VBA refuses to compile).

Metrics:
Number of Dim statements without an As statement 
Number of wrongly defined types

Objectives:
0
0

[Top]

 


Rules for Ensuring Testability

To allow integration in automated test suites, automation scripts must follow specific rules.

 


[t1] Always give a default value to InputBox

In a test case context, this default value will be used as the result of InputBox 

Dim sName As String
Set sName = InputBox ("Enter Body Name: ", "", "NEWBODY")

When using MsgBox, if you store the returned value, it will be set to 0.

Metrics: Number of InputBox without a 3rd parameter.

Objective:  0

[Top]


[t2] Use Err.Raise to exit on error

In a test case context, an error needs to be identified as such. 

Use MsgBox for information messages and Err.Raise for errors. The first and third parameters must be valuated, like in:

If (iShape > oShapes.Count) Then
    Err.Raise _
        9999,_                     ' Number greater than 1000
        "MyMacro",_                ' Optional: Name of the Script or the sub
        "Shape Number is too big"  ' Explicit error message
End If

Don't use:

If (iShape > oShapes.Count) Then
    MsgBox "ERROR: Shape Number is too big", VBOkOnly
    Exit Sub
End If
Metrics: None (program semantics involved)

Objective: None

[Top]


Rules for Writing Cross-Platform CATScripts or VBScripts

CATScripts language has been kept ofr compatibility purpose. It is processed by a VBScript engine after removal of typing information. CATIA V5 uses slightly different VBScript interpreters depending on the platform it is being run on. Even though these interpreters have a lot in common, they also have their own behaviors and list of supported features. 


[p1] Use only CAA V5 objects

On windows you can use the CreateObject and GetObject functions to access to ActiveX objects. This is not possible on Unix.

If a CAA V5 alternative exists, use it. A good example of this is filesystem acess:

This is not portable and can be replaced by the portable V5 FileSystem, File, Folder interface family, accessible from the Application object (CATIA.FileSystem).

Metrics: Number of GetObject or CreateObject

Objective:  0

[Top]


[p2] Use CATIA.SystemService.ConcatenatePaths to manage paths concatenation

Some scripts may require to calculate folder paths using a concatenation of paths from different sources. For example, the following calculates a file absolute path from the content of an environment variable (ROOT_FOLDER) and a litteral value:

Dim sRootPath As String
sRootPath=CATIA.SystemService.Environ("ROOT_FOLDER")
Dim sFilePath As String
sFilePath = sRootPath & "/drw/myDrawing.CATDrawing"
Set oDrawingDocument = CATIA.Documents.Open(sFilePath)

This is not portable, assuming that the environment variable will contain a valid path for the platform on which the macro runs:
 
Platform ROOT_FOLDER value sFilePath value
Unix /u/users/me /u/users/me/drw/myDrawing.CATDrawing
Windows E:\me E:\me/drw/myDrawing.CATDrawing

not all CAA V5 functions will be able to deal with a path like the second one, containing at the same time '/' and '\' characters as separators.

Use the ConcatenatePaths function for that purpose, it allows to always get a path containing the right separators:

Dim sRootPath As String
sRootPath=CATIA.SystemService.Environ("ROOT_FOLDER")
Dim sFilePath As String
' here you can use '/' or '\' in the constant part of the path
sFilePath = CATIA.SystemService.ConcatenatePaths(sRootPath, "drw/myDrawing.CATDrawing")
Set oDrawingDocument = CATIA.Documents.Open(sFilePath)

resulting in the following:
 
Platform ROOT_FOLDER value sFilePath value
Unix /u/users/me /u/users/me/drw/myDrawing.CATDrawing
Windows E:\me E:\me\drw\myDrawing.CATDrawing

 

Metrics: Number of string containing '/' or '\' caracters and used in a string concatenation operation

Objective:  0

[Top]


[p3] Use conversion operators to provide Strings as input of MsgBox/InputBox

The VBScript MsgBox and InputBox functions are slightly less permissive on Unix than on Windows. They only accept String parameters. For example to correctly use the MsgBox function with an integer variable, use the VBScript 'CStr' conversion function to convert the integer into a string, like described below:

Dim i  
i = 10 ' Store an Integer value in i
MsgBox CStr(i)
Metrics: Number of usage of InputBox/MsgBox using impicit conversion

Objective:  0

[Top]


References
[1] CAA V5 Automation Code Presentation Rules

History
Version: 3.0 [Jan 2006] Document updated.
Version: 2.0 [May 2004] Document updated.
Version: 1.0 [Jan 2000] Document created

[Top]


Copyright © 2000, Dassault Systèmes. All rights reserved.