7 Migration from Earlier Oracle Versions

If you have existing Oracle-accessing applications on z/OS that were developed with an Oracle Database release before Oracle Database 10g, read this chapter to understand the issues or considerations for those applications. Which issues or considerations apply depend on the applications and on the Oracle Database version with which they have been running.

This chapter assumes that you are migrating from an Oracle version no older than Oracle8i OSDI. If your applications are still running with libraries and components from Oracle8i MPM, or from any older Oracle release, you will need to refer to the Oracle8i OSDI and Oracle9i OS/390-specific documentation for additional application migration considerations.

This chapter contains the following sections:

Overview
Migrating from Oracle8i
Migrating from Oracle9i

7.1 Overview

There are two independent aspects in an application migration. One is migration of the z/OS client-side components (the Oracle program interface code, message library, Access Managers, and Oracle tools and utilities). The other is migration of the target Oracle server used by the applications. Typically, these two migrations are not done simultaneously. In general, applications built under an older Oracle version and using runtime libraries from that version will run against Oracle Database 10g without changes. This means the server migration to Oracle Database 10g can be done first and client-side applications can be migrated later, when it is convenient or at the point where you want the application to exploit features that are new in Oracle Database 10g.

This flexibility is somewhat reduced on z/OS (compared to some other Oracle platforms) due to significant improvements in Oracle's integration with z/OS in the previous two versions. Depending on the release you are migrating from and on what facilities your applications use, you may need to rebuild or make external (for example, JCL) changes in certain applications in order to run them with Oracle Database 10g client-side libraries and components. In any case, you should not attempt to migrate client-side components to Oracle Database 10g before the target Oracle servers have been migrated.

7.2 Migrating from Oracle8i

Client applications built with and using libraries from Oracle8i OSDI will continue to work without changes when run against Oracle Database 10g. They must continue to use the stubs, CMDLOAD and MESG data sets, or (in the case of POSIX shell applications) the ORACLE_HOME structures from the Oracle8i OSDI distribution. You cannot mix these applications with Oracle9i or Oracle Database 10g applications in a multi-task or multi-enclave design (where they would share the same STEPLIB and/or ORA$LIB as Oracle9i or Oracle Database 10g programs). Be aware that all non-POSIX Oracle8i clients in z/OS use the OSDI Network service when accessing a remote Oracle server. You must continue to run an Oracle8i OSDI Network service until all such clients have been migrated.

7.2.1 Migration Checklist

Migrating an Oracle8i client application to use Oracle Database 10g libraries and infrastructure requires the following:

Support for Oracle SQL*Net V1-style connection strings was removed starting with Oracle9i. If you have applications that rely on such strings, they must be changed to one of the connection specification mechanisms described in Chapter 3, "Oracle Net and Server Connections on z/OS". SQL*Net V1-style connection strings can be recognized by the full colon following the driver identifier, which was usually a single letter or digit. An example (including the Oracle userid and password) is as follows:
```
scott/tiger@z:ora3
```
Several different driver identifiers were used on OS/390, including M, F, W, and Z for cross-memory operation and T for TCP/IP. This notation can appear in JCL or scripts (for example, in a tool or utility parameter), in an input file, or in precompiler or OCI program source code.
Applications that use an Oracle8i Net PROTOCOL=XM address descriptor, either directly, in a tnsnames file, as part of Access Manager configuration, or in a TWO_TASK environment variable, may require changes to the XM address data. Refer to Chapter 3 for details on the PROTOCOL=XM address.
Net PROTOCOL=IXCF is no longer supported as of Oracle9i. Comparable capability is provided by routing TCP/IP over the cluster interconnect and using PROTOCOL=TCP. Client applications using PROTOCOL=IXCF must be changed to use PROTOCOL=TCP.
Starting with Oracle9i, only IBM Language Environment-conforming compilers are supported for batch, TSO, and POSIX precompiler and OCI applications. If your application currently is compiled with a non-LE compiler, you must recompile it with an LE compiler currently supported by IBM. Re-precompiling of Pro*C, Pro*COBOL, or Pro*PL/I applications is recommended but not required. Refer to Chapter 6, "Developing Oracle Applications to Run on z/OS" for details on precompiling and compiling for Oracle Database 10g.
Starting with Oracle9i, Oracle's own C runtime library is replaced by IBM Language Environment for runtime services. Backward compatibility is provided for some (but not all) Oracle runtime features, particularly filespec notation. The compatibility is mostly optional but it is enabled by default. Refer to the section "Oracle C Runtime Compatibility" for additional information. If your application uses an Oracle runtime feature for which backward compatibility is not provided, or if you disable the backward compatibility altogether, your application must be changed to use comparable LE facilities.
Precompiler and OCI applications from Oracle8i must be relinked or rebound to pick up the Oracle Database 10g linking stub before they can run with the Oracle Database 10g CMDLOAD and MESG data sets. Refer to Chapter 6 for details on the stubs and on linking or binding procedures.
For applications that run under CICS TS or IMS TM, the Oracle Database 10g version of the corresponding Access Manager must be installed and configured. Contact your CICS or IMS administrator if you are unsure about this.
For applications that run in TSO or batch, you must change to Oracle Database 10g runtime services and libraries and ensure that IBM LE runtime is available. In most cases this involves changing JOBLIB/STEPLIB and ORA$LIB DD statements or allocations to refer to the Oracle Database 10g versions of these data sets. Refer to Chapter 2 for details on Oracle client runtime requirements.
For applications that run in a POSIX shell, ORACLE_HOME should be changed to refer to the Oracle Database 10g ORACLE_HOME directory, and corresponding changes must be made to environment variables such as PATH and LIBPATH.
Starting with Oracle9i, TSO, Access Managers, and batch clients connecting to remote Oracle servers interact directly with the z/OS TCP/IP protocol implementation instead of going through the OSDI Network service. (POSIX shell clients already do this in Oracle8i.) IBM's TCP/IP implementation requires POSIX "dubbing" of a program that is not already a POSIX process. The z/OS userid associated with a batch job, CICS TS or IMS TM started task or jobname, or TSO session that connects to a remote Oracle server must be capable of being dubbed. Consult your z/OS system or security administrator if you are unsure about meeting this requirement.
Be sure to read the considerations covered in the section "Migrating from Oracle9i"

