Using Oracle Precompilers and the Oracle Call Interface

 

Overview

Oracle precompilers are application-development tools used to combine SQL statements for 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 Oracle9i or any other ANSI SQL database management system.

 

Precompiler Configuration Files

System configuration files for the Oracle Precompilers are located in the $ORACLE_HOME/precomp/admin directory.

 

System Configuration Files for Oracle Precompilers  

Product Configuration File
Pro*C/C++ release 9.0.1 pcscfg.cfg
Pro*COBOL release 9.0.1 (AIX, HP, Solaris, and Tru64) pcbcfg.cfg
Pro*COBOL release 1.8.75 (AIX, HP, Solaris, and Tru64) pcccob.cfg
Pro*FORTRAN release 1.8.75 pccfor.cfg
Object Type Translator release 9.0.1 ottcfg.cfg
Oracle SQL*Module for Ada release 9.0.1 (Solaris and AIX only) pmscfg.cfg

 

Relinking Precompiler Executables

Use the $ORACLE_HOME/precomp/lib/ins_precomp.mk make file to relink all precompiler executables. To manually relink a particular precompiler executable, enter the following command: 

$ make -f ins_precomp.mk relink EXENAME=executable

This command creates the new executable in the $ORACLE_HOME/precomp/lib directory, and then moves it to the $ORACLE_HOME/bin directory. To create the new executable without moving it to the $ORACLE_HOME/bin directory, enter the following command: 

$ make -f ins_precomp.mk executable

 

Products and Their Corresponding Executable Names  

Pro*C/C++ release 9.0.1 proc
Pro*COBOL release 1.8.75 procob18 or rtsora
Pro*COBOL release 9.0.1 procob or rtsora
Pro*FORTRAN release 1.8.75 profor
Oracle SQL*Module for Ada release 9.0.1 modada
Object Type Translator release 9.0.1 ott

 

Precompiler README Files

 

Location of README Files for Oracle Products  

Product README File
Pro*C/C++ release 9.0.1 $ORACLE_HOME/precomp/doc/proc2/readme.doc
Pro*COBOL release 9.0.1 $ORACLE_HOME/precomp/doc/procob2/readme.doc
Pro*COBOL release 1.8.75
Pro*FORTRAN release 1.8.75 		$ORACLE_HOME/precomp/doc/pro1x/readme.txt

 

Issues Common to All Precompilers

The following issues are common to all precompilers.

To run Oracle Precompiler demonstrations, Oracle9i must already be installed. 

 

Uppercase to Lowercase Conversion

In languages other than C, the compiler converts an uppercase function or subprogram name to lowercase. This can cause a "No such user exists" error message. If you receive this error message, verify that the function or subprogram name in your option file matches the case used in the IAPXTB table.

 

Vendor Debugger Programs

Precompilers and vendor-supplied debuggers can be incompatible. Oracle Corporation does not guarantee that a program run using a debugger will perform the same way when it is run without the debugger.

 

Value of IRECLEN and ORECLENT

The IRECLEN and ORECLEN parameters do not have maximum values.

 

Static and Dynamic Linking

You can statically or dynamically link Oracle libraries with precompiler and OCI applications. 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 very large.

With dynamic linking, the executing code is partly stored in the executable program and partly stored in libraries that are linked dynamically by the application at runtime. Libraries that are linked at runtime are called dynamic or shared libraries. The benefits of dynamic linking are:

  • Smaller disk requirements--More than one application or invocation of the same application can use the same dynamic library.

  • Smaller main memory requirements--The same dynamic library image is loaded into main memory only once and it can be shared by more than one application.

 

Client Shared Library

The client shared library is located in the $ORACLE_HOME/lib directory. If you use the Oracle provided demo_product.mk make file to link an application, the client shared library is used by default.

 

For Solaris and Linux Systems Only

You might receive the following error message when starting an executable: 

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

If you receive this error message, set the LD_LIBRARY_PATH environment variable as follows: 

$ LD_LIBRARY_PATH=$ORACLE_HOME/lib:${LD_LIBRARY_PATH}
$ export LD_LIBRARY_PATH

The client shared library is created automatically during installation. If recreate the client shared library:

  1. Exit all client applications using the client shared library, including all Oracle client applications such as SQL*Plus and Recovery Manager.

  2. Log in as the oracle user and enter: 

    $ genclntsh

 

