declarations are also echoed to the output file as normal C
    variables, so there's no need to declare them again.  Variables
    that are not intended to be used in SQL commands can be declared
    normally outside these special sections.
   </para>

   <para>
    The definition of a structure or union also must be listed inside
    a <literal>DECLARE</literal> section. Otherwise the preprocessor cannot
    handle these types since it does not know the definition.
   </para>
  </sect2>

  <sect2 id="ecpg-retrieving">
   <title>Retrieving Query Results</title>

   <para>
    Now you should be able to pass data generated by your program into
    an SQL command.  But how do you retrieve the results of a query?
    For that purpose, embedded SQL provides special variants of the
    usual commands <command>SELECT</command> and
    <command>FETCH</command>.  These commands have a special
    <literal>INTO</literal> clause that specifies which host variables
    the retrieved values are to be stored in.
    <command>SELECT</command> is used for a query that returns only
    single row, and <command>FETCH</command> is used for a query that
    returns multiple rows, using a cursor.
   </para>

   <para>
    Here is an example:
<programlisting>
/*
 * assume this table:
 * CREATE TABLE test1 (a int, b varchar(50));
 */

EXEC SQL BEGIN DECLARE SECTION;
int v1;
VARCHAR v2;
EXEC SQL END DECLARE SECTION;

 ...

EXEC SQL SELECT a, b INTO :v1, :v2 FROM test;
</programlisting>
    So the <literal>INTO</literal> clause appears between the select
    list and the <literal>FROM</literal> clause.  The number of
    elements in the select list and the list after
    <literal>INTO</literal> (also called the target list) must be
    equal.
   </para>

   <para>
    Here is an example using the command <command>FETCH</command>:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
int v1;
VARCHAR v2;
EXEC SQL END DECLARE SECTION;

 ...

EXEC SQL DECLARE foo CURSOR FOR SELECT a, b FROM test;

 ...

do
{
    ...
    EXEC SQL FETCH NEXT FROM foo INTO :v1, :v2;
    ...
} while (...);
</programlisting>
    Here the <literal>INTO</literal> clause appears after all the
    normal clauses.
   </para>

  </sect2>

  <sect2 id="ecpg-variables-type-mapping">
   <title>Type Mapping</title>

   <para>
    When ECPG applications exchange values between the PostgreSQL
    server and the C application, such as when retrieving query
    results from the server or executing SQL statements with input
    parameters, the values need to be converted between PostgreSQL
    data types and host language variable types (C language data
    types, concretely).  One of the main points of ECPG is that it
    takes care of this automatically in most cases.
   </para>

   <para>
    In this respect, there are two kinds of data types: Some simple
    PostgreSQL data types, such as <type>integer</type>
    and <type>text</type>, can be read and written by the application
    directly.  Other PostgreSQL data types, such
    as <type>timestamp</type> and <type>numeric</type> can only be
    accessed through special library functions; see
    <xref linkend="ecpg-special-types"/>.
   </para>

   <para>
    <xref linkend="ecpg-datatype-hostvars-table"/> shows which PostgreSQL
    data types correspond to which C data types.  When you wish to
    send or receive a value of a given PostgreSQL data type, you
    should declare a C variable of the corresponding C data type in
    the declare section.
   </para>

   <table id="ecpg-datatype-hostvars-table">
    <title>Mapping Between PostgreSQL Data Types and C Variable Types</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>PostgreSQL data type</entry>
       <entry>Host variable type</entry>
      </row>
     </thead>

     <tbody>
      <row>
       <entry><type>smallint</type></entry>
       <entry><type>short</type></entry>
      </row>

      <row>
       <entry><type>integer</type></entry>
       <entry><type>int</type></entry>