chriskl Wed Apr 13 23:21:36 2005 EDT
Modified files:
/phpdoc/en/reference/pgsql/functions pg-lo-open.xml
pg-lo-read-all.xml
pg-lo-read.xml pg-lo-seek.xml
pg-lo-tell.xml
pg-lo-unlink.xml
pg-lo-write.xml
Log:
- More work on pgsql docs overhaul. All the pg_lo_* functions are now done.
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-lo-open.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-lo-open.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-lo-open.xml:1.5
phpdoc/en/reference/pgsql/functions/pg-lo-open.xml:1.6
--- phpdoc/en/reference/pgsql/functions/pg-lo-open.xml:1.5 Fri Mar 11
11:03:25 2005
+++ phpdoc/en/reference/pgsql/functions/pg-lo-open.xml Wed Apr 13 23:21:36 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-lo-open">
<refnamediv>
@@ -16,12 +16,8 @@
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_lo_open</function> opens a Large Object and
- returns large object resource. The resource encapsulates
- information about the connection.
- <parameter>oid</parameter> specifies a valid large object oid and
- <parameter>mode</parameter> can be either "r", "w", or "rw". It
- returns &false; if there is an error.
+ <function>pg_lo_open</function> opens a large object in the database
+ and returns large object resource so that it can be manipulated.
</para>
<warning>
<para>
@@ -30,7 +26,7 @@
</para>
</warning>
<para>
- To use the large object (lo) interface, it is necessary to
+ To use the large object interface, it is necessary to
enclose it within a transaction block.
</para>
<note>
@@ -39,7 +35,74 @@
</para>
</note>
</refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource. When
+ <parameter>connection</parameter> is not present, the default
connection
+ is used. The default connection is the last connection made by
+ <function>pg_connect</function> or <function>pg_pconnect</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>oid</parameter></term>
+ <listitem>
+ <para>
+ The <varname>OID</varname> of the large object in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>mode</parameter></term>
+ <listitem>
+ <para>
+ Can be either "r" for read-only, "w" for write only or "rw" for read
and
+ write.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ A large object resource or &false; on error.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_lo_open</function> 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");
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-lo-read-all.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-lo-read-all.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-lo-read-all.xml:1.5
phpdoc/en/reference/pgsql/functions/pg-lo-read-all.xml:1.6
--- phpdoc/en/reference/pgsql/functions/pg-lo-read-all.xml:1.5 Fri Mar 11
11:03:25 2005
+++ phpdoc/en/reference/pgsql/functions/pg-lo-read-all.xml Wed Apr 13
23:21:36 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-lo-read-all">
<refnamediv>
@@ -19,11 +19,10 @@
<function>pg_lo_read_all</function> reads a large object and passes
it straight through to the browser after sending all pending
headers. Mainly intended for sending binary data like images or
- sound. It returns number of bytes read. It returns &false;, if an
- error occurred.
+ sound.
</para>
<para>
- To use the large object (lo) interface, it is necessary to
+ To use the large object interface, it is necessary to
enclose it within a transaction block.
</para>
<note>
@@ -33,6 +32,52 @@
</note>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>large_object</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL large object (LOB) resource, returned by
<function>pg_lo_open</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Number of bytes read or &false; on error.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_lo_read_all</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ header('Content-type: image/jpeg');
+ $image_oid = 189762345;
+ $database = pg_connect("dbname=jacarta");
+ pg_query($database, "begin");
+ $handle = pg_lo_open($database, $image_oid, "r");
+ pg_lo_read_all($handle);
+ pg_query($database, "commit");
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-lo-read.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-lo-read.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-lo-read.xml:1.5
phpdoc/en/reference/pgsql/functions/pg-lo-read.xml:1.6
--- phpdoc/en/reference/pgsql/functions/pg-lo-read.xml:1.5 Fri Mar 11
11:03:25 2005
+++ phpdoc/en/reference/pgsql/functions/pg-lo-read.xml Wed Apr 13 23:21:36 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.74 -->
<refentry id="function.pg-lo-read">
<refnamediv>
@@ -16,14 +16,11 @@
</methodsynopsis>
<para>
<function>pg_lo_read</function> reads at most
- <parameter>len</parameter> (defaults to 8192) bytes from a large object and
- returns it as a string. <parameter>large_object</parameter> specifies a
- valid large object resource and<parameter>len</parameter>
- specifies the maximum allowable size of the large object
- segment. It returns &false; if there is an error.
+ <parameter>len</parameter> bytes from a large object and
+ returns it as a <type>string</type>.
</para>
<para>
- To use the large object (lo) interface, it is necessary to
+ To use the large object interface, it is necessary to
enclose it within a transaction block.
</para>
<note>
@@ -33,6 +30,60 @@
</note>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>large_object</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL large object (LOB) resource, returned by
<function>pg_lo_open</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>len</parameter></term>
+ <listitem>
+ <para>
+ An optional maximum number of bytes to return. Defaults to 8192.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ A <type>string</type> containing <parameter>len</parameter> bytes from the
+ large object, or &false; on error.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_lo_read</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $doc_oid = 189762345;
+ $database = pg_connect("dbname=jacarta");
+ pg_query($database, "begin");
+ $handle = pg_lo_open($database, $doc_oid, "r");
+ $data = pg_lo_read($handle, 50000);
+ pg_query($database, "commit");
+ echo $data;
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-lo-seek.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-lo-seek.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-lo-seek.xml:1.5
phpdoc/en/reference/pgsql/functions/pg-lo-seek.xml:1.6
--- phpdoc/en/reference/pgsql/functions/pg-lo-seek.xml:1.5 Wed Apr 6
05:04:49 2005
+++ phpdoc/en/reference/pgsql/functions/pg-lo-seek.xml Wed Apr 13 23:21:36 2005
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id='function.pg-lo-seek'>
<refnamediv>
<refname>pg_lo_seek</refname>
<refpurpose>
- Seeks position of large object
+ Seeks position within a large object
</refpurpose>
</refnamediv>
@@ -18,12 +18,81 @@
<methodparam
choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_lo_seek</function> seeks position of large object
- resource. <parameter>whence</parameter> is
<constant>PGSQL_SEEK_SET</constant>,
- <constant>PGSQL_SEEK_CUR</constant> or <constant>PGSQL_SEEK_END</constant>.
+ <function>pg_lo_seek</function> seeks a position within a large object
+ resource.
+ </para>
+ <para>
+ To use the large object interface, it is necessary to
+ enclose it within a transaction block.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>large_object</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL large object (LOB) resource, returned by
<function>pg_lo_open</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>offset</parameter></term>
+ <listitem>
+ <para>
+ The number of bytes to seek.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>whence</parameter></term>
+ <listitem>
+ <para>
+ One of the constants <constant>PGSQL_SEEK_SET</constant> (seek from
object start),
+ <constant>PGSQL_SEEK_CUR</constant> (seek from current position)
+ or <constant>PGSQL_SEEK_END</constant> (seek from object end) .
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</para>
</refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ &return.success;
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_lo_seek</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $doc_oid = 189762345;
+ $database = pg_connect("dbname=jacarta");
+ pg_query($database, "begin");
+ $handle = pg_lo_open($database, $doc_oid, "r");
+ // Skip first 10000 bytes
+ pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
+ // Read the next 50000 bytes
+ $data = pg_lo_read($handle, 10000);
+ pg_query($database, "commit");
+ echo $data;
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-lo-tell.xml?r1=1.4&r2=1.5&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-lo-tell.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-lo-tell.xml:1.4
phpdoc/en/reference/pgsql/functions/pg-lo-tell.xml:1.5
--- phpdoc/en/reference/pgsql/functions/pg-lo-tell.xml:1.4 Fri Mar 11
11:03:25 2005
+++ phpdoc/en/reference/pgsql/functions/pg-lo-tell.xml Wed Apr 13 23:21:36 2005
@@ -1,11 +1,11 @@
<?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.74 -->
<refentry id='function.pg-lo-tell'>
<refnamediv>
<refname>pg_lo_tell</refname>
<refpurpose>
- Returns current position of large object
+ Returns current seek position a of large object
</refpurpose>
</refnamediv>
@@ -16,11 +16,70 @@
<methodparam><type>resource</type><parameter>large_object</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_lo_tell</function> returns current position (offset
- from the beginning of large object).
+ <function>pg_lo_tell</function> returns the current position (offset
+ from the beginning) of a large object.
+ </para>
+ <para>
+ To use the large object interface, it is necessary to
+ enclose it within a transaction block.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>large_object</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL large object (LOB) resource, returned by
<function>pg_lo_open</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</para>
</refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ The current seek offset (in number of bytes) from the beginning of the large
+ object. If there is an error, the return value is negative.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_lo_tell</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $doc_oid = 189762345;
+ $database = pg_connect("dbname=jacarta");
+ pg_query($database, "begin");
+ $handle = pg_lo_open($database, $doc_oid, "r");
+ // Skip first 10000 bytes
+ pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
+ // See how far we've skipped
+ $offset = pg_lo_tell($handle);
+ echo "Seek position is: $offset";
+ pg_query($database, "commit");
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Seek position is: 50000
+]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-lo-unlink.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-lo-unlink.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-lo-unlink.xml:1.5
phpdoc/en/reference/pgsql/functions/pg-lo-unlink.xml:1.6
--- phpdoc/en/reference/pgsql/functions/pg-lo-unlink.xml:1.5 Fri Mar 11
11:03:25 2005
+++ phpdoc/en/reference/pgsql/functions/pg-lo-unlink.xml Wed Apr 13
23:21:36 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-lo-unlink">
<refnamediv>
@@ -19,16 +19,71 @@
<parameter>oid</parameter>. &return.success;
</para>
<para>
- To use the large object (lo) interface, it is necessary to
+ To use the large object interface, it is necessary to
enclose it within a transaction block.
</para>
<note>
<para>
- This function used to be called <literal>pg_lo_unlink()</literal>.
+ This function used to be called <literal>pg_lounlink()</literal>.
</para>
</note>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource. When
+ <parameter>connection</parameter> is not present, the default
connection
+ is used. The default connection is the last connection made by
+ <function>pg_connect</function> or <function>pg_pconnect</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>oid</parameter></term>
+ <listitem>
+ <para>
+ The <varname>OID</varname> of the large object in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ &return.success;
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_lo_unlink</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ // OID of the large object to delete
+ $doc_oid = 189762345;
+ $database = pg_connect("dbname=jacarta");
+ pg_query($database, "begin");
+ pg_lo_unlink($database, $doc_oid);
+ pg_query($database, "commit");
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-lo-write.xml?r1=1.6&r2=1.7&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-lo-write.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-lo-write.xml:1.6
phpdoc/en/reference/pgsql/functions/pg-lo-write.xml:1.7
--- phpdoc/en/reference/pgsql/functions/pg-lo-write.xml:1.6 Fri Mar 11
11:03:25 2005
+++ phpdoc/en/reference/pgsql/functions/pg-lo-write.xml Wed Apr 13 23:21:36 2005
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-lo-write">
<refnamediv>
<refname>pg_lo_write</refname>
- <refpurpose>Write a large object</refpurpose>
+ <refpurpose>Write to a large object</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -16,14 +16,11 @@
<methodparam
choice="opt"><type>int</type><parameter>len</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_lo_write</function> writes at most to a large object
- from a variable <parameter>data</parameter> and returns the number
- of bytes actually written, or &false; in the case of an error.
- <parameter>large_object</parameter> is a large object resource
- from <function>pg_lo_open</function>.
+ <function>pg_lo_write</function> writes data into a large object
+ at the current seek position.
</para>
<para>
- To use the large object (lo) interface, it is necessary to
+ To use the large object interface, it is necessary to
enclose it within a transaction block.
</para>
<note>
@@ -33,6 +30,71 @@
</note>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>large_object</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL large object (LOB) resource, returned by
<function>pg_lo_open</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem>
+ <para>
+ The data to be written to the large object. If
<parameter>len</parameter> is
+ specified and is less than the length of <parameter>data</parameter>,
only
+ <parameter>len</parameter> bytes will be written.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>len</parameter></term>
+ <listitem>
+ <para>
+ An optional maximum number of bytes to write. Must be greater than zero
+ and no greater than the length of <parameter>data</parameter>.
Defaults to
+ the length of <parameter>data</parameter>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ The number of bytes written to the large object, or &false; on error.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_lo_write</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $doc_oid = 189762345;
+ $data = "This will overwrite the start of the large object.";
+ $database = pg_connect("dbname=jacarta");
+ pg_query($database, "begin");
+ $handle = pg_lo_open($database, $doc_oid, "w");
+ $data = pg_lo_write($handle, $data);
+ pg_query($database, "commit");
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