7.3 Migrating from Oracle9i

Applications that were built under Oracle9i will continue to work when run against an Oracle Database 10g server when using the Oracle9i runtime components (such as CMDLOAD and MESG data sets and ORACLE_HOME). In addition, Oracle9i applications will run unmodified using the Oracle Database 10g runtime components. This simplifies migration and is useful in certain situations where multiple programs (possibly mixed Oracle9i and Oracle Database 10g programs) must share one set of runtime components.

There are, however, some significant changes in the z/OS Oracle client-side implementation in Oracle Database 10g. Most changes are internal improvements with little or no external manifestation, but some are things you may want to exploit and a few are external behavior changes that could impact existing jobs, scripts, or procedures. Read each of the following sections to determine if there are changes that could affect your applications.

7.3.1 Normalized File Access

In Oracle9i, the non-POSIX and POSIX versions of Oracle's client-side programs on z/OS (including tools and utilities as well as the program interface code LIBCLNTS) were merged so that the same program was used in both environments. However, most of the client components that could use either HFS files or z/OS data sets remained predisposed to one or the other type based on the LE POSIX setting: when POSIX was OFF, filespecs were assumed to be data sets; when POSIX was ON, they were assumed to be HFS files.

Starting in Oracle Database 10g, client-side file access is mostly "agnostic" as to the POSIX setting, allowing data sets to be used in a POSIX application and HFS files to be used in non-POSIX applications. The syntax of a filespec indicates which type of file is being used and the POSIX setting is consulted only when a filespec is ambiguous, meaning not self-identifying as to type. Refer to Chapter 2 for details on filespec syntax and related processing.

7.3.2 Global Environment File

Oracle Database 10g for z/OS introduces a new feature, the global environment file. This feature permits the installation to set specific system-wide defaults for environment variables in Oracle client programs running in TSO or batch (POSIX OFF). The defaults can be overridden using a local environment variable file specified using the ORA$ENV DD statement. Consult with your system administrator to determine if the global environment file is configured on your system. For additional information refer to the section "Environment Variables".

7.3.3 Use of LE Exit CEEBXITA

Starting with Oracle Database 10g, the Oracle linking stubs for TSO, batch, and POSIX applications contain an IBM Language Environment exit, CEEBXITA. When linked into your application this exit allows Oracle code to "clean up" Oracle-specific resources when the application terminates. This design is necessary to allow execution of multiple Oracle-accessing applications (your own applications or Oracle tools or utilities) on a single z/OS task (TCB). With this exit, Oracle supports both nested LE enclaves and serial (successive) execution of Oracle-accessing programs from a single z/OS task. Oracle's use of this exit means that no installation-specific CEEBXITA exit can be used with an Oracle Precompiler or OCI application on z/OS.

