33.4. 使用宿主变量

33.4.4.1. 处理字符串

为了处理SQL字符串数据类型，比如varchar和text， 有两种可能方式声明宿主变量。

一种方式是使用char[]，char数组是在C中处理字符数据 最常见方式。

EXEC SQL BEGIN DECLARE SECTION;
    char str[50];
EXEC SQL END DECLARE SECTION;

请注意，你必须关注自身长度。 如果你使用这个宿主变量 作为查询返回一个具有多于49个字符的字符串的目标变量， 那么发生缓冲区溢出。

另一种方法是使用VARCHAR类型，这是一个由ECPG提供的 特殊类型。VARCHAR类型的数组定义被转换为 每个变量的命名结构。声明如：

VARCHAR var[180];

转换成：

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

arr有一个终止零字节的字符串。 因此，为了在VARCHAR宿主变量中存储字符串， 宿主变量必须声明为包含零字节终结符的长度。 len持有 存储在arr中而没有 终止零字节的字符串长度。当一个宿主变量作为一个查询输入时 ，如果strlen(arr) 和len是不同的，那么使用稍短的。

两个或以上VARCHAR宿主变量不能在单行语句中被声明。 下面的代码将混淆ecpg预处理程序：

VARCHAR v1[128], v2[128];   /* WRONG */

两个变量应该像下面这样在独立语句中进行定义：

VARCHAR v1[128];
VARCHAR v2[128];

VARCHAR可以使用大写或小写，但是在不混淆的情况下。

char和VARCHAR宿主变量可以持有其它SQL类型的值， 这将被存储在它们的字符串形式中。

33.4.4.2. 访问特定数据类型

ECPG含有一些特定类型帮助你 与来自PostgreSQL服务器的一些特殊数据类型进行轻松互动。 特别是，它已经实现支持numeric, decimal, date, timestamp和interval类型。 这些数据类型不能有效地映射到原始主机变量类型（例如 int, long long int或者char[]）， 因为他们有一个复杂的内部结构。 应用程序通过声明特殊类型的主机变量处理这些类型，并且在pgtypes库中使用函数访问他们。 该pgtypes库包含处理这些类型的基本函数的 详细描述参阅Section 33.6， 这样你就不需要发送一个查询到SQL服务器，仅仅为了添加间隔时间戳例子。

以下小节描述了这些特殊数据类型。为了获得关于pgtypes库函数的更多细节， 参阅Section 33.6。

#include <pgtypes_timestamp.h>

EXEC SQL BEGIN DECLARE SECTION;
timestamp ts;
EXEC SQL END DECLARE SECTION;

EXEC SQL SELECT now()::timestamp INTO :ts;

printf("ts = %s\n", PGTYPEStimestamp_to_asc(ts));

ts = 2010-06-27 18:03:56.949343

#include <stdio.h>
#include <stdlib.h>
#include <pgtypes_interval.h>

int
main(void)
{
EXEC SQL BEGIN DECLARE SECTION;
    interval *in;
EXEC SQL END DECLARE SECTION;

    EXEC SQL CONNECT TO testdb;

    in = PGTYPESinterval_new();
    EXEC SQL SELECT '1 min'::interval INTO :in;
    printf("interval = %s\n", PGTYPESinterval_to_asc(in));
    PGTYPESinterval_free(in);

    EXEC SQL COMMIT;
    EXEC SQL DISCONNECT ALL;
    return 0;
}

#include <stdio.h>
#include <stdlib.h>
#include <pgtypes_numeric.h>

EXEC SQL WHENEVER SQLERROR STOP;

int
main(void)
{
EXEC SQL BEGIN DECLARE SECTION;
    numeric *num;
    numeric *num2;
    decimal *dec;
EXEC SQL END DECLARE SECTION;

    EXEC SQL CONNECT TO testdb;

    num = PGTYPESnumeric_new();
    dec = PGTYPESdecimal_new();

    EXEC SQL SELECT 12.345::numeric(4,2), 23.456::decimal(4,2) INTO :num, :dec;

    printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 0));
    printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 1));
    printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 2));

    
