6 Using Oracle Precompilers and the Oracle Call Interface

6.1.1 Precompiler Configuration Files

Configuration files for the Oracle precompilers are located in the $ORACLE_HOME/precomp/admin directory.

Table 6-1 lists the names of the configuration files for each precompiler.

6.1.2 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_name

This command creates the new executable in the $ORACLE_HOME/precomp/lib directory, and then moves it to the $ORACLE_HOME/bin directory.

In the preceding example, replace executable with one of the product executables listed in Table 6-2.

Table 6-2 lists the executables for Oracle Precompilers.

6.1.3 Precompiler README Files

The README files describe changes made to the precompiler since the last release.

Table 6-3 lists the location of the precompiler README files.

6.1.4 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, then verify that the case of the function or subprogram name in the option file matches the case used in the IAPXTB table.

• Vendor Debugger Programs

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

• Value of IRECLEN and ORECLEN parameters

  The IRECLEN and ORECLEN parameters do not have maximum values.

6.1.5 Static and Dynamic Linking

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

• Reduced disk space requirements: More than one application or call to the same application can use the same dynamic library.

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

6.1.6 Client Shared and Static Libraries

The client shared and static libraries are located in the $ORACLE_HOME/lib or $ORACLE_HOME/lib32 directories. If you use the Oracle-provided demo_product.mk make file to link an application, then the client shared library is linked by default.

If the shared library path environment variable setting does not include the directory that contains the client shared library, then you may see an error message similar to one of the following lines when starting an executable:

Cannot load library libclntsh.a
Can't open shared library: .../libclntsh.sl.10.1
libclntsh.so.10.1: can't open file: errno=2 
can't open library: .../libclntsh.dylib.10.1  
Cannot map libclntsh.so

To avoid this error, set the shared library path environment variable to specify the appropriate directory. The following table shows sample settings for this environment variable name. If the platform supports both 32-bit and 64-bit applications, then ensure that you specify the correct directory, depending on the application that you want to run.

The client shared library is created automatically during installation. If you have to re-create it, then:

1. Quit all client applications that use the client shared library, including all Oracle client applications such as SQL*Plus and Oracle Recovery Manager.

2. Log in as the oracle user, and run the following command:

   $ $ORACLE_HOME/bin/genclntsh
   

Nonthreaded Client Shared Library

On HP-UX PA-RISC, you can use a non-threaded client shared library. However, you cannot use this library with any OCI application that uses or has a dependency on threads.

To use this library for applications that do not use threads, run one of the following commands to build the OCI application:

• For 32-bit applications:

  $ make -f demo_rdbms32.mk build_nopthread EXE=oci02 OBJS=oci02.o
  
  

• For 64-bit applications:

  $ make -f demo_rdbms.mk build_nopthread EXE=oci02 OBJS=oci02.o
  

6.3.1 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. All demonstration programs are located in the $ORACLE_HOME/precomp/demo/proc directory. By default, all programs are dynamically linked with the client shared library.

To run the demonstration programs, the programs require the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script to exist in the SCOTT schema with the password TIGER.

Use the demo_proc.mk make file, which is 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, run the following command:

$ make -r -f demo_proc.mk sample1

$ make -f demo_proc.mk sample1

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

$ make -f demo_proc.mk samples

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

$ make -f demo_proc.mk cppsamples

To create all the Object demonstration programs for Pro*C/C++, run the following command:

$ 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, then a message prompting you to run it is displayed.

To build a demonstration program and run the corresponding SQL script, include the make macro argument RUNSQL=run at the command line. For example, to create the sample9 demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/sample9.sql script, run the following command:

$ make -f demo_proc.mk sample9 RUNSQL=run

To create all the Object demonstration programs and run all the required SQL scripts, run the following command:

$ make -f demo_proc.mk object_samples RUNSQL=run

6.3.2 Pro*C/C++ User Programs

You can use the $ORACLE_HOME/precomp/demo/proc/demo_proc.mk make file to create user programs. This make file builds either 32-bit or 64-bit user programs. You can also use the demo_proc32.mk make file to build 32-bit (or 31-bit on IBM zSeries Based Linux) user programs. The following table shows the make files that you can use to build 32-bit (or 31-bit) and 64-bit user programs with Pro*C/C++:

To create a program by using the demo_proc.mk make file, run a command similar to the following:

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

In this example:

• target is the make file target that you want to use

• 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, run one of the following commands, depending on the source and the type of executable that you want to create:

• For C source dynamically linked with the client shared library, run the following command:

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

• For C source statically linked with the client shared library, run the following command:

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

• For C++ source dynamically linked with the client shared library, run the following command:

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

• For C++ source statically linked with the client shared library, run the following command:

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

6.4.1 Pro*COBOL Environment Variables

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

runcbl: error while loading shared libraries: libclntsh.so: 
cannot open shared object file: No such file or directory

6.4.2 Pro*COBOL Oracle Runtime System

Oracle provides its own complete run-time system, called rtsora (or rtsora32 for 32-bit COBOL compilers on 64-bit systems), to run dynamically loadable Pro*COBOL programs. Use the rtsora (or rtsora32) run-time system instead of the cobrun run-time system to run dynamically loadable Pro*COBOL programs. If you attempt to run a Pro*COBOL program with cobrun, then an error message similar to the following is displayed:

$ 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

6.4.3 Pro*COBOL Demonstration Programs

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

To run the demonstration programs, the programs require the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script to exist in the SCOTT schema with the password TIGER.

