<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Fleshing out your skeleton</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="internals2.pdo.preparation.html">Preparation and Housekeeping</a></div>
<div class="next" style="text-align: right; float: right;"><a href="internals2.pdo.building.html">Building</a></div>
<div class="up"><a href="internals2.pdo.html">PDO Driver How-To</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="internals2.pdo.implementing" class="sect1">
<h2 class="title">Fleshing out your skeleton</h2>
<div class="sect2" id="internals2.pdo.implementing.structures">
<h3 class="title">Major Structures and Attributes</h3>
<p class="para">
The major structures, pdo_dbh_t and pdo_stmt_t are defined and explained in
Appendix A and B respectively. Database and Statement attributes are
defined in Appendix C. Error handling is explained in Appendix D.
</p>
</div>
<div class="sect2" id="internals2.pdo.implementing.skel">
<h3 class="title">pdo_SKEL.c: PHP extension glue</h3>
<div class="sect3" id="internals2.pdo.implementing.skel.entries">
<h4 class="title">function entries</h4>
<pre class="synopsis"><div class="cdata"><pre>
static function_entry pdo_SKEL_functions[] = {
{ NULL, NULL, NULL }
};</pre></div></pre>
<p class="para">
This structure is used to register functions into the global php function
namespace. PDO drivers should try to avoid doing this, so it is
recommended that you leave this structure initialized to NULL, as shown in
the synopsis above.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.skel.module">
<h4 class="title">Module entry</h4>
<pre class="synopsis"><div class="cdata"><pre>
/* {{{ pdo_SKEL_module_entry */
#if ZEND_EXTENSION_API_NO >= 220050617
static zend_module_dep pdo_SKEL_deps[] = {
ZEND_MOD_REQUIRED("pdo")
{NULL, NULL, NULL}
};
#endif
/* }}} */
zend_module_entry pdo_SKEL_module_entry = {
#if ZEND_EXTENSION_API_NO >= 220050617
STANDARD_MODULE_HEADER_EX, NULL,
pdo_SKEL_deps,
#else
STANDARD_MODULE_HEADER,
#endif
"pdo_SKEL",
pdo_SKEL_functions,
PHP_MINIT(pdo_SKEL),
PHP_MSHUTDOWN(pdo_SKEL),
NULL,
NULL,
PHP_MINFO(pdo_SKEL),
PHP_PDO_<DB>_MODULE_VERSION,
STANDARD_MODULE_PROPERTIES
};
/* }}} */
#ifdef COMPILE_DL_PDO_<DB>
ZEND_GET_MODULE(pdo_db)
#endif</pre></div></pre>
<p class="para">
A structure of type zend_module_entry called
pdo_SKEL_module_entry must be declared and should include reference to
the pdo_SKEL_functions table defined previously.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.skel.functions">
<h4 class="title">Standard PHP Module Extension Functions</h4>
<div class="sect4" id="internals2.pdo.implementing.skel.functions.minit">
<h5 class="title">PHP_MINIT_FUNCTION</h5>
<pre class="synopsis"><div class="cdata"><pre>
/* {{{ PHP_MINIT_FUNCTION */
PHP_MINIT_FUNCTION(pdo_SKEL)
{
return php_pdo_register_driver(&pdo_SKEL_driver);
}
/* }}} */</pre></div></pre>
<p class="para">
This standard PHP extension function should be used to register your
driver with the PDO layer. This is done by calling the
<span class="function"><strong>php_pdo_register_driver()</strong></span> function passing a pointer to
a structure of type <span class="type"><span class="type pdo_driver_t">pdo_driver_t</span></span> typically named
<em>pdo_SKEL_driver</em>. A <span class="type"><span class="type pdo_driver_t">pdo_driver_t</span></span>
contains a header that is generated using the
<em>PDO_DRIVER_HEADER(SKEL)</em> macro and
<span class="function"><strong>pdo_SKEL_handle_factory()</strong></span> function pointer. The
actual function is described during the discussion of the
<var class="filename">SKEL_dbh.c</var> unit.
</p>
</div>
<div class="sect4" id="internals2.pdo.implementing.skel.functions.mshutdown">
<h5 class="title">PHP_MSHUTDOWN_FUNCTION</h5>
<pre class="synopsis"><div class="cdata"><pre>
/* {{{ PHP_MSHUTDOWN_FUNCTION */
PHP_MSHUTDOWN_FUNCTION(pdo_SKEL)
{
php_pdo_unregister_driver(&pdo_SKEL_driver);
return SUCCESS;
}
/* }}} */</pre></div></pre>
<p class="para">
This standard PHP extension function is used to unregister your driver
from the PDO layer. This is done by calling the
<span class="function"><strong>php_pdo_unregister_driver()</strong></span> function, passing the same
<em>pdo_SKEL_driver</em> structure that was passed in the
init function above.
</p>
</div>
<div class="sect4" id="internals2.pdo.implementing.skel.functions.minfo">
<h5 class="title">PHP_MINFO_FUNCTION</h5>
<p class="para">
This is again a standard PHP extension function. Its purpose is to
display information regarding the module when the
<span class="function"><a href="function.phpinfo.html" class="function">phpinfo()</a></span> is called from a script. The convention is
to display the version
of the module and also what version of the db you are dependent on, along
with any other configuration style information that might be relevant.
</p>
</div>
</div>
</div>
<div class="sect2" id="internals2.pdo.implementing.driver">
<h3 class="title">SKEL_driver.c: Driver implementation</h3>
<p class="para">
This unit implements all of the database handling methods that support the
PDO database handle object. It also contains the error fetching routines.
All of these functions will typically need to access the global variable
pool. Therefore, it is necessary to use the Zend macro TSRMLS_DC macro at
the end of each of these statements. Consult the Zend programmer
documentation for more information on this macro.
</p>
<div class="sect3" id="internals2.pdo.implementing.driver.error">
<h4 class="title">pdo_SKEL_error</h4>
<pre class="synopsis"><div class="cdata"><pre>static int pdo_SKEL_error(pdo_dbh_t *dbh,
pdo_stmt_t *stmt, const char *file, int line TSRMLS_DC)</pre></div></pre>
<p class="para">
The purpose of this function is to be used as a generic error handling
function within the driver. It is called by the driver when an error occurs
within the driver. If an error occurs that is not related to SQLSTATE, the
driver should set either <em>dbh->error_code</em> or
<em>stmt->error_code</em> to an
SQLSTATE that most closely matches the error or the generic SQLSTATE error
"<span class="quote">HY000</span>". The file pdo_sqlstate.c in the PDO source contains a table
of commonly used SQLSTATE codes that the PDO code explicitly recognizes.
This setting of the error code should be done prior to calling this
function.; This function should set the global
<em><code class="parameter">pdo_err</code></em> variable to the error found in either the
dbh or the stmt (if the variable stmt is not NULL).
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the current statement or NULL. If NULL, the error is derived by error code found in the dbh.</p>
</dd>
</dt>
<dt>
<span class="term">file</span>
<dd>
<p class="para">The source file where the error occurred or NULL if not available.</p>
</dd>
</dt>
<dt>
<span class="term">line</span>
<dd>
<p class="para">The line number within the source file if available.</p>
</dd>
</dt>
</dl>
<p class="para">
If the dbh member methods is NULL (which implies that the error is being
raised from within the PDO constructor), this function should call the
zend_throw_exception_ex() function otherwise it should return the error
code. This function is usually called using a helper macro that customizes
the calling sequence for either database handling errors or statement
handling errors.
</p>
<div class="example" id="internals2.pdo.implementing.driver.error.ex-macros">
<p><strong>Example #1 Example macros for invoking pdo_SKEL_error</strong></p>
<div class="example-contents"><div class="ccode"><pre class="ccode">#define pdo_SKEL_drv_error(what) \
pdo_SKEL_error(dbh, NULL, what, __FILE__, __LINE__ TSRMLS_CC)
#define pdo_SKEL_drv_error(what) \
pdo_SKEL_error(dbh, NULL, what, __FILE__, __LINE__ TSRMLS_CC)</pre>
</div>
</div>
</div>
<p class="para">
For more info on error handling, see <a href="internals2.pdo.error-handling.html" class="xref">Error handling</a>.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Despite being documented here, the PDO driver interface does not specify
that this function be present; it is merely a convenient way to handle
errors, and it just happens to be equally convenient for the majority of
database client library APIs to structure your driver implementation in
this way.
</p>
</p></blockquote>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.fetch-err">
<h4 class="title">pdo_SKEL_fetch_error_func</h4>
<pre class="synopsis"><div class="cdata"><pre>static int pdo_SKEL_fetch_error_func(pdo_dbh_t *dbh, pdo_stmt_t *stmt,
zval *info TSRMLS_DC)</pre></div></pre>
<p class="para">
The purpose of this function is to obtain additional information about the
last error that was triggered. This includes the driver specific error
code and a human readable string. It may also include additional
information if appropriate. This function is called as a result of the PHP
script calling the <span class="function"><a href="pdo.errorinfo.html" class="function">PDO::errorInfo()</a></span> method.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">
Pointer to the most current statement or NULL. If NULL, the error
translated is derived by error code found in the dbh.
</p>
</dd>
</dt>
<dt>
<span class="term">info</span>
<dd>
<p class="para">A hash table containing error codes and messages.</p>
</dd>
</dt>
</dl>
<p class="para">
The error_func should return two pieces of information as successive array
elements. The first item is expected to be a numeric error code, the second
item is a descriptive string. The best way to set this item is by using
add_next_index. Note that the type of the first argument need not be
<span class="type"><span class="type long">long</span></span>; use whichever type most closely matches the error code
returned by the underlying database API.
</p>
<div class="example-contents"><div class="ccode"><pre class="ccode">/* now add the error information. */
/* These need to be added in a specific order */
add_next_index_long(info, error_code); /* driver specific error code */
add_next_index_string(info, message, 0); /* readable error message */</pre>
</div></div>
<p class="para">
This function should return 1 if information is available, 0 if the driver
does not have additional info.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.handle-closer">
<h4 class="title">SKEL_handle_closer</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_closer(pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to close an open
database.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
</dl>
<p class="para">
This should do whatever database specific activity that needs to be
accomplished to close the open database. PDO ignores the return
value from this function.
</p>
</div>
<div class="sect3" id="internals2.pdo.preparer">
<h4 class="title">SKEL_handle_preparer</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql,
long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO in response to
<span class="function"><a href="pdo.query.html" class="function">PDO::query()</a></span> and <span class="function"><a href="pdo.prepare.html" class="function">PDO::prepare()</a></span>
calls from the PHP script. The purpose of the function is to prepare
raw SQL for execution, storing whatever state is appropriate into the
<em><code class="parameter">stmt</code></em> that is passed in.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">sql</span>
<dd>
<p class="para">Pointer to a character string containing the SQL statement to be prepared.</p>
</dd>
</dt>
<dt>
<span class="term">sql_len</span>
<dd>
<p class="para">The length of the SQL statement.</p>
</dd>
</dt>
<dt>
<span class="term">Stmt</span>
<dd>
<p class="para">Pointer to the returned statement or NULL if an error occurs.</p>
</dd>
</dt>
<dt>
<span class="term">driver_options</span>
<dd>
<p class="para">Any driver specific/defined options.</p>
</dd>
</dt>
</dl>
<p class="para">
This function is essentially the constructor for a stmt object. This
function is responsible for processing statement options, and setting
driver-specific option fields in the pdo_stmt_t structure.
</p>
<p class="para">
PDO does not process any statement options on the driver's
behalf before calling the preparer function. It is your responsibility to
process them before you return, raising an error for any unknown options that
are passed.
</p>
<p class="para">
One very important responsibility of this function is the processing of SQL
statement parameters. At the time of this call, PDO does not know if your
driver supports binding parameters into prepared statements, nor does it
know if it supports named or positional parameter naming conventions.
</p>
<p class="para">
Your driver is responsible for setting
<em>stmt->supports_placeholders</em> as appropriate for the
underlying database. This may involve some run-time determination on the
part of your driver, if this setting depends on the version of the database
server to which it is connected. If your driver doesn't directly support
both named and positional parameter conventions, you should use the
<span class="function"><strong>pdo_parse_params()</strong></span> API to have PDO rewrite the query to
take advantage of the support provided by your database.
</p>
<div class="example" id="internals2.pdo.implementing.preparer.ex-parse-params">
<p><strong>Example #2 Using pdo_parse_params</strong></p>
<div class="example-contents"><div class="ccode"><pre class="ccode">int ret;
char *nsql = NULL;
int nsql_len = 0;
/* before we prepare, we need to peek at the query; if it uses named parameters,
* we want PDO to rewrite them for us */
stmt->supports_placeholders = PDO_PLACEHOLDER_POSITIONAL;
ret = pdo_parse_params(stmt, (char*)sql, sql_len, &nsql, &nsql_len TSRMLS_CC);
if (ret == 1) {
/* query was re-written */
sql = nsql;
} else if (ret == -1) {
/* couldn't grok it */
strcpy(dbh->error_code, stmt->error_code);
return 0;
}
/* now proceed to prepare the query in "sql" */</pre>
</div></div>
</div>
<p class="para">
Possible values for <em>supports_placeholders</em> are:
<strong><code>PDO_PLACEHOLDER_NAMED</code></strong>,
<strong><code>PDO_PLACEHOLDER_POSITIONAL</code></strong> and
<strong><code>PDO_PLACEHOLDER_NONE</code></strong>. If the driver doesn't support prepare statements at all, then this function should simply allocate any state that it might need, and then return:
</p>
<div class="example" id="internals2.pdo.implementing.preparer.ex-no-native-prep">
<p><strong>Example #3 Implementing preparer for drivers that don't support native prepared statements</strong></p>
<div class="example-contents"><div class="ccode"><pre class="ccode">static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql,
long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC)
{
pdo_SKEL_db_handle *H = (pdo_SKEL_db_handle *)dbh->driver_data;
pdo_SKEL_stmt *S = ecalloc(1, sizeof(pdo_SKEL_stmt));
S->H = H;
stmt->driver_data = S;
stmt->methods = &SKEL_stmt_methods;
stmt->supports_placeholders = PDO_PLACEHOLDER_NONE;
return 1;
}</pre>
</div></div>
</div>
<p class="para">This function returns 1 on success or 0 on failure.</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.handle-doer">
<h4 class="title">SKEL_handle_doer</h4>
<pre class="synopsis"><div class="cdata"><pre>static long SKEL_handle_doer(pdo_dbh_t *dbh, const char *sql, long sql_len TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to execute a raw SQL
statement. No pdo_stmt_t is created.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">sql</span>
<dd>
<p class="para">Pointer to a character string containing the SQL statement to be prepared.</p>
</dd>
</dt>
<dt>
<span class="term">sql_len</span>
<dd>
<p class="para">The length of the SQL statement.</p>
</dd>
</dt>
</dl>
<p class="para">
This function returns 1 on success or 0 on failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.handle-quoter">
<h4 class="title">SKEL_handle_quoter</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_quoter(pdo_dbh_t *dbh, const char *unquoted,
int unquoted_len, char **quoted, int quoted_len, enum pdo_param_type param_type TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to turn an unquoted
string into a quoted string for use in a query.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">unquoted</span>
<dd>
<p class="para">Pointer to a character string containing the string to be quoted.</p>
</dd>
</dt>
<dt>
<span class="term">unquoted_len</span>
<dd>
<p class="para">The length of the string to be quoted.</p>
</dd>
</dt>
<dt>
<span class="term">quoted</span>
<dd>
<p class="para">Pointer to the address where a pointer to the newly quoted string will be returned.</p>
</dd>
</dt>
<dt>
<span class="term">quoted_len</span>
<dd>
<p class="para">The length of the new string.</p>
</dd>
</dt>
<dt>
<span class="term">param_type</span>
<dd>
<p class="para">A driver specific hint for driver that have alternate quoting styles</p>
</dd>
</dt>
</dl>
<p class="para">
This function is called in response to a call to
<span class="function"><a href="pdo.quote.html" class="function">PDO::quote()</a></span> or when the driver has set
<em>supports_placeholder</em> to
<strong><code>PDO_PLACEHOLDER_NONE</code></strong>. The purpose is to quote a
parameter when building SQL statements.
</p>
<p class="para">
If your driver does not support native prepared statements, implementation
of this function is required.
</p>
<p class="para">
This function returns 1 if the quoting process reformatted the string, and
0 if it was not necessary to change the string. The original string will be
used unchanged with a 0 return.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.handle-begin">
<h4 class="title">SKEL_handle_begin</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_begin(pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to begin a database transaction.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
</dl>
<p class="para">
This should do whatever database specific activity that needs to be
accomplished to begin a transaction. This function returns 1 for success or
0 if an error occurred.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.handle-commit">
<h4 class="title">SKEL_handle_commit</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_commit(pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to end a database
transaction.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
</dl>
<p class="para">
This should do whatever database specific activity that needs to be
accomplished to commit a transaction. This function returns 1 for success or 0 if an error occurred.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.handle-rollback">
<h4 class="title">SKEL_handle_rollback</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_rollback( pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>
<p class="para">This function will be called by PDO to rollback a database transaction.</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
</dl>
<p class="para">
This should do whatever database specific activity that needs to be
accomplished to rollback a transaction. This function returns 1 for
success or 0 if an error occurred.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.get-attr">
<h4 class="title">SKEL_handle_get_attribute</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_get_attribute(pdo_dbh_t *dbh, long attr, zval *return_value TSRMLS_DC)</pre></div></pre>
<p class="para">This function will be called by PDO to retrieve a database attribute.</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">attr</span>
<dd>
<p class="para">
<span class="type"><span class="type long">long</span></span> value of one of the PDO_ATTR_xxxx types. See <a href="internals2.pdo.constants.html#internals2.pdo.table.attributes" class="xref">Database and Statement Attributes Table</a> for valid attributes.
</p>
</dd>
</dt>
<dt>
<span class="term">return_value</span>
<dd>
<p class="para">The returned value for the attribute.</p>
</dd>
</dt>
</dl>
<p class="para">
It is up to the driver to decide which attributes will be supported for a
particular implementation. It is not necessary for a driver to supply this
function. PDO driver handles the PDO_ATTR_PERSISTENT, PDO_ATTR_CASE,
PDO_ATTR_ORACLE_NULLS, and PDO_ATTR_ERRMODE attributes directly.
</p>
<p class="para">
This function returns 1 on success or 0 on failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.set-attr">
<h4 class="title">SKEL_handle_set_attribute</h4>
<pre class="synopsis">static int SKEL_handle_set_attribute(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC)</pre>
<p class="para">
This function will be called by PDO to set a database attribute, usually in
response to a script calling <span class="function"><a href="pdo.setattribute.html" class="function">PDO::setAttribute()</a></span>.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">attr</span>
<dd>
<p class="para">
<span class="type"><span class="type long">long</span></span> value of one of the PDO_ATTR_xxxx types. See <a href="internals2.pdo.constants.html#internals2.pdo.table.attributes" class="xref">Database and Statement Attributes Table</a> for valid attributes.
</p>
</dd>
</dt>
<dt>
<span class="term">val</span>
<dd>
<p class="para">The new value for the attribute.</p>
</dd>
</dt>
</dl>
<p class="para">
It is up to the driver to decide which attributes will be supported for a
particular implementation. It is not necessary for a driver to provide this
function if it does not need to support additional attributes. The PDO
driver handles the PDO_ATTR_CASE, PDO_ATTR_ORACLE_NULLS, and
PDO_ATTR_ERRMODE attributes directly.
</p>
<p class="para">
This function returns 1 on success or 0 on failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.last-id">
<h4 class="title">SKEL_handle_last_id</h4>
<pre class="synopsis"><div class="cdata"><pre>static char * SKEL_handle_last_id(pdo_dbh_t *dbh, const char *name, unsigned int len TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to retrieve the ID of the last inserted
row.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">name</span>
<dd>
<p class="para">
string representing a table or sequence name.
</p>
</dd>
</dt>
<dt>
<span class="term">len</span>
<dd>
<p class="para">the length of the <em><code class="parameter">name</code></em> parameter.</p>
</dd>
</dt>
</dl>
<p class="para">
This function returns a character string containing the id of the last
inserted row on success or NULL on failure. This is an optional function.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.check-live">
<h4 class="title">SKEL_check_liveness</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_check_liveness(pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to test whether or not a persistent
connection to a database is alive and ready for use.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
</dl>
<p class="para">
This function returns 1 if the database connection is alive and ready
for use, otherwise it should return 0 to indicate failure or lack
of support.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
This is an optional function.
</p>
</p></blockquote>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.get-methods">
<h4 class="title">SKEL_get_driver_methods</h4>
<pre class="synopsis"><div class="cdata"><pre>static function_entry *SKEL_get_driver_methods(pdo_dbh_t *dbh, int kind TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO in response to a call to any method
that is not a part of either the <a href="class.pdo.html" class="classname">PDO</a> or
<a href="class.pdostatement.html" class="classname">PDOStatement</a> classes. It's purpose is to allow the
driver to provide additional driver specific methods to those classes.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">kind</span>
<dd>
<p class="para">One of the following:</p>
<dl>
<dt>
<span class="term">PDO_DBH_DRIVER_METHOD_KIND_DBH</span>
<dd>
<p class="para">
Set when the method call was attempted on an instance of the
<a href="class.pdo.html" class="classname">PDO</a> class. The driver should return a pointer
a function_entry table for any methods it wants to add to that class,
or NULL if there are none.
</p>
</dd>
</dt>
<dt>
<span class="term">PDO_DBH_DRIVER_METHOD_KIND_STMT</span>
<dd>
<p class="para">
Set when the method call was attempted on an instance of the
<a href="class.pdostatement.html" class="classname">PDOStatement</a> class. The driver should return
a pointer to a function_entry table for any methods it wants to add
to that class, or NULL if there are none.
</p>
</dd>
</dt>
</dl>
</dd>
</dt>
</dl>
<p class="para">
This function returns a pointer to the function_entry table requested,
or NULL there are no driver specific methods.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.handle-factory">
<h4 class="title">SKEL_handle_factory</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_factory(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to create a database handle. For most
databases this involves establishing a connection to the database. In some
cases, a persistent connection may be requested, in other cases connection
pooling may be requested. All of these are database/driver dependent.
</p>
<dl>
<dt>
<span class="term">dbh</span>
<dd>
<p class="para">Pointer to the database handle initialized by the handle factory</p>
</dd>
</dt>
<dt>
<span class="term">driver_options</span>
<dd>
<p class="para">
An array of driver options, keyed by integer option number. See <a href="internals2.pdo.constants.html#internals2.pdo.table.attributes" class="xref">Database and Statement Attributes Table</a> for a list of possible attributes.
</p>
</dd>
</dt>
</dl>
<p class="para">
This function should fill in the passed database handle structure with its
driver specific information on success and return 1, otherwise it should
return 0 to indicate failure.
</p>
<p class="para">
PDO processes the AUTOCOMMIT and PERSISTENT driver options
before calling the handle_factory. It is the handle factory's
responsibility to process other options.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.method-table">
<h4 class="title">Driver method table</h4>
<p class="para">
A static structure of type pdo_dbh_methods named SKEL_methods must be
declared and initialized to the function pointers for each defined
function. If a function is not supported or not implemented the value for
that function pointer should be set to NULL.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.driver.skeldriver">
<h4 class="title">pdo_SKEL_driver</h4>
<p class="para">
A structure of type pdo_driver_t named pdo_SKEL_driver should be declared.
The PDO_DRIVER_HEADER(SKEL) macro should be used to declare the header and
the function pointer to the handle factory function should set.
</p>
</div>
</div>
<div class="sect2" id="internals2.pdo.implementing.statement">
<h3 class="title">SKEL_statement.c: Statement implementation</h3>
<p class="para">
This unit implements all of the database statement handling methods that
support the PDO statement object.
</p>
<div class="sect3" id="internals2.pdo.implementing.statement.dtor">
<h4 class="title">SKEL_stmt_dtor</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_stmt_dtor(pdo_stmt_t *stmt TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to destroy a previously constructed statement object.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
</dl>
<p class="para">
This should do whatever is necessary to free up any driver specific storage
allocated for the statement. The return value from this function is
ignored.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.exec">
<h4 class="title">SKEL_stmt_execute</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_stmt_execute(pdo_stmt_t *stmt TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to execute the prepared SQL statement
in the passed statement object.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
</dl>
<p class="para">
This function returns 1 for success or 0 in the event of failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.fetch">
<h4 class="title">SKEL_stmt_fetch</h4>
<pre class="synopsis">static int SKEL_stmt_fetch(pdo_stmt_t *stmt, enum pdo_fetch_orientation ori,
long offset TSRMLS_DC)</pre>
<p class="para">
This function will be called by PDO to fetch a row from a previously
executed statement object.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
<dt>
<span class="term">ori</span>
<dd>
<p class="para">One of PDO_FETCH_ORI_xxx which will determine which row will be fetched.</p>
</dd>
</dt>
<dt>
<span class="term">offset</span>
<dd>
<p class="para">
If ori is set to PDO_FETCH_ORI_ABS or PDO_FETCH_ORI_REL, offset
represents the row desired or the row relative to the current position,
respectively. Otherwise, this value is ignored.
</p>
</dd>
</dt>
</dl>
<p class="para">
The results of this fetch are driver dependent and the data is usually
stored in the driver_data member of the pdo_stmt_t object. The ori and
offset parameters are only meaningful if the statement represents a
scrollable cursor. This function returns 1 for success or 0 in the event of
failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.param-hook">
<h4 class="title">SKEL_stmt_param_hook</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_stmt_param_hook(pdo_stmt_t *stmt,
struct pdo_bound_param_data *param, enum pdo_param_event event_type TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO for handling of both bound parameters and bound columns.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
<dt>
<span class="term">param</span>
<dd>
<p class="para">
The structure describing either a statement parameter or a bound column.
</p>
</dd>
</dt>
<dt>
<span class="term">event_type</span>
<dd>
<p class="para">The type of event to occur for this parameter, one of the following:</p>
<dl>
<dt>
<span class="term">PDO_PARAM_EVT_ALLOC</span>
<dd>
<p class="para">Called when PDO allocates the binding. Occurs as part of
<span class="function"><a href="pdostatement.bindparam.html" class="function">PDOStatement::bindParam()</a></span>,
<span class="function"><a href="pdostatement.bindvalue.html" class="function">PDOStatement::bindValue()</a></span> or as part of an implicit bind
when calling <span class="function"><a href="pdostatement.execute.html" class="function">PDOStatement::execute()</a></span>. This is your
opportunity to take some action at this point; drivers that implement
native prepared statements will typically want to query the parameter
information, reconcile the type with that requested by the script,
allocate an appropriately sized buffer and then bind the parameter to
that buffer. You should not rely on the type or value of the zval at
<em>param->parameter</em> at this point in time.
</p>
</dd>
</dt>
<dt>
<span class="term">PDO_PARAM_EVT_FREE</span>
<dd>
<p class="para">Called once per parameter as part of cleanup. You should
release any resources associated with that parameter now.</p>
</dd>
</dt>
<dt>
<span class="term">PDO_PARAM_EXEC_PRE</span>
<dd>
<p class="para">Called once for each parameter immediately before calling
SKEL_stmt_execute; take this opportunity to make any final adjustments
ready for execution. In particular, you should note that variables
bound via <span class="function"><a href="pdostatement.bindparam.html" class="function">PDOStatement::bindParam()</a></span> are only legal
to touch now, and not any sooner.
</p>
</dd>
</dt>
<dt>
<span class="term">PDO_PARAM_EXEC_POST</span>
<dd>
<p class="para">Called once for each parameter immediately after calling
SKEL_stmt_execute; take this opportunity to make any post-execution
actions that might be required by your driver.</p>
</dd>
</dt>
<dt>
<span class="term">PDO_PARAM_FETCH_PRE</span>
<dd>
<p class="para">Called once for each parameter immediately prior to calling
SKEL_stmt_fetch.</p>
</dd>
</dt>
<dt>
<span class="term">PDO_PARAM_FETCH_POST</span>
<dd>
<p class="para">Called once for each parameter immediately after calling
SKEL_stmt_fetch.</p>
</dd>
</dt>
</dl>
</dd>
</dt>
</dl>
<p class="para">
This hook will be called for each bound parameter and bound column in the
statement. For ALLOC and FREE events, a single call will be made for each
parameter or column. The param structure contains a driver_data field that
the driver can use to store implementation specific information about each
of the parameters.
</p>
<p class="para">
For all other events, PDO may call you multiple times as the script issues
<span class="function"><a href="pdostatement.execute.html" class="function">PDOStatement::execute()</a></span> and
<span class="function"><a href="pdostatement.fetch.html" class="function">PDOStatement::fetch()</a></span> calls.
</p>
<p class="para">
If this is a bound parameter, the is_param flag in the param structure is
set, otherwise the param structure refers to a bound column.
</p>
<p class="para">
This function returns 1 for success or 0 in the event of failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.desc-col">
<h4 class="title">SKEL_stmt_describe_col</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_stmt_describe_col(pdo_stmt_t *stmt, int colno TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to query information about a particular
column.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
<dt>
<span class="term">colno</span>
<dd>
<p class="para">The column number to be queried.</p>
</dd>
</dt>
</dl>
<p class="para">
The driver should populate the pdo_stmt_t member columns(colno) with the
appropriate information. This function returns 1 for success or 0 in the
event of failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.get-col-data">
<h4 class="title">SKEL_stmt_get_col_data</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_stmt_get_col_data(pdo_stmt_t *stmt, int colno,
char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to retrieve data from the specified column.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
<dt>
<span class="term">colno</span>
<dd>
<p class="para">The column number to be queried.</p>
</dd>
</dt>
<dt>
<span class="term">ptr</span>
<dd>
<p class="para">Pointer to the retrieved data.</p>
</dd>
</dt>
<dt>
<span class="term">len</span>
<dd>
<p class="para">The length of the data pointed to by ptr.</p>
</dd>
</dt>
<dt>
<span class="term">caller_frees</span>
<dd>
<p class="para">If set, ptr should point to emalloc'd memory and the main PDO driver will free it as soon as it is done with it. Otherwise, it will be the responsibility of the driver to free any allocated memory as a result of this call.</p>
</dd>
</dt>
</dl>
<p class="para">
The driver should return the resultant data and length of that data in the
ptr and len variables respectively. It should be noted that the main PDO
driver expects the driver to manage the lifetime of the data. This function
returns 1 for success or 0 in the event of failure.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.set-attr">
<h4 class="title">SKEL_stmt_set_attr</h4>
<pre class="synopsis">static int SKEL_stmt_set_attr(pdo_stmt_t *stmt, long attr, zval *val TSRMLS_DC)</pre>
<p class="para">
This function will be called by PDO to allow the setting of driver specific
attributes for a statement object.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
<dt>
<span class="term">attr</span>
<dd>
<p class="para">
<span class="type"><span class="type long">long</span></span> value of one of the PDO_ATTR_xxxx types. See <a href="internals2.pdo.constants.html#internals2.pdo.table.attributes" class="xref">Database and Statement Attributes Table</a> for valid attributes.
</p>
</dd>
</dt>
<dt>
<span class="term">val</span>
<dd>
<p class="para">The new value for the attribute.</p>
</dd>
</dt>
</dl>
<p class="para">
This function is driver dependent and allows the driver the capability to
set database specific attributes for a statement. This function returns 1
for success or 0 in the event of failure. This is an optional function. If
the driver does not support additional settable attributes, it can be
NULLed in the method table. The PDO driver does not handle any settable
attributes on the database driver's behalf.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.get-attr">
<h4 class="title">SKEL_stmt_get_attr</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_stmt_get_attr(pdo_stmt_t *stmt, long attr, zval
*return_value TSRMLS_DC)</pre></div></pre>
<p class="para">
This function will be called by PDO to allow the retrieval of driver
specific attributes for a statement object.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
<dt>
<span class="term">attr</span>
<dd>
<p class="para">
<span class="type"><span class="type long">long</span></span> value of one of the PDO_ATTR_xxxx types. See <a href="internals2.pdo.constants.html#internals2.pdo.table.attributes" class="xref">Database and Statement Attributes Table</a> for valid attributes.
</p>
</dd>
</dt>
<dt>
<span class="term">return_value</span>
<dd>
<p class="para">The returned value for the attribute.</p>
</dd>
</dt>
</dl>
<p class="para">
This function is driver dependent and allows the driver the capability to
retrieve a previously set database specific attribute for a statement. This
function returns 1 for success or 0 in the event of failure. This is an
optional function. If the driver does not support additional gettable
attributes, it can be NULLed in the method table. The PDO driver does not
handle any settable attributes on the database driver's behalf.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.get-col-meta">
<h4 class="title">SKEL_stmt_get_col_meta</h4>
<pre class="synopsis"><div class="cdata"><pre>static int SKEL_stmt_get_col_meta(pdo_stmt_t *stmt, int colno,
zval *return_value TSRMLS_DC)</pre></div></pre>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
This function is not well defined and is subject to change.
</p>
</div>
<p class="para">
This function will be called by PDO to retrieve meta data from the
specified column.
</p>
<dl>
<dt>
<span class="term">stmt</span>
<dd>
<p class="para">Pointer to the statement structure initialized by SKEL_handle_preparer.</p>
</dd>
</dt>
<dt>
<span class="term">colno</span>
<dd>
<p class="para">The column number for which data is to be retrieved.</p>
</dd>
</dt>
<dt>
<span class="term">return_value</span>
<dd>
<p class="para">Holds the returned meta data.</p>
</dd>
</dt>
</dl>
<p class="para">
The driver author should consult the documentation for this function that can be
found in the php_pdo_driver.h header as this will be the most current. This
function returns 1 for success or 0 in the event of failure. The database
driver does not need to provide this function.
</p>
</div>
<div class="sect3" id="internals2.pdo.implementing.statement.method-table">
<h4 class="title">Statement handling method table</h4>
<p class="para">
A static structure of type pdo_stmt_methods named SKEL_stmt_methods should
be declared and initialized to the function pointers for each defined
function. If a function is not supported or not implemented the value for
that function pointer should be set to NULL.
</p>
</div>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="internals2.pdo.preparation.html">Preparation and Housekeeping</a></div>
<div class="next" style="text-align: right; float: right;"><a href="internals2.pdo.building.html">Building</a></div>
<div class="up"><a href="internals2.pdo.html">PDO Driver How-To</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
