ecpg.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-244 (<symbol>ECPG_VAR_NOT_CHAR</symbol>)</term>
     <listitem>
      <para>
       During the execution of a dynamic statement, the database
       returned a non-numeric value and the host variable was numeric.
       (SQLSTATE 07006)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-400 (<symbol>ECPG_PGSQL</symbol>)</term>
     <listitem>
      <para>
       Some error caused by the <productname>PostgreSQL</productname>
       server.  The message contains the error message from the
       <productname>PostgreSQL</productname> server.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-401 (<symbol>ECPG_TRANS</symbol>)</term>
     <listitem>
      <para>
       The <productname>PostgreSQL</productname> server signaled that
       we cannot start, commit, or rollback the transaction.
       (SQLSTATE 08007)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-402 (<symbol>ECPG_CONNECT</symbol>)</term>
     <listitem>
      <para>
       The connection attempt to the database did not succeed.
       (SQLSTATE 08001)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>100 (<symbol>ECPG_NOT_FOUND</symbol>)</term>
     <listitem>
      <para>
       This is a harmless condition indicating that the last command
       retrieved or processed zero rows, or that you are at the end of
       the cursor.  (SQLSTATE 02000)
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-include">
  <title>Including Files</title>

  <para>
   To include an external file into your embedded SQL program, use:
<programlisting>
EXEC SQL INCLUDE <replaceable>filename</replaceable>;
</programlisting>
   The embedded SQL preprocessor will look for a file named
   <literal><replaceable>filename</replaceable>.h</literal>,
   preprocess it, and include it in the resulting C output.  Thus,
   embedded SQL statements in the included file are handled correctly.
  </para>

  <para>
   Note that this is <emphasis>not</emphasis> the same as
<programlisting>
#include &lt;<replaceable>filename</replaceable>.h&gt;
</programlisting>
   because this file would not be subject to SQL command preprocessing.
   Naturally, you can continue to use the C
   <literal>#include</literal> directive to include other header
   files.
  </para>

  <note>
   <para>
    The include file name is case-sensitive, even though the rest of
    the <literal>EXEC SQL INCLUDE</literal> command follows the normal
    SQL case-sensitivity rules.
   </para>
  </note>
 </sect1>

 <sect1 id="ecpg-process">
  <title>Processing Embedded SQL Programs</title>

  <para>
   Now that you have an idea how to form embedded SQL C programs, you
   probably want to know how to compile them.  Before compiling you
   run the file through the embedded <acronym>SQL</acronym>
   <acronym>C</acronym> preprocessor, which converts the
   <acronym>SQL</acronym> statements you used to special function
   calls.  After compiling, you must link with a special library that
   contains the needed functions. These functions fetch information
   from the arguments, perform the <acronym>SQL</acronym> command using
   the <application>libpq</application> interface, and put the result
   in the arguments specified for output.
  </para>

  <para>
   The preprocessor program is called <filename>ecpg</filename> and is
   included in a normal <productname>PostgreSQL</> installation.
   Embedded SQL programs are typically named with an extension
   <filename>.pgc</filename>.  If you have a program file called
   <filename>prog1.pgc</filename>, you can preprocess it by simply
   calling
<programlisting>
ecpg prog1.pgc
</programlisting>
   This will create a file called <filename>prog1.c</filename>.  If
   your input files do not follow the suggested naming pattern, you
   can specify the output file explicitly using the
   <option>-o</option> option.
  </para>

  <para>
   The preprocessed file can be compiled normally, for example:
<programlisting>
cc -c prog1.c
</programlisting>
   The generated C source files include header files from the
   <productname>PostgreSQL</> installation, so if you installed
   <productname>PostgreSQL</> in a location that is not searched by
   default, you have to add an option such as
   <literal>-I/usr/local/pgsql/include</literal> to the compilation
   command line.
  </para>

  <para>
   To link an embedded SQL program, you need to include the
   <filename>libecpg</filename> library, like so:
<programlisting>
cc -o myprog prog1.o prog2.o ... -lecpg
</programlisting>
   Again, you might have to add an option like
   <literal>-L/usr/local/pgsql/lib</literal> to that command line.
  </para>

  <para>
   If you manage the build process of a larger project using
   <application>make</application>, it may be convenient to include
   the following implicit rule to your makefiles:
<programlisting>
ECPG = ecpg

%.c: %.pgc
        $(ECPG) $<
