<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.26 2001/10/18 20:43:05 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.27 2001/10/31 20:37:39 petere Exp $
-->
<chapter id="ecpg">
<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>. Most
- <acronym>SQL</acronym> statement log their arguments and results.
+ <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>. Most
+
<acronym>SQL</acronym> statement log their arguments and results.
</para>
<para>
- The most important function , <function>ECPGdo</function>, logs
- all <acronym>SQL</acronym> statements with both the expanded
- string, i.e. the string with all the input variables inserted,
- and the result from the <productname>Postgres</productname>
- server. This can be very useful when searching for errors in
- your <acronym>SQL</acronym> statements.
+ The most important function , <function>ECPGdo</function>, logs
+
all <acronym>SQL</acronym> statements with both the expanded
+ string, i.e. the string with all the input variables inserted,
+
and the result from the <productname>Postgres</productname>
+ server. This can be very useful when searching for errors in
+
your <acronym>SQL</acronym> statements.
</para>
</listitem>
<listitem>
<para>
- <function>ECPGstatus()</function>
- This method returns TRUE if we are connected to a database and FALSE if not.
+ <function>ECPGstatus()</function>
+ This method returns TRUE if we are connected to a database and FALSE if not.
</para>
</listitem>
</itemizedlist>
/* 5: empty */
char sqlwarn[8];
/* 0: set to 'W' if at least one other is 'W' */
- /* 1: if 'W' at least one character string */
+ /* 1: if 'W' at least one character string */
/* value was truncated when it was */
/* stored into a host variable. */
/* 2: empty */
<varlistentry>
<term><computeroutput>-12, Out of memory in line %d.</computeroutput></term>
<listitem>
- <para>
- Should not normally occur. This indicates your virtual memory is
- exhausted.
- </para>
+ Should not normally occur. This indicates your virtual memory is
+ exhausted.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-200 (ECPG_UNSUPPORTED): Unsupported type %s on line %d.</computeroutput></term>
<listitem>
- <para>
- Should not normally occur. This indicates the preprocessor has
- generated something that the library does not know about.
- Perhaps you are running incompatible versions of the
- preprocessor and the library.
- </para>
+ Should not normally occur. This indicates the preprocessor has
+ generated something that the library does not know about.
+ Perhaps you are running incompatible versions of the
+ preprocessor and the library.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-201 (ECPG_TOO_MANY_ARGUMENTS): Too many arguments line %d.</computeroutput></term>
<listitem>
- <para>
- This means that <productname>Postgres</productname> has
- returned more arguments than we have matching variables.
- Perhaps you have forgotten a couple of the host variables in
- the <command>INTO :var1,:var2</command>-list.
- </para>
+
This means that <productname>Postgres</productname> has
+ returned more arguments than we have matching variables.
+ Perhaps you have forgotten a couple of the host variables in
+ the <command>INTO :var1,:var2</command>-list.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-202 (ECPG_TOO_FEW_ARGUMENTS): Too few arguments line %d.</computeroutput></term>
<listitem>
- <para>
- This means that <productname>Postgres</productname> has
- returned fewer arguments than we have host variables. Perhaps
- you have too many host variables in the <command>INTO
- :var1,:var2</command>-list.
- </para>
+
This means that <productname>Postgres</productname> has
+ returned fewer arguments than we have host variables. Perhaps
+ you have too many host variables in the <command>INTO
+ :var1,:var2</command>-list.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-203 (ECPG_TOO_MANY_MATCHES): Too many matches line %d.</computeroutput></term>
<listitem>
- <para>
- This means the query has returned several rows but the
- variables specified are not arrays. The
- <command>SELECT</command> command was not unique.
- </para>
+ This means the query has returned several rows but the
+ variables specified are not arrays. The
+ <command>SELECT</command> command was not unique.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-204 (ECPG_INT_FORMAT): Not correctly formatted int type: %s line %d.</computeroutput></term>
<listitem>
- <para>
- This means the host variable is of type <type>int</type> and
- the field in the <productname>Postgres</productname> database
- is of another type and contains a value that cannot be
- interpreted as an <type>int</type>. The library uses
- <function>strtol()</function> for this conversion.
- </para>
+ This means the host variable is of type <type>int</type> and
+
the field in the <productname>Postgres</productname> database
+ is of another type and contains a value that cannot be
+ interpreted as an <type>int</type>. The library uses
+ <function>strtol()</function> for this conversion.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-205 (ECPG_UINT_FORMAT): Not correctly formatted unsigned type: %s line %d.</computeroutput></term>
<listitem>
- <para>
- This means the host variable is of type <type>unsigned
- int</type> and the field in the
- <productname>Postgres</productname> database is of another type
- and contains a value that cannot be interpreted as an
- <type>unsigned int</type>. The library uses
- <function>strtoul()</function> for this conversion.
- </para>
+ This means the host variable is of type <type>unsigned
+ int</type> and the field in the
+
<productname>Postgres</productname> database is of another type
+ and contains a value that cannot be interpreted as an
+ <type>unsigned int</type>. The library uses
+ <function>strtoul()</function> for this conversion.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating point type: %s line %d.</computeroutput></term>
<listitem>
- <para>
- This means the host variable is of type <type>float</type> and
- the field in the <productname>Postgres</productname> database
- is of another type and contains a value that cannot be
- interpreted as a <type>float</type>. The library uses
- <function>strtod()</function> for this conversion.
- </para>
+ This means the host variable is of type <type>float</type> and
+
the field in the <productname>Postgres</productname> database
+ is of another type and contains a value that cannot be
+ interpreted as a <type>float</type>. The library uses
+ <function>strtod()</function> for this conversion.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-207 (ECPG_CONVERT_BOOL): Unable to convert %s to bool on line %d.</computeroutput></term>
<listitem>
- <para>
- This means the host variable is of type <type>bool</type> and
- the field in the <productname>Postgres</productname> database
- is neither <literal>'t'</> nor <literal>'f'</>.
- </para>
+ This means the host variable is of type <type>bool</type> and
+
the field in the <productname>Postgres</productname> database
+ is neither <literal>'t'</> nor <literal>'f'</>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-208 (ECPG_EMPTY): Empty query line %d.</computeroutput></term>
<listitem>
- <para>
- <productname>Postgres</productname> returned <symbol>PGRES_EMPTY_QUERY</symbol>, probably
- because the query indeed was empty.
- </para>
+
<productname>Postgres</productname> returned <symbol>PGRES_EMPTY_QUERY</symbol>, probably
+ because the query indeed was empty.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-209 (ECPG_MISSING_INDICATOR): NULL value without indicator in line %d.</computeroutput></term>
<listitem>
- <para>
- <productname>Postgres</productname> returned <symbol>ECPG_MISSING_INDICATOR</symbol>
- because a NULL was returned and no NULL indicator variable was supplied.
- </para>
+
<productname>Postgres</productname> returned <symbol>ECPG_MISSING_INDICATOR</symbol>
+ because a NULL was returned and no NULL indicator variable was supplied.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-210 (ECPG_NO_ARRAY): Variable is not an array in line %d.</computeroutput></term>
<listitem>
- <para>
- <productname>Postgres</productname> returned <symbol>ECPG_NO_ARRAY</symbol>
- because an ordinary variable was used in a place that requires
- an array.
- </para>
+
<productname>Postgres</productname> returned <symbol>ECPG_NO_ARRAY</symbol>
+ because an ordinary variable was used in a place that requires
+ an array.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-211 (ECPG_DATA_NOT_ARRAY): Data read from backend is not an array in line %d.</computeroutput></term>
<listitem>
- <para>
- <productname>Postgres</productname> returned <symbol>ECPG_DATA_NOT_ARRAY</symbol>
- because the database returned an ordinary variable in a place
- that requires array value.
- </para>
+
<productname>Postgres</productname> returned <symbol>ECPG_DATA_NOT_ARRAY</symbol>
+ because the database returned an ordinary variable in a place
+ that requires array value.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-220 (ECPG_NO_CONN): No such connection %s in line %d.</computeroutput></term>
<listitem>
- <para>
- The program tried to access a connection that does not exist.
- </para>
+ The program tried to access a connection that does not exist.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-221 (ECPG_NOT_CONN): Not connected in line %d.</computeroutput></term>
<listitem>
- <para>
- The program tried to access a connection that does exist but is
- not open.
- </para>
+ The program tried to access a connection that does exist but is
+ not open.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-230 (ECPG_INVALID_STMT): Invalid statement name %s in line %d.</computeroutput></term>
<listitem>
- <para>
- The statement you are trying to use has not been prepared.
- </para>
+ The statement you are trying to use has not been prepared.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-240 (ECPG_UNKNOWN_DESCRIPTOR): Descriptor %s not found in line %d.</computeroutput></term>
<listitem>
- <para>
- The descriptor specified was not foundstatement you are trying to use has not been prepared.
- </para>
+ The descriptor specified was not foundstatement you are trying to use has not been prepared.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-241 (ECPG_INVALID_DESCRIPTOR_INDEX): Descriptor index out of range in line %d.</computeroutput></term>
<listitem>
- <para>
- The descriptor index specified was out of range.
- </para>
+ The descriptor index specified was out of range.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM): Descriptor %s not found in line %d.</computeroutput></term>
<listitem>
- <para>
- The descriptor specified was not foundstatement you are trying to use has not been prepared.
- </para>
+ The descriptor specified was not foundstatement you are trying to use has not been prepared.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-243 (ECPG_VAR_NOT_NUMERIC): Variable is not a numeric type in line %d.</computeroutput></term>
<listitem>
- <para>
- The database returned a numeric value and the variable was not
- numeric.
- </para>
+ The database returned a numeric value and the variable was not
+ numeric.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-244 (ECPG_VAR_NOT_CHAR): Variable is not a character type in line %d.</computeroutput></term>
<listitem>
- <para>
- The database returned a non-numeric value and the variable was
- numeric.
- </para>
+ The database returned a non-numeric value and the variable was
+ numeric.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-400 (ECPG_PGSQL): Postgres error: %s line %d.</computeroutput></term>
<listitem>
- <para>
- Some <productname>Postgres</productname> error.
- The message contains the error message from the
- <productname>Postgres</productname> backend.
- </para>
+
Some <productname>Postgres</productname> error.
+ The message contains the error message from the
+
<productname>Postgres</productname> backend.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-401 (ECPG_TRANS): Error in transaction processing line %d.</computeroutput></term>
<listitem>
- <para>
- <productname>Postgres</productname> signaled that we cannot start,
- commit or rollback the transaction.
- </para>
+
<productname>Postgres</productname> signaled that we cannot start,
+ commit or rollback the transaction.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-402 (ECPG_CONNECT): Could not connect to database %s in line %d.</computeroutput></term>
<listitem>
- <para>
- The connect to the database did not work.
- </para>
+ The connect to the database did not work.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>100 (ECPG_NOT_FOUND): Data not found line %d.</computeroutput></term>
<listitem>
- <para>
- This is a <quote>normal</quote> error that tells you that what you are querying cannot
- be found or you are at the end of the cursor.
- </para>
+ This is a <quote>normal</quote> error that tells you that what you are querying cannot
+ be found or you are at the end of the cursor.
+ </para>
</listitem>
</varlistentry>
<sect1 id="ecpg-limitations">
<title>Limitations</title>
- <abstract>
- <para>
- What will never be included and why it cannot be done.
- </para>
- </abstract>
-
<para>
+ What will never be included and why it cannot be done:
+
<variablelist>
<varlistentry>
<term>Oracle's single tasking</term>
<listitem>
<para>
- Oracle version 7.0 on <systemitem class="osname">AIX</> 3 uses OS-supported locks in shared
- memory that allow an application designer to link an application
- in a <quote>single tasking</quote> way. Instead of starting one client
- process per application process, both the database part and the
- application part run in the same process. In later versions of
- Oracle this is no longer supported.
+ Oracle version 7.0 on <systemitem class="osname">AIX</> 3 uses OS-supported locks in shared
+ memory that allow an application designer to link an application
+ in a <quote>single tasking</quote> way. Instead of starting one client
+ process per application process, both the database part and the
+ application part run in the same process. In later versions of
+ Oracle this is no longer supported.
</para>
<para>
- This would require a total redesign of the
- <productname>Postgres</productname> access model and the
- performance gain does not justify the effort.
+ This would require a total redesign of the
+
<productname>Postgres</productname> access model and the
+ performance gain does not justify the effort.
</para>
</listitem>
</varlistentry>
<term>Syntax of FETCH</term>
<listitem>
<para>
- The standard syntax for FETCH is:
+ The standard syntax for FETCH is:
</para>
<para>
- FETCH [direction] [amount] IN|FROM <replaceable>cursor</replaceable>.
+ FETCH [direction] [amount] IN|FROM <replaceable>cursor</replaceable>.
</para>
<para>
- <application>ORACLE</application>, however, does not use the keywords IN
- or FROM. This feature cannot be added since it would create parsing
- conflicts.
+
<application>ORACLE</application>, however, does not use the keywords IN
+ or FROM. This feature cannot be added since it would create parsing
+ conflicts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Library functions</term>
<listitem>
- <para>
- to_date et al. does not exist. However,
- <productname>Postgres</productname> has some good conversion
- routines so you probably won't miss them.
- </para>
+ to_date et al. does not exist. However,
+
<productname>Postgres</productname> has some good conversion
+ routines so you probably won't miss them.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Structures and unions</term>
<listitem>
- <para>
- Structures and unions have to be defined in the
- <command>declare</> section.
- </para>
+ Structures and unions have to be defined in the
+ <command>declare</> section.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Missing statements</term>
<listitem>
- <para>
- The following statements are not implemented thus far:
- <variablelist>
- <varlistentry>
- <term><literal>exec sql allocate</></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>exec sql deallocate</></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>SQLSTATE</></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <para>
+ The following statements are not implemented thus far:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>exec sql allocate</>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>exec sql deallocate</></term>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>SQLSTATE</></term>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>message 'no data found'</term>
<listitem>
- <para>
- The error message for <quote>no data</quote> in:
- <programlisting>
+ The error message for <quote>no data</quote> in:
exec sql insert select from statement
- </programlisting>
- has to be <literal>100</>.
- </para>
+ </programlisting>
+ has to be <literal>100</>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>sqlwarn[6]</literal></term>
<listitem>
- <para>
- <literal>sqlwarn[6]</literal> should be <literal>W</> if the <command>PRECISION</>
- or <command>SCALE</> value specified in a <command>SET
- DESCRIPTOR</> statement was ignored.
- </para>
+ <literal>sqlwarn[6]</literal> should be <literal>W</> if the <command>PRECISION</>
+ or <command>SCALE</> value specified in a <command>SET
+ DESCRIPTOR</> statement was ignored.
+ </para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term>Declare sections</term>
<listitem>
- <para>
- <command>Declare</> sections begin with:
+ <command>Declare</> sections begin with:
+<programlisting>
exec sql begin declare section;
- </programlisting>
- and end with:
+</programlisting>
+ and end with:
+<programlisting>
exec sql end declare section;
- </programlisting>
- In this section only variable declarations are allowed. Every
- variable declared within this section is stored in a list
- of variables indexed by name together with its corresponding
- type.
- </para>
-
- <para>
- In particular the definition of a structure or union also must
- be listed inside a <command>declare</> section. Otherwise
- <application>ecpg</application> cannot handle these types since
- it does not know the definition.
- </para>
-
- <para>
- The declaration is also echoed to the file to make it a normal
- C variable.
- </para>
-
- <para>
- The special types <type>VARCHAR</type> and <type>VARCHAR2</type> are converted into a named struct
- for every variable. A declaration like:
+</programlisting>
+ In this section only variable declarations are allowed. Every
+ variable declared within this section is stored in a list
+ of variables indexed by name together with its corresponding
+ type.
+ </para>
+
+ In particular the definition of a structure or union also must
+ be listed inside a <command>declare</> section. Otherwise
+
<application>ecpg</application> cannot handle these types since
+ it does not know the definition.
+ </para>
+
+ The declaration is also echoed to the file to make it a normal
+ C variable.
+ </para>
+
+ The special types <type>VARCHAR</type> and <type>VARCHAR2</type> are converted into a named struct
+ for every variable. A declaration like:
+<programlisting>
VARCHAR var[180];
- </programlisting>
- is converted into:
+</programlisting>
+ is converted into:
+<programlisting>
struct varchar_var { int len; char arr[180]; } var;
- </programlisting>
- </para>
+</programlisting>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Include statements</term>
<listitem>
- <para>
- An include statement looks like:
+ An include statement looks like:
+<programlisting>
exec sql include filename;
- </programlisting>
- Note that this is NOT the same as:
+</programlisting>
+ Note that this is NOT the same as:
+<programlisting>
#include <filename.h>
- </programlisting>
- </para>
-
- <para>
- Instead the file specified is parsed by
- <application>ecpg</application> so the contents of the file are
- included in the resulting C code. This way you are able to
- specify EXEC SQL commands in an include file.
- </para>
+</programlisting>
+ </para>
+
+ Instead the file specified is parsed by
+
<application>ecpg</application> so the contents of the file are
+ included in the resulting C code. This way you are able to
+ specify EXEC SQL commands in an include file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Connect statement</term>
<listitem>
- <para>
- A connect statement looks like:
+ A connect statement looks like:
+<programlisting>
exec sql connect to <replaceable>connection target</replaceable>;
- </programlisting>
- It creates a connection to the specified database.
- </para>
-
- <para>
- The <replaceable>connection target</replaceable> can be specified in the
- following ways:
- <variablelist>
- <varlistentry>
- <term>dbname[@server][:port][as <replaceable>connection
- name</replaceable>][user <replaceable>user name</replaceable>]</term>
- <listitem><para></para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>tcp:postgresql://server[:port][/dbname][as
- <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
- <listitem><para></para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>unix:postgresql://server[:port][/dbname][as
- <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
- <listitem><para></para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>character variable</replaceable>[as
- <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
- <listitem><para></para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable>character string</replaceable>[as
- <replaceable>connection name</replaceable>][<replaceable>user</replaceable>]</term>
- <listitem><para></para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>default</term>
- <listitem><para></para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>user</term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- There are also different ways to specify the user name:
- <variablelist>
- <varlistentry>
- <term><replaceable>userid</replaceable></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><replaceable>userid</replaceable>/<replaceable>password</replaceable></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><replaceable>userid</replaceable> identified by <replaceable>password</replaceable></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term><replaceable>userid</replaceable> using <replaceable>password</replaceable></term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- Finally, the <replaceable>userid</replaceable> and <replaceable>password</replaceable> may be a constant text, a
- character variable, or a character string.
- </para>
+</programlisting>
+ It creates a connection to the specified database.
+ </para>
+
+ <para>
+ The <replaceable>connection target</replaceable> can be specified in the
+ following ways:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <literal>dbname[@server][:port][as <replaceable>connection
+ name</replaceable>][user <replaceable>user name</replaceable>]</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>tcp:postgresql://server[:port][/dbname][as
+ <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>unix:postgresql://server[:port][/dbname][as
+ <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal><replaceable>character variable</replaceable>[as
+ <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal><replaceable>character string</replaceable>[as
+ <replaceable>connection name</replaceable>][<replaceable>user</replaceable>]</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>default</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>user</literal>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ There are also different ways to specify the user name:
+
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <literal><replaceable>userid</replaceable></literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal><replaceable>userid</replaceable>/<replaceable>password</replaceable></literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal><replaceable>userid</replaceable> identified by <replaceable>password</replaceable></literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal><replaceable>userid</replaceable> using <replaceable>password</replaceable></literal>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Finally, the <replaceable>userid</replaceable> and <replaceable>password</replaceable> may be a constant text, a
+ character variable, or a character string.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Disconnect statements</term>
<listitem>
- <para>
- A disconnect statement looks like:
- <programlisting>
+ A disconnect statement looks like:
exec sql disconnect [<replaceable>connection target</replaceable>];
- </programlisting>
- It closes the connection to the specified database.
- </para>
-
- <para>
- The <replaceable>connection target</replaceable> can be specified in the
- following ways:
- <variablelist>
- <varlistentry>
- <term><replaceable>connection name</replaceable></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term>default</term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term>current</term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry>
- <term>all</term>
- <listitem><para></para></listitem>
- </varlistentry>
- </variablelist>
- </para>
+ </programlisting>
+ It closes the connection to the specified database.
+ </para>
+
+ <para>
+ The <replaceable>connection target</replaceable> can be specified in the
+ following ways:
+
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <literal><replaceable>connection name</replaceable></literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>default</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>current</literal>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <term>all</term>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Open cursor statement</term>
<listitem>
- <para>
- An open cursor statement looks like:
+ An open cursor statement looks like:
+<programlisting>
exec sql open <replaceable>cursor</replaceable>;
- </programlisting>
- and is not copied to the output. Instead, the cursor's
- <command>DECLARE</> command is used because it opens the cursor
- as well.
- </para>
+</programlisting>
+ and is not copied to the output. Instead, the cursor's
+ <command>DECLARE</> command is used because it opens the cursor
+ as well.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Commit statement</term>
<listitem>
- <para>
- A commit statement looks like:
+ A commit statement looks like:
+<programlisting>
exec sql commit;
- </programlisting>
- </para>
+</programlisting>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Rollback statement</term>
<listitem>
- <para>
- A rollback statement looks like:
+ A rollback statement looks like:
+<programlisting>
exec sql rollback;
- </programlisting>
- </para>
+</programlisting>
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Other statements</term>
<listitem>
- <para>
- Other <acronym>SQL</acronym> statements are used by
- starting with <command>exec sql</command> and ending 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
- (<command>:</command>). The variable with that name is looked
- up among the variables that were previously declared within a
- <command>declare</> section. Depending on whether the variable is
- being use for input or output, a pointer to the variable is
- output to allow access by the function.
- </para>
-
- <para>
- For every variable that is part of the <acronym>SQL</acronym>
- query, the function gets other arguments:
-
- <simplelist>
- <member>The type as a special symbol.</member>
- <member>A pointer to the value or a pointer to the pointer.</member>
- <member>The size of the variable if it is a <type>char</type> or <type>varchar</type>.</member>
- <member>The number of elements in the array (for array fetches).</member>
- <member>The offset to the next element in the array (for array fetches).</member>
- <member>The type of the indicator variable as a special symbol.</member>
- <member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</member>
- <member>0.</member>
- <member>Number of elements in the indicator array (for array fetches).</member>
- <member>The offset to the next element in the indicator array
- (for array fetches).</member>
- </simplelist>
- </para>
+ <para>
+ Other <acronym>SQL</acronym> statements are used by
+ starting with <command>exec sql</command> and ending 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
+ (<command>:</command>). The variable with that name is looked
+ up among the variables that were previously declared within a
+ <command>declare</> section. Depending on whether the variable is
+ being use for input or output, a pointer to the variable is
+ output to allow access by the function.
+ </para>
+
+ <para>
+ For every variable that is part of the <acronym>SQL</acronym>
+ query, the function gets other arguments:
+
+ <itemizedlist>
+ <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 value of the indicator variable or a pointer to the pointer of the indicator variable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 0.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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>
+ </itemizedlist>
+ </para>
</listitem>
</varlistentry>
<para>
Here is a complete example describing the output of the preprocessor of a
file <filename>foo.pgc</filename>:
+<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>
+</programlisting>
is translated into:
+<programlisting>
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include <ecpgtype.h>;
/* exec sql end declare section */
...
ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ",
- ECPGt_int,&(index),1L,1L,sizeof(int),
+ ECPGt_int,&(index),1L,1L,sizeof(int),
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
ECPGt_int,&(result),1L,1L,sizeof(int),
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
- </programlisting>
+</programlisting>
(The indentation in this manual is added for readability and not
something the preprocessor does.)
</para>
<varlistentry>
<term>A line number</term>
<listitem>
- <para>
- This is a line number of the original line; used in error messages only.
- </para>
+ This is a 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> query 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
- query. Where the variables should go the string contains
- <literal>?</literal>.
- </para>
+
This is the <acronym>SQL</acronym> query 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
+ query. Where the variables should go the string contains
+ <literal>?</literal>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Input variables</term>
<listitem>
- <para>
- As described in the section about the preprocessor, every input variable
- gets ten arguments.
- </para>
+ As described in the section about the preprocessor, every input variable
+ gets ten arguments.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ECPGt_EOIT</literal></term>
<listitem>
- <para>
- An enum telling that there are no more input variables.
- </para>
+ An enum telling that there are no more input variables.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Output variables</term>
<listitem>
- <para>
- As described in the section about the preprocessor, every input variable
- gets ten arguments. These variables are filled by the function.
- </para>
+ As described in the section about the preprocessor, every input variable
+ gets ten arguments. These variables are filled by the function.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>ECPGt_EORT</term>
<listitem>
- <para>
- An enum telling that there are no more variables.
- </para>
+ An enum telling that there are no more variables.
+ </para>
</listitem>
</varlistentry>
</variablelist>
projects / postgresql / commitdiff