For AIX Systems Only

You might receive the following error message when starting an executable: 

$ sample1
exec(): 0509-036 Cannot load program ./sample1 because of the following 
errors:
0509-022 Cannot load library libclntsh.sl [shr.0]
0509-026 System error: A file or directory in the pathname does not exist.

If you receive this error message, set the LIBPATH environment variable as follows: 

$ LIBPATH=$ORACLE_HOME/lib:${LIBPATH}
$ export LIBPATH

The client shared library is created automatically during installation. If recreate the client shared library:

  1. Exit all client applications using the client shared library, including all Oracle client applications such as SQL*Plus and Recovery Manager.

  2. Log in as the oracle user and enter: 

    $ genclntsh

 

For Tru64 Systems Only

You might receive the following error message when starting an executable: 

$ sample1
/sbin/loader: Fatal Error: Cannot map libclntsh.so
Killed

If you receive this error message, set the LD_LIBRARY_PATH environment variable as follows: 

$ LD_LIBRARY_PATH=$ORACLE_HOME/lib:${LD_LIBRARY_PATH}
$ export LD_LIBRARY_PATH

The client shared library is created automatically during installation. If recreate the client shared library:

  1. Exit all client applications using the client shared library, including all Oracle client applications such as SQL*Plus and Recovery Manager.

  2. Log in as the oracle user and enter: 

    $ genclntsh

 

For HP Systems Only

You might receive the following error message when starting an executable: 

$ sample1
/usr/lib/dld.sl: Can't open shared library:
/u01/app/oracle/product/9.0.1/lib/libclntsh.sl.8.0
/usr/lib/dld.sl: No such file or directory
Abort (core dumped)

If you receive this error message, set the SHLIB_PATH environment variable as follows: 

$ SHLIB_PATH=$ORACLE_HOME/lib:${SHLIB_PATH}
$ export SHLIB_PATH

The client shared library is created automatically during installation. If recreate the client shared library:

  1. Exit all client applications using the client shared library, including all Oracle client applications such as SQL*Plus and Recovery Manager.

  2. Log in as the oracle user and enter: 

    $ cd $ORACLE_HOME/rdbms/lib
$ make -f ins_rdbms.mk libclntsh.sl

 

Pro*C/C++ Precompiler

Before you use the Pro*C/C++ precompiler, verify that the correct version of the operating system compiler is properly installed.

 

Pro*C/C++ Demonstration Programs

Demonstration programs are provided to show the features of the Pro*C/C++ precompiler. There are three types of demonstration programs: C, C++, and Object programs. Object programs demonstrate the new Oracle9i Object features. All of the demonstration programs are located in the $ORACLE_HOME/precomp/demo/proc directory. By default, all programs are dynamically linked with the client shared library.

The programs assume that the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script exist in the SCOTT schema with the password TIGER.

Use the demo_proc.mk make file, located in the $ORACLE_HOME/precomp/demo/proc/ directory, 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

To create all of the C demonstration programs for Pro*C/C++, enter: 

$ make -f demo_proc.mk samples

To create all of the C++ demonstration programs for Pro*C/C++, enter: 

$ make -f demo_proc.mk cppsamples

To create all of the Object demonstration programs for Pro*C/C++, enter: 

$ make -f demo_proc.mk object_samples

Some demonstration programs require you to run a SQL script, located in the $ORACLE_HOME/precomp/demo/sql directory. If you do not run the script, a message displays requesting you to run it. 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, enter: 

$ make -f demo_proc.mk calldemo RUNSQL=run

To create all of the Object demonstration programs and run all corresponding required SQL scripts, enter: 

$ make -f demo_proc.mk object_samples RUNSQL=run

 

Pro*C/C++ User Program

You can use the $ORACLE_HOME/precomp/demo/proc/demo_proc.mk make file to create user programs. The syntax for linking a program with the demo_proc.mk make file is: 

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

In the preceding example:

  • target is the make file target that you want to use (for example, build)

  • objfilen is the object file to link the program

  • exename is the executable program

