Rules and Standards |
CAA V5 Automation Coding RulesRules, hints and tips to write Automation code |
|
Technical Article |
AbstractThis article presents how to program scripts using Dassault Systemes V5 product lines scripting capabilities. |
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.
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]
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]
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]
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: |
[Top]
To allow integration in automated test suites, automation scripts must follow specific rules.
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]
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]
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:
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
).
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.