libpgtcl.sgml

PostgreSQL7.4.6 for Linux

   the number requested if the end of the large object is reached first.
   In event of an error, the return value is negative.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOWRITE">
 <refmeta>
  <refentrytitle>pg_lo_write</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_write</refname>
  <refpurpose>write to a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOWRITE-2"><primary>pg_lo_write</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_write <parameter>conn</parameter> <parameter>descriptor</parameter> <parameter>buf</parameter> <parameter>len</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_write</function> writes at most
   <parameter>len</parameter> bytes from a variable
   <parameter>buf</parameter> to a large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>buf</parameter></term>
    <listitem>
     <para>
      The string to write to the large object (not a variable name,
      but the value itself).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>len</parameter></term>
    <listitem>
     <para>
      The maximum number of bytes to write.  The number written will
      be the smaller of this value and the length of the string.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   The number of bytes actually written is returned; this will ordinarily
   be the same as the number requested.
   In event of an error, the return value is negative.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOLSEEK">
 <refmeta>
  <refentrytitle>pg_lo_lseek</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_lseek</refname>
  <refpurpose>seek to a position of a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOLSEEK-2"><primary>pg_lo_lseek</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_lseek <parameter>conn</parameter> <parameter>descriptor</parameter> <parameter>offset</parameter> <parameter>whence</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_lseek</function> moves the current read/write
   position to <parameter>offset</parameter> bytes from the position
   specified by <parameter>whence</parameter>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>offset</parameter></term>
    <listitem>
     <para>
      The new seek position in bytes.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>whence</parameter></term>
    <listitem>
     <para>
      Specified from where to calculate the new seek position:
      <literal>SEEK_CUR</> (from current position),
      <literal>SEEK_END</> (from end), or <literal>SEEK_SET</> (from
      start).
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOTELL">
 <refmeta>
  <refentrytitle>pg_lo_tell</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_tell</refname>
  <refpurpose>return the current seek position of a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOTELL-2"><primary>pg_lo_tell</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_tell <parameter>conn</parameter> <parameter>descriptor</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_tell</function> returns the current read/write
   position in bytes from the beginning of the large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>

    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   A zero-based offset in bytes suitable for input to
   <function>pg_lo_lseek</function>.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOUNLINK">
 <refmeta>
  <refentrytitle>pg_lo_unlink</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_unlink</refname>
  <refpurpose>delete a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOUNLINK-2"><primary>pg_lo_unlink</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_unlink <parameter>conn</parameter> <parameter>loid</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_unlink</function> deletes the specified large
   object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>loid</parameter></term>
    <listitem>
     <para>
      The OID of the large object.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOIMPORT">
 <refmeta>
  <refentrytitle>pg_lo_import</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_import</refname>
  <refpurpose>import a large object from a file</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOIMPORT-2"><primary>pg_lo_import</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_import <parameter>conn</parameter> <parameter>filename</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_import</function> reads the specified file and
   places the contents into a new large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which to create the large
      object.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>filename</parameter></term>
    <listitem>
     <para>
      Specified the file from which to import the data.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   The OID of the large object created.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   <function>pg_lo_import</function> must be called within a
   <command>BEGIN</>/<command>COMMIT</> transaction block.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOEXPORT">
 <refmeta>
  <refentrytitle>pg_lo_export</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_export</refname>
  <refpurpose>export a large object to a file</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOEXPORT-2"><primary>pg_lo_export</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_export <parameter>conn</parameter> <parameter>loid</parameter> <parameter>filename</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_export</function> writes the specified large object
   into a file.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>loid</parameter></term>
    <listitem>
     <para>
      The OID of the large object.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>filename</parameter></term>
    <listitem>
     <para>
      Specifies the file into which the data is to be exported.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>
  <para>
   None
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   <function>pg_lo_export</function> must be called within a
   <command>BEGIN</>/<command>COMMIT</> transaction block.
  </para>
 </refsect1>
</refentry>

</sect1>


<sect1 id="pgtcl-examplesect">
 <title>Example Program</title>

 <para>
  <xref linkend="pgtcl-example"> shows a small example of how to use
  the <application>pgtcl</application> commands.
 </para>

 <example id="pgtcl-example">
  <title><application>pgtcl</application> Example Program</title>

<programlisting>
# getDBs :
#   get the names of all the databases at a given host and port number
#   with the defaults being the localhost and port 5432
#   return them in alphabetical order
proc getDBs { {host "localhost"} {port "5432"} } {
    # datnames is the list to be result
    set conn [pg_connect template1 -host $host -port $port]
    set res [pg_exec $conn "SELECT datname FROM pg_database ORDER BY datname;"]
    set ntups [pg_result $res -numTuples]
    for {set i 0} {$i < $ntups} {incr i} {
	lappend datnames [pg_result $res -getTuple $i]
    }
    pg_result $res -clear
    pg_disconnect $conn
    return $datnames
}
</programlisting>
  </example>
 </sect1>

</chapter>