From e1ddb8003da2c6882f906c8e5ebc77036ad45670 Mon Sep 17 00:00:00 2001
From: Christopher Kings-Lynne <chriskl@php.net>
Date: Mon, 5 Sep 2005 04:07:19 +0000
Subject: [PATCH] * Add examples to the 3 remaining functions that didn't have
them: pg_convert(), pg_field_prtlen() and pg_set_client_encoding(). * Large
rewrite of the PostgreSQL overview page. Bring it up to date and similar to
the MySQL extension overview page. Remove complexities, clutter and
references to truly old versions.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@195156 c90b9560-bf6c-de11-be94-00142212c4b1
---
reference/pgsql/functions/pg-convert.xml | 28 +-
reference/pgsql/functions/pg-field-prtlen.xml | 53 ++-
.../functions/pg-set-client-encoding.xml | 39 +-
reference/pgsql/reference.xml | 345 ++++--------------
4 files changed, 194 insertions(+), 271 deletions(-)
diff --git a/reference/pgsql/functions/pg-convert.xml b/reference/pgsql/functions/pg-convert.xml
index 3fbde0fe80..1d065e033a 100644
--- a/reference/pgsql/functions/pg-convert.xml
+++ b/reference/pgsql/functions/pg-convert.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.80 -->
<refentry id='function.pg-convert'>
<refnamediv>
@@ -88,7 +88,31 @@
An <type>array</type> of converted values, or &false; on error.
</para>
</refsect1>
-
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_convert</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $dbconn = pg_connect('dbname=foo');
+
+ $tmp = array(
+ 'author' => 'Joe Thackery',
+ 'year' => 2005,
+ 'title' => 'My Life, by Joe Thackery'
+ );
+
+ $vals = pg_convert($dbconn, 'authors', $tmp);
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
diff --git a/reference/pgsql/functions/pg-field-prtlen.xml b/reference/pgsql/functions/pg-field-prtlen.xml
index 6c145a84d4..db194b47af 100644
--- a/reference/pgsql/functions/pg-field-prtlen.xml
+++ b/reference/pgsql/functions/pg-field-prtlen.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-field-prtlen">
<refnamediv>
@@ -75,7 +75,56 @@
The field printed length, or &false; on error.
</para>
</refsect1>
-
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Getting information about fields</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $dbconn = pg_connect("dbname=publisher") or die("Could not connect");
+
+ $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
+ $i = pg_num_fields($res);
+ for ($j = 0; $j < $i; $j++) {
+ echo "column $j\n";
+ $fieldname = pg_field_name($res, $j);
+ echo "fieldname: $fieldname\n";
+ echo "printed length: " . pg_field_prtlen($res, $fieldname) . " characters\n";
+ echo "storage length: " . pg_field_size($res, $j) . " bytes\n";
+ echo "field type: " . pg_field_type($res, $j) . " \n\n";
+ }
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+column 0
+fieldname: author
+printed length: 6 characters
+storage length: -1 bytes
+field type: varchar
+
+column 1
+fieldname: year
+printed length: 4 characters
+storage length: 2 bytes
+field type: int2
+
+column 2
+fieldname: title
+printed length: 24 characters
+storage length: -1 bytes
+field type: varchar
+]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
diff --git a/reference/pgsql/functions/pg-set-client-encoding.xml b/reference/pgsql/functions/pg-set-client-encoding.xml
index 0c85cfec64..084d88116a 100644
--- a/reference/pgsql/functions/pg-set-client-encoding.xml
+++ b/reference/pgsql/functions/pg-set-client-encoding.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.16 -->
<refentry id="function.pg-set-client-encoding">
<refnamediv>
@@ -77,7 +77,44 @@
Returns 0 on success or -1 on error.
</para>
</refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_set_client_encoding</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$conn = pg_pconnect("dbname=publisher");
+if (!$conn) {
+ echo "An error occured.\n";
+ exit;
+}
+
+// Set the client encoding to UNICODE. Data will be automatically
+// converted from the backend encoding to the frontend.
+pg_set_client_encoding($conn, UNICODE);
+
+$result = pg_query($conn, "SELECT author, email FROM authors");
+if (!$result) {
+ echo "An error occured.\n";
+ exit;
+}
+
+// Write out UTF-8 data
+while ($row = pg_fetch_row($result)) {
+ echo "Author: $row[0] E-mail: $row[1]";
+ echo "<br />\n";
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
diff --git a/reference/pgsql/reference.xml b/reference/pgsql/reference.xml
index 1db183a8cb..c6c99993aa 100644
--- a/reference/pgsql/reference.xml
+++ b/reference/pgsql/reference.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.26 $ -->
+<!-- $Revision: 1.27 $ -->
<!-- Purpose: database.vendors -->
<!-- Membership: bundled, external -->
@@ -26,7 +26,7 @@
<para>
To use PostgreSQL support, you need PostgreSQL 6.5 or
later, PostgreSQL 8.0 or later to enable all PostgreSQL module
- features. PostgreSQL supports many character encoding including
+ features. PostgreSQL supports many character encodings including
multibyte character encoding. The current version and more
information about PostgreSQL is available at
<ulink url="&url.pgsql;">&url.pgsql;</ulink> and
@@ -38,282 +38,95 @@
&reference.pgsql.ini;
- <section id="pgsql.using">
- <title>How to use and hints</title>
- <warning>
- <para>
- Using the PostgreSQL module with PHP 4.0.6 is not recommended due to
- a bug in the notice message handling code. Use 4.1.0 or later.
- </para>
- </warning>
- <warning>
- <para>
- PostgreSQL function names will be changed in 4.2.0 release to
- confirm to current coding standards. Most of new names will have
- additional underscores, e.g. pg_lo_open(). Some functions are
- renamed to different name for consistency. e.g. pg_exec() to
- pg_query(). Older names can be used in 4.2.0 and a few releases
- from 4.2.0, but they may be deleted in the future.
- </para>
- <table>
- <title>Function names changed</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Old name</entry>
- <entry>New name</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><function>pg_cmdtuples</function></entry>
- <entry><function>pg_affected_rows</function></entry>
- </row>
- <row>
- <entry><function>pg_errormessage</function></entry>
- <entry><function>pg_last_error</function></entry>
- </row>
- <row>
- <entry><function>pg_exec</function></entry>
- <entry><function>pg_query</function></entry>
- </row>
- <row>
- <entry><function>pg_fieldname</function></entry>
- <entry><function>pg_field_name</function></entry>
- </row>
- <row>
- <entry><function>pg_fieldsize</function></entry>
- <entry><function>pg_field_size</function></entry>
- </row>
- <row>
- <entry><function>pg_fieldnum</function></entry>
- <entry><function>pg_field_num</function></entry>
- </row>
- <row>
- <entry><function>pg_fieldprtlen</function></entry>
- <entry><function>pg_field_prtlen</function></entry>
- </row>
- <row>
- <entry><function>pg_fieldisnull</function></entry>
- <entry><function>pg_field_is_null</function></entry>
- </row>
- <row>
- <entry><function>pg_freeresult</function></entry>
- <entry><function>pg_free_result</function></entry>
- </row>
- <row>
- <entry><function>pg_getlastoid</function></entry>
- <entry><function>pg_last_oid</function></entry>
- </row>
- <row>
- <entry><function>pg_loreadall</function></entry>
- <entry><function>pg_lo_read_all</function></entry>
- </row>
- <row>
- <entry><function>pg_locreate</function></entry>
- <entry><function>pg_lo_create</function></entry>
- </row>
- <row>
- <entry><function>pg_lounlink</function></entry>
- <entry><function>pg_lo_unlink</function></entry>
- </row>
- <row>
- <entry><function>pg_loopen</function></entry>
- <entry><function>pg_lo_open</function></entry>
- </row>
- <row>
- <entry><function>pg_loclose</function></entry>
- <entry><function>pg_lo_close</function></entry>
- </row>
- <row>
- <entry><function>pg_loread</function></entry>
- <entry><function>pg_lo_read</function></entry>
- </row>
- <row>
- <entry><function>pg_lowrite</function></entry>
- <entry><function>pg_lo_write</function></entry>
- </row>
- <row>
- <entry><function>pg_loimport</function></entry>
- <entry><function>pg_lo_import</function></entry>
- </row>
- <row>
- <entry><function>pg_loexport</function></entry>
- <entry><function>pg_lo_export</function></entry>
- </row>
- <row>
- <entry><function>pg_numrows</function></entry>
- <entry><function>pg_num_rows</function></entry>
- </row>
- <row>
- <entry><function>pg_numfields</function></entry>
- <entry><function>pg_num_fields</function></entry>
- </row>
- <row>
- <entry><function>pg_result</function></entry>
- <entry><function>pg_fetch_result</function></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <section id="pgsql.resources">
+ &reftitle.resources;
<para>
- The old <function>pg_connect</function>/<function>pg_pconnect</function>
- syntax will be deprecated to support asynchronous connections in the
- future. Please use a connection string for <function>pg_connect</function>
- and <function>pg_pconnect</function>.
+ There are two resource types used in the PostgreSQL module. The first one
+ is the link identifier for a database connection, the second a resource
+ which holds the result of a query.
</para>
- </warning>
- <para>
- Not all functions are supported by all builds. It depends on your
- libpq (The PostgreSQL C Client interface) version and how libpq is
- compiled. If there is missing function, libpq does not support
- the feature required for the function.
- </para>
- <para>
- It is also important that you do not use an older libpq than the PostgreSQL
- Server to which you will be connecting. If you use libpq older than PostgreSQL
- Server expects, you may have problems.
- </para>
- <para>
- Since version 6.3 (03/02/1998) PostgreSQL uses unix domain sockets
- by default. TCP port will NOT be opened by default. A table is
- shown below describing these new connection possibilities. This
- socket will be found in <filename>/tmp/.s.PGSQL.5432</filename>.
- This option can be enabled with the '-i' flag to
- <command>postmaster</command> and its meaning is: "listen on
- TCP/IP sockets as well as Unix domain sockets".
- <table>
- <title>Postmaster and PHP</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Postmaster</entry>
- <entry>PHP</entry>
- <entry>Status</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>postmaster &</entry>
- <entry>pg_connect("dbname=MyDbName");</entry>
- <entry>OK</entry>
- </row>
- <row>
- <entry>postmaster -i &</entry>
- <entry>pg_connect("dbname=MyDbName");</entry>
- <entry>OK</entry>
- </row>
- <row>
- <entry>postmaster &</entry>
- <entry>pg_connect("host=localhost dbname=MyDbName");</entry>
- <entry>
- Unable to connect to PostgreSQL server: connectDB() failed:
- Is the postmaster running and accepting TCP/IP (with -i)
- connection at 'localhost' on port '5432'? in
- /path/to/file.php on line 20.
- </entry>
- </row>
- <row>
- <entry>postmaster -i &</entry>
- <entry>pg_connect("host=localhost dbname=MyDbName");</entry>
- <entry>OK</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- A connection to PostgreSQL server can be established with the
- following value pairs set in the command string: <command>$conn =
- pg_connect("host=myHost port=myPort tty=myTTY options=myOptions
- dbname=myDB user=myUser password=myPassword ");
- </command>
- </para>
- <para>
- The previous syntax of:
- <command>
- $conn = pg_connect ("host", "port", "options", "tty", "dbname")
- </command>
- has been deprecated.
- </para>
- <para>
- Environmental variables affect PostgreSQL server/client
- behavior. For example, PostgreSQL module will lookup PGHOST
- environment variable when the hostname is omitted in the connection
- string. Supported environment variables are different from version
- to version. Refer to PostgreSQL Programmer's Manual (libpq -
- Environment Variables) for details.
- </para>
- <para>
- Make sure you set environment variables for appropriate user. Use
- <literal>$_ENV</literal> or <function>getenv</function> to check
- which environment variables are available to the current process.
- </para>
- <example>
- <title>Setting default parameters</title>
- <programlisting>
-<![CDATA[
-PGHOST=pgsql.example.com
-PGPORT=7890
-PGDATABASE=web-system
-PGUSER=web-user
-PGPASSWORD=secret
-PGDATESTYLE=ISO
-PGTZ=JST
-PGCLIENTENCODING=EUC-JP
-
-export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING
-]]>
- </programlisting>
- </example>
- <note>
- <para>
- PostgreSQL automatically folds all identifiers (e.g. table/column names)
- to lower-case values. To get it to recognize upper-case values, you must
- always wrap the identifier in quotes.
- </para>
- </note>
</section>
&reference.pgsql.constants;
+ <section id="pgsql.notes">
+ &reftitle.notes;
+ <note>
+ <para>
+ Not all functions are supported by all builds. It depends on your
+ libpq (The PostgreSQL C client library) version and how libpq is
+ compiled. If PHP PostgreSQL extensions are missing, then it is because
+ your libpq version does not support them.
+ </para>
+ </note>
+ <note>
+ <para>
+ Most PostgreSQL functions accept <parameter>connection</parameter> as
+ the first optional parameter. If it is not provided, the last opened
+ connection is used. If it doesn't exist, functions return &false;.
+ </para>
+ </note>
+ <note>
+ <para>
+ PostgreSQL automatically folds all identifiers (e.g. table/column names)
+ to lower-case values at object creation time and at query time.
+ To force the use of mixed or upper case identifiers, you must escape
+ the identifier using double quotes ("").
+ </para>
+ </note>
+ <note>
+ <para>
+ PostgreSQL does not have special commands for fetching database schema
+ information (eg. all the tables in the current database). Instead, there
+ is a standard schema named <literal>information_schema</literal> in
+ PostgreSQL 7.4 and above containing
+ system views with all the necessary information, in an easily
+ queryable form. See the <ulink url="&url.pgsql.manual;">PostgreSQL Documentation</ulink>
+ for full details.
+ </para>
+ </note>
+ </section>
+
<section id="pgsql.examples">
&reftitle.examples;
- <para>
- Starting with PostgreSQL 7.1.0, you can store up to 1GB into a
- field of type text. In older versions, this was limited to the block
- size (default was 8KB, maximum was 32KB, defined at compile time)
- </para>
- <para>
- To use the large object (lo) interface, it is required to enclose
- large object functions within a transaction block. A transaction
- block starts with a SQL statement <command>BEGIN</command> and if
- the transaction was valid ends with <command>COMMIT</command> or
- <command>END</command>. If the transaction fails the transaction
- should be closed with <command>ROLLBACK</command> or
- <command>ABORT</command>.
- <example>
- <title>Using Large Objects</title>
- <programlisting role="php">
+ <para>
+ This simple example shows how to connect, execute a query, print
+ resulting rows and disconnect from a PostgreSQL database.
+ <example>
+ <title>PostgreSQL extension overview example</title>
+ <programlisting role="php">
<![CDATA[
<?php
- $database = pg_connect("dbname=jacarta");
- pg_query($database, "begin");
- $oid = pg_lo_create($database);
- echo "$oid\n";
- $handle = pg_lo_open($database, $oid, "w");
- echo "$handle\n";
- pg_lo_write($handle, "large object data");
- pg_lo_close($handle);
- pg_query($database, "commit");
+// Connecting, selecting database
+$db = pg_connect("host=localhost dbname=publishing user=www password=foo");
+ or die('Could not connect: ' . pg_last_error());
+
+// Performing SQL query
+$query = 'SELECT * FROM authors';
+$result = pg_query($query) or die('Query failed: ' . pg_last_error());
+
+// Printing results in HTML
+echo "<table>\n";
+while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
+ echo "\t<tr>\n";
+ foreach ($line as $col_value) {
+ echo "\t\t<td>$col_value</td>\n";
+ }
+ echo "\t</tr>\n";
+}
+echo "</table>\n";
+
+// Free resultset
+pg_free_result($result);
+
+// Closing connection
+pg_close($link);
?>
]]>
- </programlisting>
- </example>
- You should not close the connection to the PostgreSQL server
- before closing the large object.
- </para>
- </section>
+ </programlisting>
+ </example>
+ </para>
+ </section>
</partintro>
&reference.pgsql.functions;