/*转换十进制到数值型以显示十进制值*/
    num2 = PGTYPESnumeric_new();
    PGTYPESnumeric_from_decimal(dec, num2);

    printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 0));
    printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 1));
    printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 2));

    PGTYPESnumeric_free(num2);
    PGTYPESdecimal_free(dec);
    PGTYPESnumeric_free(num);

    EXEC SQL COMMIT;
    EXEC SQL DISCONNECT ALL;
    return 0;
}

33.4.4.3. 使用非初级类型的宿主变量

作为一个宿主变量你也可以使用数组，typedefs，结构和指针。

int
main(void)
{
EXEC SQL BEGIN DECLARE SECTION;
    int dbid[8];
    char dbname[8][16];
    int i;
EXEC SQL END DECLARE SECTION;

    memset(dbname, 0, sizeof(char)* 16 * 8);
    memset(dbid, 0, sizeof(int) * 8);

    EXEC SQL CONNECT TO testdb;

    
/*同时检索多行到数组中*/
    EXEC SQL SELECT oid,datname INTO :dbid, :dbname FROM pg_database;

    for (i = 0; i < 8; i++)
        printf("oid=%d, dbname=%s\n", dbid[i], dbname[i]);

    EXEC SQL COMMIT;
    EXEC SQL DISCONNECT ALL;
    return 0;
}

oid=1, dbname=template1
oid=11510, dbname=template0
oid=11511, dbname=postgres
oid=313780, dbname=testdb
oid=0, dbname=
oid=0, dbname=
oid=0, dbname=

EXEC SQL BEGIN DECLARE SECTION;
    typedef struct
    {
       int oid;
       char datname[65];
       long long int size;
    } dbinfo_t;

    dbinfo_t dbval;
EXEC SQL END DECLARE SECTION;

    memset(&dbval, 0, sizeof(dbinfo_t));

    EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database;
    EXEC SQL OPEN cur1;
    
/*当结果集到达末尾时，打破while循环*/
    EXEC SQL WHENEVER NOT FOUND DO BREAK;

    while (1)
    {
    
/*抓取多列到一个结构中*/
        EXEC SQL FETCH FROM cur1 INTO :dbval;

/*打印结构成员*/
        printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, dbval.size);
    }

    EXEC SQL CLOSE cur1;

oid=1, datname=template1, size=4324580
oid=11510, datname=template0, size=4243460
oid=11511, datname=postgres, size=4324580
oid=313780, datname=testdb, size=8183012

EXEC SQL BEGIN DECLARE SECTION;
    typedef struct
    {
       int oid;
       char datname[65];
    } dbinfo_t;

    dbinfo_t dbval;
    long long int size;
EXEC SQL END DECLARE SECTION;

    memset(&dbval, 0, sizeof(dbinfo_t));

    EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database;
    EXEC SQL OPEN cur1;
    
    /*当结果集到达末尾时，打破while循环*/
    EXEC SQL WHENEVER NOT FOUND DO BREAK;

    while (1)
    {
    

/*抓取多列到一个结构中*/
        EXEC SQL FETCH FROM cur1 INTO :dbval, :size;
 
        
/*打印结构成员*/ 
        printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, size);
    }

    EXEC SQL CLOSE cur1;

EXEC SQL BEGIN DECLARE SECTION;
    typedef char mychartype[40];
    typedef long serial_t;
EXEC SQL END DECLARE SECTION;

EXEC SQL TYPE serial_t IS long;

EXEC SQL BEGIN DECLARE SECTION;
    int   *intp;
    char **charp;
EXEC SQL END DECLARE SECTION;

33.4.5.1. 数组

