Oracle8i Administrator's Reference
Release 3 (8.1.7) 64 Bit for SGI IRIX

Part Number A87435_01
Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

4
Using Oracle Precompilers and the Oracle Call Interface

This chapter describes Oracle Precompilers and the Oracle Call Interface. It contains the following sections:

Overview of Oracle Precompilers

Oracle precompilers are application development 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 database management system.

See Also:

For general information on Oracle precompilers and interface features, see the Oracle8i Server Application Developer's Guide 

Precompiler Configuration Files

System configuration files for the Oracle Precompilers are located in the $ORACLE_HOME/precomp/admin/ directory. Table 4-1 lists the system configuration files.

Table 4-1 System Configuration Files
Product  Configuration File 

Pro*C/C++ release 8.1.7 

pcscfg.cfg 

Pro*FORTRAN release 1.8.52 

pccfor.cfg 

Object Type Translator release 8.1.7 

ottcfg.cfg 

Table 4-2 lists the location of precompiler README files. The README files describe changes since the last release.

Table 4-2 Location of README Files for Oracle Products
Product  README File 

Pro*C/C++ release 8.1.7 

$ORACLE_HOME/precomp/doc/proc2/readme.doc 

Pro*FORTRAN release 1.8.52 

$ORACLE_HOME/precomp/doc/pro1x/readme.txt 

Issues Common to All Precompilers

The following issues are common to all precompilers:

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 with a debugger will run the same way on an operating system.

Value of ireclen and oreclen

The ireclen and oreclen parameters do not have maximum values.

Static and Dynamic Linking

You can statically or dynamically link precompiler and OCI applications with Oracle libraries. 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 run time. Libraries that are linked at run time are called dynamic or shared libraries. Benefits of dynamic linking are:

Client Shared Library

The client shared library, libclntsh.so, 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.

You may 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_LIBRARY64_PATH and LD_LIBRARYN32_PATH environment variables as follows:

$ LD_LIBRARY64_PATH=$ORACLE_HOME/lib: $ORACLE_HOME/javavm/admin
$ export LD_LIBRARY64_PATH
$ LD_LIBRARYN32_PATH=$ORACLE_HOME/lib32
$ export LD_LIBRARYN32_PATH

The client shared library is created automatically during installation. If you must re-create 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.so
    

Pro*C/C++ Precompiler

Before you use Pro*C/C++, verify that the MIPSpro C/C++ compiler release 7.2.1.3 or later is installed. This compiler is part of the MIPSpro compiler package supplied by SGI.

.


Note:

To compile C source files containing multi-byte character references, you must use version 7.3 of the MIPSpro C compiler. 


Pro*C/C++ 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. Object programs demonstrate the new Oracle8i Object features. All of the demonstration programs are located in the $ORACLE_HOME/precomp/demo/proc directory. 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. By default, all programs are dynamically linked with the $ORACLE_HOME/lib/libclntsh.so client shared library.

See Also:

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

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 the C demonstration programs for Pro*C/C++, enter:

$ make -f demo_proc.mk samples

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

$ make -f demo_proc.mk cppsamples

To create 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 Object demonstration programs and run all corresponding required SQL scripts, enter:

$ make -f demo_proc.mk object_samples RUNSQL=run


Note:

The ORA_CLIENT_LIB environment variable is no longer used by the demo_proc.mk make file. 


See Also:

For information on using SQL*Plus to build demonstration programs, see "Using Demonstration Tables"

Pro*C/C++ User Programs

You can use the $ORACLE_HOME/precomp/demo/proc/demo_proc.mk make file to create 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:

For example, to create the program myprog from the Pro*C/C++ source 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

Pro*FORTRAN Precompiler

Before using Pro*FORTRAN, make sure that the MIPSpro FORTRAN compiler release 7.2.1.3 or later is installed. This compiler is part of the MIPSpro compiler package supplied by SGI.

Pro*FORTRAN Demonstration Programs

