internals2.pdo.implementing.html

来自「php的帮助文档,涉及到PHP的案例和基本语法,以及实际应用内容」· HTML 代码 · 共 1,696 行 · 第 1/4 页

    </dt>

   </dl>

   <p class="para">
    This function is essentially the constructor for a stmt object. This
    function is responsible for processing statement options, and setting
    driver-specific option fields in the pdo_stmt_t structure.
   </p>
   <p class="para">
    PDO does not process any statement options on the driver&#039;s
    behalf before calling the preparer function.  It is your responsibility to
    process them before you return, raising an error for any unknown options that
    are passed.
   </p>
   <p class="para">
    One very important responsibility of this function is the processing of SQL
    statement parameters. At the time of this call, PDO does not know if your
    driver supports binding parameters into prepared statements, nor does it
    know if it supports named or positional parameter naming conventions.
   </p>
   <p class="para">
    Your driver is responsible for setting
    <i>stmt-&gt;supports_placeholders</i> 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&#039;t directly support
    both named and positional parameter conventions, you should use the
    <b>pdo_parse_params()</b> API to have PDO rewrite the query to
    take advantage of the support provided by your database.
   </p>
   <div class="example" id="internals2.pdo.implementing.preparer.ex-parse-params" name="internals2.pdo.implementing.preparer.ex-parse-params">
    <p><b>Example #2 Using pdo_parse_params</b></p>
    <div class="example-contents"><div class="cdata"><pre>
    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-&gt;supports_placeholders = PDO_PLACEHOLDER_POSITIONAL;
    ret = pdo_parse_params(stmt, (char*)sql, sql_len, &amp;nsql, &amp;nsql_len TSRMLS_CC);

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

    /* now proceed to prepare the query in &quot;sql&quot; */
</pre></div></div>

   </div>
   <p class="para">
    Possible values for <i>supports_placeholders</i> are:
    <b><tt>PDO_PLACEHOLDER_NAMED</tt></b>,
    <b><tt>PDO_PLACEHOLDER_POSITIONAL</tt></b> and
    <b><tt>PDO_PLACEHOLDER_NONE</tt></b>.  If the driver doesn&#039;t support prepare statements at all, then this function should simply allocate any state that it might need, and then return:
   </p>
   <div class="example" id="internals2.pdo.implementing.preparer.ex-no-native-prep" name="internals2.pdo.implementing.preparer.ex-no-native-prep">
    <p><b>Example #3 Implementing preparer for drivers that don&#039;t support native prepared statements</b></p>
    <div class="example-contents"><div class="cdata"><pre>
