5
Using Oracle Precompilers and the Oracle Call Interface on Solaris 2.x

• Overview of Oracle Precompilers
• Pro*C/C++
• Pro*COBOL
• Pro*FORTRAN
• SQL*Module for Ada
• Oracle Call Interface
• Oracle Precompiler and Oracle Call Interface Linking and Makefiles
• Thread Support
• Static and Dynamic Linking with Oracle Libraries
• Using Signal Handlers
• XA Functionality

Overview of Oracle Precompilers

Oracle precompilers are application design tools used to combine SQL statements from an Oracle database with programs written in a high-level language. Oracle precompilers are compatible with ANSI SQL and are used to develop open, customized applications that run with Oracle8, or any other ANSI SQL DBMS.

Relinking Precompiler Executables

All precompiler executables are relinked using the makefile, $ORACLE_HOME/precomp/lib/ins_precomp.mk. The make command uses the following convention:

$ make -f ins_precomp.mk relink EXENAME=executable

This command will create the new executable in the $ORACLE_HOME/precomp/lib directory, and then move it to $ORACLE_HOME/bin. In order to create the new executable without it being moved to $ORACLE_HOME/bin, use the following command:

$ make -f ins_precomp.mk executable

where the name of the executable in respect of the product being used, can be determined from Table 5-1.

Table 5-1 Products and Their Corresponding Executable Names

For example, to relink the Pro*C/C++ executable, use the following command:

$ cd $ORACLE_HOME/precomp/lib
$ make -f ins_precomp.mk relink EXENAME=proc

Precompiler Configuration Files

There are six .cfg system configuration files in $ORACLE_HOME/precomp/admin. These are described in Table 5-2.

Table 5-2 System Configuration Files

Issues Common to All Precompilers

Uppercase to Lowercase Conversion

In languages other than C, your compiler converts an uppercase function or subprogram name to lowercase. This can cause "No such user exit" errors. In this case, verify that the function or subprogram name in your option file matches the case in the iapxtb table.

Vendor Debugger Programs

Precompilers and vendor-supplied debuggers may be incompatible. Oracle Corporation does not guarantee that a program run under a debugger will run the same way under an operating system.

Value of ireclen and oreclen

The ireclen and oreclen parameters do not have maximum values.

Supplemental Documentation

The following documents provide additional information about precompiler and interface features:

• Programmer's Guide to the Pro*C/C++ Precompiler
• Programmer's Guide to the Pro*COBOL Precompiler
• Pro*FORTRAN Supplement to Oracle Precompilers
• Programmer's Guide to the Oracle Call Interface
• Oracle8 Server Application Developer's Guide
• Programmer's Guide to SQL*Module for Ada

Pro*C/C++

For additional information regarding Pro*C/C++ release 8.0.4, see the README file, $ORACLE_HOME/precomp/doc/proc2/readme.doc.

Administering Pro*C/C++

System Configuration File

The system configuration file for Pro*C/C++ is $ORACLE_HOME/precomp/admin/pcscfg.cfg.

Using Pro*C/C++

Prior to using Pro*C/C++, verify that the correct version of the Operating System compiler is properly installed. The required version is documented in Chapter 1 of the Oracle8 Installation Guide for Sun SPARC Solaris 2.x.

Demonstration Programs

Demonstration programs are provided to show the various functionality of the Pro*C/C++ precompiler. There are three types of demonstration programs: C, C++, and Object programs - the latter demonstrate the new Oracle8 Object features. All the demonstration programs are located in $ORACLE_HOME/precomp/demo/proc, and all of them assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql exist in the SCOTT schema with the password TIGER.

For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" on page 4-3 of this book. For further information on the demonstration programs see the Programmer's Guide to the Pro*C/C++ Precompiler.

The makefile, $ORACLE_HOME/precomp/demo/proc/demo_proc.mk, should be used to create the demonstration programs. For example, to precompile, compile, and link the sample1 demonstration program, enter the following command.

$ make -f demo_proc.mk sample1

Alternatively, the following command may be used, which achieves exactly the same result, only with more explicit syntax.

$ make -f demo_proc.mk build OBJS=sample1.o EXE=sample1

