Migrating from ENOVIA V5 VPM V5R19 to ENOVIA V5 VPM V5R20 on Windows

Special Notes

R20 GA utility Upgrade520NT_Enovia.sh will support migration of standard and customized LCA Windows Oracle and DB2 databases for Windows 2003 Professional and Windows 2003 Server. A separate program (Upgrade520_Enovia.sh) supports migration of databases from R19 to R20 on UNIX.
As a prerequisite to the migration on Windows, MKS Toolkit version 7 or higher must be installed on the machine that hosts the Enovia server.

Scope & Purpose

This documentation allows a user to migrate an existing ENOVIA V5 VPM V5R19 database into a database containing structures and data that will support ENOVIA V5 VPM V5R20 while maintaining all the user-supplied data that was generated during use of the product under ENOVIA V5 VPM V5R19.

A database migrated through this process will be converted from R19 to R20. The migration process does NOT create a separate copy of the database, but instead converts the existing database. Once you have performed this migration, you cannot use ENOVIA V5 VPM R19 on this database without dropping it and restoring a backup image of the database that was taken while it was still in R19. Attempting to run ENOVIA V5 VPM V5R19 on the database after it has been migrated to R20 is unsupported.

Assumptions

These instructions assume you are migrating directly from V5R19 to V5R20. This procedure does not support any other releases or migration effort. Do not attempt to use any other releases of ENOVIA V5 VPM with these instructions.

These instructions also assume you have a working V5R19 installation, including a completely functional Oracle or DB2 database that is up and running before beginning migration. Oracle or DB2 software should be at a level supported in the ENOVIA V5 VPM installation documentation. There should be no users connected to ENOVIA V5 VPM or the database at the time of migration.

Overview

For better documentation, error diagnosis, and restart ability, the R19 to R20 migration is done in 7 steps that each perform a particular unit of work on the database. The steps listed below generate their own unique output log that contains the name of the step embedded in the file name, located in the directory specified by the –TMP parameter. Thus, if a step fails for some reason, we can look at the logs that pertain directly to that step to determine the cause of the failure.

Before the official migration steps begin, we do some introductory environmental preparation and checking the database availability by connecting to it successfully. Then we use a function called GETMETAR20LIST, which gets the list of all the Metadata that is used in R20. This is a hard-coded list that was obtained from a CD-install of R20 by connecting to its database and doing "select schema name from rdbentitymapping" and then eliminating VPMAdminSchema from the list. This step does not change anything during migration; it simply loads the values of some variables that will be needed later.

Then we proceed to the steps of migration as follows:

• DDL - This step is required. Uses R19 and R20 metadata to generate database scripts (DDL) necessary to make the database structure changes to convert to R20 and then executes the DDL to make the changes.
  
  Output = Upgrade520.logGENERATEDDL, Upgrade520.logRUNGENDDL,
  Upgrade520.logCustoProcessDDLSetup,
  Upgrade520.logCustoProcessDDL
• ADMIN - This step is required. Runs AddCustoInAdmin (in a customized environment) and LoadAdmin (in all environments). These make changes to the database based on the contents of the VPMAdmin.adm file. The ADMIN step has a dependency on the DDL step. You cannot run the ADMIN step without simultaneously running the DDL step during a migration. If you put DDL on the EXCLUSIONLIST, the ADMIN step running alone will fail. You must run them both together during the same execution of the migration script.
  
  Output = Upgrade520.logADMIN
•  MASKS - This step is required. Updates P&O (People & Organizations) data (users, contexts and roles) and default masks.
  
  Output = Upgrade520.logMASKS
• STATS - This step is optional. Runs “update statistics” (DB2) or “analyze statistics” (Oracle) on all the ENOVIA V5 VPM tables in the database to improve performance of the ENOVIA V5 VPM product in the future.
  
  Output = Upgrade520.logSTATS
• GRAPH - This step is required. Updates the default status graphs.
  
  Output = Upgrade520.logGRAPH
• VEXT - This step is required. This updates the VEXTENSION attribute value of the Documents by running utility called as ENOVMigDOCVExtension.
  After running this utility over the existing databases, the truncated old extensions “CATAnalysisResul” and “CATAnalysisCompu” will be replaced with complete extensions as “CATAnalysisResults” and “CATAnalysisComputations” respectively.
  
  Output = Upgrade520.logVEXT
