separate some embedded
    SQL commands from C++ application code with a simple example.  In
    this example, the application is implemented in C++, while C and
    ECPG is used to connect to the PostgreSQL server.
   </para>

   <para>
    Three kinds of files have to be created: a C file
    (<filename>*.pgc</filename>), a header file, and a C++ file:

    <variablelist>
     <varlistentry id="ecpg-cpp-and-c-test-mod-pgc">
      <term><filename>test_mod.pgc</filename></term>
      <listitem>
       <para>
        A sub-routine module to execute SQL commands embedded in C.
        It is going to be converted
        into <filename>test_mod.c</filename> by the preprocessor.

<programlisting>
#include "test_mod.h"
#include &lt;stdio.h&gt;

void
db_connect()
{
    EXEC SQL CONNECT TO testdb1;
    EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
}

void
db_test()
{
    EXEC SQL BEGIN DECLARE SECTION;
    char dbname[1024];
    EXEC SQL END DECLARE SECTION;

    EXEC SQL SELECT current_database() INTO :dbname;
    printf("current_database = %s\n", dbname);
}

void
db_disconnect()
{
    EXEC SQL DISCONNECT ALL;
}
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-cpp-and-c-test-mod-h">
      <term><filename>test_mod.h</filename></term>
      <listitem>
       <para>
        A header file with declarations of the functions in the C
        module (<filename>test_mod.pgc</filename>).  It is included by
        <filename>test_cpp.cpp</filename>.  This file has to have an
        <literal>extern "C"</literal> block around the declarations,
        because it will be linked from the C++ module.

<programlisting>
#ifdef __cplusplus
extern "C" {
#endif

void db_connect();
void db_test();
void db_disconnect();

#ifdef __cplusplus
}
#endif
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ecpg-cpp-and-c-test-cpp-cpp">
      <term><filename>test_cpp.cpp</filename></term>
      <listitem>
       <para>
        The main code for the application, including
        the <function>main</function> routine, and in this example a
        C++ class.

<programlisting>
#include "test_mod.h"

class TestCpp
{
  public:
    TestCpp();
    void test();
    ~TestCpp();
};

TestCpp::TestCpp()
{
    db_connect();
}

void
TestCpp::test()
{
    db_test();
}

TestCpp::~TestCpp()
{
    db_disconnect();
}

int
main(void)
{
    TestCpp *t = new TestCpp();

    t->test();
    return 0;
}
</programlisting>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    To build the application, proceed as follows.  Convert
    <filename>test_mod.pgc</filename> into <filename>test_mod.c</filename> by
    running <command>ecpg</command>, and generate
    <filename>test_mod.o</filename> by compiling
    <filename>test_mod.c</filename> with the C compiler:
<programlisting>
ecpg -o test_mod.c test_mod.pgc
cc -c test_mod.c -o test_mod.o
</programlisting>
   </para>

   <para>
    Next, generate <filename>test_cpp.o</filename> by compiling
    <filename>test_cpp.cpp</filename> with the C++ compiler:
<programlisting>
c++ -c test_cpp.cpp -o test_cpp.o
</programlisting>
   </para>

   <para>
    Finally, link these object files, <filename>test_cpp.o</filename>
    and <filename>test_mod.o</filename>, into one executable, using the C++
    compiler driver:
<programlisting>
c++ test_cpp.o test_mod.o -lecpg -o test_cpp
</programlisting>
   </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-sql-commands">
  <title>Embedded SQL Commands</title>

  <para>
   This section describes all SQL commands that are specific to
   embedded SQL.  Also refer to the SQL commands listed
   in <xref linkend="sql-commands"/>, which can also be used in
   embedded SQL, unless stated otherwise.
  </para>

  <refentry id="ecpg-sql-allocate-descriptor">
   <refnamediv>
    <refname>ALLOCATE DESCRIPTOR</refname>
    <refpurpose>allocate an SQL descriptor