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 (Oracle Call Interface). It includes information about the following topics:

5.1 Overview

Oracle Programmatic Interfaces are tools for application designers who want 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 Database precompilers support programs written in C, C++, and COBOL programming languages.

For more detailed information about Oracle Precompilers, refer to Oracle Database Programmer's Guide to the Oracle Precompilers and the appropriate supplementary publications from the following list:

5.1.1 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 (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

5.1.2 PL/SQL

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 want to set the DEFAULT_CONNECTION variable in the ORAENV file).

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

5.2 Building and Running a Programmatic Interface Application

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.

  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 must use WE8BS2000 as client character set during precompilation (set in ORAENV file). Any other character set 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.

  3. Compile the application.

  4. Link-edit the application, including the stub module PROSTUB from the PRO.LIB.

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

  6. Run the application with the START-PROG command. The supporting Oracle Database user module is dynamically loaded from the ORALOAD library.

  7. You can find sample files in the installation user ID: $ORAC1120.P.PROC, $ORAC1120.P.PROCOB and $ORAC1120.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

Description of Figure 5-1 follows
Description of "Figure 5-1 Usage of Program Libraries by Programmatic Interfaces"

5.2.1 Existing Applications

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

5.2.2 Precompilers

Oracle Database precompilers on BS2000/OSD support LMS libraries for the following files:

This functionality improves the possibility of saving disk resources and provides you clarity by 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.

5.2.2.1 Include Files

All standard include files are shipped in the LMS library, $ORAC1120.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=$ORAC1120.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.

5.2.2.2 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 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]

5.2.2.3 Input, Output, and List-files

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

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]

5.2.3 Additional Remarks

The following are additional remarks on this release of Oracle Database 11g Release 2 (11.2) for Fujitsu 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 want 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.

5.3 Pro*C/C++

This section discusses the procedure for using Pro*C/C++.

5.3.1 Starting Pro*C

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

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

where:

myprog is the name of the C program you want 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-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*C/C++.

5.3.2 Pro*C Include, System Configuration and Demo Files

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

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

An example of a compilation and precompilation procedure is included in the Oracle Database Software under the name $ORAC1120.P.PROC.

5.3.3 SQLLIB Calls

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

5.3.4 Linking Pro*C

To link a Pro*C program, you need:

  • The Common Run-Time Environment, CRTE.

  • The Pro* library ($ORAC1120.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 user-specific link procedure. An example of such a link procedure is included in the Oracle Database Software under the name, $ORAC1120.P.PROLNK.

5.3.5 The Pro*C SQLCPR.H Header File

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.

5.3.6 UTM Applications

You can use Pro*C to write UTM program units. Refer to Oracle Database Installation and Administration Guide for Fujitsu BS2000/OSD for UTM programming rules.

5.4 Pro*COBOL

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.

  • 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 default PICX=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.

5.4.1 Starting Pro*COBOL

To start the Pro*COBOL precompiler, enter the following command:

/START-PROGRAM $ORAC1120.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.

5.4.2 Pro*COBOL Include, System Configuration, and Demo Files

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

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

An example of a compilation and precompilation procedure is included in your Oracle Database Software under the name $ORAC1120.P.PROCOB2000.

5.4.3 SQLLIB Calls

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

5.4.4 Linking Pro*COBOL

To link a Pro*COBOL program, you need:

  • The Common Run-Time Environment, CRTE.

  • The Pro* Library ($ORAC1120.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.

  • Unicode is only supported with COBOL2000. This might generate calls to the BS2000-Macro NLSCNV. To resolve the GNLCNV entry, use the system XHCS library. Refer to Fujitsu User's Guide XHCS for BS2000 for more information about the GNLCNV entry.

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, $ORAC1120.P.PROLNK.

5.4.5 openUTM Applications

You can use Pro*COBOL to write openUTM program units. Refer to Oracle Database Installation and Administration Guide for Fujitsu BS2000/OSD for openUTM programming rules. Program units written in Pro*C and Pro*COBOL can be combined.

5.5 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 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 "Known Problems, Restrictions and Workarounds" in Oracle Database Installation and Administration Guide for Fujitsu BS2000/OSD.

Note:

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.

5.5.1 Linking OCI

To link OCI program files, you need:

  • The Common Run-Time Environment, CRTE.

  • The Pro* Library ($ORAC1120.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 $ORAC1120.P.PROLNK.

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

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

or:

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

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

Example files are shipped under:

$ORAC1120.RDBMS.DEMO.*.C 
$ORAC1120.RDBMS.DEMO.*.COB

5.5.2 Optional Parameters

C does not omit optional parameters. Hence, 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.

5.6 The Object Type Translator

This section discusses port-specific notes for using the Object Type Translator.

5.6.1 Starting Ott

As the Object Type Translator is based on Java it can only be started in the POSIX environment. You must use the JDBC Thin driver to connect to the database. The connect string is published in the url-option as follows:

url=jdbc:oracle:thin:@hostname:port:sid

In the following example, OTT will connect to the database with the service identifier orcl, on the host myhost, that has a TCP/IP listener on port 1521.

For example:

ott userid=scott/tiger url=jdbc:oracle:thin:@myhost:1521:orcl intype=demoin.typ outtype=demoout.typ code=c hfile=demo.h

See Also:

Pro*C/C++ Programmer's Guide for more information about Object Type Translator.

5.6.2 Ott System Configuration File

The OTT system configuration file is shipped under:

$ORACLE_HOME/precomp/admin/ottcfg.cfg