Oracle Call Interface Programmer's Guide, Volumes 1 & 2
Release 8.0

A58234-01

Library

Product

Contents

Index

Prev Next

A
Upgrading Release 7.x OCI Applications to Release 8.0

This appendix covers issues of compatibility between Oracle7 and Oracle8 OCI applications and servers. It also discusses issues involved in upgrading applications from the 7.x OCI to the 8.0 OCI.

The appendix contains the following sections:

Compatibility and Upgrade Overview

Release 8.0 of the Oracle server provides support for applications written with either the 7.x OCI and the 8.0 OCI.

The remaining sections of this chapter discuss changes in the OCI library routines, issues concerning compatibility between different versions of the OCI and server, as well as issues involved in migrating an application from the release 7.x OCI to the release 8.0 OCI.

Obsolescent OCI Routines

Release 8.0 of the Oracle Call Interface contains an entirely new set of functions which were not available in release 7.3. The earlier calls are still available, but Oracle recommends that existing applications start using the new calls to improve performance and provide increased functionality.

Table A-1 lists the 7.x OCI calls with their release 8.0 equivalents. For more information about the 8.0 OCI calls, see the earlier chapters of this volume. For more information about the 7.x calls, see the Programmer's Guide to the Oracle Call Interface, Release 7.3. These calls are obsolescent, meaning that Oracle may not support these calls in future versions of the OCI.

Note: In many cases the new OCI routines do not map directly onto the 7.x routines, so it may not be possible to simply replace one function call and parameter list with another. Additional program logic may be required before or after the new call is made. See the remaining chapters of this guide for more information.

Table A-1 Obsolescent OCI Routines
7.x OCI Routine   Equivalent or Similar 8.0 OCI Routine  

obindps(), obndra(), obndrn(), obndrv()  

OCIBindByName(), OCIBindByPos() (Note: additional bind calls may be necessary for some data types)  

obreak()  

OCIBreak()  

ocan()  

none  

oclose()  

Note: cursors are not used in Release 8.0  

ocof(), ocon()  

OCIStmtExecute() in OCI_COMMIT_ON_SUCCESS mode  

ocom()  

OCITransCommit()  

odefin(), odefinps()  

OCIDefineByPos() (Note: additional define calls may be necessary for some data types)  

odescr()  

Note: schema objects are described with OCIDescribeAny(). A describe, as used in release 7.x , will most often be done by calling OCIAttrGet() on the statement handle after SQL statement execution.  

odessp()  

OCIDescribeAny()  

oerhms()  

OCIErrorGet()  

oexec(), oexn()  

OCIStmtExecute() (or ociflsh())  

oexfet()  

OCIStmtExecute(), OCIStmtFetch() (Note: result set rows can be implicitly prefetched)  

ofen(), ofetch()  

OCIStmtFetch()  

oflng()  

none  

ogetpi()  

OCIStmtGetPieceInfo()  

olog()  

OCISvcCtxLogon()  

ologof()  

OCISvcCtxLogoff()  

onbclr(), onbset(), onbtst()  

Note: non-blocking mode can be set or checked by calling OCIAttrSet() or OCIAttrGet() on the server context handle or service context handle  

oopen()  

Note: cursors are not used in Release 8.0  

oopt()  

none  

oparse()  

Note: there is no explicit parse step in the 8.0 OCI.  

opinit()  

OCIInitialize()  

orol()  

OCITransRollback()  

osetpi()  

OCIStmtSetPieceInfo()  

sqlld2()  

none  

sqllda()  

none  

odsc()  

Note: see odescr() above  

oermsg()  

OCIErrorGet()  

olon()  

OCISvcCtxLogon()  

orlon()  

OCISvcCtxLogon()  

oname()  

Note: see odescr() above  

osql3()  

Note: see oparse() above  

See Also: For information about the additional functionality provided by new release 8.0 functions not listed here, see the remaining chapters of this guide.

Obsolete OCI Routines

