9825 lines
306 KiB
Plaintext
9825 lines
306 KiB
Plaintext
<!-- doc/src/sgml/ecpg.sgml -->
|
|
|
|
<chapter id="ecpg">
|
|
<title><application>ECPG</application> — 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 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://<replaceable>hostname</replaceable><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>
|
|
|
|
If you specify the connection target literally (that is, not
|
|
through a variable reference) and you don't quote the value, then
|
|
the case-insensitivity rules of normal SQL are applied. In that
|
|
case you can also double-quote the individual parameters separately
|
|
as needed. In practice, it is probably less error-prone to use a
|
|
(single-quoted) string literal or a variable reference. 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>
|
|
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>
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<literal><replaceable>username</replaceable> IDENTIFIED BY <replaceable>password</replaceable></literal>
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<literal><replaceable>username</replaceable> USING <replaceable>password</replaceable></literal>
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
As above, the parameters <replaceable>username</replaceable> and
|
|
<replaceable>password</replaceable> can be an SQL identifier, an
|
|
SQL string literal, or a reference to a character variable.
|
|
</para>
|
|
|
|
<para>
|
|
If the connection target includes any <replaceable>options</replaceable>,
|
|
those consist of
|
|
<literal><replaceable>keyword</replaceable>=<replaceable>value</replaceable></literal>
|
|
specifications separated by ampersands (<literal>&</literal>).
|
|
The allowed key words are the same ones recognized
|
|
by <application>libpq</application> (see
|
|
<xref linkend="libpq-paramkeywords"/>). Spaces are ignored before
|
|
any <replaceable>keyword</replaceable> or <replaceable>value</replaceable>,
|
|
though not within or after one. Note that there is no way to
|
|
write <literal>&</literal> within a <replaceable>value</replaceable>.
|
|
</para>
|
|
|
|
<para>
|
|
The <replaceable>connection-name</replaceable> is used to handle
|
|
multiple connections in one program. It can be omitted if a
|
|
program uses only one connection. The most recently opened
|
|
connection becomes the current connection, which is used by default
|
|
when an SQL statement is to be executed (see later in this
|
|
chapter).
|
|
</para>
|
|
|
|
<para>
|
|
If untrusted users have access to a database that has not adopted a
|
|
<link linkend="ddl-schemas-patterns">secure schema usage pattern</link>,
|
|
begin each session by removing publicly-writable schemas
|
|
from <varname>search_path</varname>. For example,
|
|
add <literal>options=-c search_path=</literal>
|
|
to <literal><replaceable>options</replaceable></literal>, or
|
|
issue <literal>EXEC SQL SELECT pg_catalog.set_config('search_path', '',
|
|
false);</literal> after connecting. This consideration is not specific to
|
|
ECPG; it applies to every interface for executing arbitrary SQL commands.
|
|
</para>
|
|
|
|
<para>
|
|
Here are some examples of <command>CONNECT</command> statements:
|
|
<programlisting>
|
|
EXEC SQL CONNECT TO mydb@sql.mydomain.com;
|
|
|
|
EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john;
|
|
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
const char *target = "mydb@sql.mydomain.com";
|
|
const char *user = "john";
|
|
const char *passwd = "secret";
|
|
EXEC SQL END DECLARE SECTION;
|
|
...
|
|
EXEC SQL CONNECT TO :target USER :user USING :passwd;
|
|
/* or EXEC SQL CONNECT TO :target USER :user/:passwd; */
|
|
</programlisting>
|
|
The last form makes use of the variant referred to above as
|
|
character variable reference. You will see in later sections how C
|
|
variables can be used in SQL statements when you prefix them with a
|
|
colon.
|
|
</para>
|
|
|
|
<para>
|
|
Be advised that the format of the connection target is not
|
|
specified in the SQL standard. So if you want to develop portable
|
|
applications, you might want to use something based on the last
|
|
example above to encapsulate the connection target string
|
|
somewhere.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-set-connection">
|
|
<title>Choosing a Connection</title>
|
|
|
|
<para>
|
|
SQL statements in embedded SQL programs are by default executed on
|
|
the current connection, that is, the most recently opened one. If
|
|
an application needs to manage multiple connections, then there are
|
|
two ways to handle this.
|
|
</para>
|
|
|
|
<para>
|
|
The first option is to explicitly choose a connection for each SQL
|
|
statement, for example:
|
|
<programlisting>
|
|
EXEC SQL AT <replaceable>connection-name</replaceable> SELECT ...;
|
|
</programlisting>
|
|
This option is particularly suitable if the application needs to
|
|
use several connections in mixed order.
|
|
</para>
|
|
|
|
<para>
|
|
If your application uses multiple threads of execution, they cannot share a
|
|
connection concurrently. You must either explicitly control access to the connection
|
|
(using mutexes) or use a connection for each thread.
|
|
</para>
|
|
|
|
<para>
|
|
The second option is to execute a statement to switch the current
|
|
connection. That statement is:
|
|
<programlisting>
|
|
EXEC SQL SET CONNECTION <replaceable>connection-name</replaceable>;
|
|
</programlisting>
|
|
This option is particularly convenient if many statements are to be
|
|
executed on the same connection.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example program managing multiple database connections:
|
|
<programlisting><![CDATA[
|
|
#include <stdio.h>
|
|
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char dbname[1024];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
int
|
|
main()
|
|
{
|
|
EXEC SQL CONNECT TO testdb1 AS con1 USER testuser;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
EXEC SQL CONNECT TO testdb2 AS con2 USER testuser;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
EXEC SQL CONNECT TO testdb3 AS con3 USER testuser;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
/* This query would be executed in the last opened database "testdb3". */
|
|
EXEC SQL SELECT current_database() INTO :dbname;
|
|
printf("current=%s (should be testdb3)\n", dbname);
|
|
|
|
/* Using "AT" to run a query in "testdb2" */
|
|
EXEC SQL AT con2 SELECT current_database() INTO :dbname;
|
|
printf("current=%s (should be testdb2)\n", dbname);
|
|
|
|
/* Switch the current connection to "testdb1". */
|
|
EXEC SQL SET CONNECTION con1;
|
|
|
|
EXEC SQL SELECT current_database() INTO :dbname;
|
|
printf("current=%s (should be testdb1)\n", dbname);
|
|
|
|
EXEC SQL DISCONNECT ALL;
|
|
return 0;
|
|
}
|
|
]]></programlisting>
|
|
|
|
This example would produce this output:
|
|
<screen>
|
|
current=testdb3 (should be testdb3)
|
|
current=testdb2 (should be testdb2)
|
|
current=testdb1 (should be testdb1)
|
|
</screen>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-disconnect">
|
|
<title>Closing a Connection</title>
|
|
|
|
<para>
|
|
To close a connection, use the following statement:
|
|
<programlisting>
|
|
EXEC SQL DISCONNECT <optional><replaceable>connection</replaceable></optional>;
|
|
</programlisting>
|
|
The <replaceable>connection</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>
|
|
<literal>ALL</literal>
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
If no connection name is specified, the current connection is
|
|
closed.
|
|
</para>
|
|
|
|
<para>
|
|
It is good style that an application always explicitly disconnect
|
|
from every connection it opened.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-commands">
|
|
<title>Running SQL Commands</title>
|
|
|
|
<para>
|
|
Any SQL command can be run from within an embedded SQL application.
|
|
Below are some examples of how to do that.
|
|
</para>
|
|
|
|
<sect2 id="ecpg-executing">
|
|
<title>Executing SQL Statements</title>
|
|
|
|
<para>
|
|
Creating a table:
|
|
<programlisting>
|
|
EXEC SQL CREATE TABLE foo (number integer, ascii char(16));
|
|
EXEC SQL CREATE UNIQUE INDEX num1 ON foo(number);
|
|
EXEC SQL COMMIT;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Inserting rows:
|
|
<programlisting>
|
|
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
|
|
EXEC SQL COMMIT;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Deleting rows:
|
|
<programlisting>
|
|
EXEC SQL DELETE FROM foo WHERE number = 9999;
|
|
EXEC SQL COMMIT;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Updates:
|
|
<programlisting>
|
|
EXEC SQL UPDATE foo
|
|
SET ascii = 'foobar'
|
|
WHERE number = 9999;
|
|
EXEC SQL COMMIT;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
<literal>SELECT</literal> statements that return a single result
|
|
row can also be executed using
|
|
<literal>EXEC SQL</literal> directly. To handle result sets with
|
|
multiple rows, an application has to use a cursor;
|
|
see <xref linkend="ecpg-cursors"/> below. (As a special case, an
|
|
application can fetch multiple rows at once into an array host
|
|
variable; see <xref linkend="ecpg-variables-arrays"/>.)
|
|
</para>
|
|
|
|
<para>
|
|
Single-row select:
|
|
<programlisting>
|
|
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Also, a configuration parameter can be retrieved with the
|
|
<literal>SHOW</literal> command:
|
|
<programlisting>
|
|
EXEC SQL SHOW search_path INTO :var;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The tokens of the form
|
|
<literal>:<replaceable>something</replaceable></literal> are
|
|
<firstterm>host variables</firstterm>, that is, they refer to
|
|
variables in the C program. They are explained in <xref
|
|
linkend="ecpg-variables"/>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-cursors">
|
|
<title>Using Cursors</title>
|
|
|
|
<para>
|
|
To retrieve a result set holding multiple rows, an application has
|
|
to declare a cursor and fetch each row from the cursor. The steps
|
|
to use a cursor are the following: declare a cursor, open it, fetch
|
|
a row from the cursor, repeat, and finally close it.
|
|
</para>
|
|
|
|
<para>
|
|
Select using cursors:
|
|
<programlisting>
|
|
EXEC SQL DECLARE foo_bar CURSOR FOR
|
|
SELECT number, ascii FROM foo
|
|
ORDER BY ascii;
|
|
EXEC SQL OPEN foo_bar;
|
|
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
|
|
...
|
|
EXEC SQL CLOSE foo_bar;
|
|
EXEC SQL COMMIT;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
For more details about declaring a cursor, see <xref
|
|
linkend="ecpg-sql-declare"/>; for more details about fetching rows from a
|
|
cursor, see <xref linkend="sql-fetch"/>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
The ECPG <command>DECLARE</command> command does not actually
|
|
cause a statement to be sent to the PostgreSQL backend. The
|
|
cursor is opened in the backend (using the
|
|
backend's <command>DECLARE</command> command) at the point when
|
|
the <command>OPEN</command> command is executed.
|
|
</para>
|
|
</note>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-transactions">
|
|
<title>Managing Transactions</title>
|
|
|
|
<para>
|
|
In the default mode, statements are committed only when
|
|
<command>EXEC SQL COMMIT</command> is issued. The embedded SQL
|
|
interface also supports autocommit of transactions (similar to
|
|
<application>psql</application>'s default behavior) via the <option>-t</option>
|
|
command-line option to <command>ecpg</command> (see <xref
|
|
linkend="app-ecpg"/>) or via the <literal>EXEC SQL SET AUTOCOMMIT TO
|
|
ON</literal> statement. In autocommit mode, each command is
|
|
automatically committed unless it is inside an explicit transaction
|
|
block. This mode can be explicitly turned off using <literal>EXEC
|
|
SQL SET AUTOCOMMIT TO OFF</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
The following transaction management commands are available:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL COMMIT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Commit an in-progress transaction.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL ROLLBACK</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Roll back an in-progress transaction.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL PREPARE TRANSACTION </literal><replaceable class="parameter">transaction_id</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Prepare the current transaction for two-phase commit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL COMMIT PREPARED </literal><replaceable class="parameter">transaction_id</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Commit a transaction that is in prepared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL ROLLBACK PREPARED </literal><replaceable class="parameter">transaction_id</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Roll back a transaction that is in prepared state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL SET AUTOCOMMIT TO ON</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Enable autocommit mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL SET AUTOCOMMIT TO OFF</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Disable autocommit mode. This is the default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-prepared">
|
|
<title>Prepared Statements</title>
|
|
|
|
<para>
|
|
When the values to be passed to an SQL statement are not known at
|
|
compile time, or the same statement is going to be used many
|
|
times, then prepared statements can be useful.
|
|
</para>
|
|
|
|
<para>
|
|
The statement is prepared using the
|
|
command <literal>PREPARE</literal>. For the values that are not
|
|
known yet, use the
|
|
placeholder <quote><literal>?</literal></quote>:
|
|
<programlisting>
|
|
EXEC SQL PREPARE stmt1 FROM "SELECT oid, datname FROM pg_database WHERE oid = ?";
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
If a statement returns a single row, the application can
|
|
call <literal>EXECUTE</literal> after
|
|
<literal>PREPARE</literal> to execute the statement, supplying the
|
|
actual values for the placeholders with a <literal>USING</literal>
|
|
clause:
|
|
<programlisting>
|
|
EXEC SQL EXECUTE stmt1 INTO :dboid, :dbname USING 1;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
If a statement returns multiple rows, the application can use a
|
|
cursor declared based on the prepared statement. To bind input
|
|
parameters, the cursor must be opened with
|
|
a <literal>USING</literal> clause:
|
|
<programlisting>
|
|
EXEC SQL PREPARE stmt1 FROM "SELECT oid,datname FROM pg_database WHERE oid > ?";
|
|
EXEC SQL DECLARE foo_bar CURSOR FOR stmt1;
|
|
|
|
/* when end of result set reached, break out of while loop */
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
EXEC SQL OPEN foo_bar USING 100;
|
|
...
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH NEXT FROM foo_bar INTO :dboid, :dbname;
|
|
...
|
|
}
|
|
EXEC SQL CLOSE foo_bar;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
When you don't need the prepared statement anymore, you should
|
|
deallocate it:
|
|
<programlisting>
|
|
EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
For more details about <literal>PREPARE</literal>,
|
|
see <xref linkend="ecpg-sql-prepare"/>. Also
|
|
see <xref linkend="ecpg-dynamic"/> for more details about using
|
|
placeholders and input parameters.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-variables">
|
|
<title>Using Host Variables</title>
|
|
|
|
<para>
|
|
In <xref linkend="ecpg-commands"/> you saw how you can execute SQL
|
|
statements from an embedded SQL program. Some of those statements
|
|
only used fixed values and did not provide a way to insert
|
|
user-supplied values into statements or have the program process
|
|
the values returned by the query. Those kinds of statements are
|
|
not really useful in real applications. This section explains in
|
|
detail how you can pass data between your C program and the
|
|
embedded SQL statements using a simple mechanism called
|
|
<firstterm>host variables</firstterm>. In an embedded SQL program we
|
|
consider the SQL statements to be <firstterm>guests</firstterm> in the C
|
|
program code which is the <firstterm>host language</firstterm>. Therefore
|
|
the variables of the C program are called <firstterm>host
|
|
variables</firstterm>.
|
|
</para>
|
|
|
|
<para>
|
|
Another way to exchange values between PostgreSQL backends and ECPG
|
|
applications is the use of SQL descriptors, described
|
|
in <xref linkend="ecpg-descriptors"/>.
|
|
</para>
|
|
|
|
<sect2 id="ecpg-variables-overview">
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
Passing data between the C program and the SQL statements is
|
|
particularly simple in embedded SQL. Instead of having the
|
|
program paste the data into the statement, which entails various
|
|
complications, such as properly quoting the value, you can simply
|
|
write the name of a C variable into the SQL statement, prefixed by
|
|
a colon. For example:
|
|
<programlisting>
|
|
EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);
|
|
</programlisting>
|
|
This statement refers to two C variables named
|
|
<varname>v1</varname> and <varname>v2</varname> and also uses a
|
|
regular SQL string literal, to illustrate that you are not
|
|
restricted to use one kind of data or the other.
|
|
</para>
|
|
|
|
<para>
|
|
This style of inserting C variables in SQL statements works
|
|
anywhere a value expression is expected in an SQL statement.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-declare-sections">
|
|
<title>Declare Sections</title>
|
|
|
|
<para>
|
|
To pass data from the program to the database, for example as
|
|
parameters in a query, or to pass data from the database back to
|
|
the program, the C variables that are intended to contain this
|
|
data need to be declared in specially marked sections, so the
|
|
embedded SQL preprocessor is made aware of them.
|
|
</para>
|
|
|
|
<para>
|
|
This section starts with:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
</programlisting>
|
|
and ends with:
|
|
<programlisting>
|
|
EXEC SQL END DECLARE SECTION;
|
|
</programlisting>
|
|
Between those lines, there must be normal C variable declarations,
|
|
such as:
|
|
<programlisting>
|
|
int x = 4;
|
|
char foo[16], bar[16];
|
|
</programlisting>
|
|
As you can see, you can optionally assign an initial value to the variable.
|
|
The variable's scope is determined by the location of its declaring
|
|
section within the program.
|
|
You can also declare variables with the following syntax which implicitly
|
|
creates a declare section:
|
|
<programlisting>
|
|
EXEC SQL int i = 4;
|
|
</programlisting>
|
|
You can have as many declare sections in a program as you like.
|
|
</para>
|
|
|
|
<para>
|
|
The declarations are also echoed to the output file as normal C
|
|
variables, so there's no need to declare them again. Variables
|
|
that are not intended to be used in SQL commands can be declared
|
|
normally outside these special sections.
|
|
</para>
|
|
|
|
<para>
|
|
The definition of a structure or union also must be listed inside
|
|
a <literal>DECLARE</literal> section. Otherwise the preprocessor cannot
|
|
handle these types since it does not know the definition.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-retrieving">
|
|
<title>Retrieving Query Results</title>
|
|
|
|
<para>
|
|
Now you should be able to pass data generated by your program into
|
|
an SQL command. But how do you retrieve the results of a query?
|
|
For that purpose, embedded SQL provides special variants of the
|
|
usual commands <command>SELECT</command> and
|
|
<command>FETCH</command>. These commands have a special
|
|
<literal>INTO</literal> clause that specifies which host variables
|
|
the retrieved values are to be stored in.
|
|
<command>SELECT</command> is used for a query that returns only
|
|
single row, and <command>FETCH</command> is used for a query that
|
|
returns multiple rows, using a cursor.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example:
|
|
<programlisting>
|
|
/*
|
|
* assume this table:
|
|
* CREATE TABLE test1 (a int, b varchar(50));
|
|
*/
|
|
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int v1;
|
|
VARCHAR v2;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
...
|
|
|
|
EXEC SQL SELECT a, b INTO :v1, :v2 FROM test;
|
|
</programlisting>
|
|
So the <literal>INTO</literal> clause appears between the select
|
|
list and the <literal>FROM</literal> clause. The number of
|
|
elements in the select list and the list after
|
|
<literal>INTO</literal> (also called the target list) must be
|
|
equal.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example using the command <command>FETCH</command>:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int v1;
|
|
VARCHAR v2;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
...
|
|
|
|
EXEC SQL DECLARE foo CURSOR FOR SELECT a, b FROM test;
|
|
|
|
...
|
|
|
|
do
|
|
{
|
|
...
|
|
EXEC SQL FETCH NEXT FROM foo INTO :v1, :v2;
|
|
...
|
|
} while (...);
|
|
</programlisting>
|
|
Here the <literal>INTO</literal> clause appears after all the
|
|
normal clauses.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-variables-type-mapping">
|
|
<title>Type Mapping</title>
|
|
|
|
<para>
|
|
When ECPG applications exchange values between the PostgreSQL
|
|
server and the C application, such as when retrieving query
|
|
results from the server or executing SQL statements with input
|
|
parameters, the values need to be converted between PostgreSQL
|
|
data types and host language variable types (C language data
|
|
types, concretely). One of the main points of ECPG is that it
|
|
takes care of this automatically in most cases.
|
|
</para>
|
|
|
|
<para>
|
|
In this respect, there are two kinds of data types: Some simple
|
|
PostgreSQL data types, such as <type>integer</type>
|
|
and <type>text</type>, can be read and written by the application
|
|
directly. Other PostgreSQL data types, such
|
|
as <type>timestamp</type> and <type>numeric</type> can only be
|
|
accessed through special library functions; see
|
|
<xref linkend="ecpg-special-types"/>.
|
|
</para>
|
|
|
|
<para>
|
|
<xref linkend="ecpg-datatype-hostvars-table"/> shows which PostgreSQL
|
|
data types correspond to which C data types. When you wish to
|
|
send or receive a value of a given PostgreSQL data type, you
|
|
should declare a C variable of the corresponding C data type in
|
|
the declare section.
|
|
</para>
|
|
|
|
<table id="ecpg-datatype-hostvars-table">
|
|
<title>Mapping Between PostgreSQL Data Types and C Variable Types</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>PostgreSQL data type</entry>
|
|
<entry>Host variable type</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><type>smallint</type></entry>
|
|
<entry><type>short</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>integer</type></entry>
|
|
<entry><type>int</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>bigint</type></entry>
|
|
<entry><type>long long int</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>decimal</type></entry>
|
|
<entry><type>decimal</type><footnote id="ecpg-datatype-table-fn"><para>This type can only be accessed through special library functions; see <xref linkend="ecpg-special-types"/>.</para></footnote></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>numeric</type></entry>
|
|
<entry><type>numeric</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>real</type></entry>
|
|
<entry><type>float</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>double precision</type></entry>
|
|
<entry><type>double</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>smallserial</type></entry>
|
|
<entry><type>short</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>serial</type></entry>
|
|
<entry><type>int</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>bigserial</type></entry>
|
|
<entry><type>long long int</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>oid</type></entry>
|
|
<entry><type>unsigned int</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>character(<replaceable>n</replaceable>)</type>, <type>varchar(<replaceable>n</replaceable>)</type>, <type>text</type></entry>
|
|
<entry><type>char[<replaceable>n</replaceable>+1]</type>, <type>VARCHAR[<replaceable>n</replaceable>+1]</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>name</type></entry>
|
|
<entry><type>char[NAMEDATALEN]</type></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>timestamp</type></entry>
|
|
<entry><type>timestamp</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>interval</type></entry>
|
|
<entry><type>interval</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>date</type></entry>
|
|
<entry><type>date</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>boolean</type></entry>
|
|
<entry><type>bool</type><footnote><para>declared in <filename>ecpglib.h</filename> if not native</para></footnote></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><type>bytea</type></entry>
|
|
<entry><type>char *</type>, <type>bytea[<replaceable>n</replaceable>]</type></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<sect3 id="ecpg-char">
|
|
<title>Handling Character Strings</title>
|
|
|
|
<para>
|
|
To handle SQL character string data types, such
|
|
as <type>varchar</type> and <type>text</type>, there are two
|
|
possible ways to declare the host variables.
|
|
</para>
|
|
|
|
<para>
|
|
One way is using <type>char[]</type>, an array
|
|
of <type>char</type>, which is the most common way to handle
|
|
character data in C.
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char str[50];
|
|
EXEC SQL END DECLARE SECTION;
|
|
</programlisting>
|
|
Note that you have to take care of the length yourself. If you
|
|
use this host variable as the target variable of a query which
|
|
returns a string with more than 49 characters, a buffer overflow
|
|
occurs.
|
|
</para>
|
|
|
|
<para>
|
|
The other way is using the <type>VARCHAR</type> type, which is a
|
|
special type provided by ECPG. The definition on an array of
|
|
type <type>VARCHAR</type> is converted into a
|
|
named <type>struct</type> for every variable. A declaration like:
|
|
<programlisting>
|
|
VARCHAR var[180];
|
|
</programlisting>
|
|
is converted into:
|
|
<programlisting>
|
|
struct varchar_var { int len; char arr[180]; } var;
|
|
</programlisting>
|
|
The member <structfield>arr</structfield> hosts the string
|
|
including a terminating zero byte. Thus, to store a string in
|
|
a <type>VARCHAR</type> host variable, the host variable has to be
|
|
declared with the length including the zero byte terminator. The
|
|
member <structfield>len</structfield> holds the length of the
|
|
string stored in the <structfield>arr</structfield> without the
|
|
terminating zero byte. When a host variable is used as input for
|
|
a query, if <literal>strlen(arr)</literal>
|
|
and <structfield>len</structfield> are different, the shorter one
|
|
is used.
|
|
</para>
|
|
|
|
<para>
|
|
<type>VARCHAR</type> can be written in upper or lower case, but
|
|
not in mixed case.
|
|
</para>
|
|
|
|
<para>
|
|
<type>char</type> and <type>VARCHAR</type> host variables can
|
|
also hold values of other SQL types, which will be stored in
|
|
their string forms.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="ecpg-special-types">
|
|
<title>Accessing Special Data Types</title>
|
|
|
|
<para>
|
|
ECPG contains some special types that help you to interact easily
|
|
with some special data types from the PostgreSQL server. In
|
|
particular, it has implemented support for the
|
|
<type>numeric</type>, <type>decimal</type>, <type>date</type>, <type>timestamp</type>,
|
|
and <type>interval</type> types. These data types cannot usefully be
|
|
mapped to primitive host variable types (such
|
|
as <type>int</type>, <type>long long int</type>,
|
|
or <type>char[]</type>), because they have a complex internal
|
|
structure. Applications deal with these types by declaring host
|
|
variables in special types and accessing them using functions in
|
|
the pgtypes library. The pgtypes library, described in detail
|
|
in <xref linkend="ecpg-pgtypes"/> contains basic functions to deal
|
|
with those types, such that you do not need to send a query to
|
|
the SQL server just for adding an interval to a time stamp for
|
|
example.
|
|
</para>
|
|
|
|
<para>
|
|
The follow subsections describe these special data types. For
|
|
more details about pgtypes library functions,
|
|
see <xref linkend="ecpg-pgtypes"/>.
|
|
</para>
|
|
|
|
<sect4>
|
|
<title>timestamp, date</title>
|
|
|
|
<para>
|
|
Here is a pattern for handling <type>timestamp</type> variables
|
|
in the ECPG host application.
|
|
</para>
|
|
|
|
<para>
|
|
First, the program has to include the header file for the
|
|
<type>timestamp</type> type:
|
|
<programlisting>
|
|
#include <pgtypes_timestamp.h>
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Next, declare a host variable as type <type>timestamp</type> in
|
|
the declare section:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
timestamp ts;
|
|
EXEC SQL END DECLARE SECTION;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
And after reading a value into the host variable, process it
|
|
using pgtypes library functions. In following example, the
|
|
<type>timestamp</type> value is converted into text (ASCII) form
|
|
with the <function>PGTYPEStimestamp_to_asc()</function>
|
|
function:
|
|
<programlisting>
|
|
EXEC SQL SELECT now()::timestamp INTO :ts;
|
|
|
|
printf("ts = %s\n", PGTYPEStimestamp_to_asc(ts));
|
|
</programlisting>
|
|
This example will show some result like following:
|
|
<screen>
|
|
ts = 2010-06-27 18:03:56.949343
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
In addition, the DATE type can be handled in the same way. The
|
|
program has to include <filename>pgtypes_date.h</filename>, declare a host variable
|
|
as the date type and convert a DATE value into a text form using
|
|
<function>PGTYPESdate_to_asc()</function> function. For more details about the
|
|
pgtypes library functions, see <xref linkend="ecpg-pgtypes"/>.
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4 id="ecpg-type-interval">
|
|
<title>interval</title>
|
|
|
|
<para>
|
|
The handling of the <type>interval</type> type is also similar
|
|
to the <type>timestamp</type> and <type>date</type> types. It
|
|
is required, however, to allocate memory for
|
|
an <type>interval</type> type value explicitly. In other words,
|
|
the memory space for the variable has to be allocated in the
|
|
heap memory, not in the stack memory.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example program:
|
|
<programlisting>
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <pgtypes_interval.h>
|
|
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
interval *in;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL CONNECT TO testdb;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
in = PGTYPESinterval_new();
|
|
EXEC SQL SELECT '1 min'::interval INTO :in;
|
|
printf("interval = %s\n", PGTYPESinterval_to_asc(in));
|
|
PGTYPESinterval_free(in);
|
|
|
|
EXEC SQL COMMIT;
|
|
EXEC SQL DISCONNECT ALL;
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4 id="ecpg-type-numeric-decimal">
|
|
<title>numeric, decimal</title>
|
|
|
|
<para>
|
|
The handling of the <type>numeric</type>
|
|
and <type>decimal</type> types is similar to the
|
|
<type>interval</type> type: It requires defining a pointer,
|
|
allocating some memory space on the heap, and accessing the
|
|
variable using the pgtypes library functions. For more details
|
|
about the pgtypes library functions,
|
|
see <xref linkend="ecpg-pgtypes"/>.
|
|
</para>
|
|
|
|
<para>
|
|
No functions are provided specifically for
|
|
the <type>decimal</type> type. An application has to convert it
|
|
to a <type>numeric</type> variable using a pgtypes library
|
|
function to do further processing.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example program handling <type>numeric</type>
|
|
and <type>decimal</type> type variables.
|
|
<programlisting>
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <pgtypes_numeric.h>
|
|
|
|
EXEC SQL WHENEVER SQLERROR STOP;
|
|
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
numeric *num;
|
|
numeric *num2;
|
|
decimal *dec;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL CONNECT TO testdb;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
num = PGTYPESnumeric_new();
|
|
dec = PGTYPESdecimal_new();
|
|
|
|
EXEC SQL SELECT 12.345::numeric(4,2), 23.456::decimal(4,2) INTO :num, :dec;
|
|
|
|
printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 0));
|
|
printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 1));
|
|
printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 2));
|
|
|
|
/* Convert decimal to numeric to show a decimal value. */
|
|
num2 = PGTYPESnumeric_new();
|
|
PGTYPESnumeric_from_decimal(dec, num2);
|
|
|
|
printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 0));
|
|
printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 1));
|
|
printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 2));
|
|
|
|
PGTYPESnumeric_free(num2);
|
|
PGTYPESdecimal_free(dec);
|
|
PGTYPESnumeric_free(num);
|
|
|
|
EXEC SQL COMMIT;
|
|
EXEC SQL DISCONNECT ALL;
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>bytea</title>
|
|
|
|
<para>
|
|
The handling of the <type>bytea</type> type is similar to
|
|
that of <type>VARCHAR</type>. The definition on an array of type
|
|
<type>bytea</type> is converted into a named struct for every
|
|
variable. A declaration like:
|
|
<programlisting>
|
|
bytea var[180];
|
|
</programlisting>
|
|
is converted into:
|
|
<programlisting>
|
|
struct bytea_var { int len; char arr[180]; } var;
|
|
</programlisting>
|
|
The member <structfield>arr</structfield> hosts binary format
|
|
data. It can also handle <literal>'\0'</literal> as part of
|
|
data, unlike <type>VARCHAR</type>.
|
|
The data is converted from/to hex format and sent/received by
|
|
ecpglib.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
<type>bytea</type> variable can be used only when
|
|
<xref linkend="guc-bytea-output"/> is set to <literal>hex</literal>.
|
|
</para>
|
|
</note>
|
|
</sect4>
|
|
</sect3>
|
|
|
|
<sect3 id="ecpg-variables-nonprimitive-c">
|
|
<title>Host Variables with Nonprimitive Types</title>
|
|
|
|
<para>
|
|
As a host variable you can also use arrays, typedefs, structs, and
|
|
pointers.
|
|
</para>
|
|
|
|
<sect4 id="ecpg-variables-arrays">
|
|
<title>Arrays</title>
|
|
|
|
<para>
|
|
There are two use cases for arrays as host variables. The first
|
|
is a way to store some text string in <type>char[]</type>
|
|
or <type>VARCHAR[]</type>, as
|
|
explained in <xref linkend="ecpg-char"/>. The second use case is to
|
|
retrieve multiple rows from a query result without using a
|
|
cursor. Without an array, to process a query result consisting
|
|
of multiple rows, it is required to use a cursor and
|
|
the <command>FETCH</command> command. But with array host
|
|
variables, multiple rows can be received at once. The length of
|
|
the array has to be defined to be able to accommodate all rows,
|
|
otherwise a buffer overflow will likely occur.
|
|
</para>
|
|
|
|
<para>
|
|
Following example scans the <literal>pg_database</literal>
|
|
system table and shows all OIDs and names of the available
|
|
databases:
|
|
<programlisting>
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int dbid[8];
|
|
char dbname[8][16];
|
|
int i;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
memset(dbname, 0, sizeof(char)* 16 * 8);
|
|
memset(dbid, 0, sizeof(int) * 8);
|
|
|
|
EXEC SQL CONNECT TO testdb;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
/* Retrieve multiple rows into arrays at once. */
|
|
EXEC SQL SELECT oid,datname INTO :dbid, :dbname FROM pg_database;
|
|
|
|
for (i = 0; i < 8; i++)
|
|
printf("oid=%d, dbname=%s\n", dbid[i], dbname[i]);
|
|
|
|
EXEC SQL COMMIT;
|
|
EXEC SQL DISCONNECT ALL;
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
|
|
This example shows following result. (The exact values depend on
|
|
local circumstances.)
|
|
<screen>
|
|
oid=1, dbname=template1
|
|
oid=11510, dbname=template0
|
|
oid=11511, dbname=postgres
|
|
oid=313780, dbname=testdb
|
|
oid=0, dbname=
|
|
oid=0, dbname=
|
|
oid=0, dbname=
|
|
</screen>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4 id="ecpg-variables-struct">
|
|
<title>Structures</title>
|
|
|
|
<para>
|
|
A structure whose member names match the column names of a query
|
|
result, can be used to retrieve multiple columns at once. The
|
|
structure enables handling multiple column values in a single
|
|
host variable.
|
|
</para>
|
|
|
|
<para>
|
|
The following example retrieves OIDs, names, and sizes of the
|
|
available databases from the <literal>pg_database</literal>
|
|
system table and using
|
|
the <function>pg_database_size()</function> function. In this
|
|
example, a structure variable <varname>dbinfo_t</varname> with
|
|
members whose names match each column in
|
|
the <literal>SELECT</literal> result is used to retrieve one
|
|
result row without putting multiple host variables in
|
|
the <literal>FETCH</literal> statement.
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
typedef struct
|
|
{
|
|
int oid;
|
|
char datname[65];
|
|
long long int size;
|
|
} dbinfo_t;
|
|
|
|
dbinfo_t dbval;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
memset(&dbval, 0, sizeof(dbinfo_t));
|
|
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
/* when end of result set reached, break out of while loop */
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
/* Fetch multiple columns into one structure. */
|
|
EXEC SQL FETCH FROM cur1 INTO :dbval;
|
|
|
|
/* Print members of the structure. */
|
|
printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, dbval.size);
|
|
}
|
|
|
|
EXEC SQL CLOSE cur1;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
This example shows following result. (The exact values depend on
|
|
local circumstances.)
|
|
<screen>
|
|
oid=1, datname=template1, size=4324580
|
|
oid=11510, datname=template0, size=4243460
|
|
oid=11511, datname=postgres, size=4324580
|
|
oid=313780, datname=testdb, size=8183012
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Structure host variables <quote>absorb</quote> as many columns
|
|
as the structure as fields. Additional columns can be assigned
|
|
to other host variables. For example, the above program could
|
|
also be restructured like this, with the <varname>size</varname>
|
|
variable outside the structure:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
typedef struct
|
|
{
|
|
int oid;
|
|
char datname[65];
|
|
} dbinfo_t;
|
|
|
|
dbinfo_t dbval;
|
|
long long int size;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
memset(&dbval, 0, sizeof(dbinfo_t));
|
|
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
/* when end of result set reached, break out of while loop */
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
/* Fetch multiple columns into one structure. */
|
|
EXEC SQL FETCH FROM cur1 INTO :dbval, :size;
|
|
|
|
/* Print members of the structure. */
|
|
printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, size);
|
|
}
|
|
|
|
EXEC SQL CLOSE cur1;
|
|
</programlisting>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Typedefs</title>
|
|
|
|
<para>
|
|
Use the <literal>typedef</literal> keyword to map new types to already
|
|
existing types.
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
typedef char mychartype[40];
|
|
typedef long serial_t;
|
|
EXEC SQL END DECLARE SECTION;
|
|
</programlisting>
|
|
Note that you could also use:
|
|
<programlisting>
|
|
EXEC SQL TYPE serial_t IS long;
|
|
</programlisting>
|
|
This declaration does not need to be part of a declare section.
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Pointers</title>
|
|
|
|
<para>
|
|
You can declare pointers to the most common types. Note however
|
|
that you cannot use pointers as target variables of queries
|
|
without auto-allocation. See <xref linkend="ecpg-descriptors"/>
|
|
for more information on auto-allocation.
|
|
</para>
|
|
|
|
<para>
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int *intp;
|
|
char **charp;
|
|
EXEC SQL END DECLARE SECTION;
|
|
</programlisting>
|
|
</para>
|
|
</sect4>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-variables-nonprimitive-sql">
|
|
<title>Handling Nonprimitive SQL Data Types</title>
|
|
|
|
<para>
|
|
This section contains information on how to handle nonscalar and
|
|
user-defined SQL-level data types in ECPG applications. Note that
|
|
this is distinct from the handling of host variables of
|
|
nonprimitive types, described in the previous section.
|
|
</para>
|
|
|
|
<sect3>
|
|
<title>Arrays</title>
|
|
|
|
<para>
|
|
Multi-dimensional SQL-level arrays are not directly supported in ECPG.
|
|
One-dimensional SQL-level arrays can be mapped into C array host
|
|
variables and vice-versa. However, when creating a statement ecpg does
|
|
not know the types of the columns, so that it cannot check if a C array
|
|
is input into a corresponding SQL-level array. When processing the
|
|
output of a SQL statement, ecpg has the necessary information and thus
|
|
checks if both are arrays.
|
|
</para>
|
|
|
|
<para>
|
|
If a query accesses <emphasis>elements</emphasis> of an array
|
|
separately, then this avoids the use of arrays in ECPG. Then, a
|
|
host variable with a type that can be mapped to the element type
|
|
should be used. For example, if a column type is array of
|
|
<type>integer</type>, a host variable of type <type>int</type>
|
|
can be used. Also if the element type is <type>varchar</type>
|
|
or <type>text</type>, a host variable of type <type>char[]</type>
|
|
or <type>VARCHAR[]</type> can be used.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example. Assume the following table:
|
|
<programlisting>
|
|
CREATE TABLE t3 (
|
|
ii integer[]
|
|
);
|
|
|
|
testdb=> SELECT * FROM t3;
|
|
ii
|
|
-------------
|
|
{1,2,3,4,5}
|
|
(1 row)
|
|
</programlisting>
|
|
|
|
The following example program retrieves the 4th element of the
|
|
array and stores it into a host variable of
|
|
type <type>int</type>:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int ii;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[4] FROM t3;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH FROM cur1 INTO :ii ;
|
|
printf("ii=%d\n", ii);
|
|
}
|
|
|
|
EXEC SQL CLOSE cur1;
|
|
</programlisting>
|
|
|
|
This example shows the following result:
|
|
<screen>
|
|
ii=4
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To map multiple array elements to the multiple elements in an
|
|
array type host variables each element of array column and each
|
|
element of the host variable array have to be managed separately,
|
|
for example:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int ii_a[8];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[1], ii[2], ii[3], ii[4] FROM t3;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH FROM cur1 INTO :ii_a[0], :ii_a[1], :ii_a[2], :ii_a[3];
|
|
...
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Note again that
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int ii_a[8];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii FROM t3;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
/* WRONG */
|
|
EXEC SQL FETCH FROM cur1 INTO :ii_a;
|
|
...
|
|
}
|
|
</programlisting>
|
|
would not work correctly in this case, because you cannot map an
|
|
array type column to an array host variable directly.
|
|
</para>
|
|
|
|
<para>
|
|
Another workaround is to store arrays in their external string
|
|
representation in host variables of type <type>char[]</type>
|
|
or <type>VARCHAR[]</type>. For more details about this
|
|
representation, see <xref linkend="arrays-input"/>. Note that
|
|
this means that the array cannot be accessed naturally as an
|
|
array in the host program (without further processing that parses
|
|
the text representation).
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Composite Types</title>
|
|
|
|
<para>
|
|
Composite types are not directly supported in ECPG, but an easy workaround is possible.
|
|
The
|
|
available workarounds are similar to the ones described for
|
|
arrays above: Either access each attribute separately or use the
|
|
external string representation.
|
|
</para>
|
|
|
|
<para>
|
|
For the following examples, assume the following type and table:
|
|
<programlisting>
|
|
CREATE TYPE comp_t AS (intval integer, textval varchar(32));
|
|
CREATE TABLE t4 (compval comp_t);
|
|
INSERT INTO t4 VALUES ( (256, 'PostgreSQL') );
|
|
</programlisting>
|
|
|
|
The most obvious solution is to access each attribute separately.
|
|
The following program retrieves data from the example table by
|
|
selecting each attribute of the type <type>comp_t</type>
|
|
separately:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int intval;
|
|
varchar textval[33];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
/* Put each element of the composite type column in the SELECT list. */
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
/* Fetch each element of the composite type column into host variables. */
|
|
EXEC SQL FETCH FROM cur1 INTO :intval, :textval;
|
|
|
|
printf("intval=%d, textval=%s\n", intval, textval.arr);
|
|
}
|
|
|
|
EXEC SQL CLOSE cur1;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To enhance this example, the host variables to store values in
|
|
the <command>FETCH</command> command can be gathered into one
|
|
structure. For more details about the host variable in the
|
|
structure form, see <xref linkend="ecpg-variables-struct"/>.
|
|
To switch to the structure, the example can be modified as below.
|
|
The two host variables, <varname>intval</varname>
|
|
and <varname>textval</varname>, become members of
|
|
the <structname>comp_t</structname> structure, and the structure
|
|
is specified on the <command>FETCH</command> command.
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
typedef struct
|
|
{
|
|
int intval;
|
|
varchar textval[33];
|
|
} comp_t;
|
|
|
|
comp_t compval;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
/* Put each element of the composite type column in the SELECT list. */
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
/* Put all values in the SELECT list into one structure. */
|
|
EXEC SQL FETCH FROM cur1 INTO :compval;
|
|
|
|
printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr);
|
|
}
|
|
|
|
EXEC SQL CLOSE cur1;
|
|
</programlisting>
|
|
|
|
Although a structure is used in the <command>FETCH</command>
|
|
command, the attribute names in the <command>SELECT</command>
|
|
clause are specified one by one. This can be enhanced by using
|
|
a <literal>*</literal> to ask for all attributes of the composite
|
|
type value.
|
|
<programlisting>
|
|
...
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).* FROM t4;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
/* Put all values in the SELECT list into one structure. */
|
|
EXEC SQL FETCH FROM cur1 INTO :compval;
|
|
|
|
printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr);
|
|
}
|
|
...
|
|
</programlisting>
|
|
This way, composite types can be mapped into structures almost
|
|
seamlessly, even though ECPG does not understand the composite
|
|
type itself.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, it is also possible to store composite type values in
|
|
their external string representation in host variables of
|
|
type <type>char[]</type> or <type>VARCHAR[]</type>. But that
|
|
way, it is not easily possible to access the fields of the value
|
|
from the host program.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>User-Defined Base Types</title>
|
|
|
|
<para>
|
|
New user-defined base types are not directly supported by ECPG.
|
|
You can use the external string representation and host variables
|
|
of type <type>char[]</type> or <type>VARCHAR[]</type>, and this
|
|
solution is indeed appropriate and sufficient for many types.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example using the data type <type>complex</type> from
|
|
the example in <xref linkend="xtypes"/>. The external string
|
|
representation of that type is <literal>(%f,%f)</literal>,
|
|
which is defined in the
|
|
functions <function>complex_in()</function>
|
|
and <function>complex_out()</function> functions
|
|
in <xref linkend="xtypes"/>. The following example inserts the
|
|
complex type values <literal>(1,1)</literal>
|
|
and <literal>(3,3)</literal> into the
|
|
columns <literal>a</literal> and <literal>b</literal>, and select
|
|
them from the table after that.
|
|
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
varchar a[64];
|
|
varchar b[64];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL INSERT INTO test_complex VALUES ('(1,1)', '(3,3)');
|
|
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT a, b FROM test_complex;
|
|
EXEC SQL OPEN cur1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH FROM cur1 INTO :a, :b;
|
|
printf("a=%s, b=%s\n", a.arr, b.arr);
|
|
}
|
|
|
|
EXEC SQL CLOSE cur1;
|
|
</programlisting>
|
|
|
|
This example shows following result:
|
|
<screen>
|
|
a=(1,1), b=(3,3)
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Another workaround is avoiding the direct use of the user-defined
|
|
types in ECPG and instead create a function or cast that converts
|
|
between the user-defined type and a primitive type that ECPG can
|
|
handle. Note, however, that type casts, especially implicit
|
|
ones, should be introduced into the type system very carefully.
|
|
</para>
|
|
|
|
<para>
|
|
For example,
|
|
<programlisting>
|
|
CREATE FUNCTION create_complex(r double, i double) RETURNS complex
|
|
LANGUAGE SQL
|
|
IMMUTABLE
|
|
AS $$ SELECT $1 * complex '(1,0')' + $2 * complex '(0,1)' $$;
|
|
</programlisting>
|
|
After this definition, the following
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
double a, b, c, d;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
a = 1;
|
|
b = 2;
|
|
c = 3;
|
|
d = 4;
|
|
|
|
EXEC SQL INSERT INTO test_complex VALUES (create_complex(:a, :b), create_complex(:c, :d));
|
|
</programlisting>
|
|
has the same effect as
|
|
<programlisting>
|
|
EXEC SQL INSERT INTO test_complex VALUES ('(1,2)', '(3,4)');
|
|
</programlisting>
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-indicators">
|
|
<title>Indicators</title>
|
|
|
|
<para>
|
|
The examples above do not handle null values. In fact, the
|
|
retrieval examples will raise an error if they fetch a null value
|
|
from the database. To be able to pass null values to the database
|
|
or retrieve null values from the database, you need to append a
|
|
second host variable specification to each host variable that
|
|
contains data. This second host variable is called the
|
|
<firstterm>indicator</firstterm> and contains a flag that tells
|
|
whether the datum is null, in which case the value of the real
|
|
host variable is ignored. Here is an example that handles the
|
|
retrieval of null values correctly:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
VARCHAR val;
|
|
int val_ind;
|
|
EXEC SQL END DECLARE SECTION:
|
|
|
|
...
|
|
|
|
EXEC SQL SELECT b INTO :val :val_ind FROM test1;
|
|
</programlisting>
|
|
The indicator variable <varname>val_ind</varname> will be zero if
|
|
the value was not null, and it will be negative if the value was
|
|
null.
|
|
</para>
|
|
|
|
<para>
|
|
The indicator has another function: if the indicator value is
|
|
positive, it means that the value is not null, but it was
|
|
truncated when it was stored in the host variable.
|
|
</para>
|
|
|
|
<para>
|
|
If the argument <literal>-r no_indicator</literal> is passed to
|
|
the preprocessor <command>ecpg</command>, it works in
|
|
<quote>no-indicator</quote> mode. In no-indicator mode, if no
|
|
indicator variable is specified, null values are signaled (on
|
|
input and output) for character string types as empty string and
|
|
for integer types as the lowest possible value for type (for
|
|
example, <symbol>INT_MIN</symbol> for <type>int</type>).
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-dynamic">
|
|
<title>Dynamic SQL</title>
|
|
|
|
<para>
|
|
In many cases, the particular SQL statements that an application
|
|
has to execute are known at the time the application is written.
|
|
In some cases, however, the SQL statements are composed at run time
|
|
or provided by an external source. In these cases you cannot embed
|
|
the SQL statements directly into the C source code, but there is a
|
|
facility that allows you to call arbitrary SQL statements that you
|
|
provide in a string variable.
|
|
</para>
|
|
|
|
<sect2 id="ecpg-dynamic-without-result">
|
|
<title>Executing Statements without a Result Set</title>
|
|
|
|
<para>
|
|
The simplest way to execute an arbitrary SQL statement is to use
|
|
the command <command>EXECUTE IMMEDIATE</command>. For example:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
const char *stmt = "CREATE TABLE test1 (...);";
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL EXECUTE IMMEDIATE :stmt;
|
|
</programlisting>
|
|
<command>EXECUTE IMMEDIATE</command> can be used for SQL
|
|
statements that do not return a result set (e.g.,
|
|
DDL, <command>INSERT</command>, <command>UPDATE</command>,
|
|
<command>DELETE</command>). You cannot execute statements that
|
|
retrieve data (e.g., <command>SELECT</command>) this way. The
|
|
next section describes how to do that.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-dynamic-input">
|
|
<title>Executing a Statement with Input Parameters</title>
|
|
|
|
<para>
|
|
A more powerful way to execute arbitrary SQL statements is to
|
|
prepare them once and execute the prepared statement as often as
|
|
you like. It is also possible to prepare a generalized version of
|
|
a statement and then execute specific versions of it by
|
|
substituting parameters. When preparing the statement, write
|
|
question marks where you want to substitute parameters later. For
|
|
example:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
const char *stmt = "INSERT INTO test1 VALUES(?, ?);";
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL PREPARE mystmt FROM :stmt;
|
|
...
|
|
EXEC SQL EXECUTE mystmt USING 42, 'foobar';
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
When you don't need the prepared statement anymore, you should
|
|
deallocate it:
|
|
<programlisting>
|
|
EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-dynamic-with-result">
|
|
<title>Executing a Statement with a Result Set</title>
|
|
|
|
<para>
|
|
To execute an SQL statement with a single result row,
|
|
<command>EXECUTE</command> can be used. To save the result, add
|
|
an <literal>INTO</literal> clause.
|
|
<programlisting><![CDATA[
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
const char *stmt = "SELECT a, b, c FROM test1 WHERE a > ?";
|
|
int v1, v2;
|
|
VARCHAR v3[50];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL PREPARE mystmt FROM :stmt;
|
|
...
|
|
EXEC SQL EXECUTE mystmt INTO :v1, :v2, :v3 USING 37;
|
|
]]>
|
|
</programlisting>
|
|
An <command>EXECUTE</command> command can have an
|
|
<literal>INTO</literal> clause, a <literal>USING</literal> clause,
|
|
both, or neither.
|
|
</para>
|
|
|
|
<para>
|
|
If a query is expected to return more than one result row, a
|
|
cursor should be used, as in the following example.
|
|
(See <xref linkend="ecpg-cursors"/> for more details about the
|
|
cursor.)
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char dbaname[128];
|
|
char datname[128];
|
|
char *stmt = "SELECT u.usename as dbaname, d.datname "
|
|
" FROM pg_database d, pg_user u "
|
|
" WHERE d.datdba = u.usesysid";
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL CONNECT TO testdb AS con1 USER testuser;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
EXEC SQL PREPARE stmt1 FROM :stmt;
|
|
|
|
EXEC SQL DECLARE cursor1 CURSOR FOR stmt1;
|
|
EXEC SQL OPEN cursor1;
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH cursor1 INTO :dbaname,:datname;
|
|
printf("dbaname=%s, datname=%s\n", dbaname, datname);
|
|
}
|
|
|
|
EXEC SQL CLOSE cursor1;
|
|
|
|
EXEC SQL COMMIT;
|
|
EXEC SQL DISCONNECT ALL;
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-pgtypes">
|
|
<title>pgtypes Library</title>
|
|
|
|
<para>
|
|
The pgtypes library maps <productname>PostgreSQL</productname> database
|
|
types to C equivalents that can be used in C programs. It also offers
|
|
functions to do basic calculations with those types within C, i.e., without
|
|
the help of the <productname>PostgreSQL</productname> server. See the
|
|
following example:
|
|
<programlisting><![CDATA[
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
date date1;
|
|
timestamp ts1, tsout;
|
|
interval iv1;
|
|
char *out;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
PGTYPESdate_today(&date1);
|
|
EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
|
|
PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
|
|
out = PGTYPEStimestamp_to_asc(&tsout);
|
|
printf("Started + duration: %s\n", out);
|
|
PGTYPESchar_free(out);
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
|
|
<sect2 id="ecpg-pgtypes-cstrings">
|
|
<title>Character Strings</title>
|
|
<para>
|
|
Some functions such as <function>PGTYPESnumeric_to_asc</function> return
|
|
a pointer to a freshly allocated character string. These results should be
|
|
freed with <function>PGTYPESchar_free</function> instead of
|
|
<function>free</function>. (This is important only on Windows, where
|
|
memory allocation and release sometimes need to be done by the same
|
|
library.)
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-pgtypes-numeric">
|
|
<title>The numeric Type</title>
|
|
<para>
|
|
The numeric type offers to do calculations with arbitrary precision. See
|
|
<xref linkend="datatype-numeric"/> for the equivalent type in the
|
|
<productname>PostgreSQL</productname> server. Because of the arbitrary precision this
|
|
variable needs to be able to expand and shrink dynamically. That's why you
|
|
can only create numeric variables on the heap, by means of the
|
|
<function>PGTYPESnumeric_new</function> and <function>PGTYPESnumeric_free</function>
|
|
functions. The decimal type, which is similar but limited in precision,
|
|
can be created on the stack as well as on the heap.
|
|
</para>
|
|
<para>
|
|
The following functions can be used to work with the numeric type:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_new</function></term>
|
|
<listitem>
|
|
<para>
|
|
Request a pointer to a newly allocated numeric variable.
|
|
<synopsis>
|
|
numeric *PGTYPESnumeric_new(void);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_free</function></term>
|
|
<listitem>
|
|
<para>
|
|
Free a numeric type, release all of its memory.
|
|
<synopsis>
|
|
void PGTYPESnumeric_free(numeric *var);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_from_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parse a numeric type from its string notation.
|
|
<synopsis>
|
|
numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);
|
|
</synopsis>
|
|
Valid formats are for example:
|
|
<literal>-2</literal>,
|
|
<literal>.794</literal>,
|
|
<literal>+3.44</literal>,
|
|
<literal>592.49E07</literal> or
|
|
<literal>-32.84e-4</literal>.
|
|
If the value could be parsed successfully, a valid pointer is returned,
|
|
else the NULL pointer. At the moment ECPG always parses the complete
|
|
string and so it currently does not support to store the address of the
|
|
first invalid character in <literal>*endptr</literal>. You can safely
|
|
set <literal>endptr</literal> to NULL.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_to_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Returns a pointer to a string allocated by <function>malloc</function> that contains the string
|
|
representation of the numeric type <literal>num</literal>.
|
|
<synopsis>
|
|
char *PGTYPESnumeric_to_asc(numeric *num, int dscale);
|
|
</synopsis>
|
|
The numeric value will be printed with <literal>dscale</literal> decimal
|
|
digits, with rounding applied if necessary.
|
|
The result must be freed with <function>PGTYPESchar_free()</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_add</function></term>
|
|
<listitem>
|
|
<para>
|
|
Add two numeric variables into a third one.
|
|
<synopsis>
|
|
int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);
|
|
</synopsis>
|
|
The function adds the variables <literal>var1</literal> and
|
|
<literal>var2</literal> into the result variable
|
|
<literal>result</literal>.
|
|
The function returns 0 on success and -1 in case of error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_sub</function></term>
|
|
<listitem>
|
|
<para>
|
|
Subtract two numeric variables and return the result in a third one.
|
|
<synopsis>
|
|
int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);
|
|
</synopsis>
|
|
The function subtracts the variable <literal>var2</literal> from
|
|
the variable <literal>var1</literal>. The result of the operation is
|
|
stored in the variable <literal>result</literal>.
|
|
The function returns 0 on success and -1 in case of error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_mul</function></term>
|
|
<listitem>
|
|
<para>
|
|
Multiply two numeric variables and return the result in a third one.
|
|
<synopsis>
|
|
int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);
|
|
</synopsis>
|
|
The function multiplies the variables <literal>var1</literal> and
|
|
<literal>var2</literal>. The result of the operation is stored in the
|
|
variable <literal>result</literal>.
|
|
The function returns 0 on success and -1 in case of error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_div</function></term>
|
|
<listitem>
|
|
<para>
|
|
Divide two numeric variables and return the result in a third one.
|
|
<synopsis>
|
|
int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);
|
|
</synopsis>
|
|
The function divides the variables <literal>var1</literal> by
|
|
<literal>var2</literal>. The result of the operation is stored in the
|
|
variable <literal>result</literal>.
|
|
The function returns 0 on success and -1 in case of error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_cmp</function></term>
|
|
<listitem>
|
|
<para>
|
|
Compare two numeric variables.
|
|
<synopsis>
|
|
int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)
|
|
</synopsis>
|
|
This function compares two numeric variables. In case of error,
|
|
<literal>INT_MAX</literal> is returned. On success, the function
|
|
returns one of three possible results:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
1, if <literal>var1</literal> is bigger than <literal>var2</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
-1, if <literal>var1</literal> is smaller than <literal>var2</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
0, if <literal>var1</literal> and <literal>var2</literal> are equal
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_from_int</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert an int variable to a numeric variable.
|
|
<synopsis>
|
|
int PGTYPESnumeric_from_int(signed int int_val, numeric *var);
|
|
</synopsis>
|
|
This function accepts a variable of type signed int and stores it
|
|
in the numeric variable <literal>var</literal>. Upon success, 0 is returned and
|
|
-1 in case of a failure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_from_long</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a long int variable to a numeric variable.
|
|
<synopsis>
|
|
int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);
|
|
</synopsis>
|
|
This function accepts a variable of type signed long int and stores it
|
|
in the numeric variable <literal>var</literal>. Upon success, 0 is returned and
|
|
-1 in case of a failure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_copy</function></term>
|
|
<listitem>
|
|
<para>
|
|
Copy over one numeric variable into another one.
|
|
<synopsis>
|
|
int PGTYPESnumeric_copy(numeric *src, numeric *dst);
|
|
</synopsis>
|
|
This function copies over the value of the variable that
|
|
<literal>src</literal> points to into the variable that <literal>dst</literal>
|
|
points to. It returns 0 on success and -1 if an error occurs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_from_double</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type double to a numeric.
|
|
<synopsis>
|
|
int PGTYPESnumeric_from_double(double d, numeric *dst);
|
|
</synopsis>
|
|
This function accepts a variable of type double and stores the result
|
|
in the variable that <literal>dst</literal> points to. It returns 0 on success
|
|
and -1 if an error occurs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_to_double</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type numeric to double.
|
|
<synopsis>
|
|
int PGTYPESnumeric_to_double(numeric *nv, double *dp)
|
|
</synopsis>
|
|
The function converts the numeric value from the variable that
|
|
<literal>nv</literal> points to into the double variable that <literal>dp</literal> points
|
|
to. It returns 0 on success and -1 if an error occurs, including
|
|
overflow. On overflow, the global variable <literal>errno</literal> will be set
|
|
to <literal>PGTYPES_NUM_OVERFLOW</literal> additionally.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_to_int</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type numeric to int.
|
|
<synopsis>
|
|
int PGTYPESnumeric_to_int(numeric *nv, int *ip);
|
|
</synopsis>
|
|
The function converts the numeric value from the variable that
|
|
<literal>nv</literal> points to into the integer variable that <literal>ip</literal>
|
|
points to. It returns 0 on success and -1 if an error occurs, including
|
|
overflow. On overflow, the global variable <literal>errno</literal> will be set
|
|
to <literal>PGTYPES_NUM_OVERFLOW</literal> additionally.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_to_long</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type numeric to long.
|
|
<synopsis>
|
|
int PGTYPESnumeric_to_long(numeric *nv, long *lp);
|
|
</synopsis>
|
|
The function converts the numeric value from the variable that
|
|
<literal>nv</literal> points to into the long integer variable that
|
|
<literal>lp</literal> points to. It returns 0 on success and -1 if an error
|
|
occurs, including overflow. On overflow, the global variable
|
|
<literal>errno</literal> will be set to <literal>PGTYPES_NUM_OVERFLOW</literal>
|
|
additionally.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_to_decimal</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type numeric to decimal.
|
|
<synopsis>
|
|
int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);
|
|
</synopsis>
|
|
The function converts the numeric value from the variable that
|
|
<literal>src</literal> points to into the decimal variable that
|
|
<literal>dst</literal> points to. It returns 0 on success and -1 if an error
|
|
occurs, including overflow. On overflow, the global variable
|
|
<literal>errno</literal> will be set to <literal>PGTYPES_NUM_OVERFLOW</literal>
|
|
additionally.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESnumeric_from_decimal</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type decimal to numeric.
|
|
<synopsis>
|
|
int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);
|
|
</synopsis>
|
|
The function converts the decimal value from the variable that
|
|
<literal>src</literal> points to into the numeric variable that
|
|
<literal>dst</literal> points to. It returns 0 on success and -1 if an error
|
|
occurs. Since the decimal type is implemented as a limited version of
|
|
the numeric type, overflow cannot occur with this conversion.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-pgtypes-date">
|
|
<title>The date Type</title>
|
|
<para>
|
|
The date type in C enables your programs to deal with data of the SQL type
|
|
date. See <xref linkend="datatype-datetime"/> for the equivalent type in the
|
|
<productname>PostgreSQL</productname> server.
|
|
</para>
|
|
<para>
|
|
The following functions can be used to work with the date type:
|
|
<variablelist>
|
|
<varlistentry id="pgtypesdatefromtimestamp">
|
|
<term><function>PGTYPESdate_from_timestamp</function></term>
|
|
<listitem>
|
|
<para>
|
|
Extract the date part from a timestamp.
|
|
<synopsis>
|
|
date PGTYPESdate_from_timestamp(timestamp dt);
|
|
</synopsis>
|
|
The function receives a timestamp as its only argument and returns the
|
|
extracted date part from this timestamp.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatefromasc">
|
|
<term><function>PGTYPESdate_from_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parse a date from its textual representation.
|
|
<synopsis>
|
|
date PGTYPESdate_from_asc(char *str, char **endptr);
|
|
</synopsis>
|
|
The function receives a C char* string <literal>str</literal> and a pointer to
|
|
a C char* string <literal>endptr</literal>. At the moment ECPG always parses
|
|
the complete string and so it currently does not support to store the
|
|
address of the first invalid character in <literal>*endptr</literal>.
|
|
You can safely set <literal>endptr</literal> to NULL.
|
|
</para>
|
|
<para>
|
|
Note that the function always assumes MDY-formatted dates and there is
|
|
currently no variable to change that within ECPG.
|
|
</para>
|
|
<para>
|
|
<xref linkend="ecpg-pgtypesdate-from-asc-table"/> shows the allowed input formats.
|
|
</para>
|
|
<table id="ecpg-pgtypesdate-from-asc-table">
|
|
<title>Valid Input Formats for <function>PGTYPESdate_from_asc</function></title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Input</entry>
|
|
<entry>Result</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1999-01-08</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1/8/1999</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1/18/1999</literal></entry>
|
|
<entry><literal>January 18, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>01/02/03</literal></entry>
|
|
<entry><literal>February 1, 2003</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1999-Jan-08</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>Jan-08-1999</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>08-Jan-1999</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>99-Jan-08</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>08-Jan-99</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>08-Jan-06</literal></entry>
|
|
<entry><literal>January 8, 2006</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>Jan-08-99</literal></entry>
|
|
<entry><literal>January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>19990108</literal></entry>
|
|
<entry><literal>ISO 8601; January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>990108</literal></entry>
|
|
<entry><literal>ISO 8601; January 8, 1999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1999.008</literal></entry>
|
|
<entry><literal>year and day of year</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>J2451187</literal></entry>
|
|
<entry><literal>Julian day</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>January 8, 99 BC</literal></entry>
|
|
<entry><literal>year 99 before the Common Era</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatetoasc">
|
|
<term><function>PGTYPESdate_to_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Return the textual representation of a date variable.
|
|
<synopsis>
|
|
char *PGTYPESdate_to_asc(date dDate);
|
|
</synopsis>
|
|
The function receives the date <literal>dDate</literal> as its only parameter.
|
|
It will output the date in the form <literal>1999-01-18</literal>, i.e., in the
|
|
<literal>YYYY-MM-DD</literal> format.
|
|
The result must be freed with <function>PGTYPESchar_free()</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatejulmdy">
|
|
<term><function>PGTYPESdate_julmdy</function></term>
|
|
<listitem>
|
|
<para>
|
|
Extract the values for the day, the month and the year from a variable
|
|
of type date.
|
|
<synopsis>
|
|
void PGTYPESdate_julmdy(date d, int *mdy);
|
|
</synopsis>
|
|
<!-- almost same description as for rjulmdy() -->
|
|
The function receives the date <literal>d</literal> and a pointer to an array
|
|
of 3 integer values <literal>mdy</literal>. The variable name indicates
|
|
the sequential order: <literal>mdy[0]</literal> will be set to contain the
|
|
number of the month, <literal>mdy[1]</literal> will be set to the value of the
|
|
day and <literal>mdy[2]</literal> will contain the year.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatemdyjul">
|
|
<term><function>PGTYPESdate_mdyjul</function></term>
|
|
<listitem>
|
|
<para>
|
|
Create a date value from an array of 3 integers that specify the
|
|
day, the month and the year of the date.
|
|
<synopsis>
|
|
void PGTYPESdate_mdyjul(int *mdy, date *jdate);
|
|
</synopsis>
|
|
The function receives the array of the 3 integers (<literal>mdy</literal>) as
|
|
its first argument and as its second argument a pointer to a variable
|
|
of type date that should hold the result of the operation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatedayofweek">
|
|
<term><function>PGTYPESdate_dayofweek</function></term>
|
|
<listitem>
|
|
<para>
|
|
Return a number representing the day of the week for a date value.
|
|
<synopsis>
|
|
int PGTYPESdate_dayofweek(date d);
|
|
</synopsis>
|
|
The function receives the date variable <literal>d</literal> as its only
|
|
argument and returns an integer that indicates the day of the week for
|
|
this date.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
0 - Sunday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
1 - Monday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
2 - Tuesday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
3 - Wednesday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
4 - Thursday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
5 - Friday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
6 - Saturday
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatetoday">
|
|
<term><function>PGTYPESdate_today</function></term>
|
|
<listitem>
|
|
<para>
|
|
Get the current date.
|
|
<synopsis>
|
|
void PGTYPESdate_today(date *d);
|
|
</synopsis>
|
|
The function receives a pointer to a date variable (<literal>d</literal>)
|
|
that it sets to the current date.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatefmtasc">
|
|
<term><function>PGTYPESdate_fmt_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type date to its textual representation using a
|
|
format mask.
|
|
<synopsis>
|
|
int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
|
|
</synopsis>
|
|
The function receives the date to convert (<literal>dDate</literal>), the
|
|
format mask (<literal>fmtstring</literal>) and the string that will hold the
|
|
textual representation of the date (<literal>outbuf</literal>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if an error occurred.
|
|
</para>
|
|
<para>
|
|
The following literals are the field specifiers you can use:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>dd</literal> - The number of the day of the month.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>mm</literal> - The number of the month of the year.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>yy</literal> - The number of the year as a two digit number.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>yyyy</literal> - The number of the year as a four digit number.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ddd</literal> - The name of the day (abbreviated).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>mmm</literal> - The name of the month (abbreviated).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
All other characters are copied 1:1 to the output string.
|
|
</para>
|
|
<para>
|
|
<xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"/> indicates a few possible formats. This will give
|
|
you an idea of how to use this function. All output lines are based on
|
|
the same date: November 23, 1959.
|
|
</para>
|
|
<table id="ecpg-pgtypesdate-fmt-asc-example-table">
|
|
<title>Valid Input Formats for <function>PGTYPESdate_fmt_asc</function></title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Format</entry>
|
|
<entry>Result</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>mmddyy</literal></entry>
|
|
<entry><literal>112359</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>ddmmyy</literal></entry>
|
|
<entry><literal>231159</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yymmdd</literal></entry>
|
|
<entry><literal>591123</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yy/mm/dd</literal></entry>
|
|
<entry><literal>59/11/23</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yy mm dd</literal></entry>
|
|
<entry><literal>59 11 23</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yy.mm.dd</literal></entry>
|
|
<entry><literal>59.11.23</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>.mm.yyyy.dd.</literal></entry>
|
|
<entry><literal>.11.1959.23.</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>mmm. dd, yyyy</literal></entry>
|
|
<entry><literal>Nov. 23, 1959</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>mmm dd yyyy</literal></entry>
|
|
<entry><literal>Nov 23 1959</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yyyy dd mm</literal></entry>
|
|
<entry><literal>1959 23 11</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>ddd, mmm. dd, yyyy</literal></entry>
|
|
<entry><literal>Mon, Nov. 23, 1959</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>(ddd) mmm. dd, yyyy</literal></entry>
|
|
<entry><literal>(Mon) Nov. 23, 1959</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesdatedefmtasc">
|
|
<term><function>PGTYPESdate_defmt_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Use a format mask to convert a C <type>char*</type> string to a value of type
|
|
date.
|
|
<synopsis>
|
|
int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
|
|
</synopsis>
|
|
<!-- same description as rdefmtdate -->
|
|
The function receives a pointer to the date value that should hold the
|
|
result of the operation (<literal>d</literal>), the format mask to use for
|
|
parsing the date (<literal>fmt</literal>) and the C char* string containing
|
|
the textual representation of the date (<literal>str</literal>). The textual
|
|
representation is expected to match the format mask. However you do not
|
|
need to have a 1:1 mapping of the string to the format mask. The
|
|
function only analyzes the sequential order and looks for the literals
|
|
<literal>yy</literal> or <literal>yyyy</literal> that indicate the
|
|
position of the year, <literal>mm</literal> to indicate the position of
|
|
the month and <literal>dd</literal> to indicate the position of the
|
|
day.
|
|
</para>
|
|
<para>
|
|
<xref linkend="ecpg-rdefmtdate-example-table"/> indicates a few possible formats. This will give
|
|
you an idea of how to use this function.
|
|
</para>
|
|
<table id="ecpg-rdefmtdate-example-table">
|
|
<title>Valid Input Formats for <function>rdefmtdate</function></title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Format</entry>
|
|
<entry>String</entry>
|
|
<entry>Result</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>ddmmyy</literal></entry>
|
|
<entry><literal>21-2-54</literal></entry>
|
|
<entry><literal>1954-02-21</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>ddmmyy</literal></entry>
|
|
<entry><literal>2-12-54</literal></entry>
|
|
<entry><literal>1954-12-02</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>ddmmyy</literal></entry>
|
|
<entry><literal>20111954</literal></entry>
|
|
<entry><literal>1954-11-20</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>ddmmyy</literal></entry>
|
|
<entry><literal>130464</literal></entry>
|
|
<entry><literal>1964-04-13</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>mmm.dd.yyyy</literal></entry>
|
|
<entry><literal>MAR-12-1967</literal></entry>
|
|
<entry><literal>1967-03-12</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yy/mm/dd</literal></entry>
|
|
<entry><literal>1954, February 3rd</literal></entry>
|
|
<entry><literal>1954-02-03</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>mmm.dd.yyyy</literal></entry>
|
|
<entry><literal>041269</literal></entry>
|
|
<entry><literal>1969-04-12</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yy/mm/dd</literal></entry>
|
|
<entry><literal>In the year 2525, in the month of July, mankind will be alive on the 28th day</literal></entry>
|
|
<entry><literal>2525-07-28</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>dd-mm-yy</literal></entry>
|
|
<entry><literal>I said on the 28th of July in the year 2525</literal></entry>
|
|
<entry><literal>2525-07-28</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>mmm.dd.yyyy</literal></entry>
|
|
<entry><literal>9/14/58</literal></entry>
|
|
<entry><literal>1958-09-14</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>yy/mm/dd</literal></entry>
|
|
<entry><literal>47/03/29</literal></entry>
|
|
<entry><literal>1947-03-29</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>mmm.dd.yyyy</literal></entry>
|
|
<entry><literal>oct 28 1975</literal></entry>
|
|
<entry><literal>1975-10-28</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>mmddyy</literal></entry>
|
|
<entry><literal>Nov 14th, 1985</literal></entry>
|
|
<entry><literal>1985-11-14</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-pgtypes-timestamp">
|
|
<title>The timestamp Type</title>
|
|
<para>
|
|
The timestamp type in C enables your programs to deal with data of the SQL
|
|
type timestamp. See <xref linkend="datatype-datetime"/> for the equivalent
|
|
type in the <productname>PostgreSQL</productname> server.
|
|
</para>
|
|
<para>
|
|
The following functions can be used to work with the timestamp type:
|
|
<variablelist>
|
|
<varlistentry id="pgtypestimestampfromasc">
|
|
<term><function>PGTYPEStimestamp_from_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parse a timestamp from its textual representation into a timestamp
|
|
variable.
|
|
<synopsis>
|
|
timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
|
|
</synopsis>
|
|
The function receives the string to parse (<literal>str</literal>) and a
|
|
pointer to a C char* (<literal>endptr</literal>).
|
|
At the moment ECPG always parses
|
|
the complete string and so it currently does not support to store the
|
|
address of the first invalid character in <literal>*endptr</literal>.
|
|
You can safely set <literal>endptr</literal> to NULL.
|
|
</para>
|
|
<para>
|
|
The function returns the parsed timestamp on success. On error,
|
|
<literal>PGTYPESInvalidTimestamp</literal> is returned and <varname>errno</varname> is
|
|
set to <literal>PGTYPES_TS_BAD_TIMESTAMP</literal>. See <xref linkend="pgtypesinvalidtimestamp"/> for important notes on this value.
|
|
</para>
|
|
<para>
|
|
In general, the input string can contain any combination of an allowed
|
|
date specification, a whitespace character and an allowed time
|
|
specification. Note that time zones are not supported by ECPG. It can
|
|
parse them but does not apply any calculation as the
|
|
<productname>PostgreSQL</productname> server does for example. Timezone
|
|
specifiers are silently discarded.
|
|
</para>
|
|
<para>
|
|
<xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"/> contains a few examples for input strings.
|
|
</para>
|
|
<table id="ecpg-pgtypestimestamp-from-asc-example-table">
|
|
<title>Valid Input Formats for <function>PGTYPEStimestamp_from_asc</function></title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Input</entry>
|
|
<entry>Result</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>1999-01-08 04:05:06</literal></entry>
|
|
<entry><literal>1999-01-08 04:05:06</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>January 8 04:05:06 1999 PST</literal></entry>
|
|
<entry><literal>1999-01-08 04:05:06</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>1999-Jan-08 04:05:06.789-8</literal></entry>
|
|
<entry><literal>1999-01-08 04:05:06.789 (time zone specifier ignored)</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>J2451187 04:05-08:00</literal></entry>
|
|
<entry><literal>1999-01-08 04:05:00 (time zone specifier ignored)</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypestimestamptoasc">
|
|
<term><function>PGTYPEStimestamp_to_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Converts a date to a C char* string.
|
|
<synopsis>
|
|
char *PGTYPEStimestamp_to_asc(timestamp tstamp);
|
|
</synopsis>
|
|
The function receives the timestamp <literal>tstamp</literal> as
|
|
its only argument and returns an allocated string that contains the
|
|
textual representation of the timestamp.
|
|
The result must be freed with <function>PGTYPESchar_free()</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypestimestampcurrent">
|
|
<term><function>PGTYPEStimestamp_current</function></term>
|
|
<listitem>
|
|
<para>
|
|
Retrieve the current timestamp.
|
|
<synopsis>
|
|
void PGTYPEStimestamp_current(timestamp *ts);
|
|
</synopsis>
|
|
The function retrieves the current timestamp and saves it into the
|
|
timestamp variable that <literal>ts</literal> points to.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypestimestampfmtasc">
|
|
<term><function>PGTYPEStimestamp_fmt_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a timestamp variable to a C char* using a format mask.
|
|
<synopsis>
|
|
int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);
|
|
</synopsis>
|
|
The function receives a pointer to the timestamp to convert as its
|
|
first argument (<literal>ts</literal>), a pointer to the output buffer
|
|
(<literal>output</literal>), the maximal length that has been allocated for
|
|
the output buffer (<literal>str_len</literal>) and the format mask to
|
|
use for the conversion (<literal>fmtstr</literal>).
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
<para>
|
|
You can use the following format specifiers for the format mask. The
|
|
format specifiers are the same ones that are used in the
|
|
<function>strftime</function> function in <productname>libc</productname>. Any
|
|
non-format specifier will be copied into the output buffer.
|
|
<!-- This is from the FreeBSD man page:
|
|
http://www.freebsd.org/cgi/man.cgi?query=strftime&apropos=0&sektion=3&manpath=FreeBSD+7.0-current&format=html
|
|
-->
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>%A</literal> - is replaced by national representation of
|
|
the full weekday name.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%a</literal> - is replaced by national representation of
|
|
the abbreviated weekday name.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%B</literal> - is replaced by national representation of
|
|
the full month name.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%b</literal> - is replaced by national representation of
|
|
the abbreviated month name.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%C</literal> - is replaced by (year / 100) as decimal
|
|
number; single digits are preceded by a zero.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%c</literal> - is replaced by national representation of
|
|
time and date.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%D</literal> - is equivalent to
|
|
<literal>%m/%d/%y</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%d</literal> - is replaced by the day of the month as a
|
|
decimal number (01–31).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%E*</literal> <literal>%O*</literal> - POSIX locale
|
|
extensions. The sequences
|
|
<literal>%Ec</literal>
|
|
<literal>%EC</literal>
|
|
<literal>%Ex</literal>
|
|
<literal>%EX</literal>
|
|
<literal>%Ey</literal>
|
|
<literal>%EY</literal>
|
|
<literal>%Od</literal>
|
|
<literal>%Oe</literal>
|
|
<literal>%OH</literal>
|
|
<literal>%OI</literal>
|
|
<literal>%Om</literal>
|
|
<literal>%OM</literal>
|
|
<literal>%OS</literal>
|
|
<literal>%Ou</literal>
|
|
<literal>%OU</literal>
|
|
<literal>%OV</literal>
|
|
<literal>%Ow</literal>
|
|
<literal>%OW</literal>
|
|
<literal>%Oy</literal>
|
|
are supposed to provide alternative representations.
|
|
</para>
|
|
<para>
|
|
Additionally <literal>%OB</literal> implemented to represent
|
|
alternative months names (used standalone, without day mentioned).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%e</literal> - is replaced by the day of month as a decimal
|
|
number (1–31); single digits are preceded by a blank.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%F</literal> - is equivalent to <literal>%Y-%m-%d</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%G</literal> - is replaced by a year as a decimal number
|
|
with century. This year is the one that contains the greater part of
|
|
the week (Monday as the first day of the week).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%g</literal> - is replaced by the same year as in
|
|
<literal>%G</literal>, but as a decimal number without century
|
|
(00–99).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%H</literal> - is replaced by the hour (24-hour clock) as a
|
|
decimal number (00–23).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%h</literal> - the same as <literal>%b</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%I</literal> - is replaced by the hour (12-hour clock) as a
|
|
decimal number (01–12).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%j</literal> - is replaced by the day of the year as a
|
|
decimal number (001–366).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%k</literal> - is replaced by the hour (24-hour clock) as a
|
|
decimal number (0–23); single digits are preceded by a blank.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%l</literal> - is replaced by the hour (12-hour clock) as a
|
|
decimal number (1–12); single digits are preceded by a blank.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%M</literal> - is replaced by the minute as a decimal
|
|
number (00–59).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%m</literal> - is replaced by the month as a decimal number
|
|
(01–12).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%n</literal> - is replaced by a newline.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%O*</literal> - the same as <literal>%E*</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%p</literal> - is replaced by national representation of
|
|
either <quote>ante meridiem</quote> or <quote>post meridiem</quote> as appropriate.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%R</literal> - is equivalent to <literal>%H:%M</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%r</literal> - is equivalent to <literal>%I:%M:%S
|
|
%p</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%S</literal> - is replaced by the second as a decimal
|
|
number (00–60).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%s</literal> - is replaced by the number of seconds since
|
|
the Epoch, UTC.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%T</literal> - is equivalent to <literal>%H:%M:%S</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%t</literal> - is replaced by a tab.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%U</literal> - is replaced by the week number of the year
|
|
(Sunday as the first day of the week) as a decimal number (00–53).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%u</literal> - is replaced by the weekday (Monday as the
|
|
first day of the week) as a decimal number (1–7).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%V</literal> - is replaced by the week number of the year
|
|
(Monday as the first day of the week) as a decimal number (01–53).
|
|
If the week containing January 1 has four or more days in the new
|
|
year, then it is week 1; otherwise it is the last week of the
|
|
previous year, and the next week is week 1.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%v</literal> - is equivalent to
|
|
<literal>%e-%b-%Y</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%W</literal> - is replaced by the week number of the year
|
|
(Monday as the first day of the week) as a decimal number (00–53).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%w</literal> - is replaced by the weekday (Sunday as the
|
|
first day of the week) as a decimal number (0–6).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%X</literal> - is replaced by national representation of
|
|
the time.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%x</literal> - is replaced by national representation of
|
|
the date.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%Y</literal> - is replaced by the year with century as a
|
|
decimal number.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%y</literal> - is replaced by the year without century as a
|
|
decimal number (00–99).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%Z</literal> - is replaced by the time zone name.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%z</literal> - is replaced by the time zone offset from
|
|
UTC; a leading plus sign stands for east of UTC, a minus sign for
|
|
west of UTC, hours and minutes follow with two digits each and no
|
|
delimiter between them (common form for RFC 822 date headers).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%+</literal> - is replaced by national representation of
|
|
the date and time.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%-*</literal> - GNU libc extension. Do not do any padding
|
|
when performing numerical outputs.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
$_* - GNU libc extension. Explicitly specify space for padding.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%0*</literal> - GNU libc extension. Explicitly specify zero
|
|
for padding.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>%%</literal> - is replaced by <literal>%</literal>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypestimestampsub">
|
|
<term><function>PGTYPEStimestamp_sub</function></term>
|
|
<listitem>
|
|
<para>
|
|
Subtract one timestamp from another one and save the result in a
|
|
variable of type interval.
|
|
<synopsis>
|
|
int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);
|
|
</synopsis>
|
|
The function will subtract the timestamp variable that <literal>ts2</literal>
|
|
points to from the timestamp variable that <literal>ts1</literal> points to
|
|
and will store the result in the interval variable that <literal>iv</literal>
|
|
points to.
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypestimestampdefmtasc">
|
|
<term><function>PGTYPEStimestamp_defmt_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parse a timestamp value from its textual representation using a
|
|
formatting mask.
|
|
<synopsis>
|
|
int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
|
|
</synopsis>
|
|
The function receives the textual representation of a timestamp in the
|
|
variable <literal>str</literal> as well as the formatting mask to use in the
|
|
variable <literal>fmt</literal>. The result will be stored in the variable
|
|
that <literal>d</literal> points to.
|
|
</para>
|
|
<para>
|
|
If the formatting mask <literal>fmt</literal> is NULL, the function will fall
|
|
back to the default formatting mask which is <literal>%Y-%m-%d
|
|
%H:%M:%S</literal>.
|
|
</para>
|
|
<para>
|
|
This is the reverse function to <xref
|
|
linkend="pgtypestimestampfmtasc"/>. See the documentation there in
|
|
order to find out about the possible formatting mask entries.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypestimestampaddinterval">
|
|
<term><function>PGTYPEStimestamp_add_interval</function></term>
|
|
<listitem>
|
|
<para>
|
|
Add an interval variable to a timestamp variable.
|
|
<synopsis>
|
|
int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);
|
|
</synopsis>
|
|
The function receives a pointer to a timestamp variable <literal>tin</literal>
|
|
and a pointer to an interval variable <literal>span</literal>. It adds the
|
|
interval to the timestamp and saves the resulting timestamp in the
|
|
variable that <literal>tout</literal> points to.
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypestimestampsubinterval">
|
|
<term><function>PGTYPEStimestamp_sub_interval</function></term>
|
|
<listitem>
|
|
<para>
|
|
Subtract an interval variable from a timestamp variable.
|
|
<synopsis>
|
|
int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);
|
|
</synopsis>
|
|
The function subtracts the interval variable that <literal>span</literal>
|
|
points to from the timestamp variable that <literal>tin</literal> points to
|
|
and saves the result into the variable that <literal>tout</literal> points
|
|
to.
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-pgtypes-interval">
|
|
<title>The interval Type</title>
|
|
<para>
|
|
The interval type in C enables your programs to deal with data of the SQL
|
|
type interval. See <xref linkend="datatype-datetime"/> for the equivalent
|
|
type in the <productname>PostgreSQL</productname> server.
|
|
</para>
|
|
<para>
|
|
The following functions can be used to work with the interval type:
|
|
<variablelist>
|
|
|
|
<varlistentry id="pgtypesintervalnew">
|
|
<term><function>PGTYPESinterval_new</function></term>
|
|
<listitem>
|
|
<para>
|
|
Return a pointer to a newly allocated interval variable.
|
|
<synopsis>
|
|
interval *PGTYPESinterval_new(void);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesintervalfree">
|
|
<term><function>PGTYPESinterval_free</function></term>
|
|
<listitem>
|
|
<para>
|
|
Release the memory of a previously allocated interval variable.
|
|
<synopsis>
|
|
void PGTYPESinterval_free(interval *intvl);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesintervalfromasc">
|
|
<term><function>PGTYPESinterval_from_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parse an interval from its textual representation.
|
|
<synopsis>
|
|
interval *PGTYPESinterval_from_asc(char *str, char **endptr);
|
|
</synopsis>
|
|
The function parses the input string <literal>str</literal> and returns a
|
|
pointer to an allocated interval variable.
|
|
At the moment ECPG always parses
|
|
the complete string and so it currently does not support to store the
|
|
address of the first invalid character in <literal>*endptr</literal>.
|
|
You can safely set <literal>endptr</literal> to NULL.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesintervaltoasc">
|
|
<term><function>PGTYPESinterval_to_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type interval to its textual representation.
|
|
<synopsis>
|
|
char *PGTYPESinterval_to_asc(interval *span);
|
|
</synopsis>
|
|
The function converts the interval variable that <literal>span</literal>
|
|
points to into a C char*. The output looks like this example:
|
|
<literal>@ 1 day 12 hours 59 mins 10 secs</literal>.
|
|
The result must be freed with <function>PGTYPESchar_free()</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="pgtypesintervalcopy">
|
|
<term><function>PGTYPESinterval_copy</function></term>
|
|
<listitem>
|
|
<para>
|
|
Copy a variable of type interval.
|
|
<synopsis>
|
|
int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
|
|
</synopsis>
|
|
The function copies the interval variable that <literal>intvlsrc</literal>
|
|
points to into the variable that <literal>intvldest</literal> points to. Note
|
|
that you need to allocate the memory for the destination variable
|
|
before.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-pgtypes-decimal">
|
|
<title>The decimal Type</title>
|
|
<para>
|
|
The decimal type is similar to the numeric type. However it is limited to
|
|
a maximum precision of 30 significant digits. In contrast to the numeric
|
|
type which can be created on the heap only, the decimal type can be
|
|
created either on the stack or on the heap (by means of the functions
|
|
<function>PGTYPESdecimal_new</function> and
|
|
<function>PGTYPESdecimal_free</function>).
|
|
There are a lot of other functions that deal with the decimal type in the
|
|
<productname>Informix</productname> compatibility mode described in <xref
|
|
linkend="ecpg-informix-compat"/>.
|
|
</para>
|
|
<para>
|
|
The following functions can be used to work with the decimal type and are
|
|
not only contained in the <literal>libcompat</literal> library.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PGTYPESdecimal_new</function></term>
|
|
<listitem>
|
|
<para>
|
|
Request a pointer to a newly allocated decimal variable.
|
|
<synopsis>
|
|
decimal *PGTYPESdecimal_new(void);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PGTYPESdecimal_free</function></term>
|
|
<listitem>
|
|
<para>
|
|
Free a decimal type, release all of its memory.
|
|
<synopsis>
|
|
void PGTYPESdecimal_free(decimal *var);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-pgtypes-errno">
|
|
<title>errno Values of pgtypeslib</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_NUM_BAD_NUMERIC</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An argument should contain a numeric variable (or point to a numeric
|
|
variable) but in fact its in-memory representation was invalid.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_NUM_OVERFLOW</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An overflow occurred. Since the numeric type can deal with almost
|
|
arbitrary precision, converting a numeric variable into other types
|
|
might cause overflow.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_NUM_UNDERFLOW</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An underflow occurred. Since the numeric type can deal with almost
|
|
arbitrary precision, converting a numeric variable into other types
|
|
might cause underflow.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_NUM_DIVIDE_ZERO</literal></term>
|
|
<listitem>
|
|
<para>
|
|
A division by zero has been attempted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_BAD_DATE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An invalid date string was passed to
|
|
the <function>PGTYPESdate_from_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_ERR_EARGS</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Invalid arguments were passed to the
|
|
<function>PGTYPESdate_defmt_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_ERR_ENOSHORTDATE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An invalid token in the input string was found by the
|
|
<function>PGTYPESdate_defmt_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_INTVL_BAD_INTERVAL</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An invalid interval string was passed to the
|
|
<function>PGTYPESinterval_from_asc</function> function, or an
|
|
invalid interval value was passed to the
|
|
<function>PGTYPESinterval_to_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_ERR_ENOTDMY</literal></term>
|
|
<listitem>
|
|
<para>
|
|
There was a mismatch in the day/month/year assignment in the
|
|
<function>PGTYPESdate_defmt_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_BAD_DAY</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An invalid day of the month value was found by
|
|
the <function>PGTYPESdate_defmt_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_BAD_MONTH</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An invalid month value was found by
|
|
the <function>PGTYPESdate_defmt_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_TS_BAD_TIMESTAMP</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An invalid timestamp string pass passed to
|
|
the <function>PGTYPEStimestamp_from_asc</function> function,
|
|
or an invalid timestamp value was passed to
|
|
the <function>PGTYPEStimestamp_to_asc</function> function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_TS_ERR_EINFTIME</literal></term>
|
|
<listitem>
|
|
<para>
|
|
An infinite timestamp value was encountered in a context that
|
|
cannot handle it.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-pgtypes-constants">
|
|
<title>Special Constants of pgtypeslib</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry id="pgtypesinvalidtimestamp">
|
|
<term><literal>PGTYPESInvalidTimestamp</literal></term>
|
|
<listitem>
|
|
<para>
|
|
A value of type timestamp representing an invalid time stamp. This is
|
|
returned by the function <function>PGTYPEStimestamp_from_asc</function> on
|
|
parse error.
|
|
Note that due to the internal representation of the <type>timestamp</type> data type,
|
|
<literal>PGTYPESInvalidTimestamp</literal> is also a valid timestamp at
|
|
the same time. It is set to <literal>1899-12-31 23:59:59</literal>. In order
|
|
to detect errors, make sure that your application does not only test
|
|
for <literal>PGTYPESInvalidTimestamp</literal> but also for
|
|
<literal>errno != 0</literal> after each call to
|
|
<function>PGTYPEStimestamp_from_asc</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-descriptors">
|
|
<title>Using Descriptor Areas</title>
|
|
|
|
<para>
|
|
An SQL descriptor area is a more sophisticated method for processing
|
|
the result of a <command>SELECT</command>, <command>FETCH</command> or
|
|
a <command>DESCRIBE</command> statement. An SQL descriptor area groups
|
|
the data of one row of data together with metadata items into one
|
|
data structure. The metadata is particularly useful when executing
|
|
dynamic SQL statements, where the nature of the result columns might
|
|
not be known ahead of time. PostgreSQL provides two ways to use
|
|
Descriptor Areas: the named SQL Descriptor Areas and the C-structure
|
|
SQLDAs.
|
|
</para>
|
|
|
|
<sect2 id="ecpg-named-descriptors">
|
|
<title>Named SQL Descriptor Areas</title>
|
|
|
|
<para>
|
|
A named SQL descriptor area consists of a header, which contains
|
|
information concerning the entire descriptor, and one or more item
|
|
descriptor areas, which basically each describe one column in the
|
|
result row.
|
|
</para>
|
|
|
|
<para>
|
|
Before you can use an SQL descriptor area, you need to allocate one:
|
|
<programlisting>
|
|
EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
|
|
</programlisting>
|
|
The identifier serves as the <quote>variable name</quote> of the
|
|
descriptor area. <!-- The scope of the allocated descriptor is WHAT?. -->
|
|
When you don't need the descriptor anymore, you should deallocate
|
|
it:
|
|
<programlisting>
|
|
EXEC SQL DEALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To use a descriptor area, specify it as the storage target in an
|
|
<literal>INTO</literal> clause, instead of listing host variables:
|
|
<programlisting>
|
|
EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc;
|
|
</programlisting>
|
|
If the result set is empty, the Descriptor Area will still contain
|
|
the metadata from the query, i.e., the field names.
|
|
</para>
|
|
|
|
<para>
|
|
For not yet executed prepared queries, the <command>DESCRIBE</command>
|
|
statement can be used to get the metadata of the result set:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char *sql_stmt = "SELECT * FROM table1";
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL PREPARE stmt1 FROM :sql_stmt;
|
|
EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Before PostgreSQL 9.0, the <literal>SQL</literal> keyword was optional,
|
|
so using <literal>DESCRIPTOR</literal> and <literal>SQL DESCRIPTOR</literal>
|
|
produced named SQL Descriptor Areas. Now it is mandatory, omitting
|
|
the <literal>SQL</literal> keyword produces SQLDA Descriptor Areas,
|
|
see <xref linkend="ecpg-sqlda-descriptors"/>.
|
|
</para>
|
|
|
|
<para>
|
|
In <command>DESCRIBE</command> and <command>FETCH</command> statements,
|
|
the <literal>INTO</literal> and <literal>USING</literal> keywords can be
|
|
used to similarly: they produce the result set and the metadata in a
|
|
Descriptor Area.
|
|
</para>
|
|
|
|
<para>
|
|
Now how do you get the data out of the descriptor area? You can
|
|
think of the descriptor area as a structure with named fields. To
|
|
retrieve the value of a field from the header and store it into a
|
|
host variable, use the following command:
|
|
<programlisting>
|
|
EXEC SQL GET DESCRIPTOR <replaceable>name</replaceable> :<replaceable>hostvar</replaceable> = <replaceable>field</replaceable>;
|
|
</programlisting>
|
|
Currently, there is only one header field defined:
|
|
<replaceable>COUNT</replaceable>, which tells how many item
|
|
descriptor areas exist (that is, how many columns are contained in
|
|
the result). The host variable needs to be of an integer type. To
|
|
get a field from the item descriptor area, use the following
|
|
command:
|
|
<programlisting>
|
|
EXEC SQL GET DESCRIPTOR <replaceable>name</replaceable> VALUE <replaceable>num</replaceable> :<replaceable>hostvar</replaceable> = <replaceable>field</replaceable>;
|
|
</programlisting>
|
|
<replaceable>num</replaceable> can be a literal integer or a host
|
|
variable containing an integer. Possible fields are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>CARDINALITY</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
number of rows in the result set
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DATA</literal></term>
|
|
<listitem>
|
|
<para>
|
|
actual data item (therefore, the data type of this field
|
|
depends on the query)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DATETIME_INTERVAL_CODE</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
When <literal>TYPE</literal> is <literal>9</literal>,
|
|
<literal>DATETIME_INTERVAL_CODE</literal> will have a value of
|
|
<literal>1</literal> for <literal>DATE</literal>,
|
|
<literal>2</literal> for <literal>TIME</literal>,
|
|
<literal>3</literal> for <literal>TIMESTAMP</literal>,
|
|
<literal>4</literal> for <literal>TIME WITH TIME ZONE</literal>, or
|
|
<literal>5</literal> for <literal>TIMESTAMP WITH TIME ZONE</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DATETIME_INTERVAL_PRECISION</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
not implemented
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>INDICATOR</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
the indicator (indicating a null value or a value truncation)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>KEY_MEMBER</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
not implemented
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>LENGTH</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
length of the datum in characters
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>NAME</literal> (string)</term>
|
|
<listitem>
|
|
<para>
|
|
name of the column
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>NULLABLE</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
not implemented
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>OCTET_LENGTH</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
length of the character representation of the datum in bytes
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PRECISION</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
precision (for type <type>numeric</type>)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>RETURNED_LENGTH</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
length of the datum in characters
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>RETURNED_OCTET_LENGTH</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
length of the character representation of the datum in bytes
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>SCALE</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
scale (for type <type>numeric</type>)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>TYPE</literal> (integer)</term>
|
|
<listitem>
|
|
<para>
|
|
numeric code of the data type of the column
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
In <command>EXECUTE</command>, <command>DECLARE</command> and <command>OPEN</command>
|
|
statements, the effect of the <literal>INTO</literal> and <literal>USING</literal>
|
|
keywords are different. A Descriptor Area can also be manually built to
|
|
provide the input parameters for a query or a cursor and
|
|
<literal>USING SQL DESCRIPTOR <replaceable>name</replaceable></literal>
|
|
is the way to pass the input parameters into a parameterized query. The statement
|
|
to build a named SQL Descriptor Area is below:
|
|
<programlisting>
|
|
EXEC SQL SET DESCRIPTOR <replaceable>name</replaceable> VALUE <replaceable>num</replaceable> <replaceable>field</replaceable> = :<replaceable>hostvar</replaceable>;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
PostgreSQL supports retrieving more that one record in one <command>FETCH</command>
|
|
statement and storing the data in host variables in this case assumes that the
|
|
variable is an array. E.g.:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int id[5];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc;
|
|
|
|
EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :id = DATA;
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-sqlda-descriptors">
|
|
<title>SQLDA Descriptor Areas</title>
|
|
|
|
<para>
|
|
An SQLDA Descriptor Area is a C language structure which can be also used
|
|
to get the result set and the metadata of a query. One structure stores one
|
|
record from the result set.
|
|
<programlisting>
|
|
EXEC SQL include sqlda.h;
|
|
sqlda_t *mysqlda;
|
|
|
|
EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda;
|
|
</programlisting>
|
|
Note that the <literal>SQL</literal> keyword is omitted. The paragraphs about
|
|
the use cases of the <literal>INTO</literal> and <literal>USING</literal>
|
|
keywords in <xref linkend="ecpg-named-descriptors"/> also apply here with an addition.
|
|
In a <command>DESCRIBE</command> statement the <literal>DESCRIPTOR</literal>
|
|
keyword can be completely omitted if the <literal>INTO</literal> keyword is used:
|
|
<programlisting>
|
|
EXEC SQL DESCRIBE prepared_statement INTO mysqlda;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<procedure>
|
|
<para>
|
|
The general flow of a program that uses SQLDA is:
|
|
</para>
|
|
<step><simpara>Prepare a query, and declare a cursor for it.</simpara></step>
|
|
<step><simpara>Declare an SQLDA for the result rows.</simpara></step>
|
|
<step><simpara>Declare an SQLDA for the input parameters, and initialize them (memory allocation, parameter settings).</simpara></step>
|
|
<step><simpara>Open a cursor with the input SQLDA.</simpara></step>
|
|
<step><simpara>Fetch rows from the cursor, and store them into an output SQLDA.</simpara></step>
|
|
<step><simpara>Read values from the output SQLDA into the host variables (with conversion if necessary).</simpara></step>
|
|
<step><simpara>Close the cursor.</simpara></step>
|
|
<step><simpara>Free the memory area allocated for the input SQLDA.</simpara></step>
|
|
</procedure>
|
|
|
|
<sect3>
|
|
<title>SQLDA Data Structure</title>
|
|
|
|
<para>
|
|
SQLDA uses three data structure
|
|
types: <type>sqlda_t</type>, <type>sqlvar_t</type>,
|
|
and <type>struct sqlname</type>.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
PostgreSQL's SQLDA has a similar data structure to the one in
|
|
IBM DB2 Universal Database, so some technical information on
|
|
DB2's SQLDA could help understanding PostgreSQL's one better.
|
|
</para>
|
|
</tip>
|
|
|
|
<sect4 id="ecpg-sqlda-sqlda">
|
|
<title>sqlda_t Structure</title>
|
|
|
|
<para>
|
|
The structure type <type>sqlda_t</type> is the type of the
|
|
actual SQLDA. It holds one record. And two or
|
|
more <type>sqlda_t</type> structures can be connected in a
|
|
linked list with the pointer in
|
|
the <structfield>desc_next</structfield> field, thus
|
|
representing an ordered collection of rows. So, when two or
|
|
more rows are fetched, the application can read them by
|
|
following the <structfield>desc_next</structfield> pointer in
|
|
each <type>sqlda_t</type> node.
|
|
</para>
|
|
|
|
<para>
|
|
The definition of <type>sqlda_t</type> is:
|
|
<programlisting>
|
|
struct sqlda_struct
|
|
{
|
|
char sqldaid[8];
|
|
long sqldabc;
|
|
short sqln;
|
|
short sqld;
|
|
struct sqlda_struct *desc_next;
|
|
struct sqlvar_struct sqlvar[1];
|
|
};
|
|
|
|
typedef struct sqlda_struct sqlda_t;
|
|
</programlisting>
|
|
|
|
The meaning of the fields is:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>sqldaid</literal></term>
|
|
<listitem>
|
|
<para>
|
|
It contains the literal string <literal>"SQLDA "</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqldabc</literal></term>
|
|
<listitem>
|
|
<para>
|
|
It contains the size of the allocated space in bytes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqln</literal></term>
|
|
<listitem>
|
|
<para>
|
|
It contains the number of input parameters for a parameterized query in
|
|
case it's passed into <command>OPEN</command>, <command>DECLARE</command> or
|
|
<command>EXECUTE</command> statements using the <literal>USING</literal>
|
|
keyword. In case it's used as output of <command>SELECT</command>,
|
|
<command>EXECUTE</command> or <command>FETCH</command> statements,
|
|
its value is the same as <literal>sqld</literal>
|
|
statement
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqld</literal></term>
|
|
<listitem>
|
|
<para>
|
|
It contains the number of fields in a result set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>desc_next</literal></term>
|
|
<listitem>
|
|
<para>
|
|
If the query returns more than one record, multiple linked
|
|
SQLDA structures are returned, and <literal>desc_next</literal> holds
|
|
a pointer to the next entry in the list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>sqlvar</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This is the array of the columns in the result set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4 id="ecpg-sqlda-sqlvar">
|
|
<title>sqlvar_t Structure</title>
|
|
|
|
<para>
|
|
The structure type <type>sqlvar_t</type> holds a column value
|
|
and metadata such as type and length. The definition of the type
|
|
is:
|
|
|
|
<programlisting>
|
|
struct sqlvar_struct
|
|
{
|
|
short sqltype;
|
|
short sqllen;
|
|
char *sqldata;
|
|
short *sqlind;
|
|
struct sqlname sqlname;
|
|
};
|
|
|
|
typedef struct sqlvar_struct sqlvar_t;
|
|
</programlisting>
|
|
|
|
The meaning of the fields is:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>sqltype</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Contains the type identifier of the field. For values,
|
|
see <literal>enum ECPGttype</literal> in <literal>ecpgtype.h</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqllen</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Contains the binary length of the field. e.g., 4 bytes for <type>ECPGt_int</type>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqldata</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Points to the data. The format of the data is described
|
|
in <xref linkend="ecpg-variables-type-mapping"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlind</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Points to the null indicator. 0 means not null, -1 means
|
|
null.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlname</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the field.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4 id="ecpg-sqlda-sqlname">
|
|
<title>struct sqlname Structure</title>
|
|
|
|
<para>
|
|
A <type>struct sqlname</type> structure holds a column name. It
|
|
is used as a member of the <type>sqlvar_t</type> structure. The
|
|
definition of the structure is:
|
|
<programlisting>
|
|
#define NAMEDATALEN 64
|
|
|
|
struct sqlname
|
|
{
|
|
short length;
|
|
char data[NAMEDATALEN];
|
|
};
|
|
</programlisting>
|
|
The meaning of the fields is:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>length</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Contains the length of the field name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>data</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Contains the actual field name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect4>
|
|
</sect3>
|
|
|
|
<sect3 id="ecpg-sqlda-output">
|
|
<title>Retrieving a Result Set Using an SQLDA</title>
|
|
|
|
<procedure>
|
|
<para>
|
|
The general steps to retrieve a query result set through an
|
|
SQLDA are:
|
|
</para>
|
|
<step><simpara>Declare an <type>sqlda_t</type> structure to receive the result set.</simpara></step>
|
|
<step><simpara>Execute <command>FETCH</command>/<command>EXECUTE</command>/<command>DESCRIBE</command> commands to process a query specifying the declared SQLDA.</simpara></step>
|
|
<step><simpara>Check the number of records in the result set by looking at <structfield>sqln</structfield>, a member of the <type>sqlda_t</type> structure.</simpara></step>
|
|
<step><simpara>Get the values of each column from <literal>sqlvar[0]</literal>, <literal>sqlvar[1]</literal>, etc., members of the <type>sqlda_t</type> structure.</simpara></step>
|
|
<step><simpara>Go to next row (<type>sqlda_t</type> structure) by following the <structfield>desc_next</structfield> pointer, a member of the <type>sqlda_t</type> structure.</simpara></step>
|
|
<step><simpara>Repeat above as you need.</simpara></step>
|
|
</procedure>
|
|
|
|
<para>
|
|
Here is an example retrieving a result set through an SQLDA.
|
|
</para>
|
|
|
|
<para>
|
|
First, declare a <type>sqlda_t</type> structure to receive the result set.
|
|
<programlisting>
|
|
sqlda_t *sqlda1;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Next, specify the SQLDA in a command. This is
|
|
a <command>FETCH</command> command example.
|
|
<programlisting>
|
|
EXEC SQL FETCH NEXT FROM cur1 INTO DESCRIPTOR sqlda1;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Run a loop following the linked list to retrieve the rows.
|
|
<programlisting>
|
|
sqlda_t *cur_sqlda;
|
|
|
|
for (cur_sqlda = sqlda1;
|
|
cur_sqlda != NULL;
|
|
cur_sqlda = cur_sqlda->desc_next)
|
|
{
|
|
...
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Inside the loop, run another loop to retrieve each column data
|
|
(<type>sqlvar_t</type> structure) of the row.
|
|
<programlisting>
|
|
for (i = 0; i < cur_sqlda->sqld; i++)
|
|
{
|
|
sqlvar_t v = cur_sqlda->sqlvar[i];
|
|
char *sqldata = v.sqldata;
|
|
short sqllen = v.sqllen;
|
|
...
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To get a column value, check the <structfield>sqltype</structfield> value,
|
|
a member of the <type>sqlvar_t</type> structure. Then, switch
|
|
to an appropriate way, depending on the column type, to copy
|
|
data from the <structfield>sqlvar</structfield> field to a host variable.
|
|
<programlisting>
|
|
char var_buf[1024];
|
|
|
|
switch (v.sqltype)
|
|
{
|
|
case ECPGt_char:
|
|
memset(&var_buf, 0, sizeof(var_buf));
|
|
memcpy(&var_buf, sqldata, (sizeof(var_buf) <= sqllen ? sizeof(var_buf) - 1 : sqllen));
|
|
break;
|
|
|
|
case ECPGt_int: /* integer */
|
|
memcpy(&intval, sqldata, sqllen);
|
|
snprintf(var_buf, sizeof(var_buf), "%d", intval);
|
|
break;
|
|
|
|
...
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="ecpg-sqlda-input">
|
|
<title>Passing Query Parameters Using an SQLDA</title>
|
|
|
|
<procedure>
|
|
<para>
|
|
The general steps to use an SQLDA to pass input
|
|
parameters to a prepared query are:
|
|
</para>
|
|
<step><simpara>Create a prepared query (prepared statement)</simpara></step>
|
|
<step><simpara>Declare a sqlda_t structure as an input SQLDA.</simpara></step>
|
|
<step><simpara>Allocate memory area (as sqlda_t structure) for the input SQLDA.</simpara></step>
|
|
<step><simpara>Set (copy) input values in the allocated memory.</simpara></step>
|
|
<step><simpara>Open a cursor with specifying the input SQLDA.</simpara></step>
|
|
</procedure>
|
|
|
|
<para>
|
|
Here is an example.
|
|
</para>
|
|
|
|
<para>
|
|
First, create a prepared statement.
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char query[1024] = "SELECT d.oid, * FROM pg_database d, pg_stat_database s WHERE d.oid = s.datid AND (d.datname = ? OR d.oid = ?)";
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL PREPARE stmt1 FROM :query;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Next, allocate memory for an SQLDA, and set the number of input
|
|
parameters in <structfield>sqln</structfield>, a member variable of
|
|
the <type>sqlda_t</type> structure. When two or more input
|
|
parameters are required for the prepared query, the application
|
|
has to allocate additional memory space which is calculated by
|
|
(nr. of params - 1) * sizeof(sqlvar_t). The example shown here
|
|
allocates memory space for two input parameters.
|
|
<programlisting>
|
|
sqlda_t *sqlda2;
|
|
|
|
sqlda2 = (sqlda_t *) malloc(sizeof(sqlda_t) + sizeof(sqlvar_t));
|
|
memset(sqlda2, 0, sizeof(sqlda_t) + sizeof(sqlvar_t));
|
|
|
|
sqlda2->sqln = 2; /* number of input variables */
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
After memory allocation, store the parameter values into the
|
|
<literal>sqlvar[]</literal> array. (This is same array used for
|
|
retrieving column values when the SQLDA is receiving a result
|
|
set.) In this example, the input parameters
|
|
are <literal>"postgres"</literal>, having a string type,
|
|
and <literal>1</literal>, having an integer type.
|
|
<programlisting>
|
|
sqlda2->sqlvar[0].sqltype = ECPGt_char;
|
|
sqlda2->sqlvar[0].sqldata = "postgres";
|
|
sqlda2->sqlvar[0].sqllen = 8;
|
|
|
|
int intval = 1;
|
|
sqlda2->sqlvar[1].sqltype = ECPGt_int;
|
|
sqlda2->sqlvar[1].sqldata = (char *) &intval;
|
|
sqlda2->sqlvar[1].sqllen = sizeof(intval);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
By opening a cursor and specifying the SQLDA that was set up
|
|
beforehand, the input parameters are passed to the prepared
|
|
statement.
|
|
<programlisting>
|
|
EXEC SQL OPEN cur1 USING DESCRIPTOR sqlda2;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Finally, after using input SQLDAs, the allocated memory space
|
|
must be freed explicitly, unlike SQLDAs used for receiving query
|
|
results.
|
|
<programlisting>
|
|
free(sqlda2);
|
|
</programlisting>
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="ecpg-sqlda-example">
|
|
<title>A Sample Application Using SQLDA</title>
|
|
|
|
<para>
|
|
Here is an example program, which describes how to fetch access
|
|
statistics of the databases, specified by the input parameters,
|
|
from the system catalogs.
|
|
</para>
|
|
|
|
<para>
|
|
This application joins two system tables, pg_database and
|
|
pg_stat_database on the database OID, and also fetches and shows
|
|
the database statistics which are retrieved by two input
|
|
parameters (a database <literal>postgres</literal>, and OID <literal>1</literal>).
|
|
</para>
|
|
|
|
<para>
|
|
First, declare an SQLDA for input and an SQLDA for output.
|
|
<programlisting>
|
|
EXEC SQL include sqlda.h;
|
|
|
|
sqlda_t *sqlda1; /* an output descriptor */
|
|
sqlda_t *sqlda2; /* an input descriptor */
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Next, connect to the database, prepare a statement, and declare a
|
|
cursor for the prepared statement.
|
|
<programlisting>
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char query[1024] = "SELECT d.oid,* FROM pg_database d, pg_stat_database s WHERE d.oid=s.datid AND ( d.datname=? OR d.oid=? )";
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL CONNECT TO testdb AS con1 USER testuser;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
EXEC SQL PREPARE stmt1 FROM :query;
|
|
EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Next, put some values in the input SQLDA for the input
|
|
parameters. Allocate memory for the input SQLDA, and set the
|
|
number of input parameters to <literal>sqln</literal>. Store
|
|
type, value, and value length into <literal>sqltype</literal>,
|
|
<literal>sqldata</literal>, and <literal>sqllen</literal> in the
|
|
<literal>sqlvar</literal> structure.
|
|
|
|
<programlisting>
|
|
/* Create SQLDA structure for input parameters. */
|
|
sqlda2 = (sqlda_t *) malloc(sizeof(sqlda_t) + sizeof(sqlvar_t));
|
|
memset(sqlda2, 0, sizeof(sqlda_t) + sizeof(sqlvar_t));
|
|
sqlda2->sqln = 2; /* number of input variables */
|
|
|
|
sqlda2->sqlvar[0].sqltype = ECPGt_char;
|
|
sqlda2->sqlvar[0].sqldata = "postgres";
|
|
sqlda2->sqlvar[0].sqllen = 8;
|
|
|
|
intval = 1;
|
|
sqlda2->sqlvar[1].sqltype = ECPGt_int;
|
|
sqlda2->sqlvar[1].sqldata = (char *)&intval;
|
|
sqlda2->sqlvar[1].sqllen = sizeof(intval);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
After setting up the input SQLDA, open a cursor with the input
|
|
SQLDA.
|
|
|
|
<programlisting>
|
|
/* Open a cursor with input parameters. */
|
|
EXEC SQL OPEN cur1 USING DESCRIPTOR sqlda2;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Fetch rows into the output SQLDA from the opened cursor.
|
|
(Generally, you have to call <command>FETCH</command> repeatedly
|
|
in the loop, to fetch all rows in the result set.)
|
|
<programlisting>
|
|
while (1)
|
|
{
|
|
sqlda_t *cur_sqlda;
|
|
|
|
/* Assign descriptor to the cursor */
|
|
EXEC SQL FETCH NEXT FROM cur1 INTO DESCRIPTOR sqlda1;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Next, retrieve the fetched records from the SQLDA, by following
|
|
the linked list of the <type>sqlda_t</type> structure.
|
|
<programlisting>
|
|
for (cur_sqlda = sqlda1 ;
|
|
cur_sqlda != NULL ;
|
|
cur_sqlda = cur_sqlda->desc_next)
|
|
{
|
|
...
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Read each columns in the first record. The number of columns is
|
|
stored in <structfield>sqld</structfield>, the actual data of the first
|
|
column is stored in <literal>sqlvar[0]</literal>, both members of
|
|
the <type>sqlda_t</type> structure.
|
|
|
|
<programlisting>
|
|
/* Print every column in a row. */
|
|
for (i = 0; i < sqlda1->sqld; i++)
|
|
{
|
|
sqlvar_t v = sqlda1->sqlvar[i];
|
|
char *sqldata = v.sqldata;
|
|
short sqllen = v.sqllen;
|
|
|
|
strncpy(name_buf, v.sqlname.data, v.sqlname.length);
|
|
name_buf[v.sqlname.length] = '\0';
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Now, the column data is stored in the variable <varname>v</varname>.
|
|
Copy every datum into host variables, looking
|
|
at <literal>v.sqltype</literal> for the type of the column.
|
|
<programlisting>
|
|
switch (v.sqltype) {
|
|
int intval;
|
|
double doubleval;
|
|
unsigned long long int longlongval;
|
|
|
|
case ECPGt_char:
|
|
memset(&var_buf, 0, sizeof(var_buf));
|
|
memcpy(&var_buf, sqldata, (sizeof(var_buf) <= sqllen ? sizeof(var_buf)-1 : sqllen));
|
|
break;
|
|
|
|
case ECPGt_int: /* integer */
|
|
memcpy(&intval, sqldata, sqllen);
|
|
snprintf(var_buf, sizeof(var_buf), "%d", intval);
|
|
break;
|
|
|
|
...
|
|
|
|
default:
|
|
...
|
|
}
|
|
|
|
printf("%s = %s (type: %d)\n", name_buf, var_buf, v.sqltype);
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Close the cursor after processing all of records, and disconnect
|
|
from the database.
|
|
<programlisting>
|
|
EXEC SQL CLOSE cur1;
|
|
EXEC SQL COMMIT;
|
|
|
|
EXEC SQL DISCONNECT ALL;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The whole program is shown
|
|
in <xref linkend="ecpg-sqlda-example-example"/>.
|
|
</para>
|
|
|
|
<example id="ecpg-sqlda-example-example">
|
|
<title>Example SQLDA Program</title>
|
|
<programlisting>
|
|
#include <stdlib.h>
|
|
#include <string.h>
|
|
#include <stdlib.h>
|
|
#include <stdio.h>
|
|
#include <unistd.h>
|
|
|
|
EXEC SQL include sqlda.h;
|
|
|
|
sqlda_t *sqlda1; /* descriptor for output */
|
|
sqlda_t *sqlda2; /* descriptor for input */
|
|
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
EXEC SQL WHENEVER SQLERROR STOP;
|
|
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char query[1024] = "SELECT d.oid,* FROM pg_database d, pg_stat_database s WHERE d.oid=s.datid AND ( d.datname=? OR d.oid=? )";
|
|
|
|
int intval;
|
|
unsigned long long int longlongval;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL CONNECT TO uptimedb AS con1 USER uptime;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
EXEC SQL PREPARE stmt1 FROM :query;
|
|
EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
|
|
|
|
/* Create a SQLDA structure for an input parameter */
|
|
sqlda2 = (sqlda_t *)malloc(sizeof(sqlda_t) + sizeof(sqlvar_t));
|
|
memset(sqlda2, 0, sizeof(sqlda_t) + sizeof(sqlvar_t));
|
|
sqlda2->sqln = 2; /* a number of input variables */
|
|
|
|
sqlda2->sqlvar[0].sqltype = ECPGt_char;
|
|
sqlda2->sqlvar[0].sqldata = "postgres";
|
|
sqlda2->sqlvar[0].sqllen = 8;
|
|
|
|
intval = 1;
|
|
sqlda2->sqlvar[1].sqltype = ECPGt_int;
|
|
sqlda2->sqlvar[1].sqldata = (char *) &intval;
|
|
sqlda2->sqlvar[1].sqllen = sizeof(intval);
|
|
|
|
/* Open a cursor with input parameters. */
|
|
EXEC SQL OPEN cur1 USING DESCRIPTOR sqlda2;
|
|
|
|
while (1)
|
|
{
|
|
sqlda_t *cur_sqlda;
|
|
|
|
/* Assign descriptor to the cursor */
|
|
EXEC SQL FETCH NEXT FROM cur1 INTO DESCRIPTOR sqlda1;
|
|
|
|
for (cur_sqlda = sqlda1 ;
|
|
cur_sqlda != NULL ;
|
|
cur_sqlda = cur_sqlda->desc_next)
|
|
{
|
|
int i;
|
|
char name_buf[1024];
|
|
char var_buf[1024];
|
|
|
|
/* Print every column in a row. */
|
|
for (i=0 ; i<cur_sqlda->sqld ; i++)
|
|
{
|
|
sqlvar_t v = cur_sqlda->sqlvar[i];
|
|
char *sqldata = v.sqldata;
|
|
short sqllen = v.sqllen;
|
|
|
|
strncpy(name_buf, v.sqlname.data, v.sqlname.length);
|
|
name_buf[v.sqlname.length] = '\0';
|
|
|
|
switch (v.sqltype)
|
|
{
|
|
case ECPGt_char:
|
|
memset(&var_buf, 0, sizeof(var_buf));
|
|
memcpy(&var_buf, sqldata, (sizeof(var_buf)<=sqllen ? sizeof(var_buf)-1 : sqllen) );
|
|
break;
|
|
|
|
case ECPGt_int: /* integer */
|
|
memcpy(&intval, sqldata, sqllen);
|
|
snprintf(var_buf, sizeof(var_buf), "%d", intval);
|
|
break;
|
|
|
|
case ECPGt_long_long: /* bigint */
|
|
memcpy(&longlongval, sqldata, sqllen);
|
|
snprintf(var_buf, sizeof(var_buf), "%lld", longlongval);
|
|
break;
|
|
|
|
default:
|
|
{
|
|
int i;
|
|
memset(var_buf, 0, sizeof(var_buf));
|
|
for (i = 0; i < sqllen; i++)
|
|
{
|
|
char tmpbuf[16];
|
|
snprintf(tmpbuf, sizeof(tmpbuf), "%02x ", (unsigned char) sqldata[i]);
|
|
strncat(var_buf, tmpbuf, sizeof(var_buf));
|
|
}
|
|
}
|
|
break;
|
|
}
|
|
|
|
printf("%s = %s (type: %d)\n", name_buf, var_buf, v.sqltype);
|
|
}
|
|
|
|
printf("\n");
|
|
}
|
|
}
|
|
|
|
EXEC SQL CLOSE cur1;
|
|
EXEC SQL COMMIT;
|
|
|
|
EXEC SQL DISCONNECT ALL;
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
|
|
<para>
|
|
The output of this example should look something like the
|
|
following (some numbers will vary).
|
|
</para>
|
|
|
|
<screen>
|
|
oid = 1 (type: 1)
|
|
datname = template1 (type: 1)
|
|
datdba = 10 (type: 1)
|
|
encoding = 0 (type: 5)
|
|
datistemplate = t (type: 1)
|
|
datallowconn = t (type: 1)
|
|
datconnlimit = -1 (type: 5)
|
|
datlastsysoid = 11510 (type: 1)
|
|
datfrozenxid = 379 (type: 1)
|
|
dattablespace = 1663 (type: 1)
|
|
datconfig = (type: 1)
|
|
datacl = {=c/uptime,uptime=CTc/uptime} (type: 1)
|
|
datid = 1 (type: 1)
|
|
datname = template1 (type: 1)
|
|
numbackends = 0 (type: 5)
|
|
xact_commit = 113606 (type: 9)
|
|
xact_rollback = 0 (type: 9)
|
|
blks_read = 130 (type: 9)
|
|
blks_hit = 7341714 (type: 9)
|
|
tup_returned = 38262679 (type: 9)
|
|
tup_fetched = 1836281 (type: 9)
|
|
tup_inserted = 0 (type: 9)
|
|
tup_updated = 0 (type: 9)
|
|
tup_deleted = 0 (type: 9)
|
|
|
|
oid = 11511 (type: 1)
|
|
datname = postgres (type: 1)
|
|
datdba = 10 (type: 1)
|
|
encoding = 0 (type: 5)
|
|
datistemplate = f (type: 1)
|
|
datallowconn = t (type: 1)
|
|
datconnlimit = -1 (type: 5)
|
|
datlastsysoid = 11510 (type: 1)
|
|
datfrozenxid = 379 (type: 1)
|
|
dattablespace = 1663 (type: 1)
|
|
datconfig = (type: 1)
|
|
datacl = (type: 1)
|
|
datid = 11511 (type: 1)
|
|
datname = postgres (type: 1)
|
|
numbackends = 0 (type: 5)
|
|
xact_commit = 221069 (type: 9)
|
|
xact_rollback = 18 (type: 9)
|
|
blks_read = 1176 (type: 9)
|
|
blks_hit = 13943750 (type: 9)
|
|
tup_returned = 77410091 (type: 9)
|
|
tup_fetched = 3253694 (type: 9)
|
|
tup_inserted = 0 (type: 9)
|
|
tup_updated = 0 (type: 9)
|
|
tup_deleted = 0 (type: 9)
|
|
</screen>
|
|
</example>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-errors">
|
|
<title>Error Handling</title>
|
|
|
|
<para>
|
|
This section describes how you can handle exceptional conditions
|
|
and warnings in an embedded SQL program. There are two
|
|
nonexclusive facilities for this.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Callbacks can be configured to handle warning and error
|
|
conditions using the <literal>WHENEVER</literal> command.
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
Detailed information about the error or warning can be obtained
|
|
from the <varname>sqlca</varname> variable.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<sect2 id="ecpg-whenever">
|
|
<title>Setting Callbacks</title>
|
|
|
|
<para>
|
|
One simple method to catch errors and warnings is to set a
|
|
specific action to be executed whenever a particular condition
|
|
occurs. In general:
|
|
<programlisting>
|
|
EXEC SQL WHENEVER <replaceable>condition</replaceable> <replaceable>action</replaceable>;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
<replaceable>condition</replaceable> can be one of the following:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>SQLERROR</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The specified action is called whenever an error occurs during
|
|
the execution of an SQL statement.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>SQLWARNING</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The specified action is called whenever a warning occurs
|
|
during the execution of an SQL statement.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>NOT FOUND</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The specified action is called whenever an SQL statement
|
|
retrieves or affects zero rows. (This condition is not an
|
|
error, but you might be interested in handling it specially.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
<replaceable>action</replaceable> can be one of the following:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>CONTINUE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This effectively means that the condition is ignored. This is
|
|
the default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>GOTO <replaceable>label</replaceable></literal></term>
|
|
<term><literal>GO TO <replaceable>label</replaceable></literal></term>
|
|
<listitem>
|
|
<para>
|
|
Jump to the specified label (using a C <literal>goto</literal>
|
|
statement).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>SQLPRINT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Print a message to standard error. This is useful for simple
|
|
programs or during prototyping. The details of the message
|
|
cannot be configured.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>STOP</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Call <literal>exit(1)</literal>, which will terminate the
|
|
program.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DO BREAK</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Execute the C statement <literal>break</literal>. This should
|
|
only be used in loops or <literal>switch</literal> statements.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DO CONTINUE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Execute the C statement <literal>continue</literal>. This should
|
|
only be used in loops statements. if executed, will cause the flow
|
|
of control to return to the top of the loop.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>CALL <replaceable>name</replaceable> (<replaceable>args</replaceable>)</literal></term>
|
|
<term><literal>DO <replaceable>name</replaceable> (<replaceable>args</replaceable>)</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Call the specified C functions with the specified arguments. (This
|
|
use is different from the meaning of <literal>CALL</literal>
|
|
and <literal>DO</literal> in the normal PostgreSQL grammar.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
The SQL standard only provides for the actions
|
|
<literal>CONTINUE</literal> and <literal>GOTO</literal> (and
|
|
<literal>GO TO</literal>).
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example that you might want to use in a simple program.
|
|
It prints a simple message when a warning occurs and aborts the
|
|
program when an error happens:
|
|
<programlisting>
|
|
EXEC SQL WHENEVER SQLWARNING SQLPRINT;
|
|
EXEC SQL WHENEVER SQLERROR STOP;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The statement <literal>EXEC SQL WHENEVER</literal> is a directive
|
|
of the SQL preprocessor, not a C statement. The error or warning
|
|
actions that it sets apply to all embedded SQL statements that
|
|
appear below the point where the handler is set, unless a
|
|
different action was set for the same condition between the first
|
|
<literal>EXEC SQL WHENEVER</literal> and the SQL statement causing
|
|
the condition, regardless of the flow of control in the C program.
|
|
So neither of the two following C program excerpts will have the
|
|
desired effect:
|
|
<programlisting>
|
|
/*
|
|
* WRONG
|
|
*/
|
|
int main(int argc, char *argv[])
|
|
{
|
|
...
|
|
if (verbose) {
|
|
EXEC SQL WHENEVER SQLWARNING SQLPRINT;
|
|
}
|
|
...
|
|
EXEC SQL SELECT ...;
|
|
...
|
|
}
|
|
</programlisting>
|
|
|
|
<programlisting>
|
|
/*
|
|
* WRONG
|
|
*/
|
|
int main(int argc, char *argv[])
|
|
{
|
|
...
|
|
set_error_handler();
|
|
...
|
|
EXEC SQL SELECT ...;
|
|
...
|
|
}
|
|
|
|
static void set_error_handler(void)
|
|
{
|
|
EXEC SQL WHENEVER SQLERROR STOP;
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-sqlca">
|
|
<title>sqlca</title>
|
|
|
|
<para>
|
|
For more powerful error handling, the embedded SQL interface
|
|
provides a global variable with the name <varname>sqlca</varname>
|
|
(SQL communication area)
|
|
that has the following structure:
|
|
<programlisting>
|
|
struct
|
|
{
|
|
char sqlcaid[8];
|
|
long sqlabc;
|
|
long sqlcode;
|
|
struct
|
|
{
|
|
int sqlerrml;
|
|
char sqlerrmc[SQLERRMC_LEN];
|
|
} sqlerrm;
|
|
char sqlerrp[8];
|
|
long sqlerrd[6];
|
|
char sqlwarn[8];
|
|
char sqlstate[5];
|
|
} sqlca;
|
|
</programlisting>
|
|
(In a multithreaded program, every thread automatically gets its
|
|
own copy of <varname>sqlca</varname>. This works similarly to the
|
|
handling of the standard C global variable
|
|
<varname>errno</varname>.)
|
|
</para>
|
|
|
|
<para>
|
|
<varname>sqlca</varname> covers both warnings and errors. If
|
|
multiple warnings or errors occur during the execution of a
|
|
statement, then <varname>sqlca</varname> will only contain
|
|
information about the last one.
|
|
</para>
|
|
|
|
<para>
|
|
If no error occurred in the last <acronym>SQL</acronym> statement,
|
|
<literal>sqlca.sqlcode</literal> will be 0 and
|
|
<literal>sqlca.sqlstate</literal> will be
|
|
<literal>"00000"</literal>. If a warning or error occurred, then
|
|
<literal>sqlca.sqlcode</literal> will be negative and
|
|
<literal>sqlca.sqlstate</literal> will be different from
|
|
<literal>"00000"</literal>. A positive
|
|
<literal>sqlca.sqlcode</literal> indicates a harmless condition,
|
|
such as that the last query returned zero rows.
|
|
<literal>sqlcode</literal> and <literal>sqlstate</literal> are two
|
|
different error code schemes; details appear below.
|
|
</para>
|
|
|
|
<para>
|
|
If the last SQL statement was successful, then
|
|
<literal>sqlca.sqlerrd[1]</literal> contains the OID of the
|
|
processed row, if applicable, and
|
|
<literal>sqlca.sqlerrd[2]</literal> contains the number of
|
|
processed or returned rows, if applicable to the command.
|
|
</para>
|
|
|
|
<para>
|
|
In case of an error or warning,
|
|
<literal>sqlca.sqlerrm.sqlerrmc</literal> will contain a string
|
|
that describes the error. The field
|
|
<literal>sqlca.sqlerrm.sqlerrml</literal> contains the length of
|
|
the error message that is stored in
|
|
<literal>sqlca.sqlerrm.sqlerrmc</literal> (the result of
|
|
<function>strlen()</function>, not really interesting for a C
|
|
programmer). Note that some messages are too long to fit in the
|
|
fixed-size <literal>sqlerrmc</literal> array; they will be truncated.
|
|
</para>
|
|
|
|
<para>
|
|
In case of a warning, <literal>sqlca.sqlwarn[2]</literal> is set
|
|
to <literal>W</literal>. (In all other cases, it is set to
|
|
something different from <literal>W</literal>.) If
|
|
<literal>sqlca.sqlwarn[1]</literal> is set to
|
|
<literal>W</literal>, then a value was truncated when it was
|
|
stored in a host variable. <literal>sqlca.sqlwarn[0]</literal> is
|
|
set to <literal>W</literal> if any of the other elements are set
|
|
to indicate a warning.
|
|
</para>
|
|
|
|
<para>
|
|
The fields <structfield>sqlcaid</structfield>,
|
|
<structfield>sqlabc</structfield>,
|
|
<structfield>sqlerrp</structfield>, and the remaining elements of
|
|
<structfield>sqlerrd</structfield> and
|
|
<structfield>sqlwarn</structfield> currently contain no useful
|
|
information.
|
|
</para>
|
|
|
|
<para>
|
|
The structure <varname>sqlca</varname> is not defined in the SQL
|
|
standard, but is implemented in several other SQL database
|
|
systems. The definitions are similar at the core, but if you want
|
|
to write portable applications, then you should investigate the
|
|
different implementations carefully.
|
|
</para>
|
|
|
|
<para>
|
|
Here is one example that combines the use of <literal>WHENEVER</literal>
|
|
and <varname>sqlca</varname>, printing out the contents
|
|
of <varname>sqlca</varname> when an error occurs. This is perhaps
|
|
useful for debugging or prototyping applications, before
|
|
installing a more <quote>user-friendly</quote> error handler.
|
|
|
|
<programlisting>
|
|
EXEC SQL WHENEVER SQLERROR CALL print_sqlca();
|
|
|
|
void
|
|
print_sqlca()
|
|
{
|
|
fprintf(stderr, "==== sqlca ====\n");
|
|
fprintf(stderr, "sqlcode: %ld\n", sqlca.sqlcode);
|
|
fprintf(stderr, "sqlerrm.sqlerrml: %d\n", sqlca.sqlerrm.sqlerrml);
|
|
fprintf(stderr, "sqlerrm.sqlerrmc: %s\n", sqlca.sqlerrm.sqlerrmc);
|
|
fprintf(stderr, "sqlerrd: %ld %ld %ld %ld %ld %ld\n", sqlca.sqlerrd[0],sqlca.sqlerrd[1],sqlca.sqlerrd[2],
|
|
sqlca.sqlerrd[3],sqlca.sqlerrd[4],sqlca.sqlerrd[5]);
|
|
fprintf(stderr, "sqlwarn: %d %d %d %d %d %d %d %d\n", sqlca.sqlwarn[0], sqlca.sqlwarn[1], sqlca.sqlwarn[2],
|
|
sqlca.sqlwarn[3], sqlca.sqlwarn[4], sqlca.sqlwarn[5],
|
|
sqlca.sqlwarn[6], sqlca.sqlwarn[7]);
|
|
fprintf(stderr, "sqlstate: %5s\n", sqlca.sqlstate);
|
|
fprintf(stderr, "===============\n");
|
|
}
|
|
</programlisting>
|
|
|
|
The result could look as follows (here an error due to a
|
|
misspelled table name):
|
|
|
|
<screen>
|
|
==== sqlca ====
|
|
sqlcode: -400
|
|
sqlerrm.sqlerrml: 49
|
|
sqlerrm.sqlerrmc: relation "pg_databasep" does not exist on line 38
|
|
sqlerrd: 0 0 0 0 0 0
|
|
sqlwarn: 0 0 0 0 0 0 0 0
|
|
sqlstate: 42P01
|
|
===============
|
|
</screen>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-sqlstate-sqlcode">
|
|
<title><literal>SQLSTATE</literal> vs. <literal>SQLCODE</literal></title>
|
|
|
|
<para>
|
|
The fields <literal>sqlca.sqlstate</literal> and
|
|
<literal>sqlca.sqlcode</literal> are two different schemes that
|
|
provide error codes. Both are derived from the SQL standard, but
|
|
<literal>SQLCODE</literal> has been marked deprecated in the SQL-92
|
|
edition of the standard and has been dropped in later editions.
|
|
Therefore, new applications are strongly encouraged to use
|
|
<literal>SQLSTATE</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
<literal>SQLSTATE</literal> is a five-character array. The five
|
|
characters contain digits or upper-case letters that represent
|
|
codes of various error and warning conditions.
|
|
<literal>SQLSTATE</literal> has a hierarchical scheme: the first
|
|
two characters indicate the general class of the condition, the
|
|
last three characters indicate a subclass of the general
|
|
condition. A successful state is indicated by the code
|
|
<literal>00000</literal>. The <literal>SQLSTATE</literal> codes are for
|
|
the most part defined in the SQL standard. The
|
|
<productname>PostgreSQL</productname> server natively supports
|
|
<literal>SQLSTATE</literal> error codes; therefore a high degree
|
|
of consistency can be achieved by using this error code scheme
|
|
throughout all applications. For further information see
|
|
<xref linkend="errcodes-appendix"/>.
|
|
</para>
|
|
|
|
<para>
|
|
<literal>SQLCODE</literal>, the deprecated error code scheme, is a
|
|
simple integer. A value of 0 indicates success, a positive value
|
|
indicates success with additional information, a negative value
|
|
indicates an error. The SQL standard only defines the positive
|
|
value +100, which indicates that the last command returned or
|
|
affected zero rows, and no specific negative values. Therefore,
|
|
this scheme can only achieve poor portability and does not have a
|
|
hierarchical code assignment. Historically, the embedded SQL
|
|
processor for <productname>PostgreSQL</productname> has assigned
|
|
some specific <literal>SQLCODE</literal> values for its use, which
|
|
are listed below with their numeric value and their symbolic name.
|
|
Remember that these are not portable to other SQL implementations.
|
|
To simplify the porting of applications to the
|
|
<literal>SQLSTATE</literal> scheme, the corresponding
|
|
<literal>SQLSTATE</literal> is also listed. There is, however, no
|
|
one-to-one or one-to-many mapping between the two schemes (indeed
|
|
it is many-to-many), so you should consult the global
|
|
<literal>SQLSTATE</literal> listing in <xref linkend="errcodes-appendix"/>
|
|
in each case.
|
|
</para>
|
|
|
|
<para>
|
|
These are the assigned <literal>SQLCODE</literal> values:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>0 (<symbol>ECPG_NO_ERROR</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Indicates no error. (SQLSTATE 00000)
|
|
</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>
|
|
|
|
<para>
|
|
When processing a cursor in a loop, you could use this code as
|
|
a way to detect when to abort the loop, like this:
|
|
<programlisting>
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH ... ;
|
|
if (sqlca.sqlcode == ECPG_NOT_FOUND)
|
|
break;
|
|
}
|
|
</programlisting>
|
|
But <literal>WHENEVER NOT FOUND DO BREAK</literal> effectively
|
|
does this internally, so there is usually no advantage in
|
|
writing this out explicitly.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-12 (<symbol>ECPG_OUT_OF_MEMORY</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Indicates that your virtual memory is exhausted. The numeric
|
|
value is defined as <literal>-ENOMEM</literal>. (SQLSTATE
|
|
YE001)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-200 (<symbol>ECPG_UNSUPPORTED</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
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. (SQLSTATE YE002)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-201 (<symbol>ECPG_TOO_MANY_ARGUMENTS</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
This means that the command specified more host variables than
|
|
the command expected. (SQLSTATE 07001 or 07002)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-202 (<symbol>ECPG_TOO_FEW_ARGUMENTS</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
This means that the command specified fewer host variables than
|
|
the command expected. (SQLSTATE 07001 or 07002)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-203 (<symbol>ECPG_TOO_MANY_MATCHES</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
This means a query has returned multiple rows but the statement
|
|
was only prepared to store one result row (for example, because
|
|
the specified variables are not arrays). (SQLSTATE 21000)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-204 (<symbol>ECPG_INT_FORMAT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The host variable is of type <type>int</type> and the datum in
|
|
the database is of a different type and contains a value that
|
|
cannot be interpreted as an <type>int</type>. The library uses
|
|
<function>strtol()</function> for this conversion. (SQLSTATE
|
|
42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-205 (<symbol>ECPG_UINT_FORMAT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The host variable is of type <type>unsigned int</type> and the
|
|
datum in the database is of a different type and contains a
|
|
value that cannot be interpreted as an <type>unsigned
|
|
int</type>. The library uses <function>strtoul()</function>
|
|
for this conversion. (SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-206 (<symbol>ECPG_FLOAT_FORMAT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The host variable is of type <type>float</type> and the datum
|
|
in the 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.
|
|
(SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-207 (<symbol>ECPG_NUMERIC_FORMAT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The host variable is of type <type>numeric</type> and the datum
|
|
in the database is of another type and contains a value that
|
|
cannot be interpreted as a <type>numeric</type> value.
|
|
(SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-208 (<symbol>ECPG_INTERVAL_FORMAT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The host variable is of type <type>interval</type> and the datum
|
|
in the database is of another type and contains a value that
|
|
cannot be interpreted as an <type>interval</type> value.
|
|
(SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-209 (<symbol>ECPG_DATE_FORMAT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The host variable is of type <type>date</type> and the datum in
|
|
the database is of another type and contains a value that
|
|
cannot be interpreted as a <type>date</type> value.
|
|
(SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-210 (<symbol>ECPG_TIMESTAMP_FORMAT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The host variable is of type <type>timestamp</type> and the
|
|
datum in the database is of another type and contains a value
|
|
that cannot be interpreted as a <type>timestamp</type> value.
|
|
(SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
This means the host variable is of type <type>bool</type> and
|
|
the datum in the database is neither <literal>'t'</literal> nor
|
|
<literal>'f'</literal>. (SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The statement sent to the <productname>PostgreSQL</productname>
|
|
server was empty. (This cannot normally happen in an embedded
|
|
SQL program, so it might point to an internal error.) (SQLSTATE
|
|
YE002)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
A null value was returned and no null indicator variable was
|
|
supplied. (SQLSTATE 22002)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
An ordinary variable was used in a place that requires an
|
|
array. (SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The database returned an ordinary variable in a place that
|
|
requires array value. (SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-216 (<symbol>ECPG_ARRAY_INSERT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The value could not be inserted into the array. (SQLSTATE
|
|
42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-220 (<symbol>ECPG_NO_CONN</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The program tried to access a connection that does not exist.
|
|
(SQLSTATE 08003)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-221 (<symbol>ECPG_NOT_CONN</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The program tried to access a connection that does exist but is
|
|
not open. (This is an internal error.) (SQLSTATE YE002)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-230 (<symbol>ECPG_INVALID_STMT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The statement you are trying to use has not been prepared.
|
|
(SQLSTATE 26000)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-239 (<symbol>ECPG_INFORMIX_DUPLICATE_KEY</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Duplicate key error, violation of unique constraint (Informix
|
|
compatibility mode). (SQLSTATE 23505)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-240 (<symbol>ECPG_UNKNOWN_DESCRIPTOR</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The descriptor specified was not found. The statement you are
|
|
trying to use has not been prepared. (SQLSTATE 33000)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-241 (<symbol>ECPG_INVALID_DESCRIPTOR_INDEX</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The descriptor index specified was out of range. (SQLSTATE
|
|
07009)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-242 (<symbol>ECPG_UNKNOWN_DESCRIPTOR_ITEM</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
An invalid descriptor item was requested. (This is an internal
|
|
error.) (SQLSTATE YE002)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-243 (<symbol>ECPG_VAR_NOT_NUMERIC</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
During the execution of a dynamic statement, the database
|
|
returned a numeric value and the host variable was not numeric.
|
|
(SQLSTATE 07006)
|
|
</para>
|
|
</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>-284 (<symbol>ECPG_INFORMIX_SUBSELECT_NOT_ONE</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
A result of the subquery is not single row (Informix
|
|
compatibility mode). (SQLSTATE 21000)
|
|
</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>-403 (<symbol>ECPG_DUPLICATE_KEY</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Duplicate key error, violation of unique constraint. (SQLSTATE
|
|
23505)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-404 (<symbol>ECPG_SUBSELECT_NOT_ONE</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
A result for the subquery is not single row. (SQLSTATE 21000)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<!-- currently not used by the code -->
|
|
<!--
|
|
<varlistentry>
|
|
<term>-600 (<symbol>ECPG_WARNING_UNRECOGNIZED</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
An unrecognized warning was received from the server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-601 (<symbol>ECPG_WARNING_QUERY_IGNORED</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Current transaction is aborted. Queries are ignored until the
|
|
end of the transaction block.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
-->
|
|
|
|
<varlistentry>
|
|
<term>-602 (<symbol>ECPG_WARNING_UNKNOWN_PORTAL</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
An invalid cursor name was specified. (SQLSTATE 34000)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-603 (<symbol>ECPG_WARNING_IN_TRANSACTION</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Transaction is in progress. (SQLSTATE 25001)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-604 (<symbol>ECPG_WARNING_NO_TRANSACTION</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
There is no active (in-progress) transaction. (SQLSTATE 25P01)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-605 (<symbol>ECPG_WARNING_PORTAL_EXISTS</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
An existing cursor name was specified. (SQLSTATE 42P03)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-preproc">
|
|
<title>Preprocessor Directives</title>
|
|
|
|
<para>
|
|
Several preprocessor directives are available that modify how
|
|
the <command>ecpg</command> preprocessor parses and processes a
|
|
file.
|
|
</para>
|
|
|
|
<sect2 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>;
|
|
EXEC SQL INCLUDE <<replaceable>filename</replaceable>>;
|
|
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>
|
|
The <command>ecpg</command> preprocessor will search a file at
|
|
several directories in following order:
|
|
|
|
<itemizedlist>
|
|
<listitem><simpara>current directory</simpara></listitem>
|
|
<listitem><simpara><filename>/usr/local/include</filename></simpara></listitem>
|
|
<listitem><simpara>PostgreSQL include directory, defined at build time (e.g., <filename>/usr/local/pgsql/include</filename>)</simpara></listitem>
|
|
<listitem><simpara><filename>/usr/include</filename></simpara></listitem>
|
|
</itemizedlist>
|
|
|
|
But when <literal>EXEC SQL INCLUDE
|
|
"<replaceable>filename</replaceable>"</literal> is used, only the
|
|
current directory is searched.
|
|
</para>
|
|
|
|
<para>
|
|
In each directory, the preprocessor will first look for the file
|
|
name as given, and if not found will append <literal>.h</literal>
|
|
to the file name and try again (unless the specified file name
|
|
already has that suffix).
|
|
</para>
|
|
|
|
<para>
|
|
Note that <command>EXEC SQL INCLUDE</command> is <emphasis>not</emphasis> the same as:
|
|
<programlisting>
|
|
#include <<replaceable>filename</replaceable>.h>
|
|
</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>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-define">
|
|
<title>The define and undef Directives</title>
|
|
<para>
|
|
Similar to the directive <literal>#define</literal> that is known from C,
|
|
embedded SQL has a similar concept:
|
|
<programlisting>
|
|
EXEC SQL DEFINE <replaceable>name</replaceable>;
|
|
EXEC SQL DEFINE <replaceable>name</replaceable> <replaceable>value</replaceable>;
|
|
</programlisting>
|
|
So you can define a name:
|
|
<programlisting>
|
|
EXEC SQL DEFINE HAVE_FEATURE;
|
|
</programlisting>
|
|
And you can also define constants:
|
|
<programlisting>
|
|
EXEC SQL DEFINE MYNUMBER 12;
|
|
EXEC SQL DEFINE MYSTRING 'abc';
|
|
</programlisting>
|
|
Use <literal>undef</literal> to remove a previous definition:
|
|
<programlisting>
|
|
EXEC SQL UNDEF MYNUMBER;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Of course you can continue to use the C versions <literal>#define</literal>
|
|
and <literal>#undef</literal> in your embedded SQL program. The difference
|
|
is where your defined values get evaluated. If you use <literal>EXEC SQL
|
|
DEFINE</literal> then the <command>ecpg</command> preprocessor evaluates the defines and substitutes
|
|
the values. For example if you write:
|
|
<programlisting>
|
|
EXEC SQL DEFINE MYNUMBER 12;
|
|
...
|
|
EXEC SQL UPDATE Tbl SET col = MYNUMBER;
|
|
</programlisting>
|
|
then <command>ecpg</command> will already do the substitution and your C compiler will never
|
|
see any name or identifier <literal>MYNUMBER</literal>. Note that you cannot use
|
|
<literal>#define</literal> for a constant that you are going to use in an
|
|
embedded SQL query because in this case the embedded SQL precompiler is not
|
|
able to see this declaration.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-ifdef">
|
|
<title>ifdef, ifndef, elif, else, and endif Directives</title>
|
|
<para>
|
|
You can use the following directives to compile code sections conditionally:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL ifdef <replaceable>name</replaceable>;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Checks a <replaceable>name</replaceable> and processes subsequent lines if
|
|
<replaceable>name</replaceable> has been defined via <literal>EXEC SQL define
|
|
<replaceable>name</replaceable></literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL ifndef <replaceable>name</replaceable>;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Checks a <replaceable>name</replaceable> and processes subsequent lines if
|
|
<replaceable>name</replaceable> has <emphasis>not</emphasis> been defined via
|
|
<literal>EXEC SQL define <replaceable>name</replaceable></literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL elif <replaceable>name</replaceable>;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Begins an optional alternative section after an
|
|
<literal>EXEC SQL ifdef <replaceable>name</replaceable></literal> or
|
|
<literal>EXEC SQL ifndef <replaceable>name</replaceable></literal>
|
|
directive. Any number of <literal>elif</literal> sections can appear.
|
|
Lines following an <literal>elif</literal> will be processed
|
|
if <replaceable>name</replaceable> has been
|
|
defined <emphasis>and</emphasis> no previous section of the same
|
|
<literal>ifdef</literal>/<literal>ifndef</literal>...<literal>endif</literal>
|
|
construct has been processed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL else;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Begins an optional, final alternative section after an
|
|
<literal>EXEC SQL ifdef <replaceable>name</replaceable></literal> or
|
|
<literal>EXEC SQL ifndef <replaceable>name</replaceable></literal>
|
|
directive. Subsequent lines will be processed if no previous section
|
|
of the same
|
|
<literal>ifdef</literal>/<literal>ifndef</literal>...<literal>endif</literal>
|
|
construct has been processed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL endif;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Ends an
|
|
<literal>ifdef</literal>/<literal>ifndef</literal>...<literal>endif</literal>
|
|
construct. Subsequent lines are processed normally.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
<literal>ifdef</literal>/<literal>ifndef</literal>...<literal>endif</literal>
|
|
constructs can be nested, up to 127 levels deep.
|
|
</para>
|
|
|
|
<para>
|
|
This example will compile exactly one of the three <literal>SET
|
|
TIMEZONE</literal> commands:
|
|
<programlisting>
|
|
EXEC SQL ifdef TZVAR;
|
|
EXEC SQL SET TIMEZONE TO TZVAR;
|
|
EXEC SQL elif TZNAME;
|
|
EXEC SQL SET TIMEZONE TO TZNAME;
|
|
EXEC SQL else;
|
|
EXEC SQL SET TIMEZONE TO 'GMT';
|
|
EXEC SQL endif;
|
|
</programlisting>
|
|
</para>
|
|
|
|
</sect2>
|
|
</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</productname> 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</productname> installation, so if you installed
|
|
<productname>PostgreSQL</productname> 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>
|
|
You can
|
|
use <command>pg_config</command><indexterm><primary>pg_config</primary><secondary sortas="ecpg">with
|
|
ecpg</secondary></indexterm>
|
|
or <command>pkg-config</command><indexterm><primary>pkg-config</primary><secondary sortas="ecpg">with
|
|
ecpg</secondary></indexterm> with package name <literal>libecpg</literal> to
|
|
get the paths for your installation.
|
|
</para>
|
|
|
|
<para>
|
|
If you manage the build process of a larger project using
|
|
<application>make</application>, it might 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 by
|
|
default. However, you might need to use some 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</application> libraries and an application are
|
|
compiled with different flags, this function call will crash the
|
|
application because the internal representation of the
|
|
<literal>FILE</literal> 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>ECPGget_PGconn(const char *<replaceable>connection_name</replaceable>)
|
|
</function> returns the library database connection handle identified by the given name.
|
|
If <replaceable>connection_name</replaceable> is set to <literal>NULL</literal>, the current
|
|
connection handle is returned. If no connection handle can be identified, the function returns
|
|
<literal>NULL</literal>. The returned connection handle can be used to call any other functions
|
|
from <application>libpq</application>, if necessary.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
It is a bad idea to manipulate database connection handles made from <application>ecpg</application> directly
|
|
with <application>libpq</application> routines.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>ECPGtransactionStatus(const char *<replaceable>connection_name</replaceable>)</function>
|
|
returns the current transaction status of the given connection identified by <replaceable>connection_name</replaceable>.
|
|
See <xref linkend="libpq-status"/> and libpq's <xref linkend="libpq-PQtransactionStatus"/> for details about the returned status codes.
|
|
</para>
|
|
</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</literal>
|
|
if a single connection is being used.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-lo">
|
|
<title>Large Objects</title>
|
|
|
|
<para>
|
|
Large objects are not directly supported by ECPG, but ECPG
|
|
application can manipulate large objects through the libpq large
|
|
object functions, obtaining the necessary <type>PGconn</type>
|
|
object by calling the <function>ECPGget_PGconn()</function>
|
|
function. (However, use of
|
|
the <function>ECPGget_PGconn()</function> function and touching
|
|
<type>PGconn</type> objects directly should be done very carefully
|
|
and ideally not mixed with other ECPG database access calls.)
|
|
</para>
|
|
|
|
<para>
|
|
For more details about the <function>ECPGget_PGconn()</function>, see
|
|
<xref linkend="ecpg-library"/>. For information about the large
|
|
object function interface, see <xref linkend="largeobjects"/>.
|
|
</para>
|
|
|
|
<para>
|
|
Large object functions have to be called in a transaction block, so
|
|
when autocommit is off, <command>BEGIN</command> commands have to
|
|
be issued explicitly.
|
|
</para>
|
|
|
|
<para>
|
|
<xref linkend="ecpg-lo-example"/> shows an example program that
|
|
illustrates how to create, write, and read a large object in an
|
|
ECPG application.
|
|
</para>
|
|
|
|
<example id="ecpg-lo-example">
|
|
<title>ECPG Program Accessing Large Objects</title>
|
|
<programlisting><![CDATA[
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <libpq-fe.h>
|
|
#include <libpq/libpq-fs.h>
|
|
|
|
EXEC SQL WHENEVER SQLERROR STOP;
|
|
|
|
int
|
|
main(void)
|
|
{
|
|
PGconn *conn;
|
|
Oid loid;
|
|
int fd;
|
|
char buf[256];
|
|
int buflen = 256;
|
|
char buf2[256];
|
|
int rc;
|
|
|
|
memset(buf, 1, buflen);
|
|
|
|
EXEC SQL CONNECT TO testdb AS con1;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
conn = ECPGget_PGconn("con1");
|
|
printf("conn = %p\n", conn);
|
|
|
|
/* create */
|
|
loid = lo_create(conn, 0);
|
|
if (loid < 0)
|
|
printf("lo_create() failed: %s", PQerrorMessage(conn));
|
|
|
|
printf("loid = %d\n", loid);
|
|
|
|
/* write test */
|
|
fd = lo_open(conn, loid, INV_READ|INV_WRITE);
|
|
if (fd < 0)
|
|
printf("lo_open() failed: %s", PQerrorMessage(conn));
|
|
|
|
printf("fd = %d\n", fd);
|
|
|
|
rc = lo_write(conn, fd, buf, buflen);
|
|
if (rc < 0)
|
|
printf("lo_write() failed\n");
|
|
|
|
rc = lo_close(conn, fd);
|
|
if (rc < 0)
|
|
printf("lo_close() failed: %s", PQerrorMessage(conn));
|
|
|
|
/* read test */
|
|
fd = lo_open(conn, loid, INV_READ);
|
|
if (fd < 0)
|
|
printf("lo_open() failed: %s", PQerrorMessage(conn));
|
|
|
|
printf("fd = %d\n", fd);
|
|
|
|
rc = lo_read(conn, fd, buf2, buflen);
|
|
if (rc < 0)
|
|
printf("lo_read() failed\n");
|
|
|
|
rc = lo_close(conn, fd);
|
|
if (rc < 0)
|
|
printf("lo_close() failed: %s", PQerrorMessage(conn));
|
|
|
|
/* check */
|
|
rc = memcmp(buf, buf2, buflen);
|
|
printf("memcmp() = %d\n", rc);
|
|
|
|
/* cleanup */
|
|
rc = lo_unlink(conn, loid);
|
|
if (rc < 0)
|
|
printf("lo_unlink() failed: %s", PQerrorMessage(conn));
|
|
|
|
EXEC SQL COMMIT;
|
|
EXEC SQL DISCONNECT ALL;
|
|
return 0;
|
|
}
|
|
]]></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-cpp">
|
|
<title><acronym>C++</acronym> Applications</title>
|
|
|
|
<para>
|
|
ECPG has some limited support for C++ applications. This section
|
|
describes some caveats.
|
|
</para>
|
|
|
|
<para>
|
|
The <command>ecpg</command> preprocessor takes an input file
|
|
written in C (or something like C) and embedded SQL commands,
|
|
converts the embedded SQL commands into C language chunks, and
|
|
finally generates a <filename>.c</filename> file. The header file
|
|
declarations of the library functions used by the C language chunks
|
|
that <command>ecpg</command> generates are wrapped
|
|
in <literal>extern "C" { ... }</literal> blocks when used under
|
|
C++, so they should work seamlessly in C++.
|
|
</para>
|
|
|
|
<para>
|
|
In general, however, the <command>ecpg</command> preprocessor only
|
|
understands C; it does not handle the special syntax and reserved
|
|
words of the C++ language. So, some embedded SQL code written in
|
|
C++ application code that uses complicated features specific to C++
|
|
might fail to be preprocessed correctly or might not work as
|
|
expected.
|
|
</para>
|
|
|
|
<para>
|
|
A safe way to use the embedded SQL code in a C++ application is
|
|
hiding the ECPG calls in a C module, which the C++ application code
|
|
calls into to access the database, and linking that together with
|
|
the rest of the C++ code. See <xref linkend="ecpg-cpp-and-c"/>
|
|
about that.
|
|
</para>
|
|
|
|
<sect2 id="ecpg-cpp-scope">
|
|
<title>Scope for Host Variables</title>
|
|
|
|
<para>
|
|
The <command>ecpg</command> preprocessor understands the scope of
|
|
variables in C. In the C language, this is rather simple because
|
|
the scopes of variables is based on their code blocks. In C++,
|
|
however, the class member variables are referenced in a different
|
|
code block from the declared position, so
|
|
the <command>ecpg</command> preprocessor will not understand the
|
|
scope of the class member variables.
|
|
</para>
|
|
|
|
<para>
|
|
For example, in the following case, the <command>ecpg</command>
|
|
preprocessor cannot find any declaration for the
|
|
variable <literal>dbname</literal> in the <literal>test</literal>
|
|
method, so an error will occur.
|
|
|
|
<programlisting>
|
|
class TestCpp
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char dbname[1024];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
public:
|
|
TestCpp();
|
|
void test();
|
|
~TestCpp();
|
|
};
|
|
|
|
TestCpp::TestCpp()
|
|
{
|
|
EXEC SQL CONNECT TO testdb1;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
}
|
|
|
|
void Test::test()
|
|
{
|
|
EXEC SQL SELECT current_database() INTO :dbname;
|
|
printf("current_database = %s\n", dbname);
|
|
}
|
|
|
|
TestCpp::~TestCpp()
|
|
{
|
|
EXEC SQL DISCONNECT ALL;
|
|
}
|
|
</programlisting>
|
|
|
|
This code will result in an error like this:
|
|
<screen>
|
|
<userinput>ecpg test_cpp.pgc</userinput>
|
|
test_cpp.pgc:28: ERROR: variable "dbname" is not declared
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To avoid this scope issue, the <literal>test</literal> method
|
|
could be modified to use a local variable as intermediate storage.
|
|
But this approach is only a poor workaround, because it uglifies
|
|
the code and reduces performance.
|
|
|
|
<programlisting>
|
|
void TestCpp::test()
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char tmp[1024];
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL SELECT current_database() INTO :tmp;
|
|
strlcpy(dbname, tmp, sizeof(tmp));
|
|
|
|
printf("current_database = %s\n", dbname);
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-cpp-and-c">
|
|
<title>C++ Application Development with External C Module</title>
|
|
|
|
<para>
|
|
If you understand these technical limitations of
|
|
the <command>ecpg</command> preprocessor in C++, you might come to
|
|
the conclusion that linking C objects and C++ objects at the link
|
|
stage to enable C++ applications to use ECPG features could be
|
|
better than writing some embedded SQL commands in C++ code
|
|
directly. This section describes a way to 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>
|
|
<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 <stdio.h>
|
|
|
|
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>
|
|
<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>
|
|
<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 area</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
ALLOCATE DESCRIPTOR <replaceable class="parameter">name</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>ALLOCATE DESCRIPTOR</command> allocates a new named SQL
|
|
descriptor area, which can be used to exchange data between the
|
|
PostgreSQL server and the host program.
|
|
</para>
|
|
|
|
<para>
|
|
Descriptor areas should be freed after use using
|
|
the <command>DEALLOCATE DESCRIPTOR</command> command.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A name of SQL descriptor, case sensitive. This can be an SQL
|
|
identifier or a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
EXEC SQL ALLOCATE DESCRIPTOR mydesc;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>ALLOCATE DESCRIPTOR</command> is specified in the SQL
|
|
standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-deallocate-descriptor"/></member>
|
|
<member><xref linkend="ecpg-sql-get-descriptor"/></member>
|
|
<member><xref linkend="ecpg-sql-set-descriptor"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-connect">
|
|
<refnamediv>
|
|
<refname>CONNECT</refname>
|
|
<refpurpose>establish a database connection</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
CONNECT TO <replaceable>connection_target</replaceable> [ AS <replaceable>connection_name</replaceable> ] [ USER <replaceable>connection_user</replaceable> ]
|
|
CONNECT TO DEFAULT
|
|
CONNECT <replaceable>connection_user</replaceable>
|
|
DATABASE <replaceable>connection_target</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
The <command>CONNECT</command> command establishes a connection
|
|
between the client and the PostgreSQL server.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">connection_target</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
<replaceable class="parameter">connection_target</replaceable>
|
|
specifies the target server of the connection on one of
|
|
several forms.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>[ <replaceable>database_name</replaceable> ] [ <literal>@</literal><replaceable>host</replaceable> ] [ <literal>:</literal><replaceable>port</replaceable> ]</term>
|
|
<listitem>
|
|
<para>
|
|
Connect over TCP/IP
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>unix:postgresql://</literal><replaceable>host</replaceable> [ <literal>:</literal><replaceable>port</replaceable> ] <literal>/</literal> [ <replaceable>database_name</replaceable> ] [ <literal>?</literal><replaceable>connection_option</replaceable> ]</term>
|
|
<listitem>
|
|
<para>
|
|
Connect over Unix-domain sockets
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>tcp:postgresql://</literal><replaceable>host</replaceable> [ <literal>:</literal><replaceable>port</replaceable> ] <literal>/</literal> [ <replaceable>database_name</replaceable> ] [ <literal>?</literal><replaceable>connection_option</replaceable> ]</term>
|
|
<listitem>
|
|
<para>
|
|
Connect over TCP/IP
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>SQL string constant</term>
|
|
<listitem>
|
|
<para>
|
|
containing a value in one of the above forms
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>host variable</term>
|
|
<listitem>
|
|
<para>
|
|
host variable of type <type>char[]</type>
|
|
or <type>VARCHAR[]</type> containing a value in one of the
|
|
above forms
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">connection_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
An optional identifier for the connection, so that it can be
|
|
referred to in other commands. This can be an SQL identifier
|
|
or a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">connection_user</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The user name for the database connection.
|
|
</para>
|
|
|
|
<para>
|
|
This parameter can also specify user name and password, using one the forms
|
|
<literal><replaceable>user_name</replaceable>/<replaceable>password</replaceable></literal>,
|
|
<literal><replaceable>user_name</replaceable> IDENTIFIED BY <replaceable>password</replaceable></literal>, or
|
|
<literal><replaceable>user_name</replaceable> USING <replaceable>password</replaceable></literal>.
|
|
</para>
|
|
|
|
<para>
|
|
User name and password can be SQL identifiers, string
|
|
constants, or host variables.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DEFAULT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Use all default connection parameters, as defined by libpq.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
Here a several variants for specifying connection parameters:
|
|
<programlisting>
|
|
EXEC SQL CONNECT TO "connectdb" AS main;
|
|
EXEC SQL CONNECT TO "connectdb" AS second;
|
|
EXEC SQL CONNECT TO "unix:postgresql://200.46.204.71/connectdb" AS main USER connectuser;
|
|
EXEC SQL CONNECT TO "unix:postgresql://localhost/connectdb" AS main USER connectuser;
|
|
EXEC SQL CONNECT TO 'connectdb' AS main;
|
|
EXEC SQL CONNECT TO 'unix:postgresql://localhost/connectdb' AS main USER :user;
|
|
EXEC SQL CONNECT TO :db AS :id;
|
|
EXEC SQL CONNECT TO :db USER connectuser USING :pw;
|
|
EXEC SQL CONNECT TO @localhost AS main USER connectdb;
|
|
EXEC SQL CONNECT TO REGRESSDB1 as main;
|
|
EXEC SQL CONNECT TO AS main USER connectdb;
|
|
EXEC SQL CONNECT TO connectdb AS :id;
|
|
EXEC SQL CONNECT TO connectdb AS main USER connectuser/connectdb;
|
|
EXEC SQL CONNECT TO connectdb AS main;
|
|
EXEC SQL CONNECT TO connectdb@localhost AS main;
|
|
EXEC SQL CONNECT TO tcp:postgresql://localhost/ USER connectdb;
|
|
EXEC SQL CONNECT TO tcp:postgresql://localhost/connectdb USER connectuser IDENTIFIED BY connectpw;
|
|
EXEC SQL CONNECT TO tcp:postgresql://localhost:20/connectdb USER connectuser IDENTIFIED BY connectpw;
|
|
EXEC SQL CONNECT TO unix:postgresql://localhost/ AS main USER connectdb;
|
|
EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb AS main USER connectuser;
|
|
EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser IDENTIFIED BY "connectpw";
|
|
EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser USING "connectpw";
|
|
EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb?connect_timeout=14 USER connectuser;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example program that illustrates the use of host
|
|
variables to specify connection parameters:
|
|
<programlisting>
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char *dbname = "testdb"; /* database name */
|
|
char *user = "testuser"; /* connection user name */
|
|
char *connection = "tcp:postgresql://localhost:5432/testdb";
|
|
/* connection string */
|
|
char ver[256]; /* buffer to store the version string */
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
ECPGdebug(1, stderr);
|
|
|
|
EXEC SQL CONNECT TO :dbname USER :user;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
EXEC SQL SELECT version() INTO :ver;
|
|
EXEC SQL DISCONNECT;
|
|
|
|
printf("version: %s\n", ver);
|
|
|
|
EXEC SQL CONNECT TO :connection USER :user;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
EXEC SQL SELECT version() INTO :ver;
|
|
EXEC SQL DISCONNECT;
|
|
|
|
printf("version: %s\n", ver);
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>CONNECT</command> is specified in the SQL standard, but
|
|
the format of the connection parameters is
|
|
implementation-specific.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-disconnect"/></member>
|
|
<member><xref linkend="ecpg-sql-set-connection"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-deallocate-descriptor">
|
|
<refnamediv>
|
|
<refname>DEALLOCATE DESCRIPTOR</refname>
|
|
<refpurpose>deallocate an SQL descriptor area</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
DEALLOCATE DESCRIPTOR <replaceable class="parameter">name</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>DEALLOCATE DESCRIPTOR</command> deallocates a named SQL
|
|
descriptor area.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the descriptor which is going to be deallocated.
|
|
It is case sensitive. This can be an SQL identifier or a host
|
|
variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
EXEC SQL DEALLOCATE DESCRIPTOR mydesc;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>DEALLOCATE DESCRIPTOR</command> is specified in the SQL
|
|
standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
|
|
<member><xref linkend="ecpg-sql-get-descriptor"/></member>
|
|
<member><xref linkend="ecpg-sql-set-descriptor"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-declare">
|
|
<refnamediv>
|
|
<refname>DECLARE</refname>
|
|
<refpurpose>define a cursor</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
DECLARE <replaceable class="parameter">cursor_name</replaceable> [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR <replaceable class="parameter">prepared_name</replaceable>
|
|
DECLARE <replaceable class="parameter">cursor_name</replaceable> [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR <replaceable class="parameter">query</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>DECLARE</command> declares a cursor for iterating over
|
|
the result set of a prepared statement. This command has
|
|
slightly different semantics from the direct SQL
|
|
command <command>DECLARE</command>: Whereas the latter executes a
|
|
query and prepares the result set for retrieval, this embedded
|
|
SQL command merely declares a name as a <quote>loop
|
|
variable</quote> for iterating over the result set of a query;
|
|
the actual execution happens when the cursor is opened with
|
|
the <command>OPEN</command> command.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">cursor_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A cursor name, case sensitive. This can be an SQL identifier
|
|
or a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">prepared_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of a prepared query, either as an SQL identifier or a
|
|
host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">query</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A <xref linkend="sql-select"/> or
|
|
<xref linkend="sql-values"/> command which will provide the
|
|
rows to be returned by the cursor.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
For the meaning of the cursor options,
|
|
see <xref linkend="sql-declare"/>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
Examples declaring a cursor for a query:
|
|
<programlisting>
|
|
EXEC SQL DECLARE C CURSOR FOR SELECT * FROM My_Table;
|
|
EXEC SQL DECLARE C CURSOR FOR SELECT Item1 FROM T;
|
|
EXEC SQL DECLARE cur1 CURSOR FOR SELECT version();
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
An example declaring a cursor for a prepared statement:
|
|
<programlisting>
|
|
EXEC SQL PREPARE stmt1 AS SELECT version();
|
|
EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>DECLARE</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-open"/></member>
|
|
<member><xref linkend="sql-close"/></member>
|
|
<member><xref linkend="sql-declare"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-describe">
|
|
<refnamediv>
|
|
<refname>DESCRIBE</refname>
|
|
<refpurpose>obtain information about a prepared statement or result set</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
DESCRIBE [ OUTPUT ] <replaceable class="parameter">prepared_name</replaceable> USING [ SQL ] DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable>
|
|
DESCRIBE [ OUTPUT ] <replaceable class="parameter">prepared_name</replaceable> INTO [ SQL ] DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable>
|
|
DESCRIBE [ OUTPUT ] <replaceable class="parameter">prepared_name</replaceable> INTO <replaceable class="parameter">sqlda_name</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>DESCRIBE</command> retrieves metadata information about
|
|
the result columns contained in a prepared statement, without
|
|
actually fetching a row.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">prepared_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of a prepared statement. This can be an SQL
|
|
identifier or a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A descriptor name. It is case sensitive. It can be an SQL
|
|
identifier or a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">sqlda_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of an SQLDA variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
EXEC SQL ALLOCATE DESCRIPTOR mydesc;
|
|
EXEC SQL PREPARE stmt1 FROM :sql_stmt;
|
|
EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;
|
|
EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :charvar = NAME;
|
|
EXEC SQL DEALLOCATE DESCRIPTOR mydesc;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>DESCRIBE</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
|
|
<member><xref linkend="ecpg-sql-get-descriptor"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-disconnect">
|
|
<refnamediv>
|
|
<refname>DISCONNECT</refname>
|
|
<refpurpose>terminate a database connection</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
DISCONNECT <replaceable class="parameter">connection_name</replaceable>
|
|
DISCONNECT [ CURRENT ]
|
|
DISCONNECT DEFAULT
|
|
DISCONNECT ALL
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>DISCONNECT</command> closes a connection (or all
|
|
connections) to the database.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">connection_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A database connection name established by
|
|
the <command>CONNECT</command> command.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>CURRENT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Close the <quote>current</quote> connection, which is either
|
|
the most recently opened connection, or the connection set by
|
|
the <command>SET CONNECTION</command> command. This is also
|
|
the default if no argument is given to
|
|
the <command>DISCONNECT</command> command.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DEFAULT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Close the default connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ALL</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Close all open connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL CONNECT TO testdb AS DEFAULT USER testuser;
|
|
EXEC SQL CONNECT TO testdb AS con1 USER testuser;
|
|
EXEC SQL CONNECT TO testdb AS con2 USER testuser;
|
|
EXEC SQL CONNECT TO testdb AS con3 USER testuser;
|
|
|
|
EXEC SQL DISCONNECT CURRENT; /* close con3 */
|
|
EXEC SQL DISCONNECT DEFAULT; /* close DEFAULT */
|
|
EXEC SQL DISCONNECT ALL; /* close con2 and con1 */
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>DISCONNECT</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-connect"/></member>
|
|
<member><xref linkend="ecpg-sql-set-connection"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-execute-immediate">
|
|
<refnamediv>
|
|
<refname>EXECUTE IMMEDIATE</refname>
|
|
<refpurpose>dynamically prepare and execute a statement</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
EXECUTE IMMEDIATE <replaceable class="parameter">string</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>EXECUTE IMMEDIATE</command> immediately prepares and
|
|
executes a dynamically specified SQL statement, without
|
|
retrieving result rows.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">string</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A literal C string or a host variable containing the SQL
|
|
statement to be executed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
Here is an example that executes an <command>INSERT</command>
|
|
statement using <command>EXECUTE IMMEDIATE</command> and a host
|
|
variable named <varname>command</varname>:
|
|
<programlisting>
|
|
sprintf(command, "INSERT INTO test (name, amount, letter) VALUES ('db: ''r1''', 1, 'f')");
|
|
EXEC SQL EXECUTE IMMEDIATE :command;
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>EXECUTE IMMEDIATE</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-get-descriptor">
|
|
<refnamediv>
|
|
<refname>GET DESCRIPTOR</refname>
|
|
<refpurpose>get information from an SQL descriptor area</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
GET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> <replaceable class="parameter">:cvariable</replaceable> = <replaceable class="parameter">descriptor_header_item</replaceable> [, ... ]
|
|
GET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> VALUE <replaceable class="parameter">column_number</replaceable> <replaceable class="parameter">:cvariable</replaceable> = <replaceable class="parameter">descriptor_item</replaceable> [, ... ]
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>GET DESCRIPTOR</command> retrieves information about a
|
|
query result set from an SQL descriptor area and stores it into
|
|
host variables. A descriptor area is typically populated
|
|
using <command>FETCH</command> or <command>SELECT</command>
|
|
before using this command to transfer the information into host
|
|
language variables.
|
|
</para>
|
|
|
|
<para>
|
|
This command has two forms: The first form retrieves
|
|
descriptor <quote>header</quote> items, which apply to the result
|
|
set in its entirety. One example is the row count. The second
|
|
form, which requires the column number as additional parameter,
|
|
retrieves information about a particular column. Examples are
|
|
the column name and the actual column value.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A descriptor name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_header_item</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A token identifying which header information item to retrieve.
|
|
Only <literal>COUNT</literal>, to get the number of columns in the
|
|
result set, is currently supported.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">column_number</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The number of the column about which information is to be
|
|
retrieved. The count starts at 1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_item</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A token identifying which item of information about a column
|
|
to retrieve. See <xref linkend="ecpg-named-descriptors"/> for
|
|
a list of supported items.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">cvariable</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A host variable that will receive the data retrieved from the
|
|
descriptor area.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
An example to retrieve the number of columns in a result set:
|
|
<programlisting>
|
|
EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
An example to retrieve a data length in the first column:
|
|
<programlisting>
|
|
EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
An example to retrieve the data body of the second column as a
|
|
string:
|
|
<programlisting>
|
|
EXEC SQL GET DESCRIPTOR d VALUE 2 :d_data = DATA;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example for a whole procedure of
|
|
executing <literal>SELECT current_database();</literal> and showing the number of
|
|
columns, the column data length, and the column data:
|
|
<programlisting>
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int d_count;
|
|
char d_data[1024];
|
|
int d_returned_octet_length;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL CONNECT TO testdb AS con1 USER testuser;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
EXEC SQL ALLOCATE DESCRIPTOR d;
|
|
|
|
/* Declare, open a cursor, and assign a descriptor to the cursor */
|
|
EXEC SQL DECLARE cur CURSOR FOR SELECT current_database();
|
|
EXEC SQL OPEN cur;
|
|
EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d;
|
|
|
|
/* Get a number of total columns */
|
|
EXEC SQL GET DESCRIPTOR d :d_count = COUNT;
|
|
printf("d_count = %d\n", d_count);
|
|
|
|
/* Get length of a returned column */
|
|
EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH;
|
|
printf("d_returned_octet_length = %d\n", d_returned_octet_length);
|
|
|
|
/* Fetch the returned column as a string */
|
|
EXEC SQL GET DESCRIPTOR d VALUE 1 :d_data = DATA;
|
|
printf("d_data = %s\n", d_data);
|
|
|
|
/* Closing */
|
|
EXEC SQL CLOSE cur;
|
|
EXEC SQL COMMIT;
|
|
|
|
EXEC SQL DEALLOCATE DESCRIPTOR d;
|
|
EXEC SQL DISCONNECT ALL;
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
When the example is executed, the result will look like this:
|
|
<screen>
|
|
d_count = 1
|
|
d_returned_octet_length = 6
|
|
d_data = testdb
|
|
</screen>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>GET DESCRIPTOR</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
|
|
<member><xref linkend="ecpg-sql-set-descriptor"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-open">
|
|
<refnamediv>
|
|
<refname>OPEN</refname>
|
|
<refpurpose>open a dynamic cursor</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
OPEN <replaceable class="parameter">cursor_name</replaceable>
|
|
OPEN <replaceable class="parameter">cursor_name</replaceable> USING <replaceable class="parameter">value</replaceable> [, ... ]
|
|
OPEN <replaceable class="parameter">cursor_name</replaceable> USING SQL DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>OPEN</command> opens a cursor and optionally binds
|
|
actual values to the placeholders in the cursor's declaration.
|
|
The cursor must previously have been declared with
|
|
the <command>DECLARE</command> command. The execution
|
|
of <command>OPEN</command> causes the query to start executing on
|
|
the server.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">cursor_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the cursor to be opened. This can be an SQL
|
|
identifier or a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">value</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A value to be bound to a placeholder in the cursor. This can
|
|
be an SQL constant, a host variable, or a host variable with
|
|
indicator.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of a descriptor containing values to be bound to the
|
|
placeholders in the cursor. This can be an SQL identifier or
|
|
a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
EXEC SQL OPEN a;
|
|
EXEC SQL OPEN d USING 1, 'test';
|
|
EXEC SQL OPEN c1 USING SQL DESCRIPTOR mydesc;
|
|
EXEC SQL OPEN :curname1;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>OPEN</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-declare"/></member>
|
|
<member><xref linkend="sql-close"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-prepare">
|
|
<refnamediv>
|
|
<refname>PREPARE</refname>
|
|
<refpurpose>prepare a statement for execution</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
PREPARE <replaceable class="parameter">name</replaceable> FROM <replaceable class="parameter">string</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>PREPARE</command> prepares a statement dynamically
|
|
specified as a string for execution. This is different from the
|
|
direct SQL statement <xref linkend="sql-prepare"/>, which can also
|
|
be used in embedded programs. The <xref linkend="sql-execute"/>
|
|
command is used to execute either kind of prepared statement.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">prepared_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
An identifier for the prepared query.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">string</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A literal C string or a host variable containing a preparable
|
|
statement, one of the SELECT, INSERT, UPDATE, or
|
|
DELETE.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
char *stmt = "SELECT * FROM test1 WHERE a = ? AND b = ?";
|
|
|
|
EXEC SQL ALLOCATE DESCRIPTOR outdesc;
|
|
EXEC SQL PREPARE foo FROM :stmt;
|
|
|
|
EXEC SQL EXECUTE foo USING SQL DESCRIPTOR indesc INTO SQL DESCRIPTOR outdesc;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>PREPARE</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="sql-execute"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-set-autocommit">
|
|
<refnamediv>
|
|
<refname>SET AUTOCOMMIT</refname>
|
|
<refpurpose>set the autocommit behavior of the current session</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
SET AUTOCOMMIT { = | TO } { ON | OFF }
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>SET AUTOCOMMIT</command> sets the autocommit behavior of
|
|
the current database session. By default, embedded SQL programs
|
|
are <emphasis>not</emphasis> in autocommit mode,
|
|
so <command>COMMIT</command> needs to be issued explicitly when
|
|
desired. This command can change the session to autocommit mode,
|
|
where each individual statement is committed implicitly.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>SET AUTOCOMMIT</command> is an extension of PostgreSQL ECPG.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-set-connection">
|
|
<refnamediv>
|
|
<refname>SET CONNECTION</refname>
|
|
<refpurpose>select a database connection</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
SET CONNECTION [ TO | = ] <replaceable class="parameter">connection_name</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>SET CONNECTION</command> sets the <quote>current</quote>
|
|
database connection, which is the one that all commands use
|
|
unless overridden.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">connection_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A database connection name established by
|
|
the <command>CONNECT</command> command.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>DEFAULT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Set the connection to the default connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
EXEC SQL SET CONNECTION TO con2;
|
|
EXEC SQL SET CONNECTION = con1;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>SET CONNECTION</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-connect"/></member>
|
|
<member><xref linkend="ecpg-sql-disconnect"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-set-descriptor">
|
|
<refnamediv>
|
|
<refname>SET DESCRIPTOR</refname>
|
|
<refpurpose>set information in an SQL descriptor area</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
SET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> <replaceable class="parameter">descriptor_header_item</replaceable> = <replaceable>value</replaceable> [, ... ]
|
|
SET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> VALUE <replaceable class="parameter">number</replaceable> <replaceable class="parameter">descriptor_item</replaceable> = <replaceable>value</replaceable> [, ...]
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<command>SET DESCRIPTOR</command> populates an SQL descriptor
|
|
area with values. The descriptor area is then typically used to
|
|
bind parameters in a prepared query execution.
|
|
</para>
|
|
|
|
<para>
|
|
This command has two forms: The first form applies to the
|
|
descriptor <quote>header</quote>, which is independent of a
|
|
particular datum. The second form assigns values to particular
|
|
datums, identified by number.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A descriptor name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_header_item</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A token identifying which header information item to set.
|
|
Only <literal>COUNT</literal>, to set the number of descriptor
|
|
items, is currently supported.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">number</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The number of the descriptor item to set. The count starts at
|
|
1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">descriptor_item</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A token identifying which item of information to set in the
|
|
descriptor. See <xref linkend="ecpg-named-descriptors"/> for a
|
|
list of supported items.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">value</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A value to store into the descriptor item. This can be an SQL
|
|
constant or a host variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
EXEC SQL SET DESCRIPTOR indesc COUNT = 1;
|
|
EXEC SQL SET DESCRIPTOR indesc VALUE 1 DATA = 2;
|
|
EXEC SQL SET DESCRIPTOR indesc VALUE 1 DATA = :val1;
|
|
EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val1, DATA = 'some string';
|
|
EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val2null, DATA = :val2;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>SET DESCRIPTOR</command> is specified in the SQL standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
|
|
<member><xref linkend="ecpg-sql-get-descriptor"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-type">
|
|
<refnamediv>
|
|
<refname>TYPE</refname>
|
|
<refpurpose>define a new data type</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
TYPE <replaceable class="parameter">type_name</replaceable> IS <replaceable class="parameter">ctype</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
The <command>TYPE</command> command defines a new C type. It is
|
|
equivalent to putting a <literal>typedef</literal> into a declare
|
|
section.
|
|
</para>
|
|
|
|
<para>
|
|
This command is only recognized when <command>ecpg</command> is
|
|
run with the <option>-c</option> option.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">type_name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name for the new type. It must be a valid C type name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">ctype</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A C type specification.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
EXEC SQL TYPE customer IS
|
|
struct
|
|
{
|
|
varchar name[50];
|
|
int phone;
|
|
};
|
|
|
|
EXEC SQL TYPE cust_ind IS
|
|
struct ind
|
|
{
|
|
short name_ind;
|
|
short phone_ind;
|
|
};
|
|
|
|
EXEC SQL TYPE c IS char reference;
|
|
EXEC SQL TYPE ind IS union { int integer; short smallint; };
|
|
EXEC SQL TYPE intarray IS int[AMOUNT];
|
|
EXEC SQL TYPE str IS varchar[BUFFERSIZ];
|
|
EXEC SQL TYPE string IS char[11];
|
|
</programlisting>
|
|
|
|
<para>
|
|
Here is an example program that uses <command>EXEC SQL
|
|
TYPE</command>:
|
|
<programlisting>
|
|
EXEC SQL WHENEVER SQLERROR SQLPRINT;
|
|
|
|
EXEC SQL TYPE tt IS
|
|
struct
|
|
{
|
|
varchar v[256];
|
|
int i;
|
|
};
|
|
|
|
EXEC SQL TYPE tt_ind IS
|
|
struct ind {
|
|
short v_ind;
|
|
short i_ind;
|
|
};
|
|
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
tt t;
|
|
tt_ind t_ind;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL CONNECT TO testdb AS con1;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
|
|
EXEC SQL SELECT current_database(), 256 INTO :t:t_ind LIMIT 1;
|
|
|
|
printf("t.v = %s\n", t.v.arr);
|
|
printf("t.i = %d\n", t.i);
|
|
|
|
printf("t_ind.v_ind = %d\n", t_ind.v_ind);
|
|
printf("t_ind.i_ind = %d\n", t_ind.i_ind);
|
|
|
|
EXEC SQL DISCONNECT con1;
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
|
|
The output from this program looks like this:
|
|
<screen>
|
|
t.v = testdb
|
|
t.i = 256
|
|
t_ind.v_ind = 0
|
|
t_ind.i_ind = 0
|
|
</screen>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
The <command>TYPE</command> command is a PostgreSQL extension.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-var">
|
|
<refnamediv>
|
|
<refname>VAR</refname>
|
|
<refpurpose>define a variable</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
VAR <replaceable>varname</replaceable> IS <replaceable>ctype</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
The <command>VAR</command> command assigns a new C data type
|
|
to a host variable. The host variable must be previously
|
|
declared in a declare section.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">varname</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A C variable name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">ctype</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A C type specification.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
Exec sql begin declare section;
|
|
short a;
|
|
exec sql end declare section;
|
|
EXEC SQL VAR a IS int;
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
The <command>VAR</command> command is a PostgreSQL extension.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ecpg-sql-whenever">
|
|
<refnamediv>
|
|
<refname>WHENEVER</refname>
|
|
<refpurpose>specify the action to be taken when an SQL statement causes a specific class condition to be raised</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<synopsis>
|
|
WHENEVER { NOT FOUND | SQLERROR | SQLWARNING } <replaceable class="parameter">action</replaceable>
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Define a behavior which is called on the special cases (Rows not
|
|
found, SQL warnings or errors) in the result of SQL execution.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Parameters</title>
|
|
|
|
<para>
|
|
See <xref linkend="ecpg-whenever"/> for a description of the
|
|
parameters.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
EXEC SQL WHENEVER NOT FOUND CONTINUE;
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
EXEC SQL WHENEVER NOT FOUND DO CONTINUE;
|
|
EXEC SQL WHENEVER SQLWARNING SQLPRINT;
|
|
EXEC SQL WHENEVER SQLWARNING DO warn();
|
|
EXEC SQL WHENEVER SQLERROR sqlprint;
|
|
EXEC SQL WHENEVER SQLERROR CALL print2();
|
|
EXEC SQL WHENEVER SQLERROR DO handle_error("select");
|
|
EXEC SQL WHENEVER SQLERROR DO sqlnotice(NULL, NONO);
|
|
EXEC SQL WHENEVER SQLERROR DO sqlprint();
|
|
EXEC SQL WHENEVER SQLERROR GOTO error_label;
|
|
EXEC SQL WHENEVER SQLERROR STOP;
|
|
</programlisting>
|
|
|
|
<para>
|
|
A typical application is the use of <literal>WHENEVER NOT FOUND
|
|
BREAK</literal> to handle looping through result sets:
|
|
<programlisting>
|
|
int
|
|
main(void)
|
|
{
|
|
EXEC SQL CONNECT TO testdb AS con1;
|
|
EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT;
|
|
EXEC SQL ALLOCATE DESCRIPTOR d;
|
|
EXEC SQL DECLARE cur CURSOR FOR SELECT current_database(), 'hoge', 256;
|
|
EXEC SQL OPEN cur;
|
|
|
|
/* when end of result set reached, break out of while loop */
|
|
EXEC SQL WHENEVER NOT FOUND DO BREAK;
|
|
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d;
|
|
...
|
|
}
|
|
|
|
EXEC SQL CLOSE cur;
|
|
EXEC SQL COMMIT;
|
|
|
|
EXEC SQL DEALLOCATE DESCRIPTOR d;
|
|
EXEC SQL DISCONNECT ALL;
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>WHENEVER</command> is specified in the SQL standard, but
|
|
most of the actions are PostgreSQL extensions.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-informix-compat">
|
|
<title><productname>Informix</productname> Compatibility Mode</title>
|
|
<para>
|
|
<command>ecpg</command> can be run in a so-called <firstterm>Informix compatibility mode</firstterm>. If
|
|
this mode is active, it tries to behave as if it were the <productname>Informix</productname>
|
|
precompiler for <productname>Informix</productname> E/SQL. Generally spoken this will allow you to use
|
|
the dollar sign instead of the <literal>EXEC SQL</literal> primitive to introduce
|
|
embedded SQL commands:
|
|
<programlisting>
|
|
$int j = 3;
|
|
$CONNECT TO :dbname;
|
|
$CREATE TABLE test(i INT PRIMARY KEY, j INT);
|
|
$INSERT INTO test(i, j) VALUES (7, :j);
|
|
$COMMIT;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
There must not be any white space between the <literal>$</literal>
|
|
and a following preprocessor directive, that is,
|
|
<literal>include</literal>, <literal>define</literal>, <literal>ifdef</literal>,
|
|
etc. Otherwise, the preprocessor will parse the token as a host
|
|
variable.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
There are two compatibility modes: <literal>INFORMIX</literal>, <literal>INFORMIX_SE</literal>
|
|
</para>
|
|
<para>
|
|
When linking programs that use this compatibility mode, remember to link
|
|
against <literal>libcompat</literal> that is shipped with ECPG.
|
|
</para>
|
|
<para>
|
|
Besides the previously explained syntactic sugar, the <productname>Informix</productname> compatibility
|
|
mode ports some functions for input, output and transformation of data as
|
|
well as embedded SQL statements known from E/SQL to ECPG.
|
|
</para>
|
|
<para>
|
|
<productname>Informix</productname> compatibility mode is closely connected to the pgtypeslib library
|
|
of ECPG. pgtypeslib maps SQL data types to data types within the C host
|
|
program and most of the additional functions of the <productname>Informix</productname> compatibility
|
|
mode allow you to operate on those C host program types. Note however that
|
|
the extent of the compatibility is limited. It does not try to copy <productname>Informix</productname>
|
|
behavior; it allows you to do more or less the same operations and gives
|
|
you functions that have the same name and the same basic behavior but it is
|
|
no drop-in replacement if you are using <productname>Informix</productname> at the moment. Moreover,
|
|
some of the data types are different. For example,
|
|
<productname>PostgreSQL's</productname> datetime and interval types do not
|
|
know about ranges like for example <literal>YEAR TO MINUTE</literal> so you won't
|
|
find support in ECPG for that either.
|
|
</para>
|
|
|
|
<sect2 id="ecpg-informix-types">
|
|
<title>Additional Types</title>
|
|
<para>
|
|
The Informix-special "string" pseudo-type for storing right-trimmed character string data is now
|
|
supported in Informix-mode without using <literal>typedef</literal>. In fact, in Informix-mode,
|
|
ECPG refuses to process source files that contain <literal>typedef sometype string;</literal>
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
string userid; /* this variable will contain trimmed data */
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
EXEC SQL FETCH MYCUR INTO :userid;
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-informix-statements">
|
|
<title>Additional/Missing Embedded SQL Statements</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>CLOSE DATABASE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This statement closes the current connection. In fact, this is a
|
|
synonym for ECPG's <literal>DISCONNECT CURRENT</literal>:
|
|
<programlisting>
|
|
$CLOSE DATABASE; /* close the current connection */
|
|
EXEC SQL CLOSE DATABASE;
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>FREE cursor_name</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Due to the differences how ECPG works compared to Informix's ESQL/C (i.e., which steps
|
|
are purely grammar transformations and which steps rely on the underlying run-time library)
|
|
there is no <literal>FREE cursor_name</literal> statement in ECPG. This is because in ECPG,
|
|
<literal>DECLARE CURSOR</literal> doesn't translate to a function call into
|
|
the run-time library that uses to the cursor name. This means that there's no run-time
|
|
bookkeeping of SQL cursors in the ECPG run-time library, only in the PostgreSQL server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>FREE statement_name</literal></term>
|
|
<listitem>
|
|
<para>
|
|
<literal>FREE statement_name</literal> is a synonym for <literal>DEALLOCATE PREPARE statement_name</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-informix-sqlda">
|
|
<title>Informix-compatible SQLDA Descriptor Areas</title>
|
|
<para>
|
|
Informix-compatible mode supports a different structure than the one described in
|
|
<xref linkend="ecpg-sqlda-descriptors"/>. See below:
|
|
<programlisting>
|
|
struct sqlvar_compat
|
|
{
|
|
short sqltype;
|
|
int sqllen;
|
|
char *sqldata;
|
|
short *sqlind;
|
|
char *sqlname;
|
|
char *sqlformat;
|
|
short sqlitype;
|
|
short sqlilen;
|
|
char *sqlidata;
|
|
int sqlxid;
|
|
char *sqltypename;
|
|
short sqltypelen;
|
|
short sqlownerlen;
|
|
short sqlsourcetype;
|
|
char *sqlownername;
|
|
int sqlsourceid;
|
|
char *sqlilongdata;
|
|
int sqlflags;
|
|
void *sqlreserved;
|
|
};
|
|
|
|
struct sqlda_compat
|
|
{
|
|
short sqld;
|
|
struct sqlvar_compat *sqlvar;
|
|
char desc_name[19];
|
|
short desc_occ;
|
|
struct sqlda_compat *desc_next;
|
|
void *reserved;
|
|
};
|
|
|
|
typedef struct sqlvar_compat sqlvar_t;
|
|
typedef struct sqlda_compat sqlda_t;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The global properties are:
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqld</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The number of fields in the <literal>SQLDA</literal> descriptor.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlvar</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Pointer to the per-field properties.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>desc_name</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Unused, filled with zero-bytes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>desc_occ</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Size of the allocated structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>desc_next</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Pointer to the next SQLDA structure if the result set contains more than one record.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>reserved</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Unused pointer, contains NULL. Kept for Informix-compatibility.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
The per-field properties are below, they are stored in the <literal>sqlvar</literal> array:
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqltype</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Type of the field. Constants are in <literal>sqltypes.h</literal>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqllen</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Length of the field data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqldata</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Pointer to the field data. The pointer is of <literal>char *</literal> type,
|
|
the data pointed by it is in a binary format. Example:
|
|
<programlisting>
|
|
int intval;
|
|
|
|
switch (sqldata->sqlvar[i].sqltype)
|
|
{
|
|
case SQLINTEGER:
|
|
intval = *(int *)sqldata->sqlvar[i].sqldata;
|
|
break;
|
|
...
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlind</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Pointer to the NULL indicator. If returned by DESCRIBE or FETCH then it's always a valid pointer.
|
|
If used as input for <literal>EXECUTE ... USING sqlda;</literal> then NULL-pointer value means
|
|
that the value for this field is non-NULL. Otherwise a valid pointer and <literal>sqlitype</literal>
|
|
has to be properly set. Example:
|
|
<programlisting>
|
|
if (*(int2 *)sqldata->sqlvar[i].sqlind != 0)
|
|
printf("value is NULL\n");
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlname</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Name of the field. 0-terminated string.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlformat</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Reserved in Informix, value of <xref linkend="libpq-PQfformat"/> for the field.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlitype</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Type of the NULL indicator data. It's always SQLSMINT when returning data from the server.
|
|
When the <literal>SQLDA</literal> is used for a parameterized query, the data is treated
|
|
according to the set type.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlilen</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Length of the NULL indicator data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlxid</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Extended type of the field, result of <xref linkend="libpq-PQftype"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqltypename</literal></term>
|
|
<term><literal>sqltypelen</literal></term>
|
|
<term><literal>sqlownerlen</literal></term>
|
|
<term><literal>sqlsourcetype</literal></term>
|
|
<term><literal>sqlownername</literal></term>
|
|
<term><literal>sqlsourceid</literal></term>
|
|
<term><literal>sqlflags</literal></term>
|
|
<term><literal>sqlreserved</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Unused.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sqlilongdata</literal></term>
|
|
<listitem>
|
|
<para>
|
|
It equals to <literal>sqldata</literal> if <literal>sqllen</literal> is larger than 32kB.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
Example:
|
|
<programlisting>
|
|
EXEC SQL INCLUDE sqlda.h;
|
|
|
|
sqlda_t *sqlda; /* This doesn't need to be under embedded DECLARE SECTION */
|
|
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
char *prep_stmt = "select * from table1";
|
|
int i;
|
|
EXEC SQL END DECLARE SECTION;
|
|
|
|
...
|
|
|
|
EXEC SQL PREPARE mystmt FROM :prep_stmt;
|
|
|
|
EXEC SQL DESCRIBE mystmt INTO sqlda;
|
|
|
|
printf("# of fields: %d\n", sqlda->sqld);
|
|
for (i = 0; i < sqlda->sqld; i++)
|
|
printf("field %d: \"%s\"\n", sqlda->sqlvar[i]->sqlname);
|
|
|
|
EXEC SQL DECLARE mycursor CURSOR FOR mystmt;
|
|
EXEC SQL OPEN mycursor;
|
|
EXEC SQL WHENEVER NOT FOUND GOTO out;
|
|
|
|
while (1)
|
|
{
|
|
EXEC SQL FETCH mycursor USING sqlda;
|
|
}
|
|
|
|
EXEC SQL CLOSE mycursor;
|
|
|
|
free(sqlda); /* The main structure is all to be free(),
|
|
* sqlda and sqlda->sqlvar is in one allocated area */
|
|
</programlisting>
|
|
For more information, see the <literal>sqlda.h</literal> header and the
|
|
<literal>src/interfaces/ecpg/test/compat_informix/sqlda.pgc</literal> regression test.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-informix-functions">
|
|
<title>Additional Functions</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>decadd</function></term>
|
|
<listitem>
|
|
<para>
|
|
Add two decimal type values.
|
|
<synopsis>
|
|
int decadd(decimal *arg1, decimal *arg2, decimal *sum);
|
|
</synopsis>
|
|
The function receives a pointer to the first operand of type decimal
|
|
(<literal>arg1</literal>), a pointer to the second operand of type decimal
|
|
(<literal>arg2</literal>) and a pointer to a value of type decimal that will
|
|
contain the sum (<literal>sum</literal>). On success, the function returns 0.
|
|
<symbol>ECPG_INFORMIX_NUM_OVERFLOW</symbol> is returned in case of overflow and
|
|
<symbol>ECPG_INFORMIX_NUM_UNDERFLOW</symbol> in case of underflow. -1 is returned for
|
|
other failures and <varname>errno</varname> is set to the respective <varname>errno</varname> number of the
|
|
pgtypeslib.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccmp</function></term>
|
|
<listitem>
|
|
<para>
|
|
Compare two variables of type decimal.
|
|
<synopsis>
|
|
int deccmp(decimal *arg1, decimal *arg2);
|
|
</synopsis>
|
|
The function receives a pointer to the first decimal value
|
|
(<literal>arg1</literal>), a pointer to the second decimal value
|
|
(<literal>arg2</literal>) and returns an integer value that indicates which is
|
|
the bigger value.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
1, if the value that <literal>arg1</literal> points to is bigger than the
|
|
value that <literal>var2</literal> points to
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
-1, if the value that <literal>arg1</literal> points to is smaller than the
|
|
value that <literal>arg2</literal> points to </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
0, if the value that <literal>arg1</literal> points to and the value that
|
|
<literal>arg2</literal> points to are equal
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccopy</function></term>
|
|
<listitem>
|
|
<para>
|
|
Copy a decimal value.
|
|
<synopsis>
|
|
void deccopy(decimal *src, decimal *target);
|
|
</synopsis>
|
|
The function receives a pointer to the decimal value that should be
|
|
copied as the first argument (<literal>src</literal>) and a pointer to the
|
|
target structure of type decimal (<literal>target</literal>) as the second
|
|
argument.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccvasc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a value from its ASCII representation into a decimal type.
|
|
<synopsis>
|
|
int deccvasc(char *cp, int len, decimal *np);
|
|
</synopsis>
|
|
The function receives a pointer to string that contains the string
|
|
representation of the number to be converted (<literal>cp</literal>) as well
|
|
as its length <literal>len</literal>. <literal>np</literal> is a pointer to the
|
|
decimal value that saves the result of the operation.
|
|
</para>
|
|
<para>
|
|
Valid formats are for example:
|
|
<literal>-2</literal>,
|
|
<literal>.794</literal>,
|
|
<literal>+3.44</literal>,
|
|
<literal>592.49E07</literal> or
|
|
<literal>-32.84e-4</literal>.
|
|
</para>
|
|
<para>
|
|
The function returns 0 on success. If overflow or underflow occurred,
|
|
<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal> is returned. If the ASCII
|
|
representation could not be parsed,
|
|
<literal>ECPG_INFORMIX_BAD_NUMERIC</literal> is returned or
|
|
<literal>ECPG_INFORMIX_BAD_EXPONENT</literal> if this problem occurred while
|
|
parsing the exponent.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccvdbl</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a value of type double to a value of type decimal.
|
|
<synopsis>
|
|
int deccvdbl(double dbl, decimal *np);
|
|
</synopsis>
|
|
The function receives the variable of type double that should be
|
|
converted as its first argument (<literal>dbl</literal>). As the second
|
|
argument (<literal>np</literal>), the function receives a pointer to the
|
|
decimal variable that should hold the result of the operation.
|
|
</para>
|
|
<para>
|
|
The function returns 0 on success and a negative value if the
|
|
conversion failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccvint</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a value of type int to a value of type decimal.
|
|
<synopsis>
|
|
int deccvint(int in, decimal *np);
|
|
</synopsis>
|
|
The function receives the variable of type int that should be
|
|
converted as its first argument (<literal>in</literal>). As the second
|
|
argument (<literal>np</literal>), the function receives a pointer to the
|
|
decimal variable that should hold the result of the operation.
|
|
</para>
|
|
<para>
|
|
The function returns 0 on success and a negative value if the
|
|
conversion failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccvlong</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a value of type long to a value of type decimal.
|
|
<synopsis>
|
|
int deccvlong(long lng, decimal *np);
|
|
</synopsis>
|
|
The function receives the variable of type long that should be
|
|
converted as its first argument (<literal>lng</literal>). As the second
|
|
argument (<literal>np</literal>), the function receives a pointer to the
|
|
decimal variable that should hold the result of the operation.
|
|
</para>
|
|
<para>
|
|
The function returns 0 on success and a negative value if the
|
|
conversion failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>decdiv</function></term>
|
|
<listitem>
|
|
<para>
|
|
Divide two variables of type decimal.
|
|
<synopsis>
|
|
int decdiv(decimal *n1, decimal *n2, decimal *result);
|
|
</synopsis>
|
|
The function receives pointers to the variables that are the first
|
|
(<literal>n1</literal>) and the second (<literal>n2</literal>) operands and
|
|
calculates <literal>n1</literal>/<literal>n2</literal>. <literal>result</literal> is a
|
|
pointer to the variable that should hold the result of the operation.
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the division fails.
|
|
If overflow or underflow occurred, the function returns
|
|
<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal> respectively. If an attempt to
|
|
divide by zero is observed, the function returns
|
|
<literal>ECPG_INFORMIX_DIVIDE_ZERO</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>decmul</function></term>
|
|
<listitem>
|
|
<para>
|
|
Multiply two decimal values.
|
|
<synopsis>
|
|
int decmul(decimal *n1, decimal *n2, decimal *result);
|
|
</synopsis>
|
|
The function receives pointers to the variables that are the first
|
|
(<literal>n1</literal>) and the second (<literal>n2</literal>) operands and
|
|
calculates <literal>n1</literal>*<literal>n2</literal>. <literal>result</literal> is a
|
|
pointer to the variable that should hold the result of the operation.
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the multiplication
|
|
fails. If overflow or underflow occurred, the function returns
|
|
<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal> respectively.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>decsub</function></term>
|
|
<listitem>
|
|
<para>
|
|
Subtract one decimal value from another.
|
|
<synopsis>
|
|
int decsub(decimal *n1, decimal *n2, decimal *result);
|
|
</synopsis>
|
|
The function receives pointers to the variables that are the first
|
|
(<literal>n1</literal>) and the second (<literal>n2</literal>) operands and
|
|
calculates <literal>n1</literal>-<literal>n2</literal>. <literal>result</literal> is a
|
|
pointer to the variable that should hold the result of the operation.
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the subtraction
|
|
fails. If overflow or underflow occurred, the function returns
|
|
<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal> respectively.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectoasc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type decimal to its ASCII representation in a C
|
|
char* string.
|
|
<synopsis>
|
|
int dectoasc(decimal *np, char *cp, int len, int right)
|
|
</synopsis>
|
|
The function receives a pointer to a variable of type decimal
|
|
(<literal>np</literal>) that it converts to its textual representation.
|
|
<literal>cp</literal> is the buffer that should hold the result of the
|
|
operation. The parameter <literal>right</literal> specifies, how many digits
|
|
right of the decimal point should be included in the output. The result
|
|
will be rounded to this number of decimal digits. Setting
|
|
<literal>right</literal> to -1 indicates that all available decimal digits
|
|
should be included in the output. If the length of the output buffer,
|
|
which is indicated by <literal>len</literal> is not sufficient to hold the
|
|
textual representation including the trailing zero byte, only a
|
|
single <literal>*</literal> character is stored in the result and -1 is
|
|
returned.
|
|
</para>
|
|
<para>
|
|
The function returns either -1 if the buffer <literal>cp</literal> was too
|
|
small or <literal>ECPG_INFORMIX_OUT_OF_MEMORY</literal> if memory was
|
|
exhausted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectodbl</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type decimal to a double.
|
|
<synopsis>
|
|
int dectodbl(decimal *np, double *dblp);
|
|
</synopsis>
|
|
The function receives a pointer to the decimal value to convert
|
|
(<literal>np</literal>) and a pointer to the double variable that
|
|
should hold the result of the operation (<literal>dblp</literal>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the conversion
|
|
failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectoint</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable to type decimal to an integer.
|
|
<synopsis>
|
|
int dectoint(decimal *np, int *ip);
|
|
</synopsis>
|
|
The function receives a pointer to the decimal value to convert
|
|
(<literal>np</literal>) and a pointer to the integer variable that
|
|
should hold the result of the operation (<literal>ip</literal>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the conversion
|
|
failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</literal>
|
|
is returned.
|
|
</para>
|
|
<para>
|
|
Note that the ECPG implementation differs from the <productname>Informix</productname>
|
|
implementation. <productname>Informix</productname> limits an integer to the range from -32767 to
|
|
32767, while the limits in the ECPG implementation depend on the
|
|
architecture (<literal>-INT_MAX .. INT_MAX</literal>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectolong</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable to type decimal to a long integer.
|
|
<synopsis>
|
|
int dectolong(decimal *np, long *lngp);
|
|
</synopsis>
|
|
The function receives a pointer to the decimal value to convert
|
|
(<literal>np</literal>) and a pointer to the long variable that
|
|
should hold the result of the operation (<literal>lngp</literal>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the conversion
|
|
failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</literal>
|
|
is returned.
|
|
</para>
|
|
<para>
|
|
Note that the ECPG implementation differs from the <productname>Informix</productname>
|
|
implementation. <productname>Informix</productname> limits a long integer to the range from
|
|
-2,147,483,647 to 2,147,483,647, while the limits in the ECPG
|
|
implementation depend on the architecture (<literal>-LONG_MAX ..
|
|
LONG_MAX</literal>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rdatestr</function></term>
|
|
<listitem>
|
|
<para>
|
|
Converts a date to a C char* string.
|
|
<synopsis>
|
|
int rdatestr(date d, char *str);
|
|
</synopsis>
|
|
The function receives two arguments, the first one is the date to
|
|
convert (<literal>d</literal>) and the second one is a pointer to the target
|
|
string. The output format is always <literal>yyyy-mm-dd</literal>, so you need
|
|
to allocate at least 11 bytes (including the zero-byte terminator) for the
|
|
string.
|
|
</para>
|
|
<para>
|
|
The function returns 0 on success and a negative value in case of
|
|
error.
|
|
</para>
|
|
<para>
|
|
Note that ECPG's implementation differs from the <productname>Informix</productname>
|
|
implementation. In <productname>Informix</productname> the format can be influenced by setting
|
|
environment variables. In ECPG however, you cannot change the output
|
|
format.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rstrdate</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parse the textual representation of a date.
|
|
<synopsis>
|
|
int rstrdate(char *str, date *d);
|
|
</synopsis>
|
|
The function receives the textual representation of the date to convert
|
|
(<literal>str</literal>) and a pointer to a variable of type date
|
|
(<literal>d</literal>). This function does not allow you to specify a format
|
|
mask. It uses the default format mask of <productname>Informix</productname> which is
|
|
<literal>mm/dd/yyyy</literal>. Internally, this function is implemented by
|
|
means of <function>rdefmtdate</function>. Therefore, <function>rstrdate</function> is
|
|
not faster and if you have the choice you should opt for
|
|
<function>rdefmtdate</function> which allows you to specify the format mask
|
|
explicitly.
|
|
</para>
|
|
<para>
|
|
The function returns the same values as <function>rdefmtdate</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rtoday</function></term>
|
|
<listitem>
|
|
<para>
|
|
Get the current date.
|
|
<synopsis>
|
|
void rtoday(date *d);
|
|
</synopsis>
|
|
The function receives a pointer to a date variable (<literal>d</literal>)
|
|
that it sets to the current date.
|
|
</para>
|
|
<para>
|
|
Internally this function uses the <xref linkend="pgtypesdatetoday"/>
|
|
function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rjulmdy</function></term>
|
|
<listitem>
|
|
<para>
|
|
Extract the values for the day, the month and the year from a variable
|
|
of type date.
|
|
<synopsis>
|
|
int rjulmdy(date d, short mdy[3]);
|
|
</synopsis>
|
|
The function receives the date <literal>d</literal> and a pointer to an array
|
|
of 3 short integer values <literal>mdy</literal>. The variable name indicates
|
|
the sequential order: <literal>mdy[0]</literal> will be set to contain the
|
|
number of the month, <literal>mdy[1]</literal> will be set to the value of the
|
|
day and <literal>mdy[2]</literal> will contain the year.
|
|
</para>
|
|
<para>
|
|
The function always returns 0 at the moment.
|
|
</para>
|
|
<para>
|
|
Internally the function uses the <xref linkend="pgtypesdatejulmdy"/>
|
|
function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rdefmtdate</function></term>
|
|
<listitem>
|
|
<para>
|
|
Use a format mask to convert a character string to a value of type
|
|
date.
|
|
<synopsis>
|
|
int rdefmtdate(date *d, char *fmt, char *str);
|
|
</synopsis>
|
|
The function receives a pointer to the date value that should hold the
|
|
result of the operation (<literal>d</literal>), the format mask to use for
|
|
parsing the date (<literal>fmt</literal>) and the C char* string containing
|
|
the textual representation of the date (<literal>str</literal>). The textual
|
|
representation is expected to match the format mask. However you do not
|
|
need to have a 1:1 mapping of the string to the format mask. The
|
|
function only analyzes the sequential order and looks for the literals
|
|
<literal>yy</literal> or <literal>yyyy</literal> that indicate the
|
|
position of the year, <literal>mm</literal> to indicate the position of
|
|
the month and <literal>dd</literal> to indicate the position of the
|
|
day.
|
|
</para>
|
|
<para>
|
|
The function returns the following values:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
0 - The function terminated successfully.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_ENOSHORTDATE</literal> - The date does not contain
|
|
delimiters between day, month and year. In this case the input
|
|
string must be exactly 6 or 8 bytes long but isn't.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_ENOTDMY</literal> - The format string did not
|
|
correctly indicate the sequential order of year, month and day.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_BAD_DAY</literal> - The input string does not
|
|
contain a valid day.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_BAD_MONTH</literal> - The input string does not
|
|
contain a valid month.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_BAD_YEAR</literal> - The input string does not
|
|
contain a valid year.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Internally this function is implemented to use the <xref
|
|
linkend="pgtypesdatedefmtasc"/> function. See the reference there for a
|
|
table of example input.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rfmtdate</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a variable of type date to its textual representation using a
|
|
format mask.
|
|
<synopsis>
|
|
int rfmtdate(date d, char *fmt, char *str);
|
|
</synopsis>
|
|
The function receives the date to convert (<literal>d</literal>), the format
|
|
mask (<literal>fmt</literal>) and the string that will hold the textual
|
|
representation of the date (<literal>str</literal>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if an error occurred.
|
|
</para>
|
|
<para>
|
|
Internally this function uses the <xref linkend="pgtypesdatefmtasc"/>
|
|
function, see the reference there for examples.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rmdyjul</function></term>
|
|
<listitem>
|
|
<para>
|
|
Create a date value from an array of 3 short integers that specify the
|
|
day, the month and the year of the date.
|
|
<synopsis>
|
|
int rmdyjul(short mdy[3], date *d);
|
|
</synopsis>
|
|
The function receives the array of the 3 short integers
|
|
(<literal>mdy</literal>) and a pointer to a variable of type date that should
|
|
hold the result of the operation.
|
|
</para>
|
|
<para>
|
|
Currently the function returns always 0.
|
|
</para>
|
|
<para>
|
|
Internally the function is implemented to use the function <xref
|
|
linkend="pgtypesdatemdyjul"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rdayofweek</function></term>
|
|
<listitem>
|
|
<para>
|
|
Return a number representing the day of the week for a date value.
|
|
<synopsis>
|
|
int rdayofweek(date d);
|
|
</synopsis>
|
|
The function receives the date variable <literal>d</literal> as its only
|
|
argument and returns an integer that indicates the day of the week for
|
|
this date.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
0 - Sunday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
1 - Monday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
2 - Tuesday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
3 - Wednesday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
4 - Thursday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
5 - Friday
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
6 - Saturday
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Internally the function is implemented to use the function <xref
|
|
linkend="pgtypesdatedayofweek"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dtcurrent</function></term>
|
|
<listitem>
|
|
<para>
|
|
Retrieve the current timestamp.
|
|
<synopsis>
|
|
void dtcurrent(timestamp *ts);
|
|
</synopsis>
|
|
The function retrieves the current timestamp and saves it into the
|
|
timestamp variable that <literal>ts</literal> points to.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dtcvasc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parses a timestamp from its textual representation
|
|
into a timestamp variable.
|
|
<synopsis>
|
|
int dtcvasc(char *str, timestamp *ts);
|
|
</synopsis>
|
|
The function receives the string to parse (<literal>str</literal>) and a
|
|
pointer to the timestamp variable that should hold the result of the
|
|
operation (<literal>ts</literal>).
|
|
</para>
|
|
<para>
|
|
The function returns 0 on success and a negative value in case of
|
|
error.
|
|
</para>
|
|
<para>
|
|
Internally this function uses the <xref
|
|
linkend="pgtypestimestampfromasc"/> function. See the reference there
|
|
for a table with example inputs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dtcvfmtasc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Parses a timestamp from its textual representation
|
|
using a format mask into a timestamp variable.
|
|
<synopsis>
|
|
dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
|
|
</synopsis>
|
|
The function receives the string to parse (<literal>inbuf</literal>), the
|
|
format mask to use (<literal>fmtstr</literal>) and a pointer to the timestamp
|
|
variable that should hold the result of the operation
|
|
(<literal>dtvalue</literal>).
|
|
</para>
|
|
<para>
|
|
This function is implemented by means of the <xref
|
|
linkend="pgtypestimestampdefmtasc"/> function. See the documentation
|
|
there for a list of format specifiers that can be used.
|
|
</para>
|
|
<para>
|
|
The function returns 0 on success and a negative value in case of
|
|
error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dtsub</function></term>
|
|
<listitem>
|
|
<para>
|
|
Subtract one timestamp from another and return a variable of type
|
|
interval.
|
|
<synopsis>
|
|
int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
|
|
</synopsis>
|
|
The function will subtract the timestamp variable that <literal>ts2</literal>
|
|
points to from the timestamp variable that <literal>ts1</literal> points to
|
|
and will store the result in the interval variable that <literal>iv</literal>
|
|
points to.
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dttoasc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a timestamp variable to a C char* string.
|
|
<synopsis>
|
|
int dttoasc(timestamp *ts, char *output);
|
|
</synopsis>
|
|
The function receives a pointer to the timestamp variable to convert
|
|
(<literal>ts</literal>) and the string that should hold the result of the
|
|
operation (<literal>output</literal>). It converts <literal>ts</literal> to its
|
|
textual representation according to the SQL standard, which is
|
|
be <literal>YYYY-MM-DD HH:MM:SS</literal>.
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dttofmtasc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a timestamp variable to a C char* using a format mask.
|
|
<synopsis>
|
|
int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
|
|
</synopsis>
|
|
The function receives a pointer to the timestamp to convert as its
|
|
first argument (<literal>ts</literal>), a pointer to the output buffer
|
|
(<literal>output</literal>), the maximal length that has been allocated for
|
|
the output buffer (<literal>str_len</literal>) and the format mask to
|
|
use for the conversion (<literal>fmtstr</literal>).
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
<para>
|
|
Internally, this function uses the <xref
|
|
linkend="pgtypestimestampfmtasc"/> function. See the reference there for
|
|
information on what format mask specifiers can be used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>intoasc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert an interval variable to a C char* string.
|
|
<synopsis>
|
|
int intoasc(interval *i, char *str);
|
|
</synopsis>
|
|
The function receives a pointer to the interval variable to convert
|
|
(<literal>i</literal>) and the string that should hold the result of the
|
|
operation (<literal>str</literal>). It converts <literal>i</literal> to its
|
|
textual representation according to the SQL standard, which is
|
|
be <literal>YYYY-MM-DD HH:MM:SS</literal>.
|
|
</para>
|
|
<para>
|
|
Upon success, the function returns 0 and a negative value if an
|
|
error occurred.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rfmtlong</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a long integer value to its textual representation using a
|
|
format mask.
|
|
<synopsis>
|
|
int rfmtlong(long lng_val, char *fmt, char *outbuf);
|
|
</synopsis>
|
|
The function receives the long value <literal>lng_val</literal>, the format
|
|
mask <literal>fmt</literal> and a pointer to the output buffer
|
|
<literal>outbuf</literal>. It converts the long value according to the format
|
|
mask to its textual representation.
|
|
</para>
|
|
<para>
|
|
The format mask can be composed of the following format specifying
|
|
characters:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>*</literal> (asterisk) - if this position would be blank
|
|
otherwise, fill it with an asterisk.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>&</literal> (ampersand) - if this position would be
|
|
blank otherwise, fill it with a zero.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>#</literal> - turn leading zeroes into blanks.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal><</literal> - left-justify the number in the string.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>,</literal> (comma) - group numbers of four or more digits
|
|
into groups of three digits separated by a comma.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>.</literal> (period) - this character separates the
|
|
whole-number part of the number from the fractional part.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>-</literal> (minus) - the minus sign appears if the number
|
|
is a negative value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>+</literal> (plus) - the plus sign appears if the number is
|
|
a positive value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>(</literal> - this replaces the minus sign in front of the
|
|
negative number. The minus sign will not appear.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>)</literal> - this character replaces the minus and is
|
|
printed behind the negative value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>$</literal> - the currency symbol.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rupshift</function></term>
|
|
<listitem>
|
|
<para>
|
|
Convert a string to upper case.
|
|
<synopsis>
|
|
void rupshift(char *str);
|
|
</synopsis>
|
|
The function receives a pointer to the string and transforms every
|
|
lower case character to upper case.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>byleng</function></term>
|
|
<listitem>
|
|
<para>
|
|
Return the number of characters in a string without counting trailing
|
|
blanks.
|
|
<synopsis>
|
|
int byleng(char *str, int len);
|
|
</synopsis>
|
|
The function expects a fixed-length string as its first argument
|
|
(<literal>str</literal>) and its length as its second argument
|
|
(<literal>len</literal>). It returns the number of significant characters,
|
|
that is the length of the string without trailing blanks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>ldchar</function></term>
|
|
<listitem>
|
|
<para>
|
|
Copy a fixed-length string into a null-terminated string.
|
|
<synopsis>
|
|
void ldchar(char *src, int len, char *dest);
|
|
</synopsis>
|
|
The function receives the fixed-length string to copy
|
|
(<literal>src</literal>), its length (<literal>len</literal>) and a pointer to the
|
|
destination memory (<literal>dest</literal>). Note that you need to reserve at
|
|
least <literal>len+1</literal> bytes for the string that <literal>dest</literal>
|
|
points to. The function copies at most <literal>len</literal> bytes to the new
|
|
location (less if the source string has trailing blanks) and adds the
|
|
null-terminator.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rgetmsg</function></term>
|
|
<listitem>
|
|
<para>
|
|
<synopsis>
|
|
int rgetmsg(int msgnum, char *s, int maxsize);
|
|
</synopsis>
|
|
This function exists but is not implemented at the moment!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rtypalign</function></term>
|
|
<listitem>
|
|
<para>
|
|
<synopsis>
|
|
int rtypalign(int offset, int type);
|
|
</synopsis>
|
|
This function exists but is not implemented at the moment!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rtypmsize</function></term>
|
|
<listitem>
|
|
<para>
|
|
<synopsis>
|
|
int rtypmsize(int type, int len);
|
|
</synopsis>
|
|
This function exists but is not implemented at the moment!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rtypwidth</function></term>
|
|
<listitem>
|
|
<para>
|
|
<synopsis>
|
|
int rtypwidth(int sqltype, int sqllen);
|
|
</synopsis>
|
|
This function exists but is not implemented at the moment!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="rsetnull">
|
|
<term><function>rsetnull</function></term>
|
|
<listitem>
|
|
<para>
|
|
Set a variable to NULL.
|
|
<synopsis>
|
|
int rsetnull(int t, char *ptr);
|
|
</synopsis>
|
|
The function receives an integer that indicates the type of the
|
|
variable and a pointer to the variable itself that is cast to a C
|
|
char* pointer.
|
|
</para>
|
|
<para>
|
|
The following types exist:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>CCHARTYPE</literal> - For a variable of type <type>char</type> or <type>char*</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CSHORTTYPE</literal> - For a variable of type <type>short int</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CINTTYPE</literal> - For a variable of type <type>int</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CBOOLTYPE</literal> - For a variable of type <type>boolean</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CFLOATTYPE</literal> - For a variable of type <type>float</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CLONGTYPE</literal> - For a variable of type <type>long</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CDOUBLETYPE</literal> - For a variable of type <type>double</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CDECIMALTYPE</literal> - For a variable of type <type>decimal</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CDATETYPE</literal> - For a variable of type <type>date</type>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>CDTIMETYPE</literal> - For a variable of type <type>timestamp</type>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example of a call to this function:
|
|
<programlisting><![CDATA[
|
|
$char c[] = "abc ";
|
|
$short s = 17;
|
|
$int i = -74874;
|
|
|
|
rsetnull(CCHARTYPE, (char *) c);
|
|
rsetnull(CSHORTTYPE, (char *) &s);
|
|
rsetnull(CINTTYPE, (char *) &i);
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>risnull</function></term>
|
|
<listitem>
|
|
<para>
|
|
Test if a variable is NULL.
|
|
<synopsis>
|
|
int risnull(int t, char *ptr);
|
|
</synopsis>
|
|
The function receives the type of the variable to test (<literal>t</literal>)
|
|
as well a pointer to this variable (<literal>ptr</literal>). Note that the
|
|
latter needs to be cast to a char*. See the function <xref
|
|
linkend="rsetnull"/> for a list of possible variable types.
|
|
</para>
|
|
<para>
|
|
Here is an example of how to use this function:
|
|
<programlisting><![CDATA[
|
|
$char c[] = "abc ";
|
|
$short s = 17;
|
|
$int i = -74874;
|
|
|
|
risnull(CCHARTYPE, (char *) c);
|
|
risnull(CSHORTTYPE, (char *) &s);
|
|
risnull(CINTTYPE, (char *) &i);
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ecpg-informix-constants">
|
|
<title>Additional Constants</title>
|
|
<para>
|
|
Note that all constants here describe errors and all of them are defined
|
|
to represent negative values. In the descriptions of the different
|
|
constants you can also find the value that the constants represent in the
|
|
current implementation. However you should not rely on this number. You can
|
|
however rely on the fact all of them are defined to represent negative
|
|
values.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_NUM_OVERFLOW</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if an overflow occurred in a
|
|
calculation. Internally it is defined as -1200 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if an underflow occurred in a calculation.
|
|
Internally it is defined as -1201 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_DIVIDE_ZERO</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if an attempt to divide by zero is
|
|
observed. Internally it is defined as -1202 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_YEAR</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a bad value for a year was found while
|
|
parsing a date. Internally it is defined as -1204 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_MONTH</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a bad value for a month was found while
|
|
parsing a date. Internally it is defined as -1205 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_DAY</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a bad value for a day was found while
|
|
parsing a date. Internally it is defined as -1206 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_ENOSHORTDATE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a parsing routine needs a short date
|
|
representation but did not get the date string in the right length.
|
|
Internally it is defined as -1209 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_DATE_CONVERT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if an error occurred during date
|
|
formatting. Internally it is defined as -1210 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_OUT_OF_MEMORY</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if memory was exhausted during
|
|
their operation. Internally it is defined as -1211 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_ENOTDMY</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a parsing routine was supposed to get a
|
|
format mask (like <literal>mmddyy</literal>) but not all fields were listed
|
|
correctly. Internally it is defined as -1212 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_NUMERIC</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value either if a parsing routine cannot parse
|
|
the textual representation for a numeric value because it contains
|
|
errors or if a routine cannot complete a calculation involving numeric
|
|
variables because at least one of the numeric variables is invalid.
|
|
Internally it is defined as -1213 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_EXPONENT</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a parsing routine cannot parse
|
|
an exponent. Internally it is defined as -1216 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_DATE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a parsing routine cannot parse
|
|
a date. Internally it is defined as -1218 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_EXTRA_CHARS</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a parsing routine is passed extra
|
|
characters it cannot parse. Internally it is defined as -1264 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</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</literal> 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</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
An <type>enum</type> 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</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
An <type>enum</type> 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> command is used at the position of the <command>OPEN</command> 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 might
|
|
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><![CDATA[
|
|
/* Processed by ecpg (2.6.0) */
|
|
/* These two include files are added by the preprocessor */
|
|
#include <ecpgtype.h>;
|
|
#include <ecpglib.h>;
|
|
|
|
/* 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,&(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>
|
|
(The indentation here is added for readability and not
|
|
something the preprocessor does.)
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|