cvs: 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

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>