By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.

To create all Pro*C/C++ C demonstration programs, enter the following command:

$ make -f demo_proc.mk samples

To create all Pro*C/C++ C++ demonstration programs, enter this command:

$ make -f demo_proc.mk cppsamples

To create all Pro*C/C++ Object demonstration programs, enter this command:

$ make -f demo_proc.mk object_samples

Some demonstration programs require a SQL script, found in $ORACLE_HOME/precomp/demo/sql, to be run. In order to build such a demonstration program and run the corresponding SQL script, the make macro argument, RUNSQL=run, must be included on the command line. For example, to create the calldemo demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/calldemo.sql script, use the following command syntax:

$ make -f demo_proc.mk calldemo RUNSQL=run

As another example, to create all Object demonstration programs and run all corresponding required SQL scripts, enter the following command:

$ make -f demo_proc.mk object_samples RUNSQL=run

The SQL scripts may also be run manually, if desired.

User Programs

The makefile, $ORACLE_HOME/precomp/demo/proc/demo_proc.mk, may be used to create user programs. The general syntax for linking a user program with demo_proc.mk is as follows:

$ make -f demo_proc.mk target OBJS="objfile1 objfile2 ..." \

 EXE=exename

For example, to create the program, myprog, from the Pro*C/C++ source myprog.pc, use one of the following commands, depending on the source and type of executable desired:

For C source, dynamically linked with client shared library:

$ make -f demo_proc.mk build OBJS=myprog.o EXE=myprog

For C source, statically linked:

$ make -f demo_proc.mk build_static OBJS=myprog.o EXE=myprog

For C++ source, dynamically linked with client shared library:

$ make -f demo_proc.mk cppbuild OBJS=myprog.o EXE=myprog

For C++ source, statically linked:

$ make -f demo_proc.mk cppbuild_static OBJS=myprog.o EXE=myprog

For Solaris issues on the use of shared libraries, refer to the Solaris documentation from Sun Microsystems.

Pro*COBOL

There are two versions of Pro*COBOL included with this release: Pro*COBOL 8.0.4, and Pro*COBOL 1.8.26. Table 5-3 shows the naming differences between these two versions.

Table 5-3 Pro*COBOL naming differences

Pro*COBOL supports statically linked, dynamically linked, or dynamically loadable programs. Dynamically linked programs use the Oracle client shared library, $ORACLE_HOME/lib/libclntsh.so. Dynamically loadable programs use the rtsora executable.

For additional information regarding Pro*COBOL 8.0.4, see the README file, $ORACLE_HOME/precomp/doc/procob2/readme.doc. For additional information regarding Pro*COBOL 1.8.26, see the README file, $ORACLE_HOME/precomp/doc/pro1x/readme.txt.

Administering Pro*COBOL

System Configuration File

The system configuration file for Pro*COBOL 8.0.4 is $ORACLE_HOME/precomp/admin/pcbcfg.cfg.

The system configuration file for Pro*COBOL 1.8.26 is $ORACLE_HOME/precomp/admin/pcccob.cfg.

Environment Variables

MicroFocus COBOL Compiler

The MicroFocus COBOL Compiler requires the environment variables COBDIR and LD_LIBRARY_PATH. COBDIR must be set to the directory where the compiler is installed. For example:

$ setenv COBDIR /opt/cobol

LD_LIBRARY_PATH must include the directory $COBDIR/coblib. For example, to append $COBDIR/coblib to LD_LIBRARY_PATH:

$ setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$COBDIR/coblib

If LD_LIBRARY_PATH does not contain $COBDIR/coblib, you will receive the following error when compiling a program:

ld.so.1: rts32: fatal: libfhutil.so.2.0: can't open file: errno=2

Sun Nihongo COBOL Compiler

The Sun Nihongo COBOL Compiler does not require the environment variable COBDIR. However, the PATH environment variable must include the directory /opt/SUNWnsun/bin. For example, to append /opt/SUNWnsun/bin to PATH:

$ setenv PATH ${PATH}:/opt/SUNWnsun/bin