For example, to create the program myprog from the Pro*C/C++ source file myprog.pc, enter one of the following commands, depending on the source and the type of executable you want to create.

  • For C source, dynamically linked with the client shared library, enter: 

    $ make -f demo_proc.mk build OBJS=myprog.o EXE=myprog
  • For C source, statically linked, enter: 

    $ make -f demo_proc.mk build_static OBJS=myprog.o EXE=myprog
  • For C++ source, dynamically linked with the client shared library, enter: 

    $ make -f demo_proc.mk cppbuild OBJS=myprog.o EXE=myprog
  • For C++ source, statically linked, enter: 

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

    On AIX and HP, the demo_proc.mk make file builds 64 bit user programs by default. You can also use this make file to build 32 bit user programs. See the make file for more information on creating 32 bit user programs. 

 

Pro*COBOL Precompiler

 

Pro*COBOL Naming Differences  

Item Pro*COBOL Release 9.0.1 Pro*COBOL Release 1.8.75
Executable procob procob18
Demonstration Directory procob2 procob
Make file for Merant Server Express COBOL demo_procob.mk demo_procob18.mk
Make file 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 client shared library. Dynamically loadable programs use the rtsora executable located in the $ORACLE_HOME/bin directory.

 

Pro*COBOL Environment Variables

This section describes the environment variables required by Pro*COBOL.

 

Merant Server Express COBOL Compiler

For the Merant Server Express COBOL compiler, set the COBDIR and LD_LIBRARY_PATH environment variables.

 

COBDIR

Set the COBDIR environment variable to the directory where the compiler is installed. For example, if the compiler is installed in the /opt/cobol directory, enter: 

$ COBDIR=${COBDIR}:$/opt/cobol 
$ export COBDIR

 

LD_LIBRARY_PATH

The LD_LIBRARY_PATH environment variable must include the $COBDIR/coblib directory. To add this directory to the LD_LIBRARY_PATH environment variable, enter: 

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

If the LD_LIBRARY_PATH environment variable setting does not include the $COBDIR/coblib directory, one of the following error messages appears when you compile a program:

  • On Tru64: 

    14783 rtspra: /sbin/loader: Fatal Error: cannot map libwtc8.so
  • On AIX, HP, and Solaris: 

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

 

Sun Nihongo COBOL Compiler

For the Sun Nihongo COBOL compiler, set the PATH and LD_LIBRARY_PATH environment variables.

 

PATH

Set the PATH environment variable to include the /opt/SUNWnsun/bin directory, as follows: 

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

 

LD_LIBRARY_PATH

The LD_LIBRARY_PATH environment variable must include the /opt/SUNWnsun/bin directory. To add this directory to the LD_LIBRARY_PATH environment variable, enter: 

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

If the LD_LIBRARY_PATH environment variable setting does not include the /opt/SUNWnsun/bin directory, the following error message appears when you compile a program: 

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

 

Sun Nihongo COBOL Make Filenames

If you are using Sun Nihongo COBOL, you might want to rename the make files to match the examples and create a backup copy of the files, as follows:

  • For Pro*COBOL release 9.0.1, enter: 

    $ cd $ORACLE_HOME/precomp/demo/procob2
$ mv demo_procob.mk demo_procob.mk.mf
$ cp demo_procob.mk.nsun demo_procob.mk
  • For Pro*COBOL release 1.8.75, enter: 

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

 

Pro*COBOL Oracle Runtime System

Oracle provides its own complete runtime system, called rtsora, to run dynamically loadable Pro*COBOL programs. Use the rtsora runtime system in place of the cobrun runtime system provided by Merant to 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

 

Pro*COBOL Demonstration Programs

Demonstration programs are provided to show the features of the Pro*COBOL precompiler. The demonstration programs are located in either the $ORACLE_HOME/precomp/demo/procob directory or the $ORACLE_HOME/precomp/demo/procob2 directory, depending on the Pro*COBOL version. By default, all programs are dynamically linked with the client shared library.

The programs assume that the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script exist in the SCOTT schema with the password TIGER.

Use the appropriate make file to create the demonstration programs:

  • For Pro*COBOL release 9.0.1, use: 

    $ORACLE_HOME/precomp/demo/procob/demo_procob.mk
  • For Pro*COBOL release 1.8.75, use: 

    $ORACLE_HOME/precomp/demo/procob/demo_procob18.mk

    The following examples assume that you are using the make file for Pro*COBOL release 9.0.1. 

