<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 USER testuser;
    EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
    EXEC SQL ALLOCATE DESCRIPTOR d;

    /* Declare, open a cursor, and assign a descriptor to the cursor  */
    EXEC SQL DECLARE cur CURSOR FOR SELECT current_database();
    EXEC SQL OPEN cur;
    EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d;

    /* Get a number of total columns */
    EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
    printf("d_count                 = %d\n", d_count);

    /* Get length of a returned column */
    EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
    printf("d_returned_octet_length = %d\n", d_returned_octet_length);

    /* Fetch the returned column as a string */
    EXEC SQL GET DESCRIPTOR d VALUE 1 :d_data = DATA;
    printf("d_data                  = %s\n", d_data);

    /* Closing */
    EXEC SQL CLOSE cur;
    EXEC SQL COMMIT;

    EXEC SQL DEALLOCATE DESCRIPTOR d;
    EXEC SQL DISCONNECT ALL;

    return 0;
}
</programlisting>
     When the example is executed, the result will look like this:
<screen>
d_count                 = 1
d_returned_octet_length = 6
d_data                  = testdb
</screen>
    </para>
   </refsect1>

   <refsect1>
    <title>Compatibility</title>

    <para>
     <command>GET DESCRIPTOR</command> is specified in the SQL standard.
    </para>
   </refsect1>

   <refsect1>
    <title>See Also</title>

    <simplelist type="inline">
     <member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
     <member><xref linkend="ecpg-sql-set-descriptor"/></member>
    </simplelist>
   </refsect1>
  </refentry>

  <refentry id="ecpg-sql-open">
   <refnamediv>
    <refname>OPEN</refname>
    <refpurpose>open a dynamic cursor</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
<synopsis>
OPEN <replaceable class="parameter">cursor_name</replaceable>
OPEN <replaceable class="parameter">cursor_name</replaceable> USING <replaceable class="parameter">value</replaceable> [, ... ]
OPEN <replaceable class="parameter">cursor_name</replaceable> USING SQL DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable>
</synopsis>
   </refsynopsisdiv>

   <refsect1>
    <title>Description</title>

    <para>
     <command>OPEN</command> opens a cursor and optionally binds
     actual values to the placeholders in the cursor's declaration.
     The cursor must previously have been declared with
     the <command>DECLARE</command> command.  The execution
     of <command>OPEN</command> causes the query to start executing on
     the server.
    </para>
   </refsect1>

   <refsect1>
    <title>Parameters</title>

    <variablelist>
     <varlistentry id="ecpg-sql-open-cursor-name">
      <term><replaceable class="parameter">cursor_name</replaceable></term>
      <listitem>
       <para>
        The name of the cursor to be opened.  This can be an SQL
        identifier or a host variable.
       </para>
      </listitem>
     </varlistentry>