• PUB - This step is required/available for DB2 Database only. Changes attributes from “LONG VARCHAR” to “VARCHAR”.
  
  Output = Upgrade520.logPUB
• LVCHAR - This step is required/available for DB2 Database only. Changes attributes from “LONG VARCHAR” to “VARCHAR”.
  
  Output = Upgrade520.logLVCHAR

 

Before You Begin

1. VERY IMPORTANT: Before starting the migration, make an offline (cold) backup of your R19 database in the current Oracle or DB2 database environment and copy it off to tape or other offline storage device.
2. Ensure that you are migrating directly from V5R19 to V5R20. These procedures do not support any other releases or migration effort. Do not attempt to use any other releases of ENOVIA V5 VPM with these instructions.
3. Ensure that you have a working V5R20 installation, including a completely functional Oracle or DB2 database that is up and running before beginning migration.
   1. Oracle or DB2 software should be at the level required in the documentation for ENOVIA V5 VPM in R20
4. There should be no users connected to ENOVIA V5 VPM or the database at the time of migration.
5. VERY IMPORTANT: Ensure that you have large transaction logging capability in the database. DDL steps will fail if they run out of logging during the extensive updates needed for successful migration. Add transaction logs (DB2) or more table space to the rollback segments (Oracle) as needed. The size needed depends on the size of your database. We recommend you increase the logging space normally taken by your database by 100% before starting migration, and more may be required depending on your environment. Consult DB2 or Oracle documentation for instructions on how to make these changes and how to undo them after migration, if desired.
6. If you are using DB2, ensure that the STMTHEAP parameter value on your database is set to at least 3500. You can check this by logging in as the database administrator ID and running:
   
   db2 get db cfg for <databasename> | grep STMT
   
   If it is < 3500, increase it by using the following commands:
   
   db2 update db cfg for <databasename> using STMTHEAP 3500;db2stop force;
db2start
   
   Consult DB2 documentation for more details about this parameter and how to modify it.
7. If you are using DB2, ensure that the APPLHEAPSZ parameter for your database is set to at least 1000 and your LOCKLIST is set to at least 4000 and MAXLOCKS is set to 40. Check this by logging in as the database administrator and running:
   
   db2 get db cfg for <databasename> | grep APPLHEAPSZ
db2 get db cfg for <databasename> | grep LOCKLIST
db2 get db cfg for <databasename> | grep MAXLOCKS
   
   To increase it:
   
   db2 update db cfg for <databasename> using APPLHEAPSZ 1000 LOCKLIST 4000 MAXLOCKS 40;
db2stop force;
db2start
8. If using DB2, ensure that STAT_HEAP_SZ database configuration parameter is set to at least 9000 during the duration of the 17 > 18 migration. To increase it:
   
   db2 update db cfg for <databasename> using STAT_HEAP_SZ 9000
db2stop force;
db2start
   
   Consult DB2 documentation for more details about these parameters and how to modify them.
9. If you have created your own Masks, you should save the Mask information (the old version of the Default Mask + your own Mask) prior to starting the migration. Refer to CAA-RADE R20 documentation: Migrating Existing ENOVIA Masks / Retrieving Needed Masks for Merging.
10. IF YOU HAVE CUSTOMIZED security processes (from the customized modeler) in People & Organization: There are some special steps you need to take if you want to preserve these customizations and migrate them into R20. If you do not take these steps, your basic P&O functionality will work, but the customizations you added in R20 will be lost.
    1. Exclude the MASKS step from the 19->20 database migration. See the information elsewhere in this document on how to put MASKS on the EXCLUSIONLIST so that it is not executed during the migration.
    2. Before migration begins, while the product is still active in R20, export P&O data using the following commands:
       1. cd $INSTALL_PATH/xxx_a/code/command <-- referring to the installation path and the aix_a, hp_a, solaris_a directory where the product is installed
       2. ./catstart -run "VPMPeopleImport -export /savepath/PeopleExportFile"
          - >  where "/savepath" is a path where your data will be saved and can be protected
          from deletion or alteration until migration is completed.
    3. After migration is finished (with the MASKS step excluded), migrate your existing customization using CAA RADE. See the documentation of CAA-RADE R20 "Migrating an Existing Customization" for complete information. Be sure to include your customized security processes in these updates.
    Before Migration Begins: Ensure that you have a good EnvName.txt file in your Install-Path/intel_a directory. For example, if your install path is C:\Program Files\Dassault Systemes\R19, you will have a path under this directory with the name of your operating system (like intel_a) in it. Inside this directory, there should be a file named EnvName.txt that contains the name of the ENOVIA V5 VPM level you are using. For example, the text inside the file will look something like this:
    
    ENOVIA_V5_VPM.V5R20.B20
    
    Ensure that this file exists in both R19 and R20, that it is named EnvName.txt, and that it contains the correct name for the ENOVIA V5 VPM environment that you are migrating at both levels.
