path: root/doc/src/sgml/ref/declare.sgml

<REFENTRY ID="SQL-DECLARE">
 <REFMETA>
  <REFENTRYTITLE>
   DECLARE
  </REFENTRYTITLE>
  <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
  <REFNAME>
   DECLARE
  </REFNAME>
  <REFPURPOSE>
   Defines a cursor for table access
  </REFPURPOSE>
 </refnamediv>
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-04</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>
DECLARE <replaceable class="parameter">cursor</replaceable> [ BINARY ] [ INSENSITIVE ] [ SCROLL ]
    CURSOR FOR <replaceable class="parameter">query</replaceable>
    [ FOR { READ ONLY | UPDATE [ OF <replaceable class="parameter">column</replaceable> [, ...] ] ]
  </SYNOPSIS>
  <REFSECT2 ID="R2-SQL-DECLARE-1">
   <REFSECT2INFO>
    <DATE>1998-04-15</DATE>
   </REFSECT2INFO>
   <TITLE>
    Inputs
   </TITLE>
   <PARA>
   </PARA>
       <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	 <replaceable class="parameter">cursor</replaceable>
	 </TERM>
	 <LISTITEM>
	  <PARA>
         The name of the cursor to be used in subsequent FETCH operations..
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	 BINARY
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   Causes the cursor to fetch data in binary
	   rather than in text format.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	 INSENSITIVE
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   <acronym>SQL92</acronym> keyword indicating that data retrieved
from the cursor should be unaffected by updates from other processes or cursors.
Since cursor operations occur within transactions
 in <productname>Postgres</productname> this is always the case.
This keyword has no effect.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	 SCROLL
	 </TERM>
	 <LISTITEM>
	  <PARA>
<acronym>SQL92</acronym> keyword indicating that data may be retrieved
in multiple rows per FETCH operation. Since this is allowed at all times
by <productname>Postgres</productname> this keyword has no effect.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	 <replaceable class="parameter">query</replaceable>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   An SQL query which will provide the rows to be governed by the
	   cursor.
	   Refer to the SELECT statement for further information about
	   valid arguments.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	 READ ONLY
	 </TERM>
	 <LISTITEM>
	  <PARA>
<acronym>SQL92</acronym> keyword indicating that the cursor will be used
in a readonly mode. Since this is the only cursor access mode
available in <productname>Postgres</productname> this keyword has no effect.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	 UPDATE
	 </TERM>
	 <LISTITEM>
	  <PARA>
<acronym>SQL92</acronym> keyword indicating that the cursor will be used
to update tables. Since cursor updates are not currently
supported in <productname>Postgres</productname> this keyword
provokes an informational error message.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	 <replaceable class="parameter">column</replaceable>
	 </TERM>
	 <LISTITEM>
	  <PARA>
Column(s) to be updated.
Since cursor updates are not currently
supported in <productname>Postgres</productname> the UPDATE clause
provokes an informational error message.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

   </VARIABLELIST>
  </REFSECT2>

  <REFSECT2 ID="R2-SQL-DECLARE-2">
   <REFSECT2INFO>
    <DATE>1998-04-15</DATE>
   </REFSECT2INFO>
   <TITLE>
    Outputs
   </TITLE>
   <PARA>

   <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	 SELECT
	 </TERM>
	 <LISTITEM>
	  <PARA>
          The message returned if the SELECT is run successfully.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
	   NOTICE
	   BlankPortalAssignName: portal "<replaceable class="parameter">cursor</replaceable>" already exists
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   This error occurs if cursor "<replaceable class="parameter">cursor</replaceable>" is already declared.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
	 <TERM>
ERROR:  Named portals may only be used in begin/end transaction blocks
	 </TERM>
	 <LISTITEM>
	  <PARA>
This error occurs if the cursor is not declared within a transaction block.
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>     
    </VARIABLELIST>
   </para>
  </REFSECT2>
 </REFSYNOPSISDIV>
 
 <REFSECT1 ID="R1-SQL-DECLARE-1">
  <REFSECT1INFO>
   <DATE>1998-09-04</DATE>
  </REFSECT1INFO>
  <TITLE>
   Description
  </TITLE>
  <PARA>
   DECLARE allows a user to create cursors, which can be used to retrieve
   a small number of rows at a time out of a larger query. Cursors can return
   data either in text or in binary foramt.
  </PARA>
  <PARA>
   Normal cursors return data  in text format, either ASCII or another
encoding scheme depending on how the <productname>Postgres</productname>
backend was built. Since
   data is stored natively in binary format, the system must
   do a conversion to produce the text format. In addition,
   text formats are often larger in size than the corresponding binary format.
   Once the information comes back in text form,  the client
   application may have to convert it to a binary format to
   manipulate it anyway.
  </PARA>
  <PARA>
   BINARY cursors give you back the data in the native binary
   representation. So binary cursors will tend to be a
   little faster since they suffer less conversion overhead.
  </para>
  <para>
   As an example, if a query returns a value of one from an integer column,
you would get a string of '1' with a default cursor
whereas with a binary cursor you would get
 a 4-byte value equal to control-A ('^A').
   <caution>
    <para>
     BINARY cursors should be used carefully. User applications such
     as <application>psql</application> are not aware of binary cursors
     and expect data to come back in a text format.
    </para>
   </caution>
  </para>
  <PARA>
   However, string representation is architecture-neutral whereas binary
   representation can differ between different machine architectures.
   Therefore, if your client machine and server machine use different
   representations (e.g. "big-endian" versus "little-endian"),
 you will probably not want your data returned in
   binary format.
   
   <tip>
    <para>
     If you intend to display the data in
     ASCII,  getting it back in ASCII will save you some
     effort on the client side.
    </para>
   </tip>
  </PARA>
  
  <REFSECT2 ID="R2-SQL-DECLARE-3">
   <REFSECT2INFO>
    <DATE>1998-09-04</DATE>
   </REFSECT2INFO>
   <TITLE>
    Notes
   </TITLE>
   <PARA>
    Cursors are only available in transactions.
   </PARA>
   <PARA>
    <productname>Postgres</productname>
    does not have an explicit <command>OPEN cursor</command>
    statement; a cursor is considered to be open when it is declared.
    
    <note>
     <para>
      In <acronym>SQL92</acronym> cursors are only available in
      embedded applications. <application>ecpg</application>, the
      embedded SQL preprocessor for <productname>Postgres</productname>,
      supports the <acronym>SQL92</acronym> conventions, including those
      involving DECLARE and OPEN statements.
     </para>
    </note>
    
   </PARA>
  </REFSECT2>
 </refsect1>
 
 <REFSECT1 ID="R1-SQL-DECLARESTATEMENT-2">
  <TITLE>
   Usage
  </TITLE>
  <PARA>
   To declare a cursor:
  </PARA>
  <ProgramListing>
DECLARE liahona CURSOR
    FOR SELECT * FROM films;
  </ProgramListing>
 </REFSECT1>

 <REFSECT1 ID="R1-SQL-DECLARESTATEMENT-3">
  <TITLE>
   Compatibility
  </TITLE>
  <PARA>
  </PARA>
  
  <REFSECT2 ID="R2-SQL-DECLARESTATEMENT-4">
   <REFSECT2INFO>
    <DATE>1998-04-15</DATE>
   </REFSECT2INFO>
   <TITLE>
    SQL92
   </TITLE>
   <PARA>
    <acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym>
    and in modules. <productname>Postgres</productname> permits cursors to be used
    interactively.
    <acronym>SQL92</acronym> allows embedded or modular cursors to
    update database information.
    All <productname>Postgres</productname> cursors are readonly.
    The BINARY keyword is a <productname>Postgres</productname> extension.
   </para>
  </refsect2>
 </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
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->