Migrating Documents to Use DLNames

This section explains how to use the CATDLNameMigr batch tool for migrating existing documents once you decide to implement a data storage strategy based on the DLName mechanism.

Problems Involved When Migrating to a DLName Mechanism Strategy
You may have created a large number of documents with Version 5 without using the DLName mechanism. If you created documents pointing to other documents (for example, CATProduct documents), these documents contain the path of the documents pointed to. For example, the product structure in the document:

E:\users\ses\CATProducts\Product1.CATProduct

points to a part contained in the following CATPart document:

E:\users\ses\CATParts\Part1.CATPart

If you open the document Product1.CATProduct and select the Edit > Links... command, you will see in the "Links" and "Pointed documents" tabs that the CATProduct document points to the correct CATPart document. For example, this is what you see in the "Pointed documents" tab:
The path:

E:\users\ses\CATParts\Part1.CATPart

is stored physically inside the document:

E:\users\ses\CATProducts\Product1.CATProduct
After creating a large number of documents in this way, you may then decide to implement a data storage strategy based on the DLName mechanism,

However, it is not sufficient to simply create DLNames for all the directories where your documents are stored. Because the path of pointed documents is stored in the pointing document, you need some way of converting the pathname in the document to the corresponding DLName.

The CATDLNameMigr batch tool can be used to solve this problem. The batch tool can be used in two modes:

  • repair mode: the pointing documents are "repaired", in other words modified to replace the pathname by the correct DLName
  • check mode: provides information and generates a text file containing a list of DLNames; the pointing documents are not modified.

Running the CATDLNameMigr Batch Tool

On Windows
Run the program:

install_root\code\bin\CATDLNameMigr.exe

where "install_root" is the name of your installation folder which is, by default:

WindowsInstallPath\win_b64 (64-bit code on Windows, x64 Edition)
WindowsInstallPathx86\intel_a (32-bit code on Windows, x64 Edition)

On UNIX
1. Log on as root.
2. Enter the command:

UNIXInstallPath/OS/code/command/catstart -run CATDLNameMigr

CATDLNameMigr Command Syntax

CATDLNameMigr [-r] filename(s) [-p] dir -d directory [-h] 

  • -r filename: activates repair mode and modifies the specified file
  • -p directory: does NOT modify the original file, but copies it to the directory specified and modifies the file in this directory only. This is useful if you do not want to modify the original file.
  • -d directory: name of directory containing pointing documents
  • -h: displays help.

Running CATDLNameMigr in Repair Mode
For the purposes of this scenario, we are going to use the documents mentioned earlier, and on Windows. The pointing document is:

E:\users\ses\CATProducts\Product1.CATProduct

and the documented pointed to is:

E:\users\ses\CATParts\Part1.CATPart

Make sure that no DLNames have yet been created.
1. Start a Version 5 session, and create two DLNames.

To do so, select the Tools > Options... command, then the Document tab in the General category. To make the DLName environment the current document environment, select "DLName" in the Document Environments column, then select successively the Allowed and Current buttons. 

Then, click the Configure... button and add the two DLNames. You can name them "DLName1" and "DLName2."

Make DLName1 point to:

E:\users\ses\CATParts
2. Exit the session, then open a Command Prompt window and go to the installation directory, which is by default:

WindowsInstallPath\win_b64\code\bin (64-bit code on Windows, x64 Edition)
WindowsInstallPathx86\intel_a\code\bin (32-bit code on Windows, x64 Edition)
3. Enter the command:

CATDLNameMigr -r E:\users\ses\CATProducts\Product1.CATProduct
The output displayed in the command prompt window informs you that:
  • you chose to run the tool with the "-r" option, so it will attempt to save the file
  • it analyzed the file:
    E:\users\ses\CATProducts\Product1.CATProduct
    and succeeded in modifying it.

A report is created in the directory containing the pointing document:

E:\users\ses\CATProducts\Product1.CATProduct.CATDLNameMigr_report
4. Restart a Version 5 session, then open the document Product1.CATProduct.
5. Select the Edit > Links... command, then click the "Pointed documents" tab:
The batch tool uses the first DLName it finds in the list, and replaces the path by "DLName1" so the pointed document path is now:

DLName1\Part1.CATPart
Our scenario shows how to repair a single document. To repair all the documents contained in a specific directory, run the command with the "-d" option followed by the name of a directory. For example, the command:

CATDLNameMigr -r -d E:\users\ses\CATProducts

modifies all the files found in the directory E:\users\ses\CATProducts. The "-d" option can be run in check mode without the "-r" option.

Furthermore, if you do not want to modify the original document, specify the "-p" option followed by the name of a directory. For example, the command:

CATDLNameMigr -r E:\users\ses\CATProducts\Product1.CATProduct -p E:\users

runs the tool in repair mode, does NOT modify the original file, but copies it to the directory E:\users and modifies the file in this directory only. This is useful if you do not want to modify the original file.

Running CATDLNameMigr in Check Mode
You can also run the batch tool without having created enough DLNames, or any DLNames at all.

For the purposes of this scenario, we are going to use the same documents. But this time, make sure that NO DLNames have yet been created.
1. Start a Version 5 session, and make sure that no DLNames have been created.
2. Exit the session, then open a Command Prompt window and go to the installation directory, which is by default:

WindowsInstallPath\win_b64\code\bin (64-bit code on Windows, x64 Edition)
WindowsInstallPathx86\intel_a\code\bin (32-bit code on Windows, x64 Edition)
3. Enter the command:

CATDLNameMigr E:\users\ses\CATProducts\Product1.CATProduct

Note that this time, you do not use the "-r" option.

Because you have not yet created a DLName for the path:

E:\users\ses\CATParts

the batch tool cannot replace the path by the appropriate DLName. Displaying the document using the Edit > Links... command will show that the path has not been modified.

The output displayed in the command prompt window informs you that:

  • you have chosen to run the tool in check mode (because you did not specify the "-r" option") 
  • it could not change the link in E:\users\ses\CATProducts\Product1.CATProduct
  • the following file has been created in: 
    C:\Users\ses\Local Settings\Temp\CATDLNameMigr_missing-DLNames_report.txt
    in which a DLName has been created. The file contains the following line:
    DLName1;E:\users\ses\CATParts;/tmp; 
    The ".txt" file can now be imported, which will allow you to run the tool again later to repair the document.

A report is created in the directory containing the pointing document:

E:\users\ses\CATProducts\Product1.CATProduct.CATDLNameMigr_report

informing you that the link could not be changed because there was no corresponding DLName.
4. Restart a Version 5 session and import the text file.

To do so, select the Tools > Options... command, then the Document tab in the General category. To make the DLName environment the current document environment, select "DLName" in the Document Environments column, then select the Allowed button.

Click the Configure... button, then the Import... button, browse to select the file:

C:\Users\ses\Local Settings\Temp\CATDLNameMigr_missing-DLNames_report.txt

The following DLName is added:

DLName1 E:\users\ses\CATParts
DLName2 E:\users\ses\CATProducts

  Now that you have a DLName, you can run the batch tool using the "-r" option to repair the file.

Command Outputs

Running the command in any of the above modes outputs information to the command prompt window about the tasks processed. This information can also be obtained using the "-h" option.