Demonstration programs are provided to show the varied functionality of the Pro*FORTRAN precompiler. All of the demonstration programs are located in the $ORACLE_HOME/precomp/demo/profor directory and all of 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. By default, all programs are dynamically linked with the client shared library $ORACLE_HOME/lib/libclntsh.so.

The makefile demo_profor.mk located in the $ORACLE_HOME/precomp/demo/profor directory should be used to create the demonstration programs.

For example, to precompile, compile, and link the sample1 demonstration program, enter the command:

$ make -f demo_profor.mk sample1

Use the $ORACLE_HOME/precomp/demo/profor/demo_profor.mk makefile to create the demonstration programs. For example, to precompile, compile, and link the sample1 demonstration program, enter one of the following commands:

$ make -f demo_profor.mk sample1

or

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

To create all Pro*FORTRAN demonstration programs, enter:

$ make -f demo_profor.mk samples

For some demonstration programs, you must run a SQL script, located in the $ORACLE_HOME/precomp/demo/sql directory. If you do not run the script, a message appears 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

See Also:

For information on using SQL*Plus to build demonstration programs, see "Using Demonstration Tables". For more information on Pro*FORTRAN precompilers, see Pro*FORTRAN Supplement to Oracle Precompilers

Pro*FORTRAN User Programs

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

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

In the preceding example:

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

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

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

For a statically linked executable, enter:

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

Oracle Call Interface

Before using the Oracle Call Interface (OCI), make sure that the MIPSpro C/C++ compiler release 7.2.1.3 or later is installed. This compiler is part of the MIPSpro compiler package supplied by SGI.

See Also:

The required version for your operating system is specified in the Oracle8i Installation Guide Release 3 (8.1.7) 64 Bit for SGI IRIX

OCI Demonstration Programs

Demonstration programs are provided to show the varied functionality 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 $ORACLE_HOME/lib/libclntsh.so.

Many of the demonstration 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 $ORACLE_HOME/rdbms/demo/demo_rdbms.mk make file to create the demonstration programs. For example, to compile and link the cdemo1 demonstration program, enter:

$ make -f demo_rdbms.mk cdemo1

To create the OCI C demonstration programs, enter:

$ make -f demo_rdbms.mk demos

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

$ make -f demo_rdbms.mk cppdemos


Some demonstration programs require you to run a SQL script found in the $ORACLE_HOME/rbdms/demo directory. If you do not run the script, a message appears requesting you to run the script. In most cases, the SQL script name is the same as the program name with a.sql extension.

See Also:

For information on using SQL*Plus to build demonstration programs, see "Using Demonstration Tables".

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. 

OCI User Programs

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

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

In the preceding example:

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

To create the myprog program from the C source, dynamically linked with a the client shared library, enter:

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

To create the myprog program from the C source, statically linked, enter:

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

To create the myprog program from the C++ source, dynamically linked with client shared library, enter:

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

To create the myprog program from the C++ source, statically linked, enter:

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


Note:

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:

Correcting Undefined Symbols

Oracle provides the symfind utility to assist in locating a library or object file where a symbol is defined. A common error when linking a program is undefined symbols, which produces 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/8.1.7/bin/symfind sqlcex
Local Directory: /u01/app/oracle/product/8.1.7
Output File:     (none)
Note:            I do not traverse symbolic links
                 Use '-v' option to show any symbolic links

Locating Archive and Object files ...
[521] |    467572|      135|FUNC |GLOB |DEFAULT|mips.text |sqlcex
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ./lib/libclntsh.so
[17]    |        2864|      136|FUNC |GLOB |DEFAULT |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

Signals can be used by Oracle8i for two-task communication. Signals are installed in a user process when you connect to the database and are de-installed when you disconnect.

Table 4-3 describes the signals that Oracle8i uses for two-task communications.

Table 4-3 Signals for Two-Task Communications    
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 see if 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 

Net8 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 

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

The following example shows how you can set up a signal routine and a 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. */

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

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

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


Go to previous page Go to next page
Oracle
Copyright © 2001 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index