Oracle8 Server Migration
Release 8.0
A54650_01

Library

Product

Contents

Index

3
Migrating to Release 8.0.3 by Migration Utility

The sections in this chapter guide you step-by-step, in order, through the processes involved in using the Oracle8 Migration Utility to migrate an Oracle7 database to Oracle8. Topics covered include the following:

Overview of Migration Using the Oracle8 Migration Utility

Migration converts the data dictionary and structures of an Oracle7 database into Oracle8 format. The process of migrating an Oracle7 database is accomplished by the DBA first installing and running the Oracle8 Migration Utility on the Oracle7 side. The DBA then executes a series of ALTER DATABASE commands on the new Oracle8 database. The result of these procedures is the conversion of the following Oracle7 structures so they can be used in Oracle8:

Data files (file header only)
Data dictionary
Control file(s)
Rollback segment(s)

Note: A Version 6 database must be migrated to at least Release 7.1.x (see Oracle7 Server Migration, Release 7.3) before it can be migrated to Oracle8.

Note: The Migration Utility cannot transform an Oracle8 database back to Oracle7. In some situations, other facilities can provide for such a return, for example, using Export/Import, restoring from backups, and possibly using other functions.

Note: If the Oracle database system has Advanced Replication installed, refer to Oracle8 Server Replication, Appendix B, "Migration and Compatibility" before running the Migration Utility.

The migration process can be summarized as follows:

On the Oracle7 side:

The DBA runs the Migration Utility which creates and populates a new data dictionary based on the Oracle7 data dictionary, and also creates a binary file based on the Oracle7 control file, called the convert file.

Note: The DBA can run the Oracle8 Migration Utility multiple times (without opening the database in Oracle8) and still be able to return to the Oracle7 database. However, running the Migration Utility automatically eliminates the Oracle7 database catalog views (see "Abandoning the Migration" on page 3-13).

On the Oracle8 side:

The DBA executes an ALTER DATABASE CONVERT statement, which creates a new control file based on the convert file generated by the Migration Utility; converts all online datafile headers to Oracle8 format; and mounts the Oracle8 database.

The file headers of offline datafiles are converted later when they are brought online, and the file headers of read-only tablespaces are converted when they are made read-write.

The DBA executes an ALTER DATABASE OPEN RESETLOGS statement. This command automatically converts all objects and users defined in the new dictionary to Oracle8 specifications, and converts all rollback segments to Oracle8 format.

If a source database rollback segment is in a tablespace that is offline when the Oracle8 database is opened, the rollback segment is not converted immediately to Oracle8 database format. Instead the rollback segment is converted the first time the tablespace is brought online in Oracle8.

System Considerations and Requirements

Space Required for Migration by Migration Utility

The Migration Utility requires relatively little temporary space. It needs only enough extra room in the SYSTEM tablespace to hold the new Oracle8 data dictionary simultaneously with the existing Oracle7 data dictionary.

The space required to hold an Oracle data dictionary depends on how many objects are in the database. Typically, a new Oracle8 data dictionary may be 50 per cent larger than its Oracle7 source data dictionary. If necessary, add space to the SYSTEM tablespace.

The Migration Utility will not complete the migration unless sufficient space is allocated in the SYSTEM tablespace before migration begins. The Utility will return an error stating how much additional space needs to be allocated.

To determine how much space is needed for a successful migration, run the Oracle8 Migration Utility with the CHECK_ONLY command line option set to TRUE. The CHECK_ONLY command line option makes the Migration Utility assess how much space would be required, check the availability of the space for migration, and issue an informational message without building the Oracle8 data dictionary or performing any other migration processing.

Block Size Considerations

The value of DB_BLOCK_SIZE (parameter in INIT.ORA) in the Oracle7 database and in the Oracle8 migrated database must be the same. Oracle8 requires a minimum block size of 2048 bytes (2KB). Above this amount, integer multiples of the platform's physical block size are acceptable, but multiples of 2KB, especially powers of 2-that is, 2KB, 4KB, 8KB, 16KB-provide for the most robust operation. In summary, make sure the Oracle8 block size setting complies with the following criteria:

Matches the Oracle7 setting
Is at least 2048 bytes (2KB)
Note: The Oracle8 Migration Utility gives an error message if the Oracle7 block size is less than 2KB.
Is an integer-multiple of the platform's physical block size (see the operating system specific documentation), preferably a multiple of 2KB.

Considerations for Replication Environments

