class="parameter">descriptor_name</replaceable> VALUE <replaceable class="parameter">column_number</replaceable> <replaceable class="parameter">:cvariable</replaceable> = <replaceable class="parameter">descriptor_item</replaceable> [, ... ]
</synopsis>
   </refsynopsisdiv>

   <refsect1>
    <title>Description</title>

    <para>
     <command>GET DESCRIPTOR</command> retrieves information about a
     query result set from an SQL descriptor area and stores it into
     host variables.  A descriptor area is typically populated
     using <command>FETCH</command> or <command>SELECT</command>
     before using this command to transfer the information into host
     language variables.
    </para>

    <para>
     This command has two forms: The first form retrieves
     descriptor <quote>header</quote> items, which apply to the result
     set in its entirety.  One example is the row count.  The second
     form, which requires the column number as additional parameter,
     retrieves information about a particular column.  Examples are
     the column name and the actual column value.
    </para>
   </refsect1>

   <refsect1>
    <title>Parameters</title>

    <variablelist>
     <varlistentry id="ecpg-sql-get-descriptor-descriptor-name">
      <term><replaceable class="parameter">descriptor_name</replaceable></term>
      <listitem>
       <para>
        A descriptor name.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-sql-get-descriptor-descriptor-header-item">
      <term><replaceable class="parameter">descriptor_header_item</replaceable></term>
      <listitem>
       <para>
        A token identifying which header information item to retrieve.
        Only <literal>COUNT</literal>, to get the number of columns in the
        result set, is currently supported.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-sql-get-descriptor-column-number">
      <term><replaceable class="parameter">column_number</replaceable></term>
      <listitem>
       <para>
        The number of the column about which information is to be
        retrieved.  The count starts at 1.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-sql-get-descriptor-descriptor-item">
      <term><replaceable class="parameter">descriptor_item</replaceable></term>
      <listitem>
       <para>
        A token identifying which item of information about a column
        to retrieve.  See <xref linkend="ecpg-named-descriptors"/> for
        a list of supported items.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-sql-get-descriptor-cvariable">
      <term><replaceable class="parameter">cvariable</replaceable></term>
      <listitem>
       <para>
        A host variable that will receive the data retrieved from the
        descriptor area.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>

   <refsect1>
    <title>Examples</title>

    <para>
     An example to retrieve the number of columns in a result set:
<programlisting>
EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
</programlisting>
    </para>

    <para>
     An example to retrieve a data length in the first column:
<programlisting>
EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
</programlisting>
    </para>

    <para>
     An example to retrieve the data body of the second column as a
     string:
<programlisting>
EXEC SQL GET DESCRIPTOR d VALUE 2 :d_data = DATA;
</programlisting>
    </para>

    <para>
     Here is an example for a whole procedure of
     executing <literal>SELECT current_database();</literal> and showing the number of
     columns, the column data length, and the column data:
<programlisting>
int
main(void)
{
EXEC SQL BEGIN DECLARE SECTION;
    int  d_count;
    char d_data[1024];
    int  d_returned_octet_length;
EXEC SQL END DECLARE SECTION;

    EXEC SQL CONNECT TO testdb AS con1