dbd::oraperl.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

ora_do
.Sp
.Vb 1
\&  &ora_do($lda, $statement)
.Ve
.Sp
Not all \s-1SQL\s0 statements return data or contain substitution
variables. In these cases the &\fIora_do()\fR function may be
used as an alternative to &\fIora_open()\fR and &\fIora_close()\fR.
This function takes two parameters, a login identifier and
the statement to be executed.
.Sp
Example:
.Sp
.Vb 1
\& &ora_do($lda, \*(Aqdrop table employee\*(Aq);
.Ve
.Sp
This function is roughly equivalent to
.Sp
.Vb 1
\& &ora_close( &ora_open($lda, $statement) )
.Ve
.Sp
\&\fB\s-1DBD:\s0\fR oraperl v2 used to return the string '\s-1OK\s0' to indicate
success with a zero numeric value. The Oraperl emulation now
uses the string '0E0' to achieve the same effect since it does
not cause any \f(CW\*(C`\-w\*(C'\fR warnings when used in a numeric context.
.IP "\(bu" 2
ora_logoff
.Sp
.Vb 1
\&  &ora_logoff($lda)
.Ve
.Sp
When the program no longer needs to access a given database, the login
identifier should be released using the &\fIora_logoff()\fR function.
.Sp
This function is equivalent to the \s-1OCI\s0 ologoff function.
.Sp
\&\fB\s-1DBD:\s0\fR Since \f(CW$lda\fR is a Perl5 reference the database login identifier
is now automatically released if \f(CW$lda\fR is overwritten or goes out of scope.
.Sh "Ancillary Functions"
.IX Subsection "Ancillary Functions"
Additional functions available are: &\fIora_titles()\fR,
&\fIora_lengths()\fR, &\fIora_types()\fR, &\fIora_autocommit()\fR,
&\fIora_commit()\fR, &\fIora_rollback()\fR and &\fIora_version()\fR.
.PP
The first three are of most use within a program which
allows statements to be entered interactively. See, for
example, the sample program sql which is supplied with
Oraperl and may have been installed at your site.
.IP "\(bu" 2
ora_titles
.Sp
.Vb 1
\&  @titles = &ora_titles($csr)
.Ve
.Sp
A program may determine the field titles of an executed
query by calling &\fIora_titles()\fR. This function takes a
single parameter, a statement identifier (obtained from
&\fIora_open()\fR) indicating the query for which the titles are
required. The titles are returned as an array of strings,
one for each column.
.Sp
Titles are truncated to the length of the field, as reported
by the &\fIora_lengths()\fR function.
.Sp
\&\fB\s-1DBD:\s0\fR oraperl v2.2 actually changed the behaviour such that the
titles were not truncated unless an optional second parameter was
true.  This was not reflected in the oraperl manual.  The Oraperl
emulation adopts the non truncating behaviour and doesn't support the
truncate parameter.
.IP "\(bu" 2
ora_lengths
.Sp
.Vb 1
\&  @lengths = &ora_lengths($csr)
.Ve
.Sp
A program may determine the length of each of the fields
returned by a query by calling the &\fIora_lengths()\fR function.
This function takes a single parameter, a statement
identifier (obtained from &\fIora_open()\fR) indicating the query
for which the lengths are required. The lengths are
returned as an array of integers, one for each column.
.IP "\(bu" 2
ora_types
.Sp
.Vb 1
\&  @types = &ora_types($csr)
.Ve
.Sp
A program may determine the type of each of the fields returned by a
query by calling the &\fIora_types()\fR function.  This function takes a
single parameter, a statement identifier (obtained from &\fIora_open()\fR)
indicating the query for which the lengths are required. The types are
returned as an array of integers, one for each field.
.Sp
These types are defined in your \s-1OCI\s0 documentation. The correct
interpretation for Oracle v6 is given in the file oraperl.ph.
.IP "\(bu" 2
ora_autocommit
.Sp
.Vb 1
\&  &ora_autocommit($lda, $on_or_off)
.Ve
.Sp
Autocommit mode (in which each transaction is committed immediately,
without waiting for an explicit commit) may be enabled or disabled
using &\fIora_autocommit()\fR. This function takes two parameters, a login
identifier (obtained from &\fIora_login()\fR) and a true/false value
indicating whether autocommit is to be enabled (non-zero) or disabled
(zero).  By default, autocommit is off.
.Sp
Note that autocommit can only be set per login, not per statement. If
you need to control autocommit by statement (for example, to allow
deletions to be rolled back, but insertions to be committed
immediately) you should make multiple calls to &\fIora_login()\fR and use a
separate login identifier for each statement.
.IP "\(bu" 2
ora_commit, ora_rollback
.Sp
.Vb 2
\&  &ora_commit($lda)
\&  &ora_rollback($lda)
.Ve
.Sp
Modifications to a database may be committed or rolled back using the
&\fIora_commit()\fR and &\fIora_rollback()\fR functions.  These functions take a
single parameter, a login identifier obtained from &\fIora_login()\fR.
.Sp
Transactions which have been committed (either explicitly by a call to
&\fIora_commit()\fR or implicitly through the use of &\fIora_autocommit()\fR)
cannot be subsequently rolled back.
.Sp
Note that commit and rollback can only be used per login, not per
statement. If you need to commit or rollback by statement you should
make multiple calls to &\fIora_login()\fR and use a separate login identifier
for each statement.
.IP "\(bu" 2
ora_version
.Sp
.Vb 1
\&  &ora_version()
.Ve
.Sp
The &\fIora_version()\fR function prints the version number and
copyright information concerning Oraperl. It also prints
the values of various compilation time options. It does not
return any value, and should not normally be used in a
program.
.Sp
Example:
.Sp
.Vb 1
\&  perl \-MOraperl \-e \*(Aqora_version()\*(Aq
\&
\&  This is Oraperl, version 2, patch level 0.
\&
\&  Debugging is available, including the \-D flag.
\&  Default fetch row cache size is 5.
\&  Empty bind values are replaced by a space.
\&
\&  Perl is copyright by Larry Wall; type oraperl \-v for details.
\&  Additions for oraperl: Copyright 1991, 1992, Kevin Stock.
\&
\&  Oraperl may be distributed under the same conditions as Perl.
.Ve
.Sp
This function is the equivalent of Perl's \f(CW\*(C`\-v\*(C'\fR flag.
.Sp
\&\fB\s-1DBD:\s0\fR The Oraperl emulation printout is similar but not identical.
.SH "VARIABLES"
.IX Header "VARIABLES"
Six special variables are provided, \f(CW$ora_cache\fR, \f(CW$ora_long\fR,
\&\f(CW$ora_trunc\fR, \f(CW$ora_errno\fR, \f(CW$ora_errstr\fR and \f(CW$ora_verno\fR.
.Sh "Customisation Variables"
.IX Subsection "Customisation Variables"
These variables are used to dictate the behaviour of Oraperl
under certain conditions.
.IP "\(bu" 2
\&\f(CW$ora_cache\fR
.Sp
The \f(CW$ora_cache\fR variable determines the default cache size used by the
&\fIora_open()\fR function for \s-1SELECT\s0 statements if an explicit cache size is
not given.
.Sp
It is initialised to the default value reported by &\fIora_version()\fR but
may be set within a program to apply to all subsequent calls to
&\fIora_open()\fR. Cursors which are already open are not affected. As
distributed, the default value is five, but may have been altered at
your installation.
.Sp
As a special case, assigning zero to \f(CW$ora_cache\fR resets it to the
default value. Attempting to set \f(CW$ora_cache\fR to a negative value results
in a warning.
.IP "\(bu" 2
\&\f(CW$ora_long\fR
.Sp
Normally, Oraperl interrogates the database to determine the length of
each field and allocates buffer space accordingly.  This is not
possible for fields of type \s-1LONG\s0 or \s-1LONGRAW\s0. To allocate space
according to the maximum possible length (65535 bytes) would obviously
be extremely wasteful of memory.
.Sp
Therefore, when &\fIora_open()\fR determines that a field is a \s-1LONG\s0 type, it
allocates the amount of space indicated by the \f(CW$ora_long\fR variable. This
is initially set to 80 (for compatibility with Oracle products) but may
be set within a program to whatever size is required.
.Sp
\&\f(CW$ora_long\fR is only used when fetching data, not when inserting it.
.IP "\(bu" 2
\&\f(CW$ora_trunc\fR
.Sp
Since Oraperl cannot determine exactly the maximum length of a \s-1LONG\s0
field, it is possible that the length indicated by \f(CW$ora_long\fR is not
sufficient to store the data fetched. In such a case, the optional
second parameter to &\fIora_fetch()\fR indicates whether the truncation
should be allowed or should provoke an error.
.Sp
If this second parameter is not specified, the value of \f(CW$ora_trunc\fR is
used as a default. This only applies to \s-1LONG\s0 and \s-1LONGRAW\s0 data types.
Truncation of a field of any other type is always considered an error
(principally because it indicates a bug in Oraperl).
.Sh "Status Variables"
.IX Subsection "Status Variables"
These variables report information about error conditions or about
Oraperl itself. They may only be read; a fatal error occurs if a
program attempts to change them.
.IP "\(bu" 2
\&\f(CW$ora_errno\fR
.Sp
\&\f(CW$ora_errno\fR contains the Oracle error code provoked by the last function
call.
.Sp
There are two cases of particular interest concerning &\fIora_fetch()\fR. If
a \s-1LONG\s0 or \s-1LONGRAW\s0 field is truncated (and truncation is allowed) then
&\fIora_fetch()\fR will complete successfully but \f(CW$ora_errno\fR will be set to
1406 to indicate the truncation. When &\fIora_fetch()\fR fails, \f(CW$ora_errno\fR
will be set to zero if this was due to the end of data or an error code
if it was due to an actual error.
.IP "\(bu" 2
\&\f(CW$ora_errstr\fR
.Sp
The \f(CW$ora_errstr\fR variable contains the Oracle error message
corresponding to the current value of \f(CW$ora_errno\fR.
.IP "\(bu" 2
\&\f(CW$ora_verno\fR
.Sp
The \f(CW$ora_verno\fR variable contains the version number of Oraperl in the
form v.ppp where v is the major version number and ppp is the
patchlevel. For example, in Oraperl version 3, patch level 142,
\&\f(CW$ora_verno\fR would contain the value 3.142 (more or less, allowing for
floating point error).
.SH "SUBSTITUTION VARIABLES"
.IX Header "SUBSTITUTION VARIABLES"
Oraperl allows an \s-1SQL\s0 statement to contain substitution variables.
These consist of a colon followed by a number.  For example, a program
which added records to a telephone list might use the following call to
&\fIora_open()\fR:
.PP
.Vb 1
\&  $csr = &ora_open($csr, "insert into telno values(:1, :2)");
.Ve
.PP
The two names :1 and :2 are called substitution variables.  The
function &\fIora_bind()\fR is used to assign values to these variables. For
example, the following statements would add two new people to the
list:
.PP
.Vb 2
\&  &ora_bind($csr, "Annette", "472\-8836");
\&  &ora_bind($csr, "Brian", "937\-1823");
.Ve
.PP
Note that the substitution variables must be assigned consecutively
beginning from 1 for each \s-1SQL\s0 statement, as &\fIora_bind()\fR assigns its
parameters in this order. Named substitution variables (for example,
:NAME, :TELNO) are not permitted.
.PP
\&\fB\s-1DBD:\s0\fR Substitution variables are now bound as type 1 (\s-1VARCHAR2\s0)
and not type 5 (\s-1STRING\s0) by default. This can alter the behaviour of
\&\s-1SQL\s0 code which compares a char field with a substitution variable.
See the String Comparison section in the Datatypes chapter of the
Oracle \s-1OCI\s0 manual for more details.
.PP
You can work around this by using DBD::Oracle's ability to specify
the Oracle type to be used on a per field basis:
.PP
.Vb 5
\&  $char_attrib = { ora_type => 5 }; # 5 = STRING (ala oraperl2.4)
\&  $csr = ora_open($dbh, "select foo from bar where x=:1 and y=:2");
\&  $csr\->bind_param(1, $value_x, $char_attrib);
\&  $csr\->bind_param(2, $value_y, $char_attrib);
\&  ora_bind($csr);  # bind with no parameters since we\*(Aqve done bind_param()\*(Aqs
.Ve
.SH "DEBUGGING"
.IX Header "DEBUGGING"
\&\fB\s-1DBD:\s0\fR The Oraperl \f(CW$ora_debug\fR variable is not supported. However
detailed debugging can be enabled at any time by executing
.PP
.Vb 1
\&  $h\->debug(2);
.Ve
.PP
where \f(CW$h\fR is either a \f(CW$lda\fR or a \f(CW$csr\fR. If debugging is enabled on an
\&\f(CW$lda\fR then it is automatically passed on to any cursors returned by
&\fIora_open()\fR.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 4
\&  format STDOUT_TOP =
\&  Name Phone
\&  ==== =====
\&  .
\&
\&  format STDOUT =
\&  @<<<<<<<<<< @>>>>>>>>>>
\&  $name, $phone
\&  .
\&
\&  die "You should use oraperl, not perl\en" unless defined &ora_login;
\&  $ora_debug = shift if $ARGV[0] =~ /^\e\-#/;
\&
\&  $lda = &ora_login(\*(Aqt\*(Aq, \*(Aqkstock\*(Aq, \*(Aqkstock\*(Aq)
\&            || die $ora_errstr;
\&  $csr = &ora_open($lda, \*(Aqselect * from telno order by name\*(Aq)
\&            || die $ora_errstr;
\&
\&  $nfields = &ora_fetch($csr);
\&  print "Query will return $nfields fields\en\en";
\&
\&  while (($name, $phone) = &ora_fetch($csr)) { write; }
\&  warn $ora_errstr if $ora_errno;
\&
\&  die "fetch error: $ora_errstr" if $ora_errno;
\&
\&  do ora_close($csr) || die "can\*(Aqt close cursor";
\&  do ora_logoff($lda) || die "can\*(Aqt log off Oracle";
.Ve
.SH "NOTES"
.IX Header "NOTES"
In keeping with the philosophy of Perl, there is no pre-defined limit
to the number of simultaneous logins or \s-1SQL\s0 statements which may be
active, nor to the number of data fields which may be returned by a
query. The only limits are those imposed by the amount of memory
available, or by Oracle.
.SH "WARNINGS"
.IX Header "WARNINGS"
The Oraperl emulation software shares no code with the original
oraperl. It is built on top of the new Perl5 \s-1DBI\s0 and DBD::Oracle
modules.  These modules are still evolving. (One of the goals of
the Oraperl emulation software is to allow useful work to be done
with the \s-1DBI\s0 and DBD::Oracle modules whilst insulating users from
the ongoing changes in their interfaces.)
.PP
It is quite possible, indeed probable, that some differences in
behaviour will exist. These are probably confined to error handling.
.PP
\&\fBAll\fR differences in behaviour which are not documented here should be
reported to to dbi\[e-mail].
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "Oracle Documentation" 2
.IX Item "Oracle Documentation"
\&\s-1SQL\s0 Language Reference Manual.
Programmer's Guide to the Oracle Call Interfaces.
.IP "Books" 2
.IX Item "Books"
Programming Perl by Larry Wall and Randal Schwartz.
Learning Perl by Randal Schwartz.
.IP "Manual Pages" 2
.IX Item "Manual Pages"
\&\fIperl\fR\|(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
Original Oraperl 2.4 code and documentation
by Kevin Stock <[e-mail]>.
.PP
\&\s-1DBI\s0 and Oraperl emulation using DBD::Oracle by Tim Bunce.
.SH "MAINTAINER"
.IX Header "MAINTAINER"
As of DBD::Oracle release 1.17 in February 2006 The Pythian Group, Inc.
(<http://www.pythian.com>) are taking the lead in maintaining DBD::Oracle with
my assistance and gratitude.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1994\-2006 Tim Bunce. Ireland.
.PP
The DBD::Oracle module is free open source software; you can
redistribute it and/or modify it under the same terms as Perl 5.