LD_LIBRARY_PATH must also include the directory /opt/SUNWnsun/bin. To append /opt/SUNWnsun/bin to LD_LIBRARY_PATH:

$ setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/opt/SUNWnsun/bin

If LD_LIBRARY_PATH does not contain /opt/SUNWnsun/bin, you will receive the following error when compiling a program:

ld.so.1: cobol: fatal: liblicense.so: can't open file: errno=2

Using Pro*COBOL

Prior to using Pro*COBOL, verify that the correct version of the COBOL compiler is properly installed. The required version for your operating system is documented in Chapter 1 of the Oracle8 Installation Guide for Sun SPARC Solaris 2.x.

The Oracle Run Time System

Oracle provides its own complete run time system, called rtsora, to run dynamically loadable Pro*COBOL programs. The rtsora run time system should be used in place of the MicroFocus provided cobrun run time system when running dynamically loadable Pro*COBOL programs. If you attempt to run a Pro*COBOL program with cobrun, you will receive the following error:

$ cobrun sample1.gnt
Load error : file 'SQLADR'
error code: 173, pc=0, call=1, seg=0
173     Called program file not found in drive/directory

Demonstration Programs

Demonstration programs have been provided that show various functionality of the Pro*COBOL precompiler. All programs are located in either $ORACLE_HOME/precomp/demo/procob or $ORACLE_HOME/precomp/demo/procob2, depending on the Pro*COBOL version. All programs assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql exist in the SCOTT schema with the password TIGER.

For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" on page 4-3 of this book. For further information on the demonstration programs see the Programmer's Guide to the Pro*COBOL Precompiler.

The demonstration makefile should be used to create the sample programs. The demonstration makefile for Pro*COBOL 8.0.4 is $ORACLE_HOME/precomp/demo/procob2/demo_procob.mk. The demonstration makefile for Pro*COBOL 1.8.26 is $ORACLE_HOME/precomp/demo/procob/demo_procob18.mk. For example, to precompile, compile, and link the sample1 demonstration program for Pro*COBOL 8.0.4, use the following command:

$ cd $ORACLE_HOME/precomp/demo/procob2
$ make -f demo_procob.mk sample1

Alternatively, the following command may be used, which achieves exactly the same result, only with more explicit syntax.

$ make -f demo_procob.mk build COBS=sample1.cob EXE=sample1

By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.

To create all Pro*COBOL demonstration programs, enter the following command:

$ make -f demo_procob.mk samples

To create a dynamically loadable sample1.gnt program to be used with rtsora, enter this command:

$ make -f demo_procob.mk sample1.gnt

Then use rtsora to run the program as follows:

$ rtsora sample1.gnt

Some demonstration programs require a SQL script found in $ORACLE_HOME/precomp/demo/sql to be run. In order to build such a demonstration program and run the corresponding SQL script, the make macro argument, RUNSQL=run, must be included on the command line.

For example, to create the sample9 demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/calldemo.sql script, use the following command syntax:

$ make -f demo_procob.mk sample9 RUNSQL=run

The SQL scripts may also be run manually, if desired.

User Programs

The demonstration makefile may be used to create user programs. Be sure to use the appropriate makefile depending on the Pro*COBOL version and COBOL compiler used. The general syntax for linking a user program with the demonstration makefile is:

$ make -f demo_procob.mk target COBS="cobfile1 cobfile2 ..." \

 EXE=exename

For example, to create the program, myprog, from the Pro*COBOL source myprog.pco, use one of the following commands, depending on the type of executable and use of shared library resources desired:

For a dynamically linked executable with client shared library:

$ make -f demo_procob.mk build COBS=myprog.cob EXE=myprog

For a statically linked executable without client shared library:

$ make -f demo_procob.mk build_static COBS=myprog.cob EXE=myprog

For a dynamically loadable module usable with rtsora

$ make -f demo_procob.mk myprog.gnt

FORMAT Precompiler

The FORMAT precompiler option specifies the format of input lines for COBOL. If you specify FORMAT=ANSI, the default, columns 1 to 6 contain an optional sequence number, column 7 indicates comments or continuation lines, paragraph names begin in columns 8 to 11, and statements begin in columns 12 to 72.

