mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-10-02 16:51:15 +02:00
4989 lines
161 KiB
Plaintext
4989 lines
161 KiB
Plaintext
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.86 2008/06/12 19:15:40 momjian Exp $ -->
|
|
|
|
<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
|
|
is first passed through the embedded SQL preprocessor, which converts it
|
|
to an ordinary C program, and afterwards it can be processed by a C
|
|
compiler.
|
|
</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</> 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. Embedded
|
|
<acronym>SQL</acronym> statements follow the case-sensitivity rules
|
|
of normal <acronym>SQL</acronym> code, and not those of C.
|
|
</para>
|
|
|
|
<para>
|
|
The following sections explain all the embedded SQL statements.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-connect">
|
|
<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</><optional>@<replaceable>hostname</></optional><optional>:<replaceable>port</></optional></literal>
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<literal>tcp:postgresql://<replaceable>hostname</><optional>:<replaceable>port</></optional><optional>/<replaceable>dbname</></optional><optional>?<replaceable>options</></optional></literal>
|
|
</simpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<simpara>
|
|
<literal>unix:postgresql://<replaceable>hostname</><optional>:<replaceable>port</></optional><optional>/<replaceable>dbname</></optional><optional>?<replaceable>options</></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>
|
|
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>
|
|
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";
|
|
EXEC SQL END DECLARE SECTION;
|
|
...
|
|
EXEC SQL CONNECT TO :target USER :user;
|
|
</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>
|
|
</sect1>
|
|
|
|
<sect1 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>
|
|
</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>
|
|
|
|
<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>
|
|
Single-row select:
|
|
<programlisting>
|
|
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
|
|
</programlisting>
|
|
</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>
|
|
Updates:
|
|
<programlisting>
|
|
EXEC SQL UPDATE foo
|
|
SET ascii = 'foobar'
|
|
WHERE number = 9999;
|
|
EXEC SQL COMMIT;
|
|
</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>
|
|
|
|
<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>libpq</> behavior) via the <option>-t</option> command-line
|
|
option to <command>ecpg</command> (see below) 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>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-set-connection">
|
|
<title>Choosing a Connection</title>
|
|
|
|
<para>
|
|
The SQL statements shown in the previous section are 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. If each thread uses its own connection,
|
|
you will need to use the AT clause to specify which connection the thread will use.
|
|
</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. It is not thread-aware.
|
|
</para>
|
|
</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>
|
|
|
|
<sect2>
|
|
<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 statements 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>
|
|
<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</> section. Otherwise the preprocessor cannot
|
|
handle these types since it does not know the definition.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Different types of host variables</title>
|
|
<para>
|
|
As a host variable you can also use arrays, typedefs, structs and
|
|
pointers. Moreover there are special types of host variables that exist
|
|
only in ECPG.
|
|
</para>
|
|
|
|
<para>
|
|
A few examples on host variables:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Arrays</term>
|
|
<listitem>
|
|
<para>
|
|
One of the most common uses of an array declaration is probably the
|
|
allocation of a char array as in:
|
|
<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 for 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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Typedefs</term>
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Pointers</term>
|
|
<listitem>
|
|
<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>
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
int *intp;
|
|
char **charp;
|
|
EXEC SQL END DECLARE SECTION;
|
|
</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Special types of variables</term>
|
|
<listitem>
|
|
<para>
|
|
ECPG contains some special types that help you to interact easily with
|
|
data from the SQL server. For example it has implemented support for
|
|
the <type>varchar</>, <type>numeric</>, <type>date</>, <type>timestamp</>, and <type>interval</> types.
|
|
<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 timestamp for example.
|
|
</para>
|
|
<para>
|
|
The special type <type>VARCHAR</type>
|
|
is converted into a named <type>struct</> 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>
|
|
This structure is suitable for interfacing with SQL datums of type
|
|
<type>varchar</type>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title><command>SELECT INTO</command> and <command>FETCH INTO</command></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.
|
|
</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>
|
|
|
|
<para>
|
|
Both of these methods only allow retrieving one row at a time. If
|
|
you need to process result sets that potentially contain more than
|
|
one row, you need to use a cursor, as shown in the second example.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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>
|
|
</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>
|
|
|
|
<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>
|
|
You cannot execute statements that retrieve data (e.g.,
|
|
<command>SELECT</command>) this way.
|
|
</para>
|
|
|
|
<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>
|
|
If the statement you are executing returns values, then add an
|
|
<literal>INTO</literal> clause:
|
|
<programlisting>
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
const char *stmt = "SELECT a, b, c FROM test1 WHERE a > ?";
|
|
int v1, v2;
|
|
VARCHAR v3;
|
|
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>
|
|
When you don't need the prepared statement anymore, you should
|
|
deallocate it:
|
|
<programlisting>
|
|
EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
|
|
</programlisting>
|
|
</para>
|
|
</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>
|
|
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);
|
|
free(out);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<sect2>
|
|
<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</> server. Because of the arbitrary precision this
|
|
variable needs to be able to expand and shrink dynamically. That's why you
|
|
can only create variables on the heap by means of the
|
|
<function>PGTYPESnumeric_new</> and <function>PGTYPESnumeric_free</>
|
|
functions. The decimal type, which is similar but limited in the 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.
|
|
</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</> is bigger than <literal>var2</>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
-1, if <literal>var1</> is smaller than <literal>var2</>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
0, if <literal>var1</> and <literal>var2</> 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</>. 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</>. 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</>
|
|
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</> 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</> points to into the double variable that <literal>dp</> points
|
|
to. It returns 0 on success and -1 if an error occurs, including
|
|
overflow. On overflow, the global variable <literal>errno</> will be set
|
|
to <literal>PGTYPES_NUM_OVERFLOW</> 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</> points to into the integer variable that <literal>ip</>
|
|
points to. It returns 0 on success and -1 if an error occurs, including
|
|
overflow. On overflow, the global variable <literal>errno</> will be set
|
|
to <literal>PGTYPES_NUM_OVERFLOW</> 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</> points to into the long integer variable that
|
|
<literal>lp</> points to. It returns 0 on success and -1 if an error
|
|
occurs, including overflow. On overflow, the global variable
|
|
<literal>errno</> will be set to <literal>PGTYPES_NUM_OVERFLOW</>
|
|
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</> points to into the decimal variable that
|
|
<literal>dst</> points to. It returns 0 on success and -1 if an error
|
|
occurs, including overflow. On overflow, the global variable
|
|
<literal>errno</> will be set to <literal>PGTYPES_NUM_OVERFLOW</>
|
|
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</> points to into the numeric variable that
|
|
<literal>dst</> 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>
|
|
<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</> 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</> and a pointer to
|
|
a C char* string <literal>endptr</>. 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>
|
|
The following input formats are allowed:
|
|
<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>
|
|
</para>
|
|
</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</> as its only parameter.
|
|
It will output the date in the form <literal>1999-01-18</>, i.e. in the
|
|
<literal>YYYY-MM-DD</> format.
|
|
</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</> and a pointer to an array
|
|
of 3 integer values <literal>mdy</>. The variable name indicates
|
|
the sequential order: <literal>mdy[0]</> will be set to contain the
|
|
number of the month, <literal>mdy[1]</> will be set to the value of the
|
|
day and <literal>mdy[2]</> 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</>) 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</> 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</>)
|
|
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</>), the
|
|
format mask (<literal>fmtstring</>) and the string that will hold the
|
|
textual representation of the date (<literal>outbuf</>).
|
|
</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>
|
|
The following 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, 23rd, 1959.
|
|
<table>
|
|
<title>Valid input formats for <function>PGTYPESdate_fmt_asc</function></title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>fmt</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>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="PGTYPESdatedefmtasc">
|
|
<term><function>PGTYPESdate_defmt_asc</function></term>
|
|
<listitem>
|
|
<para>
|
|
Use a format mask to convert a C char* 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</>), the format mask to use for
|
|
parsing the date (<literal>fmt</>) and the C char* string containing
|
|
the textual representation of the date (<literal>str</>). 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 following table indicates a few possible formats. This will give
|
|
you an idea of how to use this function.
|
|
<table>
|
|
<title>Valid input formats for <function>rdefmtdate</function></title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>fmt</entry>
|
|
<entry>str</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>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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</> 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</>) and a
|
|
pointer to a C char* (<literal>endptr</>).
|
|
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 errno is
|
|
set to <literal>PGTYPES_TS_BAD_TIMESTAMP</>. 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 timezones are not supported by ecpg. It can
|
|
parse them but does not apply any calculation as the
|
|
<productname>PostgreSQL</> server does for example. Timezone
|
|
specifiers are silently discarded.
|
|
</para>
|
|
<para>
|
|
The following table contains a few examples for input strings:
|
|
<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>
|
|
</para>
|
|
</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</> as
|
|
its only argument and returns an allocated string that contains the
|
|
textual representation of the timestamp.
|
|
</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</> 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</>), a pointer to the output buffer
|
|
(<literal>output</>), 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 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 "ante meridiem" or "post meridiem" 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</>
|
|
points to from the timestamp variable that <literal>ts1</> points to
|
|
and will store the result in the interval variable that <literal>iv</>
|
|
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</> as well as the formatting mask to use in the
|
|
variable <literal>fmt</>. The result will be stored in the variable
|
|
that <literal>d</> points to.
|
|
</para>
|
|
<para>
|
|
If the formatting mask <literal>fmt</> 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</>
|
|
and a pointer to an interval variable <literal>span</>. It adds the
|
|
interval to the timestamp and saves the resulting timestamp in the
|
|
variable that <literal>tout</> 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</>
|
|
points to from the timestamp variable that <literal>tin</> points to
|
|
and saves the result into the variable that <literal>tout</> 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>
|
|
<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</> 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_new(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</> 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</>
|
|
points to into a C char*. The output looks like this example:
|
|
<literal>@ 1 day 12 hours 59 mins 10 secs</literal>.
|
|
</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</>
|
|
points to into the variable that <literal>intvldest</> points to. Note
|
|
that you need to allocate the memory for the destination variable
|
|
before.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>The decimal type</title>
|
|
<para>
|
|
The decimal type is similar to the numeric type. However it is limited to
|
|
a maximal 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
|
|
PGTYPESdecimal_new() and PGTYPESdecimal_free(). 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</> 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>
|
|
<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_OVERFLOW</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>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_ERR_EARGS</literal></term>
|
|
<listitem>
|
|
<para>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_ERR_ENOSHORTDATE</literal></term>
|
|
<listitem>
|
|
<para>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_INTVL_BAD_INTERVAL</literal></term>
|
|
<listitem>
|
|
<para>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_ERR_ENOTDMY</literal></term>
|
|
<listitem>
|
|
<para>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_BAD_DAY</literal></term>
|
|
<listitem>
|
|
<para>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_DATE_BAD_MONTH</literal></term>
|
|
<listitem>
|
|
<para>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGTYPES_TS_BAD_TIMESTAMP</literal></term>
|
|
<listitem>
|
|
<para>
|
|
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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</> on
|
|
parse error.
|
|
Note that due to the internal representation of the timestamp datatype,
|
|
<literal>PGTYPESInvalidTimestamp</literal> is also a valid timestamp at
|
|
the same time. It is set to <literal>1899-12-31 23:59:59</>. In order
|
|
to detect errors, make sure that your application does not only test
|
|
for <literal>PGTYPESInvalidTimestamp</literal> but also for
|
|
<literal>errno != 0</> after each call to
|
|
<function>PGTYPEStimestamp_from_asc</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-informix-compat">
|
|
<title><productname>Informix</productname> compatibility mode</title>
|
|
<para>
|
|
ecpg can be run in a so-called <firstterm>Informix compatibility mode</>. 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</> 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>
|
|
<para>
|
|
There are two compatiblity modes: INFORMIX, INFORMIX_SE
|
|
</para>
|
|
<para>
|
|
When linking programs that use this compatibility mode, remember to link
|
|
against <literal>libcompat</> 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>
|
|
behaviour; 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</> so you won't
|
|
find support in ecpg for that either.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Additional embedded SQL statements</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>CLOSE DATABASE</></term>
|
|
<listitem>
|
|
<para>
|
|
This statement closes the current connection. In fact, this is a
|
|
synonym for ecpg's <literal>DISCONNECT CURRENT</>.:
|
|
<programlisting>
|
|
$CLOSE DATABASE; /* close the current connection */
|
|
EXEC SQL CLOSE DATABASE;
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Additional functions</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>decadd</></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</>), a pointer to the second operand of type decimal
|
|
(<literal>arg2</>) and a pointer to a value of type decimal that will
|
|
contain the sum (<literal>sum</>). On success, the function returns 0.
|
|
ECPG_INFORMIX_NUM_OVERFLOW is returned in case of overflow and
|
|
ECPG_INFORMIX_NUM_UNDERFLOW in case of underflow. -1 is returned for
|
|
other failures and errno is set to the respective errno number of the
|
|
pgtypeslib.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccmp</></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</>), a pointer to the second decimal value
|
|
(<literal>arg2</>) and returns an integer value that indicates which is
|
|
the bigger value.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
1, if the value that <literal>arg1</> points to is bigger than the
|
|
value that <literal>var2</> points to
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
-1, if the value that <literal>arg1</> points to is smaller than the
|
|
value that <literal>arg2</> points to </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
0, if the value that <literal>arg1</> points to and the value that
|
|
<literal>arg2</> points to are equal
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccopy</></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</>) and a pointer to the
|
|
target structure of type decimal (<literal>target</>) as the second
|
|
argument.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccvasc</></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</>) as well
|
|
as its length <literal>len</>. <literal>np</> 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</> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> is returned. If the ASCII
|
|
representation could not be parsed,
|
|
<literal>ECPG_INFORMIX_BAD_NUMERIC</> is returned or
|
|
<literal>ECPG_INFORMIX_BAD_EXPONENT</> if this problem occurred while
|
|
parsing the exponent.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>deccvdbl</></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</>). As the second
|
|
argument (<literal>np</>), 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</></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</>). As the second
|
|
argument (<literal>np</>), 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</></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</>). As the second
|
|
argument (<literal>np</>), 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</></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</>) and the second (<literal>n2</>) operands and
|
|
calculates <literal>n1</>/<literal>n2</>. <literal>result</> 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</> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> 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</></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</>) and the second (<literal>n2</>) operands and
|
|
calculates <literal>n1</>*<literal>n2</>. <literal>result</> 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</> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>decsub</></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</>) and the second (<literal>n2</>) operands and
|
|
calculates <literal>n1</>-<literal>n2</>. <literal>result</> 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</> or
|
|
<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectoasc</></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</>) that it converts to its textual representation.
|
|
<literal>cp</> is the buffer that should hold the result of the
|
|
operation. The parameter <literal>right</> 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</> 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</> is not sufficient to hold the
|
|
textual representation including the trailing NUL character, only a
|
|
single <literal>*</> character is stored in the result and -1 is
|
|
returned.
|
|
</para>
|
|
<para>
|
|
The function returns either -1 if the buffer <literal>cp</> was too
|
|
small or <literal>ECPG_INFORMIX_OUT_OF_MEMORY</> if memory was
|
|
exhausted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectodbl</></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</>) and a pointer to the double variable that
|
|
should hold the result of the operation (<literal>dblp</>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the conversion
|
|
failed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectoint</></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</>) and a pointer to the integer variable that
|
|
should hold the result of the operation (<literal>ip</>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the conversion
|
|
failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
|
|
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</>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dectolong</></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</>) and a pointer to the long variable that
|
|
should hold the result of the operation (<literal>lngp</>).
|
|
</para>
|
|
<para>
|
|
On success, 0 is returned and a negative value if the conversion
|
|
failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
|
|
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</>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rdatestr</></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</> and the second one is a pointer to the target
|
|
string. The output format is always <literal>yyyy-mm-dd</>, so you need
|
|
to allocate at least 11 bytes (including the NUL-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</></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</>) and a pointer to a variable of type date
|
|
(<literal>d</>). 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</>. Internally, this function is implemented by
|
|
means of <function>rdefmtdate</>. Therefore, <function>rstrdate</> is
|
|
not faster and if you have the choice you should opt for
|
|
<function>rdefmtdate</> which allows you to specify the format mask
|
|
explicitly.
|
|
</para>
|
|
<para>
|
|
The function returns the same values as <function>rdefmtdate</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>rtoday</></term>
|
|
<listitem>
|
|
<para>
|
|
Get the current date.
|
|
<synopsis>
|
|
void rtoday(date *d);
|
|
</synopsis>
|
|
The function receives a pointer to a date variable (<literal>d</>)
|
|
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</></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</> and a pointer to an array
|
|
of 3 short integer values <literal>mdy</>. The variable name indicates
|
|
the sequential order: <literal>mdy[0]</> will be set to contain the
|
|
number of the month, <literal>mdy[1]</> will be set to the value of the
|
|
day and <literal>mdy[2]</> 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</></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</>), the format mask to use for
|
|
parsing the date (<literal>fmt</>) and the C char* string containing
|
|
the textual representation of the date (<literal>str</>). 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</> - 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</> - The format string did not
|
|
correctly indicate the sequential order of year, month and day.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_BAD_DAY</> - The input string does not
|
|
contain a valid day.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_BAD_MONTH</> - The input string does not
|
|
contain a valid month.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>ECPG_INFORMIX_BAD_YEAR</> - 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</></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</>), the format
|
|
mask (<literal>fmt</>) and the string that will hold the textual
|
|
representation of the date (<literal>str</>).
|
|
</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</></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</>) 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</></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</> 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</></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</> points to.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>dtcvasc</></term>
|
|
<listitem>
|
|
<para>
|
|
Parses a timestamp from its textual representation in ANSI standard
|
|
into a timestamp variable.
|
|
<synopsis>
|
|
int dtcvasc(char *str, timestamp *ts);
|
|
</synopsis>
|
|
The function receives the string to parse (<literal>str</>) and a
|
|
pointer to the timestamp variable that should hold the result of the
|
|
operation (<literal>ts</>).
|
|
</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</></term>
|
|
<listitem>
|
|
<para>
|
|
Parses a timestamp from its textual representation in ANSI standard
|
|
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</>), the
|
|
format mask to use (<literal>fmtstr</>) and a pointer to the timestamp
|
|
variable that should hold the result of the operation (<literal>ts</>).
|
|
</para>
|
|
<para>
|
|
This functions is implemented by means of the <xref
|
|
linkend="PGTYPEStimestampdefmtasc">. 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</></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</>
|
|
points to from the timestamp variable that <literal>ts1</> points to
|
|
and will store the result in the interval variable that <literal>iv</>
|
|
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</></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</>) and the string that should hold the result of the
|
|
operation <literal>output</>). It converts <literal>ts</> to its
|
|
textual representation in the ANSI SQL standard which is defined to
|
|
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</></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</>), a pointer to the output buffer
|
|
(<literal>output</>), 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</></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</>) and the string that should hold the result of the
|
|
operation <literal>str</>). It converts <literal>i</> to its
|
|
textual representation in the ANSI SQL standard which is defined to
|
|
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</></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</>, the format
|
|
mask <literal>fmt</> and a pointer to the output buffer
|
|
<literal>outbuf</>. 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</></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</></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</>) and its length as its second argument
|
|
(<literal>len</>). It returns the number of significant characters,
|
|
that is the length of the string without trailing blanks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>ldchar</></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</>), its length (<literal>len</>) and a pointer to the
|
|
destination memory (<literal>dest</>). Note that you need to reserve at
|
|
least <literal>len+1</> bytes for the string that <literal>dest</>
|
|
points to. The function copies at most <literal>len</> 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</></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</></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</></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</></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</></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 casted 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>
|
|
$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</></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</>)
|
|
as well a pointer to this variable (<literal>ptr</>). Note that the
|
|
latter needs to be casted 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>
|
|
$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>
|
|
<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</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if an overflow occurred in a
|
|
calculation. Internally it is defined to -1200 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_NUM_UNDERFLOW</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if an underflow occurred in a calculation.
|
|
Internally it is defined to -1201 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_DIVIDE_ZERO</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if an attempt to divide by zero is
|
|
observed. Internally it is defined to -1202 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_YEAR</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a bad value for a year was found while
|
|
parsing a date. Internally it is defined to -1204 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_MONTH</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a bad value for a month was found while
|
|
parsing a date. Internally it is defined to -1205 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_DAY</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a bad value for a day was found while
|
|
parsing a date. Internally it is defined to -1206 (the <productname>Informix</productname>
|
|
definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_ENOSHORTDATE</></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 to -1209 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_DATE_CONVERT</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if Internally it is defined to -1210 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_OUT_OF_MEMORY</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if Internally it is defined to -1211 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_ENOTDMY</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if a parsing routine was supposed to get a
|
|
format mask (like <literal>mmddyy</>) but not all fields were listed
|
|
correctly. Internally it is defined to -1212 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_NUMERIC</></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 to -1213 (the <productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_EXPONENT</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if Internally it is defined to -1216 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_BAD_DATE</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if Internally it is defined to -1218 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>ECPG_INFORMIX_EXTRA_CHARS</></term>
|
|
<listitem>
|
|
<para>
|
|
Functions return this value if Internally it is defined to -1264 (the
|
|
<productname>Informix</productname> definition).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-descriptors">
|
|
<title>Using SQL Descriptor Areas</title>
|
|
|
|
<para>
|
|
An SQL descriptor area is a more sophisticated method for
|
|
processing the result of a <command>SELECT</command> or
|
|
<command>FETCH</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.
|
|
</para>
|
|
|
|
<para>
|
|
An 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. <remark>The scope of the allocated descriptor is WHAT?.</remark>
|
|
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 DESCRIPTOR mydesc;
|
|
</programlisting>
|
|
</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>
|
|
?
|
|
</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>
|
|
</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 several
|
|
nonexclusive facilities for this.
|
|
</para>
|
|
|
|
<sect2>
|
|
<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>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.
|
|
</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>
|
|
<title>sqlca</title>
|
|
|
|
<para>
|
|
For more powerful error handling, the embedded SQL interface
|
|
provides a global variable with the name <varname>sqlca</varname>
|
|
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>sqlcabc</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>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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>-12 (<symbol>ECPG_OUT_OF_MEMORY</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Indicates that your virtual memory is exhausted. (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_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'</> nor
|
|
<literal>'f'</>. (SQLSTATE 42804)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-208 (<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>-209 (<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>-210 (<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>-211 (<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>-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>-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>-400 (<symbol>ECPG_PGSQL</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
Some error caused by the <productname>PostgreSQL</productname>
|
|
server. The message contains the error message from the
|
|
<productname>PostgreSQL</productname> server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-401 (<symbol>ECPG_TRANS</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The <productname>PostgreSQL</productname> server signaled that
|
|
we cannot start, commit, or rollback the transaction.
|
|
(SQLSTATE 08007)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-402 (<symbol>ECPG_CONNECT</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
The connection attempt to the database did not succeed.
|
|
(SQLSTATE 08001)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>100 (<symbol>ECPG_NOT_FOUND</symbol>)</term>
|
|
<listitem>
|
|
<para>
|
|
This is a harmless condition indicating that the last command
|
|
retrieved or processed zero rows, or that you are at the end of
|
|
the cursor. (SQLSTATE 02000)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-preproc">
|
|
<title>Preprocessor directives</title>
|
|
|
|
<sect2>
|
|
<title>Including files</title>
|
|
|
|
<para>
|
|
To include an external file into your embedded SQL program, use:
|
|
<programlisting>
|
|
EXEC SQL INCLUDE <replaceable>filename</replaceable>;
|
|
</programlisting>
|
|
The embedded SQL preprocessor will look for a file named
|
|
<literal><replaceable>filename</replaceable>.h</literal>,
|
|
preprocess it, and include it in the resulting C output. Thus,
|
|
embedded SQL statements in the included file are handled correctly.
|
|
</para>
|
|
|
|
<para>
|
|
Note that this is <emphasis>not</emphasis> the same as:
|
|
<programlisting>
|
|
#include <<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>
|
|
<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</>;
|
|
EXEC SQL DEFINE <replaceable>name</> <replaceable>value</>;
|
|
</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</> 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</> then the ecpg 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 ecpg will already do the substitution and your C compiler will never
|
|
see any name or identifier <literal>MYNUMBER</>. 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>
|
|
<title>ifdef, ifndef, else, elif 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</>;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Checks a <replaceable>name</> and processes subsequent lines if
|
|
<replaceable>name</> has been created with <literal>EXEC SQL define
|
|
<replaceable>name</></literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL ifndef <replaceable>name</>;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Checks a <replaceable>name</> and processes subsequent lines if
|
|
<replaceable>name</> has <emphasis>not</emphasis> been created with
|
|
<literal>EXEC SQL define <replaceable>name</></literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL else;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Starts processing an alternative section to a section introduced by
|
|
either <literal>EXEC SQL ifdef <replaceable>name</></literal> or
|
|
<literal>EXEC SQL ifndef <replaceable>name</></literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL elif <replaceable>name</>;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Checks <replaceable>name</> and starts an alternative section if
|
|
<replaceable>name</> has been created with <literal>EXEC SQL define
|
|
<replaceable>name</></literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>EXEC SQL endif;</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Ends an alternative section.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Example:
|
|
<programlisting>
|
|
exec sql ifndef TZVAR;
|
|
exec sql SET TIMEZONE TO 'GMT';
|
|
exec sql elif TZNAME;
|
|
exec sql SET TIMEZONE TO TZNAME;
|
|
exec sql else;
|
|
exec sql SET TIMEZONE TO TZVAR;
|
|
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</> installation.
|
|
Embedded SQL programs are typically named with an extension
|
|
<filename>.pgc</filename>. If you have a program file called
|
|
<filename>prog1.pgc</filename>, you can preprocess it by simply
|
|
calling:
|
|
<programlisting>
|
|
ecpg prog1.pgc
|
|
</programlisting>
|
|
This will create a file called <filename>prog1.c</filename>. If
|
|
your input files do not follow the suggested naming pattern, you
|
|
can specify the output file explicitly using the
|
|
<option>-o</option> option.
|
|
</para>
|
|
|
|
<para>
|
|
The preprocessed file can be compiled normally, for example:
|
|
<programlisting>
|
|
cc -c prog1.c
|
|
</programlisting>
|
|
The generated C source files include header files from the
|
|
<productname>PostgreSQL</> installation, so if you installed
|
|
<productname>PostgreSQL</> in a location that is not searched by
|
|
default, you have to add an option such as
|
|
<literal>-I/usr/local/pgsql/include</literal> to the compilation
|
|
command line.
|
|
</para>
|
|
|
|
<para>
|
|
To link an embedded SQL program, you need to include the
|
|
<filename>libecpg</filename> library, like so:
|
|
<programlisting>
|
|
cc -o myprog prog1.o prog2.o ... -lecpg
|
|
</programlisting>
|
|
Again, you might have to add an option like
|
|
<literal>-L/usr/local/pgsql/lib</literal> to that command line.
|
|
</para>
|
|
|
|
<para>
|
|
If you manage the build process of a larger project using
|
|
<application>make</application>, it 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 if it is built
|
|
using the <option>--enable-thread-safety</> command-line option to
|
|
<filename>configure</filename>. (You might need to use other threading
|
|
command-line options to compile your client code.)
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-library">
|
|
<title>Library Functions</title>
|
|
|
|
<para>
|
|
The <filename>libecpg</filename> library primarily contains
|
|
<quote>hidden</quote> functions that are used to implement the
|
|
functionality expressed by the embedded SQL commands. But there
|
|
are some functions that can usefully be called directly. Note that
|
|
this makes your code unportable.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>ECPGdebug(int <replaceable>on</replaceable>, FILE
|
|
*<replaceable>stream</replaceable>)</function> turns on debug
|
|
logging if called with the first argument non-zero. Debug logging
|
|
is done on <replaceable>stream</replaceable>. The log contains
|
|
all <acronym>SQL</acronym> statements with all the input
|
|
variables inserted, and the results from the
|
|
<productname>PostgreSQL</productname> server. This can be very
|
|
useful when searching for errors in your <acronym>SQL</acronym>
|
|
statements.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
On Windows, if the <application>ecpg</> libraries and an application are
|
|
compiled with different flags, this function call will crash the
|
|
application because the internal representation of the
|
|
<literal>FILE</> pointers differ. Specifically,
|
|
multithreaded/single-threaded, release/debug, and static/dynamic
|
|
flags should be the same for the library and all applications using
|
|
that library.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>ECPGstatus(int <replaceable>lineno</replaceable>,
|
|
const char* <replaceable>connection_name</replaceable>)</function>
|
|
returns true if you are connected to a database and false if not.
|
|
<replaceable>connection_name</replaceable> can be <literal>NULL</>
|
|
if a single connection is being used.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="ecpg-develop">
|
|
<title>Internals</title>
|
|
|
|
<para>
|
|
This section explains how <application>ECPG</application> works
|
|
internally. This information can occasionally be useful to help
|
|
users understand how to use <application>ECPG</application>.
|
|
</para>
|
|
|
|
<para>
|
|
The first four lines written by <command>ecpg</command> to the
|
|
output are fixed lines. Two are comments and two are include
|
|
lines necessary to interface to the library. Then the
|
|
preprocessor reads through the file and writes output. Normally
|
|
it just echoes everything to the output.
|
|
</para>
|
|
|
|
<para>
|
|
When it sees an <command>EXEC SQL</command> statement, it
|
|
intervenes and changes it. The command starts with <command>EXEC
|
|
SQL</command> and ends with <command>;</command>. Everything in
|
|
between is treated as an <acronym>SQL</acronym> statement and
|
|
parsed for variable substitution.
|
|
</para>
|
|
|
|
<para>
|
|
Variable substitution occurs when a symbol starts with a colon
|
|
(<literal>:</literal>). The variable with that name is looked up
|
|
among the variables that were previously declared within a
|
|
<literal>EXEC SQL DECLARE</> section.
|
|
</para>
|
|
|
|
<para>
|
|
The most important function in the library is
|
|
<function>ECPGdo</function>, which takes care of executing most
|
|
commands. It takes a variable number of arguments. This can easily
|
|
add up to 50 or so arguments, and we hope this will not be a
|
|
problem on any platform.
|
|
</para>
|
|
|
|
<para>
|
|
The arguments are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>A line number</term>
|
|
<listitem>
|
|
<para>
|
|
This is the line number of the original line; used in error
|
|
messages only.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>A string</term>
|
|
<listitem>
|
|
<para>
|
|
This is the <acronym>SQL</acronym> command that is to be issued.
|
|
It is modified by the input variables, i.e., the variables that
|
|
where not known at compile time but are to be entered in the
|
|
command. Where the variables should go the string contains
|
|
<literal>?</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Input variables</term>
|
|
<listitem>
|
|
<para>
|
|
Every input variable causes ten arguments to be created. (See below.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>ECPGt_EOIT</></term>
|
|
<listitem>
|
|
<para>
|
|
An <type>enum</> telling that there are no more input
|
|
variables.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Output variables</term>
|
|
<listitem>
|
|
<para>
|
|
Every output variable causes ten arguments to be created.
|
|
(See below.) These variables are filled by the function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><parameter>ECPGt_EORT</></term>
|
|
<listitem>
|
|
<para>
|
|
An <type>enum</> telling that there are no more variables.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
For every variable that is part of the <acronym>SQL</acronym>
|
|
command, the function gets ten arguments:
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
The type as a special symbol.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
A pointer to the value or a pointer to the pointer.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The size of the variable if it is a <type>char</type> or <type>varchar</type>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The number of elements in the array (for array fetches).
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The offset to the next element in the array (for array fetches).
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The type of the indicator variable as a special symbol.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
A pointer to the indicator variable.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
0
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The number of elements in the indicator array (for array fetches).
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The offset to the next element in the indicator array (for
|
|
array fetches).
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Note that not all SQL commands are treated in this way. For
|
|
instance, an open cursor statement like:
|
|
<programlisting>
|
|
EXEC SQL OPEN <replaceable>cursor</replaceable>;
|
|
</programlisting>
|
|
is not copied to the output. Instead, the cursor's
|
|
<command>DECLARE</> command is used at the position of the <command>OPEN</> command
|
|
because it indeed opens the cursor.
|
|
</para>
|
|
|
|
<para>
|
|
Here is a complete example describing the output of the
|
|
preprocessor of a file <filename>foo.pgc</filename> (details 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>
|
|
/* 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>
|