</programlisting>
  </para>

  <para>
   The complete syntax of the <command>ecpg</command> command is
   detailed in <xref linkend="app-ecpg">.
  </para>

  <para>
   The <application>ecpg</application> library is thread-safe if it is built
   using the <option>--enable-thread-safety</> command-line option to
   <filename>configure</filename>.  (You might need to use other threading
   command-line options to compile your client code.)
  </para>
 </sect1>

 <sect1 id="ecpg-library">
  <title>Library Functions</title>

  <para>
   The <filename>libecpg</filename> library primarily contains
   <quote>hidden</quote> functions that are used to implement the
   functionality expressed by the embedded SQL commands.  But there
   are some functions that can usefully be called directly.  Note that
   this makes your code unportable.
  </para>

  <itemizedlist>
   <listitem>
    <para>
     <function>ECPGdebug(int <replaceable>on</replaceable>, FILE
     *<replaceable>stream</replaceable>)</function> turns on debug
     logging if called with the first argument non-zero. Debug logging
     is done on <replaceable>stream</replaceable>.  The log contains
     all <acronym>SQL</acronym> statements with all the input
     variables inserted, and the results from the
     <productname>PostgreSQL</productname> server. This can be very
     useful when searching for errors in your <acronym>SQL</acronym>
     statements.
    </para>
    <note>
    <para>
    On Windows, if the <application>ecpg</> libraries and an application are
    compiled with different flags, this function call will crash the 
    application because the internal representation of the 
    <literal>FILE</> pointers differ.  Specifically,
    multithreaded/single-threaded, release/debug, and static/dynamic 
    flags should be the same for the library and all applications using
    that library.
    </para>
    </note>
   </listitem>

   <listitem>
    <para>
     <function>ECPGstatus(int <replaceable>lineno</replaceable>,
     const char* <replaceable>connection_name</replaceable>)</function>
     returns true if you are connected to a database and false if not.
     <replaceable>connection_name</replaceable> can be <literal>NULL</> 
     if a single connection is being used.
    </para>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 id="ecpg-develop">
  <title>Internals</title>

  <para>
   This section explains how <application>ECPG</application> works
   internally. This information can occasionally be useful to help
   users understand how to use <application>ECPG</application>.
  </para>

   <para>
    The first four lines written by <command>ecpg</command> to the
    output are fixed lines.  Two are comments and two are include
    lines necessary to interface to the library.  Then the
    preprocessor reads through the file and writes output.  Normally
    it just echoes everything to the output.
   </para>

   <para>
    When it sees an <command>EXEC SQL</command> statement, it
    intervenes and changes it. The command starts with <command>EXEC
    SQL</command> and ends with <command>;</command>. Everything in
    between is treated as an <acronym>SQL</acronym> statement and
    parsed for variable substitution.
   </para>

   <para>
    Variable substitution occurs when a symbol starts with a colon
    (<literal>:</literal>). The variable with that name is looked up
    among the variables that were previously declared within a
    <literal>EXEC SQL DECLARE</> section.
   </para>

   <para>
    The most important function in the library is
    <function>ECPGdo</function>, which takes care of executing most
    commands. It takes a variable number of arguments. This can easily
    add up to 50 or so arguments, and we hope this will not be a
    problem on any platform.
   </para>

   <para>
    The arguments are:

    <variablelist>
     <varlistentry>
      <term>A line number</term>
      <listitem>
       <para>
        This is the line number of the original line; used in error
        messages only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>A string</term>
      <listitem>
       <para>
        This is the <acronym>SQL</acronym> command that is to be issued.
        It is modified by the input variables, i.e., the variables that
        where not known at compile time but are to be entered in the
        command. Where the variables should go the string contains
        <literal>?</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Input variables</term>
      <listitem>
       <para>
        Every input variable causes ten arguments to be created.  (See below.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><parameter>ECPGt_EOIT</></term>
      <listitem>
       <para>
        An <type>enum</> telling that there are no more input
        variables.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Output variables</term>
      <listitem>
       <para>
        Every output variable causes ten arguments to be created.
        (See below.)  These variables are filled by the function.
       </para>
      </listitem>
     </varlistentry>

      <varlistentry>
       <term><parameter>ECPGt_EORT</></term>
       <listitem>
       <para>
        An <type>enum</> telling that there are no more variables.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    For every variable that is part of the <acronym>SQL</acronym>
    command, the function gets ten arguments:

    <orderedlist>
     <listitem>
      <para>
       The type as a special symbol.
      </para>
     </listitem>

     <listitem>
      <para> 
       A pointer to the value or a pointer to the pointer.
      </para>
     </listitem>

     <listitem>
      <para>
       The size of the variable if it is a <type>char</type> or <type>varchar</type>.
      </para>
     </listitem>

     <listitem>
      <para>
       The number of elements in the array (for array fetches).
      </para>
     </listitem>

     <listitem>
      <para>
       The offset to the next element in the array (for array fetches).
      </para>
     </listitem>

     <listitem>
      <para>
       The type of the indicator variable as a special symbol.
      </para>
     </listitem>

     <listitem>
      <para>
       A pointer to the indicator variable.
      </para>
     </listitem>

     <listitem>
      <para>
       0
      </para>
     </listitem>

     <listitem>
      <para>
       The number of elements in the indicator array (for array fetches).
      </para>
     </listitem>

     <listitem>
      <para>
       The offset to the next element in the indicator array (for
       array fetches).
      </para>
     </listitem>
    </orderedlist>
   </para>

   <para>
    Note that not all SQL commands are treated in this way.  For
    instance, an open cursor statement like
<programlisting>
EXEC SQL OPEN <replaceable>cursor</replaceable>;
</programlisting>
    is not copied to the output. Instead, the cursor's
    <command>DECLARE</> command is used at the position of the <command>OPEN</> command
    because it indeed opens the cursor.
   </para>

   <para>
    Here is a complete example describing the output of the
    preprocessor of a file <filename>foo.pgc</filename> (details may
    change with each particular version of the preprocessor):
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
int index;
int result;
EXEC SQL END DECLARE SECTION;
...
EXEC SQL SELECT res INTO :result FROM mytable WHERE index = :index;
</programlisting>
    is translated into:
<programlisting>
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include &lt;ecpgtype.h&gt;;
#include &lt;ecpglib.h&gt;;

/* exec sql begin declare section */

#line 1 "foo.pgc"

 int index;
 int result;
/* exec sql end declare section */
...
ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ?     ",
        ECPGt_int,&amp;(index),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
        ECPGt_int,&amp;(result),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
</programlisting>
    (The indentation here is added for readability and not
    something the preprocessor does.)
   </para>
 </sect1>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->