Release 3 (8.1.7) for Sun SPARC Solaris
Part Number A85349-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i Administrator's Reference Release 3 (8.1.7) for Sun SPARC Solaris Part Number A85349-01 |
|
This chapter describes the following Oracle Precompiler and Oracle Call Interface features:
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 database management system. In order to run the Oracle precompiler demonstrations, you must have already installed Oracle8i.
|
See Also:
For general information on Oracle precompilers and interface features, see Oracle8i Server Application Developer's Guide |
Precompiler system configuration files located in the $ORACLE_HOME/precomp/admin/ directory. Table 5-1 lists the precompiler system configuration files.
Table 5-2 lists the location of precompiler README files. The README files describe changes since the last release.
In languages other than C, the compiler converts an uppercase function or subprogram name to lowercase. This can cause an "No such user exit" 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.
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.
You can link precompiler and OCI 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 partly 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. Benefits of dynamic linking are:
The Oracle shared library is libclntsh.so located in the $ORACLE_HOME/lib/ directory. If you use the Oracle provided demo_product.mk makefile to link an application, the Oracle 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 LD_LIBRARY_PATH by entering:
$ set 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. Then log in as the oracle user and enter:
$ cd $ORACLE_HOME/rdbms/lib
$ make -f ins_rdbms.mk libclntsh.so
Before you use Pro*C/C++, verify that the correct version of the operating system compiler is properly installed.
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. Object programs demonstrate the new Oracle8i Object features. All the demonstration programs are located in the $ORACLE_HOME/precomp/demo/proc directory. The programs assume that the demonstration tables created by $ORACLE_HOME/sqlplus/demo/demobld.sql 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.a.
The makefile, demo_proc.mk located in $ORACLE_HOME/precomp/demo/proc/ directory 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
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 a SQL script, found in $ORACLE_HOME/precomp/demo/sql, to be run. If you do not run the script, a message will be displayed requesting you to run it. 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, 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
|
See Also:
For information about using SQL*Plus to build demonstration programs, see "Using Demonstration Tables". |
You can use the makefile demo_proc.mk located in the $ORACLE_HOME/precomp/demo/proc/ directory to create programs. The syntax for linking a program with demo_proc.mk is:
$ make -f demo_proc.mk target OBJS="objfile1 objfile2 ..." EXE=exename
where
target is the makefile target that will be used (example, build)
objfilen is the object file to link the program
EXE is the executable program
For example, to create the program myprog from the Pro*C/C++ source myprog.pc, enter one of the following command, depending on the source and the type of executable.
For C source, dynamically linked with a 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 a 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
There are two versions of Pro*COBOL included with this release. Table 5-3 shows the naming conventions for these versions.
Pro*COBOL supports statically linked, dynamically linked, or dynamically loadable programs. Dynamically linked programs use the client shared library $ORACLE_HOME/lib/libclntsh.so. Dynamically loadable programs use the rtsora executable located in the $ORACLE_HOME/bin directory.
This section describes setting up environment variables for the MicroFocus and the Sun Nihongo COBOL compilers.
The MicroFocus COBOL Compiler requires the COBDIR and LD_LIBRARY_PATH environment variables be set in order to run the compiler.
The COBDIR variable must be set to the directory where the compiler is installed. For example, enter:
$ set COBDIR /opt/cobol; export COBDIR
where /opt/cobol is the compiler directory.
LD_LIBRARY_PATH must include the $COBDIR/coblib directory. For example, to append $COBDIR/coblib to LD_LIBRARY_PATH, enter:
$ set LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$COBDIR/coblib $ export LD_LIBRARY_PATH
If LD_LIBRARY_PATH does not contain $COBDIR/coblib, the following error message appears when you compile 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 COBDIR environment variable. However, the PATH environment variable must include the directory /opt/SUNWnsun/bin. For example, to append /opt/SUNWnsun/bin to PATH:, enter:
$ set PATH ${PATH}:/opt/SUNWnsun/bin; export PATH
LD_LIBRARY_PATH must also include the /opt/SUNWnsun/bin directory. To append /opt/SUNWnsun/bin to LD_LIBRARY_PATH, enter:
$ set LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/opt/SUNWnsun/bin
$ export LD_LIBRARY_PATH
If LD_LIBRARY_PATH does not contain /opt/SUNWnsun/bin, the following error messages appears when you compile a program:
ld.so.1: cobol: fatal: liblicense.so: can't open file: errno=2
If you are using Sun Nihongo COBOL, you may want to rename the makefile names to match the examples and create a backup copy of the files. For example,
For Pro*COBOL 8.1.7, enter:
$ 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.52, enter:
$ cd $ORACLE_HOME/precomp/demo/procob $ mv demo_procob18.mk demo_procob.mk.mf $ cp procob.mk.nsun procob.mk
Oracle provides its own complete run time system, called rtsora, to run dynamically loadable Pro*COBOL programs. The rtsora run time system should be used in place of the MicroFocus provided cobrun run time system when running 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 various 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 exist in the SCOTT schema with the password TIGER. By default, the demonstration programs are dynamically linked with the $ORACLE_HOME/lib/libclntsh.so client shared library.
The demonstration makefile should be used to create the sample programs. The demonstration makefile for Pro*COBOL 8.1.7 is demo_procob.mk located in the $ORACLE_HOME/precomp/demo/procob2 directory. The demonstration makefile for Pro*COBOL 1.8.52 is demo_procob18.mk located in the $ORACLE_HOME/precomp/demo/procob directory.
For example, to precompile, compile, and link the sample1 demonstration program for Pro*COBOL 8.1.7, use the following command:
$ cd $ORACLE_HOME/precomp/demo/procob2 $ make -f demo_procob.mk sample1
To create 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 rtsora, enter:
$ make -f demo_procob.mk sample1.gnt $ rtsora sample1.gnt
Some demonstration programs require you to run a SQL script found in $ORACLE_HOME/precomp/demo/sql. If you do not run the script, a message will be displayed 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 calldemo.sql script located in the $ORACLE_HOME/precomp/demo/sql directory, enter:
$ make -f demo_procob.mk sample9 RUNSQL=run
|
See Also:
For information about 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 Pro*COBOL Precompiler. |
You can use demo_procob.mk to create user programs. Be sure to use the appropriate makefile depending on the Pro*COBOL version and COBOL compiler used. The syntax for linking a user program with the demonstration makefile is:
$ make -f demo_procob.mk target COBS="cobfile1 cobfile2 ..." EXE=exename
where
target is the makefile target that will be used (for example, build)
objfilen is the object file to link the program
EXE is the executable program
For example, to create the myprog program from the Pro*COBOL source myprog.pco, enter one of the following lines, depending on the type of executable and the use of shared library resources.
For a dynamically linked executable with client shared library, enter:
$ make -f demo_procob.mk build COBS=myprog.cob EXE=myprog
For a statically linked executable without client shared library, enter:
$ make -f demo_procob.mk build_static COBS=myprog.cob EXE=myprog
For a dynamically loadable module usable with rtsora, enter:
$ 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.
Prior to using Pro*FORTRAN, verify that the correct version of the compiler is properly installed.
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. By default, all programs are dynamically linked with the client shared library $ORACLE_HOME/lib/libclntsh.a.
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:
$ make -f demo_profor.mk sample1
or
$ make -f demo_profor.mk build FORS=sample1.pfo EXE=sample1
To create the Pro*FORTRAN demonstration programs, enter:
$ make -f demo_profor.mk samples
Some demonstration programs require you to run a SQL script found in $ORACLE_HOME/precomp/demo/sql. If you do not run the script, a message will be displayed 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 about using SQL*Plus to build demonstration programs, see "Using Demonstration Tables" on page 3-3. For more information on Pro*FORTRAN precompilers, see Pro*FORTRAN Supplement to Oracle Precompilers. |
You can use demo_profor.mk 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
where
target is the makefile target that will be used (example, build)
objfilen is the object file to link the program
EXE is the executable program
For example, to create the program, myprog, from the Pro*FORTRAN source myprog.pfo, enter one of the following lines, depending on the type of executable.
For a dynamically linked executable with a 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
Prior to using SQL*Module for Ada, verify that the correct version of the compiler is properly installed.
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. By default, all programs are dynamically linked with the $ORACLE_HOME/lib/libclntsh.so client shared library.
The demonstration programs demcalsp and demohost assume that the sample college database created by $ORACLE_HOME/precomp/demo/sql/mktables.sql exists 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, build a demonstration program using the makeuser and loaddb. make targets. For example, to run the required SQL scripts and create the demohost program, enter:
$ make -f demo_modada.mk makeuser loaddb demohost
To create the SQL*Module for Ada demonstration programs, enter:
$ make -f demo_modada.mk samples
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:
$ make -f demo_modada.mk all
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.
The makefile demo_modada.mk, $ORACLE_HOME/precomp/demo/modada directory 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
|
See Also:
For information about using SQL*Plus to build demonstration programs, see "Using Demonstration Tables" on page 3-3. For further information on the demonstration programs see the Programmer's Guide to SQL*Module for Ada, Release 8.0. |
You can use the makefile demo_modada.mk located in the $ORACLE_HOME/precomp/demo/modada directory to create programs. The 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 Oracle Call Interface (OCI), verify that the correct version of Pro*C/C++ is properly installed.
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. By default, all programs are dynamically linked with the client shared library $ORACLE_HOME/lib/libclntsh.a.
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.
Use the makefile demo_rdbms.mk located in the $ORACLE_HOME/rdbms/demo directory to create the demonstration programs. For example, to compile and link cdemo1, enter:
$ make -f demo_rdbms.mk cdemo1
To create the OCI C demonstration programs, enter:
$ make -f demo_rdbms.mk demos
To create the OCI C++ demonstration programs, enter:
$ make -f demo_rdbms.mk c++demos
Some demonstration programs require you to run a SQL script found in $ORACLE_HOME/rbdms/demo. If you do not run the script, a message will be displayed 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 about using SQL*Plus to build demonstration programs, see "Using Demonstration Tables" on page 3-3. 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 following error messages can appear when you link to 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
If you receive these error messages, include the directory in which the specified libraries exist in the LD_LIBRARY_PATH.
For example, if you are using SPARCompiler C++ 4.0 and the directory is /opt/SUNWspro/SC4.0/lib, enter:
$ LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:opt/SUNWspro/SC4.0/lib $ export LD_LIBRARY_PATH
You can use the demo_rdbms.mk makefile located in the $ORACLE_HOME/rdbms/demo directory to create programs. The syntax for linking a user program with demo_rdbms.mk is:
$ make -f demo_rdbms.mk target OBJS="objfile1 objfile2 ..." EXE=exename
where
target is the makefile target that will be used (example, build)
objfilen is the object file to link the program
EXE is the executable program
For example, to create the myprog program from the C/C++ source myprog.c, enter one of the following lines, depending on the type of executable:
To create the myprog program from the C source, dynamically linked with a 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
Oracle Corporation recommends that you use the provided demo_product.mk makefiles to link user programs. If you modify the provided makefile, or if you use a custom-written makefile, the following restrictions apply:
nmake or GNU make, be aware of how macro and suffix processing differs from the make utility provided with the Solaris make utility. 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.
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.
Following is an example of the output from the symfind utility which located 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 ...
[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.
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 5-4 describes the signals Oracle8i uses for two-task communications.
The 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 signal handlers for other signals. If you are not connected to the oracle process, you can have more than one signal handler.
The following example shows how to 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 is a template for using osnsui() and osncui() 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. */ ... } ...
}
Oracle Call Interface has 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 the XA dynamic registration (Oracle XA switch xaoswd).
Because Oracle8i does not support Oracle7 release 7.1.6 XA calls (although it does support Oracle7 7.3 XA calls), 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.
|
 Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|