在ECPG中不直接支持SQL级别数组。不可能简单的映射SQL数组到C数组宿主变量。 这将产生未定义操作。然而，存在一些解决方法。

如果查询分别访问数组元素，那么这可以避免在ECPG中使用数组。 然后，应该使用可以映射到元素类型的宿主变量。比如， 如果列类型是integer数组，那么使用int类型宿主变量。 如果元素类型是varchar或者text， 则可以使用char[]或者VARCHAR[]类型宿主变量。

下面是一个例子。假设下列表:

CREATE TABLE t3 (
    ii integer[]
);

testdb=> SELECT * FROM t3;
     ii
-------------
 {1,2,3,4,5}
(1 row)

下面示例程序检索了数组的第四个元素，并且将它存储在int类型 的宿主变量中：

EXEC SQL BEGIN DECLARE SECTION;
int ii;
EXEC SQL END DECLARE SECTION;

EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[4] FROM t3;
EXEC SQL OPEN cur1;

EXEC SQL WHENEVER NOT FOUND DO BREAK;

while (1)
{
    EXEC SQL FETCH FROM cur1 INTO :ii ;
    printf("ii=%d\n", ii);
}

EXEC SQL CLOSE cur1;

该例子显示了下面结果：

ii=4

为了映射多个数组元素到数组列的数组类型宿主变量每个元素的多个元组，并且 宿主变量数组的每个元素必须分别被管理，比如：

EXEC SQL BEGIN DECLARE SECTION;
int ii_a[8];
EXEC SQL END DECLARE SECTION;

EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[1], ii[2], ii[3], ii[4] FROM t3;
EXEC SQL OPEN cur1;

EXEC SQL WHENEVER NOT FOUND DO BREAK;

while (1)
{
    EXEC SQL FETCH FROM cur1 INTO :ii_a[0], :ii_a[1], :ii_a[2], :ii_a[3];
    ...
}

请再次注意

EXEC SQL BEGIN DECLARE SECTION;
int ii_a[8];
EXEC SQL END DECLARE SECTION;

EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii FROM t3;
EXEC SQL OPEN cur1;

EXEC SQL WHENEVER NOT FOUND DO BREAK;

while (1)
{
    /* WRONG */
    EXEC SQL FETCH FROM cur1 INTO :ii_a;
    ...
}

不会在这种情况下正确工作，因为你不能映射一个数组类型列直接到数组宿主变量。

另外一种方法是在char[] 或者VARCHAR[]类型宿主变量的外部字符串形式中存储数组。 更多关于该形式的详细信息，请参阅Section 8.15.2。 注意这意味着在主程序（没有对分析文本表示的进一步处理）中数组自然不能作为数组被访问。

33.4.5.2. 复合类型

在ECPG中不直接支持复合类型，但是简单解决方法是可能的。 可用的方法与上面数组描述的那个是类似的： 要么分别访问每个属性，要么使用外部字符串表示形式。

下面列子中，假设下面类型和表：

CREATE TYPE comp_t AS (intval integer, textval varchar(32));
CREATE TABLE t4 (compval comp_t);
INSERT INTO t4 VALUES ( (256, 'PostgreSQL') );

最明显的解决方法是分别访问每个属性。下面程序通过分别选择类型comp_t 的每个属性的示例表中检索数据：

EXEC SQL BEGIN DECLARE SECTION;
int intval;
varchar textval[33];
EXEC SQL END DECLARE SECTION;

/*将复合类型列的每个元素放在SELECT列表中*/

EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4;
EXEC SQL OPEN cur1;

EXEC SQL WHENEVER NOT FOUND DO BREAK;

while (1)
{
    
/*抓取复合类型列的每个元素给宿主变量*/
    EXEC SQL FETCH FROM cur1 INTO :intval, :textval;

    printf("intval=%d, textval=%s\n", intval, textval.arr);
}

EXEC SQL CLOSE cur1;

