<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<sect1 xml:id="internals2.pdo.implementing" xmlns="http://docbook.org/ns/docbook">
 <title>Fleshing out your skeleton</title>
 <sect2 xml:id="internals2.pdo.implementing.structures">
 <title>Major Structures and Attributes</title>
  <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>
 </sect2>

 <sect2 xml:id="internals2.pdo.implementing.skel">
  <title>pdo_SKEL.c: PHP extension glue</title>
  <sect3 xml:id="internals2.pdo.implementing.skel.entries">
   <title>function entries</title>
   <synopsis><![CDATA[
static function_entry pdo_SKEL_functions[] = {
  { NULL, NULL, NULL }
};]]></synopsis>
   <para>
    This structure is used to register functions into the global php function
    namespace.  PDO drivers should try to avoid doing this, so it is
    recommended that you leave this structure initialized to NULL, as shown in
    the synopsis above.
   </para>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.skel.module">
   <title>Module entry</title>
   <synopsis><![CDATA[
/* {{{ pdo_SKEL_module_entry */
#if ZEND_EXTENSION_API_NO >= 220050617
static zend_module_dep pdo_SKEL_deps[] = {
    ZEND_MOD_REQUIRED("pdo")
    {NULL, NULL, NULL}
};
#endif
/* }}} */

zend_module_entry pdo_SKEL_module_entry = {
#if ZEND_EXTENSION_API_NO >= 220050617
    STANDARD_MODULE_HEADER_EX, NULL,
    pdo_SKEL_deps,
#else
    STANDARD_MODULE_HEADER,
#endif
    "pdo_SKEL",
    pdo_SKEL_functions,
    PHP_MINIT(pdo_SKEL),
    PHP_MSHUTDOWN(pdo_SKEL),
    NULL,
    NULL,
    PHP_MINFO(pdo_SKEL),
    PHP_PDO_<DB>_MODULE_VERSION,
    STANDARD_MODULE_PROPERTIES
};
/* }}} */

#ifdef COMPILE_DL_PDO_<DB>
ZEND_GET_MODULE(pdo_db)
#endif]]></synopsis>
   <para>
    A structure of type zend_module_entry called
    pdo_SKEL_module_entry must be declared and should include reference to
    the pdo_SKEL_functions table defined previously.
   </para>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.skel.functions">
   <title>Standard PHP Module Extension Functions</title>
   <sect4 xml:id="internals2.pdo.implementing.skel.functions.minit">
    <title>PHP_MINIT_FUNCTION</title>
    <synopsis><![CDATA[
/* {{{ PHP_MINIT_FUNCTION */
PHP_MINIT_FUNCTION(pdo_SKEL)
{
    return php_pdo_register_driver(&pdo_SKEL_driver);
}
/* }}} */]]></synopsis>
    <para>
     This standard PHP extension function should be used to register your
     driver with the PDO layer. This is done by calling the
     <function>php_pdo_register_driver</function> function passing a pointer to
     a structure of type <type>pdo_driver_t</type> typically named
     <literal>pdo_SKEL_driver</literal>.  A <type>pdo_driver_t</type>
     contains a header that is generated using the
     <literal>PDO_DRIVER_HEADER(SKEL)</literal> macro and
     <function>pdo_SKEL_handle_factory</function> function pointer. The
     actual function is described during the discussion of the
     <filename>SKEL_dbh.c</filename> unit.
    </para>
   </sect4>

   <sect4 xml:id="internals2.pdo.implementing.skel.functions.mshutdown">
    <title>PHP_MSHUTDOWN_FUNCTION</title>
    <synopsis><![CDATA[
/* {{{ PHP_MSHUTDOWN_FUNCTION */
PHP_MSHUTDOWN_FUNCTION(pdo_SKEL)
{
    php_pdo_unregister_driver(&pdo_SKEL_driver);
    return SUCCESS;
}
/* }}} */]]></synopsis>
    <para>
     This standard PHP extension function is used to unregister your driver
     from the PDO layer. This is done by calling the
     <function>php_pdo_unregister_driver</function> function, passing the same
     <literal>pdo_SKEL_driver</literal> structure that was passed in the
     init function above.
    </para>
   </sect4>
   <sect4 xml:id="internals2.pdo.implementing.skel.functions.minfo">
    <title>PHP_MINFO_FUNCTION</title>
    <para>
     This is again a standard PHP extension function. Its purpose is to
     display information regarding the module when the
     <function>phpinfo</function> is called from a script.  The convention is
     to display the version
     of the module and also what version of the db you are dependent on, along
     with any other configuration style information that might be relevant.
    </para>
   </sect4>
  </sect3>
 </sect2>
 <sect2 xml:id="internals2.pdo.implementing.driver">
  <title>SKEL_driver.c: Driver implementation</title>

  <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>

  <sect3 xml:id="internals2.pdo.implementing.driver.error">
   <title>pdo_SKEL_error</title>

   <synopsis><![CDATA[static int pdo_SKEL_error(pdo_dbh_t *dbh,
  pdo_stmt_t *stmt, const char *file, int line TSRMLS_DC)]]></synopsis>

   <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 <literal>dbh-&gt;error_code</literal> or
    <literal>stmt-&gt;error_code</literal> to an
    SQLSTATE that most closely matches the error or the generic SQLSTATE error
    <quote>HY000</quote>. The file pdo_sqlstate.c in the PDO source contains a table
    of commonly used SQLSTATE codes that the PDO code explicitly recognizes.
    This setting of the error code should be done prior to calling this
    function.; This function should set the global
    <parameter>pdo_err</parameter> variable to the error found in either the
    dbh or the stmt (if the variable stmt is not NULL).
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the current statement or NULL. If NULL, the error is derived by error code found in the dbh.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>file</term>
     <listitem>
      <para>The source file where the error occurred or NULL if not available.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>line</term>
     <listitem>
      <para>The line number within the source file if available.</para>
     </listitem>
    </varlistentry>
   </variablelist> 
   <para>
    If the dbh member methods is NULL (which implies that the error is being
    raised from within the PDO constructor), this function should call the
    zend_throw_exception_ex() function otherwise it should return the error
    code.  This function is usually called using a helper macro that customizes
    the calling sequence for either database handling errors or statement
    handling errors.
   </para>

   <example xml:id="internals2.pdo.implementing.driver.error.ex-macros">
    <title>Example macros for invoking pdo_SKEL_error</title>
    <programlisting role="c"><![CDATA[
#define pdo_SKEL_drv_error(what) \
    pdo_SKEL_error(dbh, NULL, what, __FILE__, __LINE__ TSRMLS_CC)
#define pdo_SKEL_drv_error(what) \
    pdo_SKEL_error(dbh, NULL, what, __FILE__, __LINE__ TSRMLS_CC)]]>
    </programlisting>
   </example>
   <para>
    For more info on error handling, see <xref
    linkend="internals2.pdo.error-handling"/>.
   </para>
   <note>
    <para>
     Despite being documented here, the PDO driver interface does not specify
     that this function be present; it is merely a convenient way to handle
     errors, and it just happens to be equally convenient for the majority of
     database client library APIs to structure your driver implementation in
     this way.
    </para>
   </note>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.fetch-err">
   <title>pdo_SKEL_fetch_error_func</title>
   <synopsis><![CDATA[static int pdo_SKEL_fetch_error_func(pdo_dbh_t *dbh, pdo_stmt_t *stmt,
    zval *info TSRMLS_DC)]]></synopsis>

   <para>
    The purpose of this function is to obtain additional information about the
    last error that was triggered.  This includes the driver specific error
    code and a human readable string.  It may also include additional
    information if appropriate.  This function is called as a result of the PHP
    script calling the <function>PDO::errorInfo</function> method.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>
       Pointer to the most current statement or NULL. If NULL, the error
       translated is derived by error code found in the dbh.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>info</term>
     <listitem>
      <para>A hash table containing error codes and messages.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    The error_func should return two pieces of information as successive array
    elements. The first item is expected to be a numeric error code, the second
    item is a descriptive string. The best way to set this item is by using
    add_next_index.  Note that the type of the first argument need not be
    <type>long</type>; use whichever type most closely matches the error code
    returned by the underlying database API.
   </para>

   <programlisting role="c"><![CDATA[
/* now add the error information. */
/* These need to be added in a specific order */
add_next_index_long(info, error_code);   /* driver specific error code */
add_next_index_string(info, message, 0); /* readable error message */
]]></programlisting>

   <para>
    This function should return 1 if information is available, 0 if the driver
    does not have additional info.
   </para>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.handle-closer">
   <title>SKEL_handle_closer</title>
   <synopsis><![CDATA[static int SKEL_handle_closer(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO to close an open
    database.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    This should do whatever database specific activity that needs to be
    accomplished to close the open database. PDO ignores the return
    value from this function.
   </para>
  </sect3>

  <sect3 xml:id="internals2.pdo.preparer">
   <title>SKEL_handle_preparer</title>
   <synopsis><![CDATA[static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql,
long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO in response to
    <function>PDO::query</function> and <function>PDO::prepare</function>
    calls from the PHP script.  The purpose of the function is to prepare
    raw SQL for execution, storing whatever state is appropriate into the
    <parameter>stmt</parameter> that is passed in.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>sql</term>
     <listitem>
      <para>Pointer to a character string containing the SQL statement to be prepared.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>sql_len</term>
     <listitem>
      <para>The length of the SQL statement.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Stmt</term>
     <listitem>
      <para>Pointer to the returned statement or NULL if an error occurs.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>driver_options</term>
     <listitem>
      <para>Any driver specific/defined options.</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    This function is essentially the constructor for a stmt object. This
    function is responsible for processing statement options, and setting
    driver-specific option fields in the pdo_stmt_t structure.
   </para>
   <para>
    PDO does not process any statement options on the driver's
    behalf before calling the preparer function.  It is your responsibility to
    process them before you return, raising an error for any unknown options that
    are passed.
   </para>
   <para>
    One very important responsibility of this function is the processing of SQL
    statement parameters. At the time of this call, PDO does not know if your
    driver supports binding parameters into prepared statements, nor does it
    know if it supports named or positional parameter naming conventions.
   </para>
   <para>
    Your driver is responsible for setting
    <literal>stmt-&gt;supports_placeholders</literal> as appropriate for the
    underlying database.  This may involve some run-time determination on the
    part of your driver, if this setting depends on the version of the database
    server to which it is connected.  If your driver doesn't directly support
    both named and positional parameter conventions, you should use the
    <function>pdo_parse_params</function> API to have PDO rewrite the query to
    take advantage of the support provided by your database.
   </para>
   <example xml:id="internals2.pdo.implementing.preparer.ex-parse-params">
    <title>Using pdo_parse_params</title>
    <programlisting role="c"><![CDATA[
    int ret;
    char *nsql = NULL;
    int nsql_len = 0;

    /* before we prepare, we need to peek at the query; if it uses named parameters,
     * we want PDO to rewrite them for us */
    stmt->supports_placeholders = PDO_PLACEHOLDER_POSITIONAL;
    ret = pdo_parse_params(stmt, (char*)sql, sql_len, &nsql, &nsql_len TSRMLS_CC);

    if (ret == 1) {
        /* query was re-written */
        sql = nsql;
    } else if (ret == -1) {
        /* couldn't grok it */
        strcpy(dbh->error_code, stmt->error_code);
        return 0;
    }

    /* now proceed to prepare the query in "sql" */
]]></programlisting>
   </example>
   <para>
    Possible values for <literal>supports_placeholders</literal> are:
    <constant>PDO_PLACEHOLDER_NAMED</constant>,
    <constant>PDO_PLACEHOLDER_POSITIONAL</constant> and
    <constant>PDO_PLACEHOLDER_NONE</constant>.  If the driver doesn't support prepare statements at all, then this function should simply allocate any state that it might need, and then return:
   </para>
   <example xml:id="internals2.pdo.implementing.preparer.ex-no-native-prep">
    <title>Implementing preparer for drivers that don't support native prepared statements</title>
    <programlisting role="c"><![CDATA[
static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql,
    long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC)
{
    pdo_SKEL_db_handle *H = (pdo_SKEL_db_handle *)dbh->driver_data;
    pdo_SKEL_stmt *S = ecalloc(1, sizeof(pdo_SKEL_stmt));

    S->H = H;
    stmt->driver_data = S;
    stmt->methods = &SKEL_stmt_methods;
    stmt->supports_placeholders = PDO_PLACEHOLDER_NONE;

    return 1;
}
]]></programlisting>
   </example>

   <para>This function returns 1 on success or 0 on failure.</para>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.handle-doer">
  <title>SKEL_handle_doer</title>
   <synopsis><![CDATA[static long SKEL_handle_doer(pdo_dbh_t *dbh, const char *sql, long sql_len TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO to execute a raw SQL
    statement. No pdo_stmt_t is created.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>sql</term>
     <listitem>
      <para>Pointer to a character string containing the SQL statement to be prepared.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>sql_len</term>
     <listitem>
      <para>The length of the SQL statement.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    This function returns 1 on success or 0 on failure.
   </para>

  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.handle-quoter">
   <title>SKEL_handle_quoter</title>
   <synopsis><![CDATA[static int SKEL_handle_quoter(pdo_dbh_t *dbh, const char *unquoted,
  int unquoted_len, char **quoted, int quoted_len, enum pdo_param_type param_type TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO to turn an unquoted
    string into a quoted string for use in a query.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>unquoted</term>
     <listitem>
      <para>Pointer to a character string containing the string to be quoted.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>unquoted_len</term>
     <listitem>
      <para>The length of the string to be quoted.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>quoted</term>
     <listitem>
      <para>Pointer to the address where a pointer to the newly quoted string will be returned.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>quoted_len</term>
     <listitem>
      <para>The length of the new string.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>param_type</term>
     <listitem>
      <para>A driver specific hint for driver that have alternate quoting styles</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    This function is called in response to a call to
    <function>PDO::quote</function> or when the driver has set
    <literal>supports_placeholder</literal> to
    <constant>PDO_PLACEHOLDER_NONE</constant>. The purpose is to quote a
    parameter when building SQL statements.
   </para>
   <para>
    If your driver does not support native prepared statements, implementation
    of this function is required.
   </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>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.handle-begin">
   <title>SKEL_handle_begin</title>
   <synopsis><![CDATA[static int SKEL_handle_begin(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO to begin a database transaction.
   </para>
   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <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>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.handle-commit">
   <title>SKEL_handle_commit</title>
   <synopsis><![CDATA[static int SKEL_handle_commit(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO to end a database
    transaction.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    This should do whatever database specific activity that needs to be
    accomplished to commit a transaction. This function returns 1 for success or 0 if an error occurred.
   </para>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.handle-rollback">
   <title>SKEL_handle_rollback</title>
   <synopsis><![CDATA[static int SKEL_handle_rollback( pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis>
   <para>This function will be called by PDO to rollback a database transaction.</para>
   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <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>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.get-attr">
   <title>SKEL_handle_get_attribute</title>
   <synopsis><![CDATA[static int SKEL_handle_get_attribute(pdo_dbh_t *dbh, long attr, zval *return_value TSRMLS_DC)]]></synopsis>
   <para>This function will be called by PDO to retrieve a database attribute.</para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>attr</term>
     <listitem>
      <para>
       <type>long</type> value of one of the PDO_ATTR_xxxx types.  See <xref
       linkend="internals2.pdo.table.attributes"/> for valid attributes.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>return_value</term>
     <listitem>
      <para>The returned value for the attribute.</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    It is up to the driver to decide which attributes will be supported for a
    particular implementation. It is not necessary for a driver to supply this
    function. PDO driver handles the PDO_ATTR_PERSISTENT, PDO_ATTR_CASE,
    PDO_ATTR_ORACLE_NULLS, and PDO_ATTR_ERRMODE attributes directly. 
   </para>
   <para>
    This function returns 1 on success or 0 on failure.
   </para>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.driver.set-attr">
   <title>SKEL_handle_set_attribute</title>
   <synopsis>static int SKEL_handle_set_attribute(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC)</synopsis>
   <para>
    This function will be called by PDO to set a database attribute, usually in
    response to a script calling <function>PDO::setAttribute</function>.
   </para>
   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>attr</term>
     <listitem>
      <para>
       <type>long</type> value of one of the PDO_ATTR_xxxx types.  See <xref
       linkend="internals2.pdo.table.attributes"/> for valid attributes.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>val</term>
     <listitem>
      <para>The new value for the attribute.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <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>
    This function returns 1 on success or 0 on failure.
   </para>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.driver.last-id">
   <title>SKEL_handle_last_id</title>
   <synopsis><![CDATA[static char * SKEL_handle_last_id(pdo_dbh_t *dbh, const char *name, unsigned int len TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO to retrieve the ID of the last inserted
    row.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>name</term>
     <listitem>
      <para>
       string representing a table or sequence name.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>len</term>
     <listitem>
      <para>the length of the <parameter>name</parameter> parameter.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <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>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.driver.check-live">
   <title>SKEL_check_liveness</title>

   <synopsis><![CDATA[static int SKEL_check_liveness(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO to test whether or not a persistent
    connection to a database is alive and ready for use.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <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.
   </para>
   
   <note>
    <para>
     This is an optional function.
    </para>
   </note>

  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.driver.get-methods">
   <title>SKEL_get_driver_methods</title>
   <synopsis><![CDATA[static function_entry *SKEL_get_driver_methods(pdo_dbh_t *dbh, int kind TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO in response to a call to any method
    that is not a part of either the <classname>PDO</classname> or
    <classname>PDOStatement</classname> classes.  It's purpose is to allow the
    driver to provide additional driver specific methods to those classes.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>kind</term>
     <listitem>
      <para>One of the following:</para>
      <variablelist>
       <varlistentry>
        <term>PDO_DBH_DRIVER_METHOD_KIND_DBH</term>
        <listitem>
         <para>
          Set when the method call was attempted on an instance of the
          <classname>PDO</classname> class.  The driver should return a pointer
          a function_entry table for any methods it wants to add to that class,
          or NULL if there are none.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>PDO_DBH_DRIVER_METHOD_KIND_STMT</term>
        <listitem>
         <para>
          Set when the method call was attempted on an instance of the
          <classname>PDOStatement</classname> class.  The driver should return
          a pointer to a function_entry table for any methods it wants to add
          to that class, or NULL if there are none.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    This function returns a pointer to the function_entry table requested,
    or NULL there are no driver specific methods.
   </para>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.driver.handle-factory">
   <title>SKEL_handle_factory</title>
   <synopsis><![CDATA[static int SKEL_handle_factory(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO to create a database handle. For most
    databases this involves establishing a connection to the database. In some
    cases, a persistent connection may be requested, in other cases connection
    pooling may be requested. All of these are database/driver dependent.
   </para>

   <variablelist>
    <varlistentry>
     <term>dbh</term>
     <listitem>
      <para>Pointer to the database handle initialized by the handle factory</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>driver_options</term>
     <listitem>
      <para>
       An array of driver options, keyed by integer option number. See <xref
       linkend="internals2.pdo.table.attributes"/> for a list of possible attributes.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>

   <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>
    PDO processes the AUTOCOMMIT and PERSISTENT driver options
    before calling the handle_factory. It is the handle factory's
    responsibility to process other options.
   </para>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.driver.method-table">
   <title>Driver method table</title>
   <para>
    A static structure of type pdo_dbh_methods named SKEL_methods must be
    declared and initialized to the function pointers for each defined
    function. If a function is not supported or not implemented the value for
    that function pointer should be set to NULL.
   </para>
  </sect3>
  
  <sect3 xml:id="internals2.pdo.implementing.driver.skeldriver">
   <title>pdo_SKEL_driver</title>
   <para>
    A structure of type pdo_driver_t named pdo_SKEL_driver should be declared.
    The PDO_DRIVER_HEADER(SKEL) macro should be used to declare the header and
    the function pointer to the handle factory function should set.
   </para>
  </sect3>
 </sect2>
 <sect2 xml:id="internals2.pdo.implementing.statement">
  <title>SKEL_statement.c: Statement implementation</title>
  <para>
   This unit implements all of the database statement handling methods that
   support the PDO statement object.
  </para>
  <sect3 xml:id="internals2.pdo.implementing.statement.dtor">
   <title>SKEL_stmt_dtor</title>

   <synopsis><![CDATA[static int SKEL_stmt_dtor(pdo_stmt_t *stmt TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO to destroy a previously constructed statement object.
   </para>
   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <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>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.statement.exec">
   <title>SKEL_stmt_execute</title>
   <synopsis><![CDATA[static int SKEL_stmt_execute(pdo_stmt_t *stmt TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO to execute the prepared SQL statement
    in the passed statement object.
   </para>
   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    This function returns 1 for success or 0 in the event of failure.
   </para>
   </sect3>
   <sect3 xml:id="internals2.pdo.implementing.statement.fetch">
   <title>SKEL_stmt_fetch</title>
   <synopsis>static int SKEL_stmt_fetch(pdo_stmt_t *stmt, enum pdo_fetch_orientation ori,
   long offset TSRMLS_DC)</synopsis>
   
   <para>
    This function will be called by PDO to fetch a row from a previously
    executed statement object.
   </para>

   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>ori</term>
     <listitem>
      <para>One of PDO_FETCH_ORI_xxx which will determine which row will be fetched.</para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>offset</term>
     <listitem>
      <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>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    The results of this fetch are driver dependent and the data is usually
    stored in the driver_data member of the pdo_stmt_t object. The ori and
    offset parameters are only meaningful if the statement represents a
    scrollable cursor. This function returns 1 for success or 0 in the event of
    failure.
   </para>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.statement.param-hook">
   <title>SKEL_stmt_param_hook</title>
   <synopsis><![CDATA[static int SKEL_stmt_param_hook(pdo_stmt_t *stmt,
  struct pdo_bound_param_data *param, enum pdo_param_event event_type TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO for handling of both bound parameters and bound columns.
   </para>

   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>param</term>
     <listitem>
      <para>
       The structure describing either a statement parameter or a bound column.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>event_type</term>
     <listitem>
      <para>The type of event to occur for this parameter, one of the following:</para>
      <variablelist>

       <varlistentry>
        <term>PDO_PARAM_EVT_ALLOC</term>
        <listitem>
         <para>Called when PDO allocates the binding.  Occurs as part of
         <function>PDOStatement::bindParam</function>,
         <function>PDOStatement::bindValue</function> or as part of an implicit bind
         when calling <function>PDOStatement::execute</function>.  This is your
         opportunity to take some action at this point; drivers that implement
         native prepared statements will typically want to query the parameter
         information, reconcile the type with that requested by the script,
         allocate an appropriately sized buffer and then bind the parameter to
         that buffer.  You should not rely on the type or value of the zval at
         <literal>param-&gt;parameter</literal> at this point in time.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>PDO_PARAM_EVT_FREE</term>
        <listitem>
         <para>Called once per parameter as part of cleanup.  You should
         release any resources associated with that parameter now.</para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>PDO_PARAM_EXEC_PRE</term>
        <listitem>
         <para>Called once for each parameter immediately before calling
         SKEL_stmt_execute; take this opportunity to make any final adjustments
         ready for execution.  In particular, you should note that variables
         bound via <function>PDOStatement::bindParam</function> are only legal
         to touch now, and not any sooner.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>PDO_PARAM_EXEC_POST</term>
        <listitem>
         <para>Called once for each parameter immediately after calling
         SKEL_stmt_execute; take this opportunity to make any post-execution
         actions that might be required by your driver.</para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>PDO_PARAM_FETCH_PRE</term>
        <listitem>
         <para>Called once for each parameter immediately prior to calling
         SKEL_stmt_fetch.</para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>PDO_PARAM_FETCH_POST</term>
        <listitem>
         <para>Called once for each parameter immediately after calling
          SKEL_stmt_fetch.</para>
        </listitem>
       </varlistentry>

       </variablelist>
     </listitem>
    </varlistentry>
   </variablelist>

   <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>
    For all other events, PDO may call you multiple times as the script issues
    <function>PDOStatement::execute</function> and
    <function>PDOStatement::fetch</function> calls.
   </para>
   <para>
    If this is a bound parameter, the is_param flag in the param structure is
    set, otherwise the param structure refers to a bound column.
   </para>
   <para>
    This function returns 1 for success or 0 in the event of failure.
   </para>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.statement.desc-col">
   <title>SKEL_stmt_describe_col</title>
   <synopsis><![CDATA[static int SKEL_stmt_describe_col(pdo_stmt_t *stmt, int colno TSRMLS_DC)]]></synopsis>

   <para>
    This function will be called by PDO to query information about a particular
    column.
   </para>

   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>colno</term>
     <listitem>
      <para>The column number to be queried.</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <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>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.statement.get-col-data">
   <title>SKEL_stmt_get_col_data</title>
   <synopsis><![CDATA[static int SKEL_stmt_get_col_data(pdo_stmt_t *stmt, int colno,
  char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO to retrieve data from the specified column.
   </para>
   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>colno</term>
     <listitem>
      <para>The column number to be queried.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>ptr</term>
     <listitem>
      <para>Pointer to the retrieved data.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>len</term>
     <listitem>
      <para>The length of the data pointed to by ptr.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>caller_frees</term>
     <listitem>
      <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>
     </listitem>
    </varlistentry>
   </variablelist>
   <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>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.statement.set-attr">
  <title>SKEL_stmt_set_attr</title>
  <synopsis>static int SKEL_stmt_set_attr(pdo_stmt_t *stmt, long attr, zval *val TSRMLS_DC)</synopsis>

  <para>
   This function will be called by PDO to allow the setting of driver specific
   attributes for a statement object.
  </para>

  <variablelist>
   <varlistentry>
    <term>stmt</term>
    <listitem>
     <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>attr</term>
    <listitem>
     <para>
      <type>long</type> value of one of the PDO_ATTR_xxxx types.  See <xref
      linkend="internals2.pdo.table.attributes"/> for valid attributes.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>val</term>
    <listitem>
     <para>The new value for the attribute.</para>
    </listitem>
   </varlistentry>
  </variablelist>


  <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>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.statement.get-attr">
   <title>SKEL_stmt_get_attr</title>
   <synopsis><![CDATA[static int SKEL_stmt_get_attr(pdo_stmt_t *stmt, long attr, zval
   *return_value TSRMLS_DC)]]></synopsis>
   <para>
    This function will be called by PDO to allow the retrieval of driver
    specific attributes for a statement object.
   </para>

   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>attr</term>
     <listitem>
      <para>
       <type>long</type> value of one of the PDO_ATTR_xxxx types.  See <xref
       linkend="internals2.pdo.table.attributes"/> for valid attributes.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>return_value</term>
     <listitem>
      <para>The returned value for the attribute.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <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>
  </sect3>
  <sect3 xml:id="internals2.pdo.implementing.statement.get-col-meta">
   <title>SKEL_stmt_get_col_meta</title>
   <synopsis><![CDATA[static int SKEL_stmt_get_col_meta(pdo_stmt_t *stmt, int colno,
   zval *return_value TSRMLS_DC)]]></synopsis>
   <warning>
    <para>
     This function is not well defined and is subject to change.
    </para>
   </warning>

   <para>
    This function will be called by PDO to retrieve meta data from the
    specified column.
   </para>
   <variablelist>
    <varlistentry>
     <term>stmt</term>
     <listitem>
      <para>Pointer to the statement structure initialized by SKEL_handle_preparer.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>colno</term>
     <listitem>
      <para>The column number for which data is to be retrieved.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>return_value</term>
     <listitem>
      <para>Holds the returned meta data.</para>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    The driver author should consult the documentation for this function that can be
    found in the php_pdo_driver.h header as this will be the most current. This
    function returns 1 for success or 0 in the event of failure. The database
    driver does not need to provide this function.
   </para>
  </sect3>

  <sect3 xml:id="internals2.pdo.implementing.statement.method-table">
   <title>Statement handling method table</title>
   <para>
    A static structure of type pdo_stmt_methods named SKEL_stmt_methods should
    be declared and initialized to the function pointers for each defined
    function. If a function is not supported or not implemented the value for
    that function pointer should be set to NULL.
   </para>
  </sect3>
 </sect2>
</sect1>
<!-- 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
-->