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 how to open, close, and switch database
   connections.
  </para>

  <sect2 id="ecpg-connecting">
   <title>Connecting to the Database Server</title>

  <para>
   One connects to a database using the following statement:
<programlisting>
EXEC SQL CONNECT TO <replaceable>target</replaceable> <optional>AS <replaceable>connection-name</replaceable></optional> <optional>USER <replaceable>user-name</replaceable></optional>;
</programlisting>
   The <replaceable>target</replaceable> can be specified in the
   following ways:

   <itemizedlist>
    <listitem>
     <simpara>
      <literal><replaceable>dbname</replaceable><optional>@<replaceable>hostname</replaceable></optional><optional>:<replaceable>port</replaceable></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>tcp:postgresql://<replaceable>hostname</replaceable><optional>:<replaceable>port</replaceable></optional><optional>/<replaceable>dbname</replaceable></optional><optional>?<replaceable>options</replaceable></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>unix:postgresql://localhost<optional>:<replaceable>port</replaceable></optional><optional>/<replaceable>dbname</replaceable></optional><optional>?<replaceable>options</replaceable></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      an SQL string literal containing one of the above forms
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      a reference to a character variable containing one of the above forms (see examples)
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>DEFAULT</literal>
     </simpara>
    </listitem>
   </itemizedlist>

   The connection target <literal>DEFAULT</literal> initiates a connection
   to the default database under the default user name.  No separate
   user name or connection name can be specified in that case.
  </para>

  <para>
   If you specify the connection target directly (that is, not as a string
   literal or variable reference), then the components of the target are
   passed through normal SQL parsing; this means that, for example,
   the <replaceable>hostname</replaceable> must look like one or more SQL
   identifiers separated by dots, and those identifiers will be
   case-folded unless double-quoted.  Values of
   any <replaceable>options</replaceable> must be SQL identifiers,
   integers, or variable references.  Of course, you can put nearly
   anything into an SQL identifier by double-quoting it.
   In practice, it is probably less error-prone to use a (single-quoted)
   string literal or a variable reference than to write the connection
   target directly.
  </para>

  <para>
   There are also different ways to specify the user name:

   <itemizedlist>
    <listitem>
     <simpara>
      <literal><replaceable>username</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal><replaceable>username</replaceable>/<replaceable>password</replaceable></literal>