8
Oracle Call Interface

TSO Programs

To use an OCI application under TSO (by the CALL command or as a command processor), ensure you call OCISessionEnd or OCIServerDetach before the program ends.  Otherwise, an abend with completion code A03 occurs when the program attempts to end.  The OCISessionEnd or OCIServerDetach call ensures Oracle cleanup actions are taken, in particular the removal of an OS/390 subtask that is used to handle TSO session attention signals.

The IBM TSO TEST processor does not support cross memory mode operations. Because Oracle applications perform all database operations in cross memory mode, you cannot escape to TSO TEST when an Oracle application is performing operations within the database.

CICS Programs

Oracle OCI calls are not supported by Oracle Access Manager for CICS.

IMS TM Programs

Oracle Access Manager for IMS TM allows OCI programs written in C programming language and running in an IMS MPP, IFP, or BMP region to access an Oracle9i database server anywhere in your network.  Programs can access and update IMS, DB2, and Oracle9i data within a single synchronized transaction.

From an IMS TM perspective, transaction programs accessing Oracle9i databases have no special requirements.  The normal IMS calls for input and output messages processing, data access, and synchronization perform as if the Oracle9i system is not being used.

From an Oracle9i perspective, OCI applications running under IMS TM are no different from other OCI applications.  They contain OCI function calls that are passed to the Oracle9i database server as the program runs.  When using OCI programs in an IMS TM transaction, there are some special considerations.

Long Name Support

Unlike previous releases of the OS/390 implementation of OCI, this release relies on and exploits native support for long, mixed-case function names.  So, when compiling an OCI application, the LONGNAME compiler option must be specified. The object produced will cause the binder to create a PM3 type program object.  If this is not appropriate, another method is available.  See Appendix A, "API Short Name Support".

Callback Restriction

Applications using OCI functions that make use of callbacks must be compiled with the DLL option.

UNIX System Services

The Oracle Call Interface may be used in C programs developed for the USS environment.  Refer to Chapter 4, " Accessing Oracle9i Under USS" for more information.

To build one of the sample OCI programs, cd to the rdbms/demo directory and issue the following make command:

make -f demo_rdbms.mk build EXE=demo OBJS="demo.o ..."

For example:

make -f demo_rdbms.mk build EXE=oci02 OBJS=oci02.o 

To build all of the sample OCI programs, cd to the rdbms/demo directory and issue the following make command:

make -f demo_rdbms.mk demos

Sample Link JCL

Following is an example of JCL that might be used for linking:

//LKED     EXEC PGM=IEWL,

//         PARM='XREF,LET,LIST,DYNAM=DLL'

//SYSPRINT DD  SYSOUT=* 

//SYSLIB   DD  DSN=SYS1.SCEELKED,DISP=SHR

//         DD  *- Refer to Note 1 -*

//         DD  SYS.SCEELKED

//SQLLIB   DD  DSN=oran.orav.SQLLIB,DISP=SHR 

//SYSLMOD  DD  *- Refer to Note 2 -*

//TEXT DD  *- Refer to Note 3 -*

//SYSUT1   DD  UNIT=VIO

//SYSLIN   DD  *

INCLUDE SQLLIB(stub) *- Refer to Note 4 -*

INCLUDE TEXT

*- Refer to Note 5 -*

/*

Batch and TSO Programs

When linking an OCI program to run in batch or TSO, you must add the following linkage editor control statement to the SYSLIN DD statement:

INCLUDE SYSLIB(ORASTBL)

The ORASTBL stub provides long name support for OCI functions and support for SQL functions.

If there are external references for symbols whose names begin with the letter O, then the linkage editor cannot find one or more of the function calls in your application.  Ensure ORASTBL is included in your linkedit.  The ORASTBL stub resolves any calls in your code.  If ORASTBL is correctly included, then the problem might be caused by a missing entry point to the stub routine.  You can contact Oracle Support Services for additional assistance.

IMS TM Programs

When linking a program to run under IMS TM, add the following linkage editor control statements to the SYSLIN DD statement:

INCLUDE SQLLIB(AMILS)

INCLUDE SQLLIB(lit-module)

The AMILS module must be the version that is compatible with this release if Oracle9i OCI is used.

The lit-module statement refers to a customer-generated language interface module.  The IMS TM system administrator generates and names the statement according to the installation's standards.

Do not include references to ORASTBL, ORASTUBS, or ORACSTUB.

If there are external references for symbols whose names begin with the letter O, then the linkage editor cannot find one or more of the function calls in your application.  Ensure AMILS is included in your linkedit.  The AMILS stub resolves any calls in your code.  If AMILS is correctly included, then the problem might be caused by a missing entry point to the stub routine.  You can contact Oracle Support Services for additional assistance.

Batch and TSO Programs

The requirement for OCI programs in batch and TSO environments is the same as Precompiler programs.  Refer to the "Running Your Program".

IMS TM Programs

Normal IMS TM practices for defining your program to IMS TM are followed for OCI programs.  IMS TM programs access a shared copy of the full OCI interface that must be configured and available before your program begins running.  If the interface is not available, then you receive error message 3042 from IMS TM.  You must contact your IMS TM system administrator to have this condition corrected.

OCI Interface to Publish/Subscribe

The OCI interface to Oracle's publish/subscribe features allows an application to register a callback function that is driven when there are queue data or trigger events to process.  This feature is supported with Oracle for OS/390 server as long as the client executes in a multi-threaded environment and there is TCP connectivity between the server and the client.  This includes local OS/390 clients running under USS as well as remote clients on any multi-threaded platform.  It excludes native TSO/batch and IMS clients at this time

The TCP connectivity requirement does not mean that the client must be connected to the server via Oracle Net PROTOCOL=TCP.  The client can be connected via any protocol (including Oracle Net PROTOCOL=XM for a local USS client) and in fact the client can disconnect its session from the database after setting up the callback without affecting the callback.  A special background process in the server (EMON) opens a TCP connection to the client thread that gets created when OCISubscriptionRegister is called. TCP communication from the server to the client thread ultimately drives the callback functions.

See the OCI Programmer's Guide for further details on the OCI interface to Oracle's publish/subscribe facility.