To precompile, compile, and link the sample1 demonstration program for ProCOBOL, enter: 

$ make -f demo_procob.mk sample1

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

$ make -f demo_procob.mk samples

To create and run a dynamically loadable sample1.gnt program to be used with the rtsora runtime system, enter: 

$ make -f demo_procob.mk sample1.gnt
$ rtsora sample1.gnt

Some demonstration programs require you to run a SQL script, located in the $ORACLE_HOME/precomp/demo/sql directory. If you do not run the script, a message displays requesting you to run it. 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 sample9 demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/sample9.sql script, enter: 

$ make -f demo_procob.mk sample9 RUNSQL=run

To create all of the Pro*COBOL demonstration programs and run all corresponding required SQL scripts, enter: 

$ make -f demo_procob.mk samples RUNSQL=run

 

Pro*COBOL User Programs

You can use the appropriate demonstration make file to create user programs, depending on the version of Pro*COBOL you are using. The syntax for linking a program with the demonstration make file is:

  • For Pro*COBOL release 9.0.1, enter: 

    $ make -f demo_procob.mk target COBS="cobfile1 cobile2 ..." EXE=exename
  • For Pro*COBOL release 1.8.75, enter: 

    $ make -f demo_procob18.mk target COBS="cobfile1 cobfile2 ..." EXE=

In the preceding examples:

  • target is the make file target that you want to use (for example, build)

  • cobfilen is the COBOL source file for the program

  • exename is the executable program

For example, to create the program myprog, enter one of the following commands, depending on the source and type of executable you want to create:

  • For COBOL source, dynamically linked with the client shared library, enter: 

    $ make -f demo_procob.mk build COBS=myprog.cob EXE=myprog
  • For COBOL source, statically linked, enter: 

    $ make -f demo_procob.mk build_static COBS=myprog.cob EXE=myprog
  • For COBOL source, dynamically loadable for use with rtsora, enter: 

    $ 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 the default FORMAT=ANSI, 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 left-most column.

 

Pro*FORTRAN Precompiler

Before you use the Pro*FORTRAN precompiler, verify that the correct version of the compiler is installed.

 

Pro*FORTRAN Demonstration Programs

Demonstration programs are provided to show the features of the Pro*FORTRAN precompiler. All of the demonstration programs are located in the $ORACLE_HOME/precomp/demo/profor directory. By default, all programs are dynamically linked with the client shared library.

The programs assume that the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script exist in the SCOTT schema with the password TIGER.

Use the demo_profor.mk make file, located in the $ORACLE_HOME/precomp/demo/profor directory, to create the demonstration programs. For example, to precompile, compile, and link the sample1 demonstration program, enter: 

$ make -f demo_profor.mk sample1

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

$ make -f demo_profor.mk samples

Some demonstration programs require you to run a SQL script, located in the $ORACLE_HOME/precomp/demo/sql directory. If you do not run the script, a message displays requesting you to run it. 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 sample11 demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/sample11.sql script, enter: 

$ make -f demo_profor.mk sample11 RUNSQL=run

To create all of the Pro*FORTRAN demonstration programs and run all corresponding required SQL scripts, enter: 

$ make -f demo_profor.mk samples RUNSQL=run

 

Pro*FORTRAN User Programs

You can use the $ORACLE_HOME/precomp/demo/profor/demo_profor.mk make file to create user programs. The syntax for linking a program with the demo_proc.mk make file is: 

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

In the preceding example:

  • target is the make file target that you want to use (for example, build)

  • forfilen is the FORTRAN source for the program

  • exename is the executable program

For example, to create the program myprog, from the Pro*FORTRAN source file myprog.pfo, enter one of the following commands, depending on the type of executable that you want to create:

  • For an executable dynamically linked with the client shared library, enter: 

    $ make -f demo_profor.mk build FORS=myprog.f EXE=myprog
  • For an executable statically linked, enter: 

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

 

SQL*Module for Ada (Solaris and AIX Only)

Before using SQL*Module for Ada, verify that the correct version of the compiler is installed.

 

SQL*Module for Ada Demonstration Programs