Use the following make file to create the demonstration programs:

$ORACLE_HOME/precomp/demo/procob2/demo_procob.mk

To precompile, compile, and link the sample1 demonstration program for Pro*COBOL, run the following command:

$ make -f demo_procob.mk sample1

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

$ make -f demo_procob.mk samples

To create and run a dynamically loadable sample1.gnt program to be used with the rtsora run-time system, run the following command:

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

Some demonstration programs require you to run a SQL script, which is located in the $ORACLE_HOME/precomp/demo/sql directory. If you do not run the script, then a message requesting you to run it is displayed.

To build a demonstration program and run the corresponding SQL script, include the make macro argument RUNSQL=run in the command. For example, to create the sample9 demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/sample9.sql script, run the following command:

$ make -f demo_procob.mk sample9 RUNSQL=run

To create the Pro*COBOL demonstration programs and run all required SQL scripts, run the following command:

$ make -f demo_procob.mk samples RUNSQL=run

6.4.4 Pro*COBOL User Programs

You can use the $ORACLE_HOME/precomp/demo/procob2/demo_procob.mk make file to create user programs. This make file builds either 32-bit or 64-bit user programs. You can also use the demo_procob_32.mk make file to build 32-bit (or 31-bit) user programs. The following table shows the make files that you can use to build 32-bit (or 31-bit) and 64-bit user programs with Pro*COBOL:

To create a program using the demo_procob.mk make file, run a command similar to the following:

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

In this example:

• target is the make file target that you want to use

• cobfilen is the COBOL source file for the program

• exename is the executable program

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

• For COBOL source, dynamically linked with the client shared library, run the following command:

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

• For COBOL source, statically linked, run the following command:

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

• For COBOL source, dynamically loadable for use with rtsora (or rtsora32 for 32-bit COBOL compilers), run the following command:

  $ make -f demo_procob.mk myprog.gnt
  

6.4.5 FORMAT Precompiler Option

The FORMAT precompiler option specifies the format of input lines for COBOL. If you specify the default value ANSI, then 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 the value TERMINAL, then columns 1 to 6 are dropped, making column 7 the left most column.

6.5.1 Pro*FORTRAN Demonstration Programs

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

To run the demonstration programs, the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script must exist in the SCOTT schema with the password TIGER.

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

$ make -f demo_profor.mk sample1

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

$ make -f demo_profor.mk samples

Some demonstration programs require you to run a SQL script that is located in the $ORACLE_HOME/precomp/demo/sql directory. If you do not run the script, then a message prompting you to run it is displayed.

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, run the following command:

$ make -f demo_profor.mk sample11 RUNSQL=run

To create the Pro*FORTRAN demonstration programs and run all the required SQL scripts, run the following command:

$ make -f demo_profor.mk samples RUNSQL=run

6.5.2 Pro*FORTRAN User Programs

You can use the $ORACLE_HOME/precomp/demo/profor/demo_profor.mk make file to create user programs. This make file builds either 32-bit or 64-bit user programs. You can also use the demo_profor_32.mk make file to build 32-bit user programs. The following table shows the make files that you can use to build 32-bit and 64-bit user programs with Pro*FORTRAN:

To create a program using the demo_proc.mk make file, run a command similar to the following:

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

In this example:

• target is the make file target that you want to use

• 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, run 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, run the following command:

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

• For an executable statically linked with the client shared library, run the following command:

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

6.6.1 SQL*Module for Ada Demonstration Programs

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

To run the ch1_drv demonstration program, the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script must 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.

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

$ 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, run the following command:

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

To create the SQL*Module for Ada demonstration programs, without re-creating the sample college database, run the following command:

$ make -f demo_modada.mk samples

To create a single demonstration program (demohost), without re-creating the sample college database, run the following command:

$ make -f demo_modada.mk demohost

To run the programs, you must define an Oracle Net connect string or alias named INST1_ALIAS that is capable of connecting to the database where the appropriate tables exist.

6.6.2 SQL*Module for Ada User Programs

You can use the $ORACLE_HOME/precomp/demo/modada/demo_modada.mk make file to create user programs. To create a user program with the demo_modada.mk make file, run a command similar to the following:

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

In this 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

  See Also:

  Oracle SQL*Module for Ada Programmer's Guide for information about SQL*Module for Ada

6.7.1 OCI and OCCI Demonstration Programs

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

To run the demonstration programs, the programs require the demonstration tables created by the $ORACLE_HOME/sqlplus/demo/demobld.sql script to exist in the SCOTT schema with the password TIGER. Some of the demonstration programs require specific .sql files to be run, as mentioned in the demonstration source files. OCCI demonstration programs require occidemo.sql to be run.

Use the demo_rdbms.mk make file, which is located in the $ORACLE_HOME/rdbms/demo directory, to create the demonstration programs. For example, to compile and link the cdemo1 demonstration program, run the following command:

$ make -f demo_rdbms.mk cdemo1

To create the C demonstration programs for OCI, run the following command:

$ make -f demo_rdbms.mk demos

To create the C++ demonstration programs for OCCI, run the following command:

$ make -f demo_rdbms.mk occidemos

6.7.2 OCI and OCCI User Programs

You can use the $ORACLE_HOME/rdbms/demo/demo_rdbms.mk make file to build user programs. This make file builds either 32-bit or 64-bit user programs. You can also use the demo_rdbms32.mk to build 32-bit user programs on a 64-bit operating system. The following table shows the make files that you can use to build 32-bit and 64-bit user programs with Pro*FORTRAN: