Migrating from ENOVIA V5 VPM V5R17 to ENOVIA V5 VPM V5R18 in UNIX

Special Notes

R18 GA utility Upgrade518_Enovia.sh will support migration of standard and customized ENOVIA V5 VPM UNIX Oracle and DB2 databases for AIX, HP, and Solaris in Oracle and DB2. A separate program Upgrade518NT_Enovia.sh supports migration of databases from R17->R18 on Windows Server.

Scope & Purpose

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

A database migrated through this process will be converted from R17 to R18. 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 R17 on this database without dropping it and restoring a backup image of the database that was taken while it was still in R17. Attempting to run ENOVIA V5 VPM V5R17 on the database after it has been migrated to R18 is unsupported.

Assumptions

These instructions assume you are migrating directly from V5R17 to V5R18. 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 V5R17 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 for R18. There should be no users connected to ENOVIA V5 VPM or the database at the time of migration.

Overview

The 17->18 migration is done in 5 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 GETMETAR18LIST, which gets the list of all the Metadata that is used in R18. This is a hard coded list that was obtained from a CD-install of R18 by connecting to its database and doing select schemaname 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 R17 and R18 metadata to generate database scripts (DDL) necessary to make the database structure changes to convert to R18 and then executes the DDL to make the changes.
  
  Output = Upgrade518.logGENERATEDDL, Upgrade518.logRUNGENDDL, Upgrade518.logCustoProcessDDLSetup, Upgrade518.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 = Upgrade518.logADMIN
•  MASKS - This step is required. Updates P&O (People & Organizations) data (users, contexts and roles) and default masks.
  
  Output = Upgrade518.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 = Upgrade518.logSTATS
• GRAPH - This step is required. Updates the default status graphs.
  
  Output = Upgrade518.logGRAPH
• CMAFF - This step is required. Sets the new life cycle graph to support V_Status of CMAFFECTED_OBJECTS and assigns value to the V_status attribute of CMAFFECTED_OBJECTS.
  
  Output = Upgrade518.logCMAFF

  Special Notes: There are three things that can cause CMAFF step to fail, which you can correct in your environment if you are aware of them.

  • 1. Out of memory.

    This can happen if you have a large number of Affected Objects and the –cmaffsize value is set too high. Retry with a lower –cmaffsize value (e.g. -cmaffsize 300). This will slow down performance, but it will avoid crashing due to out-of –memory.

  • 2. GRAPH step.

    Rarely, even if the GRAPH step has completed successfully, the CMAFF step requires it to be executed again. Simply run GRAPH again using –Step GRAPH on the migration command line, then retry the CMAFF step using –Step CMAFF on the command line. Then finish migration using –Step GCOLC on the command line.

  • 3. Enoviadbsetup.

    If you forgot to run enoviadbsetup to point your R18 environment to the database being migrated, the other steps of migration may complete successfully, but CMAFF will fail. The error messages will not be clear as to the root cause (because the code cannot detect this condition), so be sure to consider this as a possibility if CMAFF fails.

• GCOLC This step is required. For R18, GCOs will have lifecycles. In order to allow a client to customize the GCO lifecycle a new VGraph file for GCOs is introduced. Any new GCOs that clients create in R18 will use this new graph. However, any existing GCOs that the client may have migrated from a previous release will still use the default VPMObject graph. We change a migrated GCO's V506_graph attribute to use the new graph. Program executed is UpdateGCOLifecycle.
  
  Output = Upgrade518.logGCOLC

Before You Begin

1. VERY IMPORTANT: Before starting the migration, make an offline (cold) backup of your R17 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 V5R17 to V5R18. These procedures do not support any other releases or migration effort. Do not attempt to use any other releases of ENOVIA LCA with these instructions.
3. Ensure that you have a working V5R18 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 R18
4. There should be no users connected to ENOVIA LCA 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 tablespace 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 R18 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 R18. If you do not take these steps, your basic P&O functionality will work, but the customizations you added in R17 will be lost.
    1. Exclude the MASKS step from the 17->18 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 R17, 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 R18 "Migrating an Existing Customization" for complete information. Be sure to include your customized security processes in these updates.
11. Before Migration Begins: Ensure that you have a good EnvName.txt file in your Install-Path/xxx_a directory. For example, if your install path is /usr/DS/R17, you will have a path under this directory with the name of your operating system (like aix or hp or solaris) 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.V5R18.B18
    
    Ensure that this file exists in both R17 and R18, 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.