11. Set the V5MEM environment variable in the .txt file in your CATEnv directory to 8:
    V5MEM=8
    If you have a large number of ECOs and this parameter is not set, you might experience an out-of-memory condition during the CMAFF step of migration. If you do not want to set this value, you can also manage memory usage by using the –cmaffsize parameter on the migration command line as described below.
12. Set the new R20 vault to the same Unix path as the LCA V5R19 vault and follow the Vault documentation instructions for configuring the R20 vault using the R19 vault database and vault files. This must be done before running the R19-R20 LCA database migration.
    After your installation is completed, you must manually change the information in the properties file to set the V5R20 Vault to the same path as the old V5R19 Vault. To do this:
    - cd to the Java Properties directory ~/<platform>_a/docs/java (platform=WindowNT)
    - edit the ENOVIAVaultServer.properties file
    If you have defined your own Vault(s) - other than the one created during product installation - you must recreate in V5R20 the additional vault(s) using the directions contained in the document “Setting Up the Vault Server Manually in Windows” after migration is completed. Make the same Java Properties changes to document these additional vaults as well.

    Important: You must perform this R20 vault configuration and activate the R20 vault (pointing to the R19 database and R19 vault files paths) before starting the migration utility documented here.

Migration Steps

Step 1: Install V5R20 pointing to existing V5R19 database

Follow the CD installation steps for ENOVIA V5 VPM V5R20 with the following special instructions:

1. Use the same database vendor as ENOVIA V5 VPM V5R19 used.
2. Use the same database name and path as ENOVIA V5 VPM V5R19.

Use a different Port Number for LCA V5R20 than LCA V5R19 used. Do not select the Database objects nor the Startup Data options - this is because we will be using the existing database and data from R19. You may have to “unselect” these 2 options if they are selected by default.

Step 2: Migrate V5R19 > V5R20

1. Logon to the ENOVIA LCA product server with the ENOVIA administrator ID. DO NOT attempt to run the migration as Administrator.
2. cd to the code directory under your product install path. This path appears like one of the following under the directory where you installed the product.
   
   cd <<R19 Install Path>>\intel_a\code
    
