29.6. 使用宿主变量

29.6.1. 概述

在 C 程序和 SQL 语句之间传递数据在嵌入的 SQL 里特别简单。我们不用把数据贴到语句中， 这样必然会有各种复杂事情需要处理，比如正确给数值加引号等等，我们只需要在 SQL 语句里写上 C 变量的名字，前缀一个冒号即可。 比如：

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

这个语句引用了两个 C 变量，一个叫 v1，另一个叫 v2， 并且也使用一个普通的 SQL 字串文本，这样表明你并不局限于只使用某一种数据。

这种在 SQL 语句里插入 C 变量的方式在 SQL 语句里任何需要表达式的地方都可以用。 在 SQL 语句里，我们把引用的 C 变量叫做 宿主变量。

29.6.2. 声明段

要从程序中向数据库传递数据，比如，查询中的参数，或者从数据库里向程序传回的数据， 想包含这类数据的 C 变量必须在一个特殊的标记段里面声明，这样嵌入的 SQL 预处理器就会明白要做什么。

这个段以下面的代码开头

EXEC SQL BEGIN DECLARE SECTION;

以下面的代码结束

EXEC SQL END DECLARE SECTION;

在这两行之间，是普通的 C 变量声明，比如

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

在程序里你可以有任意多个声明段。

这些声明也同时以普通 C 变量的形式回显到输出文件中， 因此，我们不必再次声明他们。那些不准备在 SQL 命令里使用的变量可以像通常一样在这些特殊的段外面声明。

结构或者联合的定义也必须在 DECLARE 段中列出。 否则，预处理器就无法处理这些类型，因为它不知道定义。

特殊的类型 varchar 对每个变量都转化成一个叫 struct 的名字。像下面这样的声明：

varchar var[180];

转化成

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

这个结构适合于和 SQL 数据类型 varchar 的数据交互。

29.6.3. SELECT INTO 和 FETCH INTO

现在你应该能把你的程序生成的数据传递到 SQL 命令里面去了。但是你如何检索一个查询的结果呢？ 为了这个目的，嵌入的 SQL 提供了常用命令 SELECT 和 FETCH 的特殊变体。 这些命令有了特殊的 INTO 子句，声明检索出来的数值存储在哪个宿主变量里。

下面是一些例子：

/*
 * 假设表是这个：
 * 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;

所以，INTO 子句出现在选择列表和 FROM 子句之间。选择列表和 INTO 后面的列表的元素（也叫目标列表）个数必须相同。

下面是使用 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 (...);

这里的 INTO 子句出现在所有正常的子句后面。

这些方法只能一次检索一行。如果你需要处理可能多于一行的结果集， 那么你需要使用游标，就想我们第二个例子演示的那样。

29.6.4. 指示器

上面的例子不能处理空值。实际上，如果从数据库中抓到一条空值，那么上面的检索例子会抛出一个错误。 要能够向数据库中传递空值，或者从数据库中检索空值，你需要给每个包含数据的宿主变量后面附加一个额外的宿主变量。 这第二个宿主变量叫指示器，里面包含一个标志， 告诉我们数据是否为空，如果为空，那么真正的宿主变量的数值就可以忽略。 下面是一个能正确检索空值的例子：

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;

如果数值不是空，那么指示器变量 val_ind 将是零， 如果值是空，那么它将是负数。

指示器还有另外一个用途：如果它是正数，那么它标识数值不是空， 但是在数值存储到宿主变量里的时候被截断了。