A similar version of this exit was provided for Oracle9i in the fix for Oracle bug 3431417. If your Oracle9i application was linked with a version of the stub that includes this fix, the application can participate in a multiple enclave task application on z/OS. Refer to the section "Application Design Considerations" for additional details.

7.3.4 Oracle Runtime Compatibility

Starting with Oracle Database 10g, most of the backward compatibility for the Oracle C runtime library is optional, controlled by the ORA_RTL_COMPAT environment variable. This means the backward compatibility can be disabled, causing filespecs that begin with "/dd/" or "/dsn/" to be treated as HFS files (as their syntax indicates).

A few adjustments were made in Oracle Database 10g to the logic that supports backward compatibility for Oracle runtime C standard file redirection operators in non-POSIX batch and TSO environments. Unlike other aspects of Oracle runtime backward compatibility, this feature cannot be disabled with an environment variable.

Refer to "Oracle C Runtime Compatibility" for additional details.

7.3.5 SYSOUT Filespec in Clients

In Oracle Database 10g, a filespec providing explicit designation of JES spool output is now usable for most client-side output files. This provides an alternative to DD filespecs for creating spooled output and may be particularly useful in POSIX shell applications (where supplying DD statements is awkward). Refer to the section ""File Types and Filespec Syntax" for additional details.

7.3.6 SQL*Loader Changes

Significant internal changes were made to the SQL*Loader utility in Oracle Database 10g. Mostly these concern the defaulting and processing of the various files SQL*Loader reads or writes in non-POSIX environments. Some of the changes cause external behavior differences and may affect existing SQL*Loader batch jobs or TSO procedures. Review the following sections before you attempt to migrate existing SQL*Loader jobs or scripts to use SQL*Loader from Oracle Database 10g.

7.3.6.1 Interpretation of DDN Keywords

In previous Oracle releases, filespecs supplied with the control file keywords INDDN, BADDN, and DISCARDDN were treated exactly the same as INFILE, BADFILE, and DISCARDFILE respectively. In Oracle Database 10g, the values supplied with INDDN, BADDN, and DISCARDDN are treated as 1-character to 8-character DD names; they cannot specify a data set or HFS file name nor can they include a DD:, //DD:, or /DD/ prefix. Existing loader jobs or scripts that use INDDN, BADDN, or DISCARDDN must be modified for SQL*Loader in Oracle Database 10g. If the associated file is in fact a DD, remove any DD:, //DD:, or /DD/ prefix from the supplied value. If the value is meant to be processed as a data set or HFS file name, change the control file keyword to INFILE, BADFILE, or DISCARDFILE.

7.3.6.2 Default Filespecs for DD-type Data Files

In previous Oracle releases, when multiple input data files were specified as DD-type files in a single load, if corresponding bad and discard files were not specified they would default to the same DD names (BAD and DISCARD respectively) for every data file. This caused rejected and discarded rows from all data files to be written to the same DDs. In Oracle Database 10g, the defaults for these files (when the corresponding data file is a DD type) are //DD:BAD and //DD:DISCARD for the first data file, //DD:BAD2 and //DD:DISCAR2 for the second, and so on for up to 99 data files.

7.3.6.3 Default Filespecs for Data Set Name Files

When a loader data file is specified as a z/OS data set name filespec in Oracle Database 10g, defaults for the bad and discard files are constructed using the high-level qualifier (if any) of the control file, the "base" portion (minus any high level qualifier) of the data file data set name, and the extension suffixes BAD and DSC. This matches the default construction of POSIX HFS filenames and reflects the notion that the bad and discard outputs of the load are associated with the load application (its control file) rather than with the input data file. In previous releases, construction of these data set names did not involve the control file high level qualifier.

7.3.6.4 Default Bad/Discard DCB attributes

In Oracle Database 10g, when the bad and discard files are data sets without explicitly-supplied DCB attributes (either coded on the DD statement or, for an existing data set, already present in the VTOC), DCB attributes are derived automatically based on the attributes of the associated data file. If these files do have specific DCB attributes, SQL*Loader checks them to ensure that the logical record length is the same or greater than that of the data file and fails the load if not. In previous releases, DCB attributes for the bad and discard files were not defaulted or checked based on the attributes of the data file.

Refer to the section "SQL*Loader" for z/OS-specific information on Oracle Database 10g SQL*Loader.