Release 1 (9.0.1) for Alpha OpenVMS
Part Number A90868-01
 |  Contents |
 Index |
| Oracle9i Administrator's Reference Release 1 (9.0.1) for Alpha OpenVMS Part Number A90868-01 |
|
This chapter describes Oracle Precompilers and the Oracle Call Interface.
It contains the following topics:
Oracle precompilers are application-development 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 Oracle9i or any other ANSI SQL database management system.
System configuration files for the Oracle Precompilers are located in the ORA.ROOT:[PROGINT.EXE]directory. Table 9-1 lists the names of the system configuration files for each precompiler.
The following table lists products and their corresponding executable names.
|
Warning: When upgrading from previous versions (7.1 or earlier,) you must recompile all your programmatic interface programs using the appropriate compilers. |
The programmatic interfaces include:
SQL*Module is a development tool that facilitates building and managing large applications that access data in an Oracle database. SQL*Module is available for the Ada language.
|
Additional Information: For general information, see the user's guide and README files for the programming language you are using. |
The following figure shows the directory structure created when the following Oracle Programmatic Interfaces are installed.
Table 9-3 lists the location of the precompiler README files. The README files describe changes made to the precompiler since the last release.
You invoke the precompilers and SQL*Module generator by using the OpenVMS symbols specified in Table 10-1.
Use the following syntax to precompile source files:
$ <VMS_symbol> INAME=<filename> <option>=<value> ...
where:
OpenVMS symbol for the precompiler or SQL*Module.
Name of the source file you want to precompile.
Precompiling option available for the Oracle Precompilers program. You can supply any number of option-value pairs, separated by a space.
Value for the option specified.
$ PROFOR INAME=MYFILE HOST=FORTRAN INCLUDE=ORA_PRECOMP
The HOST=<language> identifier is optional. For example, the following command is also valid:
$ PROFOR INAME=MYFILE INCLUDE=ORA_PRECOMP
The INCLUDE option gives the path to the directory that contains the precompiler include files. If not supplied, the include path defaults to the directory in which the include files are distributed.
You can get a list of options and their values (if you have an Oracle instance running) by entering the appropriate symbol name, for example:
$ PROFOR
The system will display a list of options and their values for Pro*FORTRAN.
The following guidelines and restrictions apply to precompiling.
Precompiler programs can be run with the Alpha OpenVMS debugger by compiling the program with the /DEBUG qualifier and linking using the D option with the LNPRO<language> symbol.
If you use Alpha OpenVMS event flags in your source code, make sure none of them are numbered 1-18 before compiling the code for use against the Oracle Server. Event flags 1-18 are reserved for the Server.
When migrating applications developed with Pro*C precompilers, each application must have a unique SQLCA and/or ORACA. Oracle Corporation recommends that you insert the following definition in one module to produce a "defining declaration" of the SQLCA structure:
#DEFINE SQLCA_STORAGE_CLASS GLOBALDEF
Each of the other modules should have the following global reference to product "referencing declarations."
#DEFINE SQLCA_STORAGE_CLASS GLOBALREF
This line must precede SQLCA.H.
Ensure that the following conditions are met when using the precompilers listed in this section.
Oracle9i is compiled with as few deviations from the default C compiler options as possible and with minimal use of pragma statements.
Under the DEC C 6.4a AP compiler on Alpha OpenVMS, the compilation options are as follows for most modules:
/decc/nostandard/optimize/debug=trace
For the RDBMS, the following options are used on Alpha OpenVMS:
/decc/nostandard/debug=trace/optimize/prefix=all/gran=long
If you compile your code with /debug=trace, line numbers in your modules will appear, as appropriate, in Oracle9i stack trace listings.
Oracle9i is compiled with the default floating point format supported by the C compiler. The conversion routines within Oracle9i translate operating system-specific floating point numbers into Oracle9i internal floating point representation.
|
Note: Oracle precompiler and OCI programmers should take special note that Oracle9i Alpha OpenVMS is compiled to recognize the G_FLOAT floating point format. |
You must specify the /ANSI option when you compile the Pro*COBOL demo source files.
Use the following methods to link object files:
LNPRO<language>.COM is the standard, suggested linking method.
Use LNPRO<language>.COM to link precompiled files, object files, and SQL*Module files.
Use LOUTL.COM under special circumstances when LNPRO<language>.COM is not appropriate. If you decide to use LOUTL.COM, use a command syntax similar to that found in the appropriate LNPRO<language>.COM script.
To link compiled PRO<language> object files, use the LNPRO<language> symbol:
To link MYOBJ and SUB into an COB executable called MYFILE (and to specify options D, and M), use the following command:
$ LNPROCOB MYFILE MYOBJ,SUB DM
When you are using the Alpha OpenVMS linker, you sometimes give linker directives through standard input. When using the Oracle linking symbols (LNPROC, LNPROADA, etc.), however, you must put your directives into an options file, even if you only have one or two directives.
For example, the following statement is incorrect:
$ LNPROC MYPROG.EXE MYOBJ,SYS$INPUT/OPT
while the following command would work:
$ LNPROC MYPROG.EXE MYOBJ,MYOPT/OPT
where MYOPT is the options file.
When using the link scripts, you should be aware of the following guidelines:
Several sample programs, covering different aspects of precompiler programs, are provided in the PRO<language> demo directories. We recommend that you precompile, compile, and link these programs. You can use these programs as models for new programming efforts.
Before running the Proc Demos, make sure you define the following environment setting:
DEFINE SYS ORA_ROOT:[PROGINT.INCLUDE.DECC]
For more information on linking user exits, see the Developer/2000 for OpenVMS User's Guide.
Oracle Corporation makes every effort to ensure compatibility with the ANSI standard compilers supported by Compaq Computer Corporation. However, new functionality available with the latest compilers might not yet be supported.
You may link a shareable image against Oracle9i code using the LOUTL I and D options with LOUTL.COM or one of the LNPRO*.COM link scripts that internally calls LOUTL.COM. To eliminate missing file errors, also use the LOUTL flag LS (for Link Shareable).
You may want to install the shareable image in system memory with a command like:
$ install create/share/write/header <shareable_image>
To avoid receiving an error when you link your main program, including the shareable image in the link list with the option D for debug, also use the LOUTL option LD (for Link Debugger).
In summary, only use the LS option when linking the shareable using the I and D options and use the option LD when linking an executable image that uses this shareable. Or use both the LS and LD options when linking an executable image that uses this shareable.
Valid examples:
DS LS LD
SD LS LD
S LS
D LS
S LD MF
Examples that will fail:
LS S (the S option can not occur after the LS option)
SLD (space is missing between S and LD)
S D LSLD (space missing between LS and LD)
S LDMF (space missing between LD and M)
LOUTL looks for the symbol SHOW_LINK_COMMAND, which allows you to see the LINK command that is constructed by LOUTL.COM without waiting for a link map. If this symbol is defined to any non-null value, LOUTL displays the link command. If this symbol is undefined, LOUTL issues the link command silently.
All Oracle link scripts call LINK with the /NOUSERLIBRARY qualifier. This means that any libraries you want to link automatically using the LNK$LIBRARY logical names will be ignored. Therefore, explicitly include these libraries in your link line or via an option file.
OCI routines allow high-level language applications to access data in an Oracle database. Programs that use the OCI routines can make direct calls to Oracle subroutines; they need not be precompiled. C, FORTRAN, and COBOL are supported on Alpha OpenVMS for OCI programs.
OCI sample programs are supplied in the following directory:
ORA_ROOT:[RDBMS.DEMO]
The following guidelines apply to using OCI routines:
For the C OCI programmer, the CDA and LDA structures (64 bytes each) are declared in the header file OCIDFN.H.
The following tabulation of the size and offsets of the structure elements allows COBOL and FORTRAN programmers to use these structures.
The information for the cda_def structure, of which Cda_Def and Lda_Def are typedefs, is shown in Table 10-2:
| Structure Element | Offset (Bytes) | Size (Bytes) |
|---|---|---|
|
v2_rc |
0 |
2 |
|
ft |
2 |
2 |
|
rpc |
4 |
4 |
|
peo |
8 |
2 |
|
fc |
10 |
1 |
|
rc |
12 |
2 |
|
wrn |
14 |
1 |
|
rid |
20 |
16 |
|
ose |
36 |
4 |
|
rcsp |
44 |
4 |
LNOCIC.COM is used to link OCI routines written in C. The syntax is:
$ @ORA_RDBMS:LNOCIC <executable> <objfilelist> <options>
where:
Name of the executable image to be created; a filename extension is not required.
List of object files and libraries separated by commas. If this list is longer than one line, use the continuation character, the hyphen (-). Note that spaces are not allowed in the object file list.
List of options with no separators needed:
D Links with the Alpha OpenVMS DEBUG utility.
F Produces a full map.
M Creates a link map.
X Produces a link map with cross references.
For example:
$ @ORA_RDBMS:LNOCIC SAMPLE OBJECT1 D
LNOCI.COM is used to link with non-C programs. Of these, only FORTRAN, and COBOL are supported on Alpha OpenVMS for OCI programs. The syntax is:
$ @ORA_RDBMS:LNOCI <executable> <objectfilelist> <options>
For example:
$ @ORA_RDBMS:LNOCI SAMPLE OBJECT1 D
If you are linking object files in a library, use the /LIB qualifier and do not include your main or calling program in a library. If your command line exceeds the OpenVMS limit of 256 characters, you can use an option file with the /OPT qualifier.
If you receive unexpected link errors, you should make a custom copy of the appropriate ORA_RDBMS:LNOCI<option>.COM or ORA_PRECOMP:LNPRO<language>.COM file, and comment out the following line:
$ SHARED_CORE_LIB = "YES"
Relink the user-written utility with the custom copy of either ORA_RDBMS:LNOCI<option>.COM or ORA_PRECOMP:LNPRO<language>.COM. If commenting out this line eliminates your link errors, you must run that user-written utility without utilizing shared core. Running without shared core requires approximately 1500 additional OpenVMS blocks.
Datatypes for Oracle under Alpha OpenVMS are described below. Cursor Data Area is correct for Alpha OpenVMS as shown in the programmatic interface guides.
For Alpha OpenVMS, binary integers are 32 bits and short binary integers are 16 bits, as shown in Table 10-4.
| Programming Language | Usage of Binary Integers | Usage of Short Binary Integers |
|---|---|---|
|
C |
int; |
|
|
FORTRAN |
INTEGER*4 |
|
|
COBOL |
PIC S9(9) COMP |
PIC S9(4) COMP |
In FORTRAN, literals and the CHARACTER datatype are passed by descriptor to subroutines. Oracle requires all data to be passed by reference. Alpha OpenVMS FORTRAN provides the %REF compiler directive for overriding the normal calling mechanism; %REF should be used to pass literal strings and CHAR data to Oracle. For example:
CALL ORLON (LDA(1), HDA(1), %REF('SCOTT'), 5, %REF('TIGER'), 5)
In Alpha OpenVMS, C does not allow missing optional parameters; all call parameters must be specified. FORTRAN and COBOL, however, allow for missing trailing parameters; Oracle provides the necessary defaults. FORTRAN also allows missing embedded parameters; Oracle provides the necessary defaults.
If you omit a parameter using the -1 convention, the argument can be either a reference to the integer -1 or the integer value -1, as long as the argument is of datatype integer or short binary integer (for example, for length specifications). If the argument is the address of any datatype, the -1 must be passed by value.
The following two examples show how to override the normal calling mechanism. In FORTRAN, you could use this:
CALL ORLON(LDA(1), HDA(1), %REF('SCOTT/TIGER'), -1, X, %VAL(-1))
In COBOL, you could use this:
01 DEFLT PIC S9(9) COMP VALUE -1. 01 LDA PIC X(64). 01 HDA PIC X(256). 01 UID PIC X(11) VALUE 'SCOTT/TIGER' 01 UIDL PIC S9(9) VALUE 11. CALL ORLON USING LDA, HDA, UID, UIDL, BY VALUE DEFLT.
Event flags signal the completion of synchronous and asynchronous events in Alpha OpenVMS, such as disk I/O, terminal I/O, timers, the return of system and user information, lock acquisition, and user interrupts.
Oracle9i prevents asynchronous events from interfering with synchronous events by overwriting their event flags. This may increase the reliability of Oracle9i software on modern hardware, but it may introduce some problems for application programmers.
Oracle9i makes hard-coded references to event flags 1 - 18. All of these event flags except flags 1 and 5 are tied to specific asynchronous events within Oracle9i. Event flags 1 and 5 are used by all synchronous events within Oracle9i and can also be used by application programmers. SYS$GETEF() is not used for these event flags.
SQL*Net version 2 also uses additional event flags, which it gets dynamically from SYS$GETEF() calls from the second event flag group that ranges from 32-63. Make sure that you check the availability of any event flags you use in this range.
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|