This chapter provides BS2000/OSD-specific information that supplements the documentation for the individual precompilers (such as Pro*C), and host language calls (Oracle Call Interface). It includes information on the following topics:
Oracle Programmatic Interfaces are tools for application designers who wish to use SQL statements to access an Oracle Database from within high-level language programs. The following types of programmatic interfaces are available:
The Precompiler Interface, which is a programming tool that enables you to embed SQL statements in high-level language source code
The Oracle Call Interface, which allows high-level language applications to access data in an Oracle Database by making direct calls to the Oracle Database kernel
Under BS2000/OSD, the Oracle system precompilers support programs written in C, C++, and COBOL programming languages.
For more detailed information on Oracle Precompilers, refer to Oracle Database Programmer's Guide to the Oracle Precompilers and the appropriate supplementary publications from the following list:
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 (by using the BIND
system macro). Programs written in the following languages can be combined:
Pro*C/C++
Pro*COBOL (COBOL85 and COBOL2000)
Note:
OCI C and OCI COBOL programs cannot be combined together; any attempt to do so results in execution errors. The entries into the Oracle Database used by OCI C and OCI COBOL (for example, OLOGON) have identical names but different argument lists (for OCI COBOL, all arguments are by reference, that is, the parameter list contains all pointers, whereas for OCI C, the numeric arguments are by value).Oracle precompilers generate different SQLLIB
function names for different languages. The following names are used:
SQ0XXX:
COBOL
SQ2XXX:
C
The precompilers support PL/SQL as described in the Oracle Database PL/SQL Language Reference . When using PL/SQL, you must specify SQLCHECK=FULL
or SQLCHECK=SEMANTICS
on the precompiler option line. The default is SQLCHECK=NONE
. When requesting SQLCHECK
, the precompiler must connect to a database. So, ensure that you provide the necessary connection information. (You may also wish to set the DEFAULT_CONNECTION
variable in the ORAENV
file).
When SQLCHECK=SEMANTICS
you must also specify USERID=username/password
.
Perform the following steps to build and run a programmatic interface application. For additional details, refer to the specific notes for the programmatic interfaces in this chapter.
Edit your source code, including embedded SQL, as outlined in the generic precompiler documentation.
Pre-process the source with the corresponding pre-processor.
Note:
You must use WE8BS2000 as client charset during precompilation (set inORAENV
file). Any other charset might lead to problems with concatenation sign ("||").
You do not need to precompile if you are building an OCI C or an OCI COBOL application.
Compile the application.
Link-edit the application, including the stub module PROSTUB
from the PRO.LIB
.
Identify the ORALOAD
library by using a SET-FILE-LINK
command. (Usually, this is included in the ORAENV
procedure).
Run the application with the START-PROG
command. The supporting Oracle Database user module is dynamically loaded from the ORALOAD
library.
You can find sample files in the installation user ID: $ORAC1020.P.PROC, $ORAC1020.P.PROCOB and $ORAC1020.P.PROLNK
.
Figure 5-1 illustrates the sequence of events outlined in the preceding numbered list and how the programmatic interfaces make use of the program libraries.
Figure 5-1 Usage of Program Libraries by Programmatic Interfaces
Oracle precompilers shipped with this release of BS2000/OSD provide BS2000-LMS-Functionality for the following files:
This functionality 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.
All standard include files are shipped under the LMS library, $ORAC1020.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=$ORAC1020.PRO.INCLUDE.LIB \ * INCLUDE=mylibrary
where mylibrary
is the BS2000 file name 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.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 file name of the configuration library and config_element is the full name of the element.
Note:
You must use brackets when specifying the configuration element, as shown in the following example.For example:
* CONFIG=CONFIG.LIB[PROCOB.CFG]
Besides using BS2000 files, you can also 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 file name and an element from it, then 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 file name (SAM
or ISAM
) or a library file name and the name of an element from it.
For example,
* 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 file name of the particular library and my_element is the name of the element including the specific suffix.
Note:
You must use 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]
The following are additional remarks on this release of Oracle Database 10g release 2 (10.2) for Fujitsu Siemens Computers BS2000/OSD.
Only compilers and compiler versions supporting the ILCS Standard Linkage are supported. If the Oracle Database detects a call from a user program not using Standard Linkage conventions, then it terminates the task and displays message number 5002 or 5003.
If ONAME
is not specified when starting a precompiler, then the precompiler generates a default name which consists of the last part of INAME
with the relevant suffix. For example, if the name of the C program you wish to compile is MYPROG.PERS.TEST.PC
, and if ONAME
is omitted, then Pro*C generates an output file with the name TEST.C
.
If you work with float variables, then you may encounter rounding problems. The workaround is to declare the float variables as double variables instead.
This section discusses the procedure for using Pro*C/C++.
To start the Pro*C precompiler, enter the following:
/START-PROGRAM $ORAC1020.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/C++ Programmer's Guide for a list and description of the valid options.
Note:
Unlike as described in Pro*C/C++ Programmer's Guide, you must use one Precompiler-optionINCLUDE
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*C/C++.The Pro*C include files, demo files, and system configuration file are shipped under:
$ORAC1020.PRO.INCLUDE.LIB $ORAC1020.C.DEMO.*.PC $ORAC1020.UTM.DEMO.*.PC $ORAC1020.CONFIG.PCSCFG.CFG
An example of a compilation and precompilation procedure is included in the Oracle Database Software under the name $ORAC1020.P.PROC
.
If you wish to code explicit C calls to SQLLIB
functions, then you must call SQ2
XXX
instead of SQL
XXX
. For example, call SQ2CEX
instead of SQLCEX
.
To link a Pro*C program, you need:
The Common Run-Time Environment, CRTE
.
The Pro* library ($ORAC1020.PRO.LIB
), which contains the stub module, PROSTUB.
At run time, this module loads the pre-linked module, ORAPRO
, which contains the actual SQLLIB
code.
Note:
You must useBINDER
instead of TSOSLNK
.To link your program, you should create your user-specific link procedure. An example of such a link procedure is included in the Oracle Database Software under the name, $ORAC1020.P.PROLNK
.
If you are making calls to Pro*C functions, such as sq2cls()
or sq2glm()
, then you can include the SQLCPR.H
file in the C programs to verify that you have called the functions correctly.
In the Pro*C programs add the following line:
EXEC SQL INCLUDE SQLCPR
as you would for SQLCA
or SQLDA
.
You can use Pro*C to write UTM program units. Refer to Oracle Database Installation and Administration Guide for Fujitsu Siemens BS2000/OSD for UTM programming rules.
This section discusses the procedure for using Pro*COBOL. You must follow these special considerations, when using Pro*COBOL:
Host variables of the type PIC S9(
n
)
with n
=8 and n >10
are not supported.
The COB1
compiler is not supported on Oracle Database 10g release 2 (10.2) for BS2000/OSD. If you still have applications based on COB1
, then you cannot relink them with Oracle Database 10g release 2 (10.2). Instead, you must first precompile them with the new Pro*COBOL precompiler, then recompile them using the newer COBOL85 resp. COBOL2000 compiler.
When using Pro*COBOL be careful about the following constructions with paragraphs and EXEC
statements, because the precompiler generates a paragraph heading for the code generated from these EXEC
statements.
Before precompiling | After precompiling |
---|---|
COB-LABEL1. | COB-LABEL1 |
. | . |
. | . |
EXEC SQL .... | SQL-LABEL1. |
. | . |
. | . |
COB-LABEL2. | COB-LABEL2. |
Before precompiling, the statement PERFORM COB-LABEL1
runs the code in paragraph COB-LABEL1
until the COB-LABEL2
heading is reached. However, the precompiler generates a paragraph heading, SQL-LABEL1
, for the code generated from the EXEC SQL
statement.
As a result, after precompiling, PERFORM COB-LABEL1
runs the code in the paragraph, COB-LABEL1
, until SQL-LABEL1
is reached. The workaround for this problem is to use SECTIONS
or to run PERFORM COB-LABEL1 THRU COB-LABEL2
.
A COPY
statement as first statement in WORKING STORAGE SECTION
may result in wrong code generation if copied structures are to be continued by non-copied code because the precompiler generates its data definitions before the first data definition of the source program. To avoid this action, insert one FILLER
definition as first line in WORKING-STORAGE SECTION
as follows:
01 FILLER PIC X
The default data type for PIC X
variables has changed in version 8.1.7 from VARCHAR2
to CHARF
. A precompiler option provides backward compatibility: PICX={VARCHAR2 | CHARF (default)}
.
This option is allowed only on the command line or in a configuration file. The new default action is consistent with the usual COBOL move action.
Note:
Using the defaultPICX=CHARF
while precompiling existing applications may result in run-time error ORA-1403: no data found
.For more details, refer to the chapter "Precompiler Options, in Pro*COBOL Programmer's Guide.
To start the Pro*COBOL precompiler, enter the following command:
/START-PROGRAM $ORAC1020.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 Programmer's Guide.
Note:
The PROCOB option MAXLITERAL defaults to 180, not 256, as shown in the Pro*COBOL Programmer's Guide . The option FORMAT=TERMINAL is not supported.The Pro*COBOL include files, demo files, and system configuration file are shipped under:
$ORAC1020.PRO.INCLUDE.LIB $ORAC1020.COBOL.DEMO.*.PCO $ORAC1020.UTM.DEMO.*.PCO $ORAC1020.CONFIG.PCBCFG.CFG
An example of a compilation and precompilation procedure is included in your Oracle Database Software under the name $ORAC1020.P.PROCOB
.
If you want to code explicit COBOL calls to SQLLIB
functions, then call SQ0
XXX
instead of SQL
XXX
. For example, call SQ0ADR
instead of SQLADR
.
To link a Pro*COBOL program, you need:
The Common Run-Time Environment, CRTE
.
The Pro* Library ($ORAC1020.PRO.LIB
), which contains the stub module, PROSTUB.
At run time, this module loads the pre-linked module, ORAPRO
, which contains the actual SQLLIB
code.
Note:
You must use BINDER instead of TSOSLNK.To link your program, you should create your own user-specific link procedure. An example of such a link procedure is included on your Oracle Database Software under the name, $ORAC1020.P.PROLNK
.
You can use Pro*COBOL to write openUTM program units. Refer to Oracle Database Installation and Administration Guide for Fujitsu Siemens BS2000/OSD for openUTM programming rules. Program units written in Pro*C and Pro*COBOL can be combined.
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 Database by programs written in the C and COBOL programming languages. OCI calls are fully described in the Oracle Call Interface Programmer's Guide .
For restrictions refer to the section, Known Problems, Restrictions and Workarounds in Oracle Database Installation and Administration Guide for Fujitsu Siemens BS2000/OSD.
Note that the precompiler products from Oracle offer a higher level interface to the Oracle Database (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.
To link OCI program files, you need:
The Common Run-Time Environment, CRTE.
The Pro* Library ($ORAC1020.PRO.LIB
), which contains the stub modules OCI$COB
and PROSTUB.
At run time, PROSTUB
loads the prelinked module ORAPRO
, which contains the actual SQLLIB
code.
When linking OCI COBOL programs, OCI$COB
must always be included before PROSTUB
.
Note:
You must use BINDER instead of TSOSLNK.To link your program, you should create your own user-specific link procedure. An example of such a link procedure is included in your Oracle Database Software under the name $ORAC1020.P.PROLNK
.
For example, to link your program using this sample procedure, enter the following:
/CALL-PROCEDURE $ORAC1020.P.PROLNK,dir,module,TYPE=OCIC
or:
/CALL-PROCEDURE $ORAC1020.P.PROLNK,dir,module,TYPE=OCICOB
where the module to be linked is stored in dir
.LIB
.
Example files are shipped under:
$ORAC1020.RDBMS.DEMO.*.C $ORAC1020.RDBMS.DEMO.*.COB
C does not omit optional parameters. This means that all parameters must be specified. (Refer to the sample C program).
If a length parameter is -1, then 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; the call interface provides default values.
This section discusses port-specific notes for using the Object Type Translator.
To start the Object Type Translator, enter the following:
/START-PROGRAM $ORAC1020.OTT8 *<options>
where <options> are Ott8-options as described in the Pro*C/C++ Programmer's Guide.
Example:
*userid=scott/tiger intype=$ORAC1020.ott8.demo.demoin.typ outtype=demoout.typ code=c hfile=demo.h