rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
postgresql/doc/src/sgml/ecpg.sgml

4994 lines
162 KiB
Plaintext
Raw Blame History

<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.90 2009/07/11 21:15:32 petere 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><![CDATA[
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><![CDATA[
EXEC SQL BEGIN DECLARE SECTION;
date date1;
timestamp ts1, tsout;
interval iv1;
char *out;
EXEC SQL END DECLARE SECTION;
PGTYPESdate_today(&date1);
EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
out = PGTYPEStimestamp_to_asc(&tsout);
printf("Started + duration: %s\n", out);
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>
<xref linkend="ecpg-pgtypesdate-from-asc-table"> shows the allowed input formats.
</para>
<table id="ecpg-pgtypesdate-from-asc-table">
<title>Valid input formats for <function>PGTYPESdate_from_asc</function></title>
<tgroup cols="2">
<thead>
<row>
<entry>Input</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>January 8, 1999</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>1999-01-08</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>1/8/1999</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>1/18/1999</literal></entry>
<entry><literal>January 18, 1999</literal></entry>
</row>
<row>
<entry><literal>01/02/03</literal></entry>
<entry><literal>February 1, 2003</literal></entry>
</row>
<row>
<entry><literal>1999-Jan-08</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>Jan-08-1999</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>08-Jan-1999</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>99-Jan-08</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>08-Jan-99</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>08-Jan-06</literal></entry>
<entry><literal>January 8, 2006</literal></entry>
</row>
<row>
<entry><literal>Jan-08-99</literal></entry>
<entry><literal>January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>19990108</literal></entry>
<entry><literal>ISO 8601; January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>990108</literal></entry>
<entry><literal>ISO 8601; January 8, 1999</literal></entry>
</row>
<row>
<entry><literal>1999.008</literal></entry>
<entry><literal>year and day of year</literal></entry>
</row>
<row>
<entry><literal>J2451187</literal></entry>
<entry><literal>Julian day</literal></entry>
</row>
<row>
<entry><literal>January 8, 99 BC</literal></entry>
<entry><literal>year 99 before the Common Era</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry id="PGTYPESdatetoasc">
<term><function>PGTYPESdate_to_asc</function></term>
<listitem>
<para>
Return the textual representation of a date variable.
<synopsis>
char *PGTYPESdate_to_asc(date dDate);
</synopsis>
The function receives the date <literal>dDate</> 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>
<xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"> indicates a few possible formats. This will give
you an idea of how to use this function. All output lines are based on
the same date: November 23, 1959.
</para>
<table id="ecpg-pgtypesdate-fmt-asc-example-table">
<title>Valid input formats for <function>PGTYPESdate_fmt_asc</function></title>
<tgroup cols="2">
<thead>
<row>
<entry>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>
</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>
<xref linkend="ecpg-rdefmtdate-example-table"> indicates a few possible formats. This will give
you an idea of how to use this function.
</para>
<table id="ecpg-rdefmtdate-example-table">
<title>Valid input formats for <function>rdefmtdate</function></title>
<tgroup cols="3">
<thead>
<row>
<entry>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>
</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>
<xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"> contains a few examples for input strings.
</para>
<table id="ecpg-pgtypestimestamp-from-asc-example-table">
<title>Valid input formats for <function>PGTYPEStimestamp_from_asc</function></title>
<tgroup cols="2">
<thead>
<row>
<entry>Input</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>1999-01-08 04:05:06</literal></entry>
<entry><literal>1999-01-08 04:05:06</literal></entry>
</row>
<row>
<entry><literal>January 8 04:05:06 1999 PST</literal></entry>
<entry><literal>1999-01-08 04:05:06</literal></entry>
</row>
<row>
<entry><literal>1999-Jan-08 04:05:06.789-8</literal></entry>
<entry><literal>1999-01-08 04:05:06.789 (time zone specifier ignored)</literal></entry>
</row>
<row>
<entry><literal>J2451187 04:05-08:00</literal></entry>
<entry><literal>1999-01-08 04:05:00 (time zone specifier ignored)</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry id="PGTYPEStimestamptoasc">
<term><function>PGTYPEStimestamp_to_asc</function></term>
<listitem>
<para>
Converts a date to a C char* string.
<synopsis>
char *PGTYPEStimestamp_to_asc(timestamp tstamp);
</synopsis>
The function receives the timestamp <literal>tstamp</> 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
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
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 according to the SQL standard, which is
be <literal>YYYY-MM-DD HH:MM:SS</literal>.
</para>
<para>
Upon success, the function returns 0 and a negative value if an
error occurred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>dttofmtasc</></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 according to the SQL standard, which is
be <literal>YYYY-MM-DD HH:MM:SS</literal>.
</para>
<para>
Upon success, the function returns 0 and a negative value if an
error occurred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>rfmtlong</></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>&amp;</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>&lt;</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><![CDATA[
$char c[] = "abc ";
$short s = 17;
$int i = -74874;
rsetnull(CCHARTYPE, (char *) c);
rsetnull(CSHORTTYPE, (char *) &s);
rsetnull(CINTTYPE, (char *) &i);
]]>
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>risnull</></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><![CDATA[
$char c[] = "abc ";
$short s = 17;
$int i = -74874;
risnull(CCHARTYPE, (char *) c);
risnull(CSHORTTYPE, (char *) &s);
risnull(CINTTYPE, (char *) &i);
]]>
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2>
<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 &lt;<replaceable>filename</replaceable>.h&gt;
</programlisting>
because this file would not be subject to SQL command preprocessing.
Naturally, you can continue to use the C
<literal>#include</literal> directive to include other header
files.
</para>
<note>
<para>
The include file name is case-sensitive, even though the rest of
the <literal>EXEC SQL INCLUDE</literal> command follows the normal
SQL case-sensitivity rules.
</para>
</note>
</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) $&lt;
</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><![CDATA[
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include <ecpgtype.h>;
#include <ecpglib.h>;
/* exec sql begin declare section */
#line 1 "foo.pgc"
int index;
int result;
/* exec sql end declare section */
...
ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ? ",
ECPGt_int,&(index),1L,1L,sizeof(int),
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
ECPGt_int,&(result),1L,1L,sizeof(int),
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
]]>
</programlisting>
(The indentation here is added for readability and not
something the preprocessor does.)
</para>
</sect1>
</chapter>
Reference in New Issue View Git Blame Copy Permalink