- More work on pgsql docs overhaul. All the pg_lo_* functions are now done.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@184314 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Christopher Kings-Lynne 2005-04-14 03:21:36 +00:00
parent 6926843be0
commit 4ee6ee268a
7 changed files with 443 additions and 39 deletions

View file

@ -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>

View file

@ -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>

View file

@ -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>

View file

@ -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>

View file

@ -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>

View file

@ -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>

View file

@ -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>