</para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-named-descriptors-returned-length">
      <term><literal>RETURNED_LENGTH</literal> (integer)</term>
      <listitem>
       <para>
        length of the datum in characters
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-named-descriptors-returned-octet-length">
      <term><literal>RETURNED_OCTET_LENGTH</literal> (integer)</term>
      <listitem>
       <para>
        length of the character representation of the datum in bytes
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-named-descriptors-scale">
      <term><literal>SCALE</literal> (integer)</term>
      <listitem>
       <para>
        scale (for type <type>numeric</type>)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-named-descriptors-type">
      <term><literal>TYPE</literal> (integer)</term>
      <listitem>
       <para>
        numeric code of the data type of the column
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    In <command>EXECUTE</command>, <command>DECLARE</command> and <command>OPEN</command>
    statements, the effect of the <literal>INTO</literal> and <literal>USING</literal>
    keywords are different. A Descriptor Area can also be manually built to
    provide the input parameters for a query or a cursor and
    <literal>USING SQL DESCRIPTOR <replaceable>name</replaceable></literal>
    is the way to pass the input parameters into a parameterized query. The statement
    to build a named SQL Descriptor Area is below:
<programlisting>
EXEC SQL SET DESCRIPTOR <replaceable>name</replaceable> VALUE <replaceable>num</replaceable> <replaceable>field</replaceable> = :<replaceable>hostvar</replaceable>;
</programlisting>
   </para>

   <para>
    PostgreSQL supports retrieving more that one record in one <command>FETCH</command>
    statement and storing the data in host variables in this case assumes that the
    variable is an array. E.g.:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
int id[5];
EXEC SQL END DECLARE SECTION;

EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc;

EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :id = DATA;
</programlisting>

   </para>

  </sect2>

  <sect2 id="ecpg-sqlda-descriptors">
   <title>SQLDA Descriptor Areas</title>

   <para>
    An SQLDA Descriptor Area is a C language structure which can be also used
    to get the result set and the metadata of a query. One structure stores one
    record from the result set.
<programlisting>
EXEC SQL include sqlda.h;
sqlda_t         *mysqlda;

EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda;
</programlisting>
    Note that the <literal>SQL</literal> keyword is omitted. The paragraphs about
    the use cases of the <literal>INTO</literal> and <literal>USING</literal>
    keywords in <xref linkend="ecpg-named-descriptors"/> also apply here with an addition.
    In a <command>DESCRIBE</command> statement the <literal>DESCRIPTOR</literal>
    keyword can be completely omitted if the <literal>INTO</literal> keyword is used:
<programlisting>
EXEC SQL DESCRIBE prepared_statement INTO mysqlda;
</programlisting>
   </para>

    <procedure>
     <para>
      The general flow of a program that uses SQLDA is:
     </para>
     <step><simpara>Prepare a query, and declare a cursor for it.</simpara></step>
     <step><simpara>Declare an SQLDA for the result rows.</simpara></step>
     <step><simpara>Declare an SQLDA for the input parameters, and initialize them (memory allocation, parameter settings).</simpara></step>
     <step><simpara>Open a cursor with the input SQLDA.</simpara></step>
     <step><simpara>Fetch rows from the cursor, and store them into an output SQLDA.</simpara></step>
     <step><simpara>Read values from the output SQLDA into the host variables (with conversion if necessary).</simpara></step>
     <step><simpara>Close the cursor.</simpara></step>