Release 2 (8.1.6) for Sun SPARC Solaris
A77184-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i Administrator's Reference Release 2 (8.1.6) for Sun SPARC Solaris A77184-01 |
|
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 Oracle8i or any other ANSI SQL DBMS.
The.cfg system configuration files in $ORACLE_HOME/precomp/admin are described in Table 4-1.
In languages other than C, your compiler converts an uppercase function or subprogram name to lowercase. This can cause "No such user exit" errors. Verify that the function or subprogram name in your option file matches the case in the iapxtb table.
Precompilers and vendor-supplied debuggers can be incompatible. Oracle Corporation does not guarantee that a program run under a debugger will run the same way under an operating system.
The ireclen and oreclen parameters do not have maximum values.
The following documents provide additional information about precompiler and interface features:
For additional information regarding Pro*C/C++ version 8.1.6, see the README file, $ORACLE_HOME/precomp/doc/proc2/readme.doc.
The system configuration file for Pro*C/C++ is $ORACLE_HOME/precomp/admin/pcscfg.cfg.
Before you use Pro*C/C++, verify that the correct version of the operating system compiler is properly installed. The required version is documented in the Oracle8i Installation Guide for Sun SPARC Solaris.
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. The latter demonstrate the new Oracle8i Object features. All the demonstration programs are in the directory $ORACLE_HOME/precomp/demo/proc and all of them assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql are in the SCOTT schema with the password TIGER.
For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" of this book.
Use the makefile, $ORACLE_HOME/precomp/demo/proc/demo_proc.mk, 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, use the following command, which achieves the same result, 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 C demonstration programs for Pro*C/C++, enter the following command:
$ make -f demo_proc.mk samples
To create all C++ demonstration programs for Pro*C/C++, enter this command:
$ make -f demo_proc.mk cppsamples
To create all Object demonstration programs for Pro*C/C++, enter this command:
$ make -f demo_proc.mk object_samples
Some demonstration programs require you to run a SQL script from $ORACLE_HOME/precomp/demo/sql. 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, use the following command syntax:
$ make -f demo_proc.mk calldemo RUNSQL=run
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 can also be run manually.
The makefile, $ORACLE_HOME/precomp/demo/proc/demo_proc.mk, can 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 Solaris restrictions on the use of shared libraries, refer to the Solaris documentation from Sun Microsystems.
There are two versions of Pro*COBOL included with this release: Pro*COBOL 8.1.6 and Pro*COBOL 1.8.50. Table 4-2 shows the naming differences between these two versions.
Pro*COBOL supports statically linked, dynamically linked, or dynamically loadable programs. Dynamically linked programs use the Oracle client shared library, $ORACLE_HOME/lib/libclntsh.so. Dynamically loadable programs use the rtsora executable.
For additional information on Pro*COBOL 8.1.6, see the README file $ORACLE_HOME/precomp/doc/procob2/readme.doc.
For additional information on Pro*COBOL 1.8.50, see the README file, $ORACLE_HOME/precomp/doc/pro1x/readme.txt.
The system configuration file for Pro*COBOL 8.1.6 is $ORACLE_HOME/precomp/admin/pcbcfg.cfg.
The system configuration file for Pro*COBOL 1.8.50 is $ORACLE_HOME/precomp/admin/pcccob.cfg
The MicroFocus COBOL Compiler requires the environment variables COBDIR and LD_LIBRARY_PATH.
COBDIR must be set to the directory where the compiler is installed. For example:
$ set COBDIR /opt/cobol; export COBDIR
LD_LIBRARY_PATH must include the directory $COBDIR/coblib. For example, to append $COBDIR/coblib to LD_LIBRARY_PATH:
$ set LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$COBDIR/coblib $ export LD_LIBRARY_PATH
If LD_LIBRARY_PATH does not contain $COBDIR/coblib, you receive the following error when compiling a program:
ld.so.1: rts32: fatal: libfhutil.so.2.0: can't open file: errno=2
The Sun Nihongo COBOL Compiler does not require the environment variable COBDIR. However, the PATH environment variable must include the directory /opt/SUNWnsun/bin. For example, to append /opt/SUNWnsun/bin to PATH:
$ set PATH ${PATH}:/opt/SUNWnsun/bin; export PATH
LD_LIBRARY_PATH must also include the directory /opt/SUNWnsun/bin. To append /opt/SUNWnsun/bin to LD_LIBRARY_PATH:
$ set LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/opt/SUNWnsun/bin
$ export LD_LIBRARY_PATH
If LD_LIBRARY_PATH does not contain /opt/SUNWnsun/bin, you will receive the following error when compiling a program:
ld.so.1: cobol: fatal: liblicense.so: can't open file: errno=2
Before you use Pro*COBOL, verify that the correct version of the COBOL compiler is properly installed. The required version for your operating system is documented in the Oracle8i Installation Guide for Sun SPARC Solaris.
Oracle provides its own complete run time system, called rtsora, to run dynamically loadable Pro*COBOL programs use the rtsora runtime system in place of the MicroFocus provided cobrun run time system when you 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
Demonstration programs have been provided that show the varied functionality of the Pro*COBOL precompiler. All programs are located in either $ORACLE_HOME/precomp/demo/procob or $ORACLE_HOME/precomp/demo/procob2, depending on the Pro*COBOL version. All programs assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql are in the SCOTT schema with the password TIGER. For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" of this book.
Use the demonstration makefile to create the sample programs. The demonstration makefile for Pro*COBOL 8.1.6 is $ORACLE_HOME/precomp/demo/procob2/demo_procob.mk.
The demonstration makefile for Pro*COBOL 1.8.50 is .
$ORACLE_HOME/precomp/demo/procob/demo_procob18.mk
For example, to precompile, compile, and link the sample1 demonstration program for Pro*COBOL 8.1.6, use the following command:
$ cd $ORACLE_HOME/precomp/demo/procob2
$ make -f demo_procob.mk sample1
Alternatively, the following command may be used, which achieves the same result, with more explicit syntax.
$ make -f demo_procob.mk build COBS=sample1.cob EXE=sample1
By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.
To create all Pro*COBOL demonstration programs, enter the following command:
$ make -f demo_procob.mk samples
To create a dynamically loadable sample1.gnt program to be used with rtsora, enter this command:
$ make -f demo_procob.mk sample1.gnt
Then use rtsora to run the program as follows:
$ rtsora sample1.gnt
Some demonstration programs require a SQL script found in $ORACLE_HOME/precomp/demo/sql to be run. To build such 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/calldemo.sql script, use the following command syntax:
$ make -f demo_procob.mk sample9 RUNSQL=run
The SQL scripts can also be run manually.
The demonstration makefile can be used to create user programs. Be sure to use the appropriate makefile depending on the Pro*COBOL version and COBOL compiler used. The general syntax for linking a user program with the demonstration makefile is:
$ make -f demo_procob.mk target COBS="cobfile1 cobfile2 ..." \
EXE=exename
For example, to create the program, myprog, from the Pro*COBOL source myprog.pco, use one of the following commands, depending on the type of executable and use of shared library resources desired.
For a dynamically linked executable with client shared library:
$ make -f demo_procob.mk build COBS=myprog.cob EXE=myprog
For a statically linked executable without client shared library:
$ make -f demo_procob.mk build_static COBS=myprog.cob EXE=myprog
For a dynamically loadable module usable with rtsora:
$ make -f demo_procob.mk myprog.gnt
The FORMAT precompiler option specifies the format of input lines for COBOL. If you specify FORMAT=ANSI, the default, 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 leftmost column.
If you are using Sun Nihongo COBOL, rename the makefile as follows:
For Pro*COBOL 8.1.6:
$ cd $ORACLE_HOME/precomp/demo/procob2 $ mv demo_procob.mk demo_procob.mk.mf $ cp procob.mk.nsun procob.mk
For Pro*COBOL 1.8.50:
$ cd $ORACLE_HOME/precomp/demo/procob $ mv demo_procob18.mk demo_procob.mk.mf $ cp procob.mk.nsun procob.mk
For additional information regarding Pro*FORTRAN 1.8.50, see the README file, $ORACLE_HOME/precomp/doc/pro1x/readme.txt.
The system configuration file for Pro*FORTRAN is $ORACLE_HOME/precomp/admin/pccfor.cfg.
Prior to using Pro*FORTRAN, 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 Oracle8i Installation Guide for Sun SPARC Solaris.
Demonstration programs are provided to show the various functionality of the Pro*FORTRAN precompiler. All programs are located in
$ORACLE_HOME/precomp/demo/profor, 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 3-3 of this book.
The makefile, $ORACLE_HOME/precomp/demo/profor/demo_profor.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_profor.mk sample1
Alternatively, the following command may be used, which achieves exactly the same result, only with more explicit syntax:
$ make -f demo_profor.mk build FORS=sample1.pfo EXE=sample1
By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.
To create all Pro*FORTRAN demonstration programs, enter the following command:
$ make -f demo_profor.mk samples
Some demonstration programs require a SQL script, found in $ORACLE_HOME/precomp/demo/sql, to be run. 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 sample11 demonstration program and run the required $ORACLE_HOME/precomp/demo/sql/sample11.sql script, use the following command syntax:
$ make -f demo_profor.mk sample11 RUNSQL=run
The SQL scripts can also be run manually.
The makefile, $ORACLE_HOME/precomp/demo/profor/demo_profor.mk, can be used to create user programs. The general syntax for linking a user program with demo_profor.mk is as follows:
$ make -f demo_profor.mk target FORS="forfile1 forfile2 ..." \
EXE=exename
For example, to create the program, myprog, from the Pro*FORTRAN source myprog.pfo, use one of the following commands, depending on the type of executable desired:
For dynamically linked executable with client shared library:
$ make -f demo_profor.mk build FORS=myprog.f EXE=myprog
For a statically linked executable:
$ make -f demo_profor.mk build_static FORS=myprog.f EXE=myprog
The system configuration file for Oracle SQL*Module is $ORACLE_HOME/precomp/admin/pmscfg.cfg.
Prior to using SQL*Module for Ada, 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 Oracle8i Installation Guide for Sun SPARC Solaris.
Demonstration programs have been provided that show various functionality of SQL*Module for Ada. All programs are located in $ORACLE_HOME/precomp/demo/modada.
The demonstration program ch1_drv assumes that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql exist in the SCOTT schema with the password TIGER.
The demonstration programs demcalsp and demohost assume that the sample college database created by $ORACLE_HOME/precomp/demo/sql/mktable.sql exists in the MODTEST schema.
All programs assume that a Net8 connect string or instance-alias named INST1_ALIAS has been defined and is capable of connecting to the database where the appropriate tables exist.
For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" on page 3-3 of this book.
The makefile, $ORACLE_HOME/precomp/demo/modada/demo_modada.mk, should be used to create the demonstration programs. For example, to compile and link the ch1_drv demonstration program, use the following command:
$ make -f demo_modada.mk ch1_drv
Alternatively, the following command can be used, which achieves exactly the same result, only using more explicit syntax:
$ make -f demo_modada.mk ada OBJS="ch1_mod.ada ch1_drv.ada" \
EXE=ch1_drv MODARAGS=user=modtest/yes
By default, all programs are dynamically linked with the client shared library, $ORACLE_HOME/lib/libclntsh.so.
To create all SQL*Module for Ada demonstration programs, enter the following command:
$ make -f demo_modada.mk samples
The sample programs demcalsp and demohost require the sample college database created by $ORACLE_HOME/precomp/demo/sql/mktable.sql in the MODTEST schema. The MODTEST user can be created by the running SQL script, $ORACLE_HOME/precomp/demo/sql/grant.sql. To create the MODTEST user, create the sample college database, and build a demonstration program, use the make targets makeuser and loaddb. For example, to run the required SQL scripts and create the demohost program, use the following command syntax:
$ make -f demo_modada.mk makeuser loaddb demohost
The SQL scripts can also be run manually.
To create all SQL*Module for Ada demonstration programs, to run the necessary SQL scripts to create the MODTEST user, and to create the sample college database, enter the following command:
$ make -f demo_modada.mk all
The makefile, $ORACLE_HOME/precomp/demo/modada/demo_modada.mk, may be used to create user programs. The general syntax for linking a user program with demo_modada.mk is:
$ make -f demo_modada.mk ada OBJS="module1 module2 ..." \
EXE=exename MODARAGS=SQL*Module_arguments
Before using the Oracle Call Interface (OCI), verify that the correct version of Pro*C/C++ is properly installed. The required version for your operating system is specified in Chapter 1 of the Oracle8i Installation Guide for Sun SPARC Solaris.
Demonstration programs have been provided that show the varied 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 are in the SCOTT schema with the password TIGER.
For further information on building the demonstration programs using SQL*Plus, see "Demonstration Tables" of this book.
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.
Use the makefile, $ORACLE_HOME/rdbms/demo/demo_rdbms.mk, 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, you can use the following command, which achieves the same result 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 this command:
$ make -f demo_rdbms.mk demos
To create all OCI C++ demonstration programs, enter this command:
$ make -f demo_rdbms.mk c++demos
Some demonstration programs require you to run a SQL script manually before you execute the program. All the scripts are in $ORACLE_HOME/rbdms/demo. 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.
The makefile, $ORACLE_HOME/rdbms/demo/demo_rdbms.mk, can 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
It is recommended that you use the provided demo_product.mk makefiles to link user programs as described in the specific product sections of this chapter. You need to modify the provided makefile, or if you decide to use a custom written makefile, note the following:
nmake or GNU make, be aware of how macro and suffix processing differs from the make utility provided with Solaris, /usr/ccs/bin/make. Oracle makefiles have been tested and are supported with the Solaris make utility.
demo_product.mk makefile that ships with the current release as a guide to determine which libraries are necessary.
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.1.6/bin/symfind sqlcex Local Directory: /u01/app/oracle/product/8.1.6 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
The Oracle libraries provided with this release are thread safe, allowing support for multi-threaded applications.
You can link precompiler and Oracle Call Interface applications 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 runtime. Libraries that are linked at runtime are called dynamic or shared libraries. There are two primary benefits of dynamic linking:
The Oracle shared library is $ORACLE_HOME/lib/libclntsh.so. If you use the Oracle provided demo_product.mk makefile to link an application, the Oracle shared library is used by default.
It might be necessary to set the environment variable LD_LIBRARY_PATH so the runtime loader can find the Oracle shared library at process startup. 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 you need to re-create the Oracle shared library, exit all client applications using the Oracle shared library, including all Oracle client applications such as 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 libclntsh.so
This section describes signals Oracle8i uses for two-task communication and explains how to set up your own signal handlers.
Signals are installed in a user process when you connect to the database and are de-installed when you disconnect.
Oracle8i uses the following signals for two-task communications:
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.
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. */ ... } ...
}
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).
Oracle8i does not support Oracle7 r7.1.6 XA calls (although it does support 7.3 XA calls), hence TP-monitor XA applications using r7.1.6 XA calls must be relinked with the Oracle8i XA library. The Oracle8i XA calls are defined in both the shared library $ORACLE_HOME/lib/libclntsh.so and the static library $ORACLE_HOME/lib/libclient8.a.
|
 Copyright © 1999 Oracle Corporation. All Rights Reserved. |
|