An Oracle7 replication environment can be migrated to Oracle8, site by site. Oracle7 sites can coexist and run successfully with Oracle8 sites within the replication environment. However, you must take special care to accommodate the various replication features implemented on each system. Be sure to study Oracle8 Server Replication, particularly Appendix B, "Migration and Compatibility," which provides detailed instructions for migrating systems that implement replication features.

Migrating to a Different Computer Architecture

The Oracle8 Migration Utility cannot migrate a database to a computer system that uses a different architecture. For example, it will not successfully migrate a database from a 32-bit platform to a 64-bit platform or from Oracle7 on AIX to Oracle8 on SP2. Different types of operating systems are typically associated with different architectures. Therefore, the Migration Utility generally will not migrate a database between such operating systems. However, migration using the Export/Import procedures normally will work correctly in such situations.

Character Encoding Considerations

Successful migration requires that the character encoding scheme for data in the Oracle8 database must be correctly specified. All character data in the Oracle8 database is assumed to be in the character encoding scheme specified in the CREATE DATABASE command that created the database. For information on National Language Support (NLS) for specifying these character encodings, see the Oracle8 Server Reference Manual.

The Migration Utility uses the character set of the source Oracle7 database as the character set for the Oracle8 database unless specified otherwise by the language parameter in the INIT.ORA initialization file (see also "NCHAR and NLS Use" on page 6-15 and "NCHAR and NLS Parameters and Compatibility" on page D-2). This character set cannot be changed after migration is complete, so you must ensure that the correct character set is specified before you run the Migration Utility.

Prepare the Oracle7 Source Database for Migration

Several preparatory steps are required before you perform a clean shutdown of the database followed by the migration processes:

The Oracle8 Migration Utility migrates only Oracle7 databases-Release 7.1.4 or higher. If the production database is an earlier version, for example, Version 6, migrate it to Oracle7, Release 7.1, at least, before implementing the Oracle8 migration procedures.
Make sure all datafiles and tablespaces are online or offline normal.

The Oracle8 Migration Utility will not proceed, and gives an error, if any datafiles need media recovery. Tablespaces that are not taken offline cleanly (that is, are taken offline by using an ALTER TABLESPACE OFFLINE IMMEDIATE or OFFLINE TEMPORARY command) must be dropped or brought online before migration. Otherwise such tablespaces will not be available under Oracle8 after migration.

Note: Tablespaces that are offline when you open the Oracle8 database remain in Oracle7 database file format. The offline tablespaces can be brought online at any time after migration, and the file headers are then converted to Oracle8 format.

Make sure no user or role has the name MIGRATE, because the Oracle8 Migration Utility creates this schema and uses it to replace any pre-existing user or role with this name, and finally drops it from the system.
Make sure no redo information and no uncommitted transactions are outstanding; resolve every pending, in-doubt transaction. That is, as discussed in the "Manually Overriding In-Doubt Transactions" section in Oracle8 Server Distributed Systems, ensure that no in-doubt transactions are left in DBA_2PC_PENDING.
Make sure your SYSTEM tablespace has enough free space to hold the Oracle8 data dictionary and the existing Oracle7 data dictionary concurrently. For more information see "Space Required for Migration by Migration Utility" on page 3-3.

Install the Oracle8 Migration Utility

Install the Oracle8 Migration Utility executable from the Oracle8 CD into the Oracle7 $ORACLE_HOME directory, as follows:

Note: The specific commands for some steps of the following procedure depend on the platform operating system. Refer also to the platform-specific Oracle documentation and README file.

Run the Oracle8 installation utility. The utility name will vary, depending on the operating system-for example, orainst on UNIX systems or oracleins on VMS.
On the "Select the Installer activity" screen select "Install, Upgrade, or De-Install Software".
On the "Select the Installer option" screen select the "Migrate from ORACLE7 to ORACLE8".
On the "Select an ORACLE7 to ORACLE8 migration action" screen select "Install Migration Utility". The installation utility then builds the environment to run the Migration Utility on the Oracle7 database. For example, on the UNIX platform, the following installations take place:

the Oracle8 Migration Utility executable installed into the Oracle7 home directory $ORACLE_HOME/bin.
the Oracle8 version of the message file, migus.msb, installed into the Oracle7 message directory $ORACLE_HOME/rdbms/mesg.
the Oracle8 version of migrate.bsq installed into Oracle7 $ORACLE_HOME/dbs.
the required NLS files installed into Oracle7 $ORACLE_HOME/migrate/nls/admin/data.

If you choose not to use the Oracle8 Installation utility to set up the environment for the Migration Utility, make sure all files (migrate executable, message files, MIGRATE.BSQ, and NLS files) are in the correct locations, as listed in this step. For detailed information on the Oracle Installer, see the platform-specific Oracle8 Installation Guide.