3. Create (for example, using the notepad editor) a batch file containing all the parameters you will need to run the migration script. The parameters should all wrap continuously as one line; there should be no carriage return.
4. If you are migrating an Oracle database, the commands below must be executed in an MKS Korn shell window. If you are migrating a DB2 database, the commands below must be executed in a DB2 Command Window (Note: NOT a DB2 Command Editor and NOT a DB2 Command Line Processor). Note that in no case is the Windows migration performed in the normal Windows “command prompt.”
5. The command line for the STANDARD option is as follows: [if you are running CUSTOMIZED migration, go to Step 5 and DO NOT run Step 4.]

   “C:\installpathR20\intel_a\code\bin\catstart” -run "sh Upgrade520NT_Enovia.sh ... "

   The info below goes into the (...) of the command line. Be sure to put the double quotes (") around the command from the beginning of "sh Upgrade520NT_Enovia.sh" to the end of the last parameter.

Here are two sample executable files, one for Oracle and one for DB2:

DB2

“C:\installpathR20\intel_a\code\bin\catstart” –run “sh C:\installpathR20\intel_a\code\command\Upgrade520NT_Enovia.sh -DBVendor DB2 -DBName R19STD -DBAID ev5adm -DBAdmHome E:\Program Files\SQLLIB -TbsName ENOTBS -IdxTbsName ENOTBS -Tbs32KName ENOTBS32K -IdxTbs32KName ENOTBS32K -TableOwner ev5adm -AdmUsr ev5adm -EnvDir E:\Program Files\Dassault Systemes\B19\CATEnv -EnvName ENOVIA_V5_VPM.V5R20.B20 -R19path E:\Program Files\Dassault Systemes\B18\intel_a -TMP E:\Program Files\Dassault Systemes\tmp -Step ALL -DBAPwd ev5adm
-AdmPwd ev5adm”

ORACLE

“C:\installpathR20\intel_a\code\bin\catstart” –run “sh C:\installpathR20\intel_a\code\command\Upgrade520NT_Enovia.sh -DBVendor ORACLE -DBName R19STD -DBAID ev5adm -DBAdmHome E:\Oracle\ora11 -TbsName ENOTBS -IdxTbsName ENOTBS -Tbs32KName ENOTBS32K -IdxTbs32KName ENOTBS32K -TableOwner ev5adm -AdmUsr ev5adm -EnvDir E:\Program Files\Dassault Systemes\B19\CATEnv -EnvName ENOVIA_V5_VPM.V5R20.B20 -R19path E:\Program Files\Dassault Systemes\B18\intel_a -TMP D:\Projects\DataMigration\Logs\R19-R20\tmp.std.oracle -Step ALL -DBAPwd ev5adm -AdmPwd ev5adm”
 

6. The command line for the CUSTOMIZED option is as follows: [if you are running STANDARD migration, go back to Step 4 and DO NOT run Step 5.] A Customized database is one that is used in an environment that has been altered using customizations produced by the RADE tool.

   “C:\installpathR20\intel_a\code\bin\catstart” –run “sh Upgrade520NT_Enovia.sh ...”

The info below goes into the (...)"…" of the command line. Be sure to put the double quotes ("") around the command from the beginning of ""sh Upgrade520NT_Enovia.sh .." " to the end of the last parameter.

ORACLE:

“C:\installpathR20\intel_a\code\bin\catstart” –run “sh command\Upgrade520NT_Enovia.sh -DBVendor ORACLE -DBName R1918CUS -DBAID ev5adm -DBAdmHome E:\Oracle\ora92 -TbsName ENOTBS -IdxTbsName ENOTBS -Tbs32KName ENOTBS32K -IdxTbs32KName ENOTBS32K -TableOwner ev5adm -AdmUsr ev5adm -EnvDir E:\Program Files\Dassault Systemes\B18\CATEnv -EnvName ENOVIA_V5_VPM.V5R20.B20 -R19path E:\Program Files\Dassault Systemes\B17\intel_a -TMP E:\Program Files\Dassault Systemes\tmp -Step ALL -R19custo D:\home\Custos\NAPR19CustoOra\intel_a\code\dictionary -R19CustoWorkspace D:\home\Custos\NAPR19CustoOra\intel_a\reffiles\DBMS\Generator”

DB2:

“C:\installpathR20\intel_a\code\bin\catstart” –run “sh command\Upgrade518NT_Enovia.sh -DBVendor DB2 -DBName R1918CUS -DBAID ev5adm -DBAdmHome E:\Program Files\SQLLIB -TbsName ENOTBS -IdxTbsName ENOTBS -Tbs32KName ENOTBS32K -IdxTbs32KName ENOTBS32K -TableOwner ev5adm -AdmUsr ev5adm -EnvDir E:\Program Files\Dassault Systemes\B18\CATEnv -EnvName ENOVIA_V5_VPM.V5R20.B20 -R19path E:\Program Files\Dassault Systemes\B17\intel_a -TMP E:\Program Files\Dassault Systemes\tmp -Step ALL -R19custo D:\home\Custos\NAPR19CustoDb2\intel_a\code\dictionary -R19CustoWorkspace D:\home\Custos\NAPR19CustoDb2\intel_a\reffiles\DBMS\Generator -DBAPwd ev5adm -AdmPwd ev5adm”

The R19 migration has the capability to run the steps of migration in an "all…but" fashion - that is, to run all the steps except the ones that you would like to exclude. You might want to do this if:

• You do not want to run one of the optional steps
• You have experienced a problem on some steps but the others have already succeeded. Rather than run the entire migration again, you can correct the problem and then run with all the succeeded steps excluded.

To run all the steps except for one or more to be excluded, follow these procedures:

1. Create a text file called EXCLUSIONLIST (all capital letters) under the directory provided in your –TMP parameter.
2. List the steps inside this file that you DO NOT want to be executed during the migration.
   For example, you might create a file D:\tmp\EXCLUSIONLIST that looks like this:
   STATS
3. Now run the migration with the –Step ALL parameter. It will run all the steps except the ones you mentioned in the EXCLUSIONLIST.
4. Notice that Step names are all capital letters and are all listed in bold type in the OVERVIEW section of this document above.
5. It is not permitted to run the ADMIN step without running the DDL step simultaneously, due to dependencies inside ADMIN.
6. Recognize that some steps have dependencies on the successful completion of other steps. If you try to run any individual step out of order or without completion of its dependencies, the migration script will stop and report that a dependency has been violated and will advise you what to do.
7. Run the (filename) script from the command prompt. Informational status messages appear. Some steps will take several minutes, during which no additional messages will appear.
8. If you did not specify the DBAID password on the command line, a prompt will appear as follows:
   
   Enter password for Database Admin Id (xxxxxx):
   
   where xxxxxx is the userid that you put into your command line as the Database Administrator. Type the password for this userid. It will be displayed on the screen.
9. If you did not specify the ENOVIA Admin User password on the command line, a prompt will appear as follows:
   
   Enter password for EV5 Admin User (XXXXXX):
   
   Where XXXXXXX is the userid that you put into your command line as the ENOVIA Administrator. Type the password for this userid. It will not be displayed on the screen.
10. If running with the -Step ALL parameter, the failure of any critical steps will abort the script and the other steps will not run. Optional steps may allow the migration to continue if they fail. If a step fails:
    • resolve the error and then rerun any steps that did not execute or that failed the first time, in the order that they appear in the STATUS message at the end of the failed execution (also documented in the OVERVIEW above). This allows you to keep the results of any steps that succeeded, but requires you to manually run each step for the rest of the migration until they are all completed or use the -Step ALL with the EXCLUSIONLIST
    • or restore the database and run again with the -Step ALL parameter after resolving the error. This wipes out all migration done so far and completely starts over.
11. Be patient. Migration of a large database can take several hours. If the migration appears to be ‘hung', you can verify progress by opening a second command window and going to the directory you gave as your TMP directory. Use the command "ls -lrt" and look at the timestamp on the most recent Upgrade520* file. If more than 1 hour passes with no activity in this directory, it is likely the migration has stopped.
12. If you used something other than CAARADE to customize your ENOVIA V5 VPM R19 environment, and you have customized a schema, you now need to consult with the author or maintainer of those customizations to obtain instructions for migrating these customizations into ENOVIA LCA R19.

If you have not already done, don’t forget to reconfigure your Vault in R20 to point to the R19 Vault. You must follow the procedures documented within the Migrating a Vault Server Manually chapter of R20 LCA documentation. There are no changes needed to the Vault database to make it compatible with R20; however, you must still follow the steps needed to point the R20 environment to the R19 vault files.

Special Notes on Migration of Lifecycles (Graphs)

General instructions for migration of customizations to ENOVIA object lifecycles:

If you want to remove a lifecycle state for an object type, you should either:

• ensure that no objects of this type exist in that state, or
• leave the state in the lifecycle graph, with an appropriate transition to a state in the new lifecycle. In this case, users can migrate the old data to the new lifecycle states as needed.

You may update the lifecycle either by editing the text of the lifecycle VGraph file, or by editing the lifecycle in the ENOVIA VPM Product Editor, then exporting to a VGraph file and adding any specialized conditions and operations.

If necessary, you may retrieve the old customized lifecycle VGraph from the old ENOVIA database, but you must do this before you migrate the ENOVIA database to the new release.