Some OCI routines that were available in previous versions of the OCI are now obsolete, meaning that they are not supported for Release 8.0. They are listed in Table A-2

Table A-2 Obsolete OCI Routines
Obsolete OCI Routine   Equivalent or Similar 8.0 OCI Routine  

obind()  

OCIBindByName(), OCIBindByPos() (Note: additional bind calls may be necessary for some data types)  

obindn()  

OCIBindByName(), OCIBindByPos() (Note: additional bind calls may be necessary for some data types)  

odfinn()  

OCIDefineByPos() (Note: additional define calls may be necessary for some data types)  

odsrbn()  

Note: see odescr() in Table A-1  

ologon()  

OCISvcCtxLogon()  

osql()  

Note: see oparse() Table A-1  

:

Compatibility

This section addresses compatibility between different versions of the OCI and Oracle server.

7.x Applications

Existing 7.x applications with no new release 8.0 OCI calls have two choices:

In either case, the application will work against both Oracle7 and Oracle8 servers. The application will not be able to use Oracle8's object features, and will not get any of the performance or scalability benefits provided by the Oracle8 OCI.

8.0 Applications

New applications written completely in the release 8.0 OCI will work seamlessly against both Oracle7 and Oracle8 servers with the following exceptions:

Upgrading

Programmers who wish to incorporate new release 8.0 functionality into existing OCI applications have two options:

This manual, along with Volume I, should provide the information necessary to rewrite an existing application to use only new OCI calls.

Adding 8.0 Calls to 7.x Applications

The following guidelines apply to programmers who want to incorporate new Oracle8 datatypes and features by using new OCI calls, while keeping 7.x calls for some operations:

This approach allows an application to use a single connection, but two different APIs, to accomplish different tasks.

You can mix and match OCI 7.x and OCI 8.0 calls within a transaction, but not within a statement. So you can execute one SQL or PL/SQL statement with OCI 7.x calls and the next SQL or PL/SQL statement within that transaction with OCI 8.0 calls.

Warning: You can not open a cursor, and parse with OCI 7.x calls and then execute the statement with OCI 8.0 calls.

Application Linking Issues

This section discusses issues related to application linking, including the use of non-deferred linking and single-task linking with various OCI versions.

Non-deferred linking

Application developers are cautioned that Oracle plans to desupport non-deferred mode linking beginning with the release of Oracle9 (it will continue to be supported with all the releases of Oracle8). Recognizing these plans, application developers should no longer use non-deferred mode linking in developing new applications. Version 7.3 of the OCI supports two linking modes:

  1. Non-deferred linking: The Oracle6 OCI (client) only supported non-deferred linking which meant that for each SQL statement, a parse, a bind and a define call were each executed separately with individual round trips between the client and the server. This significantly increased network traffic between the client and the server and reduced both the performance and scalability of OCI applications.
  2. Deferred linking: Unlike the Oracle6 OCI, the Oracle7 OCI supports both non-deferred linking and deferred linking. Deferred mode linking essentially defers the bind and define steps until the statement executes - that is it automatically bundles and defers the bind and define calls to execution time. Further, when the application is linked with deferred mode and a special parsing call is used (the OPARSE call with the DEFFLG set to a non-zero value), even the parse call can be deferred to execution time. Note that deferred mode linking does not depend on the specific OCI calls that the application uses, only on the link option that is selected.

Deferred mode linking therefore significantly reduces the number of round trips between the client and the server and as a result improves the performance and scalability of OCI applications. The default behavior of Oracle7 OCI connected to the Oracle7 server is deferred mode linking. However, Oracle7 OCI also supports non-deferred linking by setting specific link time options.

Further, Oracle8 OCI has two types of calls: first, all the Oracle7 OCI calls are supported with Oracle8 OCI i.e. they will work with a Oracle8 OCI client by relinking the version 8 OCI libraries. Second, there are additional Oracle8-specific OCI calls. The default mode with the first type of calls continues to be deferred mode linking; however, non-deferred mode linking is supported for these calls through all releases of Oracle8 by setting link time options. However, Oracle8-specific calls use a different paradigm and as a result non-deferred mode linking is not necessary.