Oracle8 Migration Utility Command Line Options

In executing the Oracle8 Migration Utility, you can specify several command-line parameters, as described in this section. Refer also to the operating system-specific Oracle documentation for possible additional details.

CHECK_ONLY	When TRUE, space use calculations are performed without performing any migration (mutually exclusive with NO_SPACE_CHECK). When FALSE (default), both space usage calculations and migration are performed.
*DBNAME*	Specifies name of the database to migrate (db_name in init.ora)
*MULTIPLIER*	Specifies the initial size of the Oracle8 i_file#_block# index relative to the Oracle7 i_file#_block# index. For example, MULTIPLIER=30 triples the initial size when the index is created; or no MULTIPLIER specified, by default uses the i_file#_block# value of 15, creating an index for Oracle8 that is 1.5 times larger than the Oracle7 i_file#_block# index.
*NEW_DBNAME*	Specifies a new name for the migrated database. The default name "DEFAULT" should not be used. Choose a more meaningful name.
*NLS_NCHAR*	Specifies the National Language Standard (NLS) NCHAR character set in props$ for the Oracle8 database, for example, W52DEC or US7ASCII. The default otherwise is the Oracle7 database character set.
*NO_SPACE_CHECK*	When TRUE, no space check is performed before migration; mutually exclusive with CHECK_ONLY.
*PFILE*	Specifies the name of the parameter file (if not using the expected default, INIT.ORA). Note: pathname must be enclosed by double-quotes masked by backslash on UNIX, for example, mig PFILE=\"/tmp/mig/pfile\"
*SPOOL*	Specifies filename of file to which to spool output; pathname must be enclosed by double-quotes masked by a backslash on UNIX, for example, mig SPOOL=\"/tmp/mig/spool\"

Migrate the Oracle7 Source Database

The following sections explain the exact steps to follow to migrate an Oracle7 source database to Oracle8 using the Oracle8 Migration Utility.

Migration on the Oracle7 Side

Make sure you have DBA privileges, which are necessary to run the Oracle8 Migration Utility.
Refer to the platform-specific documentation, and verify the system settings that control the placement of new Oracle8 database objects you will be creating. For example, on a UNIX system unset the TWO_TASK environment variable; on an NT system, however, TWO_TASK must remain set; or on VMS unset the ORA_DFLT_HOSTSTR logical variable.
Be sure no other DBA (CONNECT INTERNAL) with RESTRICTED SESSION privilege will connect to the database while the migration utility is running. "Normal" users cannot connect to the database anyway.
Make sure the Oracle ORA_NLS33 variable is set correctly. For example, on UNIX with the NLS file installed in the default location, $ORACLE_HOME/migrate/nls/admin/data, you must set ORA_NLS33 to $ORACLE_HOME/migrate/nls/admin/data.
Shut down the Oracle7 database cleanly using the SHUTDOWN command. (NORMAL or IMMEDIATE are OK. Do not use SHUTDOWN ABORT.) The Oracle7 source database must be shut down cleanly, so no redo information and no uncommitted transactions are left outstanding.

Note: If the Oracle7 database is not shut down before migration starts, the Migration Utility will stop and issue an error message.

Run the Oracle8 Migration Utility:

To start the Migration Utility at the system prompt, use the command shown in the operating system specific documentation. For example, on a UNIX system enter mig alone (for a default set of options) or enter mig followed by one or more selected options (see "Oracle8 Migration Utility Command Line Options" on page 3-7).
To run the Migration Utility from the installer:

Run the Oracle8 installation utility. Depending on the operating system, for example, use orainst on a UNIX system, or use oracleins on VMS.
On the "Select the Installer activity" screen select "Install, Upgrade, or De-Install Software".
On the "Select the Installer option" screen select the "Migrate from ORACLE7 to ORACLE8".
On the "Select an ORACLE7 to ORACLE8 migration action" screen select "Run Migration Utility" and the installation utility then guides you through a series of configuration questions before running the Migration Utility.

Check the results after running the Migration utility. The Migration Utility generates informational messages (such as starting up or shutting down the database) and echoes its progress as it runs the MIGRATE.BSQ script (see Appendix B, "Migration Utility Messages").

The Migration Utility creates a convert file that contains the information of the Oracle7 control file. The name and location of the convert file are platform specific. The default name on a UNIX platform is Oracle7 $ORACLE_HOME/dbs/conv<SID>.dbf where <SID> is your Oracle7 instance ID. The convert file is used by "ALTER DATABASE CONVERT" to create a new controlfile in Oracle8 (see Step 11 in"Migration on the Oracle8 Side" on page 3-11).

