11
Migration Considerations

This chapter describes usage considerations when migrating from an earlier Oracle8i database with MPM or earlier OSI database to this release of the Oracle9i database.

The following topics are included:

Overview

Oracle9i database server users on OS/390 communicate with the OSDI database service address space using OS/390 cross memory services. This facility allows both data and program operation to cross address space boundaries in a secure and controlled manner.

OSDI provides a cross-memory protocol for connecting local Oracle database server clients to OSDI-managed database instances. The protocol is based on Oracle Net architecture. If migrating from MPM, this protocol replaces the SQL*Net V1-based protocols that are used by MPM. You cannot connect to an OSDI-managed server using the MPM protocol, and you cannot connect to an MPM-based Oracle instance using the OSDI protocol.

OS/390 Language Environment

In this release all Oracle clients use the IBM Language Environment for C program runtime services. This includes all Oracle tool, utilities, Access Managers and the Oracle client code used by customer written applications built using the Oracle precompilers or OCI interface.

The Oracle client code previously provided with the ORADRV load module, is now provided in LIBCLNTS. LIBCLNTS is a DLL module in CMDLOAD and must be made available to tools, utilities, Access Managers, and customer written applications either:

by placing CMDLOAD in the STEPLIB DD concatenation in the jcl, or
by LIBCLNTS copied into SYS1.PALIB so that one copy is shared across all uses.

The IBM Language Environment runtime library, SYS1.SCEERUN, must be made available either in the STEPLIB DD concatenation in the jcl, or by placing SYS1.SCEERUN in the LNKLSTxx member of SYS1.PARMLIB.

TOS/Batch and USS customer applications must be compiled using a Language Environment conforming compiler. See the Release Notes, "Additional Software Requirements" section for supported compilers. With migration to the use of the LIBCLNTS DLL, customer applications must be linked with a new stub as described in "Linking Your Program" in the Oracle Precompilers chapter of this book. For migration, existing applications using an OSDI version of CMDLOAD can access this version of the database as long as they continue to use the existing CMDLOAD and MSEG datasets. Existing applications built using an MPM version of CMDLOAD must be recompiled if compiled with a non-conforming Language Environment compiler and/or be relinked with the new stub.

Oracle tools and utilities now support file specifications and redirection specifications according to Language Environment syntax. See the IBM C/C++ Programming guide section on "Opening Files" and "Using Redirection Symbols" for more information. For backward compatibility Oracle Runtime file specification is supported as described in the " Oracle9i Utilities and OS/390 Files" chapter of this book. See also the appropriate chapter for the specific product being used. A previous OSDI version of tools such as SQL*Plus can access this version of the database as long as they continue to use the CMDLOAD and MESG datasets provided with that release. Prior versions of the tools provided in an MPM release will not work with this version of the database.

OS/390 Cross Memory Support

OS/390 cross memory support is provided for Oracle clients as described in the following sections.

Cross Memory Support

Oracle9i's cross memory mechanism is based on Oracle Net and supports local access to Oracle database instances by its SID using the ORA@sid DD statement, local tnsnames connect string (either explicitly or using the TWO_TASK environment variable) or with the ORACLE_SID environment variable. See "Enabling OS/390 Local Client Access" for details.

Applications that utilize an ORA@ssn DD statement to access an MPM-based Oracle database would require only minor JCL change to access an OSDI-managed database instance with a different SID. In other cases where other MPM specific local connection mechanisms are used, applications will need to be changed to use one of the Oracle9i supported mechanisms.

Support for the old SQL*Net V1-style connection strings (M:, F:, W:, and Z:) and for the CONNSTR environment variable has been removed for the Oracle9i and subsequent releases; therefore, a SQL*Net V1-style connection string will produce an error during the connect attempt. Any CONNSTR setting will be ignored, and other mechanisms that are lower in the precedence list will be attempted. You will need to convert scripts or applications that use either of these mechanisms to one of the others before you upgrade to Oracle9i.

MPM Compatibility

With MPM, a TSO or batch Oracle application has four different ways to specify a local target instance. They are, in descending order of precedence:

A SQL*Net V1-style connection string following an "@" character that is appended to the userid and password supplied to an Oracle connect call. This string is of the general form:
```
x:ssn
```
where x is the letter M, F, W, or Z and ssn is the 1-character to 4-character subsystem name of the target MPM. Additional protocol parameters following ssn such as buffer size or NOSTAX are not supported under OSDI. Note that it is the colon character that distinguishes this connection string from a Oracle Net tnsname-type specification.
A CONNSTR environment variable containing a connection string of the form just described in specification 1. Environment variables are supplied in a sequential file that is specified by an ORA$ENV DD statement in the batch job or is allocated to the TSO session.
A DD statement in a batch job (or equivalent TSO allocation) of the form:
```
//ORA@ssn DD DUMMY
```
where ssn is the 1-character to 4-character subsystem name of the target MPM Oracle instance.
None of the above. By default, the subsystem name MPMT is targeted.

Oracle9i only provides compatibility support for the ORA@ssn DD (as in method 3 above). Any applications that rely on the other mechanisms to specify a target instance will have to be changed to access an Oracle9i server.

These connection short-cut mechanisms all specify an MPM subsystem name. With OSDI, a single subsystem can support many Oracle instances, so the "subsystem name" that is specified by the supported mechanism is not used as such by OSDI. Instead, it is used as a SID (service identification). The SID is an identifier that is specified on the OSDI DEFINE SERVICE command. Every service must have a SID that is unique throughout the OS/390 system. Even services that are defined in different OSDI subsystems cannot have the same SID if they are on the same OS/390 system.

When you use the ORA@ssn DD described above with an OSDI-enabled client, OSDI attempts to connect to the service whose SID matches the 1-character to 4-character string that was treated as a subsystem name by MPM. OSDI SIDs can be up to 8 characters long, but if you want to exploit this client compatibility feature, then you must use a SID that matches the subsystem name of your old MPM Oracle instance, which means that the SID must be 4 characters or less. If you do not specify a SID in the DEFINE SERVICE command, then the SID name defaults to the service name. You may want to specify the SID (matching your old MPM subsystem name) so that you can use a longer, more descriptive name for the service.

Henceforth, we will refer to the DD statement mechanism for specifying an instance as "ORA@sid" instead of "ORA@ssn".

TNSNAMES Connect Descriptors

All of the mechanisms that OS/390 clients can use to specify connections, both local and remote, are listed below in descending precedence order. Aspects of each were discussed in the prior sections as well as Chapter 2, " Using the OS/390 Database Instance".

A connection string following an "@" appended to the userid and password supplied on an Oracle connect request. This can be a tnsname-style name for TNSNAMES lookup, or a complete Oracle Net address string.
A DD statement (or TSO allocation equivalent) of the form:
```
//ORA@sid  DD DUMMY
```
where sid matches the SID of a local OSDI-managed instance
A TWO_TASK environment variable whose value is a tnsname-style name, or a complete Oracle Net address string.
An ORACLE_SID environment variable whose value matches the SID of a local OSDI-managed instance.

If none of the above four mechanisms is specified, then the client connection attempt will fail. There is no "default instance" mechanism.

Database Links

Cross-memory database links (in either direction) between MPM and OSDI instances are not supported. If you have a requirement for such distributed access, then you will need to use a network protocol (that is, TCP/IP) instead of cross-memory access. Doing this requires running both OSDI Oracle Net and TNS with distinct endpoints for the chosen protocol.

IXCF Support

IXCF is no longer supported as a separate Oracle Net for OS/390 protocol. IXCF can be supported via IBM TCP/IP in which case, Oracle Net IBM TCP/IP protocol can be used. Consult with your Oracle for OS/390 administrator regarding IXCF support with IBM TCP for your installation.

Remote Clients

All net applications now open their own tcp/ip sockets; that is, they no longer make use of the Net address for communications. Instead, each net application makes direct use of OS/390 UNIX System Services and therefore requires an OS/390 UNIX security context, also known as an OMVS segment. Each user that invokes tcp/ip functionality must have an MVS segment if an installation is not using a default OMVS segment.

11 Migration Considerations