6
Upgrading Your Applications

This chapter describes upgrading your current applications and covers the following topics:

• Overview of Upgrading Applications
• Upgrading Precompiler and OCI Applications
• Upgrading SQL*Plus Scripts
• Upgrading Oracle7 Forms or Oracle Developer Applications

Overview of Upgrading Applications

You do not need to modify existing applications that do not use features available in the new Oracle9i release. Existing applications running against a new Oracle9i database function the same as they did on prior releases and achieve the same, or enhanced, performance.

Many new features and enhancements are available after upgrading to the new Oracle9i release. Some of these features provide added functionality, while others provide improved performance. Before you upgrade your applications, you should review these new features to decide which ones you want to use.

Compatibility Issues for Applications

There may be compatibility issues between different releases of Oracle that could affect your applications. These compatibility issues result from differences in the Oracle database server in various releases. Also, in each new release of Oracle, new Oracle reserved words may be added, changes may be made to initialization parameters, and changes may be made to the data dictionary.

When you upgrade your Oracle database server to a new release, make sure that your applications do not use any Oracle reserved words, that your applications are compatible with the initialization parameters of the server, and that your applications are compatible with the data dictionary of the server. Finally, a new release of Oracle software may require certain operating system releases or the application of certain patch sets.

SQL*Net release 2.x, Net8, and Oracle Net Services work with various Oracle releases. Thus, Oracle7, Oracle8, Oracle8i, and Oracle9i databases can communicate by using SQL*Net release 2.x, Net8, and Oracle Net Services. SQL*Net release 1.x, however, uses a different network addressing scheme and cannot be used with release 8.0 and higher.

Upgrading Precompiler and OCI Applications

The upgrade path is very similar for precompiler and OCI applications. This section guides you through your upgrade options for these applications and notes differences between precompiler and OCI applications whenever necessary.

Create a test environment before you upgrade your production environment. Your test environment should include your upgraded application and the new Oracle9i database. Also, your test environment should provide a realistic test of your application.

Understanding Software Upgrades and Your Client/Server Configuration

To understand your options for upgrading precompiler and OCI applications, you first need to understand the type of software upgrade you are performing and your client/server configuration.

Types of Software Upgrades

Two types of upgrades are possible for both client and server Oracle software.

Major Database Release Upgrade

The upgrade changes the first digit of the release number.For example, upgrading from Oracle8i to Oracle9i is a major database release upgrade.

Database Maintenance Release Upgrade

The upgrade changes the second digit of the release number. For example, upgrading from release 9.0.1 to release 9.2 is a database maintenance release upgrade.

Possible Client/Server Configurations

Your precompiler and OCI applications run on the client in a client/server environment, where the Oracle database server is the server. You may use one or more of the following client/server configurations in your environment.

Different Computers

The client software and the server software are on different computers, and they are connected through a network. The client and server environments are separate.

Different Oracle Home Directories on the Same Computer

The client software and the server software are on the same computer, but they are installed in different Oracle home directories. Again, the client and server environments are separate.

Same Oracle Home

The client software and server software are installed in the same Oracle home on the same computer. In this case, any upgrade of the server software is also an upgrade of the client software.

Compatibility Rules for Applications When Upgrading Oracle Software

This section covers compatibility rules that apply when you upgrade Oracle server software or Oracle client software. The rules are based on the type of software upgrade you are performing and on your client/server configuration.

The following sections contain compatibility rules for the following type of upgrades:

• Upgrading the Oracle Server Software
• Upgrading the Oracle Client Software

  Note: This section uses the terms introduced in "Understanding Software Upgrades and Your Client/Server Configuration".

Upgrading the Oracle Server Software

The following rules apply when you upgrade the Oracle server software.

If You Do Not Change the Client Environment, Then You Do Not Need to Relink.

If your client and server are on different computers or are in different Oracle home directories on the same computer, and you upgrade the Oracle server software without changing the client software, then you do not need to precompile, compile, or relink your applications. In these cases, the client software is separate from the server software and will continue to function against the server.

