Rules and Standards

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

[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. 

• Keep as much as possible the automatic error handling mechanism active
• When you deactivate it, isolate its use to places where it's mandatory and explicitly handle all errors meanwhile :

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

[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")
...

[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.

[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).

[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.

[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

[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:

•  VBScript provides access to the filesystem through a set of ActiveX objects bundled with the Windows Scripting Host (CreateObject("Scripting.FileSystemObject").

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

[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

[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)

[Top]

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