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 (OCI), that enables to create high-level language applications that use function calls to access an Oracle database and control all phases of SQL statement execution.

Under BS2000/OSD, the Oracle Database precompilers support programs written in C, C++, and COBOL programming languages.

For more detailed information about Oracle Precompilers, see Oracle Database Programmer's Guide to the Oracle Precompilers and the appropriate supplementary publications from either Pro*C/C++ Programmer's Guide or Pro*COBOL Programmer's Guide.

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 Support

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

To build and run a programmatic interface application, perform the following steps:

  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 to build an OCI C or an OCI COBOL application.

  3. Compile the application.

  4. Link 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 module is dynamically loaded from the ORALOAD library.

  7. You can find sample BS2000 procedures for precompiling, compiling, and linking 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 use 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"

For more information, see the specific notes for the programmatic interfaces in this chapter.

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 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 library 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 that 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 specify 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.

Note:

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.

You must use brackets when specifying the configuration element, as shown in the following example.

* CONFIG=CONFIG.LIB[PROCOB.CFG]

5.2.2.3 Input, Output, and List-files

Besides using BS2000 files, you can also use LMS library 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 describes 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. For a list and description of the valid options, see Pro*C/C++ Programmer's Guide.

Note:

You must use one Precompiler-option INCLUDE for each path you want to specify, unlike as described in Pro*C/C++ Programmer's Guide. 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

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. For UTM programming rules, see Oracle Database Installation and Administration Guide for Fujitsu BS2000/OSD.

5.4 Pro*COBOL

This section describes the procedure for using Pro*COBOL. You must follow these 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 the SQL-LABEL1 heading 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 when precompiling existing applications may result in run-time error ORA-1403: no data found.

For more information, see 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

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. For more information about the GNLCNV entry, see Fujitsu User's Guide XHCS for BS2000.

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 (Universal Transaction Monitor) program units. For openUTM programming rules, see Oracle Database Installation and Administration Guide for Fujitsu BS2000/OSD. 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 comprise 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, see "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 the following sample procedure:

/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 support optional parameters. Hence, all parameters must be specified. (See 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 Oracle Database Applications in POSIX

Starting with Oracle Database 11.2.0.4, application programs cannot only run in the ”normal” BS2000 environment but also in the POSIX environment. This section describes how you can build Oracle Database applications that can run in the POSIX environment.

You must precompile and compile the Pro* application or OCI application as described in the previous chapters.

When linking the application, you have to include Oracle stub module PROSTUBX instead of PROSTUB and you must add the following lines in the BS2000 procedure for linking:

/   SET-FILE-LINK BLSLIB01,$.SYSLNK.CRTE.POSIX
/   SET-FILE-LINK BLSLIB02,$.SYSLIB.POSIX-SOCKETS.<version_number>

Note:

These two libraries must be the first libraries in the search order for the resolution of unresolved external references.

To start an Oracle Database application in the POSIX environment by using BS2000 SDF commands, set the BS2000 SDF-P variable SYSPOSIX.PROGRAM-ENVIRONMENT to SHELL.

You can set additional POSIX environment variables by using the BS2000 SDF-P variable SYSPOSIX.

The following example shows how to set the SDF-P variable SYSPOSIX to run an application in the POSIX environment:

/DECL-VAR SYSPOSIX,TYPE=*STRUCT(DEF=*DYN),SCOPE=*TASK(STATE=*ANY)
/SET-VAR SYSPOSIX.PROGRAM-ENVIRONMENT='SHELL'
/SET-VAR SYSPOSIX.ORACLE-HOME='<oracle_home_path>'
/SET-VAR SYSPOSIX.ORACLE-SID='<oracle_sid>'

5.7 The Object Type Translator

This section describes the port-specific notes for using the Object Type Translator (OTT).

5.7.1 Starting OTT

The OTT is based on Java and can only be started in the POSIX environment. You must use the JDBC Thin driver to connect to the database. The connect string is specified 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

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

See Also:

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

5.7.2 OTT System Configuration File

The OTT system configuration file is shipped under:

$ORACLE_HOME/precomp/admin/ottcfg.cfg