From 249a4edf11e2fffd5f8c98a92b1924a8564c8d30 Mon Sep 17 00:00:00 2001 From: Gwynne Raskind Date: Wed, 6 Jun 2007 05:20:48 +0000 Subject: [PATCH] - Fixed several spelling and grammatical errors in the PDO documentation. - Removed displayed author information from the PDO documentation front page. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@237076 c90b9560-bf6c-de11-be94-00142212c4b1 --- internals/pdo/building.xml | 16 ++++++------ internals/pdo/error-handling.xml | 14 +++++------ internals/pdo/implementing.xml | 27 ++++++++++---------- internals/pdo/index.xml | 43 +------------------------------- internals/pdo/intro.xml | 9 ++++++- internals/pdo/pdo-dbh-t.xml | 10 ++++---- internals/pdo/pdo-stmt-t.xml | 12 ++++----- internals/pdo/preparation.xml | 3 ++- internals/pdo/prerequisites.xml | 10 ++++---- 9 files changed, 56 insertions(+), 88 deletions(-) diff --git a/internals/pdo/building.xml b/internals/pdo/building.xml index 702043265f..ce35806eeb 100644 --- a/internals/pdo/building.xml +++ b/internals/pdo/building.xml @@ -1,18 +1,18 @@ - + Building The build process is designed to work with PEAR (see 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 a build 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: + 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 is a build 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: diff --git a/internals/pdo/error-handling.xml b/internals/pdo/error-handling.xml index 582f7f4a30..eaea5228cb 100644 --- a/internals/pdo/error-handling.xml +++ b/internals/pdo/error-handling.xml @@ -1,16 +1,16 @@ - + Error handling Error handling is implemented using a hand-shaking protocol between PDO and the database driver code. The database driver code - signals PDO than an error has occurred via a failure + signals PDO that 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. + is returned, set 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. @@ -39,7 +39,7 @@ - A descriptive string. This string can contain anything additional + A descriptive string. This string can contain any 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 diff --git a/internals/pdo/implementing.xml b/internals/pdo/implementing.xml index 5f58d31ed1..c92c6dc45c 100644 --- a/internals/pdo/implementing.xml +++ b/internals/pdo/implementing.xml @@ -1,5 +1,5 @@ - + Fleshing out your skeleton @@ -207,7 +207,7 @@ PHP_MSHUTDOWN_FUNCTION(pdo_SKEL) Despite being documented here, the PDO driver interface does not specify - that his function be present; it is merely a convenient way to handle + 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. @@ -354,14 +354,14 @@ long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC)]]> One very important responsibility of this function is the processing of SQL - statement parameters. At the time of this call, PDO does not if your driver - supports binding parameters into prepared statements, nor does it know if - it supports named or positional parameter naming conventions. + 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. Your driver is responsible for setting stmt->supports_placeholders as appropriate for the - underlying database. This may involved some run-time determination on 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 @@ -399,7 +399,7 @@ long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC)]]> PDO_PLACEHOLDER_NONE. 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: - implementing preparer for drivers that don't support native prepared statements + Implementing preparer for drivers that don't support native prepared statements 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. + 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. @@ -1047,8 +1048,8 @@ static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql, PDOStatement::fetch calls. - If this is a bound parameter, the is_param flag in the param structure, - otherwise, the param structure refers to a bound column. + 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. This function returns 1 for success or 0 in the event of failure. @@ -1227,7 +1228,7 @@ static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql, - This function will be called by PDO to retrieve meta-data from the + This function will be called by PDO to retrieve meta data from the specified column. diff --git a/internals/pdo/index.xml b/internals/pdo/index.xml index 095daf28a8..a1b45bc485 100644 --- a/internals/pdo/index.xml +++ b/internals/pdo/index.xml @@ -1,5 +1,5 @@ - + - - - Bill - Abt - - IBM - - - - Rick - McGuire - - IBM - - - - Wez - Furlong - - OmniTI - - - - 2005 - IBM Corporation - - - 2005 - the PHP Documentation Group - - - - 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 layer. - 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 PDO. - The learning curve is steep; expect to spend a lot of time on the - prerequisites. - - - PDO Driver How-To &internals.pdo.intro; diff --git a/internals/pdo/intro.xml b/internals/pdo/intro.xml index 082b44803b..787940faaa 100644 --- a/internals/pdo/intro.xml +++ b/internals/pdo/intro.xml @@ -1,5 +1,5 @@ - + A brief note about this How-To @@ -8,6 +8,13 @@ to assist in the development of drivers for more databases and to encourage the emerging standard for database access in PHP. + + + 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 PDO. + The learning curve is steep; expect to spend a lot of time on the + prerequisites. + + pdo_dbh_t definition @@ -121,7 +121,7 @@ struct _pdo_dbh_t { If your database client library API operates by fetching data into a caller-supplied buffer, you should set this flag to 1 during your SKEL_handle_factory. When set, PDO will call your - SKEL_stmt_describer earlier that it would + SKEL_stmt_describer earlier than it would otherwise. This early call allows you to determine those buffer sizes and issue appropriate calls to the database client library. @@ -140,7 +140,7 @@ struct _pdo_dbh_t { this value to the maximum length that can be taken up by a single character when it is quoted by your SKEL_handle_quoter function. This value is used to - calculate the amount of buffer space required when PDO it executes the + calculate the amount of buffer space required when PDO executes the statement. @@ -175,8 +175,8 @@ struct _pdo_dbh_t { PDO_CASE_NATURAL (this is actually the default). If the column names are always returned in upper case, set it to PDO_CASE_UPPER. If the column names are always - return in lower case, set it to PDO_CASE_LOWER. - The value you set it used to determine if PDO should perform case + returned in lower case, set it to PDO_CASE_LOWER. + The value you set is used to determine if PDO should perform case folding when the user sets the PDO_ATTR_CASE attribute. diff --git a/internals/pdo/pdo-stmt-t.xml b/internals/pdo/pdo-stmt-t.xml index f76700da1e..9749c0b46c 100644 --- a/internals/pdo/pdo-stmt-t.xml +++ b/internals/pdo/pdo-stmt-t.xml @@ -1,5 +1,5 @@ - + pdo_stmt_t definition @@ -98,7 +98,7 @@ struct _pdo_stmt_t { - Discussed in more detail in + Discussed in more detail in . SKEL_stmt_execute but with some database implementations, the column count may not be available until SKEL_stmt_fetch has been called at least once. - Drivers that SKEL_stmt_next_rowset should update the - column count when a new rowset is available. + Drivers that implement SKEL_stmt_next_rowset should + update the column count when a new rowset is available. name, namelen and param_type members for each column. The name is expected to be allocated using - emalloc; PDO will efree at the - appropriate time. + emalloc; PDO will call efree at + the appropriate time. diff --git a/internals/pdo/preparation.xml b/internals/pdo/preparation.xml index f55649ab42..c8330250e7 100644 --- a/internals/pdo/preparation.xml +++ b/internals/pdo/preparation.xml @@ -1,5 +1,5 @@ - + Preparation and Housekeeping @@ -23,6 +23,7 @@ pdo_SKEL/ php_pdo_SKEL_int.h SKEL_dbh.c SKEL_stmt.c + tests/ diff --git a/internals/pdo/prerequisites.xml b/internals/pdo/prerequisites.xml index 75352b60d1..7b4651d922 100644 --- a/internals/pdo/prerequisites.xml +++ b/internals/pdo/prerequisites.xml @@ -1,5 +1,5 @@ - + Prerequisites @@ -16,15 +16,15 @@ A working development environment: + + Linux: standard development tools, gcc, ld, make, autoconf, automake, etc., versions dependent on distribution; + Other Unix: standard development tools supplied by vendor plus the GNU development tool set; Win32: Visual Studio compiler suite; - - Linux: standard development tools, gcc, ld, make, autoconf, automake, etc., versions dependent on distribution; - @@ -34,7 +34,7 @@ A working PDO environment (can be installed using 'sudo pecl install PDO'), including the headers which will be needed to access the PDO type definitions and function declarations; - A good working knowledge of the 'C' programming language; + A good working knowledge of the C programming language; A good working knowledge of the way to write a PHP extension;