PostgreSQL 8.0.0rc4 Documentation
Prev | Fast Backward | Chapter 29. ECPG - Embedded SQL in C | Fast Forward | Next

# 29.6. Using Host Variables

In Section 29.4 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 host variables.

## 29.6.1. Overview

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:

    EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);

This statements refers to two C variables named `v1` and `v2` and also uses a regular SQL string literal, to illustrate that you are not restricted to use one kind of data or the other.

This style of inserting C variables in SQL statements works anywhere a value expression is expected in an SQL statement. In the SQL environment we call the references to C variables host variables.

## 29.6.2. Declare Sections

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.

This section starts with

    EXEC SQL BEGIN DECLARE SECTION;

and ends with

    EXEC SQL END DECLARE SECTION;

Between those lines, there must be normal C variable declarations, such as

    int   x;
    char  foo[16], bar[16];

You can have as many declare sections in a program as you like.

The declarations are also echoed to the output file as a 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.

The definition of a structure or union also must be listed inside a `DECLARE` section. Otherwise the preprocessor cannot handle these types since it does not know the definition.

The special type `VARCHAR` is converted into a named `struct` for every variable. A declaration like

    VARCHAR var[180];

is converted into

    struct varchar_var { int len; char arr[180]; } var;

This structure is suitable for interfacing with SQL datums of type `varchar`.

## 29.6.3. `SELECT INTO` and `FETCH INTO`

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 `SELECT` and `FETCH`. These commands have a special `INTO` clause that specifies which host variables the retrieved values are to be stored in.

Here is an example:

    /*
     * 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;

So the `INTO` clause appears between the select list and the `FROM` clause. The number of elements in the select list and the list after `INTO` (also called the target list) must be equal.

Here is an example using the command `FETCH`:

    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 (...);

Here the `INTO` clause appears after all the normal clauses.

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.

## 29.6.4. Indicators

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 indicator 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:

    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;

The indicator variable `val_ind` will be zero if the value was not null, and it will be negative if the value was null.

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.

Prev | Home | Next
Choosing a Connection | Up | Dynamic SQL