static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql,
    long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC)
{
    pdo_SKEL_db_handle *H = (pdo_SKEL_db_handle *)dbh-&gt;driver_data;
    pdo_SKEL_stmt *S = ecalloc(1, sizeof(pdo_SKEL_stmt));

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

    return 1;
}
</pre></div></div>

   </div>

   <p class="para">This function returns 1 on success or 0 on failure.</p>
  </div>
  <div id="internals2.pdo.implementing.driver.handle-doer" class="sect3">
  <h4 class="title">SKEL_handle_doer</h4>
   <pre class="synopsis"><div class="cdata"><pre>static long SKEL_handle_doer(pdo_dbh_t *dbh, const char *sql, long sql_len TSRMLS_DC)</pre></div></pre>

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

   <dl>

    <dt>

     <span class="term">dbh</span>

     <dd>

      <p class="para">Pointer to the database handle initialized by the handle factory</p>
     </dd>

    </dt>

    <dt>

     <span class="term">sql</span>

     <dd>

      <p class="para">Pointer to a character string containing the SQL statement to be prepared.</p>
     </dd>

    </dt>

    <dt>

     <span class="term">sql_len</span>

     <dd>

      <p class="para">The length of the SQL statement.</p>
     </dd>

    </dt>

   </dl>


   <p class="para">
    This function returns 1 on success or 0 on failure.
   </p>

  </div>
  <div id="internals2.pdo.implementing.driver.handle-quoter" class="sect3">
   <h4 class="title">SKEL_handle_quoter</h4>
   <pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_quoter(pdo_dbh_t *dbh, const char *unquoted,
  int unquoted_len, char **quoted, int quoted_len, enum pdo_param_type param_type TSRMLS_DC)</pre></div></pre>

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

   <dl>

    <dt>

     <span class="term">dbh</span>

     <dd>

      <p class="para">Pointer to the database handle initialized by the handle factory</p>
     </dd>

    </dt>

    <dt>

     <span class="term">unquoted</span>

     <dd>

      <p class="para">Pointer to a character string containing the string to be quoted.</p>
     </dd>

    </dt>

    <dt>

     <span class="term">unquoted_len</span>

     <dd>

      <p class="para">The length of the string to be quoted.</p>
     </dd>

    </dt>

    <dt>

     <span class="term">quoted</span>

     <dd>

      <p class="para">Pointer to the address where a pointer to the newly quoted string will be returned.</p>
     </dd>

    </dt>

    <dt>

     <span class="term">quoted_len</span>

     <dd>

      <p class="para">The length of the new string.</p>
     </dd>

    </dt>

    <dt>

     <span class="term">param_type</span>

     <dd>

      <p class="para">A driver specific hint for driver that have alternate quoting styles</p>
     </dd>

    </dt>

   </dl>

   <p class="para">
    This function is called in response to a call to
    <a href="pdo.quote.html" class="function">PDO::quote()</a> or when the driver has set
    <i>supports_placeholder</i> to
    <b><tt>PDO_PLACEHOLDER_NONE</tt></b>. The purpose is to quote a
    parameter when building SQL statements.
   </p>
   <p class="para">
    If your driver does not support native prepared statements, implementation
    of this function is required.
   </p>
   <p class="para">
    This function returns 1 if the quoting process reformatted the string, and
    0 if it was not necessary to change the string. The original string will be
    used unchanged with a 0 return.
   </p>
  </div>
  <div id="internals2.pdo.implementing.driver.handle-begin" class="sect3">
   <h4 class="title">SKEL_handle_begin</h4>
   <pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_begin(pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>

   <p class="para">
    This function will be called by PDO to begin a database transaction.
   </p>
   <dl>

    <dt>

     <span class="term">dbh</span>

     <dd>

      <p class="para">Pointer to the database handle initialized by the handle factory</p>
     </dd>

    </dt>

   </dl>

   <p class="para">
    This should do whatever database specific activity that needs to be
    accomplished to begin a transaction. This function returns 1 for success or
    0 if an error occurred.
   </p>
  </div>
  <div id="internals2.pdo.implementing.driver.handle-commit" class="sect3">
   <h4 class="title">SKEL_handle_commit</h4>
   <pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_commit(pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>
   <p class="para">
    This function will be called by PDO to end a database
    transaction.
   </p>

   <dl>

    <dt>

     <span class="term">dbh</span>

     <dd>

      <p class="para">Pointer to the database handle initialized by the handle factory</p>
     </dd>

    </dt>

   </dl>


   <p class="para">
    This should do whatever database specific activity that needs to be
    accomplished to commit a transaction. This function returns 1 for success or 0 if an error occurred.
   </p>
  </div>
  <div id="internals2.pdo.implementing.driver.handle-rollback" class="sect3">
   <h4 class="title">SKEL_handle_rollback</h4>
   <pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_rollback( pdo_dbh_t *dbh TSRMLS_DC)</pre></div></pre>
   <p class="para">This function will be called by PDO to rollback a database transaction.</p>
   <dl>

    <dt>

     <span class="term">dbh</span>

     <dd>

      <p class="para">Pointer to the database handle initialized by the handle factory</p>
     </dd>

    </dt>

   </dl>

   <p class="para">
    This should do whatever database specific activity that needs to be
    accomplished to rollback a transaction. This function returns 1 for
    success or 0 if an error occurred.
   </p>
  </div>
  <div id="internals2.pdo.implementing.driver.get-attr" class="sect3">
   <h4 class="title">SKEL_handle_get_attribute</h4>
   <pre class="synopsis"><div class="cdata"><pre>static int SKEL_handle_get_attribute(pdo_dbh_t *dbh, long attr, zval *return_value TSRMLS_DC)</pre></div></pre>
   <p class="para">This function will be called by PDO to retrieve a database attribute.</p>

   <dl>

    <dt>

     <span class="term">dbh</span>

     <dd>

      <p class="para">Pointer to the database handle initialized by the handle factory</p>
     </dd>

    </dt>

    <dt>

     <span class="term">attr</span>

     <dd>

      <p class="para">
       <span class="type long">long</span> value of one of the PDO_ATTR_xxxx types.  See <a href="internals2.pdo.constants.html" class="xref">Constants</a> for valid attributes.
      </p>
     </dd>

    </dt>

    <dt>

     <span class="term">return_value</span>

     <dd>

      <p class="para">The returned value for the attribute.</p>
     </dd>

    </dt>

   </dl>

   <p class="para">
    It is up to the driver to decide which attributes will be supported for a
    particular implementation. It is not necessary for a driver to supply this
    function. PDO driver handles the PDO_ATTR_PERSISTENT, PDO_ATTR_CASE,
    PDO_ATTR_ORACLE_NULLS, and PDO_ATTR_ERRMODE attributes directly. 
   </p>
   <p class="para">
    This function returns 1 on success or 0 on failure.
   </p>
  </div>
  <div id="internals2.pdo.implementing.driver.set-attr" class="sect3">
   <h4 class="title">SKEL_handle_set_attribute</h4>
   <pre class="synopsis">static int SKEL_handle_set_attribute(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC)</pre>
   <p class="para">
    This function will be called by PDO to set a database attribute, usually in
    response to a script calling <a href="pdo.setattribute.html" class="function">PDO::setAttribute()</a>.
   </p>
   <dl>

    <dt>

     <span class="term">dbh</span>

     <dd>

      <p class="para">Pointer to the database handle initialized by the handle factory</p>
     </dd>

    </dt>

    <dt>

     <span class="term">attr</span>

     <dd>

      <p class="para">
       <span class="type long">long</span> value of one of the PDO_ATTR_xxxx types.  See <a href="internals2.pdo.constants.html" class="xref">Constants</a> for valid attributes.
      </p>
     </dd>

    </dt>

    <dt>

     <span class="term">val</span>

     <dd>

      <p class="para">The new value for the attribute.</p>
     </dd>

    </dt>

   </dl>


   <p class="para">
    It is up to the driver to decide which attributes will be supported for a
    particular implementation. It is not necessary for a driver to provide this
    function if it does not need to support additional attributes. The PDO
    driver handles the PDO_ATTR_CASE, PDO_ATTR_ORACLE_NULLS, and
    PDO_ATTR_ERRMODE attributes directly. 
   </p>