dbi.3

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

Returns \f(CW\*(C`undef\*(C'\fR for each element that is undefined or empty.
.PP
\fI\f(CI\*(C`hash\*(C'\fI\fR
.IX Subsection "hash"
.PP
.Vb 1
\&  $hash_value = DBI::hash($buffer, $type);
.Ve
.PP
Return a 32\-bit integer 'hash' value corresponding to the contents of \f(CW$buffer\fR.
The \f(CW$type\fR parameter selects which kind of hash algorithm should be used.
.PP
For the technically curious, type 0 (which is the default if \f(CW$type\fR
isn't specified) is based on the Perl 5.1 hash except that the value
is forced to be negative (for obscure historical reasons).
Type 1 is the better \*(L"Fowler / Noll / Vo\*(R" (\s-1FNV\s0) hash. See
<http://www.isthe.com/chongo/tech/comp/fnv/> for more information.
Both types are implemented in C and are very fast.
.PP
This function doesn't have much to do with databases, except that
it can be handy to store hash values in a database.
.Sh "\s-1DBI\s0 Dynamic Attributes"
.IX Subsection "DBI Dynamic Attributes"
Dynamic attributes are always associated with the \fIlast handle used\fR
(that handle is represented by \f(CW$h\fR in the descriptions below).
.PP
Where an attribute is equivalent to a method call, then refer to
the method call for all related documentation.
.PP
Warning: these attributes are provided as a convenience but they
do have limitations. Specifically, they have a short lifespan:
because they are associated with
the last handle used, they should only be used \fIimmediately\fR after
calling the method that \*(L"sets\*(R" them.
If in any doubt, use the corresponding method call.
.PP
\fI\f(CI$DBI::err\fI\fR
.IX Subsection "$DBI::err"
.PP
Equivalent to \f(CW\*(C`$h\->err\*(C'\fR.
.PP
\fI\f(CI$DBI::errstr\fI\fR
.IX Subsection "$DBI::errstr"
.PP
Equivalent to \f(CW\*(C`$h\->errstr\*(C'\fR.
.PP
\fI\f(CI$DBI::state\fI\fR
.IX Subsection "$DBI::state"
.PP
Equivalent to \f(CW\*(C`$h\->state\*(C'\fR.
.PP
\fI\f(CI$DBI::rows\fI\fR
.IX Subsection "$DBI::rows"
.PP
Equivalent to \f(CW\*(C`$h\->rows\*(C'\fR. Please refer to the documentation
for the \*(L"rows\*(R" method.
.PP
\fI\f(CI$DBI::lasth\fI\fR
.IX Subsection "$DBI::lasth"
.PP
Returns the \s-1DBI\s0 object handle used for the most recent \s-1DBI\s0 method call.
If the last \s-1DBI\s0 method call was a \s-1DESTROY\s0 then \f(CW$DBI::lasth\fR will return
the handle of the parent of the destroyed handle, if there is one.
.SH "METHODS COMMON TO ALL HANDLES"
.IX Header "METHODS COMMON TO ALL HANDLES"
The following methods can be used by all types of \s-1DBI\s0 handles.
.PP
\fI\f(CI\*(C`err\*(C'\fI\fR
.IX Subsection "err"
.PP
.Vb 1
\&  $rv = $h\->err;
.Ve
.PP
Returns the \fInative\fR database engine error code from the last driver
method called. The code is typically an integer but you should not
assume that.
.PP
The \s-1DBI\s0 resets \f(CW$h\fR\->err to undef before almost all \s-1DBI\s0 method calls, so the
value only has a short lifespan. Also, for most drivers, the statement
handles share the same error variable as the parent database handle,
so calling a method on one handle may reset the error on the
related handles.
.PP
(Methods which don't reset err before being called include \fIerr()\fR and \fIerrstr()\fR,
obviously, \fIstate()\fR, \fIrows()\fR, \fIfunc()\fR, \fItrace()\fR, \fItrace_msg()\fR, \fIping()\fR, and the
tied hash attribute \s-1\fIFETCH\s0()\fR and \s-1\fISTORE\s0()\fR methods.)
.PP
If you need to test for specific error conditions \fIand\fR have your program be
portable to different database engines, then you'll need to determine what the
corresponding error codes are for all those engines and test for all of them.
.PP
A driver may return \f(CW0\fR from \fIerr()\fR to indicate a warning condition
after a method call. Similarly, a driver may return an empty string
to indicate a 'success with information' condition. In both these
cases the value is false but not undef. The \fIerrstr()\fR and \fIstate()\fR
methods may be used to retrieve extra information in these cases.
.PP
See \*(L"set_err\*(R" for more information.
.PP
\fI\f(CI\*(C`errstr\*(C'\fI\fR
.IX Subsection "errstr"
.PP
.Vb 1
\&  $str = $h\->errstr;
.Ve
.PP
Returns the native database engine error message from the last \s-1DBI\s0
method called. This has the same lifespan issues as the \*(L"err\*(R" method
described above.
.PP
The returned string may contain multiple messages separated by
newline characters.
.PP
The \fIerrstr()\fR method should not be used to test for errors, use \fIerr()\fR
for that, because drivers may return 'success with information' or
warning messages via \fIerrstr()\fR for methods that have not 'failed'.
.PP
See \*(L"set_err\*(R" for more information.
.PP
\fI\f(CI\*(C`state\*(C'\fI\fR
.IX Subsection "state"
.PP
.Vb 1
\&  $str = $h\->state;
.Ve
.PP
Returns a state code in the standard \s-1SQLSTATE\s0 five character format.
Note that the specific success code \f(CW00000\fR is translated to any empty string
(false). If the driver does not support \s-1SQLSTATE\s0 (and most don't),
then \fIstate()\fR will return \f(CW\*(C`S1000\*(C'\fR (General Error) for all errors.
.PP
The driver is free to return any value via \f(CW\*(C`state\*(C'\fR, e.g., warning
codes, even if it has not declared an error by returning a true value
via the \*(L"err\*(R" method described above.
.PP
The \fIstate()\fR method should not be used to test for errors, use \fIerr()\fR
for that, because drivers may return a 'success with information' or
warning state code via \fIstate()\fR for methods that have not 'failed'.
.PP
\fI\f(CI\*(C`set_err\*(C'\fI\fR
.IX Subsection "set_err"
.PP
.Vb 4
\&  $rv = $h\->set_err($err, $errstr);
\&  $rv = $h\->set_err($err, $errstr, $state);
\&  $rv = $h\->set_err($err, $errstr, $state, $method);
\&  $rv = $h\->set_err($err, $errstr, $state, $method, $rv);
.Ve
.PP
Set the \f(CW\*(C`err\*(C'\fR, \f(CW\*(C`errstr\*(C'\fR, and \f(CW\*(C`state\*(C'\fR values for the handle.
This method is typically only used by \s-1DBI\s0 drivers and \s-1DBI\s0 subclasses.
.PP
If the \*(L"HandleSetErr\*(R" attribute holds a reference to a subroutine
it is called first. The subroutine can alter the \f(CW$err\fR, \f(CW$errstr\fR, \f(CW$state\fR,
and \f(CW$method\fR values. See \*(L"HandleSetErr\*(R" for full details.
If the subroutine returns a true value then the handle \f(CW\*(C`err\*(C'\fR,
\&\f(CW\*(C`errstr\*(C'\fR, and \f(CW\*(C`state\*(C'\fR values are not altered and \fIset_err()\fR returns
an empty list (it normally returns \f(CW$rv\fR which defaults to undef, see below).
.PP
Setting \f(CW\*(C`err\*(C'\fR to a \fItrue\fR value indicates an error and will trigger
the normal \s-1DBI\s0 error handling mechanisms, such as \f(CW\*(C`RaiseError\*(C'\fR and
\&\f(CW\*(C`HandleError\*(C'\fR, if they are enabled, when execution returns from
the \s-1DBI\s0 back to the application.
.PP
Setting \f(CW\*(C`err\*(C'\fR to \f(CW""\fR indicates an 'information' state, and setting
it to \f(CW"0"\fR indicates a 'warning' state. Setting \f(CW\*(C`err\*(C'\fR to \f(CW\*(C`undef\*(C'\fR
also sets \f(CW\*(C`errstr\*(C'\fR to undef, and \f(CW\*(C`state\*(C'\fR to \f(CW""\fR, irrespective
of the values of the \f(CW$errstr\fR and \f(CW$state\fR parameters.
.PP
The \f(CW$method\fR parameter provides an alternate method name for the
\&\f(CW\*(C`RaiseError\*(C'\fR/\f(CW\*(C`PrintError\*(C'\fR/\f(CW\*(C`PrintWarn\*(C'\fR error string instead of
the fairly unhelpful '\f(CW\*(C`set_err\*(C'\fR'.
.PP
The \f(CW\*(C`set_err\*(C'\fR method normally returns undef.  The \f(CW$rv\fR parameter
provides an alternate return value.
.PP
Some special rules apply if the \f(CW\*(C`err\*(C'\fR or \f(CW\*(C`errstr\*(C'\fR
values for the handle are \fIalready\fR set...
.PP
If \f(CW\*(C`errstr\*(C'\fR is true then: "\f(CW\*(C` [err was %s now %s]\*(C'\fR" is appended if \f(CW$err\fR is
true and \f(CW\*(C`err\*(C'\fR is already true and the new err value differs from the original
one. Similarly "\f(CW\*(C` [state was %s now %s]\*(C'\fR" is appended if \f(CW$state\fR is true and \f(CW\*(C`state\*(C'\fR is
already true and the new state value differs from the original one. Finally
"\f(CW\*(C`\en\*(C'\fR" and the new \f(CW$errstr\fR are appended if \f(CW$errstr\fR differs from the existing
errstr value. Obviously the \f(CW%s\fR's above are replaced by the corresponding values.
.PP
The handle \f(CW\*(C`err\*(C'\fR value is set to \f(CW$err\fR if: \f(CW$err\fR is true; or handle
\&\f(CW\*(C`err\*(C'\fR value is undef; or \f(CW$err\fR is defined and the length is greater
than the handle \f(CW\*(C`err\*(C'\fR length. The effect is that an 'information'
state only overrides undef; a 'warning' overrides undef or 'information',
and an 'error' state overrides anything.
.PP
The handle \f(CW\*(C`state\*(C'\fR value is set to \f(CW$state\fR if \f(CW$state\fR is true and
the handle \f(CW\*(C`err\*(C'\fR value was set (by the rules above).
.PP
Support for warning and information states was added in \s-1DBI\s0 1.41.
.PP
\fI\f(CI\*(C`trace\*(C'\fI\fR
.IX Subsection "trace"
.PP
.Vb 3
\&  $h\->trace($trace_settings);
\&  $h\->trace($trace_settings, $trace_filename);
\&  $trace_settings = $h\->trace;
.Ve
.PP
The \fItrace()\fR method is used to alter the trace settings for a handle
(and any future children of that handle).  It can also be used to
change where the trace output is sent.
.PP
There's a similar method, \f(CW\*(C`DBI\->trace\*(C'\fR, which sets the global
default trace settings.
.PP
See the \*(L"\s-1TRACING\s0\*(R" section for full details about the \s-1DBI\s0's powerful
tracing facilities.
.PP
\fI\f(CI\*(C`trace_msg\*(C'\fI\fR
.IX Subsection "trace_msg"
.PP
.Vb 2
\&  $h\->trace_msg($message_text);
\&  $h\->trace_msg($message_text, $min_level);
.Ve
.PP
Writes \f(CW$message_text\fR to the trace file if the trace level is
greater than or equal to \f(CW$min_level\fR (which defaults to 1).
Can also be called as \f(CW\*(C`DBI\->trace_msg($msg)\*(C'\fR.
.PP
See \*(L"\s-1TRACING\s0\*(R" for more details.
.PP
\fI\f(CI\*(C`func\*(C'\fI\fR
.IX Subsection "func"
.PP
.Vb 1
\&  $h\->func(@func_arguments, $func_name) or die ...;
.Ve
.PP
The \f(CW\*(C`func\*(C'\fR method can be used to call private non-standard and
non-portable methods implemented by the driver. Note that the function
name is given as the \fIlast\fR argument.
.PP
It's also important to note that the \fIfunc()\fR method does not clear
a previous error ($DBI::err etc.) and it does not trigger automatic
error detection (RaiseError etc.) so you must check the return
status and/or \f(CW$h\fR\->err to detect errors.
.PP
(This method is not directly related to calling stored procedures.
Calling stored procedures is currently not defined by the \s-1DBI\s0.
Some drivers, such as DBD::Oracle, support it in non-portable ways.
See driver documentation for more details.)
.PP
See also \fIinstall_method()\fR in \s-1DBI::DBD\s0 for how you can avoid needing to
use \fIfunc()\fR and gain direct access to driver-private methods.
.PP
\fI\f(CI\*(C`can\*(C'\fI\fR
.IX Subsection "can"
.PP
.Vb 1
\&  $is_implemented = $h\->can($method_name);
.Ve
.PP
Returns true if \f(CW$method_name\fR is implemented by the driver or a
default method is provided by the \s-1DBI\s0.
It returns false where a driver hasn't implemented a method and the
default method is provided by the \s-1DBI\s0 is just an empty stub.
.PP
\fI\f(CI\*(C`parse_trace_flags\*(C'\fI\fR
.IX Subsection "parse_trace_flags"
.PP
.Vb 1
\&  $trace_settings_integer = $h\->parse_trace_flags($trace_settings);
.Ve
.PP
Parses a string containing trace settings and returns the corresponding
integer value used internally by the \s-1DBI\s0 and drivers.
.PP
The \f(CW$trace_settings\fR argument is a string containing a trace level
between 0 and 15 and/or trace flag names separated by vertical bar
("\f(CW\*(C`|\*(C'\fR\*(L") or comma (\*(R"\f(CW\*(C`,\*(C'\fR") characters. For example: \f(CW"SQL|3|foo"\fR.
.PP
It uses the \fIparse_trace_flag()\fR method, described below, to process
the individual trage flag names.
.PP
The \fIparse_trace_flags()\fR method was added in \s-1DBI\s0 1.42.
.PP
\fI\f(CI\*(C`parse_trace_flag\*(C'\fI\fR
.IX Subsection "parse_trace_flag"
.PP
.Vb 1
\&  $bit_flag = $h\->parse_trace_flag($trace_flag_name);
.Ve
.PP
Returns the bit flag corresponding to the trace flag name in
\&\f(CW$trace_flag_name\fR.  Drivers are expected to override this method and
check if \f(CW$trace_flag_name\fR is a driver specific trace flags and, if
not, then call the DBIs default \fIparse_trace_flag()\fR.
.PP
The \fIparse_trace_flag()\fR method was added in \s-1DBI\s0 1.42.
.PP
\fI\f(CI\*(C`private_attribute_info\*(C'\fI\fR
.IX Subsection "private_attribute_info"
.PP
.Vb 1
\&  $hash_ref = $h\->private_attribute_info();
.Ve
.PP
Returns a reference to a hash whose keys are the names of driver-private
attributes available for the kind of handle (driver, database, statement)
that the method was called on.
.PP
For example, the return value when called with a DBD::Sybase \f(CW$dbh\fR could look like this:
.PP
.Vb 6
\&  {
\&      syb_dynamic_supported => undef,
\&      syb_oc_version => undef,
\&      syb_server_version => undef,
\