Go to primary content
Oracle Agile Engineering Data Management Upgrade Tool
Release e6.2.0.0
E52564-02
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

2 Configuration and Installation

2.1 Database Settings

The Upgrade Tool needs a well-configured database to provide a good performance.

2.1.1 Oracle Parameters

Check the Oracle parameters and verify that the following minimum values are set in your database instance:

  • memory_target >= 1 GB

  • log_buffer >= 163,840 (3*64 Kbytes)

    If the database memory consumption is too small, adapt the values.

    If you use the server parameter file spfile (like in the Agile e6 standard installation), execute the following commands to change the values of the initialization parameters.

  • Login into Sql*Plus as user sys

    C:\> Sqlplus /nolog SQL> CONNECT <sys>@<db_service> as sysdba SQL>ALTER SYSTEM SET <parameter name>=<Value> SCOPE=BOTH


    Note:

    Do not change the values of production systems. Make a copy of the initialization file and adapt the values.

  • Also read the Oracle online manuals and the Oracle Database 12c (12.1.0.2) installation manual.

Oracle needs physical memory. If the system starts swapping or paging, the Or.acle performance degrades or causes errors. Examine your free physical memory and prevent the OS from swapping.

Some Unix systems have maximum values for shared memory. Refer to the installation instructions before changing any value.

2.1.2 SQL Net Configuration

The network domain is part of different Oracle settings. Please check if the domain is consistently used for the following settings:

  • Global Database

  • Service name

  • Listener.ora

  • Default domain name

2.1.3 Global Database Name

  1. Login into Sql*Plus as user sys and check the global database name.

    The name should contain the network domain. Here is an example:

    sqlplus <system>/<db_password>@<db_service
    SWL>select * from global name;
    GLOBAL_NAME -----------------
    PLM.WORLD
    

    The example uses the default network domain in world. A typical value could look like: PLM61.us.oracle.com.

  2. Change the global database name login to Sql*Plus and execute the following commands:

    SQL>alter database rename global_name to <db_name>.<domain_name>
    

    Example:

    SQL>alter database rename global_name to plm61.us.oracle.com
    

2.1.4 Service Name

The service name in the SQL net configuration file tnsnames.ora in the directory $ORACLE_HOME/network/admin must include the network domain.

  1. Change to the directory $ORACLE_HOME/network/admin.

  2. Open the file tnsnames.ora and check if the service name is fully defined.

    That means the name contains the same network domain as the global database name.

    PLM.WORLD =
    (DESCRIPTION =
    (ADDRESS_LIST =
    (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1524))
    )
    (CONNECT_DATA =
    (SERVICE_NAME = PLM.WORLD)
    )
    )
    

2.1.5 listener.ora

  1. Check if the global database name in the section SID_List of the listener configuration file contains also the same fully qualified global database name.

    SID_LIST_LISTENER_PLM =
    (SID_LIST =
    (SID_DESC =
    (GLOBAL_DBNAME = PLM.WORLD)
    (SID_NAME = plm)
    )
    )
    LISTENER_PLM =
    (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521))
    )
    

2.1.6 sqlnet.ora

The default setting for the network domain in the sqlnet.ora file should be the same.

  1. Change to the directory $ORACLE_HOME/network/admin.

  2. Open the file sqlnet.ora.

  3. Check the default domain settings:

    names.default_domain = world

2.2 Character Scan

With Agile e6, the UTF-8 database server-side encoding is supported. Therefore, a character scan has to be performed prior to the upgrade procedure. This should guarantee that all characters within the dump can be converted to the target encoding and no invalid characters are used.

This check has to be performed in the current production database instance, or in an identical database installation. It has to be executed prior to any dump imports for upgrade purposes.


Note:

In case of a check of an identical database, no charset conversion should be performed prior to this check. This means, NLS_LANG client settings and database character set should have the same settings as defined in the current production environment.


Note:

The entries found during this check have to be corrected manually in the upgraded environment after the take-over phase of the upgrade.