However, if your applications are using the same Oracle home as the Oracle database server, then your server upgrade also upgrades your client software, and you must follow the rules in "Upgrading the Oracle Client Software".

Applications Can Run Against Newer or Older Oracle Server Releases

When you run a precompiler or OCI application against a database server, Oracle Corporation recommends that the release of the database server software be equal to or higher than the client software release, but this configuration is not strictly required. For example, if your Oracle client software is release 8.1.7, then your Oracle server software should be release 8.1.7 or higher to run a precompiler application on the client against the server.

For OCI, Oracle7 client software can run against a release 8.0 or higher Oracle server, and release 8.0 and higher client software can run against an Oracle7 server. If a release 8.0 or higher client is running against an Oracle7 server, then the application cannot use features available in release 8.0 and higher, including object capabilities.

Upgrading the Oracle Client Software

Oracle Corporation recommends that you upgrade your client software to match the current server software. For example, if you upgrade your Oracle database server to release 9.2, then Oracle Corporation recommends upgrading the client software to release 9.2 as well. Keeping the server and client software at the same release number ensures the maximum stability for your applications. In addition, the latest Oracle client software may provide added functionality and performance enhancements that were not available with previous releases.

The following rules apply when you upgrade the Oracle client software.

Applications Can Be Linked with Newer Libraries

The code generated by precompiler applications can be linked with a release of the client library that is equal to or higher than the server release. In addition, Oracle7 and release 8.0 and higher SQLLIB function calls cannot be mixed in the same application and the same transaction.

OCI applications can be linked with a version of the OCI runtime library that is equal to or higher than the version of the OCI library with which the application was developed.

Statically-Linked Applications Do Not Need to be Relinked

For statically-linked applications, when you perform any type of upgrade of the client software, you do not need to relink your precompiler and OCI applications. However, relinking is recommended because it may improve performance.

Dynamically-Linked Applications Do Not Need To Be Relinked

When you perform an upgrade of your client software, you do not need to relink your dynamically-linked precompiler and OCI applications. However, relinking is recommended because it may improve performance.

Upgrading Options for Your Precompiler and OCI Applications

You have the following four options for upgrading your precompiler and OCI applications:

Option 1:	Leave the application unchanged. Do not relink, precompile, or compile the application, and do not change the application code. The application will continue to work against an Oracle9i database.
Option 2:	Relink the application with the new Oracle9i libraries. Do not precompile or compile the application and do not change the application code.
Option 3:	Precompile and/or compile and then relink the application using the new Oracle9i software. Do not change the application code.
Option 4:	Change the application code to use new Oracle9i features. Then, precompile and/or compile and then relink the code.

These options are listed in order of increasing difficulty and increasing potential benefits. That is, Option 1 is the least difficult option, but it offers the least potential benefits, while Option 4 is the most difficult option, but it offers the most potential benefits. These options are discussed in the following sections.

Option 1: Leave the Application Unchanged

You can leave the application unchanged, and it will continue to work with an Oracle9i database. The major advantage to this option is that it is simple and easy. In addition, this option requires the least amount of administration, because you do not need to upgrade all of your client computers. If you have a large number of client computers, then avoiding the administrative costs of upgrading all of them can become very important.

The major disadvantage to this option is that your application cannot use the features that are available in the new Oracle9i release. In addition, your application cannot leverage some of the possible performance benefits of the new Oracle9i release.

Option 2: Relink the Application with the New Oracle9i Libraries

You can relink the application with the new Oracle9i libraries, without making any code changes and without recompiling. By relinking, your application may benefit from performance improvements that are available only with the new libraries. Remember that you should always relink the application in a test environment before you relink in your production environment.

Option 3: Precompile or Compile the Application Using the New Software

You can precompile or compile the application with the new Oracle9i software, without making any code changes. This option requires that you install the new Oracle client software on each client computer. However, you only need to precompile or compile, and relink your application once, regardless of the number of clients you have. The advantages, however, can be quite large.

By recompiling, you perform a syntax check of your application code. Some problems in the application code that were not detected by previous releases of the Oracle software may emerge when you precompile or compile with the new Oracle software. Therefore, precompiling and compiling with the new software often helps you detect and correct problems in the application code that may have gone unnoticed before.

