cvs: phpdoc /en/reference/pdo_pgsql/functions PDO-pgsqlLOBCreate.xml PDO-pgsqlLOBOpen.xml PDO-pgsqlLOBUnlink.xml

From:	Wez Furlong	Date:	Tue, 29 Nov 2005 04:07:04 +0000
Subject:	cvs: phpdoc /en/reference/pdo_pgsql/functions PDO-pgsqlLOBCreate.xml PDO-pgsqlLOBOpen.xml PDO-pgsqlLOBUnlink.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969371041@lists.php.net to get a copy of this message

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"?>   <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>  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"?>   <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>  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"?>   <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>