Warning: Do not attempt to open the Oracle7 database, which the Oracle8 Migration Utility has automatically shut down at this point. To ensure datafile version integrity, the SCNs in the dictionary, the convert file, and file header must all be consistent when the database is converted at Oracle8. If the Oracle7 database is opened after the Migration Utility is run, the SCN checking will fail later at Oracle8 convert time, giving an error, most likely an ORA-1211 error stating "Oracle7 datafile is not from migration to Oracle8." Therefore, if the Oracle7 database is opened, you must rerun the Migration Utility again, starting at Step 5.

Although it is not recommended to be done immediately after the Migration Utility completes a successful migration, you could at this time deinstall the Oracle7 software by using the Oracle7 Installer. However, if the Migration Utility were to have failed somehow without announcement, you would then need the Oracle7 software in the preceding steps to retry the migration. Or you would need the Oracle7 software to restore the Oracle7 database if migration were to be abandoned (see "Abandoning the Migration" on page 3-13).

Step 4: Preserve the Oracle7 Source Database

After the Migration Utility runs successfully, take a cold backup to preserve the Oracle7 database. The backup taken at this time serves two purposes:

If you wish to return to the Oracle7 database after executing the ALTER DATABASE CONVERT command on Oracle8, you can restore the backup and start the Oracle7 database.
It can be used as the first Oracle8 backup for an Oracle8 recovery.
If an error occurs at Oracle8 database convert time (ALTER DATABASE CONVERT or ALTER DATABASE OPEN RESETLOGS), you can restore the backup taken after the Migration Utility was run, fix the problems, and continue the conversion process. However, if you restore the backup taken before the Migration Utility was run, you must rerun the Migration Utility.

Make a backup of the entire Oracle7 software distribution, that is, of the Oracle7 home directory, $ORACLE_HOME (UNIX) or ORA_ROOT (VMS). Be sure the backup includes all subdirectories and all of the following:

control files
datafiles and online redo log files (in case any datafiles in the Oracle7 database are lost or unreadable), even though these files should not contain any outstanding redo information.
parameter files
convert file
scripts that create objects in the Oracle7 database
scripts that could restore the original database, if necessary.

Migration on the Oracle8 Side

Install Oracle8 software with the Oracle8 Installer, choose the Install/Upgrade option and thus bypass creation of a new instance/database. Installation of the Oracle8 database is operating system specific. See the operating system-specific Oracle8 installation documents, and read additions or modifications in README.DOC included with Oracle8.
Make sure that the appropriate environment variable points to the Oracle8 executables. If $ORACLE_HOME points to the Oracle7 executable, an ORA-223 error "conversion data file is invalid or incorrect version" will be returned by "ALTER DATABASE CONVERT" command.
Make sure the operating system running the Oracle8 DBMS is the same as the operating system used for running the Oracle7 DBMS and the Oracle8 Migration Utility.
Adjust the INIT.ORA file for Oracle8:

Certain Oracle7 initialization parameters are obsolete in Oracle8. You must remove all obsolete parameters from any initialization parameter file that starts an Oracle8 instance. Obsolete parameters may cause errors if used with an Oracle8 database. You must also alter any parameter whose syntax has changed in Oracle8; refer to Appendix D, "Oracle8 INIT.ORA Changes" for lists of new, changed, and obsolete parameters.
The value of certain Oracle initialization parameters should be adjusted from Oracle7 values to work with Oracle8, for example, COMPATIBLE should be adjusted to COMPATIBLE=8.0.0.0.0 or should not be set at all.

Remove or rename the database's control files. They are created automatically by the ALTER DATABASE CONVERT command.
Move or copy the convert file from Oracle7 environment to the Oracle8 environment. On UNIX, the convert file, conv<SID>.dbf (where <SID> is the Oracel8 instance ID), should reside in $ORACLE_HOME/dbs. If the Oracle8 instance ID is different from the Oracle7 instance ID, be sure to rename it accordingly.
Before starting the server manager, avoid most possible future errors by first making sure all online data files are accessible and in the right directories. If you are using a raw disk, log files also must be accessible.
Start the server manager, SVRMGRL.
Connect to the Oracle8 database instance:

SVRMGR> CONNECT INTERNAL;

Start an Oracle8 database instance without mounting the new Oracle8 database:

SVRMGR> STARTUP NOMOUNT;

WARNING: Starting in any other mode might corrupt the database.

