Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume25/oraperl/patch03b

Text File | 1991-11-11 | 18KB | 593 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Kevin Stock)
Subject:  v25i036:  oraperl - Extensions to Perl to access Oracle databases, Patch03b/2
Message-ID: <[e-mail]>
X-Md4-Signature: d783a6e7c3fef65ecc5795f9f7c1f07d
Date: Sun, 10 Nov 1991 17:41:03 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Kevin Stock)
Posting-number: Volume 25, Issue 36
Archive-name: oraperl/patch03b
Environment: Perl, Oracle
Patch-To: oraperl: Volume 18, Issue 10

#!/bin/sh
# do not concatenate these parts, unpack them in order with /bin/sh
# file Patch03 continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 2; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping Patch03'
else
echo 'x - continuing file Patch03'
sed 's/^X//' << 'SHAR_EOF' >> 'Patch03' &&
! The return value is a statement identifier
! (an \fIORACLE cursor\fP).
X
X  If the SQL statement contains substitution variables
- (see later)
X  \fIora_bind\fP is used to assign values to them.
! This takes a statement identifier (obtained from \fIora_open\fP)
X  as its first parameter,
X  followed by as many parameters as are required by the statement.
X
--- 38,57 ----
X  (an \fIORACLE Login Data Area\fP).
X
X  To specify the \fISQL\fP statement to be executed,
! the program must call \fIora_open\fP or \fIora_do\fP.
! These functions take two parameters:
X  a login identifier (obtained from \fIora_login\fP)
X  and the \fISQL\fP statement to be executed.
! The return value from \fIora_open\fP is a statement identifier
! (an \fIORACLE cursor\fP) for use with \fIora_fetch\fP or \fIora_bind\fP.
! The return value from \fIora_do\fP is the constant string \fBOK\fP.
! The \fIora_do\fP function
! is only suitable for statements which do not return data
! or contain substitution variables.
X
X  If the SQL statement contains substitution variables
X  \fIora_bind\fP is used to assign values to them.
! This function takes a statement identifier (obtained from \fIora_open\fP)
X  as its first parameter,
X  followed by as many parameters as are required by the statement.
X
***************
*** 54,66 ****
X  the return value is an array containing the data,
X  one element per field.
X  In a scalar context,
X  the return value is the number of fields available from the query.
X
! When all the data desired has been returned from an \fISQL\fP statement,
X  the statement identifier should be released using the \fIora_close\fP function.
X  Every \fIora_open\fP call should have a corresponding \fIora_close\fP,
X  even if it did not return any data.
- This function returns the string \fBOK\fP.
X
X  When the program no longer needs to access a given database,
X  the login identifier should be released using the \fIora_logoff\fP function.
--- 63,76 ----
X  the return value is an array containing the data,
X  one element per field.
X  In a scalar context,
+ no data is actually fetched and
X  the return value is the number of fields available from the query.
X
! When all the data desired has been returned from an \fIora_open()\fP call,
X  the statement identifier should be released using the \fIora_close\fP function.
+ This function returns the string \fBOK\fP.
X  Every \fIora_open\fP call should have a corresponding \fIora_close\fP,
X  even if it did not return any data.
X
X  When the program no longer needs to access a given database,
X  the login identifier should be released using the \fIora_logoff\fP function.
***************
*** 67,73 ****
X  This function returns the string \fBOK\fP.
X
X  All functions return a null string to indicate failure.
! In the case of \fIora_fetch\fP, this implies the end of the data.
X  .SH Variables
X  Two special variables are provided,
X  \fIora_errno\fP and \fIora_errstr\fP.
--- 77,85 ----
X  This function returns the string \fBOK\fP.
X
X  All functions return a null string to indicate failure.
! In the case of \fIora_fetch\fP,
! if $ora_errno is zero,
! this indicates the end of the data.
X  .SH Variables
X  Two special variables are provided,
X  \fIora_errno\fP and \fIora_errstr\fP.
***************
*** 83,90 ****
X  For example, a program which added records to a telephone list
X  might use the following call to \fIora_open\fP:
X
X  .ti +.5i
! \f(CW$csr = &ora_open($csr, "insert into phonelist values(:1, :2)");\fP
X
X  The two names \fB:1\fP and \fB:2\fP are called substitution variables.
X  The function \fIora_bind\fP is used to assign values to these variables.
--- 95,104 ----
X  For example, a program which added records to a telephone list
X  might use the following call to \fIora_open\fP:
X
+ .if t .ft CW
X  .ti +.5i
! $csr = &ora_open($csr, "insert into phonelist values(:1, :2)");
! .if t .ft P
X
X  The two names \fB:1\fP and \fB:2\fP are called substitution variables.
X  The function \fIora_bind\fP is used to assign values to these variables.
***************
*** 91,99 ****
X  For example, the following statements would add two new people to the list:
X
X  .ti +.5i
! \f(CW&ora_bind($csr, "Annette", "472-8836");\fP
X  .ti +.5i
! \f(CW&ora_bind($csr, "Brian", "937-1823");\fP
X
X  Note that the substitution variables must be assigned consecutively
X  beginning from \fB1\fP for each SQL statement,
--- 105,115 ----
X  For example, the following statements would add two new people to the list:
X
X  .ti +.5i
! .if t .ft CW
! &ora_bind($csr, "Annette", "472-8836");
X  .ti +.5i
! &ora_bind($csr, "Brian", "937-1823");
! .if t .ft P
X
X  Note that the substitution variables must be assigned consecutively
X  beginning from \fB1\fP for each SQL statement,
***************
*** 101,107 ****
X  Named substitution variables
X  (for example, \fB:NAME\fP, \fB:TELNO\fP)
X  are not permitted.
! .ne 28
X  .SH EXAMPLE
X  .if t .ft C
X  .ta 4 8 12 16 20 24 28 32 36 40
--- 117,123 ----
X  Named substitution variables
X  (for example, \fB:NAME\fP, \fB:TELNO\fP)
X  are not permitted.
! .ne 30
X  .SH EXAMPLE
X  .if t .ft C
X  .ta 4 8 12 16 20 24 28 32 36 40
***************
*** 133,138 ****
--- 149,156 ----
X      write;
X  }
X
+ die "fetch error: $ora_errstr" if $ora_errno;
+
X  do ora_close($csr) || die "can't close cursor";
X  do ora_logoff($lda) || die "can't log off Oracle";
X  ^cc
***************
*** 162,171 ****
X  .if t .ft P
X  .in -3
X
! At present, only flags \fB8\fP (program execution)
X  and \fB128\fP (use of malloc and free)
X  are supported.
- .bp
X  .SH NOTES
X  In keeping with the philosophy of \fIPerl\fP,
X  there is no pre-defined limit to the number of simultaneous logins
--- 180,189 ----
X  .if t .ft P
X  .in -3
X
! At present, only flags \fB8\fP (program execution),
! \fB32\fP (string/numeric conversion)
X  and \fB128\fP (use of malloc and free)
X  are supported.
X  .SH NOTES
X  In keeping with the philosophy of \fIPerl\fP,
X  there is no pre-defined limit to the number of simultaneous logins
***************
*** 173,187 ****
X  nor to the number of data fields which may be returned by a query.
X  The only limits are those imposed by the amount of memory available,
X  or by \fIOracle\fP.
X  .SH SEE ALSO
! Documentation for \fIOracle\fP, \fISQL*Plus\fP and \fIPro*C\fP.
! .br
! Documentation for \fIPerl\fP.
! .SH AUTHOR
X  \fIORACLE\fP by Oracle Corporation, California.
X  .br
X  \fIPerl\fP by Larry Wall, Netlabs
! (\f([e-mail]\fP).
X  .br
X  \fIOraperl\fP by Kevin Stock, Encore Computer SA, France
! (\f([e-mail]\fP).
--- 191,221 ----
X  nor to the number of data fields which may be returned by a query.
X  The only limits are those imposed by the amount of memory available,
X  or by \fIOracle\fP.
+
+ Debugging option \fB32\fP only reports internal string/numeric translations,
+ not those performed on the data retrieved from the database.
X  .SH SEE ALSO
! .nf
! Oracle Documentation:
! .in +5
! \fISQL Language Reference Manual\fP
! \fIProgrammer's Guide to the Oracle Call Interfaces\fP
!
! .ti -5
! \fIPerl\fP documentation:
! \fIProgramming Perl\fP by Larry Wall and Randall Schwartz
! \fIperl(1)\fP
! .in -5
! .fi
! .SH AUTHORS
X  \fIORACLE\fP by Oracle Corporation, California.
X  .br
X  \fIPerl\fP by Larry Wall, Netlabs
! .if t .ft C
! ([e-mail]).
! .if t .ft P
X  .br
X  \fIOraperl\fP by Kevin Stock, Encore Computer SA, France
! .if t .ft C
! ([e-mail]).
! .if t .ft P
*** ORIG/oraperl.doc    Mon Oct 28 17:13:06 1991
--- ./oraperl.doc    Mon Oct 28 11:05:49 1991
***************
*** 27,33 ****
X  because it requires fixed addresses to be specified for receipt of data.
X  A new interface was therefore created for \fBOraperl\fP.
X
! The interface follows the idiom of the following six tasks:
X
X  .in +5
X  .ta .4i 4.4i
--- 27,33 ----
X  because it requires fixed addresses to be specified for receipt of data.
X  A new interface was therefore created for \fBOraperl\fP.
X
! The interface follows the idiom of the following seven tasks:
X
X  .in +5
X  .ta .4i 4.4i
***************
*** 39,45 ****
X  \fB3\fP    modify the statement    \fIora_bind\fP
X  \fB4\fP    get the data    \fIora_fetch\fP
X  \fB5\fP    close the stream    \fIora_close\fP
! \fB6\fP    log off of the database    \fIora_logoff\fP
X  .fi
X  .in -5
X
--- 39,46 ----
X  \fB3\fP    modify the statement    \fIora_bind\fP
X  \fB4\fP    get the data    \fIora_fetch\fP
X  \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
X  .fi
X  .in -5
X
***************
*** 80,85 ****
--- 81,94 ----
X  with a null string being returned for an error.
X
X
+ \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.
+
+
X  \fBora_login(database, name, password)\fP
X
X  Requests a cursor
***************
*** 103,108 ****
--- 112,119 ----
X  to determine the number and size of the fields which will be returned.
X  It allocates memory for these fields within \fIcsr\fP
X  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.
X  It returns the address of the \fIcsr\fP.
X
X
***************
*** 120,125 ****
--- 131,139 ----
X  In an array context,
X  calls \fBOCI\ ofetch\fP with the specified \fIcsr\fP
X  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.
X  In a scalar context,
X  returns the number of fields available from the query.
X
***************
*** 131,136 ****
--- 145,161 ----
X  The string \fBOK\fP is returned.
X
X
+ \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.
+
+
X  \fBora_logoff(lda)\fP
X
X  Calls \fBOCI\ ologoff\fP to log off of \fIOracle\fP
***************
*** 165,172 ****
X  deal with the allocation and release of cursors.
X
X  The definition of a cursor is extended from the \fIOracle\fP definition
! to include an \fIhda\fP (\fIHost Data Area\fP)
! and space for the data returned from the database.
X  Thus, \fIcsr\fPs and \fIlda\fPs have the same structure internally.
X  All the cursors are held on a singly\-linked list.
X
--- 190,198 ----
X  deal with the allocation and release of cursors.
X
X  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.
X  Thus, \fIcsr\fPs and \fIlda\fPs have the same structure internally.
X  All the cursors are held on a singly\-linked list.
X
***************
*** 244,254 ****
X  .in +5
X  .ta 5
X  .ti -5
! \ \ 8    \c
X  Reports entry and exit to \fIOraperl\fP functions,
X  including internal functions not directly available to \fIOraperl\fP scripts.
X
X  .ti -5
X  128    \c
X  Reports use of \fImalloc\fP and \fIfree\fP
X  to obtain cursors, login data areas, etc.
--- 270,289 ----
X  .in +5
X  .ta 5
X  .ti -5
! \0\08    \c
X  Reports entry and exit to \fIOraperl\fP functions,
X  including internal functions not directly available to \fIOraperl\fP scripts.
X
X  .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
X  128    \c
X  Reports use of \fImalloc\fP and \fIfree\fP
X  to obtain cursors, login data areas, etc.
***************
*** 269,273 ****
--- 304,310 ----
X  This variable may be tested to determine whether debugging has been enabled;
X  for example:
X
+ .nf
X  .ti +5
X  \fBdefined($ora_debug)\0||\0warn("oraperl debugging not enabled\en");\fP
+ .fi
*** ORIG/oraperl.ref    Mon Oct 28 17:13:07 1991
--- ./oraperl.ref    Mon Oct 28 11:42:42 1991
***************
*** 2,7 ****
--- 2,8 ----
X  .\"
X  .nf
X  .\"
+ .vs 10
X  .ps 10
X  \fBOraperl Quick Reference\fP
X  .ps 8
***************
*** 12,17 ****
--- 13,22 ----
X  .in +2m
X  .sp
X  .ti -2m
+ \fB&ora_version\fP
+ Displays version and copyright information for Oraperl.
+ .sp
+ .ti -2m
X  \fB$lda = &ora_login($database, $name, $password)\fP
X  Logs into the specified database with the name and password given.
X  Returns an \fIlda\fP for use with \fIora_open()\fP.
***************
*** 40,45 ****
--- 45,55 ----
X  Finishes the SQL statement identified by $csr.
X  .sp
X  .ti -2m
+ \fB&ora_do($lda, $stmt)\fP
+ Equivalent to \fI&ora_close\fP(\fI&ora_open(...))\fP
+ for statements which have no substitution variables and do not return data.
+ .sp
+ .ti -2m
X  \fB&ora_logoff($lda)\fP
X  Logs out of the database identified by $lda.
X  .ti -2m
***************
*** 58,66 ****
X
X  .ti -2m
X  \fB$ora_debug\fP  (if debugging is enabled)
! Contains the debugging flags for \fIOraperl\fP.
X  May be set by a program to debug only certain parts of the script.
X  The following flags are meaningful:
X  .ta 5m
X  \0\08    report function entry and exit
X  128    report use of malloc and free
--- 68,77 ----
X
X  .ti -2m
X  \fB$ora_debug\fP  (if debugging is enabled)
! Contains the debugging flags for \fIOraperl\fP, initialised from Perl's -D flag.
X  May be set by a program to debug only certain parts of the script.
X  The following flags are meaningful:
X  .ta 5m
X  \0\08    report function entry and exit
+ \032    report conversions between strings and numerics
X  128    report use of malloc and free
*** ORIG/usersub.c    Mon Oct 28 17:12:43 1991
--- ./usersub.c    Mon Oct 28 16:39:29 1991
***************
*** 18,30 ****
X  {
X      init_oracle();
X
! #ifdef    DEBUGGING
! #ifdef    PERL_DEBUGGING
X      ora_debug = debug;        /* pick up the -D flag */
! #else
X      ora_debug = 0;
! #endif    /* PERL_DEBUGGING */
! #endif    /* DEBUGGING */
X
X      ora_errno = 0;
X  }
--- 18,30 ----
X  {
X      init_oracle();
X
! #ifdef DEBUGGING
! #   ifdef PERL_DEBUGGING
X      ora_debug = debug;        /* pick up the -D flag */
! #   else
X      ora_debug = 0;
! #   endif
! #endif
X
X      ora_errno = 0;
X  }
SHAR_EOF
echo 'File Patch03 is complete' &&
chmod 0644 Patch03 ||
echo 'restore of Patch03 failed'
Wc_c="`wc -c < 'Patch03'`"
test 67801 -eq "$Wc_c" ||
    echo 'Patch03: original size 67801, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= oraperl.ph ==============
if test -f 'oraperl.ph' -a X"$1" != X"-c"; then
    echo 'x - skipping oraperl.ph (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting oraperl.ph (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'oraperl.ph' &&
# oraperl.ph
#
# Various defines which may be useful in oraperl programs
#
# Author:    Kevin Stock
# Date:        28th October 1991
X
X
# Oraperl error codes, set in $ora_errno
X
$ORAP_NOMEM    = 100001;    # out of memory
$ORAP_INVCSR    = 100002;    # invalid cursor supplied
$ORAP_INVLDA    = 100003;    # invalid lda supplied
$ORAP_NOSID    = 100004;    # couldn't set ORACLE_SID
$ORAP_BADVAR    = 100005;    # bad colon variable sequence
$ORAP_NUMVARS    = 100006;    # wrong number of colon variables
$ORAP_NODATA    = 100007;    # statement does not return data
X
X
# Oraperl debugging codes for $ora_debug
X
$ODBG_EXEC    =   8;        # program execution
$ODBG_STRNUM    =  32;        # string/numeric conversions
$ODBG_MALLOC    = 128;        # memory allocation/release
X
X
1;
SHAR_EOF
chmod 0644 oraperl.ph ||
echo 'restore of oraperl.ph failed'
Wc_c="`wc -c < 'oraperl.ph'`"
test 703 -eq "$Wc_c" ||
    echo 'oraperl.ph: original size 703, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= patchlevel.h ==============
if test -f 'patchlevel.h' -a X"$1" != X"-c"; then
    echo 'x - skipping patchlevel.h (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting patchlevel.h (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'patchlevel.h' &&
/* patchlevel.h */
X
#define    PATCHLEVEL    3
SHAR_EOF
chmod 0644 patchlevel.h ||
echo 'restore of patchlevel.h failed'
Wc_c="`wc -c < 'patchlevel.h'`"
test 41 -eq "$Wc_c" ||
    echo 'patchlevel.h: original size 41, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
rm -f _shar_seq_.tmp
echo You have unpacked the last part
exit 0
exit 0 # Just in case...
--
Kent Landfield                   INTERNET: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].