Skip Headers

Oracle8i Server User's Guide
Release 3 (8.1.7) for Fujitsu Siemens Computers BS2000/OSD

Part Number A95463-01
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

5
Programmatic Interfaces

This chapter provides BS2000/OSD-specific information that supplements the documentation for the individual precompilers (such as Pro*C), and host language calls (the Oracle Call Interface). It includes information on the following topics:

Overview

The Oracle Programmatic Interfaces are tools for application designers who wish to use SQL statements to access an Oracle Server database from within high-level language programs. There are two types of programmatic interface available:

Under BS2000/OSD, the Oracle system precompilers support programs written in C, C++ and COBOL programming languages.
For more detailed information, refer to Oracle8i Server Application Development Guide and the appropriate supplementary publication(s) from the following list:

Architecture of the Programmatic Interfaces

All precompiler and Oracle Call Interface (OCI) applications are link-edited with a small stub module. The stub module dynamically loads the bulk code of the Oracle precompiler software from the ORALOAD library (using the BIND system macro). Programs written in the different languages listed below can be combined:

The Oracle precompilers generate different SQLLIB function names for different languages. The following names are used:

PL/SQL

The precompilers support PL/SQL as described in the PL/SQL User's Guide and Reference. When using PL/SQL, you need to specify SQLCHECK=FULL or SQLCHECK=SEMANTICS on the precompiler option line. The default is SQLCHECK=NONE. When requesting SQLCHECK, the precompiler needs to connect to a database, so ensure you provide the necessary connection information (you also may wish to set the DEFAULT_CONNECTION variable in the ORAENV file).

When SQLCHECK=SEMANTICS you must also specify USERID=username/password.

Building and Executing a Programmatic Interface Application

Follow the steps outlined below to build and execute a programmatic interface application. In addition, refer to the specific notes for the programmatic interfaces in this chapter.

  1. Edit your source code, including embedded SQL, as outlined in the generic precompiler documentation.

  2. Pre-process the source with the corresponding pre-processor.


    Note:

    You do not need to do this if you are building an OCI C or an OCI COBOL application.


  3. Compile the application.

  4. Link-edit the application, including the appropriate stub module from the PRO.language.LIB. You also need the ORASQL.LIB and the language-specific link library.

  5. Identify the ORALOAD library, using a SET-FILE-LINK command (usually this is included in your ORAENV procedure).

  6. Run the application. The supporting Oracle Server user module is dynamically loaded from the ORALOAD library.

  7. You can find sample files in the installation userid: $ORACL817.P.PROC, $ORACL817.P.PROCOB and $ORACL817.P.PROLNK.

Figure 5-1 illustrates the sequence of events outlined in the numbered list above, and how the programmatic interfaces make use of the program libraries:

Text description of fig5-1.gif follows.

Text description of the illustration fig5-1.gif

Figure 5-1 Programmatic interfaces use of Program Libraries

Existing Applications

Existing Applications must be pre-processed, compiled and linked anew.

Precompilers

The Oracle precompilers shipping with this release of BS2000/OSD provide BS2000-LMS-Functionality for the following files:

This improves the possibility of saving disk resources and provides you with more of an overview for grouping files in different libraries.

All LMS-library elements to be used must be of element-type "S". Pro* generates elements of type "S" if libraries are used. When you use LMS elements, the precompiler builds temporary files with the prefix "#T.", which are deleted when the preprocessing completes successfully.

When you use LMS library elements, the element name you specify must be the full element name including the suffix. Pro* does not append the suffix to the element name.

Include Files

All standard include files are now shipped under the new LMS library, $ORACL817.PRO.INCLUDE.LIB. You must enter either this library or a user-defined include library for EXEC SQL INCLUDE statements using the INCLUDE precompiler option as follows:

* INCLUDE=$ORACL817.PRO.INCLUDE.LIB \
* INCLUDE=mylibrary

where mylibrary is the BS2000 filename of the user-defined library, such as PROC.INCLIB.


Attention:

The order in which you specify different INCLUDE-Options affects the performance of precompilation. You should place commonly-used files before rarely-used ones.


