OS/2 Shareware BBS: 5 Edit/05-Edit.zip/oraperl2.zip/oraperl.doc

Text File | 1993-07-01 | 9KB | 311 lines

.ce 2
\fBO R A P E R L\fP
_____________


This document describes the implementation of \fBOraperl\fP,
an extension of the \fIPerl\fP language
capable of accessing \fIOracle\fP databases.

\fIPerl\fP provides a facility known as \fIusersubs\fP,
which allows user\-specified subroutines
to be linked into a \fIPerl\fP interpreter.
\fIOracle\fP provides \fIOCI\fP, the \fIOracle Call Interface\fP,
which is a library of subroutines which may be called from C programs.
\fBOraperl\fP is a combination of these two features.


.ce 2
\fBInterface\fP
_________

The C language interface of the \fIOCI\fP is not particularly friendly.
A number of functions accept redundant parameters,
in order to be useful in a wide range of programming languages.
The interface is not really suitable for \fIPerl\fP
because it requires fixed addresses to be specified for receipt of data.
A new interface was therefore created for \fBOraperl\fP.

The interface follows the idiom of the following seven tasks:

.in +5
.ta .4i 4.4i
.nf
\fBTask        Interface\fP

\fB1\fP    log in to the database    \fIora_login\fP
\fB2\fP    open a stream for an SQL statement    \fIora_open\fP
\fB3\fP    modify the statement    \fIora_bind\fP
\fB4\fP    get the data    \fIora_fetch\fP
\fB5\fP    close the stream    \fIora_close\fP
\fB6\fP    execute an SQL statement    \fIora_do\fP
\fB7\fP    log off of the database    \fIora_logoff\fP
.fi
.in -5


.ce 2
\fBCursors\fP
_______

The \fIOCI\fP communicates with the calling process via \fIcursor\fPs.
One cursor is required for each login (together with a host data area),
and one for each SQL statement executed.
To save the user the task of allocating cursors,
\fBOraperl\fP allocates them automatically,
and returns an identifier to the user
to be supplied as a parameter to future function calls.

A set of functions (not directly accessible to the user)
deals with the allocation and release of cursors.


.ce 2
\fBInformation from the Database\fP
_____________________________

Each set of data retrieved from the database
is returned to the user as an array.
A program may determine the number of fields to be returned
without actually accessing any data.
This may be useful
in a program which allows queries to be entered interactively.


.ce 2
\fBPublic Function Descriptions\fP
____________________________

Return values from functions are in the form of strings,
with a null string being returned for an error.


\fBora_version\fP

This function has nothing to do with the data interface;
it simply prints the Oraperl version and copyright information,
similar to Perl's \fB\-v\fP flag.
It does not return a value.


\fBora_login(database, name, password)\fP

Requests a cursor
for use as a \fILogin Data Area\fP (\fIlda\fP)
and then calls \fBOCI\ orlon\fP
to log the user into the given \fIOracle\fP database
under the name and password specified.
It returns the address of the \fIlda\fP.


\fBora_open(lda, stmt)\fP

Requests a cursor (\fIcsr\fP)
and calls \fBOCI\ oopen\fP to connect it the the specified \fIlda\fP.
It then calls \fBOCI\ osql3\fP to attach the SQL statement.
If the statement does not contain any substitution variables,
\fIora_open\fP calls \fBOCI\ oexec\fP to instruct \fIOracle\fP to execute it.

If these three steps succeed,
\fBora_open\fP then makes successive calls to \fBOCI\ odsc\fP
to determine the number and size of the fields which will be returned.
It allocates memory for these fields within \fIcsr\fP
and attaches them to the cursor using \fBOCI\ odefin\fP.
It also attaches a return code field to each item,
so that NULL data returns can be caught and treated sensibly.
It returns the address of the \fIcsr\fP.


\fBora_bind(csr, var, ...)\fP

Binds the specified \fIvar\fPs to the substitution variables
in the SQL statement identified by \fIcsr\fP
and calls \fBOCI\ oexec\fP to execute the resulting statement.
Assumes that the substitution variables are \fB:1\fP, \fB:2\fP, \fB:3\fP, etc
in the order that they appear in the \fBora_bind\fP call.


\fBora_fetch(csr)\fP

In an array context,
calls \fBOCI\ ofetch\fP with the specified \fIcsr\fP
and returns an array with one element for each field returned.
If any field in the database was NULL,
and empty string will be returned.
It is not possible to distinguish between empty and NULL fields.
In a scalar context,
returns the number of fields available from the query.


\fBora_close(csr)\fP

Calls \fBOCI\ oclose\fP to release the \fIcsr\fP
and then frees the memory allocated to it.
The string \fBOK\fP is returned.


