mirror of
https://github.com/php/php-src.git
synced 2026-04-27 01:48:26 +02:00
Wez Furlong
286 lines
9.6 KiB
XML
286 lines
9.6 KiB
XML
<?xml version='1.0' encoding='UTF-8' ?>
|
|
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
|
|
<section id="drivers.dbh.methods">
|
|
<title>Database Handle Methods</title>
|
|
|
|
<para>
|
|
The <structname>pdo_dbh_methods</structname> structure defines the methods
|
|
for a given database connection handle. The methods are defined below;
|
|
each one is subject to the following error handling protocol:
|
|
</para>
|
|
|
|
<section id="dbh.error.protocol">
|
|
<title>Error handling protocol</title>
|
|
|
|
<para>
|
|
When a driver encounters an error, it must update the
|
|
<structfield>error_code</structfield> field of the
|
|
<varname>dbh</varname> to hold an appropriate SQLSTATE error code, and
|
|
take some action to record the driver specific error code and human
|
|
readable message, if necessary.
|
|
</para>
|
|
<para>
|
|
The method descriptions below describe how to indicate an error
|
|
status. The PDO core may invoke the
|
|
<function>SKEL_fetch_error_func</function> to obtain the driver
|
|
specific error code and human readable message.
|
|
</para>
|
|
<para>
|
|
The driver should not unilaterally raise an exception in reponse to an
|
|
error. Instead, it should be left to the PDO core to handle reporting
|
|
the error to the script, based on the application preferences for
|
|
error handling.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="dbh.close_func">
|
|
<title>SKEL_close_func</title>
|
|
|
|
<synopsis>int SKEL_close_func(pdo_dbh_t *dbh TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
This function is called by the PDO core when freeing resources
|
|
associated with the <varname>dbh</varname>. It should release any
|
|
resources allocated by the driver.
|
|
</para>
|
|
|
|
<para>
|
|
Returns 0. An implementation bug means that the return value is not
|
|
checked.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.prepare_func">
|
|
<title>SKEL_prepare_func</title>
|
|
|
|
<synopsis>int SKEL_prepare_func(pdo_dbh_t *dbh, const char *sql,
|
|
long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
This function is called when creating a statement handle. It is
|
|
described in more detail in <xref
|
|
linkend="drivers.stmt.prepare"/>.
|
|
</para>
|
|
|
|
<para>
|
|
Returns 1 on success, 0 on failure.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.do_func">
|
|
<title>SKEL_do_func</title>
|
|
|
|
<synopsis>int SKEL_do_func(pdo_dbh_t *dbh, const char *sql,
|
|
long sql_len TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Execute a statement that does not return a result set.
|
|
</para>
|
|
|
|
<para>
|
|
Returns -1 on failure, or the number of affected rows otherwise.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.quote_func">
|
|
<title>SKEL_quote_func</title>
|
|
|
|
<synopsis>int SKEL_quote_func(pdo_dbh_t *dbh, const char *unquoted,
|
|
int unquoted_len, char **quoted, int *quotedlen,
|
|
enum pdo_param_type paramtype TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Quote a parameter, escaping SQL meta-characters as appropriate and
|
|
enclosing the parameter in appropriate quotation marks. This function
|
|
will allocate an appropriately sized buffer using
|
|
<function>emalloc</function> and return it to the caller by setting
|
|
<parameter>quoted</parameter> and <parameter>quotedlen</parameter> to
|
|
the buffer and its length.
|
|
</para>
|
|
|
|
<para>
|
|
The return value should be 1 if the function generated a quoted
|
|
string, or 0 otherwise.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.begin_func">
|
|
<title>SKEL_begin_func</title>
|
|
|
|
<synopsis>int SKEL_begin_func(pdo_dbh_t *dbh TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
This function begins a transaction on the connection. If the driver
|
|
does not support transactions, it should not provide this method.
|
|
</para>
|
|
|
|
<para>
|
|
Returns 1 to indicate that a new transaction has begun, 0 to indicate
|
|
error. The PDO core maintains its own idea of whether a transaction
|
|
is in progress, so the driver should not maintain its own.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.commit_func">
|
|
<title>SKEL_commit_func</title>
|
|
|
|
<synopsis>int SKEL_commit_func(pdo_dbh_t *dbh TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
This function commits a transaction on the connection. If the driver
|
|
does not support transactions, it should not provide this method.
|
|
</para>
|
|
|
|
<para>
|
|
Returns 1 to indicate that the transaction was committed, 0 otherwise.
|
|
Once committed, PDO assumes that a transaction is no longer active.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.rollback_func">
|
|
<title>SKEL_rollback_func</title>
|
|
|
|
<synopsis>int SKEL_rollback_func(pdo_dbh_t *dbh TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
This function rolls back a transaction on the connection. If the driver
|
|
does not support transactions, it should not provide this method.
|
|
</para>
|
|
<para>
|
|
Returns 1 to indicate a successful rollback, 0 otherwise.
|
|
Once rolled back, PDO assumes that a transaction is no longer active.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.set_attr_func">
|
|
<title>SKEL_set_attr_func</title>
|
|
|
|
<synopsis>int SKEL_set_attr_func(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Sets an attribute on the database handle. Returns 1 if the attribute
|
|
was set successfully, 0 otherwise. There are a number of attributes
|
|
that can be set, and these are discussed in <xref
|
|
linkend="attributes.dbh"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.last_id_func">
|
|
<title>SKEL_last_id_func</title>
|
|
|
|
<synopsis>char *SKEL_last_id_func(pdo_dbh_t *dbh, const char *name,
|
|
unsigned int *len TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Returns the last insert id. A NULL return value indicates an error
|
|
condition, otherwise the return value must be a NUL terminated string
|
|
allocated using <function>emalloc</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.fetch_error_func">
|
|
<title>SKEL_fetch_error_func</title>
|
|
|
|
<synopsis>int SKEL_fetch_error_func(pdo_dbh_t *dbh, pdo_stmt *stmt,
|
|
zval *info TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Fetch error information. If stmt is not NULL, fetch information
|
|
pertaining to the statement, otherwise fetch the connection level
|
|
error information. The driver should add the following information
|
|
to the array "info" in this order: a) the native error code and b) a
|
|
string representation of the error code.
|
|
</para>
|
|
<para>
|
|
A driver may optionally append any other arbitrary, useful,
|
|
information to the info array.
|
|
</para>
|
|
<para>
|
|
Returns 1 to indicate that it populated info, 0 otherwise.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.get_attr_func">
|
|
<title>SKEL_get_attr_func</title>
|
|
|
|
<synopsis>int SKEL_get_attr_func(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Retrieves an attribute from a database handle. Returns 0 if the
|
|
driver doesn't support the attribute. Returns -1 if the driver
|
|
encountered an error. Returns 1 on success. There are a number of
|
|
attributes that can be fetched, and these are discussed in <xref
|
|
linkend="attributes.dbh"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.check_liveness">
|
|
<title>SKEL_check_liveness_func</title>
|
|
|
|
<synopsis>int SKEL_check_liveness_func(pdo_dbh_t *dbh TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Performs some driver dependent action to determine if a connection is
|
|
still valid for use, typically a low overhead ping. Returns
|
|
<constant>SUCCESS</constant> if the connection is still alive and
|
|
ready to be used, <constant>FAILURE</constant> if the connection is
|
|
no longer alive (perhaps it timed out). If this function is not
|
|
provided, it is equivalent to defining a function that always returns
|
|
<constant>SUCCESS</constant>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.get_driver_methods">
|
|
<title>SKEL_get_driver_methods_func</title>
|
|
|
|
<synopsis>zend_function_entry *SKEL_get_driver_methods_func(
|
|
pdo_dbh_t *dbh, int kind TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
When a PHP script attempts to call a method on a PDO or PDOStatement
|
|
object that is not covered by either this specification or by a user
|
|
defined class that extends either PDO or a PDOStatement, then
|
|
<function>SKEL_get_driver_methods_func</function> is called to
|
|
determine the driver extension methods that are present.
|
|
</para>
|
|
<para>
|
|
When kind is <constant>PDO_DBH_DRIVER_METHOD_KIND_DBH</constant>, the
|
|
driver extension method table for the connection handle must be
|
|
returned. When kind is
|
|
<constant>PDO_DBH_DRIVER_METHOD_KIND_STMT</constant>, the driver
|
|
extension method table for the statement handle must be returned.
|
|
</para>
|
|
<para>
|
|
The return value is either a <type>zend_function_entry</type> pointer
|
|
referencing a table of methods, or NULL to indicate that there are no
|
|
extension methods available.
|
|
</para>
|
|
<para>
|
|
Driver extension methods must be prefixed with the driver name used to
|
|
register the driver so that they are less likely to collide with
|
|
either future PDO methods or user defined functions in derived
|
|
classes.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="dbh.request_shutdown">
|
|
<title>SKEL_request_shutdown_func</title>
|
|
|
|
<synopsis>void SKEL_request_shutdown_func(pdo_dbh_t *dbh TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Called when a script terminates (request shutdown) for a persistent
|
|
connection handle. This provides the opportunity to safely releases
|
|
resources that only have per-request scope.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<!--
|
|
vim:ts=2:sw=2:et:tw=78:
|
|
-->
|
|
|