User-Specific Configuration Files

You can also specify a user-specific configuration file as an LMS-element using the following syntax:

* CONFIG=my_config_lib[config_element]

where my_config_lib is the BS2000 filename of the configuration library and config_element is the full name of the element.


Attention:

You must use square brackets when specifying the configuration element.


For example:

* CONFIG=CONFIG.LIB[PROCOB.CFG]

Input-, Output-, and List-files

As well as using BS2000-files you can benefit from using LMS-elements for precompiler I/O using the options INAME, ONAME and LNAME.

As in previous releases, if you do not specify a library filename and an element from it, the Oracle precompilers generate ISAM BS2000-files by default. The only option that you must enter is the INAME option. That can be either a BS2000 filename (SAM or ISAM) or a library filename and the name of an element from it.

* INAME=my_input_lib[my_element]
* ONAME=my_output_lib[my_element]
* LNAME=my_list_lib[my_element]

where my_input_lib is the BS2000 filename of the particular library and my_element is the name of the element including the specific suffix.


Attention:

You must use square brackets when specifying the appropriate element.


In the following example, Pro*C generates a BS2000-ISAM-output file called "SAMPLE.C" as the ONAME option has been omitted:

* INAME=INPUT.LIB[SAMPLE.PC] \
* LNAME=LIST.LIB[SAMPLE.LST]

Additional Remarks

The following are additional remarks on this release of Oracle8i Release 3 Server for Fujitsu Siemens Computers BS2000/OSD.

Pro*C/C++

Invoking Pro*C

To invoke the Pro*C precompiler, enter the following:

/START-PROGRAM $ORACL817.PROC 
* INAME=myprog.PC ONAME=myprog.C [options]

where:

myprog
is the name of the C program you wish to compile and link.

options
is one of the PROC options. Refer to the Pro*C Supplement to the Oracle Precompilers Guide for a list and description of the valid options.


Attention:

Unlike as described in Programmer's Guide for Pro*C/C++ Precompiler you must use one Precompiler-Option INCLUDE for each path you want to specify. A list as allowed for the option SYS_INCLUDE may cause the precompiler to loop! See Include-Option for Pro*COBOL


Pro*C Include, System Configuration and Demo Files

The Pro*C "include files", demo files, and system configuration file are shipped under:

$ORACL817.PRO.INCLUDE.LIB
$ORACL817.C.DEMO.*.PC
$ORACL817.UTM.DEMO.*.PC
$ORACL817.CONFIG.PCSCFG.CFG 

An example of a (pre-)compilation procedure is included on your distribution tape under the name $ORACL817.P.PROC.

SQLLIB Calls

If you wish to code explicit C calls to SQLLIB functions, you must call SQ2XXX instead of SQLXXX. For example, call SQ2CEX instead of SQLCEX.

Linking Pro*C

To link a Pro*C program, you need:

To link your program, you should create your own user-specific link procedure. An example of such a link procedure is included on your distribution tape under the name, $ORACL817.P.PROLNK.

The Pro*C SQLCPR.H Header File

If you are making calls to Pro*C functions, such as sq2cls() or sq2glm(), you can include the SQLCPR.H file in your C programs to verify that you have called the function(s) correctly.

In your Pro*C programs add the following line:

EXEC SQL INCLUDE SQLCPR;

as you would for SQLCA or SQLDA.

UTM Applications

You can use Pro*C to write UTM program units. See the Installation and Database Administration Guide for UTM programming rules.

Pro*COBOL

Invoking Pro*COBOL

To invoke the Pro*COBOL precompiler, enter the following:

/START-PROGRAM $ORACL817.PROCOB
* INAME=myprog.PCO ONAME=myprog.COB [options]
 

where:

myprog
specifies the COBOL program to compile and link

options
is one of the PROCOB options described in the Pro*COBOL Supplement to the Oracle Precompilers Guide.


Note:

The PROCOB option MAXLITERAL defaults to 180, not 256 as shown in the Pro*COBOL Supplement to the Oracle Precompilers Guide. The option FORMAT=TERMINAL is not supported.