If you specify FORMAT=TERMINAL, columns 1 to 6 are dropped, making column 7 the leftmost column.

Sun Nihongo COBOL

If you are using Sun Nihongo COBOL, rename the makefiles as follows:

For Pro*COBOL 1.8.26:

$ cd $ORACLE_HOME/precomp/demo/procob
$ mv demo_procob18.mk demo_procob.mk.mf
$ cp procob.mk.nsun procob.mk

For Pro*COBOL 8.0.4:

$ cd $ORACLE_HOME/precomp/demo/procob2
$ mv demo_procob.mk demo_procob.mk.mf
$ cp procob.mk.nsun procob.mk

Pro*FORTRAN

For additional information regarding Pro*FORTRAN 1.8.26, see the README file, $ORACLE_HOME/precomp/doc/pro1x/readme.txt.

Administering Pro*FORTRAN

System Configuration File

The system configuration file for Pro*FORTRAN is $ORACLE_HOME/precomp/admin/pccfor.cfg.

Using Pro*FORTRAN

Prior to using Pro*FORTRAN, verify that the correct version of the compiler is properly installed. The required version for your operating system is specified in Chapter 1 of the Oracle8 Installation Guide for Sun SPARC Solaris 2.x.

Demonstration Programs

Demonstration programs are provided to show the various functionality of the Pro*FORTRAN precompiler. All programs are located in $ORACLE_HOME/precomp/demo/profor, and all of them assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql exist in the SCOTT schema with the password TIGER.

For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" on page 4-3 of this book. For further information on the demonstration programs see the Pro*FORTRAN Supplement to Oracle Precompilers.

The makefile, $ORACLE_HOME/precomp/demo/profor/demo_profor.mk, should be used to create the demonstration programs. For example, to precompile, compile, and link the sample1 demonstration program, enter the following command.

$ make -f demo_profor.mk sample1

Alternatively, the following command may be used, which achieves exactly the same result, only with more explicit syntax.

$ make -f demo_profor.mk build FORS=sample1.pfo EXE=sample1

By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.

To create all Pro*FORTRAN demonstration programs, enter the following command:

$ make -f demo_profor.mk samples

Some demonstration programs require a SQL script, found in $ORACLE_HOME/precomp/demo/sql, to be run. In order to build such a demonstration program and run the corresponding SQL script, the make macro argument, RUNSQL=run, must be included on the command line. For example, to create the sample11 demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/sample11.sql script, use the following command syntax:

$ make -f demo_profor.mk sample11 RUNSQL=run

The SQL scripts may also be run manually, if desired.

User Programs

The makefile, $ORACLE_HOME/precomp/demo/profor/demo_profor.mk, may be used to create user programs. The general syntax for linking a user program with demo_profor.mk is as follows:

$ make -f demo_profor.mk target FORS="forfile1 forfile2 ..." \

 EXE=exename

For example, to create the program, myprog, from the Pro*FORTRAN source myprog.pfo, use one of the following commands, depending on the type of executable desired:

For dynamically linked executable with client shared library:

$ make -f demo_profor.mk build FORS=myprog.f EXE=myprog

For a statically linked executable:

$ make -f demo_profor.mk build_static FORS=myprog.f EXE=myprog

SQL*Module for Ada

Administering SQL*Module for Ada

System Configuration File

The system configuration file for Oracle SQL*Module is $ORACLE_HOME/precomp/admin/pmscfg.cfg.

Using SQL*Module for Ada

Prior to using SQL*Module for Ada, verify that the correct version of the compiler is properly installed. The required version for your operating system is specified in Chapter 1 of the Oracle8 Installation Guide for Sun SPARC Solaris 2.x.

Demonstration Programs

Demonstration programs have been provided that show various functionality of SQL*Module for Ada. All programs are located in $ORACLE_HOME/precomp/demo/modada.

The demonstration program ch1_drv assumes that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql exist in the SCOTT schema with the password TIGER.

The demonstration programs demcalsp and demohost assume that the sample college database created by $ORACLE_HOME/precomp/demo/sql/mktable.sql exists in the MODTEST schema.