\fBora_do(lda, stmt)\fP

This is equivalent to an \fBora_open\fP
immediately followed by an \fBora_close\fP
(in fact, that is how it is implemented)
except that the user does not have to keep track
of the \fIcsr\fP used.
It is suitable for statements which do not return any data
and which do not contain any substitution variables.


\fBora_logoff(lda)\fP

Calls \fBOCI\ ologoff\fP to log off of \fIOracle\fP
and then frees the memory allocated to \fIlda\fP.
The string \fBOK\fP is returned.


.ce 2
\fBPublic Variable Descriptions\fP
____________________________

The variables are read\-only,
since they refer to the status of \fIOracle\fP commands.


\fB$ora_errno\fP

Contains the error number from the last \fBOCI\fP function executed.


\fB$ora_errstr\fP

Contains the error message corresponding to the current value of $errno.


.ce 2
\fBPrivate Function Descriptions\fP
_____________________________


Functions private to \fBOraperl\fP
deal with the allocation and release of cursors.

The definition of a cursor is extended from the \fIOracle\fP definition
to include an \fIhda\fP (\fIHost Data Area\fP),
space for the data returned from the database
and space for return codes for each data field.
Thus, \fIcsr\fPs and \fIlda\fPs have the same structure internally.
All the cursors are held on a singly\-linked list.


\fBora_free_data(csr)\fP

Releases the memory space reserved for data for the specified \fIcsr\fP.


\fBora_getcursor()\fP

Allocates a new cursor and adds it to the list.
It returns the address of the cursor.


\fBora_getlda()\fP

Calls \fBora_getcursor\fP to allocate a new cursor,
then allocates the \fIhda\fP
to allow it to be used for logging into \fIOracle\fP.
It returns the address of the cursor.


\fBora_dropcursor(csr)\fP

Releases the memory associated with the specified cursor,
and removes it from the list.
It returns 1 if the cursor was successfully dropped,
0 otherwise.


\fBora_droplda(lda)\fP

Calls \fBora_dropcursor\fP to release the cursor
and passes back the return value.
Only exists for completeness,
but could be extended to verify that what it is dropping is an \fIlda\fP.


\fBora_findcursor(csr)\fP

Searches the list looking for the specified \fIcsr\fP.
It returns 1 if it was found, 0 otherwise.


\fBcheck_csr(csr)\fP

Checks whether the address supplied corresponds to a valid data cursor
(i.e. it exists in the list,
its \fIhda\fP is not allocated,
its \fIdata\fP area is allocated).
It returns 1 for a valid cursor, 0 otherwise.


\fBcheck_lda(lda)\fP

Checks whether the address supplied corresponds to a valid login cursor
(i.e. it exists in the list,
its \fIhda\fP is allocated,
its \fIdata\fP area is not allocated).
It returns 1 for a valid cursor, 0 otherwise.


.ce 2
\fBDebugging\fP
_________

\fIPerl\fP includes support for runtime debugging via a \fB\-D\fP option
which sets debugging flags.
\fIOraperl\fP also allows runtime debugging by a separate but related mechanism.

Debugging is flag based.
The following flags have significance for \fIOraperl\fP:

.in +5
.ta 5
.ti -5
\0\08    \c
Reports entry and exit to \fIOraperl\fP functions,
including internal functions not directly available to \fIOraperl\fP scripts.

.ti -5
\032    \c
Reports conversions between strings and numerics.
In the case of Oraperl, this only concerns the translation of cursor addresses
into strings, and vice versa,
since the data translations are performed by the Oracle software.
However, it could be useful in tracing obscure bugs,
if the \fIlda\fPs or \fIcsr\fPs returned by \fIOraperl\fP are unusable.

.ti -5
128    \c
Reports use of \fImalloc\fP and \fIfree\fP
to obtain cursors, login data areas, etc.
.in -5

Debugging may be enabled in \fIOraperl\fP
by defining either \fBDEBUGGING\fP or \fBPERL_DEBUGGING\fP during compilation.
\fBPERL_DEBUGGING\fP may only be used
if \fIPerl\fP was compiled with debugging enabled.
It differs from \fBDEBUGGING\fP in that
it arranges for the \fIOraperl\fP debugging flags to be initialised
from the \fB\-D\fP option on the command line,
if given.

If debugging is compiled into \fIOraperl\fP,
the debugging flags may be accessed or set
via the variable \fIora_debug\fP.
This variable may be tested to determine whether debugging has been enabled;
for example:

.nf
.ti +5
\fBdefined($ora_debug)\0||\0warn("oraperl debugging not enabled\en");\fP
.fi