4
Using Oracle Precompilers and the Oracle Call Interface

Precompiler Configuration Files

Configuration files for the Oracle precompilers are located in the $ORACLE_HOME/precomp/admin directory. Table 4-1 lists the names of the configuration files for each precompiler.

Table 4-1 System Configuration Files for Oracle Precompilers

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

In the preceding examples, executable is a product executable listed in Table 4-2.

Table 4-2 Products and Their Corresponding Executable

Precompiler README Files

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

Table 4-3 Location of Precompiler README Files

Issues Common to All Precompilers

The following issues are common to all precompilers.

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 linked by default.

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

• On AIX systems:

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

• On HP systems:

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

• On Solaris and Linux systems:

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

• On Tru64 systems:

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

If you receive one of these error messages, set one of the following environment variables, depending on your platform:

• On AIX systems:

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

• On HP systems (64-bit applications), Linux, Solaris, and Tru64 systems:

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

• On HP systems (32-bit applications)

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

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

1. Exit all client applications that use 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
   

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

• 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
  
  

  
  

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

  
  

Pro*COBOL Environment Variables

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

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

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

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

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

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

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

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

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.2.0.1.0, use:

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

• For Pro*COBOL release 1.8.77.0.0, use:

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

  
  

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

  
  

To precompile, compile, and link the sample1 demonstration program for Pro*COBOL, 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 creating a program with the demonstration make file is:

• For Pro*COBOL release 9.2.0.1.0, enter:

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

• For Pro*COBOL release 1.8.77.0.0, enter:

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

In the preceding examples:

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

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

You can use the $ORACLE_HOME/precomp/demo/modada/demo_modada.mk make file to create user programs. The syntax for creating 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

  
  

  See Also: SQL*Module for Ada Programmers Guide for more information on SQL*Module for Ada user programs.

  
  

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 the $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 user programs. The syntax for creating a user program with the demo_rdbms.mk make file 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

• 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
  
  

  
  

  Note: In the preceding examples, the file myprog.o is the object file generated by the compiler. On AIX, HP, and Solaris 64-bit, the demo_rdbms.mk make file builds 64-bit user programs by default. You can use the demo_rdbms32.mk make file to build 32-bit user programs. See the make file for more information on creating 32-bit user programs.