What You Will Learn With This Use Case

This use case is intended to show you how to write, document and test a CAA V5 automation use case. It will then discuss integration in CAA V5 as well as in interactive products documentation. 

[Top]

File Tree description

As for C++, use cases are created in specific modules. Only two frameworks will be created:

[Top]

Step-by-Step

Prior to the creation of your sample, a suitable doc module must exist, as described in the File Tree. A sample is then created in 5 steps:

1. Create the CAScript file
2. Generate an html view
3. Document the CATScript file
4. Create a test case
5. Integrate it in the tocs

1. Create the CATScript file

 The CATScript file must follow the CAA V5 rules for automation code [1] and must be as much as possible stand alone. 

That means that prerequisite models may have to be loaded by the sample (no effect if they are already loaded) and for that purpose picked in the doc view. The doc view is retrieved in the CATDocView environment variable. 

...
' -----------------------------------------------------------
' Optional: allows to find the sample wherever it's installed 
Dim sDocPath As String
sDocPath=CATIA.SystemService.Environ("CATDocView")
If (Not CATIA.FileSystem.FolderExists(sDocPath)) Then
    Err.Raise 9999,,"No Doc Path Defined"
End If 
' -----------------------------------------------------------
' Open the Part document 
 Dim oPartToDraw As PartDocument 
Dim sFilePath As String
sFilePath = CATIA.FileSystem.ConcatenatePaths(sDocPath, "online\CAADriScriptUseCases\samples\Cube.CATPart")
Set oPartToDraw = CATIA.Documents.Open(sFilePath)
...

the address of the CATPart is the concatenation of the value of CATDocView and its relative address in the documentation view. For this purpose use the FileSystemObjet::ConcatenatePaths method that allows to get a valid path on any platform (some automation services can't deal with path containing at the same time "/" and "\" characters).

Depending on your targeted platforms, test your macro on NT and/or Unix. To do that, you will need to correct the value of CATDocView which is not correctly set by mkrun:

on Unix:

> mkrun -c ksh
> SETCATENV -k CATDocView=<myWorkspace/Doc>

 On windows:

> mkrun -c cmd
> SETCATENV -k CATDocView=<myWorkspace\Doc>

This macro has to be delivered in the src/sample directory of your module.

2. Generate an html view

Once the CATScript macro works, use the CAAScrColorizeVBMacro utility to create a html version of your CATScript:

> CAAScrColorizeVBMacro mySample.CATScript

This html version is created in the same directory as the macro, and its name is mySampleSource.htm. To deliver it, move it to the src directory. You wil then be able to copy/paste part of its content in the use case documentation.

3. Document the CATScript file

You will then create a mySample.htm file explaining the sample. Its content is about the same as a C++ sample, the presentation slightly changes to fit requirements of interactive products documentation:

When commenting a piece of source code:

• indicate cut in sequence of lines with continuation point: ...
• explain what are variables whose declaration is not visible
• use a bold font for object, methods and properties names. 
• Create hyperlinks once in the file on the main objects targeted by the use case. This link can be of two kinds:

  either an object description exists (for example: CAADriTechArticles.doc/src/CAADriObjDrawingView.htm) and you can directly point on this file.

  if no such description exists, point to the mkdcidl generated documentation using the following syntax for your hyperlink href field:

    href="#" onclick="javascript:CAAlink('IDL', 'DraftingInterfaces', 'DrawingDocument'); return false;"

for a method, just add the name of the method as a new argument:

    href="#" onclick="javascript:CAAlink('IDL', 'DraftingInterfaces', 'DrawingDocument', 'Sheets'); return false;"

4. Create a test case

You must deliver a test case for your macro. As there is no test framework associated to CAA automation, you must create it in a CAA C++ test framework.

################################################################
# Look for the documentation built directory that contains the
# samples and Correct the misdefinition of DocView by SetCATENV ... 
################################################################

DOC_SAMPLE_PATH=$(WhichDir Doc/online/CAAScdDriUseCases)
[ ! -d $DOC_SAMPLE_PATH ] && type CNEXT && exit $?
...

First, find where the data you need to access (CATScript, CATPart, ...) are. Your sample data should be located in a single module or in modules of dependant frameworks. At Release Project level, a DocView is often not available when running ODTs, the second line so tests for the existence of this directory, type CNEXT  allows to keep the test case pertinent.

...
ONLINE=$(dirname $DOC_SAMPLE_PATH)
DOC_VIEW=$(dirname $ONLINE)
SETCATENV -k CATDocView=$DOC_VIEW -e $CATDefaultEnvironment
...

If your macro is using files form the documentation view, you need to find this documentation view and correct the mkrun environment. For this purpose we use the whichdir utility that comes with mkodt. And then the SETCATENV administration utility.

...
CAAScrPreproVBMacro ${DOC_SAMPLE_PATH}${ADL_ODT_SLASH}macros${ADL_ODT_SLASH}CAADriCreateView.CATScript 
${ADL_ODT_OUT}${ADL_ODT_SLASH}CAADriCreateView.CATScript
...

If your sample is using MsgBox or InputBox or does not close all files, which is generally the case, you will need to preprocess your macro in order to avoid the batch execution to hang up on an end user interaction.

...
################################################################
# Execute CNEXT in batch mode with a possible initial mode
################################################################

CNEXT -batch -macro ${ADL_ODT_OUT}${ADL_ODT_SLASH}CAADriCreateView.CATScript
exit $?

You can then lauch CNEXT and request the execution of the macro. The -batch option is required, it will end the CNEXT session after the execution of your macro. 

If your macro does not load all files that it needs for execution, you can request them to be loaded prior to the execution of the macro:

...
################################################################
# Execute CNEXT in batch mode with a possible initial mode
################################################################

CNEXT -batch ${DOC_SAMPLE_PATH}${ADL_ODT_SLASH}samples${ADL_ODT_SLASH}myPart.CATPart 
-macro ${ADL_ODT_OUT}${ADL_ODT_SLASH}CAADriCreateView.CATScript
exit $?

If your sample is requiring interactive selection, this does'nt apply and you will need to create a record.

5. Integrate it in the tocs

Your sample must be integrated in a table of content of CAA V5 (CAAScriptDoc.edu/CAAScdBase.doc) and in a table of content of the interactive documentation (xxxEnglish/xxxjg.doc).

[Top]

In Short

This use case shows how to write, document and test a CAA V5 automation sample.

[Top]

References

[Top]

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