wez Mon Nov 28 23:07:04 2005 EDT
Added files:
/phpdoc/en/reference/pdo_pgsql/functions PDO-pgsqlLOBCreate.xml
PDO-pgsqlLOBOpen.xml
PDO-pgsqlLOBUnlink.xml
Log:
Document new lob functions
http://cvs.php.net/co.php/phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBCreate.xml?r=1.1&p=1
Index: phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBCreate.xml
+++ phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBCreate.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Generated by xml_proto.php v2.3. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-pgsqlLOBCreate">
<refnamediv>
<refname>PDO::pgsqlLOBCreate</refname>
<refpurpose>Creates a new large object, returning its identifier. Must be
called inside a transaction.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>PDO::pgsqlLOBCreate</methodname>
<void/>
</methodsynopsis>
<para>
<function>PDO::pgsqlLOBCreate</function> creates a large object and
returns the OID of that object. You may then open a stream on the object
using <function>PDO::pgsqlLOBOpen</function> to read or write data to
it. The OID can be stored in columns of type OID and be used to reference
the large object, without causing the row to grow arbitrarily large.
The large object will continue to live in the database until it
is removed by calling <function>PDO::pgsqlLOBUnlink</function>.
</para>
<para>
Large objects can be up to 2GB in size, but are cumbersome to use; you need
to ensure that <function>PDO::pgsqlLOBUnlink</function> is called prior
to deleting the last row that references its OID from your database.
In addition, large objects have no access controls. As an alternative,
try the bytea column type; recent versions of PostgreSQL allow bytea
columns of up to 1GB in size and transparently manage the storage for
optimal row size.
</para>
<note>
<simpara>
This function must be called within a transaction.
</simpara>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<function>PDO::pgsqlLOBCreate</function> takes no parameters.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the OID of the newly created large object on success, or &false;
on failure.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PDO::pgsqlLOBCreate</function> example</title>
<para>
This example creates a new large object and copies the contents
of a file into it. The OID is then stored into a table.
</para>
<programlisting role="php">
<![CDATA[
<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$oid = $db->pgsqlLOBCreate();
$stream = $db->pgsqlLOBOpen($oid, 'w');
$local = fopen($filename, 'rb');
stream_copy_to_stream($local, $stream);
$local = null;
$stream = null;
$stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
$stmt->execute(array($some_id, $oid));
$db->commit();
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::pgsqlLOBOpen</function></member>
<member><function>PDO::pgsqlLOBCreate</function></member>
<member><function>pg_lo_create</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/co.php/phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBOpen.xml?r=1.1&p=1
Index: phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBOpen.xml
+++ phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBOpen.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Generated by xml_proto.php v2.3. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-pgsqlLOBOpen">
<refnamediv>
<refname>PDO::pgsqlLOBOpen</refname>
<refpurpose>Opens an existing large object stream. Must be called inside a
transaction.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>PDO::pgsqlLOBOpen</methodname>
<methodparam><type>string</type><parameter>oid</parameter></methodparam>
<methodparam
choice="opt"><type>string</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
<function>PDO::pgsqlLOBOpen</function> opens a stream to access the data
referenced by <parameter>oid</parameter>. If <parameter>mode</parameter>
is <literal>r</literal>, the stream is opened for reading, if
<parameter>mode</parameter> is <literal>w</literal>, then the stream will
be opened for writing. You can use all the usual filesystem functions,
such as <function>fread</function>, <function>fwrite</function> and
<function>fgets</function> to manipulate the contents of the stream.
</para>
<note>
<simpara>
This function, and all manipulations of the large object,
must be called and carried out within a transaction.
</simpara>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>oid</parameter></term>
<listitem>
<para>
A large object identifier.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
If mode is <literal>r</literal>, open the stream for reading.
If mode is <literal>w</literal>, open the stream for writing.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a stream resource on success, of &false; on failure.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PDO::pgsqlLOBOpen</function> example</title>
<para>
Following on from the <function>PDO::pgsqlLOBCreate</function>
example, this code snippet retrieves the large object from
the database and outputs it to the browser.
</para>
<programlisting role="php">
<![CDATA[
<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$stmt = $db->prepare("select oid from BLOBS where ident = ?");
$stmt->execute(array($some_id));
$stmt->bindColumn('oid', $lob, PDO::PARAM_LOB);
$stmt->fetch(PDO::FETCH_BOUND);
fpassthru($lob);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::pgsqlLOBCreate</function></member>
<member><function>PDO::pgsqlLOBUnlink</function></member>
<member><function>pg_lo_open</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/co.php/phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBUnlink.xml?r=1.1&p=1
Index: phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBUnlink.xml
+++ phpdoc/en/reference/pdo_pgsql/functions/PDO-pgsqlLOBUnlink.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Generated by xml_proto.php v2.3. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-pgsqlLOBUnlink">
<refnamediv>
<refname>PDO::pgsqlLOBUnlink</refname>
<refpurpose>Deletes the large object identified by oid. Must be called inside
a transaction.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PDO::pgsqlLOBUnlink</methodname>
<methodparam><type>string</type><parameter>oid</parameter></methodparam>
</methodsynopsis>
<para>
Deletes a large object from the database.
</para>
<note>
<simpara>
This function must be called within a transaction.
</simpara>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>oid</parameter></term>
<listitem>
<para>
The large object identifier
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PDO::pgsqlLOBUnlink</function> example</title>
<para>
This example unlinks a large object from the database prior to deleting
the row that references it from the blobs table we've been using in
our <function>PDO::pgsqlLOBCreate</function> and
<function>PDO::pgsqlLOBOpen</function> examples.
</para>
<programlisting role="php">
<![CDATA[
<?php
$db = new PDO('pgsql:dbname=test host=localhost', $user, $pass);
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->beginTransaction();
$db->pgsqlLOBUnlink($oid);
$stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
$stmt->execute(array($some_id));
$db->commit();
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::pgsqlLOBOpen</function></member>
<member><function>PDO::pgsqlLOBCreate</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