Pro*COBOL Include, System Configuration, and Demo Files

The Pro*COBOL "include files", demo files and system configuration file are shipped under:

$ORACL817.PRO.INCLUDE.LIB
$ORACL817.COBOL.DEMO.*.PCO
$ORACL817.UTM.DEMO.*.PCO
$ORACL817.CONFIG.PCBCFG.CFG

An example of a (pre-)compilation procedure is included on your distribution tape under the name $ORACL817.P.PROCOB.

SQLLIB Calls

If you want to code explicit COBOL calls to SQLLIB functions, call SQ0XXX instead of SQLXXX. For example, call SQ0ADR instead of SQLADR.

Linking Pro*COBOL

To link a Pro*COBOL program, you need:

To link your program, you should create your own user-specific link procedure. An example of such a link procedure is included on your distribution tape under the name, $ORACL817.P.PROLNK.

openUTM Applications

You can use Pro*COBOL to write openUTM program units. See the Installation and Database Administration Guide for openUTM programming rules. Program units written in Pro*C and Pro*COBOL can be combined.

The Oracle Call Interface

Under BS2000/OSD, the Oracle Call Interface supports the C and COBOL languages.

When you use the set of "host language calls" that make up the Oracle Call Interface, you can access the data in an Oracle Server database by programs written in the C and COBOL programming language. OCI calls are fully described in the Programmers Guide to the Oracle Call Interfaces.

For restrictions refer to Installation and Database Administration Guide (see section Known Problems, Restrictions and Workarounds).

Note that the precompiler products from Oracle Corporation offer a higher-level interface to Oracle Server (one precompiler call is translated to several OCI calls). As the precompilers are simpler to use, and in a few cases offer more (or different) functionality than OCI, you may prefer to use the precompilers for some applications.

Linking Instructions

To link compiled C and COBOL program files, you should create your own user-specific link procedure. An example of such a link procedure is included on your distribution tape under the name, $ORACL817.P.PROLNK.

For example, to link your program using this sample procedure, enter the following:

/CALL-PROCEDURE $ORACL817.P.PROLNK,dir,module,TYPE=OCIC 

or:

/CALL-PROCEDURE $ORACL817.P.PROLNK,dir,module,TYPE=OCICOB

where the module to be linked is stored in dir.LIB.

Example files are shipped under:

$ORACL817.RDBMS.DEMO.*.C
$ORACL817.RDBMS.DEMO.*.COB

If you want to use new OCI8 functions you must use BINDER instead of TSOSLNK because of longer C-function names.

Data Areas and Data Types

The Cursor Data Area

The cursor data area is described in the Programmers Guide to the Oracle Call Interfaces.

Binary Integers

Binary integers are described in the generic documentation and correspond to binary fullwords (32 bits) in BS2000/OSD.

Short Binary Integers

Short binary integers are described in the generic documentation and correspond to binary halfwords (16 bits) in BS2000/OSD.

Optional Parameters

C does not allow you to omit optional parameters. This means that all parameters must be specified (see the sample C program).

If a length parameter is -1, the length is determined by scanning the associated string parameter for a null byte. Missing address parameters may be specified as NULL. In C, the -1 should be cast to the proper type.

For COBOL, you may omit optional trailing parameters and the call interface provides default values.

The Object Type Translator

Invoking Ott

To invoke the Object Type Translator, enter the following:

/START-PROGRAM $ORACL817.OTT 
*<options>

where <options> are Ott-Options as described in the Oracle Precompiler Guide, e.g.:

*userid=scott/tiger intype=$oracl817.ott.demo.demoin.typ
outtype=demoout.typ code=c hfile=demo.h

Ott System Configuration and Demo Files

The Ott demo files and system configuration file are shipped under:

$ORACL817.OTT.DEMO.*
$ORACL817.CONFIG.OTTCFG.CFG 

Use $ORACL817.OTT.DEMO.TYPE.SQL to create object type employee.


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

All Rights Reserved.
Go To Table Of Contents
Contents
Go To Index
Index