Demonstration programs are provided to show the features of SQL*Module for Ada. All of the demonstration programs are located in the $ORACLE_HOME/precomp/demo/modada directory. By default, all programs are dynamically linked with the client shared library.

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

The demcalsp and demohost demonstration programs require that the sample college database exists in the MODTEST schema. You can use the appropriate make command to create the MODTEST schema and load the sample college database.

To create all of the SQL*Module for Ada demonstration programs, run the necessary SQL scripts to create the MODTEST user, and create the sample college database, enter: 

$ make -f demo_modada.mk all RUNSQL=run

To create a single demonstration program (demohost), and run the necessary SQL scripts to create the MODTEST user, and create the sample college database, enter: 

$ make -f demo_modada.mk makeuser loaddb demohost RUNSQL=run

To create all of the SQL*Module for Ada demonstration programs, without recreating the sample college database, enter: 

$ make -f demo_modada.mk samples

To create a single demonstration program (demohost), without recreating the sample college database, enter: 

$ make -f demo_modada.mk demohost

All programs assume that an Oracle Net connect string or alias named INST1_ALIAS is defined and is capable of connecting to the database where the appropriate tables exist.

 

SQL*Module for Ada User Programs

Use the $ORACLE_HOME/precomp/demo/modada/demo_modada.mk make file to create user programs. The syntax for linking a user program with the demo_modada.mk make file is: 

$ make -f demo_modada.mk ada OBJS="module1 module2 ..." \
EXE=exename MODARGS=SQL*Module_arguments

In the preceding example:

  • modulen is a compiled Ada object

  • exename is the executable program

  • SQL*Module_arguments are the command line arguments to be passed to the SQL*Module

 

Oracle Call Interface

Before you use the Oracle Call Interface (OCI), verify that the correct version of Pro*C/C++ is installed.

 

OCI Demonstration Programs

Demonstration programs are provided that show the features of the OCI. There are two types of demonstration programs: C and C++. All of the demonstration programs are located in the $ORACLE_HOME/rdbms/demo directory. By default, all programs are dynamically linked with the client shared library.

Many of the demonstration programs assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql script exist in the SCOTT schema with the password TIGER.

Use the demo_rdbms.mk make file, located in the $ORACLE_HOME/rdbms/demo directory, 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

To create all of the C demonstration programs for OCI, enter: 

$ make -f demo_rdbms.mk demos

To create all of the C++ demonstration programs for OCI, enter: 

$ make -f demo_rdbms.mk c++demos

 

OCI User Programs

You can use the $ORACLE_HOME/rdbms/demo/demo_rdbms.mk make file to create programs. The syntax for linking a user program with demo_rdbms.mk is: 

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

In the preceding example:

  • target is the make file target that you want to use (for example, build)

  • objfilen is the object file to link the program

  • exename is the executable program

For example, to create the myprog program from the C/C++ source myprog.c, enter one of the following commands, depending on the type of executable you want to create:

  • For C source, dynamically linked with the client shared library, enter: 

    $ make -f demo_rdbms.mk build OBJS=myprog.o EXE=myprog
  • For C source, statically linked, enter: 

    $ make -f demo_rdbms.mk build_static OBJS=myprog.o EXE=myprog
  • For C++ source, dynamically linked with the client shared library, enter: 

    $ make -f demo_rdbms.mk buildc++ OBJS=myprog.o EXE=myprog
  • For C++ source, statically linked, enter: 

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

    In the preceding examples, the file myprog.o is the object file generated by the compiler. 

 

Custom Make Files

Oracle Corporation recommends that you use the provided demo_product.mk make files to link user programs as described in the specific product sections of this chapter. If you modify the provided make file, or if you choose to use a custom-written make file, the following restrictions apply:

  • Do not modify the order of the Oracle libraries. Oracle libraries are included on the link line more than once so that all of the symbols are resolved during linking. This information does not apply to AIX-based systems.

    The order of the Oracle libraries is essential for the following reasons:

    • Oracle libraries are mutually referential. Functions in library A call functions in library B, and functions in library B call functions in library A.

    • The HP and Tru64 linkers are one-pass linkers. The AIX, Linux, and Solaris linkers are two-pass linkers.

  • If you add your own library to the link line, add it to the beginning or to the end of the link line. Do not place user libraries between the Oracle libraries.

  • If you choose to use a make utility such as nmake or GNU make, be aware of how macro and suffix processing differs from the make utility provided with the platform. Oracle make files are tested and are supported with the make utility for your platform.

  • Oracle library names and the contents of Oracle libraries are subject to change between releases. Always use the demo_product.mk make file that ships with the current release as a guide to determine the required libraries.

 

