Oracle8i Administrator's Reference
Release 8.1.5 for Sun SPARC Solaris

A67456-01

Library

Product

Contents

Index

Prev Next

4
Using Oracle Precompilers and the Oracle Call Interface

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 Oracle8i or any other ANSI SQL DBMS.

Precompiler Configuration Files

The.cfg system configuration files in $ORACLE_HOME/precomp/admin are described in Table 4-1.

Table 4-1 System Configuration Files
Product  Configuration File 

Pro*C/C++ 8.1.5 

pcscfg.cfg 

Pro*COBOL 8.1.5 

pcbcfg.cfg 

Pro*COBOL 1.8.50 

pcccob.cfg 

Pro*FORTRAN 1.8.50.0 

pccfor.cfg 

Oracle SQL*Module for Ada 8.1.5 

pmscfg.cfg 

Object Type Translator 8.1.5 

ottcfg.cfg 

Issues Common to All Precompilers


Note:

In order to run Oracle Precompiler demonstrations, you must already have installed Oracle8i


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. 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.

Additional Documentation

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

Pro*C/C++

For additional information regarding Pro*C/C++ Release 8.1.5, 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.

See Also:

For further information, see the Programmer's Guide to the Pro*C/C++ Precompiler

Using Pro*C/C++

Before you use Pro*C/C++, verify that the correct version of the Operating System compiler is properly installed. The required version is documented in the Oracle8i Installation Guide for Sun SPARC Solaris.

Demonstration Programs

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

For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" of this book.

See Also:

For further information on using demonstration programs, see the Programmer's Guide to the Pro*C/C++ Precompiler

Use the makefile, $ORACLE_HOME/precomp/demo/proc/demo_proc.mk, 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, use the following command, which achieves the same result, 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 C demonstration programs for Pro*C/C++, enter the following command:

$ make -f demo_proc.mk samples

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

$ make -f demo_proc.mk cppsamples

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

$ make -f demo_proc.mk object_samples

Some demonstration programs require you to run a SQL script from $ORACLE_HOME/precomp/demo/sql. To build a demonstration program and run the corresponding SQL script, include the make macro argument, RUNSQL=run, 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

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 restrictions 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.1.5 and Pro*COBOL 1.8.50. Table 4-2 shows the naming differences between these two versions.

Table 4-2 Pro*COBOL naming differences
  Pro*COBOL 8.1.5  Pro*COBOL 1.8.50 
Executable 

procob 

procob18 

Demo Directory 

procob2 

procob 

Makefile
for MicroFocus COBOL
 

demo_procob.mk 

demo_procob18.mk 

Makefile
for SUN Nihongo COBOL
 

demo_procob.mk.nsun 

demo_procob18.mk.nsun 

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.1.5, see the README file $ORACLE_HOME/precomp/doc/procob2/readme.doc. For additional information regarding Pro*COBOL 1.8.50, 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.1.5 is
$ORACLE_HOME/precomp/admin/pcbcfg.cfg.

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

See Also:

For further information, see the Programmer's Guide to the Pro*COBOL Precompiler

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:

$ set COBDIR /opt/cobol; export COBDIR

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

$ set LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$COBDIR/coblib
$ export LD_LIBRARY_PATH

If LD_LIBRARY_PATH does not contain $COBDIR/coblib, you 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:

$ set PATH ${PATH}:/opt/SUNWnsun/bin; export PATH

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

$ set LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/opt/SUNWnsun/bin
$ export LD_LIBRARY_PATH

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

Before you use Pro*COBOL, verify that the correct version of the COBOL compiler is properly installed. The required version for your operating system is documented in the Oracle8i Installation Guide for Sun SPARC Solaris.

The Oracle Run Time System

Oracle provides its own complete run time system, called rtsora, to run dynamically loadable Pro*COBOL programs use the rtsora runtime system in place of the MicroFocus provided cobrun run time system when you run dynamically loadable Pro*COBOL programs. If you attempt to run a Pro*COBOL program with cobrun, you 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 the varied 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 are in the SCOTT schema with the password TIGER. For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" of this book.

