granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/move.sgml

   1 <!--
   2 doc/src/sgml/ref/move.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-MOVE">
   7  <refmeta>
   8   <refentrytitle>MOVE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>MOVE</refname>
  15   <refpurpose>position a cursor</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-move">
  19   <primary>MOVE</primary>
  20  </indexterm>
  21
  22  <indexterm zone="sql-move">
  23   <primary>cursor</primary>
  24   <secondary>MOVE</secondary>
  25  </indexterm>
  26
  27  <refsynopsisdiv>
  28 <!-- Note the "direction" bit is also in ref/fetch.sgml -->
  29 <synopsis>
  30 MOVE [ <replaceable class="PARAMETER">direction</replaceable> [ FROM | IN ] ] <replaceable class="PARAMETER">cursor_name</replaceable>
  31
  32 <phrase>where <replaceable class="PARAMETER">direction</replaceable> can be empty or one of:</phrase>
  33
  34     NEXT
  35     PRIOR
  36     FIRST
  37     LAST
  38     ABSOLUTE <replaceable class="PARAMETER">count</replaceable>
  39     RELATIVE <replaceable class="PARAMETER">count</replaceable>
  40     <replaceable class="PARAMETER">count</replaceable>
  41     ALL
  42     FORWARD
  43     FORWARD <replaceable class="PARAMETER">count</replaceable>
  44     FORWARD ALL
  45     BACKWARD
  46     BACKWARD <replaceable class="PARAMETER">count</replaceable>
  47     BACKWARD ALL
  48 </synopsis>
  49  </refsynopsisdiv>
  50
  51  <refsect1>
  52   <title>Description</title>
  53
  54   <para>
  55    <command>MOVE</command> repositions a cursor without retrieving any data.
  56    <command>MOVE</command> works exactly like the <command>FETCH</command>
  57    command, except it only positions the cursor and does not return rows.
  58   </para>
  59
  60   <para>
  61    The parameters for the <command>MOVE</command> command are identical to
  62    those of the <command>FETCH</command> command; refer to
  63    <xref linkend="sql-fetch">
  64    for details on syntax and usage.
  65   </para>
  66  </refsect1>
  67
  68  <refsect1>
  69   <title>Outputs</title>
  70
  71   <para>
  72    On successful completion, a <command>MOVE</> command returns a command
  73    tag of the form
  74 <screen>
  75 MOVE <replaceable class="parameter">count</replaceable>
  76 </screen>
  77    The <replaceable class="parameter">count</replaceable> is the number
  78    of rows that a <command>FETCH</command> command with the same parameters
  79    would have returned (possibly zero).
  80   </para>
  81  </refsect1>
  82
  83  <refsect1>
  84   <title>Examples</title>
  85
  86 <programlisting>
  87 BEGIN WORK;
  88 DECLARE liahona CURSOR FOR SELECT * FROM films;
  89
  90 -- Skip the first 5 rows:
  91 MOVE FORWARD 5 IN liahona;
  92 MOVE 5
  93
  94 -- Fetch the 6th row from the cursor liahona:
  95 FETCH 1 FROM liahona;
  96  code  | title  | did | date_prod  |  kind  |  len
  97 -------+--------+-----+------------+--------+-------
  98  P_303 | 48 Hrs | 103 | 1982-10-22 | Action | 01:37
  99 (1 row)
 100
 101 -- Close the cursor liahona and end the transaction:
 102 CLOSE liahona;
 103 COMMIT WORK;
 104 </programlisting>
 105  </refsect1>
 106
 107  <refsect1>
 108   <title>Compatibility</title>
 109
 110   <para>
 111    There is no <command>MOVE</command> statement in the SQL standard.
 112   </para>
 113  </refsect1>
 114
 115  <refsect1>
 116   <title>See Also</title>
 117
 118   <simplelist type="inline">
 119    <member><xref linkend="sql-close"></member>
 120    <member><xref linkend="sql-declare"></member>
 121    <member><xref linkend="sql-fetch"></member>
 122   </simplelist>
 123  </refsect1>
 124 </refentry>