Also, recompiling affords maximum stability for your application, because you are sure that it works with the new Oracle software. Further, your environment is ready for new development using the latest tools and features available. In addition, you may benefit from performance improvements that are available with the new Oracle software only after you recompile and relink.

Option 4: Change the Application Code to Use New Oracle9i Features

You can make code changes to your application to take advantage of new Oracle9i features. This option is the most difficult, but it can provide the most potential benefits. You gain all of the advantages described in Option 3. In addition, you also benefit from changes to your application that may leverage performance and scalability benefits available with Oracle9i. Further, you can add new features to your application that are available only with the new release of Oracle9i.

Become familiar with the new Oracle9i features by reading Oracle9i Database New Features. Also, consult the Oracle documentation for your development environment so that you understand how to implement the features you want to use. For the precompilers, see Pro*C/C++ Precompiler Programmer's Guide and Pro*COBOL Precompiler Programmer's Guide. For OCI, see Oracle Call Interface Programmer's Guide.

When you have decided on the new features you want to use, change the code of your application to use these features. Follow the appropriate instructions in the following sections based on your development environment:

• Changing Precompiler Applications
• Changing OCI Applications

Changing Precompiler Applications

Complete the following steps to change your precompiler application to use Oracle9i features:

1. Perform one of the following actions based on whether the existing application is an Oracle7 application or a version 8 application:
   • If you have an Oracle7 application, then the existing Oracle7 application may need to be modified, or new applications written, to reflect the differences between Oracle7 and Oracle9i.
   • If you have a version 8 application and you want to take advantage of the new Oracle9i features, then incorporate code for the new Oracle9i functionality into the existing version 8 application.
2. Precompile the application using the Oracle precompiler.
3. Compile the application.
4. Relink the application with the Oracle9i runtime library, SQLLIB, which is included with the precompiler.

Changing OCI Applications

Complete the following steps to change your OCI application to use Oracle9i features:

1. Change your OCI calls in one of the following ways:
   • If your application uses Oracle7 OCI calls, then modify the application to use only new Oracle9i OCI calls.
   • If your application uses Oracle7 OCI calls, then incorporate Oracle9i OCI calls into the existing application, while still using Oracle7 calls for some operations.
   • If your application uses only version 8 calls, then incorporate the new Oracle9i OCI calls into the existing application.
2. Compile the application.
3. Relink the application with the Oracle9i runtime library.

Upgrading SQL*Plus Scripts

To use SQL*Plus release 8.0 and higher, a release 8.0 or higher database, and PL/SQL release 8.0 and higher functionality, complete the following steps:

1. Make the following changes to SQL*Plus release 3.x scripts to convert them into scripts that are compatible with SQL*Plus release 8.0 and higher:
   1. If a script contains the line SET COMPATIBILITY V7, then change it to SET COMPATIBILITY NATIVE, or remove the line so that the default setting is used. In Oracle9i, the default setting is NATIVE.
   2. Check any login.sql and glogin.sql files and change any SET COMPATIBILITY V7 line found to SET COMPATIBILITY NATIVE.
2. To use new Oracle9i functionality, change existing SQL scripts to use the new Oracle9i syntax. Existing SQL scripts run unchanged on Oracle9i, and require no modification, if they do not use new Oracle9i functionality.

   See Also: SQL*Plus User's Guide and Reference to learn about new functionality in SQL*Plus Oracle9i SQL Reference for more information about upgrading SQL scripts

   Note: No changes to PL/SQL packages, procedures, or functions should be required.

Upgrading Oracle7 Forms or Oracle Developer Applications

Forms applications run the same on Oracle7, version 8, and Oracle9i. However, review the new features described in Oracle9i Database New Features to determine whether any of the new Oracle9i features would be beneficial to your applications or might otherwise affect them. Information about the ways in which the Oracle9i features interact with forms and developer applications is provided in the Oracle Developer documentation set. Also, the Oracle Developer documentation for your operating system contains instructions for upgrading your forms or developer applications.