diff --git a/reference/pgsql/functions/pg-close.xml b/reference/pgsql/functions/pg-close.xml index 25cb040b9c..ad651f4d3a 100644 --- a/reference/pgsql/functions/pg-close.xml +++ b/reference/pgsql/functions/pg-close.xml @@ -1,5 +1,5 @@ - + @@ -53,7 +53,7 @@ &reftitle.returnvalues; - &true; on success, &false; on failure. + &return.success; diff --git a/reference/pgsql/functions/pg-connection-status.xml b/reference/pgsql/functions/pg-connection-status.xml index 41f86f75b3..66827be455 100644 --- a/reference/pgsql/functions/pg-connection-status.xml +++ b/reference/pgsql/functions/pg-connection-status.xml @@ -1,5 +1,5 @@ - + @@ -17,8 +17,8 @@ pg_connection_status returns a connection status. - Possible statuses are PGSQL_CONNECTION_OK and - PGSQL_CONNECTION_BAD. The return value 0 as + Possible statuses are PGSQL_CONNECTION_OK and + PGSQL_CONNECTION_BAD. The return value 0 as integer indicates a valid connection. diff --git a/reference/pgsql/functions/pg-fetch-all.xml b/reference/pgsql/functions/pg-fetch-all.xml index b13d3beabf..cc8a844296 100644 --- a/reference/pgsql/functions/pg-fetch-all.xml +++ b/reference/pgsql/functions/pg-fetch-all.xml @@ -1,5 +1,5 @@ - + @@ -15,12 +15,41 @@ pg_fetch_all returns an array that - contains all rows (tuples/records) in result resource. It returns - &false;, if there are no rows. + contains all rows (records) in the result resource. &database.fetch-null; + + &reftitle.parameters; + + + + result + + + PostgreSQL query result resource, returned by pg_query, + pg_query_params or pg_execute + (among others). + + + + + + + + + &reftitle.returnvalues; + + An array with all rows in the result. Each row is an array + of field values indexed by field name. + + + &false; is returned if there are no rows in the result, or on any + other error. + + + &reftitle.examples; diff --git a/reference/pgsql/functions/pg-fetch-array.xml b/reference/pgsql/functions/pg-fetch-array.xml index 9a69eee850..44d0468e3b 100644 --- a/reference/pgsql/functions/pg-fetch-array.xml +++ b/reference/pgsql/functions/pg-fetch-array.xml @@ -1,5 +1,5 @@ - + @@ -17,52 +17,92 @@ pg_fetch_array returns an array that - corresponds to the fetched row (tuples/records). It returns - &false;, if there are no more rows. + corresponds to the fetched row (record). pg_fetch_array is an extended version of pg_fetch_row. In addition to storing the - data in the numeric indices (field index) to the result array, it - also stores the data in associative indices (field name) by - default. + data in the numeric indices (field number) to the result array, it + can also store the data using associative indices (field name). + It stores both indicies by default. &database.fetch-null; - - row is row (record) number to be - retrieved. First row is 0. - - - result_type is an optional parameter that controls - how the return value is initialized. - result_type is a constant and can take the - following values: PGSQL_ASSOC, - PGSQL_NUM, and PGSQL_BOTH. - Using PGSQL_NUM, pg_fetch_array - will return an array with numerical indices, using - PGSQL_ASSOC will return only associative indices - while PGSQL_BOTH, the default, will return both - numerical and associative indices. - - - result_type was added in PHP 4.0. - - - pg_fetch_array is NOT significantly - slower than using pg_fetch_row, while it - provides a significant ease of use. + slower than using pg_fetch_row, and + is significantly easier to use. - From 4.1.0, row became optional. - Calling pg_fetch_array will increment - the internal row counter by one. + row became optional in PHP 4.1.0. + + + + + result_type was added in PHP 4.0.0. + + &reftitle.parameters; + + + + result + + + PostgreSQL query result resource, returned by pg_query, + pg_query_params or pg_execute + (among others). + + + + + row + + + Row number in result to fetch. Rows are numbered from 0 upwards. If omitted, + next row is fetched. + + + + + result_type + + + An optional parameter that controls + how the returned array is indexed. + result_type is a constant and can take the + following values: PGSQL_ASSOC, + PGSQL_NUM and PGSQL_BOTH. + Using PGSQL_NUM, pg_fetch_array + will return an array with numerical indices, using + PGSQL_ASSOC it will return only associative indices + while PGSQL_BOTH, the default, will return both + numerical and associative indices. + + + + + + + + + &reftitle.returnvalues; + + An array indexed numerically (beginning with 0) or + associatively (indexed by field name), or both. + Each value in the array is represented as a + string. Database NULL + values are returned as &null;. + + + &false; is returned if row exceeds the number + of rows in the set, there are no more rows, or on any other error. + + + &reftitle.examples; diff --git a/reference/pgsql/functions/pg-fetch-assoc.xml b/reference/pgsql/functions/pg-fetch-assoc.xml index 62a17f5168..59d71e907e 100644 --- a/reference/pgsql/functions/pg-fetch-assoc.xml +++ b/reference/pgsql/functions/pg-fetch-assoc.xml @@ -1,5 +1,5 @@ - + @@ -16,35 +16,69 @@ pg_fetch_assoc returns an associative array that - corresponds to the fetched row (tuples/records). It returns - &false;, if there are no more rows. + corresponds to the fetched row (records). pg_fetch_assoc is equivalent to calling - pg_fetch_array with PGSQL_ASSOC for the + pg_fetch_array with PGSQL_ASSOC as the optional third parameter. It only returns an associative array. If you need the numeric indices, use pg_fetch_row. &database.fetch-null; - - row is row (record) number to be - retrieved. First row is 0. - pg_fetch_assoc is NOT significantly - slower than using pg_fetch_row, while it - provides a significant ease of use. + slower than using pg_fetch_row, and + is significantly easier to use. - From 4.1.0, row became optional. - Calling pg_fetch_assoc will increment - the internal row counter by one. + row became optional in PHP 4.1.0. + + &reftitle.parameters; + + + + result + + + PostgreSQL query result resource, returned by pg_query, + pg_query_params or pg_execute + (among others). + + + + + row + + + Row number in result to fetch. Rows are numbered from 0 upwards. If omitted, + next row is fetched. + + + + + + + + + &reftitle.returnvalues; + + An array indexed associatively (by field name). + Each value in the array is represented as a + string. Database NULL + values are returned as &null;. + + + &false; is returned if row exceeds the number + of rows in the set, there are no more rows, or on any other error. + + + &reftitle.examples; diff --git a/reference/pgsql/functions/pg-fetch-object.xml b/reference/pgsql/functions/pg-fetch-object.xml index 698ec4d7ee..4ff65368ac 100644 --- a/reference/pgsql/functions/pg-fetch-object.xml +++ b/reference/pgsql/functions/pg-fetch-object.xml @@ -1,5 +1,5 @@ - + @@ -15,48 +15,113 @@ introw intresult_type + + objectpg_fetch_object + resourceresult + introw + stringclass_name + arrayparams + pg_fetch_object returns an object with - properties that correspond to the fetched row. It returns &false; - if there are no more rows or error. - - - pg_fetch_object is similar to - pg_fetch_array, with one difference - an - object is returned, instead of an array. Indirectly, that means - that you can only access the data by the field names, and not by - their offsets (numbers are illegal property names). + properties that correspond to the fetched row's field names. It can optionally + instantiate an object of a specific class, and pass parameters to that + class's constructor. &database.fetch-null; - - row is row (record) number to be - retrieved. First row is 0. - Speed-wise, the function is identical to - pg_fetch_array, and almost as quick as + pg_fetch_array, and almost as fast as pg_fetch_row (the difference is insignificant). - From 4.3.0, result_type is default to PGSQL_ASSOC while - older versions' default was PGSQL_BOTH. There is no use for numeric property, - since numeric property name is invalid in PHP. - - - result_type may be deleted in future versions. + row became optional in PHP 4.1.0. - From 4.1.0, row became optional. - Calling pg_fetch_object will increment - the internal row counter counter by one. + result_type default changed from PGSQL_BOTH + to PGSQL_ASSOC from PHP 4.3.0, since the numeric index was + illegal. + + + + + class_name and params were + added in PHP 5.0. The old form with result_type + still exists for backwards compatibility. + + &reftitle.parameters; + + + + result + + + PostgreSQL query result resource, returned by pg_query, + pg_query_params or pg_execute + (among others). + + + + + row + + + Row number in result to fetch. Rows are numbered from 0 upwards. If omitted, + next row is fetched. + + + + + result_type + + + Ignored and deprecated. Defaults to PGSQL_ASSOC. + + + + + class_name + + + The name of the class to instantiate, set the properties of and return. + If not specified, an unnamed object is returned. + + + + + params + + + An optional array of parameters to pass to the constructor + for class_name objects. + + + + + + + + + &reftitle.returnvalues; + + An object with one attribute for each field + name in the result. Database NULL + values are returned as &null;. + + + &false; is returned if row exceeds the number + of rows in the set, there are no more rows, or on any other error. + + + &reftitle.examples; diff --git a/reference/pgsql/functions/pg-fetch-result.xml b/reference/pgsql/functions/pg-fetch-result.xml index fb4a193ecf..ff4070b2f4 100644 --- a/reference/pgsql/functions/pg-fetch-result.xml +++ b/reference/pgsql/functions/pg-fetch-result.xml @@ -1,5 +1,5 @@ - + @@ -21,29 +21,106 @@ mixedfield - pg_fetch_result returns values from a - result resource returned by - pg_query. row - is integer. field is field name (string) - or field index (integer). The row - and field specify what cell in the table - of results to return. Row numbering starts from 0. Instead of - naming the field, you may use the field index as an unquoted - number. Field indices start from 0. + pg_fetch_result returns the value of a particular + row and field (column) in a PostgreSQL result resource. + + + + &reftitle.parameters; + + + + result + + + PostgreSQL query result resource, returned by pg_query, + pg_query_params or pg_execute + (among others). + + + + + row + + + Row number in result to fetch. Rows are numbered from 0 upwards. If omitted, + next row is fetched. + + + + + field + + + A string representing the name of the field (column) to fetch, otherwise + and int representing the field number to fetch. Fields are + numbered from 0 upwards. + + + + + + + + + &reftitle.returnvalues; PostgreSQL has many built in types and only the basic ones are - directly supported here. All forms of integer types are returned as integer values. All forms of - float, and real types are returned as float values. + float and real types are returned as float values. Boolean is returned as "t" or "f". All other types, including arrays are returned as strings formatted in the same default PostgreSQL manner that you would see in the - psql program. + psql program. Database NULL + values are returned as &null;. + + + &false; is returned if row exceeds the number + of rows in the set, or on any other error. + + + + + &reftitle.examples; + + + <function>pg_fetch_result</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + pg_query + pg_fetch_array + diff --git a/reference/pgsql/functions/pg-fetch-row.xml b/reference/pgsql/functions/pg-fetch-row.xml index 263613d53a..313d4dd9b9 100644 --- a/reference/pgsql/functions/pg-fetch-row.xml +++ b/reference/pgsql/functions/pg-fetch-row.xml @@ -1,5 +1,5 @@ - + @@ -17,24 +17,56 @@ pg_fetch_row fetches one row of data from the result associated with the specified - result resource. The row (record) is - returned as an array. Each result column is stored in an array - offset, starting at offset 0. - - - It returns an array that corresponds to the fetched row, or &false; - if there are no more rows. + result resource. &database.fetch-null; - From 4.1.0, row became optional. - Calling pg_fetch_row will increment - the internal row counter by one. + From PHP 4.1.0, row became optional. + + &reftitle.parameters; + + + + result + + + PostgreSQL query result resource, returned by pg_query, + pg_query_params or pg_execute + (among others). + + + + + row + + + Row number in result to fetch. Rows are numbered from 0 upwards. If omitted, + next row is fetched. + + + + + + + + + &reftitle.returnvalues; + + An array, indexed from 0 upwards, with each value + represented as a string. Database NULL + values are returned as &null;. + + + &false; is returned if row exceeds the number + of rows in the set, there are no more rows, or on any other error. + + + &reftitle.examples; diff --git a/reference/pgsql/functions/pg-lo-seek.xml b/reference/pgsql/functions/pg-lo-seek.xml index 4a7e180723..d684c2b14d 100644 --- a/reference/pgsql/functions/pg-lo-seek.xml +++ b/reference/pgsql/functions/pg-lo-seek.xml @@ -1,5 +1,5 @@ - + @@ -19,8 +19,8 @@ pg_lo_seek seeks position of large object - resource. whence is PGSQL_SEEK_SET, - PGSQL_SEEK_CUR or PGSQL_SEEK_END. + resource. whence is PGSQL_SEEK_SET, + PGSQL_SEEK_CUR or PGSQL_SEEK_END. diff --git a/reference/pgsql/functions/pg-result-error-field.xml b/reference/pgsql/functions/pg-result-error-field.xml index ddf38d4785..9a5a4abf4f 100644 --- a/reference/pgsql/functions/pg-result-error-field.xml +++ b/reference/pgsql/functions/pg-result-error-field.xml @@ -1,5 +1,5 @@ - + @@ -25,6 +25,11 @@ you must use pg_send_query and pg_get_result to get the result handle. + + If you need to get additional error information from failed pg_query queries, + use pg_set_error_verbosity and pg_last_error + and then parse the result. + @@ -44,15 +49,15 @@ fieldcode - Possible fieldcode values are: PGSQL_DIAG_SEVERITY, - PGSQL_DIAG_SQLSTATE, PGSQL_DIAG_MESSAGE_PRIMARY, - PGSQL_DIAG_MESSAGE_DETAIL, - PGSQL_DIAG_MESSAGE_HINT, PGSQL_DIAG_STATEMENT_POSITION, - PGSQL_DIAG_INTERNAL_POSITION (PostgreSQL 8.0+ only), - PGSQL_DIAG_INTERNAL_QUERY (PostgreSQL 8.0+ only), - PGSQL_DIAG_CONTEXT, PGSQL_DIAG_SOURCE_FILE, - PGSQL_DIAG_SOURCE_LINE or - PGSQL_DIAG_SOURCE_FUNCTION. + Possible fieldcode values are: PGSQL_DIAG_SEVERITY, + PGSQL_DIAG_SQLSTATE, PGSQL_DIAG_MESSAGE_PRIMARY, + PGSQL_DIAG_MESSAGE_DETAIL, + PGSQL_DIAG_MESSAGE_HINT, PGSQL_DIAG_STATEMENT_POSITION, + PGSQL_DIAG_INTERNAL_POSITION (PostgreSQL 8.0+ only), + PGSQL_DIAG_INTERNAL_QUERY (PostgreSQL 8.0+ only), + PGSQL_DIAG_CONTEXT, PGSQL_DIAG_SOURCE_FILE, + PGSQL_DIAG_SOURCE_LINE or + PGSQL_DIAG_SOURCE_FUNCTION. diff --git a/reference/pgsql/functions/pg-result-status.xml b/reference/pgsql/functions/pg-result-status.xml index 54a1a7a1ad..572933c4fa 100644 --- a/reference/pgsql/functions/pg-result-status.xml +++ b/reference/pgsql/functions/pg-result-status.xml @@ -1,5 +1,5 @@ - + @@ -19,19 +19,19 @@ pg_result_status returns status of result resource, or the command tag associated with the result. Possible values - of type are PGSQL_STATUS_LONG - or PGSQL_STATUS_STRING. The default is - PGSQL_STATUS_LONG. + of type are PGSQL_STATUS_LONG + or PGSQL_STATUS_STRING. The default is + PGSQL_STATUS_LONG. - Possible return values are PGSQL_EMPTY_QUERY, - PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_TO, - PGSQL_COPY_FROM, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR and - PGSQL_FATAL_ERROR if PGSQL_STATUS_LONG is + Possible return values are PGSQL_EMPTY_QUERY, + PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_TO, + PGSQL_COPY_FROM, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR and + PGSQL_FATAL_ERROR if PGSQL_STATUS_LONG is specified. - When PGSQL_STATUS_STRING is used, then the returned + When PGSQL_STATUS_STRING is used, then the returned value is the command completion tag from PostgreSQL. diff --git a/reference/pgsql/functions/pg-set-error-verbosity.xml b/reference/pgsql/functions/pg-set-error-verbosity.xml index c9ef9047d2..d3481c2eb3 100644 --- a/reference/pgsql/functions/pg-set-error-verbosity.xml +++ b/reference/pgsql/functions/pg-set-error-verbosity.xml @@ -1,5 +1,5 @@ - + @@ -27,10 +27,10 @@ pg_set_error_verbosity sets the verbosity mode, returning the connection's previous - setting. In TERSE mode, returned messages include severity, primary text, and - position only; this will normally fit on a single line. The default mode + setting. In PGSQL_ERRORS_TERSE mode, returned messages include severity, primary text, and + position only; this will normally fit on a single line. The default mode (PGSQL_ERRORS_DEFAULT) produces messages that include the above plus any detail, hint, or context - fields (these may span multiple lines). The VERBOSE mode includes all available + fields (these may span multiple lines). The PGSQL_ERRORS_VERBOSE mode includes all available fields. Changing the verbosity does not affect the messages available from already-existing result objects, only subsequently-created ones. @@ -55,9 +55,9 @@ verbosity - The required verbosity: PGSQL_ERRORS_TERSE, - PGSQL_ERRORS_DEFAULT - or PGSQL_ERRORS_VERBOSE. + The required verbosity: PGSQL_ERRORS_TERSE, + PGSQL_ERRORS_DEFAULT + or PGSQL_ERRORS_VERBOSE. @@ -68,9 +68,9 @@ &reftitle.returnvalues; - The previous verbosity level: PGSQL_ERRORS_TERSE, - PGSQL_ERRORS_DEFAULT - or PGSQL_ERRORS_VERBOSE. + The previous verbosity level: PGSQL_ERRORS_TERSE, + PGSQL_ERRORS_DEFAULT + or PGSQL_ERRORS_VERBOSE. diff --git a/reference/pgsql/functions/pg-transaction-status.xml b/reference/pgsql/functions/pg-transaction-status.xml index 0bd8865c50..463d40b8b2 100644 --- a/reference/pgsql/functions/pg-transaction-status.xml +++ b/reference/pgsql/functions/pg-transaction-status.xml @@ -1,5 +1,5 @@ - + @@ -44,12 +44,12 @@ &reftitle.returnvalues; - The status can be PGSQL_TRANSACTION_IDLE (currently idle), - PGSQL_TRANSACTION_ACTIVE (a command is in progress), - PGSQL_TRANSACTION_INTRANS (idle, in a valid transaction block), - or PGSQL_TRANSACTION_INERROR (idle, in a failed transaction block). - PGSQL_TRANSACTION_UNKNOWN is reported if the connection is bad. - PGSQL_TRANSACTION_ACTIVE is reported only when a query + The status can be PGSQL_TRANSACTION_IDLE (currently idle), + PGSQL_TRANSACTION_ACTIVE (a command is in progress), + PGSQL_TRANSACTION_INTRANS (idle, in a valid transaction block), + or PGSQL_TRANSACTION_INERROR (idle, in a failed transaction block). + PGSQL_TRANSACTION_UNKNOWN is reported if the connection is bad. + PGSQL_TRANSACTION_ACTIVE is reported only when a query has been sent to the server and not yet completed.