mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-29 07:18:55 +00:00
cf05ac7d25
Hopefully fix most whitespace issues. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@197512 c90b9560-bf6c-de11-be94-00142212c4b1
205 lines
8.2 KiB
XML
205 lines
8.2 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.1 $ -->
|
|
<sect1 id="internals.pdo.pdo-dbh-t">
|
|
<title>pdo_dbh_t definition</title>
|
|
<para>
|
|
All fields should be treated as read-only by the driver, unless explicitly
|
|
stated otherwise.
|
|
</para>
|
|
<figure>
|
|
<title>pdo_dbh_t</title>
|
|
<programlisting role="c">
|
|
/* represents a connection to a database */
|
|
struct _pdo_dbh_t {
|
|
/* driver specific methods */
|
|
struct pdo_dbh_methods *methods; <co id="internals.pdo.dbh.co.methods" linkends="internals.pdo.dbh.co.methods-co"/>
|
|
/* driver specific data */
|
|
void *driver_data; <co id="internals.pdo.dbh.co.driver-data" linkends="internals.pdo.dbh.co.driver-data-co"/>
|
|
|
|
/* credentials */
|
|
char *username, *password; <co
|
|
id="internals.pdo.dbh.co.credentials"
|
|
linkends="internals.pdo.dbh.co.credentials-co"/>
|
|
|
|
/* if true, then data stored and pointed at by this handle must all be
|
|
* persistently allocated */
|
|
unsigned is_persistent:1; <co
|
|
id="internals.pdo.dbh.co.is-persist"
|
|
linkends="internals.pdo.dbh.co.is-persist-co"/>
|
|
|
|
/* if true, driver should act as though a COMMIT were executed between
|
|
* each executed statement; otherwise, COMMIT must be carried out manually
|
|
* */
|
|
unsigned auto_commit:1; <co
|
|
id="internals.pdo.dbh.co.auto-commit"
|
|
linkends="internals.pdo.dbh.co.auto-commit-co"/>
|
|
|
|
/* if true, the driver requires that memory be allocated explicitly for
|
|
* the columns that are returned */
|
|
unsigned alloc_own_columns:1; <co
|
|
id="internals.pdo.dbh.co.alloc-own"
|
|
linkends="internals.pdo.dbh.co.alloc-own-co"/>
|
|
|
|
/* if true, commit or rollBack is allowed to be called */
|
|
unsigned in_txn:1;
|
|
|
|
/* max length a single character can become after correct quoting */
|
|
unsigned max_escaped_char_length:3; <co
|
|
id="internals.pdo.dbh.co.max-esc"
|
|
linkends="internals.pdo.dbh.co.max-esc-co"/>
|
|
|
|
/* data source string used to open this handle */
|
|
const char *data_source; <co id="internals.pdo.dbh.co.dsn"
|
|
linkends="internals.pdo.dbh.co.dsn-co"/>
|
|
unsigned long data_source_len;
|
|
|
|
/* the global error code. */
|
|
pdo_error_type error_code; <co
|
|
id="internals.pdo.dbh.co.error-code"
|
|
linkends="internals.pdo.dbh.co.error-code-co"/>
|
|
|
|
enum pdo_case_conversion native_case<co id="internals.pdo.dbh.co-ncase"
|
|
linkends="internals.pdo.dbh.co-ncase-co"/>, desired_case;
|
|
};
|
|
</programlisting>
|
|
</figure>
|
|
<calloutlist>
|
|
<callout arearefs="internals.pdo.dbh.co.methods"
|
|
id="internals.pdo.dbh.co.methods-co">
|
|
<para>
|
|
The driver <emphasis>must</emphasis> set this during
|
|
<function>SKEL_handle_factory</function>.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.driver-data"
|
|
id="internals.pdo.dbh.co.driver-data-co">
|
|
<para>
|
|
This item is for use by the driver; the intended usage is to store a
|
|
pointer (during <function>SKEL_handle_factory</function>)
|
|
to whatever instance data is required to maintain a connection to
|
|
the database.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.credentials"
|
|
id="internals.pdo.dbh.co.credentials-co">
|
|
<para>
|
|
The username and password that were passed into the PDO constructor.
|
|
The driver should use these values when it initiates a connection to the
|
|
database.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.is-persist"
|
|
id="internals.pdo.dbh.co.is-persist-co">
|
|
<para>
|
|
If this is set to 1, then any data that is referenced by the
|
|
dbh, including whatever structure your driver allocates,
|
|
<emphasis>MUST</emphasis> be allocated persistently. This is easy to
|
|
achieve; rather than using the usual <function>emalloc</function> simply
|
|
use <function>pemalloc</function> and pass the value of this flag as the
|
|
last parameter. Failure to use the appropriate kind of memory can lead
|
|
to serious memory faults, resulting (in the best case) a hard crash, and
|
|
in the worst case, an exploitable memory problem.
|
|
</para>
|
|
<para>
|
|
If, for whatever reason, your driver is not suitable to run persistently,
|
|
you <emphasis>MUST</emphasis> check this flag in your
|
|
<function>SKEL_handle_factory</function> and raise an appropriate error.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.auto-commit"
|
|
id="internals.pdo.dbh.co.auto-commit-co">
|
|
<para>
|
|
You should check this value in your <function>SKEL_handle_doer</function>
|
|
and <function>SKEL_stmt_execute</function> functions; if it evaluates to
|
|
true, you must attempt to commit the query now. Most database
|
|
implementations offer an auto-commit mode that handles this automatically.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.alloc-own"
|
|
id="internals.pdo.dbh.co.alloc-own-co">
|
|
<para>
|
|
If your database client library API operates by fetching data into a
|
|
caller-supplied buffer, you should set this flag to 1 during your
|
|
<function>SKEL_handle_factory</function>. When set, PDO will call your
|
|
<function>SKEL_stmt_describer</function> earlier that it would
|
|
otherwise. This early call allows you to determine those buffer sizes
|
|
and issue appropriate calls to the database client library.
|
|
</para>
|
|
<para>
|
|
If your database client library API simply returns pointers to its own
|
|
internal buffers for you to copy after each fetch call, you should leave
|
|
this value set to 0.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.max-esc"
|
|
id="internals.pdo.dbh.co.max-esc-co">
|
|
<para>
|
|
If your driver doesn't support native prepared statements
|
|
(<parameter>supports_placeholders</parameter> is set to
|
|
<constant>PDO_PLACEHOLDER_NONE</constant>), you must set
|
|
this value to the maximum length that can be taken up by a single
|
|
character when it is quoted by your
|
|
<function>SKEL_handle_quoter</function> function. This value is used to
|
|
calculate the amount of buffer space required when PDO it executes the
|
|
statement.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.dsn"
|
|
id="internals.pdo.dbh.co.dsn-co">
|
|
<para>
|
|
This holds the value of the DSN that was passed into the PDO
|
|
constructor. If your driver implementation needed to modify the DSN for
|
|
whatever reason, it should update this member during
|
|
<function>SKEL_handle_factory</function>. Modifying this member should
|
|
be avoided. If you do change it, you must ensure that
|
|
<parameter>data_source_len</parameter> is also correct.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co.error-code"
|
|
id="internals.pdo.dbh.co.error-code-co">
|
|
<para>
|
|
Whenever an error occurs during a call to one of your driver methods,
|
|
you should set this member to the SQLSTATE code that best describes the
|
|
error and return an error. In this HOW-TO, the suggested practice is to
|
|
call <function>SKEL_handle_error</function> when an error is detected,
|
|
and have it set the error code.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.dbh.co-ncase"
|
|
id="internals.pdo.dbh.co-ncase-co">
|
|
<para>
|
|
Your driver should set this during
|
|
<function>SKEL_handle_factory</function>; the value should reflect how
|
|
the database returns the names of the columns in result sets. If the
|
|
name matches the case that was used in the query, set it to
|
|
<constant>PDO_CASE_NATURAL</constant> (this is actually the default).
|
|
If the column names are always returned in upper case, set it to
|
|
<constant>PDO_CASE_UPPER</constant>. If the column names are always
|
|
return in lower case, set it to <constant>PDO_CASE_LOWER</constant>.
|
|
The value you set it used to determine if PDO should perform case
|
|
folding when the user sets the <constant>PDO_ATTR_CASE</constant>
|
|
attribute.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</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
|
|
-->
|