From 49ea73c4c3ddf2489752ca5f873e21a737ce996e Mon Sep 17 00:00:00 2001
From: Cornelia Boenigk <conni@php.net>
Date: Tue, 15 Jul 2003 22:36:03 +0000
Subject: [PATCH] minor fixes, some examples added
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@135149 c90b9560-bf6c-de11-be94-00142212c4b1
---
.../pgsql/functions/pg-connection-busy.xml | 24 ++++++-
.../pgsql/functions/pg-connection-status.xml | 19 ++++-
.../pgsql/functions/pg-field-is-null.xml | 27 ++++++-
reference/pgsql/functions/pg-field-name.xml | 49 ++++++++++++-
reference/pgsql/functions/pg-field-num.xml | 7 +-
reference/pgsql/functions/pg-field-prtlen.xml | 7 +-
reference/pgsql/functions/pg-field-size.xml | 5 +-
reference/pgsql/functions/pg-field-type.xml | 5 +-
reference/pgsql/functions/pg-meta-data.xml | 70 ++++++++++++++++++-
reference/pgsql/functions/pg-send-query.xml | 41 ++++++++++-
10 files changed, 240 insertions(+), 14 deletions(-)
diff --git a/reference/pgsql/functions/pg-connection-busy.xml b/reference/pgsql/functions/pg-connection-busy.xml
index 9a32e810ee..d18a61ef3f 100644
--- a/reference/pgsql/functions/pg-connection-busy.xml
+++ b/reference/pgsql/functions/pg-connection-busy.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.82 -->
<refentry id='function.pg-connection-busy'>
<refnamediv>
@@ -19,6 +19,28 @@
connection is busy. If it is busy, a previous query is still executing.
If <function>pg_get_result</function> is called, it will be blocked.
</para>
+ <para>
+ <example>
+ <title>pg_connection_busy</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $dbconn = pg_connect("dbname=publisher") or die ("Could not connect");
+ $bs = pg_connection_busy($dbconn);
+ if ($bs) {
+ echo 'connection is busy';
+ }
+ else {
+ echo 'connection is not busy';
+ }
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+
+
<para>
See also <function>pg_connection_status</function> and
<function>pg_get_result</function>
diff --git a/reference/pgsql/functions/pg-connection-status.xml b/reference/pgsql/functions/pg-connection-status.xml
index a8282ac193..4b4cc32ce5 100644
--- a/reference/pgsql/functions/pg-connection-status.xml
+++ b/reference/pgsql/functions/pg-connection-status.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.82 -->
<refentry id='function.pg-connection-status'>
<refnamediv>
@@ -19,6 +19,23 @@
status. Possible statuses are <literal>PGSQL_CONNECTION_OK</literal>
and <literal>PGSQL_CONNECTION_BAD</literal>.
</para>
+ <para>
+ <example>
+ <title>pg_connection_status</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $dbconn = pg_connect("dbname=publisher") or die ("Could not connect");
+ $stat = pg_connection_status($dbconn);
+ echo 'connection_status: '.$stat;
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+
+
<para>
See also <function>pg_connection_busy</function>.
</para>
diff --git a/reference/pgsql/functions/pg-field-is-null.xml b/reference/pgsql/functions/pg-field-is-null.xml
index 7ef7a951b4..5cbd8c5406 100644
--- a/reference/pgsql/functions/pg-field-is-null.xml
+++ b/reference/pgsql/functions/pg-field-is-null.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-field-is-null">
<refnamediv>
@@ -15,12 +15,35 @@
<methodparam><type>mixed</type><parameter>field</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_field_is_null</function> test if a field is &null; or
+ <function>pg_field_is_null</function> tests if a field is &null; or
not. It returns 1 if the field in the given row is &null;. It
returns 0 if the field in the given row is NOT &null;. Field can
be specified as column index (number) or fieldname (string). Row
numbering starts at 0.
</para>
+ <para>
+ <example>
+ <title>pg_field_is_null</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'");
+ if ($res) {
+ if (pg_field_is_null($res, 0, "year") == 1) {
+ echo 'The value of the field year is null.';
+ }
+ if (pg_field_is_null($res, 0, "year") == 0) {
+ echo 'The value of the field year is not null.';
+ }
+ }
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+
+
<note>
<para>
This function used to be called <literal>pg_fieldisnull()</literal>.
diff --git a/reference/pgsql/functions/pg-field-name.xml b/reference/pgsql/functions/pg-field-name.xml
index f828853945..3894635957 100644
--- a/reference/pgsql/functions/pg-field-name.xml
+++ b/reference/pgsql/functions/pg-field-name.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-field-name">
<refnamediv>
@@ -19,6 +19,53 @@
given PostgreSQL <parameter>result</parameter> resource. Field
numbering starts from 0.
</para>
+ <para>
+ <example>
+ <title>Getting informations 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>
+ <para>
+ The above example would produce the following output:
+ </para>
+ <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>
<note>
<para>
This function used to be called <literal>pg_fieldname()</literal>.
diff --git a/reference/pgsql/functions/pg-field-num.xml b/reference/pgsql/functions/pg-field-num.xml
index 8b0dc19f8e..d1769c1694 100644
--- a/reference/pgsql/functions/pg-field-num.xml
+++ b/reference/pgsql/functions/pg-field-num.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-field-num">
<refnamediv>
@@ -18,7 +18,10 @@
column (field) slot that corresponds to the
<parameter>field_name</parameter> in the given PostgreSQL
<parameter>result</parameter> resource. Field numbering starts
- at 0. This function will return -1 on error.
+ at 0. This function will return -1 on error.
+ </para>
+ <para>
+ See the example given at the <function>pg_field_name</function> page.
</para>
<note>
<para>
diff --git a/reference/pgsql/functions/pg-field-prtlen.xml b/reference/pgsql/functions/pg-field-prtlen.xml
index 846f526c4e..f7f979923b 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.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-field-prtlen">
<refnamediv>
@@ -20,9 +20,12 @@
<parameter>result</parameter>. Row numbering starts at 0. This
function will return -1 on an error.
</para>
+ <para>
+ See the example given at the <function>pg_field_name</function> page.
+ </para>
<note>
<para>
- This function used to be called <literal>pg_field_prtlen()</literal>.
+ This function used to be called <literal>pg_fieldprtlen()</literal>.
</para>
</note>
<para>
diff --git a/reference/pgsql/functions/pg-field-size.xml b/reference/pgsql/functions/pg-field-size.xml
index 5ab92d2d45..ac3dbb2a3c 100644
--- a/reference/pgsql/functions/pg-field-size.xml
+++ b/reference/pgsql/functions/pg-field-size.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-field-size">
<refnamediv>
@@ -22,6 +22,9 @@
field size of -1 indicates a variable length field. This function
will return &false; on error.
</para>
+ <para>
+ See the example given at the <function>pg_field_name</function> page.
+ </para>
<note>
<para>
This function used to be called <literal>pg_fieldsize()</literal>.
diff --git a/reference/pgsql/functions/pg-field-type.xml b/reference/pgsql/functions/pg-field-type.xml
index 5fd32f4b42..d72cd24b5e 100644
--- a/reference/pgsql/functions/pg-field-type.xml
+++ b/reference/pgsql/functions/pg-field-type.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.52 -->
<refentry id="function.pg-field-type">
<refnamediv>
@@ -21,6 +21,9 @@
given PostgreSQL <parameter>result</parameter> resource. Field
numbering starts at 0.
</para>
+ <para>
+ See the example given at the <function>pg_field_name</function> page.
+ </para>
<note>
<para>
This function used to be called <literal>pg_fieldtype()</literal>.
diff --git a/reference/pgsql/functions/pg-meta-data.xml b/reference/pgsql/functions/pg-meta-data.xml
index f8c8ae5695..a90fcc6d79 100644
--- a/reference/pgsql/functions/pg-meta-data.xml
+++ b/reference/pgsql/functions/pg-meta-data.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.80 -->
<refentry id='function.pg-meta-data'>
<refnamediv>
@@ -20,6 +20,74 @@
<literal>table_name</literal> as array. If there is error, it
returns &false;
</para>
+ <para>
+ <example>
+ <title>Getting table metadata</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $dbconn = pg_connect("dbname=publisher") or die ("Could not connect");
+
+ $meta = pg_meta_data($dbconn,'authors');
+ if (is_array ($meta)) {
+ echo '<pre>';
+ var_dump ($meta);
+ echo '</pre>';
+ }
+?>
+]]>
+ </programlisting>
+ <para>
+ The above example would produce the following output:
+ </para>
+ <screen>
+<![CDATA[
+array(3) {
+ ["author"]=>
+ array(5) {
+ ["num"]=>
+ int(1)
+ ["type"]=>
+ string(7) "varchar"
+ ["len"]=>
+ int(-1)
+ ["not null"]=>
+ bool(false)
+ ["has default"]=>
+ bool(false)
+ }
+ ["year"]=>
+ array(5) {
+ ["num"]=>
+ int(2)
+ ["type"]=>
+ string(4) "int2"
+ ["len"]=>
+ int(2)
+ ["not null"]=>
+ bool(false)
+ ["has default"]=>
+ bool(false)
+ }
+ ["title"]=>
+ array(5) {
+ ["num"]=>
+ int(3)
+ ["type"]=>
+ string(7) "varchar"
+ ["len"]=>
+ int(-1)
+ ["not null"]=>
+ bool(false)
+ ["has default"]=>
+ bool(false)
+ }
+}
+]]>
+ </screen>
+ </example>
+ </para>
+
<note>
<para>
This function is experimental.
diff --git a/reference/pgsql/functions/pg-send-query.xml b/reference/pgsql/functions/pg-send-query.xml
index a12c9cc127..4c92e06a53 100644
--- a/reference/pgsql/functions/pg-send-query.xml
+++ b/reference/pgsql/functions/pg-send-query.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id='function.pg-send-query'>
<refnamediv>
@@ -27,7 +27,7 @@
<function>pg_get_result</function>. Script execution is not blocked
while query is executing. Use
<function>pg_connection_busy</function> to check connection is
- busy (i.e. query is executing). Query may be canceled by calling
+ busy (i.e. query is executing). Query may be cancelled by calling
<function>pg_cancel_query</function>.
</para>
<para>
@@ -36,6 +36,43 @@
connection is busy, it waits until last query is finished and
discards all result.
</para>
+ <para>
+ <example>
+ <title>Asynchronous Queries</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $dbconn = pg_connect("dbname=publisher") or die ("Could not connect");
+
+ if (!pg_connection_busy($dbconn)) {
+ pg_send_query($dbconn,"select * from authors; select count(*) from authors;");
+ }
+ $res1 = pg_get_result($dbconn);
+ echo 'first call to pg_get_result(): '.$res1.'<br>';
+ $rows1 = pg_num_rows($res1);
+ echo $res1.' has '.$rows1.' records<br><br>';
+
+ $res2 = pg_get_result($dbconn);
+ echo 'second call to pg_get_result(): '.$res2.'<br>';
+ $rows2 = pg_num_rows($res2);
+ echo $res2.' has '.$rows2.' records<br>';
+?>
+]]>
+ </programlisting>
+ <para>
+ The above example would produce the following output:
+ </para>
+ <screen>
+<![CDATA[
+first call to pg_get_result(): Resource id #3
+Resource id #3 has 3 records
+
+second call to pg_get_result(): Resource id #4
+Resource id #4 has 1 records
+]]>
+ </screen>
+ </example>
+ </para>
<para>
See also <function>pg_query</function>,
<function>pg_cancel_query</function>,