12. Install ENOVIA V5 VPM V5R18 pointing to existing ENOVIA V5 VPM V5R17 database
    Follow the CD installation steps for ENOVIA V5 VPM V5R18 with the following special instructions:
    1. Use the same database vendor as ENOVIA V5 VPM V5R17 used.
    2. Use the same database name and path as ENOVIA V5 VPM V5R17.
    3. Set the new vault to the same Unix path as the ENOVIA V5 VPM V5R17 vault.

    Use a different Port Number for ENOVIA V5 VPM V5R18 than ENOVIA V5 VPM V5R17 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 R17. You may have to unselect these 2 options if they are selected by default.
    After your installation (enoviadbsetup) is completed, you must manually change the information in the properties file to set the V5R18 Vault to the same path as the old V5R17 Vault.
    
    To do this:

    • cd to the Java Properties directory ~/<platform>_a/docs/java (platform = aix, hpux, solaris)
      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 V5R18 the additional vault(s) using the directions contained in the document Setting Up the Vault Server Manually in UNIX after migration is completed. Make the same Java Properties changes to document these additional vaults as well.

13. 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.

Migration Steps

Migrate ENOVIA V5 VPM V5R17 -> ENOVIA V5 VPM V5R18

1. Logon to the ENOVIA LCA server with the ENOVIA administrator ID. DO NOT attempt to run the migration as root. DO NOT login as root and su to the ENOVIA administrator id. Open a separate window by logging in as the ENOVIA admin ID. Keep the root window you used in STEP 1 available also.
2. cd to the code/command directory under your ENOVIA LCA product install path. This path appears like one of the following:
   ~/aix_a/code/command
~/solaris_a/code/command
~/hpux_b/code/command
   under the directory where you installed the product.
3. Create (for example, using the vi editor) a command 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. The command line for CUSTOMIZED option is as follows: (If you are running STANDARD migration, skip ahead to Step 5 and DO NOT run Step 4.) A Customized database is one that is used in an environment that has been altered using customizations produced by the RADE tool.
   
   ./catstart -run -s “Upgrade518_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 Upgrade518_Enovia.sh to the end of the last parameter.

Default if not specified = 500.
Acceptable values = 1 – 2000.

Example:

-cmaffsize 1000

If the CMAFF step fails with an out-of-memory error, you should retry the step using a smaller value for –cmaffsize.

Here are two sample executable files with working command lines for CUSTO migration, one for Oracle and one for DB2:

DB2

./catstart -run -s "Upgrade518_Enovia.sh -DBVendor DB2 -DBName DBNAME1 -DBAdmHome /home/db2adm -TbsName ENOTBS -IdxTbsName ENOTBS -TableOwner EV5ADM -AdmUsr ev5adm -DBAID db2adm -EnvDir /mig/B18/CATEnv -EnvName ENOVIA V5 VPM.V5R18.B18 -R17path /mig/R17/aix_a/code/dictionary/ -R17custo /R17custo/aix_a/code/dictionary/ -R17CustoWorkspace /R17custo/aix_a/reffiles/DBMS/Generator/ -TMP /tmp/output -Step ALL -cmaffsize 700”

ORACLE

./catstart -run -s “./Upgrade518_Enovia.sh -DBVendor ORACLE -DBName ORADB1 -DBAdmHome /home/oracle/9.2.0 -TbsName ENOTBS -IdxTbsName ENOTBS -TableOwner EV5ADM -AdmUsr ev5adm -DBAID ev5adm -EnvDir /path/R18/CATEnv -EnvName ENOVIA V5 VPM.V5R18.B18 -R17path /path/R17/aix_a/code/dictionary -R17custo /path/R17custo/aix_a/code/dictionary/
-R17CustoWorkspace /path/R17custo/aix_a/reffiles/DBMS/Generator/ -TMP /usr/out -Step ALL -cmaffsize 700“

5. The command line for STANDARD option is as follows: (If you are running CUSTOMIZED migration, go back to Step 4 and DO NOT run Step 5.)
   
   ./catstart -run -s “Upgrade518_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 Upgrade518_Enovia.sh to the end of the last parameter.

Default if not specified = 500.
Acceptable values = 1 – 2000.

Example:

-cmaffsize 1000

If the CMAFF step fails with an out-of-memory error, you should retry the step using a smaller value for –cmaffsize.

The R18 migration has the capability 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 /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.

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.

6. chmod 700 (filename) ...where (filename) is the parameter file you created in the steps above. You must also run the command: export PATH=$PATH:. <- to include current directory in your path.
7. Run the (filename) script from the Unix command line. 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 in the password for this userid. It will not 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 in 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 window and going to the directory you gave as your TMP directory. Use the command ls -lst and look at the timestamp on the most recent Upgrade518* 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 R17 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 R18.
13. If you have not already done so, don’t forget to reconfigure your Vault in R18 to point to the R17 Vault. You must follow the procedures documented within the Migrating a Vault Server Manually chapter of R18 ENOVIA V5 VPM documentation. You must then run another database migration script (Upgrade518_Vault.sh) to make changes to the Vault Database to be compatible with R18.

Special Notes on Migration of Lifecycles (Graphs)

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.