Create a new Oracle8 database control file, and convert the file header of all online tablespaces to Oracle8 format:

SVRMGR> ALTER DATABASE CONVERT;

Note: Successful execution of this command is the "point of no return" to Oracle7 for this database. (If necessary, you can restore the Oracle7 database from backups, of course.)

Note: Control files are considerably larger in Oracle8 than in Oracle7. Control files in the tens of kilobytes size range in Oracle7 could be expanded into the range of tens of megabytes automatically during migration to Oracle8. This size increase could be important if the control file is on a raw device or if its available disk space is restricted.

WARNING: If an error occurs during this step, you must correct the condition(s) that caused the error(s) and rerun the Migration Utility, restarting at Step 1 on page 3-8, otherwise restore the backup taken after the Migration Utility was run.

Open the Oracle8 database:

SVRMGR> ALTER DATABASE OPEN RESETLOGS;

When the Oracle8 database is opened, all rollback segments that are online are converted to the new Oracle8 format.

Set the system to spool results to a log file for later verification of success:

SVRMGR>SPOOL CATOUT.LOG

Run the Oracle8 database conversion script, CAT8000.SQL:

SVRMGR>@CAT8000.SQL

The CAT8000.SQL script creates and alters certain system tables and drops the "MIGRATE" user. It also runs the CATALOG.SQL and CATPROC.SQL scripts, which create the system catalog views and all the necessary packages for using PL/SQL.

Note: To create additional data dictionary structures, see Oracle8 Server Reference Manual for a complete list and description of available scripts.

Note: If the Oracle system includes implementation of any Oracle option, such as the Parallel Server, you must also run the appropriate script to install each option. These scripts are described in the Oracle8 Server Reference Manual.

Note for Replication Systems: If the Oracle system has the Advanced Replication Option installed, you must also run the Oracle8 conversion script, CATREP8M.SQL:

SVRMGR>@CATREP8M.SQL

Turn off the spooling of script results to the log file:

SVRMGR>SPOOL OFF

Check the spool file (for this example, CATOUT.LOG) and verify that every package and procedure compiled successfully.
Run SHUTDOWN on the Oracle8 database:

SVRMGR> SHUTDOWN
(NORMAL or IMMEDIATE is OK. Do not use SHUTDOWN ABORT.)

Note: Executing this clean shutdown flushes all caches, clears buffers, and performs other DBMS housekeeping activities. These measures are an important final step to ensure the integrity and consistency of the newly migrated Oracle8 database.

The Oracle7 database now has been migrated to Oracle8 and is ready to be opened for use.

Errors During Migration

Errors might occur during the migration procedure, and error messages might be displayed. Errors can be caused by the following actions or omissions.

Performing a migration step out of order
Not fulfilling the prerequisites for migration
Encountering an occasional conversion irregularity

See Appendix B, "Migration Utility Messages" and Oracle8 Server Messages for information about errors possible during migration and about the action to take for correction of each.

Abandoning the Migration

Note: The DBA can run the Oracle8 Migration Utility multiple times (as detailed in "Migration on the Oracle7 Side" on page 3-8) and yet be able to return to the Oracle7 database. However, running the Migration Utility automatically eliminates the Oracle7 database catalog views. Therefore, to return to the Oracle7 database after the Migration Utility has run, the Oracle7 database catalog views must be restored by running the Oracle7 CATALOG.SQL script.

To abandon the migration, depending on how far the migration proceeded, for example before Step 11 on page 3-11, you generally must restore the Oracle7 database again, as follows:

Start up the Oracle7 database (shown using server manager):

> SVRMGRL

SVRMGR> CONNECT INTERNAL

SVRMGR> STARTUP

Drop the user "MIGRATE":

SVRMGR> DROP USER MIGRATE CASCADE

Rerun CATALOG.SQL and CATPROC.SQL:

SVRMGR> @CATALOG.SQL

SVRMGR> @CATPROC.SQL

If the Server Manager is installed, also run CATSVRMG.SQL:

SVRMGR> @CATSVRMG.SQL

If the Parallel Server is installed, also run CATPARR.SQL

SVRMGR> @CATPARR.SQL

If the Advanced Replication Option is installed, CATREP.SQL:

SVRMGR> @CATREP.SQL

Note: The Oracle8 Migration Utility upgrades Release 7.1 and Release 7.2 databases to Release 7.3. If the original Oracle7 production database was Release 7.1 or 7.2 and the migration is run but abandoned before the conversion to Oracle8, the Oracle7 database will be left with a dictionary that is apparently Release 7.3.