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:

do not relink the application
relink with the new 8.0 OCI library

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:

Against Oracle7 servers, none of Oracle8's object features are supported, and the following datatypes are not supported:
- SQLT_NTY - named data type
- SQLT_REF - reference to named data type in host language representation.
- SQLT_CLOB - a character LOB data type.
- SQLT_BLOB - a binary LOB data type.
- SQLT_NCLOB - a national character set LOB data type.
- SQLT_NCHAR - fixed or varying national character set datatype.
- SQLT_BFILE - a binary FILE LOB data type.
- SQLT_RSET - result set data type.

Against Oracle7 Servers, the following calls or features are not supported, or are supported with restrictions:

Table A-3 8.0 OCI Restrictions When Running Against Oracle7 Servers

Function	Restrictions
OCIBindObject()	not supported
OCIPasswordChange()	not supported
OCIDefineObject()	not supported
OCIDescribeAny()	only supports description of select lists or stored procedures
OCIErrorGet()	only a subset of Oracle error codes can be returned
OCIStmtFetch()	prefetching options not supported
OCILob*() calls	LOB/FILE calls are not supported
OCIAttrSet()	setting NCHAR attributes not supported
OCIAttrGet()	getting NCHAR attributes not supported

Upgrading

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

Completely rewrite the application to use only new OCI calls
Incorporate new release 8.0 OCI calls into the application, while still using 7.x calls for some operations.

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:

Change the existing logon to use OCILogon instead of olog() (or other logon call). The service context handle can be used with new OCI calls or can be converted into a Lda_Def to be used with 7.x OCI calls.
Note: See the description of OCIServerAttach() on page 13-125 and the description of OCISessionBegin() on page 13-129 for information about the logon calls necessary for applications which are maintaining multiple sessions.
Once the server context handle has been initialized, it can be used with Oracle8 OCI calls.
To use Oracle7 OCI calls, convert the server context handle to an Lda_Def using OCISvcCtxToLda(), and pass the resulting Lda_Def to the 7.x calls.
Note: If there are multiple service contexts which share the same server handle, only one can be in Oracle7 mode at any time.
To begin using 8.0 calls again, the application must convert the Lda_Def back to a server context handle using OCILdaToSvcCtx().
The application may toggle between the Lda_Def and server context as often as necessary in the application.

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:

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.
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	Oracle6 OCI	Oracle7 OCI	Oracle8 OCI (7.x calls)	Oracle8 OCI (8.0 calls)	Oracle9 OCI
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:

They can be run with Oracle7 OCI libraries against an Oracle8 database in non-deferred mode provided link time options are set appropriately.
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:

Single-task linking: In this case, applications are directly linked against the Oracle shareable image making single-task connection to Oracle
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.

AUpgrading Release 7.x OCI Applications to Release 8.0