cvs: phpdoc /en/internals/pdo index.xml
| From: | Wez Furlong | Date: | Sun, 18 Sep 2005 01:13:08 +0000 |
| Subject: | cvs: phpdoc /en/internals/pdo index.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969370163@lists.php.net to get a copy of this message | ||
wez Sat Sep 17 21:13:08 2005 EDT
Added files:
/phpdoc/en/internals/pdo index.xml
Log:
IBM has contributed an howto for creating PDO drivers.
They supplied the text to me as a word doc, and I've converted that to
Open Office and then used OOo2sDbk (http://www.chez.com/ebellot/ooo2sdbk/)
to arrive at what you see here.
This text is based on an older version of the driver API, and I will be
updating this in the near future.
I'd like to ask a phpdoc'er to volunteer to patch up the formatting to make
it acceptable for inclusion in the manual before I do this; I'm really short
on time right now, and I'm not up to speed with the latest phpdoc rules.
Feel free to split this document out into multiple files as you see fit.
Many thanks!
http://cvs.php.net/co.php/phpdoc/en/internals/pdo/index.xml?r=1.1&p=1 Index: phpdoc/en/internals/pdo/index.xml +++ phpdoc/en/internals/pdo/index.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <!-- Authors: Bill Abt and Rick McGuire of IBM Portions are thus Copyright 2005 IBM Corporation and are reproduced here with their permission to "edit, combine, transform, rewrite, etc. as suits the needs of the community". --> <chapter id="internals.pdo"> <title>PDO Driver How-To</title> <sect1> <para>Purpose</para> <para>The purpose of this How-To is to provide a basic understanding of the steps required to write a database driver that interfaces with the PDO driver. Please note that this is still an evolving API and as such, subject to change. This document was prepared based on version 0.3 of the PDO driver. The learning curve is steep; expect to spend a lot of time on the pre-requisites.</para> <para/> <para/> <para>Pre-requisites</para> <para>The following is list of pre-requisites and assumptions needed for writing a PDO database driver:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>A working target database, examples, demos, etc. working as per vendor specifications;</para> </listitem> <listitem> <para>A working development environment:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Other Unix: standard development tools supplied by vendor plus the GNU development tool set; </para> </listitem> <listitem> <para>Win32: Visual Studio compiler suite;</para> </listitem> <listitem> <para>Linux: standard development tools, gcc, ld, make, autoconf, automake, etc., versions dependent on distribution;</para> </listitem> </orderedlist> </listitem> <listitem> <para>A working PHP environment version 5.0.3 or higher with a working PEAR extension version 1.3.5 or higher;</para> </listitem> <listitem> <para>A working PDO driver environment (can be installed using 'sudo pear install PDO'), including the headers which will be needed to access the PDO type definitions and function declarations;</para> </listitem> <listitem> <para>A good working knowledge of the 'C' programming language;</para> </listitem> <listitem> <para>A good working knowledge of the way to write a PHP extension (I recommend <emphasis role="strong">Advanced PHP Programming</emphasis> by <emphasis>George Schlossnagle </emphasis>published by Developer's Library, chapters 21 and 22);</para> </listitem> <listitem> <para>Finally, a familiarity with the Zend API that forms the heart of PHP in particular paying attention to the memory management aspects.</para> </listitem> </orderedlist> <para/> <para>Preparation and Housekeeping</para> <para>Source directory layout</para> <para>The source directory for a PDO is laid out as follows:</para> <para>./PDO_<DB>-x.x</para> <para>config.m4</para> <para>config.w32</para> <para>CREDITS</para> <para>pdo_<db>.c</para> <para>php_pdo_<db>.h</para> <para>php_pdo_<db>_int.h</para> <para><db>_driver.c</para> <para><db>_statement.c</para> <para>where :</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para><DB> is a capitalized short name for the db this driver is for;</para> </listitem> <listitem> <para><db> is a lowercase short name for the db this driver is for and</para> </listitem> <listitem> <para>x.x is the version number of the driver.</para> </listitem> </orderedlist> <para>The purpose and contents of these files are defined later in this document.</para> <para/> <para>Creating a skeleton</para> <para>The easiest way to get started is to use the ext_skel shell script found in the PHP build tree in the 'ext' directory. This will build a skeleton directory containing a lot of the files listed above. It can be build by executing the following command from within the 'ext' directory:</para> <para>./ext_skel --extname=pdo_<db></para> <para>This will generate a directory called pdo_<db> containing the skeleton files that you can then modify. This directory should then be moved out of the php extension directory . PDO is a PECL extension and should not be included in the standard extension directory. As long as you have PHP and PDO installed, you should be able to build from any directory.</para> <para/> <para/> <para>Standard Includes</para> <para>Build Specific Headers</para> <para>The header file config.h is generated by the configure process for the platform for the which the driver is being built. If this header is present, the HAVE_CONFIG_H compiler variable is set. This variable should be tested for and if set, the file config.h should be included in the compilation unit.</para> <para/> <para>PHP Headers</para> <para>The following standard public php headers should be included in each source module:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>php.h</para> </listitem> <listitem> <para>php_ini.h</para> </listitem> <listitem> <para>ext/standard/info.h</para> </listitem> </orderedlist> <para>PDO Interface Headers</para> <para>The following standard public pdo header files are also included in each source module:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>pdo/php_pdo.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header file contains definitions of the initialization and shutdown functions in the main driver as well as definitions of global PDO variables..</para> </listitem> </orderedlist> </listitem> <listitem> <para>pdo/php_pdo_driver.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header contains the types and API contracts that are used to write a PDO driver. It also contains method signature for calling back into the main PDO driver and registering/unregistering your driver with the main PDO driver. Most importantly, this header file contains the type definitions for PDO database handles and statements. The two main structures a driver has to deal with, pdo_dbh_t and pdo_stmt_t, are described in more detail in Appendix A and B.</para> </listitem> </orderedlist> </listitem> </orderedlist> <para/> <para>Driver Specific Headers</para> <para>The typical pdo driver has two header files that are specific to the database implementation. This does not preclude the use of more depending on the implementation. The following two headers are, by convention, standard:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>php_pdo_<db>.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header file is virtually an exact duplicate in functionality and content of the previously defined pdo/php_pdo.h that has been specifically tailored for your database. If your driver requires the use of global variables they should be defined using the ZEND_BEGIN_MODULE_GLOBALS and ZEND_END_MODULE_GLOBALS macros. Macros are then used to access these variables. This macro is usually named PDO_<DB>_G(v) where v is global variable to be accessed. Consult the Zend programmer documentation for more information.</para> </listitem> </orderedlist> </listitem> <listitem> <para>php_pdo_<db>_int.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header file typically contains type definitions and function declarations specific to the driver implementation. It also should contain the db specicfic definitions of a pdo_<db>_handle and pdo_<db>_stmt structures. These are the names of the private data structures that are then referenced by the driver_data members of the handle and statement structures.</para> </listitem> </orderedlist> </listitem> </orderedlist> <para/> <para>Optional Headers</para> <para>Depending on the implementation details for a particular driver it may be necessary to include the following header:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>zend_exceptions.h</para> </listitem> </orderedlist> <para/> <para>Major Structures and Attributes</para> <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.</para> <para>Housekeeping unit -- pdo_<db>.c</para> <para>Entry functions</para> <para>A structure of type function_entry, called pdo_<db>_functions should be declared and initialized to all NULL.</para> <para/> <para>Module entry</para> <para>A structure of type zend_module_entry (typically called pdo_<db>_module_entry should be declared and should include reference to the pdo_<db>_functions table defined previously.</para> <para/> <para/> <para>Standard PHP Module Extension Functions</para> <para>PHP_MINIT_FUNCTION</para> <para>This standard PHP extension function should be used to register your driver with the PDO main driver. This is done by calling the php_pdo_register_driver function passing a pointer to a structure of type pdo_driver_t typically named pdo_<db>_driver. A pdo_driver_t contains a header that is generated using the PDO_DRIVER_HEADER(<db>) macro and pdo_<db>_handle_factory function pointer. The actual function is described during the discussion of the <db>_driver.c unit.</para> <para/> <para>PHP_MSHUTDOWN_FUNCTION</para> <para>This standard PHP extension function is used to unregister your driver with the main PDO driver. This is done by calling the php_pdo_unregister_driver function passing the same pdo_<db>_driver structure that was passed in the init function above.</para> <para/> <para>PHP_MINFO_FUNCTION</para> <para>This is again a standard PHP extension function. It's purpose is to display information regarding the module. You should include the version of the module and also what version of the db you are dependent on.</para> <para>Driver unit -- <db>_driver.c</para> <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.</para> <para/> <para>static int pdo_<db>_error(</para> <para>pdo_dbh_t *dbh, </para> <para>pdo_stmt_t *stmt, </para> <para>const char *file, </para> <para>int line </para> <para>TSRMLS_DC)</para> <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 dbh->error_code or stmt->error_code to an SQLSTATE that most closely matches the error or the generic SQLSTATE error “HY000”. The PDO driver file pdo_sqlstate.c 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 <emphasis role="strong">pdo_err</emphasis> variable to the error found in either the dbh or the stmt (if the variable stmt is not NULL).</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to the most current statement or NULL. If NULL, the error is derived by error code found in the dbh.</para> </entry> </row> <row> <entry valign="top"> <para>file</para> </entry> <entry valign="top"> <para>The source file where the error occurred or NULL if not available.</para> </entry> </row> <row> <entry valign="top"> <para>line</para> </entry> <entry valign="top"> <para>The line number within the source file if available.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>If the dbh member methods is NULL, 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.</para> <para><emphasis role="strong">Example macros</emphasis>:</para> <para>#define pdo_<db>_drv_error(what) pdo_<db>_error(dbh, NULL, what, __FILE__, __LINE__, TSRMLS_CC)</para> <para>#define pdo_<db>_drv_error(what) pdo_<db>_error(dbh, NULL, what, __FILE__, __LINE__, TSRMLS_CC)</para> <para/> <para>For more info on error handling, see Appendix C.</para> <para/> <para>static int pdo_<db>_fetch_error_func(</para> <para>pdo_dbh_t *dbh,</para> <para>pdo_stmt_t *stmt,</para> <para>zval *info</para> <para>TSRMLS_DC)</para> <para>The purpose of this function is to translate the database specific error code into an human readable string. </para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to the most current statement or NULL. If NULL, the error translated is derived by error code found in the dbh.</para> </entry> </row> <row> <entry valign="top"> <para>info</para> </entry> <entry valign="top"> <para>A hash table containing error codes and messages.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This function's sole purpose is retrieve the current error code and corresponding message and add it to the hash table pointed to by info.</para> <para/> <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</para> <para/> <para>// now add the error information. </para> <para>// These need to be added in a specific order</para> <para>add_next_index_long(info, error_code);</para> <para>add_next_index_string(info, message, 0);</para> <para/> <para>This function should return 1 if information is available, 0 if the driver does not have additional info. </para> <para/> <para>static int <db>_handle_closer(</para> <para> <emphasis role="strong"/> <emphasis role="strong">pdo_dbh_t *dbh</emphasis> </para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to close an open database.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This should do whatever database specific activity that needs to be accomplished to close the open database. The PDO driver ignores the return value from this function. </para> <para/> <para>static int <db>_handle_preparer(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *sql,</para> <para>long sql_len,</para> <para>pdo_stmt_t *stmt,</para> <para>zval *driver_options</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to convert raw SQL into a pdo_stmt_t which can then be executed.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>sql</para> </entry> <entry valign="top"> <para>Pointer to a character string containing the SQL statement to be prepared.</para> </entry> </row> <row> <entry valign="top"> <para>sql_len</para> </entry> <entry valign="top"> <para>The length of the SQL statement.</para> </entry> </row> <row> <entry valign="top"> <para>Stmt</para> </entry> <entry valign="top"> <para>Pointer to the returned statement or NULL if an error occurs.</para> </entry> </row> <row> <entry valign="top"> <para>driver_options</para> </entry> <entry valign="top"> <para>Any driver specific/defined options.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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 control block. </para> <para/> <para>The PDO driver does not process any statement options on the driver's behalf before calling the preparer function. </para> <para/> <para>One very important responsibility of this function is the processing of SQL statement parameters. At the time of this call, the PDO driver does not know how the driver supports positional parameters in the SQL statements. Depending on the placeholder option used, the statement string may need to reformatted into the form required by the database driver. The PDO driver implements a special function, pdo_parse_params(), which will reformat the statement string, if necessary, based on the setting of the supports_placeholders field. In particular, if a driver only supports PDO_PLACEHOLDER_NAMED or PDO_PLACEHOLDER_POSITIONAL, pdo_parse_params() should be used to obtain a correctly formatted statement string. This parsing process also will mapped named parameters into positional parameters for the driver. </para> <para/> <para>This function returns 1 on success or 0 on failure.</para> <para/> <para>static long <db>_handle_doer(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *sql,</para> <para>long sql_len</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to execute a raw SQL statement. No pdo_stmt_t is created.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>sql</para> </entry> <entry valign="top"> <para>Pointer to a character string containing the SQL statement to be prepared.</para> </entry> </row> <row> <entry valign="top"> <para>sql_len</para> </entry> <entry valign="top"> <para>The length of the SQL statement.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para>This function returns 1 on success or 0 on failure.</para> <para/> <para>static int <db>_handle_quoter(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *unquoted,</para> <para>int unquoted_len,</para> <para>char **quoted,</para> <para>int quoted_len,</para> <para>enum pdo_param_type param_type</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to turn a unquoted string into a quoted string for use in a query.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>unquoted</para> </entry> <entry valign="top"> <para>Pointer to a character string containing the string to be quoted.</para> </entry> </row> <row> <entry valign="top"> <para>unquoted_len</para> </entry> <entry valign="top"> <para>The length of the string to be quoted.</para> </entry> </row> <row> <entry valign="top"> <para>quoted</para> </entry> <entry valign="top"> <para>Pointer to the address where a pointer to the newly quoted string will be returned.</para> </entry> </row> <row> <entry valign="top"> <para>quoted_len</para> </entry> <entry valign="top"> <para>The length of the new string.</para> </entry> </row> <row> <entry valign="top"> <para>param_type</para> </entry> <entry valign="top"> <para>A driver specific hint for driver that have alternate quoting styles</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para>This function is only required if the supports_placeholder value is PDO_PLACEHOLDER_NONE. For database drivers without placeholder support, the PDO code will reformat statement with all parameters replaced by quoted strings directly containing the parameter values. The quoter() function is used to transform a string value into a quoted string appropriate for the driver. If the driver supports parameter placeholders, it is not necessary to implement this function. </para> <para/> <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. </para> <para>.</para> <para>static int <db>_handle_begin(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to begin a database transaction.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_handle_commit(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to end a database transaction.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This should do whatever database specific activity that needs to be accomplished to end a transaction. This function returns 1 for success or 0 if an error occurred.</para> <para/> <para>static int <db>_handle_rollback(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to rollback a database transaction.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_handle_get_attribute(</para> <para>pdo_dbh_t *dbh,</para> <para>long attr,</para> <para>zval *return_value</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve a database attribute.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>Long value of one of the PDO_ATTR_xxxx types.</para> <para>(see table below for valid attributes)</para> </entry> </row> <row> <entry valign="top"> <para>return_value</para> </entry> <entry valign="top"> <para>The returned value for the attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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. The PDO driver handles the PDO_ATTR_PERSISTENT, PDO_ATTR_CASE, PDO_ATTR_ORACLE_NULLS, and PDO_ATTR_ERRMODE attributes directly. </para> <para/> <para>This function returns 1 on success or 0 on failure.<emphasis role="strong"> </emphasis></para> <para/> <para>static int <db>_handle_set_attribute(</para> <para>pdo_dbh_t *dbh,</para> <para>long attr,</para> <para>zval *val</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to set a database attribute.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>Long value of one of the PDO_ATTR_xxxx types.</para> <para>(see table below for valid attributes)</para> </entry> </row> <row> <entry valign="top"> <para>val</para> </entry> <entry valign="top"> <para>The new value for the attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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. </para> <para/> <para>This function returns 1 on success or 0 on failure.<emphasis role="strong"> </emphasis></para> <para/> <para>static char * <db>_handle_last_id(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *name,</para> <para>unsigned int len</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve the ID of the last inserted row.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>name</para> </entry> <entry valign="top"> <para>Pointer to a character string representing the table name if required by the database.</para> </entry> </row> <row> <entry valign="top"> <para>len</para> </entry> <entry valign="top"> <para>The length of the SQL statement.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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. </para> <para/> <para>static int <db>_check_liveness(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to test whether or not a persistent connection to a database is alive and ready for use.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.<emphasis role="strong"> This is an optional function. </emphasis></para> <para/> <para>static function_entry <db>_get_driver_methods(</para> <para>pdo_dbh_t *dbh,</para> <para>int kind</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve a pointer to either the database or statement handling method table.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>kind</para> </entry> <entry valign="top"> <para>One of the following:</para> <para>PDO_DBH_DRIVER_METHOD_KIND_DBH</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Return a pointer to the database handling method table;</para> </listitem> </orderedlist> <para>PDO_DBH_DRIVER_METHOD_KIND_STMT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Return a pointer to the statement handling method table.</para> </listitem> </orderedlist> </entry> </row> </tbody> </tgroup> </informaltable> <para>This function returns a pointer to the method handling requested if successful or NULL if the method table cannot be found.<emphasis role="strong"> </emphasis></para> <para/> <para>static int <db>_handle_factory(</para> <para>pdo_dbh_t *dbh,</para> <para>zval *driver_options</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver 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.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>driver_options</para> </entry> <entry valign="top"> <para>DB specific options.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>The PDO driver processes the AUTOCOMMIT and PERSISTENT driver options before calling the handle_factory. It is the handle factory's responsibility to process other options. </para> <para/> <para/> <para>Driver method table</para> <para>A static structure of type pdo_dbh_methods named <db>_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.</para> <para/> <para/> <para>pdo_<db>_driver</para> <para>A structure of type pdo_driver_t named pdo_<db>_driver should be declared. The PDO_DRIVER_HEADER(<db>) macro should be used to declare the header and the function pointer to the handle factory function should set.</para> <para>Statement handling unit -- <db>_statement.c</para> <para>This unit implements all of the database statement handling methods that support the PDO statement object.</para> <para/> <para>static int <db>_stmt_dtor(</para> <para>pdo_stmt_t *stmt</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to destroy a previously constructed statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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. </para> <para/> <para>static int <db>_stmt_execute(</para> <para>pdo_stmt_t *stmt</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to execute the prepared SQL statement in the passed statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This function returns 1 for success or 0 in the event of failure.</para> <para/> <para>static int <db>_stmt_fetch(</para> <para>pdo_stmt_t *stmt,</para> <para>enum pdo_fetch_orientation ori,</para> <para>long offset</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to fetch a row from a previously executed statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>ori</para> </entry> <entry valign="top"> <para>One of PDO_FETCH_ORI_xxx which will determine which row will be fetched.</para> </entry> </row> <row> <entry valign="top"> <para>offset</para> </entry> <entry valign="top"> <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.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>The results of this fetch are driver dependent and the data is usually stored in the driver_data member of 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.</para> <para/> <para>static int <db>_stmt_param_hook(</para> <para>pdo_stmt_t *stmt,</para> <para>struct pdo_bound_param_data *param,</para> <para>enum pdo_param_event event_type</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver for handling of both bound parameters and bound columns. </para> <para/> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>param</para> </entry> <entry valign="top"> <para>The structure describing which statement variable will be bound to what variable name.</para> </entry> </row> <row> <entry valign="top"> <para>event_type</para> </entry> <entry valign="top"> <para>The type of event to occur for this parameter, one of the following:</para> <para>PDO_PARAM_EVT_ALLOC -- allocate the binding; Only called once, when the binding is created.</para> <para>PDO_PARAM_EVT_FREE -- free the allocated binding; Only called once as part of cleanup. </para> <para>PDO_PARAM_EXEC_PRE -- bind the variable before execution; </para> <para>PDO_PARAM_EXEC_POST -- bind the variable after execution;</para> <para>PDO_PARAM_FETCH_PRE -- bind the variable prior to the fetch;</para> <para>PDO_PARAM_FETCH_POST -- bind the variable after the fetch.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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. </para> <para/> <para>For all other events, the PDO driver will loop, calling the hook for each of the parameters and colums. </para> <para/> <para>If this is a bound parameter, the is_param flag in the param structure</para> <para/> <para>This function returns 1 for success or 0 in the event of failure.</para> <para/> <para>static int <db>_stmt_describe_col(</para> <para>pdo_stmt_t *stmt,</para> <para>int colno</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to query information about a particular column.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>colno</para> </entry> <entry valign="top"> <para>The column number to be queried.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_stmt_get_col_data(</para> <para>pdo_stmt_t *stmt,</para> <para>int colno,</para> <para>char **ptr,</para> <para>unsigned long *len,</para> <para>int *caller_frees</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve data from the specified column.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>colno</para> </entry> <entry valign="top"> <para>The column number for which data is to be retrieved.</para> </entry> </row> <row> <entry valign="top"> <para>ptr</para> </entry> <entry valign="top"> <para>Pointer to the retrieved data.</para> </entry> </row> <row> <entry valign="top"> <para>len</para> </entry> <entry valign="top"> <para>The length of the data pointed to by ptr.</para> </entry> </row> <row> <entry valign="top"> <para>caller_frees</para> </entry> <entry valign="top"> <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.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_stmt_set_attr(</para> <para>pdo_stmt_t *stmt,</para> <para>long attr,</para> <para>zval *val</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to allow the setting of driver specific attributes for a statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>The attribute to be set (DRIVER DEFINED AND SPECIFIC).</para> </entry> </row> <row> <entry valign="top"> <para>val</para> </entry> <entry valign="top"> <para>New value for the attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_stmt_get_attr(</para> <para>pdo_stmt_t *stmt,</para> <para>long attr,</para> <para>zval *val</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to allow the retrieval of driver specific attributes for a statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>The attribute to be retrieved, one of:</para> <para>PDO_ATTR_CURSOR</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>The type of cursor this statement refers to.</para> </listitem> </orderedlist> <para>PDO_ATTR_CURSOR_NAME</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>The name of the cursor this statement refers to.</para> </listitem> </orderedlist> <para>(Others are DRIVER DEFINED AND SPECIFIC).</para> </entry> </row> <row> <entry valign="top"> <para>val</para> </entry> <entry valign="top"> <para>Pointer to the retrieved attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>THE FOLLOWING FUNCTION IS A ROUGH FIRST CUT AND SUBJECT TO CHANGE.</para> <para>static int <db>_stmt_get_col_meta(</para> <para>pdo_stmt_t *stmt,</para> <para>int colno,</para> <para>zval *return_value</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve meta-data from the specified column.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>colno</para> </entry> <entry valign="top"> <para>The column number for which data is to be retrieved.</para> </entry> </row> <row> <entry valign="top"> <para>return_value</para> </entry> <entry valign="top"> <para>Pointer to the retrieved data.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>The driver 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.</para> <para/> <para>Statement handling method table</para> <para>A static structure of type pdo_stmt_methods named <db>_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.</para> <para>Building</para> <para>The build process is designed to work with PEAR (see <ulink url="http://pear.php.net/index.php" type="">http://pear.php.net/index.php</ulink> for more information about PEAR). There are two files that are used to assist in configuring your package for building. The first is config.m4 which is the autoconf configuration file for all platforms except Win32. The second is config.w32 which an autoconf configuration file for use on Win32. Skeleton files for these are built for you when you first set up your project. You then need to customize them to fit the needs of your project. Once you've customized your config files, you can build your driver using the following sequence of commands:</para> <para>Before first build:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>sudo pear install PDO</para> </listitem> </orderedlist> <para>For each build:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>cd pdo_<db></para> </listitem> <listitem> <para>phpize</para> </listitem> <listitem> <para>./configure</para> </listitem> <listitem> <para>make</para> </listitem> <listitem> <para>sudo make install</para> </listitem> </orderedlist> <para>The process can then be repeated as necessary during the development process.</para> <para/> <para/> <para>Package format</para> <para>PDO drivers are released in compress tar format. The following layout should be observed:</para> <para>./</para> <para>package.xml</para> <para>PDO_<DB>-xx.xx</para> <para>… driver build tree</para> <para>where DB is the capitalized short name for the database and xx.xx is the major and minor version numbers.</para> <para>Assuming the directory structure above you then create the release package with the following command:</para> <para>tar cfz pdo_<db>-xx.xx.tar.gz package.xml PDO_<DB>-xx.xx</para> <para>The resultant tar file is then ready for release. The contents of the package.xml file are described in the PEAR Programmer's documentation (<ulink url="http://pear.php.net/manual/index.php" type="">http://pear.php.net/manual/index.php</ulink>).</para> <para/> <para/> <para>Releasing</para> <para>A PDO driver is released using the PHP Extension Community Library (PECL) mechanism. Information about PECL and the coding standards currently in force can be found at <ulink url="http://pecl.php.net/index.php" type="">http://pecl.php.net/index.php</ulink>.</para> <para/> <para/> <para>Testing</para> <para>To be determined. The testing scheme for PDO is still being developed. </para> <para>Appendix A -- pdo_dbh_t</para> <informaltable> <tgroup cols="3"> <colspec colname="c1" colwidth="1.9inch"/> <colspec colname="c2" colwidth="2.3inch"/> <colspec colname="c3" colwidth="2inch"/> <tbody> <row> <entry valign="top"> <para>Variable name</para> </entry> <entry valign="top"> <para>Function</para> </entry> <entry valign="top"> <para>Responsibility</para> </entry> </row> <row> <entry valign="top"> <para>ce</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>properties</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_get</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_set</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>methods</para> </entry> <entry valign="top"> <para>Pointer to the methods function pointer for db handling.</para> </entry> <entry valign="top"> <para>Driver must set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>driver_data</para> </entry> <entry valign="top"> <para>Opaque pointer containing driver specific data.</para> </entry> <entry valign="top"> <para>Driver can store driver specific data and structures for database handling. This field should be allocated and set during handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>username</para> </entry> <entry valign="top"> <para>Database user on behalf access is to be granted.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>password</para> </entry> <entry valign="top"> <para>Password for the database user.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>is_persistent</para> </entry> <entry valign="top"> <para>If true, data stored and pointed to by this handle must be persistently allocated.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>auto_commit</para> </entry> <entry valign="top"> <para>If true, the driver should ensure that a COMMIT is processed at the end of each executed statement. Otherwise, COMMIT will only be done at user request.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>is_closed</para> </entry> <entry valign="top"> <para>If true, this handle is closed and is no longer valid for operations.</para> </entry> <entry valign="top"> <para>This field is NOT initialized and does NOT appear to be used at present.</para> </entry> </row> <row> <entry valign="top"> <para>alloc_own_columns</para> </entry> <entry valign="top"> <para>If true, the driver requires that memory be explicitly allocated for all columns returned. Setting this will cause the PDO driver to call the stmt describer() function after the first statement execute and before the first fetch. </para> </entry> <entry valign="top"> <para>Driver should set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>in_txn</para> </entry> <entry valign="top"> <para>If true, a COMMIT or ROLLBACK is allowed to be called. A transaction is in progress.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. </para> </entry> </row> <row> <entry valign="top"> <para>max_escaped_char_length</para> </entry> <entry valign="top"> <para>This is the maximum length a single character can become after correct quoting. This is only needed if supports_placeholders is PDO_PLACEHOLDER_NONE.</para> </entry> <entry valign="top"> <para>Driver should set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>oracle_nulls</para> </entry> <entry valign="top"> <para>If true, convert all empty strings to NULL.</para> </entry> <entry valign="top"> <para>Driver should set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>_reserved_flags</para> </entry> <entry valign="top"> <para>Reserved for PDO main driver.</para> </entry> <entry valign="top"> <para>These are reserved for future use by the main PDO driver.</para> </entry> </row> <row> <entry valign="top"> <para>data_source</para> </entry> <entry valign="top"> <para>A string representing the data source used to open this handle.</para> </entry> <entry valign="top"> <para>This field is initially set by the main PDO driver. It can be modified, if necessary, by the driver. For example, a driver may need to pre-pend a directory path to filename passed or may need to add a qualifier as required by a particular database implementation.</para> </entry> </row> <row> <entry valign="top"> <para>data_source_len</para> </entry> <entry valign="top"> <para>The length of the string in the data_source field.</para> </entry> <entry valign="top"> <para>This field is initially set by the PDO main driver. If a driver modifies the data_source field such that the length changes, this field can be modified by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>error_code</para> </entry> <entry valign="top"> <para>This is the latest error code. It is the SQLSTATE expressed as 6 character ASCIIZ field. </para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. Drivers should set the global variable pdo_err whenever an error occurs and the driver will set this field when appropriate. </para> </entry> </row> <row> <entry valign="top"> <para>error_mode</para> </entry> <entry valign="top"> <para>This field contains the mode in which PDO reports errors. This field is set to one of the following:</para> <para>PDO_ERRMODE_SILENT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Fail silently</para> </listitem> </orderedlist> <para>PDO_ERRMODE_WARNING</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Treat all errors as warnings.</para> </listitem> </orderedlist> <para>PDO_ERRMODE_EXCEPTION</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Throw exceptions instead of returning error codes.</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is initially set to PDO_ERR_MODE_SILENT by the PDO main driver. It can be subsequently modified by the driver via a call to change the attribute.</para> </entry> </row> <row> <entry valign="top"> <para>native_case</para> </entry> <entry valign="top"> <para>This is set to native case for the database being accessed. It can be one of:</para> <para>PDO_CASE_NATURAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Mixed case</para> </listitem> </orderedlist> <para>PDO_CASE_UPPER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>All upper case</para> </listitem> </orderedlist> <para>PDO_CASE_LOWER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>All lower case</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is set during the handle factory method by the driver to appropriate value. The default value is PDO_CASE_NATURAL.</para> </entry> </row> <row> <entry valign="top"> <para>desired_case</para> </entry> <entry valign="top"> <para>This is set to the case conversion requested by the caller. It can be one of the following:</para> <para>PDO_CASE_NATURAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Don't do case conversion</para> </listitem> </orderedlist> <para>PDO_CASE_UPPER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to uppercase</para> </listitem> </orderedlist> <para>PDO_CASE_LOWER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to lowercase</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is set during the handle factory by the driver based on options passed and can be subsequently modified with a call to change the attribute. The default value for this field is PDO_CASE_NATURAL.</para> </entry> </row> <row> <entry valign="top"> <para>persistent_id</para> </entry> <entry valign="top"> <para>This a hash key that is associated with the handle this structure represents.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>persistent_id_len</para> </entry> <entry valign="top"> <para>This is the length of the hash key represented by the persistent_id field.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>refcount</para> </entry> <entry valign="top"> <para>This field contains the count of how many times this handle is currently referenced. If a handle is persistent, this field is increased when a persistent object is created. It is decremented each time the destructor is called. When the count reaches zero, the handle can be safely destructed.</para> </entry> <entry valign="top"> <para>This field is set initially by the main PDO driver to one when the handle is constructed. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>cls_methods</para> </entry> <entry valign="top"> <para>This field is an array of hashtables containing (at present) driver methods for database handling and statement handling.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para/> <para>Appendix B -- pdo_stmt_t</para> <informaltable> <tgroup cols="3"> <colspec colname="c1" colwidth="1.9inch"/> <colspec colname="c2" colwidth="3inch"/> <colspec colname="c3" colwidth="1.9inch"/> <tbody> <row> <entry valign="top"> <para>Variable name</para> </entry> <entry valign="top"> <para>Function</para> </entry> <entry valign="top"> <para>Responsibility</para> </entry> </row> <row> <entry valign="top"> <para>ce</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>properties</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_get</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_set</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>methods</para> </entry> <entry valign="top"> <para>Pointer to the methods function pointer for SQL statement handling.</para> </entry> <entry valign="top"> <para>Driver should set this during the call to <db>_handle_preparer function.</para> </entry> </row> <row> <entry valign="top"> <para>driver_data</para> </entry> <entry valign="top"> <para>Opaque pointer containing driver specific data.</para> </entry> <entry valign="top"> <para>Driver can store driver specific data and structures for database handling. This field is typically allocated and set during the call to <db>_handle_preparer.</para> </entry> </row> <row> <entry valign="top"> <para>executed</para> </entry> <entry valign="top"> <para>If true, the statement represented by this object has been executed at least once, otherwise, it's never been executed. This is set automatically after the first call to the stmt executor() function.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>supports_placeholders</para> </entry> <entry valign="top"> <para>This field determines whether the driver support placeholders. It can be any one or combination of the following values:</para> <para>PDO_PLACEHOLDER_NONE</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Driver has no placeholder support</para> </listitem> </orderedlist> <para>PDO_PLACEHOLDER_NAMED</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Driver supports named placeholders</para> </listitem> </orderedlist> <para>PDO_PLACEHOLDER_POSITIONAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Driver supports positional placeholders</para> </listitem> </orderedlist> <para>If both named and positional are supported the field should be set to the OR'd value the two values.</para> </entry> <entry valign="top"> <para>The driver should set this field to the appropriate value during the call to <db>_handler_preparer.</para> </entry> </row> <row> <entry valign="top"> <para>_reserved</para> </entry> <entry valign="top"> <para>Reserved for PDO main driver.</para> </entry> <entry valign="top"> <para>These are reserved for future use by the main PDO driver.</para> </entry> </row> <row> <entry valign="top"> <para>column_count</para> </entry> <entry valign="top"> <para>This field contains the number of columns in the result set. The contents of this field is not valid until the “executed” field is set to true and the statement has been executed. There may be cases (driver specific) where this value is not valid until the drivers fetch method has been called at least once.</para> </entry> <entry valign="top"> <para>This field is maintained by the driver. It is normally set during <db>_stmt_execute but can be reset in <db_stmt_next_rowset as well. </para> </entry> </row> <row> <entry valign="top"> <para>columns</para> </entry> <entry valign="top"> <para>This is a pointer to the column description data. It contains column_count number of elements. A column is represented by the pdo_column_data structure. This structure contains the following members:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>name -- the name of the column</para> </listitem> <listitem> <para>namelen -- the length of name</para> </listitem> <listitem> <para>maxlen -- the maximum length of the data this column can handle</para> </listitem> <listitem> <para>param_type -- the type of data this column contains</para> </listitem> <listitem> <para>precision -- if numeric data, the precision of data contained.</para> </listitem> </orderedlist> </entry> <entry valign="top"> <para>This field is allocated and freed by the PDO main driver. However, the driver is responsible for populating the contents during the call to <db>_stmt_describe.</para> </entry> </row> <row> <entry valign="top"> <para>database_object_handle</para> </entry> <entry valign="top"> <para>This is the Zend object representation of the database handle. This field is kept so that a reference to the database handle object is always referenced while as statement object exists.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>This is a pointer to pdo_dbh_t representation of the database handle. It is valid so long as the database_object_handle is valid.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>bound_params</para> </entry> <entry valign="top"> <para>This is a hashtable of bound input parameters. This is kept because not all drivers support both input and out parameters.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>bound_param_map</para> </entry> <entry valign="top"> <para>This hashtable contains a mapping of positions to names when rewriting from named to positional.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>bound_columns</para> </entry> <entry valign="top"> <para>This hashtable is used to keep track of PHP variables that are bound to named or positional columns in the result set.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>row_count</para> </entry> <entry valign="top"> <para>This field represents the count of rows available in the result set.</para> </entry> <entry valign="top"> <para>This field is initialized to zero by the PDO main driver and CAN be set by the driver during the <db>_handle_doer method call. Note: not all drivers have this information available at this time so the reliability of this field is driver specific.</para> </entry> </row> <row> <entry valign="top"> <para>query_string</para> </entry> <entry valign="top"> <para>This character string holds the current raw SQL query associated with this statement.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>query_stringlen</para> </entry> <entry valign="top"> <para>This field represents the length of the raw SQL query string.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>error_code</para> </entry> <entry valign="top"> <para>This is the latest error code for this statement. It is the SQLSTATE expressed as 6 character field.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. Drivers should set the global variable pdo_err whenever an error occurs and the driver will set this field when appropriate. </para> </entry> </row> <row> <entry valign="top"> <para>lazy_object_ref</para> </entry> <entry valign="top"> <para>This field is used to store the lazy object handle (fetch type is equal to PDO_FETCH_LAZY) that is returned for each lazy fetch.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers.</para> </entry> </row> <row> <entry valign="top"> <para>refcount</para> </entry> <entry valign="top"> <para>This is count of how many lazy fetches have been done.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers.</para> </entry> </row> <row> <entry valign="top"> <para>default_fetch_type</para> </entry> <entry valign="top"> <para>This is the default fetch type. It can be any one of the following:</para> <para>PDO_FETCH_USE_DEFAULT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Use the default fetch mode</para> </listitem> </orderedlist> <para>PDO_FETCH_LAZY</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an object with variable names that correspond to the column names returned in the result set. PDO_FETCH_LAZY creates the object variable names as they are accessed.</para> </listitem> </orderedlist> <para>PDO_FETCH_ASSOC</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an array indexed by column name as returned in the corresponding result set.</para> </listitem> </orderedlist> <para>PDO_FETCH_NUM</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an array indexed by column number as returned in the corresponding result set, starting at column 0.</para> </listitem> </orderedlist> <para>PDO_FETCH_BOTH</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an array indexed by both column name and number as returned in the corresponding result set, starting at column 0.</para> </listitem> </orderedlist> <para>PDO_FETCH_OBJ</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an object with property names that correspond to the column names returned in the result set.</para> </listitem> </orderedlist> <para>PDO_FETCH_BOUND</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return TRUE and assign the values of the columns in the result set to the variables to which they were bound.</para> </listitem> </orderedlist> <para>PDO_FETCH_COLUMN</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return only a single requested column from the next row in the result set.</para> </listitem> </orderedlist> <para>PDO_FETCH_CLASS</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return a new instance of the requested class, mapping the columns to named properties in the class.</para> </listitem> </orderedlist> <para>PDO_FETCH_INTO</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall update an existing instance of the requested class, mapping the columns to named properties in the class.</para> </listitem> </orderedlist> <para>PDO_FETCH_FUNC</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Fetch into function and return result of function.</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers. The default value for this field is PDO_FETCH_BOTH.</para> </entry> </row> <row> <entry valign="top"> <para>fetch</para> </entry> <entry valign="top"> <para>This union is used to contain fetch information used by the PDO main driver.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para/> <para>Appendix C - Database and Statement Attributes Table</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="3inch"/> <colspec colname="c2" colwidth="2.7inch"/> <tbody> <row> <entry valign="top"> <para>Attribute</para> </entry> <entry valign="top"> <para>Valid value(s)</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_AUTOCOMMIT</para> </entry> <entry valign="top"> <para>ZVAL_BOOL</para> <para>TRUE if autocommit is set, FALSE otherwise. </para> <para>Dbh->auto_commit contains value. Processed by the PDO driver directly.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_PREFETCH</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>Value of the prefetch size in drivers that support it.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_TIMEOUT</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>How long to wait for a db operation before timing out.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_ERRMODE</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>PDO_ERRMODE_SILENT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Fail silently</para> </listitem> </orderedlist> <para>PDO_ERRMODE_WARNING</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Treat all errors as warnings.</para> </listitem> </orderedlist> <para>PDO_ERRMODE_EXCEPTION</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Throw exceptions instead of returning error codes.</para> </listitem> </orderedlist> <para/> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_SERVER_VERSION</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>The “human-readable” string representing the Server/Version this driver supports.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CLIENT_VERSION</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>The “human-readable” string representing the Client/Version this driver supports.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_SERVER_INFO</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>The “human-readable” description of the Server.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CONNECTION_STATUS</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>Values not yet defined</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CASE</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>PDO_CASE_NATURAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Don't do case conversion</para> </listitem> </orderedlist> <para>PDO_CASE_UPPER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to uppercase</para> </listitem> </orderedlist> <para>PDO_CASE_LOWER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to lowercase</para> </listitem> <listitem> <para/> </listitem> </orderedlist> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CURSOR_NAME</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>String representing the name for a database cursor for use in “where current in <name>” SQL statements</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CURSOR</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>PDO_CURSOR_FWDONLY</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Forward only cursor</para> </listitem> </orderedlist> <para>PDO_CURSOR_SCROLL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Scrollable cursor</para> </listitem> </orderedlist> <para/> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_ORACLE_NULLS</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>(For Oracle Driver)</para> <para>dbh->oracle_nulls is set the result of Z_LVAL_P(value) ? 1 : 0</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_PERSISTENT</para> </entry> <entry valign="top"> <para>ZVAL_BOOL</para> <para>True if persistent connection, false if not. Processed directly by the PDO driver. </para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_STATEMENT_CLASS</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>Values not yet defined.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para>The values for the attributes above are all defined in terms of the Zend API. The Zend API contains macros that can be used to convert a *zval to a value. These macros are defined in the Zend header file, zend_API.h in the Zend directory of your PHP build directory. Some of these attributes can be used with the statement attribute handlers such as the PDO_ATTR_CURSOR and PDO_ATTR_CURSOR_NAME. See the statement attribute handling functions for more information.</para> <para/> <para>Appendix D -- Error handling</para> <para/> <para>Error handling is implemented using a hand-shaking protocol between the main PDO driver and the database driver code. The database driver code signals the PDO driver than an error has occurred via a failure (“0”) return from any of the interface functions. If a zero is returned, the field error_code in the control block appropriate to the context (either the pdo_dbh_t or pdo_stmt_t block). In practice, it is probably a good idea to set the field in both blocks to the same value to ensure the correct one is getting used. </para> <para/> <para>The error_mode field is a six-field field containing a 5 character ASCIIZ SQLSTATE identifier code. This code drives the error message process. The SQLSTATE code is used to look up an error message in the internal PDO error message table (see pdo_sqlstate.c for a list of error codes and their messages). If the code is not known to the PDO driver, a default “Unknown Message” value will be used. </para> <para/> <para>In addition to the SQLSTATE code and error message, the PDO driver will call the driver-specific fetch-err() routine to obtain supplemental data for the particular error condition. This routine is passed an array into which the driver may place additional information. This array has slot positions assigned to particular types of supplemental info:</para> <para/> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>A native error code. This will frequently be an error code obtained from the database API. </para> </listitem> <listitem> <para>A descriptive string. This string can contain anything additional information related to the failure. Database drivers typically include information such as an error message, code location of the failure, and any additional descriptive information the driver developer feels worthy of inclusion. It is generally a good idea to include all diagnostic information<emphasis role="strong"> </emphasis>obtainable from the database interface at the time of the failure. For driver-detected errors (such as memory allocation problems), the driver developer can define whatever error information that seems appropriate.</para> </listitem> </orderedlist> <para/> <para/> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
http://cvs.php.net/co.php/phpdoc/en/internals/pdo/index.xml?r=1.1&p=1 Index: phpdoc/en/internals/pdo/index.xml +++ phpdoc/en/internals/pdo/index.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <!-- Authors: Bill Abt and Rick McGuire of IBM Portions are thus Copyright 2005 IBM Corporation and are reproduced here with their permission to "edit, combine, transform, rewrite, etc. as suits the needs of the community". --> <chapter id="internals.pdo"> <title>PDO Driver How-To</title> <sect1> <para>Purpose</para> <para>The purpose of this How-To is to provide a basic understanding of the steps required to write a database driver that interfaces with the PDO driver. Please note that this is still an evolving API and as such, subject to change. This document was prepared based on version 0.3 of the PDO driver. The learning curve is steep; expect to spend a lot of time on the pre-requisites.</para> <para/> <para/> <para>Pre-requisites</para> <para>The following is list of pre-requisites and assumptions needed for writing a PDO database driver:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>A working target database, examples, demos, etc. working as per vendor specifications;</para> </listitem> <listitem> <para>A working development environment:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Other Unix: standard development tools supplied by vendor plus the GNU development tool set; </para> </listitem> <listitem> <para>Win32: Visual Studio compiler suite;</para> </listitem> <listitem> <para>Linux: standard development tools, gcc, ld, make, autoconf, automake, etc., versions dependent on distribution;</para> </listitem> </orderedlist> </listitem> <listitem> <para>A working PHP environment version 5.0.3 or higher with a working PEAR extension version 1.3.5 or higher;</para> </listitem> <listitem> <para>A working PDO driver environment (can be installed using 'sudo pear install PDO'), including the headers which will be needed to access the PDO type definitions and function declarations;</para> </listitem> <listitem> <para>A good working knowledge of the 'C' programming language;</para> </listitem> <listitem> <para>A good working knowledge of the way to write a PHP extension (I recommend <emphasis role="strong">Advanced PHP Programming</emphasis> by <emphasis>George Schlossnagle </emphasis>published by Developer's Library, chapters 21 and 22);</para> </listitem> <listitem> <para>Finally, a familiarity with the Zend API that forms the heart of PHP in particular paying attention to the memory management aspects.</para> </listitem> </orderedlist> <para/> <para>Preparation and Housekeeping</para> <para>Source directory layout</para> <para>The source directory for a PDO is laid out as follows:</para> <para>./PDO_<DB>-x.x</para> <para>config.m4</para> <para>config.w32</para> <para>CREDITS</para> <para>pdo_<db>.c</para> <para>php_pdo_<db>.h</para> <para>php_pdo_<db>_int.h</para> <para><db>_driver.c</para> <para><db>_statement.c</para> <para>where :</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para><DB> is a capitalized short name for the db this driver is for;</para> </listitem> <listitem> <para><db> is a lowercase short name for the db this driver is for and</para> </listitem> <listitem> <para>x.x is the version number of the driver.</para> </listitem> </orderedlist> <para>The purpose and contents of these files are defined later in this document.</para> <para/> <para>Creating a skeleton</para> <para>The easiest way to get started is to use the ext_skel shell script found in the PHP build tree in the 'ext' directory. This will build a skeleton directory containing a lot of the files listed above. It can be build by executing the following command from within the 'ext' directory:</para> <para>./ext_skel --extname=pdo_<db></para> <para>This will generate a directory called pdo_<db> containing the skeleton files that you can then modify. This directory should then be moved out of the php extension directory . PDO is a PECL extension and should not be included in the standard extension directory. As long as you have PHP and PDO installed, you should be able to build from any directory.</para> <para/> <para/> <para>Standard Includes</para> <para>Build Specific Headers</para> <para>The header file config.h is generated by the configure process for the platform for the which the driver is being built. If this header is present, the HAVE_CONFIG_H compiler variable is set. This variable should be tested for and if set, the file config.h should be included in the compilation unit.</para> <para/> <para>PHP Headers</para> <para>The following standard public php headers should be included in each source module:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>php.h</para> </listitem> <listitem> <para>php_ini.h</para> </listitem> <listitem> <para>ext/standard/info.h</para> </listitem> </orderedlist> <para>PDO Interface Headers</para> <para>The following standard public pdo header files are also included in each source module:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>pdo/php_pdo.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header file contains definitions of the initialization and shutdown functions in the main driver as well as definitions of global PDO variables..</para> </listitem> </orderedlist> </listitem> <listitem> <para>pdo/php_pdo_driver.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header contains the types and API contracts that are used to write a PDO driver. It also contains method signature for calling back into the main PDO driver and registering/unregistering your driver with the main PDO driver. Most importantly, this header file contains the type definitions for PDO database handles and statements. The two main structures a driver has to deal with, pdo_dbh_t and pdo_stmt_t, are described in more detail in Appendix A and B.</para> </listitem> </orderedlist> </listitem> </orderedlist> <para/> <para>Driver Specific Headers</para> <para>The typical pdo driver has two header files that are specific to the database implementation. This does not preclude the use of more depending on the implementation. The following two headers are, by convention, standard:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>php_pdo_<db>.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header file is virtually an exact duplicate in functionality and content of the previously defined pdo/php_pdo.h that has been specifically tailored for your database. If your driver requires the use of global variables they should be defined using the ZEND_BEGIN_MODULE_GLOBALS and ZEND_END_MODULE_GLOBALS macros. Macros are then used to access these variables. This macro is usually named PDO_<DB>_G(v) where v is global variable to be accessed. Consult the Zend programmer documentation for more information.</para> </listitem> </orderedlist> </listitem> <listitem> <para>php_pdo_<db>_int.h</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>This header file typically contains type definitions and function declarations specific to the driver implementation. It also should contain the db specicfic definitions of a pdo_<db>_handle and pdo_<db>_stmt structures. These are the names of the private data structures that are then referenced by the driver_data members of the handle and statement structures.</para> </listitem> </orderedlist> </listitem> </orderedlist> <para/> <para>Optional Headers</para> <para>Depending on the implementation details for a particular driver it may be necessary to include the following header:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>zend_exceptions.h</para> </listitem> </orderedlist> <para/> <para>Major Structures and Attributes</para> <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.</para> <para>Housekeeping unit -- pdo_<db>.c</para> <para>Entry functions</para> <para>A structure of type function_entry, called pdo_<db>_functions should be declared and initialized to all NULL.</para> <para/> <para>Module entry</para> <para>A structure of type zend_module_entry (typically called pdo_<db>_module_entry should be declared and should include reference to the pdo_<db>_functions table defined previously.</para> <para/> <para/> <para>Standard PHP Module Extension Functions</para> <para>PHP_MINIT_FUNCTION</para> <para>This standard PHP extension function should be used to register your driver with the PDO main driver. This is done by calling the php_pdo_register_driver function passing a pointer to a structure of type pdo_driver_t typically named pdo_<db>_driver. A pdo_driver_t contains a header that is generated using the PDO_DRIVER_HEADER(<db>) macro and pdo_<db>_handle_factory function pointer. The actual function is described during the discussion of the <db>_driver.c unit.</para> <para/> <para>PHP_MSHUTDOWN_FUNCTION</para> <para>This standard PHP extension function is used to unregister your driver with the main PDO driver. This is done by calling the php_pdo_unregister_driver function passing the same pdo_<db>_driver structure that was passed in the init function above.</para> <para/> <para>PHP_MINFO_FUNCTION</para> <para>This is again a standard PHP extension function. It's purpose is to display information regarding the module. You should include the version of the module and also what version of the db you are dependent on.</para> <para>Driver unit -- <db>_driver.c</para> <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.</para> <para/> <para>static int pdo_<db>_error(</para> <para>pdo_dbh_t *dbh, </para> <para>pdo_stmt_t *stmt, </para> <para>const char *file, </para> <para>int line </para> <para>TSRMLS_DC)</para> <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 dbh->error_code or stmt->error_code to an SQLSTATE that most closely matches the error or the generic SQLSTATE error “HY000”. The PDO driver file pdo_sqlstate.c 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 <emphasis role="strong">pdo_err</emphasis> variable to the error found in either the dbh or the stmt (if the variable stmt is not NULL).</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to the most current statement or NULL. If NULL, the error is derived by error code found in the dbh.</para> </entry> </row> <row> <entry valign="top"> <para>file</para> </entry> <entry valign="top"> <para>The source file where the error occurred or NULL if not available.</para> </entry> </row> <row> <entry valign="top"> <para>line</para> </entry> <entry valign="top"> <para>The line number within the source file if available.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>If the dbh member methods is NULL, 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.</para> <para><emphasis role="strong">Example macros</emphasis>:</para> <para>#define pdo_<db>_drv_error(what) pdo_<db>_error(dbh, NULL, what, __FILE__, __LINE__, TSRMLS_CC)</para> <para>#define pdo_<db>_drv_error(what) pdo_<db>_error(dbh, NULL, what, __FILE__, __LINE__, TSRMLS_CC)</para> <para/> <para>For more info on error handling, see Appendix C.</para> <para/> <para>static int pdo_<db>_fetch_error_func(</para> <para>pdo_dbh_t *dbh,</para> <para>pdo_stmt_t *stmt,</para> <para>zval *info</para> <para>TSRMLS_DC)</para> <para>The purpose of this function is to translate the database specific error code into an human readable string. </para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to the most current statement or NULL. If NULL, the error translated is derived by error code found in the dbh.</para> </entry> </row> <row> <entry valign="top"> <para>info</para> </entry> <entry valign="top"> <para>A hash table containing error codes and messages.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This function's sole purpose is retrieve the current error code and corresponding message and add it to the hash table pointed to by info.</para> <para/> <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</para> <para/> <para>// now add the error information. </para> <para>// These need to be added in a specific order</para> <para>add_next_index_long(info, error_code);</para> <para>add_next_index_string(info, message, 0);</para> <para/> <para>This function should return 1 if information is available, 0 if the driver does not have additional info. </para> <para/> <para>static int <db>_handle_closer(</para> <para> <emphasis role="strong"/> <emphasis role="strong">pdo_dbh_t *dbh</emphasis> </para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to close an open database.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This should do whatever database specific activity that needs to be accomplished to close the open database. The PDO driver ignores the return value from this function. </para> <para/> <para>static int <db>_handle_preparer(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *sql,</para> <para>long sql_len,</para> <para>pdo_stmt_t *stmt,</para> <para>zval *driver_options</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to convert raw SQL into a pdo_stmt_t which can then be executed.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>sql</para> </entry> <entry valign="top"> <para>Pointer to a character string containing the SQL statement to be prepared.</para> </entry> </row> <row> <entry valign="top"> <para>sql_len</para> </entry> <entry valign="top"> <para>The length of the SQL statement.</para> </entry> </row> <row> <entry valign="top"> <para>Stmt</para> </entry> <entry valign="top"> <para>Pointer to the returned statement or NULL if an error occurs.</para> </entry> </row> <row> <entry valign="top"> <para>driver_options</para> </entry> <entry valign="top"> <para>Any driver specific/defined options.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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 control block. </para> <para/> <para>The PDO driver does not process any statement options on the driver's behalf before calling the preparer function. </para> <para/> <para>One very important responsibility of this function is the processing of SQL statement parameters. At the time of this call, the PDO driver does not know how the driver supports positional parameters in the SQL statements. Depending on the placeholder option used, the statement string may need to reformatted into the form required by the database driver. The PDO driver implements a special function, pdo_parse_params(), which will reformat the statement string, if necessary, based on the setting of the supports_placeholders field. In particular, if a driver only supports PDO_PLACEHOLDER_NAMED or PDO_PLACEHOLDER_POSITIONAL, pdo_parse_params() should be used to obtain a correctly formatted statement string. This parsing process also will mapped named parameters into positional parameters for the driver. </para> <para/> <para>This function returns 1 on success or 0 on failure.</para> <para/> <para>static long <db>_handle_doer(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *sql,</para> <para>long sql_len</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to execute a raw SQL statement. No pdo_stmt_t is created.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>sql</para> </entry> <entry valign="top"> <para>Pointer to a character string containing the SQL statement to be prepared.</para> </entry> </row> <row> <entry valign="top"> <para>sql_len</para> </entry> <entry valign="top"> <para>The length of the SQL statement.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para>This function returns 1 on success or 0 on failure.</para> <para/> <para>static int <db>_handle_quoter(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *unquoted,</para> <para>int unquoted_len,</para> <para>char **quoted,</para> <para>int quoted_len,</para> <para>enum pdo_param_type param_type</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to turn a unquoted string into a quoted string for use in a query.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>unquoted</para> </entry> <entry valign="top"> <para>Pointer to a character string containing the string to be quoted.</para> </entry> </row> <row> <entry valign="top"> <para>unquoted_len</para> </entry> <entry valign="top"> <para>The length of the string to be quoted.</para> </entry> </row> <row> <entry valign="top"> <para>quoted</para> </entry> <entry valign="top"> <para>Pointer to the address where a pointer to the newly quoted string will be returned.</para> </entry> </row> <row> <entry valign="top"> <para>quoted_len</para> </entry> <entry valign="top"> <para>The length of the new string.</para> </entry> </row> <row> <entry valign="top"> <para>param_type</para> </entry> <entry valign="top"> <para>A driver specific hint for driver that have alternate quoting styles</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para>This function is only required if the supports_placeholder value is PDO_PLACEHOLDER_NONE. For database drivers without placeholder support, the PDO code will reformat statement with all parameters replaced by quoted strings directly containing the parameter values. The quoter() function is used to transform a string value into a quoted string appropriate for the driver. If the driver supports parameter placeholders, it is not necessary to implement this function. </para> <para/> <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. </para> <para>.</para> <para>static int <db>_handle_begin(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to begin a database transaction.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_handle_commit(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to end a database transaction.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This should do whatever database specific activity that needs to be accomplished to end a transaction. This function returns 1 for success or 0 if an error occurred.</para> <para/> <para>static int <db>_handle_rollback(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to rollback a database transaction.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_handle_get_attribute(</para> <para>pdo_dbh_t *dbh,</para> <para>long attr,</para> <para>zval *return_value</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve a database attribute.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>Long value of one of the PDO_ATTR_xxxx types.</para> <para>(see table below for valid attributes)</para> </entry> </row> <row> <entry valign="top"> <para>return_value</para> </entry> <entry valign="top"> <para>The returned value for the attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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. The PDO driver handles the PDO_ATTR_PERSISTENT, PDO_ATTR_CASE, PDO_ATTR_ORACLE_NULLS, and PDO_ATTR_ERRMODE attributes directly. </para> <para/> <para>This function returns 1 on success or 0 on failure.<emphasis role="strong"> </emphasis></para> <para/> <para>static int <db>_handle_set_attribute(</para> <para>pdo_dbh_t *dbh,</para> <para>long attr,</para> <para>zval *val</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to set a database attribute.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>Long value of one of the PDO_ATTR_xxxx types.</para> <para>(see table below for valid attributes)</para> </entry> </row> <row> <entry valign="top"> <para>val</para> </entry> <entry valign="top"> <para>The new value for the attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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. </para> <para/> <para>This function returns 1 on success or 0 on failure.<emphasis role="strong"> </emphasis></para> <para/> <para>static char * <db>_handle_last_id(</para> <para>pdo_dbh_t *dbh,</para> <para>const char *name,</para> <para>unsigned int len</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve the ID of the last inserted row.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>name</para> </entry> <entry valign="top"> <para>Pointer to a character string representing the table name if required by the database.</para> </entry> </row> <row> <entry valign="top"> <para>len</para> </entry> <entry valign="top"> <para>The length of the SQL statement.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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. </para> <para/> <para>static int <db>_check_liveness(</para> <para>pdo_dbh_t *dbh</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to test whether or not a persistent connection to a database is alive and ready for use.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.<emphasis role="strong"> This is an optional function. </emphasis></para> <para/> <para>static function_entry <db>_get_driver_methods(</para> <para>pdo_dbh_t *dbh,</para> <para>int kind</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve a pointer to either the database or statement handling method table.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>kind</para> </entry> <entry valign="top"> <para>One of the following:</para> <para>PDO_DBH_DRIVER_METHOD_KIND_DBH</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Return a pointer to the database handling method table;</para> </listitem> </orderedlist> <para>PDO_DBH_DRIVER_METHOD_KIND_STMT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Return a pointer to the statement handling method table.</para> </listitem> </orderedlist> </entry> </row> </tbody> </tgroup> </informaltable> <para>This function returns a pointer to the method handling requested if successful or NULL if the method table cannot be found.<emphasis role="strong"> </emphasis></para> <para/> <para>static int <db>_handle_factory(</para> <para>pdo_dbh_t *dbh,</para> <para>zval *driver_options</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver 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.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>Pointer to database handle returned by the handle factory</para> </entry> </row> <row> <entry valign="top"> <para>driver_options</para> </entry> <entry valign="top"> <para>DB specific options.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>The PDO driver processes the AUTOCOMMIT and PERSISTENT driver options before calling the handle_factory. It is the handle factory's responsibility to process other options. </para> <para/> <para/> <para>Driver method table</para> <para>A static structure of type pdo_dbh_methods named <db>_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.</para> <para/> <para/> <para>pdo_<db>_driver</para> <para>A structure of type pdo_driver_t named pdo_<db>_driver should be declared. The PDO_DRIVER_HEADER(<db>) macro should be used to declare the header and the function pointer to the handle factory function should set.</para> <para>Statement handling unit -- <db>_statement.c</para> <para>This unit implements all of the database statement handling methods that support the PDO statement object.</para> <para/> <para>static int <db>_stmt_dtor(</para> <para>pdo_stmt_t *stmt</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to destroy a previously constructed statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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. </para> <para/> <para>static int <db>_stmt_execute(</para> <para>pdo_stmt_t *stmt</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to execute the prepared SQL statement in the passed statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>This function returns 1 for success or 0 in the event of failure.</para> <para/> <para>static int <db>_stmt_fetch(</para> <para>pdo_stmt_t *stmt,</para> <para>enum pdo_fetch_orientation ori,</para> <para>long offset</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to fetch a row from a previously executed statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>ori</para> </entry> <entry valign="top"> <para>One of PDO_FETCH_ORI_xxx which will determine which row will be fetched.</para> </entry> </row> <row> <entry valign="top"> <para>offset</para> </entry> <entry valign="top"> <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.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>The results of this fetch are driver dependent and the data is usually stored in the driver_data member of 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.</para> <para/> <para>static int <db>_stmt_param_hook(</para> <para>pdo_stmt_t *stmt,</para> <para>struct pdo_bound_param_data *param,</para> <para>enum pdo_param_event event_type</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver for handling of both bound parameters and bound columns. </para> <para/> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>param</para> </entry> <entry valign="top"> <para>The structure describing which statement variable will be bound to what variable name.</para> </entry> </row> <row> <entry valign="top"> <para>event_type</para> </entry> <entry valign="top"> <para>The type of event to occur for this parameter, one of the following:</para> <para>PDO_PARAM_EVT_ALLOC -- allocate the binding; Only called once, when the binding is created.</para> <para>PDO_PARAM_EVT_FREE -- free the allocated binding; Only called once as part of cleanup. </para> <para>PDO_PARAM_EXEC_PRE -- bind the variable before execution; </para> <para>PDO_PARAM_EXEC_POST -- bind the variable after execution;</para> <para>PDO_PARAM_FETCH_PRE -- bind the variable prior to the fetch;</para> <para>PDO_PARAM_FETCH_POST -- bind the variable after the fetch.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <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. </para> <para/> <para>For all other events, the PDO driver will loop, calling the hook for each of the parameters and colums. </para> <para/> <para>If this is a bound parameter, the is_param flag in the param structure</para> <para/> <para>This function returns 1 for success or 0 in the event of failure.</para> <para/> <para>static int <db>_stmt_describe_col(</para> <para>pdo_stmt_t *stmt,</para> <para>int colno</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to query information about a particular column.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>colno</para> </entry> <entry valign="top"> <para>The column number to be queried.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_stmt_get_col_data(</para> <para>pdo_stmt_t *stmt,</para> <para>int colno,</para> <para>char **ptr,</para> <para>unsigned long *len,</para> <para>int *caller_frees</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve data from the specified column.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>colno</para> </entry> <entry valign="top"> <para>The column number for which data is to be retrieved.</para> </entry> </row> <row> <entry valign="top"> <para>ptr</para> </entry> <entry valign="top"> <para>Pointer to the retrieved data.</para> </entry> </row> <row> <entry valign="top"> <para>len</para> </entry> <entry valign="top"> <para>The length of the data pointed to by ptr.</para> </entry> </row> <row> <entry valign="top"> <para>caller_frees</para> </entry> <entry valign="top"> <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.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_stmt_set_attr(</para> <para>pdo_stmt_t *stmt,</para> <para>long attr,</para> <para>zval *val</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to allow the setting of driver specific attributes for a statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>The attribute to be set (DRIVER DEFINED AND SPECIFIC).</para> </entry> </row> <row> <entry valign="top"> <para>val</para> </entry> <entry valign="top"> <para>New value for the attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>static int <db>_stmt_get_attr(</para> <para>pdo_stmt_t *stmt,</para> <para>long attr,</para> <para>zval *val</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to allow the retrieval of driver specific attributes for a statement object.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>attr</para> </entry> <entry valign="top"> <para>The attribute to be retrieved, one of:</para> <para>PDO_ATTR_CURSOR</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>The type of cursor this statement refers to.</para> </listitem> </orderedlist> <para>PDO_ATTR_CURSOR_NAME</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>The name of the cursor this statement refers to.</para> </listitem> </orderedlist> <para>(Others are DRIVER DEFINED AND SPECIFIC).</para> </entry> </row> <row> <entry valign="top"> <para>val</para> </entry> <entry valign="top"> <para>Pointer to the retrieved attribute.</para> </entry> </row> </tbody> </tgroup> </informaltable> <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.</para> <para/> <para>THE FOLLOWING FUNCTION IS A ROUGH FIRST CUT AND SUBJECT TO CHANGE.</para> <para>static int <db>_stmt_get_col_meta(</para> <para>pdo_stmt_t *stmt,</para> <para>int colno,</para> <para>zval *return_value</para> <para>TSRMLS_DC)</para> <para>This function will be called by the main PDO driver to retrieve meta-data from the specified column.</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="1.1inch"/> <colspec colname="c2" colwidth="3.6inch"/> <tbody> <row> <entry valign="top"> <para>stmt</para> </entry> <entry valign="top"> <para>Pointer to statement structure returned by the statement constructor.</para> </entry> </row> <row> <entry valign="top"> <para>colno</para> </entry> <entry valign="top"> <para>The column number for which data is to be retrieved.</para> </entry> </row> <row> <entry valign="top"> <para>return_value</para> </entry> <entry valign="top"> <para>Pointer to the retrieved data.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para>The driver 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.</para> <para/> <para>Statement handling method table</para> <para>A static structure of type pdo_stmt_methods named <db>_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.</para> <para>Building</para> <para>The build process is designed to work with PEAR (see <ulink url="http://pear.php.net/index.php" type="">http://pear.php.net/index.php</ulink> for more information about PEAR). There are two files that are used to assist in configuring your package for building. The first is config.m4 which is the autoconf configuration file for all platforms except Win32. The second is config.w32 which an autoconf configuration file for use on Win32. Skeleton files for these are built for you when you first set up your project. You then need to customize them to fit the needs of your project. Once you've customized your config files, you can build your driver using the following sequence of commands:</para> <para>Before first build:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>sudo pear install PDO</para> </listitem> </orderedlist> <para>For each build:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>cd pdo_<db></para> </listitem> <listitem> <para>phpize</para> </listitem> <listitem> <para>./configure</para> </listitem> <listitem> <para>make</para> </listitem> <listitem> <para>sudo make install</para> </listitem> </orderedlist> <para>The process can then be repeated as necessary during the development process.</para> <para/> <para/> <para>Package format</para> <para>PDO drivers are released in compress tar format. The following layout should be observed:</para> <para>./</para> <para>package.xml</para> <para>PDO_<DB>-xx.xx</para> <para>… driver build tree</para> <para>where DB is the capitalized short name for the database and xx.xx is the major and minor version numbers.</para> <para>Assuming the directory structure above you then create the release package with the following command:</para> <para>tar cfz pdo_<db>-xx.xx.tar.gz package.xml PDO_<DB>-xx.xx</para> <para>The resultant tar file is then ready for release. The contents of the package.xml file are described in the PEAR Programmer's documentation (<ulink url="http://pear.php.net/manual/index.php" type="">http://pear.php.net/manual/index.php</ulink>).</para> <para/> <para/> <para>Releasing</para> <para>A PDO driver is released using the PHP Extension Community Library (PECL) mechanism. Information about PECL and the coding standards currently in force can be found at <ulink url="http://pecl.php.net/index.php" type="">http://pecl.php.net/index.php</ulink>.</para> <para/> <para/> <para>Testing</para> <para>To be determined. The testing scheme for PDO is still being developed. </para> <para>Appendix A -- pdo_dbh_t</para> <informaltable> <tgroup cols="3"> <colspec colname="c1" colwidth="1.9inch"/> <colspec colname="c2" colwidth="2.3inch"/> <colspec colname="c3" colwidth="2inch"/> <tbody> <row> <entry valign="top"> <para>Variable name</para> </entry> <entry valign="top"> <para>Function</para> </entry> <entry valign="top"> <para>Responsibility</para> </entry> </row> <row> <entry valign="top"> <para>ce</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>properties</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_get</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_set</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>methods</para> </entry> <entry valign="top"> <para>Pointer to the methods function pointer for db handling.</para> </entry> <entry valign="top"> <para>Driver must set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>driver_data</para> </entry> <entry valign="top"> <para>Opaque pointer containing driver specific data.</para> </entry> <entry valign="top"> <para>Driver can store driver specific data and structures for database handling. This field should be allocated and set during handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>username</para> </entry> <entry valign="top"> <para>Database user on behalf access is to be granted.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>password</para> </entry> <entry valign="top"> <para>Password for the database user.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>is_persistent</para> </entry> <entry valign="top"> <para>If true, data stored and pointed to by this handle must be persistently allocated.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>auto_commit</para> </entry> <entry valign="top"> <para>If true, the driver should ensure that a COMMIT is processed at the end of each executed statement. Otherwise, COMMIT will only be done at user request.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>is_closed</para> </entry> <entry valign="top"> <para>If true, this handle is closed and is no longer valid for operations.</para> </entry> <entry valign="top"> <para>This field is NOT initialized and does NOT appear to be used at present.</para> </entry> </row> <row> <entry valign="top"> <para>alloc_own_columns</para> </entry> <entry valign="top"> <para>If true, the driver requires that memory be explicitly allocated for all columns returned. Setting this will cause the PDO driver to call the stmt describer() function after the first statement execute and before the first fetch. </para> </entry> <entry valign="top"> <para>Driver should set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>in_txn</para> </entry> <entry valign="top"> <para>If true, a COMMIT or ROLLBACK is allowed to be called. A transaction is in progress.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. </para> </entry> </row> <row> <entry valign="top"> <para>max_escaped_char_length</para> </entry> <entry valign="top"> <para>This is the maximum length a single character can become after correct quoting. This is only needed if supports_placeholders is PDO_PLACEHOLDER_NONE.</para> </entry> <entry valign="top"> <para>Driver should set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>oracle_nulls</para> </entry> <entry valign="top"> <para>If true, convert all empty strings to NULL.</para> </entry> <entry valign="top"> <para>Driver should set this during the handle factory method.</para> </entry> </row> <row> <entry valign="top"> <para>_reserved_flags</para> </entry> <entry valign="top"> <para>Reserved for PDO main driver.</para> </entry> <entry valign="top"> <para>These are reserved for future use by the main PDO driver.</para> </entry> </row> <row> <entry valign="top"> <para>data_source</para> </entry> <entry valign="top"> <para>A string representing the data source used to open this handle.</para> </entry> <entry valign="top"> <para>This field is initially set by the main PDO driver. It can be modified, if necessary, by the driver. For example, a driver may need to pre-pend a directory path to filename passed or may need to add a qualifier as required by a particular database implementation.</para> </entry> </row> <row> <entry valign="top"> <para>data_source_len</para> </entry> <entry valign="top"> <para>The length of the string in the data_source field.</para> </entry> <entry valign="top"> <para>This field is initially set by the PDO main driver. If a driver modifies the data_source field such that the length changes, this field can be modified by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>error_code</para> </entry> <entry valign="top"> <para>This is the latest error code. It is the SQLSTATE expressed as 6 character ASCIIZ field. </para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. Drivers should set the global variable pdo_err whenever an error occurs and the driver will set this field when appropriate. </para> </entry> </row> <row> <entry valign="top"> <para>error_mode</para> </entry> <entry valign="top"> <para>This field contains the mode in which PDO reports errors. This field is set to one of the following:</para> <para>PDO_ERRMODE_SILENT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Fail silently</para> </listitem> </orderedlist> <para>PDO_ERRMODE_WARNING</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Treat all errors as warnings.</para> </listitem> </orderedlist> <para>PDO_ERRMODE_EXCEPTION</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Throw exceptions instead of returning error codes.</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is initially set to PDO_ERR_MODE_SILENT by the PDO main driver. It can be subsequently modified by the driver via a call to change the attribute.</para> </entry> </row> <row> <entry valign="top"> <para>native_case</para> </entry> <entry valign="top"> <para>This is set to native case for the database being accessed. It can be one of:</para> <para>PDO_CASE_NATURAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Mixed case</para> </listitem> </orderedlist> <para>PDO_CASE_UPPER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>All upper case</para> </listitem> </orderedlist> <para>PDO_CASE_LOWER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>All lower case</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is set during the handle factory method by the driver to appropriate value. The default value is PDO_CASE_NATURAL.</para> </entry> </row> <row> <entry valign="top"> <para>desired_case</para> </entry> <entry valign="top"> <para>This is set to the case conversion requested by the caller. It can be one of the following:</para> <para>PDO_CASE_NATURAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Don't do case conversion</para> </listitem> </orderedlist> <para>PDO_CASE_UPPER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to uppercase</para> </listitem> </orderedlist> <para>PDO_CASE_LOWER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to lowercase</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is set during the handle factory by the driver based on options passed and can be subsequently modified with a call to change the attribute. The default value for this field is PDO_CASE_NATURAL.</para> </entry> </row> <row> <entry valign="top"> <para>persistent_id</para> </entry> <entry valign="top"> <para>This a hash key that is associated with the handle this structure represents.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>persistent_id_len</para> </entry> <entry valign="top"> <para>This is the length of the hash key represented by the persistent_id field.</para> </entry> <entry valign="top"> <para>This field is set by the PDO main driver before the factory method is called. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>refcount</para> </entry> <entry valign="top"> <para>This field contains the count of how many times this handle is currently referenced. If a handle is persistent, this field is increased when a persistent object is created. It is decremented each time the destructor is called. When the count reaches zero, the handle can be safely destructed.</para> </entry> <entry valign="top"> <para>This field is set initially by the main PDO driver to one when the handle is constructed. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>cls_methods</para> </entry> <entry valign="top"> <para>This field is an array of hashtables containing (at present) driver methods for database handling and statement handling.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para/> <para>Appendix B -- pdo_stmt_t</para> <informaltable> <tgroup cols="3"> <colspec colname="c1" colwidth="1.9inch"/> <colspec colname="c2" colwidth="3inch"/> <colspec colname="c3" colwidth="1.9inch"/> <tbody> <row> <entry valign="top"> <para>Variable name</para> </entry> <entry valign="top"> <para>Function</para> </entry> <entry valign="top"> <para>Responsibility</para> </entry> </row> <row> <entry valign="top"> <para>ce</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>properties</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_get</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>in_set</para> </entry> <entry valign="top"> <para>Required for casting as Zend object.</para> </entry> <entry valign="top"> <para>Zend engine. It should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>methods</para> </entry> <entry valign="top"> <para>Pointer to the methods function pointer for SQL statement handling.</para> </entry> <entry valign="top"> <para>Driver should set this during the call to <db>_handle_preparer function.</para> </entry> </row> <row> <entry valign="top"> <para>driver_data</para> </entry> <entry valign="top"> <para>Opaque pointer containing driver specific data.</para> </entry> <entry valign="top"> <para>Driver can store driver specific data and structures for database handling. This field is typically allocated and set during the call to <db>_handle_preparer.</para> </entry> </row> <row> <entry valign="top"> <para>executed</para> </entry> <entry valign="top"> <para>If true, the statement represented by this object has been executed at least once, otherwise, it's never been executed. This is set automatically after the first call to the stmt executor() function.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>supports_placeholders</para> </entry> <entry valign="top"> <para>This field determines whether the driver support placeholders. It can be any one or combination of the following values:</para> <para>PDO_PLACEHOLDER_NONE</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Driver has no placeholder support</para> </listitem> </orderedlist> <para>PDO_PLACEHOLDER_NAMED</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Driver supports named placeholders</para> </listitem> </orderedlist> <para>PDO_PLACEHOLDER_POSITIONAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Driver supports positional placeholders</para> </listitem> </orderedlist> <para>If both named and positional are supported the field should be set to the OR'd value the two values.</para> </entry> <entry valign="top"> <para>The driver should set this field to the appropriate value during the call to <db>_handler_preparer.</para> </entry> </row> <row> <entry valign="top"> <para>_reserved</para> </entry> <entry valign="top"> <para>Reserved for PDO main driver.</para> </entry> <entry valign="top"> <para>These are reserved for future use by the main PDO driver.</para> </entry> </row> <row> <entry valign="top"> <para>column_count</para> </entry> <entry valign="top"> <para>This field contains the number of columns in the result set. The contents of this field is not valid until the “executed” field is set to true and the statement has been executed. There may be cases (driver specific) where this value is not valid until the drivers fetch method has been called at least once.</para> </entry> <entry valign="top"> <para>This field is maintained by the driver. It is normally set during <db>_stmt_execute but can be reset in <db_stmt_next_rowset as well. </para> </entry> </row> <row> <entry valign="top"> <para>columns</para> </entry> <entry valign="top"> <para>This is a pointer to the column description data. It contains column_count number of elements. A column is represented by the pdo_column_data structure. This structure contains the following members:</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>name -- the name of the column</para> </listitem> <listitem> <para>namelen -- the length of name</para> </listitem> <listitem> <para>maxlen -- the maximum length of the data this column can handle</para> </listitem> <listitem> <para>param_type -- the type of data this column contains</para> </listitem> <listitem> <para>precision -- if numeric data, the precision of data contained.</para> </listitem> </orderedlist> </entry> <entry valign="top"> <para>This field is allocated and freed by the PDO main driver. However, the driver is responsible for populating the contents during the call to <db>_stmt_describe.</para> </entry> </row> <row> <entry valign="top"> <para>database_object_handle</para> </entry> <entry valign="top"> <para>This is the Zend object representation of the database handle. This field is kept so that a reference to the database handle object is always referenced while as statement object exists.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>dbh</para> </entry> <entry valign="top"> <para>This is a pointer to pdo_dbh_t representation of the database handle. It is valid so long as the database_object_handle is valid.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver.</para> </entry> </row> <row> <entry valign="top"> <para>bound_params</para> </entry> <entry valign="top"> <para>This is a hashtable of bound input parameters. This is kept because not all drivers support both input and out parameters.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>bound_param_map</para> </entry> <entry valign="top"> <para>This hashtable contains a mapping of positions to names when rewriting from named to positional.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>bound_columns</para> </entry> <entry valign="top"> <para>This hashtable is used to keep track of PHP variables that are bound to named or positional columns in the result set.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>row_count</para> </entry> <entry valign="top"> <para>This field represents the count of rows available in the result set.</para> </entry> <entry valign="top"> <para>This field is initialized to zero by the PDO main driver and CAN be set by the driver during the <db>_handle_doer method call. Note: not all drivers have this information available at this time so the reliability of this field is driver specific.</para> </entry> </row> <row> <entry valign="top"> <para>query_string</para> </entry> <entry valign="top"> <para>This character string holds the current raw SQL query associated with this statement.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>query_stringlen</para> </entry> <entry valign="top"> <para>This field represents the length of the raw SQL query string.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver and should be treated as read-only by the driver. There are no known instances where a driver needs to access this variable.</para> </entry> </row> <row> <entry valign="top"> <para>error_code</para> </entry> <entry valign="top"> <para>This is the latest error code for this statement. It is the SQLSTATE expressed as 6 character field.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. Drivers should set the global variable pdo_err whenever an error occurs and the driver will set this field when appropriate. </para> </entry> </row> <row> <entry valign="top"> <para>lazy_object_ref</para> </entry> <entry valign="top"> <para>This field is used to store the lazy object handle (fetch type is equal to PDO_FETCH_LAZY) that is returned for each lazy fetch.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers.</para> </entry> </row> <row> <entry valign="top"> <para>refcount</para> </entry> <entry valign="top"> <para>This is count of how many lazy fetches have been done.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers.</para> </entry> </row> <row> <entry valign="top"> <para>default_fetch_type</para> </entry> <entry valign="top"> <para>This is the default fetch type. It can be any one of the following:</para> <para>PDO_FETCH_USE_DEFAULT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Use the default fetch mode</para> </listitem> </orderedlist> <para>PDO_FETCH_LAZY</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an object with variable names that correspond to the column names returned in the result set. PDO_FETCH_LAZY creates the object variable names as they are accessed.</para> </listitem> </orderedlist> <para>PDO_FETCH_ASSOC</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an array indexed by column name as returned in the corresponding result set.</para> </listitem> </orderedlist> <para>PDO_FETCH_NUM</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an array indexed by column number as returned in the corresponding result set, starting at column 0.</para> </listitem> </orderedlist> <para>PDO_FETCH_BOTH</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an array indexed by both column name and number as returned in the corresponding result set, starting at column 0.</para> </listitem> </orderedlist> <para>PDO_FETCH_OBJ</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return each row as an object with property names that correspond to the column names returned in the result set.</para> </listitem> </orderedlist> <para>PDO_FETCH_BOUND</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return TRUE and assign the values of the columns in the result set to the variables to which they were bound.</para> </listitem> </orderedlist> <para>PDO_FETCH_COLUMN</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return only a single requested column from the next row in the result set.</para> </listitem> </orderedlist> <para>PDO_FETCH_CLASS</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall return a new instance of the requested class, mapping the columns to named properties in the class.</para> </listitem> </orderedlist> <para>PDO_FETCH_INTO</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Specifies that the fetch method shall update an existing instance of the requested class, mapping the columns to named properties in the class.</para> </listitem> </orderedlist> <para>PDO_FETCH_FUNC</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Fetch into function and return result of function.</para> </listitem> </orderedlist> <para/> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers. The default value for this field is PDO_FETCH_BOTH.</para> </entry> </row> <row> <entry valign="top"> <para>fetch</para> </entry> <entry valign="top"> <para>This union is used to contain fetch information used by the PDO main driver.</para> </entry> <entry valign="top"> <para>This field is set and maintained by the PDO main driver. It should not be used by drivers.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para/> <para>Appendix C - Database and Statement Attributes Table</para> <informaltable> <tgroup cols="2"> <colspec colname="c1" colwidth="3inch"/> <colspec colname="c2" colwidth="2.7inch"/> <tbody> <row> <entry valign="top"> <para>Attribute</para> </entry> <entry valign="top"> <para>Valid value(s)</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_AUTOCOMMIT</para> </entry> <entry valign="top"> <para>ZVAL_BOOL</para> <para>TRUE if autocommit is set, FALSE otherwise. </para> <para>Dbh->auto_commit contains value. Processed by the PDO driver directly.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_PREFETCH</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>Value of the prefetch size in drivers that support it.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_TIMEOUT</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>How long to wait for a db operation before timing out.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_ERRMODE</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>PDO_ERRMODE_SILENT</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Fail silently</para> </listitem> </orderedlist> <para>PDO_ERRMODE_WARNING</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Treat all errors as warnings.</para> </listitem> </orderedlist> <para>PDO_ERRMODE_EXCEPTION</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Throw exceptions instead of returning error codes.</para> </listitem> </orderedlist> <para/> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_SERVER_VERSION</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>The “human-readable” string representing the Server/Version this driver supports.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CLIENT_VERSION</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>The “human-readable” string representing the Client/Version this driver supports.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_SERVER_INFO</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>The “human-readable” description of the Server.</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CONNECTION_STATUS</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>Values not yet defined</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CASE</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>PDO_CASE_NATURAL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Don't do case conversion</para> </listitem> </orderedlist> <para>PDO_CASE_UPPER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to uppercase</para> </listitem> </orderedlist> <para>PDO_CASE_LOWER</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Convert strings to lowercase</para> </listitem> <listitem> <para/> </listitem> </orderedlist> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CURSOR_NAME</para> </entry> <entry valign="top"> <para>ZVAL_STRING</para> <para>String representing the name for a database cursor for use in “where current in <name>” SQL statements</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_CURSOR</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>PDO_CURSOR_FWDONLY</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Forward only cursor</para> </listitem> </orderedlist> <para>PDO_CURSOR_SCROLL</para> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>Scrollable cursor</para> </listitem> </orderedlist> <para/> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_ORACLE_NULLS</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>(For Oracle Driver)</para> <para>dbh->oracle_nulls is set the result of Z_LVAL_P(value) ? 1 : 0</para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_PERSISTENT</para> </entry> <entry valign="top"> <para>ZVAL_BOOL</para> <para>True if persistent connection, false if not. Processed directly by the PDO driver. </para> </entry> </row> <row> <entry valign="top"> <para>PDO_ATTR_STATEMENT_CLASS</para> </entry> <entry valign="top"> <para>ZVAL_LONG</para> <para>Values not yet defined.</para> </entry> </row> </tbody> </tgroup> </informaltable> <para/> <para>The values for the attributes above are all defined in terms of the Zend API. The Zend API contains macros that can be used to convert a *zval to a value. These macros are defined in the Zend header file, zend_API.h in the Zend directory of your PHP build directory. Some of these attributes can be used with the statement attribute handlers such as the PDO_ATTR_CURSOR and PDO_ATTR_CURSOR_NAME. See the statement attribute handling functions for more information.</para> <para/> <para>Appendix D -- Error handling</para> <para/> <para>Error handling is implemented using a hand-shaking protocol between the main PDO driver and the database driver code. The database driver code signals the PDO driver than an error has occurred via a failure (“0”) return from any of the interface functions. If a zero is returned, the field error_code in the control block appropriate to the context (either the pdo_dbh_t or pdo_stmt_t block). In practice, it is probably a good idea to set the field in both blocks to the same value to ensure the correct one is getting used. </para> <para/> <para>The error_mode field is a six-field field containing a 5 character ASCIIZ SQLSTATE identifier code. This code drives the error message process. The SQLSTATE code is used to look up an error message in the internal PDO error message table (see pdo_sqlstate.c for a list of error codes and their messages). If the code is not known to the PDO driver, a default “Unknown Message” value will be used. </para> <para/> <para>In addition to the SQLSTATE code and error message, the PDO driver will call the driver-specific fetch-err() routine to obtain supplemental data for the particular error condition. This routine is passed an array into which the driver may place additional information. This array has slot positions assigned to particular types of supplemental info:</para> <para/> <orderedlist continuation="restarts" numeration="arabic"> <listitem> <para>A native error code. This will frequently be an error code obtained from the database API. </para> </listitem> <listitem> <para>A descriptive string. This string can contain anything additional information related to the failure. Database drivers typically include information such as an error message, code location of the failure, and any additional descriptive information the driver developer feels worthy of inclusion. It is generally a good idea to include all diagnostic information<emphasis role="strong"> </emphasis>obtainable from the database interface at the time of the failure. For driver-detected errors (such as memory allocation problems), the driver developer can define whatever error information that seems appropriate.</para> </listitem> </orderedlist> <para/> <para/> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->