From ffc3345912c342f6328e5c323c315d14e2656a8e Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Mon, 11 Jul 2005 04:38:55 +0000 Subject: [PATCH] misc tweaks git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@190460 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/pdo/constants.xml | 21 ++++++- .../pdo/functions/PDO-beginTransaction.xml | 9 +-- reference/pdo/functions/PDO-construct.xml | 18 +++++- reference/pdo/functions/PDO-errorCode.xml | 18 ++++-- reference/pdo/functions/PDO-errorInfo.xml | 17 +++--- reference/pdo/functions/PDO-exec.xml | 8 +-- reference/pdo/functions/PDO-getAttribute.xml | 7 ++- reference/pdo/functions/PDO-lastInsertId.xml | 9 +-- reference/pdo/functions/PDO-prepare.xml | 25 ++++++--- reference/pdo/functions/PDO-query.xml | 11 ++-- reference/pdo/functions/PDO-quote.xml | 20 ++++--- reference/pdo/functions/PDO-rollBack.xml | 13 ++--- reference/pdo/functions/PDO-setAttribute.xml | 8 +-- .../pdo/functions/PDOStatement-bindColumn.xml | 56 ++++++++----------- .../pdo/functions/PDOStatement-bindParam.xml | 26 ++++----- .../pdo/functions/PDOStatement-errorCode.xml | 6 +- reference/pdo/reference.xml | 8 ++- 17 files changed, 159 insertions(+), 121 deletions(-) diff --git a/reference/pdo/constants.xml b/reference/pdo/constants.xml index 8776e35a27..073d3eb808 100644 --- a/reference/pdo/constants.xml +++ b/reference/pdo/constants.xml @@ -1,5 +1,5 @@ - +
&reftitle.constants; @@ -266,7 +266,9 @@ - + Setting the prefetch size allows you to balance speed against memory + usage for your application. Not all database/driver combinations support + setting of the prefetch size. @@ -370,6 +372,19 @@ + + + + PDO_ATTR_DRIVER_NAME + (string) + + + + Returns the name of the driver. + + + + PDO_ATTR_ORACLE_NULLS @@ -426,7 +441,7 @@ Do not raise an error or exception if an error occurs. The developer is - expected to explicitly check for errors. + expected to explicitly check for errors. This is the default mode. diff --git a/reference/pdo/functions/PDO-beginTransaction.xml b/reference/pdo/functions/PDO-beginTransaction.xml index 9ccd8b966e..a91e40295d 100644 --- a/reference/pdo/functions/PDO-beginTransaction.xml +++ b/reference/pdo/functions/PDO-beginTransaction.xml @@ -1,5 +1,5 @@ - + @@ -17,9 +17,10 @@ &warn.experimental.func; - Turns off autocommit mode. Call PDO::commit or - PDO::rollback to end the transaction and return to - autocommit mode. + Turns off autocommit mode. While autocommit mode is turned off, changes + made to the database via the PDO object instance are not committed until + you end the transaction by calling either + PDO::commit or PDO::rollback. diff --git a/reference/pdo/functions/PDO-construct.xml b/reference/pdo/functions/PDO-construct.xml index 4c3641f89a..0548c76889 100644 --- a/reference/pdo/functions/PDO-construct.xml +++ b/reference/pdo/functions/PDO-construct.xml @@ -1,5 +1,5 @@ - + PDO::__construct @@ -99,6 +99,22 @@ sqlite::memory: + + sqlite (version 2) + + sqlite2:/path/to/database + To create a database in memory, use: + sqlite2::memory: + + + The SQLite 2 PDO driver provides access to old SQLite 2 + databases that you may have created with earlier versions + of PHP. It is recommended that you migrate to SQLite 3 (the + PDO_SQLITE driver), as it has superior features and performance. + + + + diff --git a/reference/pdo/functions/PDO-errorCode.xml b/reference/pdo/functions/PDO-errorCode.xml index 4d73a2ac37..b461b5f541 100644 --- a/reference/pdo/functions/PDO-errorCode.xml +++ b/reference/pdo/functions/PDO-errorCode.xml @@ -1,5 +1,5 @@ - + @@ -21,17 +21,23 @@ &reftitle.returnvalues; - Returns a SQLSTATE, a five-character alphanumeric identifier defined in the ANSI SQL - standard. + Returns a SQLSTATE, a five-character alphanumeric identifier defined in + the ANSI SQL-92 standard. Briefly, an SQLSTATE consists of a + two-character class value followed by a three-character subclass value. A + class value of 01 indicates a warning and is accompanied by a return code + of SQL_SUCCESS_WITH_INFO. Class values other than '01', except for the + class 'IM', indicate an error. The class 'IM' is specific to warnings + and errors that derive from the implementation of PDO (or perhaps ODBC, + if you're using the ODBC driver) itself. The subclass value '000' in any + class indicates that there is no subclass for that SQLSTATE. PDO::errorCode only retrieves error codes for operations performed directly on the database handle. If you create a PDOStatement object through PDO::prepare or PDO::query and invoke an error on the statement - handle, PDO::errorCode will return - PDO_ERR_NONE. You must call - PDOStatement::errorCode to return the error + handle, PDO::errorCode will not reflect that error. + You must call PDOStatement::errorCode to return the error code for an operation performed on a particular statement handle. diff --git a/reference/pdo/functions/PDO-errorInfo.xml b/reference/pdo/functions/PDO-errorInfo.xml index 561d9769fa..15e31c11d5 100644 --- a/reference/pdo/functions/PDO-errorInfo.xml +++ b/reference/pdo/functions/PDO-errorInfo.xml @@ -1,5 +1,5 @@ - + @@ -52,15 +52,14 @@ - PDO::errorInfo only retrieves error information - for operations performed directly on the database handle. If you create - a PDOStatement object through PDO::prepare or + PDO::errorInfo only retrieves error information for + operations performed directly on the database handle. If you create a + PDOStatement object through PDO::prepare or PDO::query and invoke an error on the statement - handle, PDO::errorInfo will insert an error code - of PDO_ERR_NONE into the first element of the returned - array. You must call PDOStatement::errorInfo to - return the error information for an operation performed on a particular - statement handle. + handle, PDO::errorInfo will not reflect the error + from the statement handle. You must call + PDOStatement::errorInfo to return the error + information for an operation performed on a particular statement handle. diff --git a/reference/pdo/functions/PDO-exec.xml b/reference/pdo/functions/PDO-exec.xml index f55daefb44..f01d598b2a 100644 --- a/reference/pdo/functions/PDO-exec.xml +++ b/reference/pdo/functions/PDO-exec.xml @@ -1,5 +1,5 @@ - + @@ -18,7 +18,7 @@ &warn.experimental.func; - PDO::exec prepares and executes an SQL statement in + PDO::exec executes an SQL statement in a single function call, returning the number of rows affected by the statement. @@ -26,7 +26,7 @@ PDO::exec does not return results from a SELECT statement. For a SELECT statement that you only need to issue once during your program, consider issuing PDO::query. - For a SELECT statement that you need to issue multiple times, prepare + For a statement that you need to issue multiple times, prepare a PDOStatement object with PDO::prepare and issue the statement with PDOStatement::execute. @@ -89,7 +89,6 @@ $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2'); $count = $dbh->exec("DELETE FROM fruit WHERE colour = 'red'"); /* Return number of rows that were deleted */ -print("Return number of rows that were deleted:\n"); print("Deleted $count rows.\n"); ?> ]]> @@ -97,7 +96,6 @@ print("Deleted $count rows.\n"); &example.outputs; diff --git a/reference/pdo/functions/PDO-getAttribute.xml b/reference/pdo/functions/PDO-getAttribute.xml index 82ab1d2758..3ae075128b 100644 --- a/reference/pdo/functions/PDO-getAttribute.xml +++ b/reference/pdo/functions/PDO-getAttribute.xml @@ -1,5 +1,5 @@ - + @@ -24,8 +24,8 @@ - Note that some databases may not support all of the database connection - attributes. + Note that some database/driver combinations may not support all of the + database connection attributes. @@ -45,6 +45,7 @@ PDO_ATTR_CASE PDO_ATTR_CLIENT_VERSION PDO_ATTR_CONNECTION_STATUS + PDO_ATTR_DRIVER_NAME PDO_ATTR_ERRMODE PDO_ATTR_ORACLE_NULLS PDO_ATTR_PERSISTENT diff --git a/reference/pdo/functions/PDO-lastInsertId.xml b/reference/pdo/functions/PDO-lastInsertId.xml index 763795c6cb..605e93f0a5 100644 --- a/reference/pdo/functions/PDO-lastInsertId.xml +++ b/reference/pdo/functions/PDO-lastInsertId.xml @@ -1,5 +1,5 @@ - + @@ -19,12 +19,13 @@ Returns the ID of the last inserted row, or the last value from a - sequence object. + sequence object, depending on the underlying driver. - Due to differences between database server implementations, this method - may not always return a meaningful result. + This method may not return a meaningful/consistent result across different PDO + drivers, because the underlying database may not even support the notion + of auto-increment fields or sequences. diff --git a/reference/pdo/functions/PDO-prepare.xml b/reference/pdo/functions/PDO-prepare.xml index 2c96645d0d..6bacbc9227 100644 --- a/reference/pdo/functions/PDO-prepare.xml +++ b/reference/pdo/functions/PDO-prepare.xml @@ -1,5 +1,5 @@ - + @@ -22,14 +22,23 @@ PDOStatement::execute method. The SQL statement can contain zero or more named (:name) or question mark (?) parameter markers for which real values will be substituted when the statement is executed. - You cannot use named and question mark parameter markers within the same - SQL statement. + You cannot use both named and question mark parameter markers within the same + SQL statement; pick one or the other parameter style. - Calling PDO::prepare and PDOStatement::execute - for statements that will be issued multiple times with different parameter - values optimizes the performance of your application and helps prevent SQL - injection attacks. + Calling PDO::prepare and + PDOStatement::execute for statements that will be + issued multiple times with different parameter values optimizes the + performance of your application by allowing the driver to negotiate + client and/or server side caching of the query plan and meta information, + and helps to prevent SQL injection attacks by eliminating the need to + manually quote the parameters. + + + PDO will emulate prepared statements/bound parameters for drivers that do + not natively support them, and can also rewrite named or question mark + style parameter markers to something more appropriate, if the driver + supports one style but not the other. @@ -53,6 +62,8 @@ returns. You would most commonly use this to set the PDO_ATTR_CURSOR value to PDO_CURSOR_SCROLL to request a scrollable cursor. + Some drivers have driver specific options that may be set at + prepare-time. diff --git a/reference/pdo/functions/PDO-query.xml b/reference/pdo/functions/PDO-query.xml index ad2fb26662..01196c66ac 100644 --- a/reference/pdo/functions/PDO-query.xml +++ b/reference/pdo/functions/PDO-query.xml @@ -1,5 +1,5 @@ - + @@ -18,14 +18,15 @@ &warn.experimental.func; - PDO::query prepares and executes an SQL statement in + PDO::query executes an SQL statement in a single function call, returning the result set (if any) returned by the statement as a PDOStatement object. - For a SELECT statement that you need to issue multiple times, prepare - a PDOStatement object with PDO::prepare and issue - the statement with PDOStatement::execute. + For a query that you need to issue multiple times, you will realize better + performance if you prepare a PDOStatement object using + PDO::prepare and issue the statement with multiple + calls to PDOStatement::execute. diff --git a/reference/pdo/functions/PDO-quote.xml b/reference/pdo/functions/PDO-quote.xml index 39c7adb9d9..cd833bb760 100644 --- a/reference/pdo/functions/PDO-quote.xml +++ b/reference/pdo/functions/PDO-quote.xml @@ -1,5 +1,5 @@ - + @@ -20,14 +20,17 @@ PDO::quote places quotes around the input - string and escapes and single quotes within the input string. - Quoting input strings has been a common means of attempting to - prevent SQL injection attacks; however, an even safer approach - is to use prepared statements with named parameters or placeholders - for the input values. + string and escapes and single quotes within the input string, using a + quoting style appropriate to the underlying driver. - Not all PDO drivers implement this method. + If you're using this function to build SQL, it is recommended that you + using prepared statements and bound parameters instead, as it is not only + more convenient, but often much faster. + + + Not all PDO drivers implement this method (notably PDO_ODBC). Consider + using prepared statements instead. @@ -58,7 +61,8 @@ &reftitle.returnvalues; Returns a quoted string that is theoretically safe to pass into an - SQL statement. + SQL statement. Returns &false; if the driver does not support quoting in + this way. diff --git a/reference/pdo/functions/PDO-rollBack.xml b/reference/pdo/functions/PDO-rollBack.xml index 1207e7ae9d..3cf43c086d 100644 --- a/reference/pdo/functions/PDO-rollBack.xml +++ b/reference/pdo/functions/PDO-rollBack.xml @@ -1,5 +1,5 @@ - + @@ -18,14 +18,13 @@ &warn.experimental.func; - When issued against databases that support transactions, - PDO::rollBack rolls back any work in progress - and returns the connection state to autocommit mode. + Rolls back the current transaction, as initiated by + PDO::beginTransaction. It is an error to call this + method if no transaction is active. - You must issue PDO::beginTransaction to set the - connection state to manual commit mode before issuing - PDO::rollBack has any effect. + If the database was set to autocommit mode, this function will restore + autocommit mode after it has rolled back the transaction. diff --git a/reference/pdo/functions/PDO-setAttribute.xml b/reference/pdo/functions/PDO-setAttribute.xml index 2c38ec9c95..8ee441c67e 100644 --- a/reference/pdo/functions/PDO-setAttribute.xml +++ b/reference/pdo/functions/PDO-setAttribute.xml @@ -1,5 +1,5 @@ - + @@ -18,8 +18,9 @@ &warn.experimental.func; - Sets a database connection attribute. The generic PDO connection attributes - include: + Sets an attribute on the database handle. Some of the available generic + attributes are listed below; some drivers may make use of + additional driver specific attributes. PDO_ATTR_CASE: Force column names to a specific case. @@ -37,7 +38,6 @@ - PDO drivers may define further driver-specific attributes. diff --git a/reference/pdo/functions/PDOStatement-bindColumn.xml b/reference/pdo/functions/PDOStatement-bindColumn.xml index 0fe842fd69..f11fba2799 100644 --- a/reference/pdo/functions/PDOStatement-bindColumn.xml +++ b/reference/pdo/functions/PDOStatement-bindColumn.xml @@ -1,5 +1,5 @@ - + @@ -15,19 +15,23 @@ mixedcolumn mixedparam inttype - intmaxlen - mixeddriver_options &warn.experimental.func; - On each row fetch param will contain the value of - the corresponding column. column is the 1-based - offset of the column, or the column name. For maximum portability, do not - call this function before calling - PDOStatement::execute. + PDOStatement::bindColumn arranges to have a + particular variable bound to a given column in the result-set from a + query. Each call to PDOStatement::fetch or + PDOStatement::fetchAll will update all the variables + that are bound to columns. - + + + Since information about the columns is not always available to PDO until + the statement is executed, portable applications should call this + function after PDO::execute. + + @@ -38,7 +42,9 @@ column - Number of the column (1-indexed) in the result set. + Number of the column (1-indexed) or name of the column in the result set. + If using the column name, be aware that the name should match the + case of the column, as returned by the driver. @@ -58,23 +64,7 @@ - - maxlen - - - Maximum length of the parameter. - - - - - driver_options - - - - - - - + @@ -99,14 +89,12 @@ function readData($dbh) { $stmt = $dbh->prepare($sql); $stmt->execute(); - /* Bind by column number with an explicit data type & length */ - $stmt->bindColumn(1, $name, PDO_PARAM_STR, 64); - - /* Bind by column number with default data type & length */ + /* Bind by column number */ + $stmt->bindColumn(1, $name); $stmt->bindColumn(2, $colour); - - /* Bind by column name with default data type & length */ - $stmt->bindColumn('CALORIES', $cals); + + /* Bind by column name */ + $stmt->bindColumn('calories', $cals); while ($row = $stmt->fetch(PDO_FETCH_BOUND)) { $data = $name . "\t" . $colour . "\t" . $cals . "\n"; diff --git a/reference/pdo/functions/PDOStatement-bindParam.xml b/reference/pdo/functions/PDOStatement-bindParam.xml index 24c79fc1d8..0087dbe71f 100644 --- a/reference/pdo/functions/PDOStatement-bindParam.xml +++ b/reference/pdo/functions/PDOStatement-bindParam.xml @@ -1,5 +1,5 @@ - + @@ -20,18 +20,15 @@ &warn.experimental.func; - Binds an SQL statement parameter to the specified variable name. The SQL statement - parameter can either be a named placeholder or a question mark placeholder. + Binds a parameter to a corresponding named or question mark placeholder + in the SQL statement that was use to prepare the statement. - Output parameters will set the value of the bound PHP variable to the value - returned by the database when the SQL statement is executed. This enables you - to call stored procedures with output or input/output parameters, for example, - for databases that support such features. - - - For non-NULL input-only variables, you can pass an array of input values to - PDOStatement::execute instead. + Most parameters are input parameters, that is, parameters that are used + in a read-only fashion to build up the query. Some drivers support the + invocation of stored procedures that return data as output parameters, + and some also as intput/output parameters that both send in data and are + updated to receive it. @@ -69,10 +66,6 @@ use the bitwise OR operator to set the PDO_PARAM_INPUT_OUTPUT bits for the data_type parameter. - - To pass a NULL value as an input parameter, declare the - PDO_PARAM_NULL constant. - @@ -135,6 +128,7 @@ $sth->execute(); + Call a stored procedure with an INOUT parameter - + @@ -20,8 +20,8 @@ &reftitle.returnvalues; - Returns a SQLSTATE, a five-character alphanumeric identifier defined in the ANSI SQL - standard. PDOStatement::errorCode only retrieves error codes + Identical to PDO::errorCode, except that + PDOStatement::errorCode only retrieves error codes for operations performed with PDOStatement objects. diff --git a/reference/pdo/reference.xml b/reference/pdo/reference.xml index 45b168d834..f717588fe8 100644 --- a/reference/pdo/reference.xml +++ b/reference/pdo/reference.xml @@ -1,5 +1,5 @@ - + PDO Functions @@ -190,7 +190,7 @@ bash# echo extension=pdo.so >> /usr/local/php5/lib/php.ini PDO_ODBC - ODBC v3 (IBM DB2 and unixODBC) + ODBC v3 (IBM DB2, unixODBC and win32 ODBC) PDO_PGSQL @@ -200,6 +200,10 @@ bash# echo extension=pdo.so >> /usr/local/php5/lib/php.ini PDO_SQLITE SQLite 3.x + + sqlite + SQLite 2.x (PHP 5.1 and up) +