The following is a description of how to proceed with this check.

  1. Install CSSCAN on the database server with user oracle.

  2. Check the csminst.log for errors.

    cd $ORACLE_HOME/rdbms/admin
    set oracle_sid=<your SID>
    sqlplus sys@<your SID> as sysdba
    SQL>spool csminst.log
    SQL>@csminst.sql
    
  3. Create a separate directory from where csscan is run, and output files are placed, e.g. /opt/oracle/tmp/charcheck.

  4. Find out, which character set is used in your production database.


    Note:

    Please make sure you are running this statement in your current production environment.

  5. sqlplus system@PLM/<password>

    SQL>SELECT VALUE AS ORIGINAL_CHARACTER_SET from v$nls_parameters WHERE PARAMETER='NLS_CHARACTERSET';
    
  6. Switch to the directory created in step 2 and perform a database character health check.

  7. To perform a DB character health check, run the csscan utility.

    This could take a few hours if huge tables are scanned.

    csscan <dba_user> USER=<username> FROMCHAR=<original_character_set> TOCHAR=<target_character_set> ARRAY=1024000 LOG=charcheck CAPTURE=Y PROCESS=4
    
    • <original_character_set>:

      The character set of your productive database (as determined in Step 3)

    • <target_character_set>:

      The character set of your upgrade database (UTF-8)

    • <username>:

      The schema to be scanned.

    Example:

    csscan system@PLM61 USER=PLM FROMCHAR=AL32UTF8 TOCHAR=UTF8 ARRAY=1024000 LOG=charcheck CAPTURE=Y PROCESS=4
    

    In this example, the csscan utility will create 3 files:

    • charcheck.out:

      Logs the output of csscan

    • charcheck.txt:

      Database Scan Summary Report

    • charcheck.err:

      Log file that normally should contain the row ids of the rows of the tables reported in charcheck.txt

  8. Log on to the database as user SYSTEM and create a directory CSSCAN_DIR

    sqlplus system@<your SID>/<password>

    SQL>create directory CSSCAN_DIR as '/opt/oracle/tmp/charcheck';

    SQL>grant read, write on directory CSSCAN_DIR to <username>;

  9. Copy the file ora/sql/char_check.sql to /opt/oracle/tmp/charcheck.

  10. Open sqlplus session and connect as EDM database user.

  11. Execute the script char_check.sql.

    SQL>@char_check.sql
    

    The script will create the file charcheck.rep. Values to be corrected are listed by table, column, and C_ID. These values have to be fixed manually.

    =======================
    = Table : BVB_ARTIKEL =
    =======================
    C_ID : 1951227764
    COLUMN: ARTID
    Value : GEH<80>USE
    C_ID : 1951224513
    COLUMN: ARTID
    Value : DREHSTABGEST<80>NGE
    C_ID : 1951227764
    COLUMN: ARTID
    Value : GEH<80>USE
    ======================= = Table : BVB_ARTIKEL
    =======================
    

2.3 Import Dumps

Three dumps need to be imported into one new database environment:

  • Source reference dump

  • Target reference dump

  • Customer dump


Note:

Schemas for source reference dump, target reference dump, and customer dump have to be in one database. Otherwise, the Upgrade Tool will return an error.

For importing the dumps, do not change the table space names because the created table statements on tables containing a blob clause will fail if the original table spaces like EDB, EDB_IDX, and EDB_LOB do not exist

To import dumps into the database, you have to be familiar with your database environment and Oracle import utilities as well. Alternatively, a batch script called imp_dmp.cmd can be used for automated imports (Oracle only). This script uses dumps located in the directory upgrade/dumps.