The various combinations of client-side libraries and server with which non-deferred linking is currently supported are summarized in the following table:

Table A-4 Supported Linking Modes for Various Client and Server Versions
Client   Oracle6 OCI   Oracle7 OCI   Oracle8 OCI

(7.x calls)  

Oracle8 OCI

(8.0 calls)  

Oracle9 OCI  
Server  

Oracle9  

Not supported  

Default: deferred
Non-deferred supported  

Default: deferred
Non-deferred supported  

Not supported  

Not supported  

Oracle8  

Not supported  

Default: deferred
Non-deferred supported  

Default: deferred
Non-deferred supported  

Not supported  

Not supported  

Oracle7  

Non-deferred mode only  

Default: deferred
Non-deferred supported  

Default: deferred
Non-deferred supported  

Not supported  

Not supported  

Oracle6  

Non-deferred mode only  

Default: deferred
Non-deferred supported  

Not supported  

Not supported  

Not supported  

Oracle will continue to support deferred-mode linking with all the releases of Oracle8 (all 8.* releases). This has the following implications:

Applications using Oracle6 OCI libraries

Since the Oracle6 OCI library is not supported against the Oracle8 database, applications using the Oracle6 OCI library cannot be run against an Oracle8 database.

Applications using Oracle7 OCI libraries

Applications using Oracle7 OCI libraries can run in two configurations against an Oracle8 database:

  1. They can be run with Oracle7 OCI libraries against an Oracle8 database in non-deferred mode provided link time options are set appropriately.
  2. They can also be relinked with the Oracle8 OCI libraries and run in non-deferred mode provided link time options are set appropriately. Oracle will support the first configuration through all the releases of Oracle8. However, the second configuration will not be supported in Oracle9. Therefore, applications that require non-deferred linking will not be able to upgrade to Oracle9 client-side libraries.

Applications using Oracle8 OCI libraries

Applications using Oracle8- specific OCI calls, such as those used to access Oracle8's object types, do not need to use non-deferred mode linking since the Oracle8 OCI uses a different paradigm. Applications using only Oracle7 OCI calls will be able to use non-deferred mode linking but only through release 8.1

Single-task linking

Single-task linking is a feature used by a limited number of Oracle's customers, primarily on the OpenVMS platform. Some Oracle platforms support single-task linking, others no longer support it. Application developers are cautioned that Oracle will desupport single task on ALL platforms beginning with the first server release after Oracle8. Oracle will continue to support single-task linking for all Oracle8.x releases on those platforms that do support it today. Application developers are referred to the product-line specific documentation to determine whether or not their platform supports single-task linking today.

With single-task linking, Oracle supports two configurations to link Oracle products and user-written applications against the Oracle database:

  1. Single-task linking: In this case, applications are directly linked against the Oracle shareable image making single-task connection to Oracle
  2. Two-task linking: In this case, applications linked in a standalone configuration can only connect to Oracle using Net8's two task drivers such as Net8 DECnet or Net8 VMS Mailbox on the OpenVMS platform. This is the typical configuration used in the large majority of client-server applications. With two task linking applications and tools connect with the Oracle7 database through a programmatic interface that creates a shadow process for each user process. This shadow process runs a copy of the Oracle shareable image on behalf of the user process using Net8 protocols to communicate between the user and shadow processes. Therefore, with this interface, user routines that invoke the Oracle7 Server functions run as one process or task, and the Oracle7 routines that execute these functions run as the second task.

Oracle will continue to support single-task linking with all the releases of Oracle8 (all 8.* releases) but will desupport it beginning with the first release after Oracle8. Application developers who would like to use single-task linking to run their applications will not be able to do so against the first server release after Oracle8.




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index