mirror of
https://github.com/php/php-src.git
synced 2024-10-04 08:16:11 +00:00
257 lines
9.6 KiB
XML
257 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.stmt.methods">
|
|
<title>Statement Handle Methods</title>
|
|
|
|
<para>
|
|
The <structname>pdo_stmt_methods</structname> structure defines the
|
|
methods for a given prepared statement handle. The methods are defined
|
|
below; each one is subject to the error handling protocol below.
|
|
</para>
|
|
|
|
<para>
|
|
Note that the <structfield>dbh</structfield> of the
|
|
<varname>stmt</varname> handle references the connection handle associated
|
|
with the statement.
|
|
</para>
|
|
|
|
<section id="stmt.error.protocol">
|
|
<title>Error handling protocol</title>
|
|
|
|
<para>
|
|
When a driver encounters an error on a prepared statement handle, it
|
|
must update the <structfield>error_code</structfield> field of the
|
|
<varname>stmt</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="stmt.dtor_func">
|
|
<title>SKEL_stmt_dtor_func</title>
|
|
|
|
<synopsis>int SKEL_stmt_dtor_func(pdo_stmt_t *stmt TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
This function is called by the PDO core when freeing resources
|
|
associated with the <varname>stmt</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="stmt.execute_func">
|
|
<title>SKEL_stmt_execute_func</title>
|
|
|
|
<synopsis>int SKEL_stmt_execute_func(pdo_stmt_t *stmt TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Starts the query. This is typically implemented as a call to the
|
|
database specific prepared statement execute function. Prior to calling
|
|
this function, the PDO core will trigger a
|
|
<constant>PDO_PARAM_EVT_EXEC_PRE</constant> event for each parameter,
|
|
offering the driver an opportunity to perform some final binding or
|
|
allocation actions prior to executing the statement.
|
|
</para>
|
|
<para>
|
|
<structfield>active_query_string</structfield> and
|
|
<structfield>active_query_stringlen</structfield> will be set by the PDO
|
|
core to reflect the query being executed. This is largely for the
|
|
convenience of drivers that don't natively support parameterized
|
|
queries; the query rewriter will have synthesized a query string with
|
|
the parameters expanded, if the
|
|
<structfield>supports_placeholders</structfield> indicates that it
|
|
should have. For drivers that do support parameterized queries, it is
|
|
anticipated that they will have already prepared their statement handles
|
|
and associated the parameters with it during the
|
|
<constant>PDO_PARAM_EVT_EXEC_PRE</constant> notification.
|
|
</para>
|
|
<para>
|
|
Immediately after executing, the PDO core will trigger a
|
|
<constant>PDO_PARAM_EVT_EXEC_POST</constant> event for each parameter,
|
|
offering the driver an opportunity to take some action, for example,
|
|
with parameters bound as OUT parameters.
|
|
</para>
|
|
|
|
<para>
|
|
Returns 1 on success, 0 on failure.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="stmt.fetch_func">
|
|
<title>SKEL_stmt_fetch_func</title>
|
|
|
|
<synopsis>int SKEL_stmt_fetch_func(pdo_stmt_t *stmt,
|
|
enum pdo_fetch_orientation ori, long offset TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Requests that the driver fetch the next row into driver storage. Prior to
|
|
calling this function the PDO core will trigger a
|
|
<constant>PDO_PARAM_EVT_FETCH_PRE</constant> event for each column,
|
|
offering the driver an opportunity to perform per-column allocations or
|
|
binding.
|
|
</para>
|
|
<para>
|
|
After calling this function, the PDO core will trigger a describe of the
|
|
columns if they haven't already been queried, and will then trigger a
|
|
<constant>PDO_PARAM_EVT_FETCH_POST</constant> event.
|
|
</para>
|
|
<para>
|
|
The orientation and offset parameters allow scrolling cursor operation.
|
|
</para>
|
|
<para>
|
|
Returns 1 if data was returned, 0 otherwise.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="stmt.describe_col_func">
|
|
<title>SKEL_stmt_describe_col_func</title>
|
|
|
|
<synopsis>int SKEL_stmt_describe_col_func(pdo_stmt_t *stmt,
|
|
int colno TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Requests that the driver populate the <structfield>columns</structfield>
|
|
field of <varname>stmt</varname> with information about a given column.
|
|
Columns are numbered zero-based in this function.
|
|
</para>
|
|
<para>
|
|
Returns 1 if successful, 0 otherwise.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="stmt.get_col_data_func">
|
|
<title>SKEL_stmt_get_col_data_func</title>
|
|
|
|
<synopsis>int SKEL_stmt_get_col_data_func(pdo_stmt_t *stmt,
|
|
int colno, char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
Requests that the driver return a pointer and size of the data for a
|
|
particular column. PDO prefers that the driver manage the lifetime of
|
|
this data (it can often reuse the same memory block for repeated
|
|
fetches). The PDO core will translate this memory, copying it if
|
|
necessary. If the driver must allocate transient memory for a column,
|
|
then it should do so using emalloc() and set caller_frees to a non-zero
|
|
value. This informs PDO that it is responsible for freeing the column
|
|
data when it is no longer required.
|
|
</para>
|
|
<para>
|
|
The type of pointer is specified by the column description prepared by
|
|
SKEL_stmt_describe_col_func.
|
|
</para>
|
|
<para>
|
|
Returns 1 if successful, 0 otherwise.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="stmt.param_hook_func">
|
|
<title>SKEL_stmt_param_hook_func</title>
|
|
|
|
<synopsis>int SKEL_stmt_param_hook_func(pdo_stmt_t *stmt,
|
|
struct pdo_bound_param_data *param, enum pdo_param_event event_type
|
|
TSRMLS_DC);</synopsis>
|
|
|
|
<para>
|
|
The param hook function is called by the PDO core at certain key points
|
|
in the setup of a statement handle, per parameter or column, to notify
|
|
the driver, so that it can perform some driver specific function.
|
|
</para>
|
|
<para>
|
|
The PDO core has no expectations for the hook function, except that it
|
|
should return 0 if there was an error, 1 otherwise.
|
|
</para>
|
|
<para>
|
|
The events that are possible are:
|
|
</para>
|
|
|
|
<bridgehead>PDO_PARAM_EVT_NORMALIZE</bridgehead>
|
|
<para>
|
|
Triggered before PDO_PARAM_EVT_ALLOC to normalize the parameter name.
|
|
This is not typically used by most drivers. The pgsql driver uses
|
|
this opportunity to fixup the parameter name and ordinal position before
|
|
the core registers its parameter state.
|
|
</para>
|
|
|
|
<bridgehead>PDO_PARAM_EVT_ALLOC</bridgehead>
|
|
<para>
|
|
Triggered in response to binding a parameter or column. This is the
|
|
drivers opportunity to allocate its driver-specific state for the
|
|
parameter.
|
|
</para>
|
|
<para>
|
|
Some drivers will take this opportunity to set up bind descriptors
|
|
if enough information is present in the param data. Note that this
|
|
stage is too early to be sure of the value (it may change between the
|
|
bind call and statement execution), so drivers must not snapshot
|
|
the value of the parameter at this point.
|
|
</para>
|
|
|
|
<bridgehead>PDO_PARAM_EVT_FREE</bridgehead>
|
|
<para>
|
|
Triggered when the core is done with a parameter, typically at statement
|
|
handle tear-down time. The driver must release any resources it may
|
|
have allocated for the parameter.
|
|
</para>
|
|
|
|
<bridgehead>PDO_PARAM_EVT_EXEC_PRE</bridgehead>
|
|
<para>
|
|
Triggered for each parameter immediately before invoking the
|
|
<function>SKEL_stmt_execute_func</function>. This is the correct time
|
|
to capture or reference the parameter value and finalize the binding of
|
|
the parameter.
|
|
</para>
|
|
|
|
<bridgehead>PDO_PARAM_EVT_EXEC_POST</bridgehead>
|
|
<para>
|
|
Triggered for each parameter immediately after invoking the
|
|
<function>SKEL_stmt_execute_func</function>. This allows a driver to
|
|
fixup or reconcile state, in particular for OUT parameters that have
|
|
been bound to a zval.
|
|
</para>
|
|
|
|
<bridgehead>PDO_PARAM_EVT_FETCH_PRE</bridgehead>
|
|
<para>
|
|
Triggered for each bound column immediately before invoking the
|
|
<function>SKEL_stmt_fetch_func</function>. This has similar semantics
|
|
to PDO_PARAM_EVT_EXEC_PRE, except that it applies to binding columns in
|
|
a result set to zvals rather than parameters in a prepared statement.
|
|
</para>
|
|
|
|
<bridgehead>PDO_PARAM_EVT_FETCH_POST</bridgehead>
|
|
<para>
|
|
Triggered for each bound column immediately after invoking the
|
|
<function>SKEL_stmt_fetch_func</function>. This has similar semantics
|
|
to PDO_PARAM_EVT_EXEC_POST, except that it applies to binding columns in
|
|
a result set to zvals rather than parameters in a prepared statement.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
|
|
</section>
|
|
|
|
<!--
|
|
vim:ts=2:sw=2:et:tw=78:
|
|
-->
|
|
|