2.3.1 Import Source Reference Dump

  1. Download appropriate source reference dump from the Oracle Software Delivery Cloud (http://edelivery.oracle.com).

  2. Import it into the new database environment.

    Example: import plm604upgref.dmp into a user named PLM604UPGREF

  3. Import target reference dump.

  4. Download the latest target reference dump from the Oracle Software Delivery Cloud (http://edelivery.oracle.com).

  5. Import it into the new database environment.

    To import the dump execute the following commands in the shell:

    imp <sysuser>/<syspwd>@<dbvname>fromuser=<fromuser>touser=<impdbuser> FILE=../dumps/<impfile>.dmp log=imp_source.log
    sqlplus <impdbuser>/<impdbuser>@<dbname> @../ora/sql/convert_to_utf8.sql > imp_customer2.log
    

2.3.2 Import Customer Dump

  1. Export the current production environment into a dump file and import it in the new environment.


    Note:

    Always work on this customer dump. Do not attach production dump during the upgrade process except for the takeover step described below.


    Note:

    If you are about to import item data into T_MASTER_DAT by using the binary loader, please keep in mind that you have to set the C_ID value of the EDB-NULL-ITEM lower than 2,000,000,000. Otherwise, an error will occur during the import.

    This dump will be the new production dump after the upgrade is completed.


    Note:

    The Agile e6.2.0.0 database client uses the NLS_LANG client setting AMERICAN_AMERICA.AL32UTF8.

    Please also use this setting when you export your database from the old production system. The NLS_LANG setting during importing the dump needs to be the same as for exporting the dump.


  2. Give the new environment an expressive name.


    Note:

    Agile e6.2.0.0 database uses an UTF-8 Database encoding, if the old production is Agile e6.0.x or older. Therefore, a simple import (using IMP tool) will fail. The following commands must be executed to import an older (non-UTF-8) EDM dump into the new database:

    The following variables are used in this example:

    • sysuser = system user name

    • syspwd = system user password

    • dbname = database service name

    • fromuser = user name the dump was exported from

    • impdbuser = schema name where the dump should be imported to

    • impfile = dump file name

  3. Login to SQL *PLus as user customer (impdbuser, in this example).

    Execute script convert_to_utf8.sql.

    SQLPLUS> @ ../ora/sql/convert_to_ut8.sql
    
  4. To import the dump execute the following commands in the shell:

    imp <sysuser>/<syspwd>@<dbvname>fromuser=<fromuser>touser=<impdbuser> FILE=../dumps/<impfile>.dmp BUFFER=132000 feedback=50000 statistics=none rows=n log=imp_customer1.log
    imp <sysuser>/<syspwd>@<srvname> fromuser=<fromuser> touser=<impdbuser> FILE=../dumps/<impfile>.dmp BUFFER=132000 feedback=50000 statistics=none ignore=y log=imp_customer3.log
    

2.3.3 Create Statistics for All Involved Database Schemas

  1. Check Language settings:

    The setting for the environment variable NLS_LANG must be AMERICAN_AMERICA.AL32UTF8, otherwise the statistics will not be computed correctly.

  2. Login in Sql*Plus as user sys with sysdba privilege and gather statistics.

    Sqlplus sys@<your SID>/<password> as sysdba
    SQL> EXECUTE DBMS_STATS.GATHER_SCHEMA_STATS(<DBUSER>,CASCADE =>true);
    

2.4 Run Upgrade Tool

The Upgrade Tool can be run on Windows and UNIX.

  1. Set a DISPLAY variable.


    Note:

    Only required on UNIX.

  2. Control the NLS_LANG setting in:

    Windows Unix
    upg_env.cmd upg_env.sh

    Specifies the client character set. For upgrade reference dumps, default = "AMERICAN_AMERICA.AL32UTF8".

  3. Adapt the following environment definitions in

    Windows Unix
    upg_env.cmd upg_env.sh

    • JAVA_HOME:

      The JDK used for the Agile e6.2.0.0 installation, or JRE 32-bit of the same version, can be used by the Upgrade Tool.

    • ORACLE_HOME:

      Make sure that the Oracle Database 12c (12.1.0.2) environment is set before proceeding with the upgrade.

  4. To check the environment, execute the following commands:


    Note:

    Only required on UNIX.

    > env|grep.NLS
    NLS_LANG=AMERICAN_AMERICA.AL32UTF8
    ORA_NLS10=/opt/oracle/product/12.1/nls/data
    > env|grep ORA
    ORACLE_BASE=/opt/oracle
    ORACLE_HOME=/opt/oracle/product/12.1
    ORACLE_TERM=xterm
    ORA_NLS10=/opt/oracle/product/12.1/nls/data
    

2.5 Configuring the Upgrade Tool

2.5.1 Configuring New Database Environment Connections


Note:

Please make sure that the JAVA_HOME environment variable is set.

  1. Run:

    Windows Unix
    start_upg.cmd start_upg.sh

    The Create Wallet screen is opened. It is mandatory to create a wallet root.

    Surrounding text describes create_wallet_root.png.
  2. Manually create the wallet root directory under <UPG_TOOL_ROOT>/wallet and make it secure.

  3. Click Re-check wallet root.

    If wallet root is accepted, you can create the wallet.

    Surrounding text describes create_wallet.png.
  4. Click Create wallet.

    After the wallet is created, Upgrade Tool UI will be started.

    Surrounding text describes upt_nopassword.png.

    Note:

    Because the wallet is newly created, the passwords, which you have saved in the configuration file <UPG_TOOL_ROOT>/conf/ApplicationParameter.xml, cannot be decrypted.

    You can set it again in Upgrade Tool UI.


  5. Enter the following information for dumps in your new database environment.

    Parameter Description
    Host Host name of database server.
    Port Port number of Oracle listener (default 1521).
    SID Oracle_SID (uppercase). For RAC databases use the SID of the instance where the upgrade tool should run.
    User Database user name.
    Password Password of database user.
    Connection String Service name which is used to run SQL*PLUS commands on the machine the Upgrade Tool is installed on.

    Use fully qualified name including the network domain, i.e. plm60.agile.agilesoft.com

    Note: The service name cannot be tested in the current version of the Upgrade Tool.


    Each database connection can be tested with a "TEST" button on the appropriate tab.


    Note:

    To save changes in the form, press enter after every change in a field. The color then changes from red to black. Otherwise, the changes will be lost.

    Adapt the table space names for each database connection since they are used, e.g. for creation of new database objects, or running SQL scripts:

    Table Space Name Database Connection
    Table Default EDB
    Index Default EDB_IDX
    LOB Default EDB_LOB
    Temporary table Default EDB_TMP
    Temporary index Default EDB_TMPIDX

2.5.2 Configuring Production Database Connection

  1. Enter a database connection for the current production database.

    This connection will be used at the end of the upgrade process in the "Take over" phase. The definition of this connection is different, because it is implemented as a database link, which is temporarily created in your new customer dump. Creation of the database link can be tested with the "TEST" button.

    This connection will not be used until the takeover phase of the upgrade process.


    Note:

    To save changes in the form, press enter after every change in a field. The color then changes from red to black. Otherwise, the changes will be lost.

    Surrounding text describes ch2002.jpg.
    Parameter Description
    Service Name Oracle service name including network domain, i.e. AGILE.AGILESOFT.COM.

    Service name must be defined in tnsnames.ora.

    SID Oracle_SID (uppercase)
    User Database user name.
    Password Password of database user.

2.5.3 Setting Upgrade Tool Parameters

  1. Review and correct the entries if necessary and check the following table for valid entries.

    The correct values can be determined with the Compute button. Always check the computed values.


    Note:

    To save changes in the form, press enter after every change in a field. The color then changes from red to black. Otherwise, the changes will be lost.

    Surrounding text describes ch2003.jpg.
    PLM-Version The customer dump version (before Agile e6 upgrade process). Following values are valid:

    08 = e6.0.1

    09 = e6.0.2

    10 = e6.0.3

    11 = e6.0.4

    20 = e6.1.0.0

    20 = e6.1.0.0004

    21 = e6.1.1

    22 = e6.1.2.0 2

    23 = e6.1.2.2

    24 = e6.1.3.0

    25 = e6.2.0.0

    LogiView Timestamp All LogiView items with a change date after this time point will be deleted. You can adapt this value manually. Following values are possible:

    Note: When using the Upgrade Tool GUI to compute the timestamp, the value stored for EDB-VERSION in table T_DEFAULT in Agile e6 will be used to generate the timestamp.


    axalant2000 SP1 20001109140557
    axalant2000 SP2 20010723102350
    axalant2000 SP3 20011113092600axa2000 SP3 PA1 20020808110309Eigner PLM 5.0.1 20020830153411Agile e6.0 LA¼ 20050414160530Agile e6.0 GA² 20050615170000Agile e6.0.1 20051111135800Agile e6.0.2 LA¼ 20060630200000Agile e6.0.2 GA² 20060731220000Agile e6.0.3 20070213080000Agile e6.0.4 20070704180000Agile e6.1.0.0 20080929210000Agile e6.1.0.0004 20081107210000Agile e6.1.1 20090812210000Agile e6.1.2.0 20101105210000Agile e6.1.2.2 20120116210000Agile e6.1.3.0 20131118210000

    ¼: Limited Availability

    ²: General Availability

    Classification -Control file A file name of the classification control file for the customer dump. Valid entries are:

    cla_ctl.xml cla_ctl_with_multi_lang.xml cla_ctl_with_multi_lang_repl.xml cla_ctl_with_repl.xml

    Database Language Language for the database dump. This influences the migration of the classification date. Values: German, English Default: German
    Level Status that is set during classification upgrade for records in the tables T_CLA_DAT (pool attributes), T_GROUP_DAT (classes)
    Replication server The valid name of the database server, in case of an implemented database replication to the environment, should be migrated.

2.5.4 Save Configuration

To save the current configuration, select File > Save.