宿主变量¶

宿主变量是指存放SQL语句输入、输出的变量，简称主变量。宿主变量必须在DECLARE段中说明。

宿主变量分类¶

根据主变量在程序中所起的作用，可以分为输入主变量和输出主变量。

一个SELECT或者FETCH语句的INTO子句中和DESCRIBE的USING子句中的主变量称为输出主变量，它们用于保存从后台输入库获得的列值。神通数据库把列值赋给相应的INTO子句中的输出主变量。

所有SQL语句中的其它主变量都称为输入主变量，应用程序把这些变量的值输入给神通数据库。例如，可以在INSERT语句的VALUES子句中和UPDATE语句的SET子句中使用输入主变量。它们也可以用在WHERE、HAVING和FOR子句中。输入主变量可以出现在一个SQL语句中所有允许值或者表达式出现的地方。

注解

在ORDER BY子句中，可以使用主变量，但是并不能得到用户预期的结果。比如，如下SQL语句:

strcpy(ord, "empnum");
EXEC SQL SELECT empname, empnum INTO :hname, :hnum
FROM employee ORDER BY :ord;

在ORDER BY子句中，包含了一个输入主变量:ord，它的值为"empnum"，用户希望根据empnum列值对结果表排序。然而，在这种情况下主变量值会经过系统的处理，在发给后台数据库时，已经在列名的前后加上了单引号，所以，后台数据库会因为无法识别该格式而报错——"Non-integer constant in ORDER BY"，用户可以在执行SELECT语句后通过调用sqlprint查看这个错误信息。

注解

不能用输入主变量提供SQL关键字或者数据库对象的名字。所以，在数据定义语句(DDL)中不能使用输入主变量，比如ALTER、CREATE和DROP语句。下面是一个用主变量输入表名的例子，这种使用方法是错误的：

EXEC SQL BEGIN DECLARE SECTION;
char htabname[20]; --主变量必须定义在DECLARE段中
EXEC SQL END DECLARE SECTION;
printf("Please input table name:\n");
gets(htabname);
EXEC SQL DROP TABLE :htabname; --不允许使用主变量

注解

如果需要在运行时改变数据库对象的名字，请使用动态SQL。详情请参见动态SQL语句。

在神通数据库执行一个包含输入主变量的SQL语句之前，必须先赋值给主变量。下面是一个简单的使用输入主变量的例子：

EXEC SQL BEGIN DECLARE SECTION;
int hnum;
char hname[20];
EXEC SQL END DECLARE SECTION;
hnum = 20;
strcpy(hname, "汤金森");
EXEC SQL INSERT INTO employee(hnum, hname)
VALUES(:hnum, :hname);

输入主变量在SQL语句中必须用冒号（:）做前缀，这是主变量的使用必须符合的准则之一。

宿主变量使用准则¶

一个宿主变量的使用必须符合如下准则：

必须在DECLARE段明确说明；
必须先说明后使用；
在SQL语句里必须以冒号（:）作前缀；
在C语句中不得以冒号作前缀；
不得与SQL保留字同名；
只能在允许使用常量的地方使用；
可以与一个指示变量相关（指示变量将在后一小节说明）；
不能在动态命令中使用宿主变量。

宿主变量类型¶

esql*C中合法的宿主变量类型见下表：

表 -1

类型	含义	说明
char	字符串类型	单个字符、一维或二维数组
varchar	变长字符串类型	一维或二维数组
long	长整型	标量或一维数组
int	整型	标量或一维数组
short	短整型	标量或一维数组
float	浮点型	标量或一维数组
double	双精度型	标量或一维数组
__int64	8字节整型	标量或一维数组(WINDOWS环境)
long long [int]	8字节整型	标量或一维数组 (LINUX环境)

注解

如果超过说明的维数，系统就会报错。因为系统不支持更高的维数。用户可以根据预处理报错进行相应的调整。