为了加强这个例子，在FETCH命令中存储值的宿主变量 可以聚集在一个结构中。 关于结构形式中宿主变量的更多细节，参阅Section 33.4.4.3.2。 为了切换到结构，例子可以做如下修改。 两个宿主变量intval和textval， 是comp_t结构成员，并且在FETCH命令上 指定结构。

EXEC SQL BEGIN DECLARE SECTION;
typedef struct
{
    int intval;
    varchar textval[33];
} comp_t;

comp_t compval;
EXEC SQL END DECLARE SECTION;

/*将复合类型列的每个元素放在SELECT列表中*/

EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4;
EXEC SQL OPEN cur1;

EXEC SQL WHENEVER NOT FOUND DO BREAK;

while (1)
{
    
/*将SELECT列表中所有值放到结构中*/

    EXEC SQL FETCH FROM cur1 INTO :compval;

    printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr);
}

EXEC SQL CLOSE cur1;

虽然结构用于FETCH命令，逐一指定SELECT 子句中的属性名，这可以通过使用 *请求复合类型值的所有属性获得提高。

...
EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).* FROM t4;
EXEC SQL OPEN cur1;

EXEC SQL WHENEVER NOT FOUND DO BREAK;

while (1)
{
    
/*将SELECT列表中的所有值放到结构中*/
    EXEC SQL FETCH FROM cur1 INTO :compval;

    printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr);
}
...

这种方式，可以无缝的将复合类型映射到结构中，尽管ECPG并不了解该复合类型。

最后，在类型char[]或者VARCHAR[]宿主变量中的外部字符串表示形式中 存储复合类型是可能的。但是那种方式，不容易从主程序中访问值的字段。

33.4.5.3. 用户自定义基本类型

ECPG不直接支持新用户自定义基础类型。你可以使用外部字符串表示形式和 类型char[]或者VARCHAR[]的宿主变量，并且该方法 对于许多类型的确是合适的并且充分的。

这是一个使用Section 35.11中复合数据类型的例子。 该类型的外部字符串表示形式是(%lf,%lf)， 定义在Section 35.11中的complex_in() 和complex_out()函数中。 下面例子将复合类型值(1,1) 和(3,3)插入到列a和b中， 并且之后从表中选择它们。

EXEC SQL BEGIN DECLARE SECTION;
    varchar a[64];
    varchar b[64];
EXEC SQL END DECLARE SECTION;

    EXEC SQL INSERT INTO test_complex VALUES ('(1,1)', '(3,3)');

    EXEC SQL DECLARE cur1 CURSOR FOR SELECT a, b FROM test_complex;
    EXEC SQL OPEN cur1;

    EXEC SQL WHENEVER NOT FOUND DO BREAK;

    while (1)
    {
        EXEC SQL FETCH FROM cur1 INTO :a, :b;
        printf("a=%s, b=%s\n", a.arr, b.arr);
    }

    EXEC SQL CLOSE cur1;

这个例子显示了如下结果:

a=(1,1), b=(3,3)

另一种方法是避免ECPG中用户自定义类型的直接使用，并且创建一个函数或者计算在 用户自定义类型和ECPG处理的原始类型之间的转换。 注意，然而那个类型计算，特别是隐式的那个，应该小心引入类型系统中。

比如，

CREATE FUNCTION create_complex(r double, i double) RETURNS complex
LANGUAGE SQL
IMMUTABLE
AS $$ SELECT $1 * complex '(1,0')' + $2 * complex '(0,1)' $$;

这个定义之后，下面

EXEC SQL BEGIN DECLARE SECTION;
double a, b, c, d;
EXEC SQL END DECLARE SECTION;

a = 1;
b = 2;
c = 3;
d = 4;

EXEC SQL INSERT INTO test_complex VALUES (create_complex(:a, :b), create_complex(:c, :d));

具有相同效果正如

EXEC SQL INSERT INTO test_complex VALUES ('(1,2)', '(3,4)');