Converting CATIA Version 4 Libraries into CATIA Version 5 Catalogs

This task shows you how to convert a CATIA Version 4 library into a CATIA Version 5 catalog.
Before embarking on any conversion make sure you are familiar with the concepts described in "About Catalogs" in the CATIA - Component Catalog Editor User's Guide.

It would also be instructive to read "Converting CATIA Version 4 Library Objects into CATIA Version 5 CATPart Documents".

Migrating the Data Structure

The batch operation creates a catalog chapter for each DETAIL type library family (see  Creating a Catalog in the CATIA - Component Catalog Editor User's Guide).
Other types of families (SYMBOL, SECTION, NCMILL, NCLATHE) cannot be converted.

The keywords relating to the library family are converted into catalog keywords as shown in the table below. These keywords define the associated chapter.

V4 Keyword Type V5 Keyword Type
Discrete String
Alphanumeric String
Numeric Real (no unit retrieval)
Boolean Boolean
The Library structure is migrated into a catalog structure, with the following architecture:
  • one root catalog file containing the root chapter
  • one catalog file for each migrated family and specific files (CATParts and CATDrawings) for the actual data (see below: Migrating the Actual Data).

The multi-file catalog has the following benefits:

  • enhanced migration performance because of reduced catalog file size
  • enhanced catalog usage, for only the necessary subset of the catalog files will be loaded in the catalog browser for browsing and/or instantiation
  • the generated catalog families can easily and independently be reused to build other new catalogs.
Migrating the Actual Data

Bear in mind the following:

  • No link is kept between the V4 library and the new V5 catalog.
  • SPACE details can be migrated to CATIA Version 5 i.e. converted into CATPart documents. Other library objects such as symbols, sections and tools cannot be migrated.
  • DRAW details can be migrated to CATIA Version 5 i.e. converted into CATDrawing documents.
  • If details reference other subdetails the whole of the geometry is exploded in one single CATPart document.
  • Only DETAIL type families are converted into a catalog chapter.
  • Regarding Solid Mockup copy/paste: when copying as CATIA_RESULT or when the solid mockup is isolated, it is stored in a .cgr format in the directory where the catalog is generated.
  • When the copy/paste of a solid is partial, an geometric set is created in the part.

For more information about the copying of V4 data to V5, see Copying CATIA Version 4 Model Data to CATIA Version 5.

Consequences of Migration on Filenames

In Windows, it is extremely important to be aware of the consequences of migration on filenames. Before reading any further see "About Filenames" in the CATIA - Infrastructure User's Guide. In view of the restrictions described in this section, the following default conversion table will apply to new CATPart documents converted from library objects:

ASCII Code of the Original Character Character to be Replaced New Character String
0x22 " _Inch
0x2a * x
0x2f / _
0x3a : _
0x3c < _
0x3e > _
0x3f ? _
0x5c \ _
0x7c | _

National characters will be replaced by default by _xxx where xxx is the ASCII code of the character replaced. The default correspondence table can be modified but you cannot avoid the replacement of these characters. If, for example, you delete the line l''*' the table will be declared invalid. The two characters most likely to occur are:

  • 0xb1
  • 0xb4

which correspond to the characters used in V4 model names as replacements for the blank character " " and slash character "/" respectively. To avoid excessively long document names it is advisable to modify the default conversion table.

Only national characters and those characters not supported by Windows can be declared in the correspondence table. For example, you cannot decide that you want to change all characters from "a" to "w".

If you have declared all the national characters not supported by Windows, you can replace the national characters supported by Windows as follows:

ASCII Code of the Original Character Character to be Replaced New Character String

0x61

a

A

As a consequence, "a" will be replaced by "A".

The scenario described below shows the consequences of:

  • data structure migration
  • actual data migration
  • consequences of migration on filenames.
Conversion of very large V4 Libraries

The conversion of very large V4 libraries uses a lot of resources (memory, CPU and disk space for generated files). In case the batch fails before the end of the conversion due to any reason (lack of memory, individual detail conversion failure, disk full) you can restart it using the Rattrap mode that will continue the job starting from where it was just before the failure.

Following are guidelines regarding this special process mode:

  • first, launch your CATIA V4 library conversion as usual (using MIGRATION mode)
  • if it fails, modify the script so that the new mode is RATTRAP
  • start the script again: the conversion will continue from where it stopped
  • if it fails again for the same reason, start the script again until the whole library is converted

Take care not using this RATTRAP mode for any other reason.

At any time, you are able to check the converted catalog, using the File / SaveAs capability on the generated catalog file. Choosing "txt" format will output a printable text file that dumps the catalog structure, enabling to quickly identify missing converted details, for example.

  1. Open the document ConvertLibrary.CATScript It looks like this:

Abstract:
Conversion batch of V4 Libraries in V5 Catalogs.

The generated report file (*.report) is located in the same catalog directory with the same catalog name.

Language="VBSCRIPT"

Sub CATMain()

' The following valuated parameters (AS_SPEC = 0
' and AS_RESULT = 1) define the conversion format
' option of the space details in parts. DO NOT MODIFY
' these values; they are mandatory and reserved for
' the running application.

AS_SPEC = 0
AS_RESULT = 1

' Choose a conversion format by specifying the value
' AS_SPEC or AS_RESULT
' (e.g. CONVERSION_FORMAT = AS_SPEC).

CONVERSION_FORMAT = AS_SPEC

' The following valuated parameters (MIGRATION = 0
' and SIMULATION = 1 and RATTRAP = 2) define the batch mode option.
' DO NOT MODIFY these values; they are mandatory
' and reserved for the running application.

MIGRATION = 0
SIMULATION = 1

RATTRAP = 2

 

' Choose the desired batch mode by specifying
' the value MIGRATION or SIMULATION
' (e.g. BATCH_MODE = MIGRATION).

BATCH_MODE = MIGRATION

' Specify the absolute UNIX directory of the V4
' library. In Windows, use the http protocol and
' take care of the / separator on UNIX
' (e.g. libraryDirectory
' = "http://machine_name/../../FASTENERS").

libraryDirectory = "http://../../FASTENERS"

 

'
' Specify the catalog name (with its extension)
' the catalog filename correspond to the name of the
' sub-directory containing the V4 libraries.
' This parameter is used to open the catalog in RATTRAP
' mode
' It will not be used in the others (MIGRATION or
' SIMULATION) modes
' e.g:
' if libraryDirectory is set to '/u/users/xxx/LIB'
' then, catalogName has to be set as 'LIB.catalog'

catalogName = "LIB.catalog"

' Specify the absolute directory of the catalog. In
' Windows, take care of the \ separator
' (e.g. catalogDirectory = "E:\..\..\catalog")

' All catalog files will be generated in this directory (one per family).

catalogDirectory = "E:\..\..\Catalog"

 

' Specify the absolute UNIX directory of the V4 project
' if the V4 library needs one
' (e.g. projectDirectory
' = "http://machine_name/../../project"),
' otherwise, you have to specify an empty one
' (e.g. projectDirectory = " ").

projectDirectory = "http://../../Interop"
'projectDirectory = " "

' Specify the absolute path of the character
' conversion table to convert V4 file names of details
' and families in V5 file names of parts and chapters
' (e.g. tablePath = "E:\..\..\table.txt"), or indicate an
' empty one if you want to use the default installation
' (e.g. tablePath = "").

tablePath = "E:\..\..\table.txt"

' Creates a CatalogDocument type document. DO
' NOT MODIFY the following declaration and valuated
' parameters
' (Dim Catalog As Document and
' Set Catalog =
' CATIA.Documents.Add("CatalogDocument")).

Dim Catalog As Document

if ( BATCH_MODE = RATTRAP ) then
Set Catalog = CATIA.Documents.Open(catalogDirectory & "/" & catalogName)
else
Set Catalog = CATIA.Documents.Add("CatalogDocument")
end if

' Calls CreateCatalogFromLibrary method on Catalog.
' DO NOT MODIFY the following declaration related to
' previous variables
' (Catalog.CreateCatalogFromLibrary
' libraryDirectory,
' projectDirectory,
' catalogDirectory,
' tablePath,
' CONVERSION_FORMAT,
' BATCH_MODE).

Catalog.CreateCatalogFromLibrary libraryDirectory, projectDirectory, catalogDirectory, tablePath, CONVERSION_FORMAT, BATCH_MODE

' To perform automatically the close of the newly created
' catalog, decomment the Catalog.close command,
' otherwise put the command in comments.

Catalog.Close

End Sub

  1. Adapt the CATScript file to your needs by selecting the settings you want to use (for CONVERSION_FORMAT and BATCH_MODE) and by providing the different paths required for the batch (libraryDirectory, catalogDirectory, projectDirectory and tablePath). The comments relating to these settings and paths are shown above in red.
    As you can see, this file, written in the VBScript language, contains the information required to batch-convert a V4 library into a V5 catalog file in the location you specify. It can be used on both Windows and UNIX. (Do not forget to use the http protocol on Windows to access the library and the PRJ file.)
    In the example above the CATScript file contains just one set of instructions to batch-convert a single library. However, a CATScript file can of course include several series of instructions for the conversion of several libraries.

  2. Close the file when you have finished.

  3. If you now wish to act on the information above and modify the string to replace one of the characters in the default conversion table, open the file table.txt and make the changes required.

  4. You are now ready to run the batch operation. Select the Tools >Macro>Macros command.

  5. In the dialog box that appears, select the external file and the appropriate ConvertLibrary.CATScript file. Make sure that at the bottom of the box External File is selected indicating the location of the macro. Click on Run.

Example

Let us suppose you have a V4 library called FASTENERS on your UNIX machine. This library has two DETAIL type families: SCREWS and NUTS. 

The migration will now create a chapter called FASTENERS in the document FASTENERS.catalog. For each DETAIL type family an end chapter will be created i.e. a chapter called SCREWS in the document SCREWS.catalog and a chapter called NUTS in the document NUTS.catalog. These end chapters are both referenced by the FASTENERS chapter which is the highest-level entry point in the catalog.

The migration does several things one of which is the conversion of the keywords of each V4 family to keywords in V5 that define the end chapters SCREWS and NUTS. The library family SCREWS, for example, has four keywords that are converted as follows:

Existing V4 Library Family Keywords Created V5 Catalog Keywords
REFERENCE
an alphanumeric keyword
REFERENCE
a string keyword
TYPE
a discrete keyword with the possible values:
CHC, FHC, H and HC
TYPE
a string keyword
DIAMETER
a numerical keyword with millimeter (mm) as the unit
DIAMETER
a real keyword
LENGTH
a numerical keyword with millimeter (mm) as the unit
LENGTH
a real keyword

It should be noted that discrete keywords are converted to strings and that units are NOT converted.

The migration then assigns the chapters as many descriptions as there are converted objects, retrieves the values of the keywords related to the object and establishes a reference to the Part resulting from the migration of the detail. For example, the object CHC M05*06 has the following characteristics:

REFERENCE CHC M05*06
TYPE CHC
DIAMETER 5,0
LENGTH 6,0

The description in the chapter will have the same values.

The migration also converts the geometry of the detail into a Part whose name must be made up of V5-compliant characters (see Consequences of Migration on Filenames above). The asterisk is a character that is not supported by Windows and not available in V5 and so the Part cannot be named CHC M05*06.CATPart. The V4>V5 correspondence table is therefore applied. If you had already supplied a conversion table containing:

0x2a * x

the part created will be given the name CHC M05x06.CATPart.

If, in the CATScript file, you chose SIMULATION the batch operation will:
  • generate a report in the same location as the catalog file, allowing you to verify whether migration would be successful or not
  • detect errors in data migration
  • detect possible occurrences of V5 names following the conversion of V4 names into V5 names.

If more than one occurrence of the same V5 name is detected the older CATPart documents are overwritten. You are therefore strongly advised to modify the conversion table so that CATParts are not created with the same name.

If, in the CATScript file, you chose MIGRATION the batch operation will generate:

  • a report in the same location as the catalog file, allowing you to verify successful migration
  • a catalog with the name of the library.

If a library is migrated to the same directory twice the catalog (both catalog and CATParts) generated by the previous migration is overwritten by the new one.

If, in the CATScript file, you chose RATTRAP the program locates the last converted objects then continues with the next ones. It will generate:

  • a report in the same location as the catalog files, allowing you to verify successful migration.
  • a catalog with the name given as input

The library is migrated to the same directory and the catalog files generated by the previous migration is overwritten by the new one.

  1. If you want to open the catalog you have just created see "Navigating Through a Catalog" in the CATIA - Component Catalog Editor User's Guide.