See Also:

For further information on the demonstration programs, see the Programmer's Guide to the Pro*COBOL Precompiler

Use the demonstration makefile to create the sample programs. The demonstration makefile for Pro*COBOL 8.1.5 is
$ORACLE_HOME/precomp/demo/procob2/demo_procob.mk.

the demonstration makefile for Pro*COBOL 1.8.50 is
$ORACLE_HOME/precomp/demo/procob/demo_procob18.mk.

For example, to precompile, compile, and link the sample1 demonstration program for Pro*COBOL 8.1.5, 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 the same result, 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 Option

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 makefile as follows:


For Pro*COBOL 8.1.5:

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

For Pro*COBOL 1.8.50:

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

Pro*FORTRAN

For additional information regarding Pro*FORTRAN 1.8.50, 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 Oracle8i Installation Guide for Sun SPARC Solaris.

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.

See Also:

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 Oracle8i Installation Guide for Sun SPARC Solaris.

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.

See Also:

For further information on the demonstration programs see the Programmer's Guide to SQL*Module for Ada

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 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, 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

Before using the Oracle Call Interface (OCI), verify that the correct version of Pro*C/C++ is properly installed. The required version for your operating system is specified in Chapter 1 of the Oracle8i Installation Guide for Sun SPARC Solaris.

Demonstration Programs

Demonstration programs have been provided that show the varied 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 are in the SCOTT schema with the password TIGER.

For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" 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.

Use the makefile, $ORACLE_HOME/rdbms/demo/demo_rdbms.mk, 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 the same result 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 this command:

$ make -f demo_rdbms.mk demos

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

$ make -f demo_rdbms.mk c++demos


Note:

If you receive the following errors while linking a C++ program: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


you must include in LD_LIBRARY_PATH the directory in which the specified libraries exist.

For example, if using SPARCompiler C++ 4.0 the directory is /opt/SUNWspro/SC4.0/lib. Enter these commands:$ LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:\ /opt/SUNWspro/SC4.0/lib$ export LD_LIBRARY_PATH 


Some demonstration programs require you to run a SQL script manually before you execute the program. All the scripts are in $ORACLE_HOME/rbdms/demo. 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 you use the provided demo_product.mk makefiles 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, note the following:

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.The Solaris linker is a one-pass linker, meaning that the linker searches a library exactly once at the point it is encountered in the link line.

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.1.5/bin/symfind sqlcex
Local Directory: /u01/app/oracle/product/8.1.5
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 runtime. Libraries that are linked at runtime 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 (for example, 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 startup. 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 re-create the Oracle shared library, exit all client applications using the Oracle shared library, including all Oracle client applications such as 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 libclntsh.so

Using Signal Handlers

This section describes signals Oracle8i 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.

Oracle8i uses the following signals for two-task communications:

Table 4-3 Signals for Two-Task Communications

SIGCONT  

used by the pipe two-task driver to send out-of-band breaks from the user process to the oracle process. 

SIGINT 

used by all two-task drivers to detect user interrupt requests. SIGINT is not caught by oracle; it is caught by the user process. 

SIGPIPE 

used by the pipe driver to detect end-of-file on the communications channel. When writing to the pipe, if no reading process exists, a SIGPIPE signal is sent to the writing process. SIGPIPE is caught by both the oracle process and the user process. 

SIGCLD 

used by the pipe driver. SIGCLD is similar to SIGPIPE, but only applies to user processes, not oracle processes. When an oracle process dies, the UNIX kernel sends a SIGCLD to the user process (wait() is used in the signal handler to see if the server process died). SIGCLD is not caught by oracle; it is caught by the user process.  

SIGTERM 

used by the pipe driver to signal interrupts from the user side to the oracle process. This occurs when the user presses the interrupt key [Ctrl]+[c]. SIGTERM is not caught by the user process; it is caught by oracle.  

SIGIO 

used by Net8 protocol methods to indicate incoming networking events. 

SIGURG 

used by the Net8 TCP/IP drivers to send out-of-band breaks from the user process to the oracle process. 

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).

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


Prev Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index