Полезная информация

Oracle8 Administrator's Reference
Release 8.0.5 for Intel-LINUX

A66585-02

Library

Product

Contents

Index

Prev Next

5
Using Oracle Precompilers and the Oracle Call Interface on LINUX

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
Product   Executable  

Pro*C/C++

 

proc

 

Object Type Translator

 

ott

 

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
Product   Configuration File  

Pro*C/C++ v8.0.5

 

pcscfg.cfg

 

Object Type Translator v8.0.5

 

ottcfg.cfg

 

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:

Pro*C/C++

For additional information regarding Pro*C/C++ release 8.0.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.

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

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 LINUX issues on the use of shared libraries, refer to the LINUX documentation.

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

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.

See Also:

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


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

it will be necessary to include in LD_LIBRARY_PATH, the directory in which the specified libraries exist.

 

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:

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.5/bin/symfind sqlcex
Local Directory: /u01/app/oracle/product/8.0.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 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.
  1. 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-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 LINUX 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 Oracle Net8 protocol adapters to indicate incoming networking events.

 

SIGURG

 

used by the Oracle 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).

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.




Prev

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index