user-supplied values into statements or have the program process
   the values returned by the query.  Those kinds of statements are
   not really useful in real applications.  This section explains in
   detail how you can pass data between your C program and the
   embedded SQL statements using a simple mechanism called
   <firstterm>host variables</firstterm>. In an embedded SQL program we
   consider the SQL statements to be <firstterm>guests</firstterm> in the C
   program code which is the <firstterm>host language</firstterm>. Therefore
   the variables of the C program are called <firstterm>host
   variables</firstterm>.
  </para>

  <para>
   Another way to exchange values between PostgreSQL backends and ECPG
   applications is the use of SQL descriptors, described
   in <xref linkend="ecpg-descriptors"/>.
  </para>

  <sect2 id="ecpg-variables-overview">
   <title>Overview</title>

   <para>
    Passing data between the C program and the SQL statements is
    particularly simple in embedded SQL.  Instead of having the
    program paste the data into the statement, which entails various
    complications, such as properly quoting the value, you can simply
    write the name of a C variable into the SQL statement, prefixed by
    a colon.  For example:
<programlisting>
EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);
</programlisting>
    This statement refers to two C variables named
    <varname>v1</varname> and <varname>v2</varname> and also uses a
    regular SQL string literal, to illustrate that you are not
    restricted to use one kind of data or the other.
   </para>

   <para>
    This style of inserting C variables in SQL statements works
    anywhere a value expression is expected in an SQL statement.
   </para>
  </sect2>

  <sect2 id="ecpg-declare-sections">
   <title>Declare Sections</title>

   <para>
    To pass data from the program to the database, for example as
    parameters in a query, or to pass data from the database back to
    the program, the C variables that are intended to contain this
    data need to be declared in specially marked sections, so the
    embedded SQL preprocessor is made aware of them.
   </para>

   <para>
    This section starts with:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
</programlisting>
    and ends with:
<programlisting>
EXEC SQL END DECLARE SECTION;
</programlisting>
    Between those lines, there must be normal C variable declarations,
    such as:
<programlisting>
int   x = 4;
char  foo[16], bar[16];
</programlisting>
    As you can see, you can optionally assign an initial value to the variable.
    The variable's scope is determined by the location of its declaring
    section within the program.
    You can also declare variables with the following syntax which implicitly
    creates a declare section:
<programlisting>
EXEC SQL int i = 4;
</programlisting>
    You can have as many declare sections in a program as you like.
   </para>

   <para>
    The 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