Correcting Undefined Symbols (Solaris Only)

Oracle provides the symfind utility to assist you in locating a library or object file where a symbol is defined. When linking a program, undefined symbols are a common error that produce an error message 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

The error occurs when the linker cannot find a definition for a referenced symbol. If this error message occurs, 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.

The following example shows the output from the symfind utility, used to locate the sqlcex symbol: 

$ symfind sqlcex

SymFind - Find Symbol <sqlcex> in <**>.a, .o, .so
------------------------------------------------------
Command:         /u01/app/oracle/product/9.0.1/bin/symfind sqlcex
Local Directory: /u01/app/oracle/product/9.0.1
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.sl
[35]    |         0|      44|FUNC |GLOB |0    |5      |sqlcex
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ./lib/libsql.a

 

Multi-threaded Applications

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

 

Using Signal Handlers

Oracle9i uses signals for two-task communication. Signals are installed in a user process when you connect to the database and are removed when you disconnect.

 

Signals for Two-Task Communication  

Signal Description
SIGCLD The pipe driver uses SIGCLD, also referred to as SIGCHLD, when an Oracle process dies. The UNIX kernel sends a SIGCLD signal to the user process. The signal handler uses the wait() routine to determine whether a server process died. The Oracle process does not catch SIGCLD; the user process catches it.
SIGCONT The pipe two-task driver uses SIGCONT to send out-of-band breaks from the user process to the Oracle process.
SIGINT Two-task drivers use SIGINT to detect user interrupt requests. The Oracle process does not catch SIGINT; the user process catches it.
SIGIO Oracle Net protocols use SIGIO to indicate incoming networking events.
SIGPIPE The pipe driver uses SIGPIPE 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. Both the Oracle process and the user process catch SIGPIPE. SIGCLD is similar to SIGPIPE, but only applies to user processes, not to Oracle processes.
SIGTERM The pipe driver uses SIGTERM to signal interrupts from the user to the Oracle process. This occurs when the user presses the interrupt key, Ctrl+c. The user process does not catch SIGTERM; the Oracle process catches it.
SIGURG Oracle Net TCP/IP drivers use SIGURG to send out-of-band breaks from the user process to the Oracle process.

The listed signals affect Pro*C and all other precompiler applications. You can install one signal handler for SIGCLD (or SIGCHLD) and SIGPIPE when connected to the Oracle process. If you call the osnsui() routine to set it up, you can have more than one signal handle for SIGINT. For SIGINT, use osnsui() and osncui() to register and delete signal-catching routines.

You can also 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.

Example 4-1 shows how to set up a signal routine and a catching routine.

 

Example 4-1 Signal Routine and Catching Routine

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

Example 4-2 shows how to use the osnsui() and the osncui() routines in an application program.

 

Example 4-2 osnsui() and osncui() Routine Template

/*
** User interrupt handler template.
*/
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
                   Take appropriate action for the error. */
                ...
        }

        ...

        /* clear my interrupt handler */

        if (err = osncui(handle))
        {
                /* if the return value is non-zero, an error has occurred
                   Take appropriate action for the error. */
                ...
        }
        ...
}

 

XA Functionality

Oracle XA is the Oracle implementation of the X/Open Distributed Transaction Processing (DTP) XA interface. The XA standard specifies a bi-directional interface between resource managers (for example, Oracle) that provide access to shared resources within transactions, and between a transaction service that monitors and resolves transactions.

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

Oracle9i does not support Oracle7 release 7.1.6 XA calls (although it does support Oracle7 release 7.3 XA calls). Therefore, TP-monitor XA applications using Oracle7 release 7.1.6 XA calls must be relinked with the Oracle9i XA library. The Oracle9i XA calls are defined in both the $ORACLE_HOME/lib/libclntsh.sl shared library and the $ORACLE_HOME/lib/libclient9.a static library.