All programs assume that a Net8 connect string or instance-alias named INST1_ALIAS has been defined, and is capable of connecting to the database where the appropriate tables exist.

For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" on page 4-3 of this book. For further information on the demonstration programs see the Programmer's Guide to SQL*Module for Ada, Release 8.0.

The makefile, $ORACLE_HOME/precomp/demo/modada/demo_modada.mk, should be used to create the demonstration programs. For example, to compile and link the ch1_drv demonstration program, use the following command:

$ make -f demo_modada.mk ch1_drv

Alternatively, the following command may be used, which achieves exactly the same result, only using more explicit syntax.

$ make -f demo_modada.mk ada OBJS="ch1_mod.ada ch1_drv.ada" \

 EXE=ch1_drv MODARAGS=user=modtest/yes

By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.

To create all SQL*Module for Ada demonstration programs, enter the following command:

$ make -f demo_modada.mk samples

The sample programs demcalsp and demohost require the sample college database created by $ORACLE_HOME/precomp/demo/sql/mktable.sql to exist in the MODTEST schema. The MODTEST user can be created by the running SQL script, $ORACLE_HOME/precomp/demo/sql/grant.sql. In order to create the MODTEST user, create the sample college database, and build a demonstration program, use the make targets makeuser and loaddb. For example, to run the required SQL scripts and create the demohost program, use the following command syntax:

$ make -f demo_modada.mk makeuser loaddb demohost

The SQL scripts may also be run manually if desired.

In order to create all SQL*Module for Ada demonstration programs, and to run the necessary SQL scripts to create the MODTEST user, and to create the sample college database, enter the following command:

$ make -f demo_modada.mk all

User Programs

The makefile, $ORACLE_HOME/precomp/demo/modada/demo_modada.mk, may be used to create user programs. The general syntax for linking a user program with demo_modada.mk is:

$ make -f demo_modada.mk ada OBJS="module1 module2 ..." \

 EXE=exename MODARAGS=SQL*Module_arguments

Oracle Call Interface

Using the Oracle Call Interface

Prior to using the Oracle Call interface (OCI), verify that the correct version of the compiler is properly installed. The required version for your operating system is specified in Chapter 1 of the Oracle8 Installation Guide for Sun SPARC Solaris 2.x.

Demonstration Programs

Demonstration programs have been provided that show various functionality of the OCI. There are two types of demonstration programs: C and C++. All the demonstration programs are located in $ORACLE_HOME/rdbms/demo. Many of the demonstration programs assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql exist in the SCOTT schema with the password TIGER.

For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" on page 4-3 of this book. For further information on the demonstration programs see the Programmer's Guide to the Oracle Call Interface and the program source for details of each program.

The makefile, $ORACLE_HOME/rdbms/demo/demo_rdbms.mk, should be used to create the demonstration programs. For example, to compile and link the cdemo1 demonstration program, enter the following command:

$ make -f demo_rdbms.mk cdemo1

Alternatively, the following command may be used, which achieves exactly the same result, only with more explicit syntax:

$ make -f demo_rdbms.mk build OBJS=cdemo1.o EXE=cdemo1

By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.

To create all OCI C demonstration programs, enter the following command:

$ make -f demo_rdbms.mk demos

To create all OCI C++ demonstration programs, enter this command:

$ make -f demo_rdbms.mk c++demos

ld: fatal: library -lsunmath: not found

ld: fatal: library -lC: not found

ld: fatal: library -lC_mtstubs: not found

ld: fatal: library -lcx: not found

$ setenv LD_LIBRARY_PATH \

${LD_LIBRARY_PATH}:/opt/SUNWspro/SC4.0/lib

Some demonstration programs require a SQL script, located in $ORACLE_HOME/rdbms/demo, to be run manually prior to executing the program. In most cases, the SQL script name is the same as the program name with a .sql extension. For example, the SQL script for the program oci02 is oci02.sql.

Read the comments at the beginning of the program to determine the required SQL script, if any.

User Programs

The makefile, $ORACLE_HOME/rdbms/demo/demo_rdbms.mk, may be used to create user programs. The general syntax for linking a user program with demo_rdbms.mk is:

$ make -f demo_rdbms.mk target OBJS="objfile1 objfile2 ..." \

 EXE=exename

For example, to create the program myprog from the C source myprog.c, use one of the following commands depending on the type of executable desired:

For C source, dynamically linked with client shared library:

$ make -f demo_rdbms.mk build OBJS=myprog.o EXE=myprog

For C source, statically linked:

$ make -f demo_rdbms.mk build_static OBJS=myprog.o EXE=myprog

To create the program myprog from the C++ source myprog.cc

For C++ source, dynamically linked with client shared library:

$ make -f demo_rdbms.mk buildc++ OBJS=myprog.o EXE=myprog

For C++ source, statically linked:

$ make -f demo_rdbms.mk buildc++_static OBJS=myprog.o EXE=myprog

Oracle Precompiler and Oracle Call Interface Linking and Makefiles

Custom Makefiles

It is recommended that the provided demo_product.mk makefiles be used to link user programs as described in the specific product sections of this chapter. If it is necessary to modify the provided makefile, or if you decide to use a custom written makefile, the following should be noted:

• Do not modify the ordering of the Oracle libraries.
  Oracle libraries are included on the link line more than once so all symbols will be resolved during linking. There are two reasons for this:
  1. Oracle libraries are mutually referential, meaning that functions in library A call functions in library B, and functions in library B call functions in library A.
  2. The Solaris linker is a one-pass linker, meaning that the linker will search a library exactly once at the point it is encountered in the link line.
• If you add your own library to the link line, it should be added to the beginning or to the end of the link line.
  User libraries should not be placed between the Oracle libraries.
• If you choose to use a make utility such as nmake or GNU make, you should be aware of how macro and suffix processing differs from the make utility provided with Solaris, /usr/ccs/bin/make. Oracle makefiles have been tested and are supported with the Solaris make utility.
• Oracle library names and the contents of those libraries are subject to change between releases. Always use the ddemo_product.mk makefile that ships with the current release as a guide to determine which libraries are necessary.

Undefined Symbols

A common error when linking a program is undefined symbols, similar to the following:

$ make -f demo_proc.mk sample1
Undefined                       first referenced
 symbol                             in file
sqlcex                              sample1.o
sqlglm                              sample1.o
ld: fatal: Symbol referencing errors. No output written to sample1

This error occurs when the linker cannot find a definition for a referenced symbol. Generally, the remedy for this type of problem is to ensure that the library or object file containing the definition exists on the link line and that the linker is searching the correct directories for the file.

Oracle provides a utility called symfind to assist in locating a library or object file where a symbol is defined. Here is example output of symfind locating the symbol sqlcex:

$ symfind sqlcex

SymFind - Find Symbol <sqlcex> in <**>.a, .o, .so
------------------------------------------------------
Command:         /u01/app/oracle/product/8.0.4/bin/symfind sqlcex
Local Directory: /u01/app/oracle/product/8.0.4
Output File:     (none)
Note:            I do not traverse symbolic links
                 Use '-v' option to show any symbolic links

Locating Archive and Object files ...
[11645] |    467572|      44|FUNC |GLOB |0    |8      |sqlcex
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ./lib/libclntsh.so
[35]    |         0|      44|FUNC |GLOB |0    |5      |sqlcex
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ./lib/libsql.a

Thread Support

The Oracle libraries provided with this release are thread safe, allowing support for multi-threaded applications.

Static and Dynamic Linking with Oracle Libraries

Precompiler and OCI applications can be linked with Oracle Libraries either statically or dynamically. With static linking, the libraries and objects of the whole application are linked together into a single executable program. As a result, application executables can become fairly large.

With dynamic linking, the executing code partly resides in the executable program, and also resides in libraries that are linked by the application dynamically at run-time. Libraries that are linked at run-time are called dynamic or shared libraries. There are two primary benefits of dynamic linking:

1. Smaller disk requirements:
   Different applications, or different invocations of the same application, can use the same shared or dynamic library. As a result, the overall disk requirements are reduced.
