<!-- doc/src/sgml/ecpg.sgml -->

<chapter id="ecpg">
 <title><application>ECPG</application> &mdash; Embedded <acronym>SQL</acronym> in C</title>

 <indexterm zone="ecpg"><primary>embedded SQL</primary><secondary>in C</secondary></indexterm>
 <indexterm zone="ecpg"><primary>C</primary></indexterm>
 <indexterm zone="ecpg"><primary>ECPG</primary></indexterm>

 <para>
  This chapter describes the embedded <acronym>SQL</acronym> package
  for <productname>PostgreSQL</productname>. It was written by
  Linus Tolke (<email>linus@epact.se</email>) and Michael Meskes
  (<email>meskes@postgresql.org</email>). Originally it was written to work with
  <acronym>C</acronym>. It also works with <acronym>C++</acronym>, but
  it does not recognize all <acronym>C++</acronym> constructs yet.
 </para>

 <para>
  This documentation is quite incomplete.  But since this
  interface is standardized, additional information can be found in
  many resources about SQL.
 </para>

 <sect1 id="ecpg-concept">
  <title>The Concept</title>

  <para>
   An embedded SQL program consists of code written in an ordinary
   programming language, in this case C, mixed with SQL commands in
   specially marked sections.  To build the program, the source code (<filename>*.pgc</filename>)
   is first passed through the embedded SQL preprocessor, which converts it
   to an ordinary C program (<filename>*.c</filename>), and afterwards it can be processed by a C
   compiler.  (For details about the compiling and linking see <xref linkend="ecpg-process"/>.)
   Converted ECPG applications call functions in the libpq library
   through the embedded SQL library (ecpglib), and communicate with
   the PostgreSQL server using the normal frontend-backend protocol.
  </para>

  <para>
   Embedded <acronym>SQL</acronym> has advantages over other methods
   for handling <acronym>SQL</acronym> commands from C code. First, it
   takes care of the tedious passing of information to and from
   variables in your <acronym>C</acronym> program.  Second, the SQL
   code in the program is checked at build time for syntactical
   correctness.  Third, embedded <acronym>SQL</acronym> in C is
   specified in the <acronym>SQL</acronym> standard and supported by
   many other <acronym>SQL</acronym> database systems.  The
   <productname>PostgreSQL</productname> implementation is designed to match this
   standard as much as possible, and it is usually possible to port
   embedded <acronym>SQL</acronym> programs written for other SQL
   databases to <productname>PostgreSQL</productname> with relative
   ease.
  </para>

  <para>
   As already stated, programs written for the embedded
   <acronym>SQL</acronym> interface are normal C programs with special
   code inserted to perform database-related actions.  This special
   code always has the form:
<programlisting>
EXEC SQL ...;
</programlisting>
   These statements syntactically take the place of a C statement.
   Depending on the particular statement, they can appear at the
   global level or within a function.
  </para>

  <para>
   Embedded
   <acronym>SQL</acronym> statements follow the case-sensitivity rules of
   normal <acronym>SQL</acronym> code, and not those of C. Also they allow nested
   C-style comments as per the SQL standard. The C part of the
   program, however, follows the C standard of not accepting nested comments.
   Embedded <acronym>SQL</acronym> statements likewise use SQL rules, not
   C rules, for parsing quoted strings and identifiers.
   (See <xref linkend="sql-syntax-strings"/> and
   <xref linkend="sql-syntax-identifiers"/> respectively.  Note that
   ECPG assumes that <varname>standard_conforming_strings</varname>
   is <literal>on</literal>.)
   Of course, the C part of the program follows C quoting rules.
  </para>

  <para>
   The following sections explain all the embedded SQL statements.
  </para>
 </sect1>

 <sect1 id="ecpg-connect">
  <title>Managing Database Connections</title>

  <para>
   This section describes