2. Smaller main memory requirements:
   The same shared or dynamic library image (i.e., the in-memory copy), can be shared by different applications. This means that a library needs to be loaded only once into the main memory and then multiple applications can use the same library. As a result, main memory requirements are reduced.

Oracle Shared Library

The Oracle shared library is $ORACLE_HOME/lib/libclntsh.so. If the Oracle provided demo_product.mk makefile is used to link an application, the Oracle shared library is used by default.

It may be necessary to set the environment variable LD_LIBRARY_PATH so the runtime loader can find the Oracle shared library at process start-up. If you receive the following error when starting an executable, LD_LIBRARY_PATH must be set to the directory where the Oracle shared library exists:

% sample1
ld.so.1: sample1: fatal: libclntsh.so.1.0: can't open file: errno=2 
Killed

Set LD_LIBRARY_PATH as follows:

% setenv LD_LIBRARY_PATH $ORACLE_HOME/lib

The Oracle shared library is created automatically during installation. If there is a need to recreate the Oracle shared library, exit all client applications using the Oracle shared library, including all Oracle client applications like SQL*Plus and Recovery Manager, and run the following command logged in as the oracle user:

% cd $ORACLE_HOME/rdbms/lib
% make -f ins_rdbms.mk client_sharedlib

Using Signal Handlers

This section describes signals Oracle8 uses for two-task communication, and explains how to set up your own signal handlers.

Signals

Signals are installed in a user process when you connect to the database, and are de-installed when you disconnect.

Oracle8 uses the following signals for two-task communications:

Table 5-4 Signals for Two-Task Communications

The listed signals affect Pro*C or other precompiler applications. You can install one signal handler for SIGCLD (or SIGCHLD) and SIGPIPE when connected to the oracle process. You can have multiple signal handlers for SIGINT as long as the osnsui() routine is called to set this up. You can install as many signal handlers as you want for other signals. If you are not connected to the oracle process, you can have multiple signal handlers.

Sample Signal Routine

The following example shows how you can set up your own signal routine and the catching routine. For SIGINT, use osnsui() and osncui() to register and delete signal-catching routines.

/* user side interrupt set */
word osnsui( /*_ word *handlp, void (*astp), char * ctx, _*/)
/*
** osnsui: Operating System dependent Network Set 
**User-side
** Interrupt. Add an interrupt handling procedure 
**astp. 
** Whenever a user interrupt(such as a ^C) occurs, 
**call astp
** with argument ctx. Put in *handlp handle for this 
**handler so that it may be cleared with osncui.
** Note that there may be many handlers; each should 
** be cleared using osncui. An error code is 
**returned if an error occurs.
*/

/* user side interrupt clear */
word osncui( /*_ word handle _*/ );
/*
** osncui: Operating System dependent Clear User-side 
**Interrupt.
** Clear the specified handler. The argument is the 
**handle obtained from osnsui. An error code is 
** returned if an error occurs.
*/

The following is a template for using osnsui() and osncui() in an application program:

/*
** My own user interrupt handler.
*/
void sig_handler()
{
...
}

main(argc, argv)
int arc;
char **argv;
   {

   int handle, err;
   ...
   
   /* set up my user interrupt handler */
   if (err = osnsui(&handle, sig_handler, (char *) 0))
      {
      /* if the return value is non-zero, an error has occurred
      Do something appropriate here. */
      ...
      }
      ...
      /* clear my interrupt handler */
      if (err = osncui(handle))
      {
      /* if the return value is non-zero, an error has occurred
      Do something appropriate here. */
      ...
      }
      ...

      }

XA Functionality

When building a TP-monitor XA application, ensure that the TP-monitors libraries (that define the symbols ax_reg and ax_unreg) are placed in the link line before Oracle's client shared library. This link restriction is required only when using XA's dynamic registration (Oracle XA switch xaoswd).

The Oracle8 Server does not support Oracle7 7.1.6 XA calls (although it does support 7.3 XA calls), hence TP-monitor XA applications using 7.1.6 XA calls must be relinked with the Oracle8 XA library. The Oracle8 XA calls are defined in both the shared library $ORACLE_HOME/lib/libclntsh.so and the static library $ORACLE_HOME/lib/libclient.a.