更新日期：2024年09月11日
您的 GBase 8s ESQL/C 程序可操纵带有下表总结的 SQL 语句的系统描述符区域。
表 16. 可用于操纵系统描述符区域的 SQL 语句
SQL 语句
用途
请参阅
ALLOCATE
DESCRIPTOR
为系统描述符区域分配内存
为系统描
述符区域
分配内存
DESCRIBE...USING SQL
DESCRIPTOR
以关于列列表列的信息初始化系统描述符
区域
初始化系
统描述符
区域
GET DESCRIPTOR
从系统描述符区域的字段获得信息
指定与从
系统描述
符区域获
得值
SET DESCRIPTOR
对于要访问的数据库服务器，将信息放至系
统描述符区域内
指定与从
系统描述
符区域获
得值
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 511 -
表 17. 可用于操纵系统描述符区域的 SQL 语句：使用游标的 SELECT 和 EXECUTE FUNCTION 语句
SQL 语句
用途
请参阅
OPEN...USING SQL
DESCRIPTOR
FETCH...USING SQL
DESCRIPTOR
从指定的系统描述符区域取任何输入参数
将该行的内容放至系统描述符区域内
指定输入
参数值
将列值放
至系统描
述符区域
内
表 18. 可用于操纵系统描述符区域的 SQL 语句：仅返回一行的 SELECT 和 EXECUTE FUNCTION 语句
SQL 语句
用途
请参阅
EXECUTE...INTO SQL
DESCRIPTOR
将单个行的内容放至系统描述符区域内
将列值放
至系统描
述符区域
内
表 19. 可用于操纵系统描述符区域的 SQL 语句：非 SELECT 语句：
SQL 语句
用途
请参阅
EXECUTE...USING SQL
DESCRIPTOR
从指定的系统描述符区域取任何输入参数
指定输入
参数值
表 20. 可用于操纵系统描述符区域的 SQL 语句：使用插入游标的 INSERT 语句：
SQL 语句
用途
请参阅
PUT...USING SQL
DESCRIPTOR
将一行放至插入缓冲区内，从指定的系统描
述符区域获得列值
处理未知
的列列表
DEALLOCATE
DESCRIPTOR
当以其结束您的程序时，释放为系统描述符
区域分配的内存
释放分配
给系统描
述符区域
的内存
为系统描述符区域分配内存
要为系统描述符区域分配内存，请使用 ALLOCATE DESCRIPTOR 语句。
ALLOCATE DESCRIPTOR 语句执行下列任务：
它指定指定的描述符名称来标识此内存区域。在罗列在 表 1中的所有 SQL 语句中，
此名称是必须提供的标识符，来指定对其采取行动的系统描述符。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 512 -
它分配项描述符。在缺省情况下，它在系统描述符区域中分配 100 个项描述符。您
可以 WITH MAX 子句来更改此缺省值。
它将系统描述符区域中的 COUNT 字段初始化为分配的项描述符的数目。
重要： ALLOCATE DESCRIPTOR 不为列数据（DATA 字段）分配内存。由
DESCRIBE 语句根据需要来分配内存。
初始化系统描述符区域
DESCRIBE...USING SQL DESCRIPTOR 语句以关于准备好的语句的信息来初始化系
统描述符区域。
DESCRIBE...USING SQL DESCRIPTOR 语句采取下列行动：
它设置 COUNT 字段，其包含以数据初始化的项描述符的数目。
此值是列列表
（SELECT 和 INSERT）
中的列和表达式的数目，
或返回的值
（EXECUTE
FUNCTION）的数目。
它描述
（不带有 INTO TEMP）
的准备好的 SELECT 语句、
EXECUTE FUNCTION 或
INSERT 语句中每一未知的列。
DESCRIBE 语句为每一列初始化项描述符的字段，如下：
它基于 TYPE 和 LENGTH 信息为 DATA 字段分配内存。
它初始化 TYPE、LENGTH、NAME、SCALE、PRECISION 和 NULLABLE 字段来
从数据库提供关于列的信息。
它返回准备好的 SQL 语句的类型。
正如前面提到的，DESCRIBE 语句提供关于列列表的列的信息。因此，您通常在准备
好了的（不带有 INTO TEMP 子句的）SELECT、INSERT 或 EXECUTE FUNCTION 语
句之后使用此语句。
DESCRIBE 语句和输入参数
当您使用系统描述符区域来保存输入参数时，您不可使用 DESCRIBE 来初始化该系
统描述符区域。您的代码必须以 SET DESCRIPTOR 语句来定义输入函数，来显式地设置
系统描述符区域的恰当的字段。
DESCRIBE 语句与内存分配
当您使用系统描述符区域来保存准备好的 SQL 语句的列时，ALLOCATE
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 513 -
DESCRIPTOR 语句为每一列的项描述符分配内存，且 DESCRIBE...USING SQL
DESCRIPTOR 语句为每一项描述符的 DATA 字段分配内存。
然而，当您描述一准备好的 SELECT 语句，而该语句将数据从一列访存至 lvarchar
类型的主变量内时，DESCRIBE...USING SQL DESCRIPTOR 语句不为系统描述符区域的
DATA 字段分配内存。
在您将 lvarchar 数据访存至系统描述符区域之前，您必须显式地将内存指定到
DATA 字段来保存该列值，如下：
声明一大小恰当的 lvarchar 主变量。
请确保此变量不只是一个指针，而有与它相关联的内存。
以 SET DESCRIPTOR 语句将此主变量指定给 DATA 字段。
此 SET DESCRIPTOR 语句发生在 DESCRIBE...USING SQL DESCRIPTOR 语句之
后，但发生在 FETCH...USING SQL DESCRIPTOR 语句之前。
执行 FETCH...USING SQL DESCRIPTOR 语句来将列数据检索至系统描述符区域的
DATA 字段内。
下列代码段展示为 table1 表中的名为 lvarch_col 的 LVARCHAR 列分配内存的基
本步骤：
EXEC SQL BEGIN DECLARE SECTION;
lvarchar lvarch_val[50];
int i;
EXEC SQL END DECLARE SECTION;
EXEC SQL allocate descriptor 'desc';
EXEC SQL prepare stmt1 from 'select opaque_col from table1';
EXEC SQL describe stmt1 using sql descriptor 'desc';
EXEC SQL declare cursor curs1 for stmt1;
EXEC SQL open curs1;
EXEC SQL set descriptor 'desc' value 1
data = :lvarch_val, length = 50;
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 514 -
while (1)
{
EXEC SQL fetch curs1 using sql descriptor 'desc';
EXEC SQL get descriptor 'desc' value 1 :lvarch_val;
printf("Column value is %s\n", lvarch_val);
⋮
}
前面的代码段不执行异常处理。
指定与从系统描述符区域获得值
下列 SQL 语句允许您的程序访问系统描述符区域的字段：
SET DESCRIPTOR 语句将值指定给系统描述符区域的字段。
GET DESCRIPTOR 语句从系统描述符区域的字段获得值。
SET DESCRIPTOR 语句
要将值指定给系统描述符区域字段，请使用 SET DESCRIPTOR 语句。
您可使用 SET DESCRIPTOR 语句来：
设置 COUNT 字段，
来匹配您在系统描述符区域中提供其描述的项的数目。
此值通常
为 WHERE 子句中输入参数的数目。
EXEC SQL set descriptor sysdesc COUNT=:hostvar;
为您为其提供描述的每一列值设置项描述符字段。
EXEC SQL set descriptor sysdesc VALUE :item_numDESCRIP_FIELD=:hostvar;
在此示例中，item_num 是对应于期望的列的项描述符的数目，
DESCRIP_FIELD 是罗列在 表 1中的项描述符字段之一。
设置字段值来为 WHERE 子句中的输入参数提供值（指定输入参数值）
或在您使用 DESCRIBE...USING SQL DESCRIPTOR 语句来填充系统描述
符区域之后，来修改项描述符字段的内容（将列值放至系统描述符区域
内）。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 515 -
数据库服务器在 sqltypes.h 头文件中提供数据类型常量，来标识系统描述符区域的
TYPE 字段
（及可选的 ITYPE 字段）
中列的数据类型。
然而，
您不可在 SET DESCRIPTOR
语句中直接地指定数据类型常量。相反，请将该常量值指定给整数主变量，并在 SET
DESCRIPTOR 语句中指定此变量，如下：
EXEC SQL BEGIN DECLARE SECTION;
int i;
⋮
EXEC SQL END DECLARE SECTION;
⋮
i = SQLINT;
EXEC SQL set descriptor 'desc1' VALUE 1
TYPE = :i;
带有描述符的 lvarchar 指针主变量
如果您随同使用系统描述符区域的 FETCH 或 PUT 语句使用 lvarchar 指针主变量，
则您必须显式地在 SET DESCRIPTOR 语句中将类型设置为 124
（CLVCHARPTRTYPE 来
自 incl/esql/sqltypes.h）。下列示例说明：
EXEC SQL BEGIN DECLARE SECTION;
lvarchar *lv;
EXEC SQL END DECLARE SECTION;
/* where tab has lvarchar * column */
EXEC SQL prepare stmt from "select col from tab";
EXEC SQL allocate descriptor 'd';
/* The following describe will return SQLLVARCHAR for the
type of the column */
EXEC SQL describe stmt using sql descriptor 'd';
/* You must set type for *lv variable */
EXEC SQL set descriptor 'd' value 1 DATA = :lv, TYPE = 124;
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 516 -
EXEC SQL declare c cursor for stmt;
EXEC SQL open c;
EXEC SQL fetch c using sql descriptor 'd';
GET DESCRIPTOR 语句
GET DESCRIPTOR 语句从系统描述符区域字段获得值。
您可使用 GET DESCRIPTOR 语句来：
获得 COUNT 字段来确定在系统描述符区域中描述了多少个值。
EXEC SQL get descriptor sysdesc :hostvar=COUNT;
获得每一被描述的列的项描述符字段。
EXEC SQL get descriptor sysdesc VALUE :item_num
:hostvar=DESCRIP_FIELD;
在此示例中，item_num 是对应于期望的列的项描述符的数目，
DESCRIP_FIELD 是罗列在 表 1中的项描述符字段之一。
这些项描述符值通常是 SELECT、INSERT 或 EXECUTE FUNCTION 语句
中列的描述。还在 FETCH...USING SQL DESCRIPTOR 之后使用 GET
DESCRIPTOR，来将由数据库服务器返回的列值从系统描述符区域复制
至主变量内(将列值放至系统描述符区域内）。
主变量的数据类型必须与相关联的系统描述符区域字段的类型相兼容。当
您在 TYPE 字段中说明时，请确保您使用的数据类型值与您的环境相匹配。对
于一些数据类型，X/Open 值不同于 GBase 8s 值。
指定输入参数值
由于 DESCRIBE...USING SQL DESCRIPTOR 语句不分析 WHERE 子句，因此，您
的程序必须在系统描述符区域的字段中存储输入参数的数目、数据类型和值，来显式地描
述这些参数。
当您执行参数化的语句时，您必须以 USING SQL DESCRIPTOR 子句指定系统描述
符区域作为输入参数值的位置，如下：
对于 SELECT 的 WHERE 子句中的输入参数，请使用 OPEN...USING SQL
DESCRIPTOR 语句。
此语句处理顺序的、
滚动的、
保存或更新游标。
如果您确定该 SELECT
仅返回一行，则您可使用 EXECUTE...INTO...USING SQL DESCRIPTOR 语句，而不使用
游标。
对于非 SELECT 语句的 WHERE 子句中的输入参数，诸如 DELETE 或 UPDATE，
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 517 -
请使用 EXECUTE...USING SQL DESCRIPTOR 语句。
对于 INSERT 语句的 VALUES 子句中的输入参数，
请使用 EXECUTE...USING SQL
DESCRIPTOR 语句。如果该 INSERT 语句与插入游标相关联，则请改为使用
PUT...USING SQL DESCRIPTOR 语句。
将列值放至系统描述符区域内
当您动态地创建 SELECT 语句时，您不可使用 FETCH 的 INTO host_var 子句，因
为您不可在准备好的语句中命名主变量。要将列值访存至系统描述符区域内，请使用
FETCH 的 USING SQL DESCRIPTOR 子句，而不是 INTO 子句。FETCH...USING SQL
DESCRIPTOR 语句将每一列值放至它的项描述符的 DATA 字段内。
FETCH...USING SQL DESCRIPTOR 语句的使用假设存在与准备好的语句相关联的游
标。您必须总是使用 SELECT 语句的游标以及游标函数（返回多行的 EXECUTE
FUNCTION 语句）。然而，如果该 SELECT（或 EXECUTE FUNCTION）仅返回一行，
则您可忽略该游标，而以 EXECUTE...INTO SQL DESCRIPTOR 语句，将列值检索至系统
描述符区域内。
重要： 如果您执行返回多行的 SELECT 语句或用户定义的函数，且不将该语句与游
标相关联，
则您的程序生成运行时刻错误。
当您将单个 SELECT
（或 EXECUTE FUNCTION）
语句与游标相关联，则 GBase 8s ESQL/C 不生成错误。因此，总是将动态 SELECT 或
EXECUTE FUNCTION 语句与游标相关联，且使用 FETCH...USING SQL DESCRIPTOR
语句来将列值从此游标检索至系统描述符区域内，是一个很好的做法。
当列值在系统描述符区域中时，
您可使用 GET DESCRIPTOR 语句来将这些值从它们
的 DATA 字段转移至恰当的主变量。在运行时刻，您必须使用 LENGTH 和 TYPE 字段
来确定这些主变量的数据类型。您可能需要在 TYPE 字段中的 SQL 数据类型与保存该返
回值的主变量所需要的 GBase 8s ESQL/C 数据类型之间，执行数据类型或长度转换。
释放分配给系统描述符区域的内存
DEALLOCATE DESCRIPTOR 语句释放指定的系统描述符区域使用的内存。
被释放的
内存包括由项描述符使用的
（在 DATA 字段中）
保存数据的内存。
请确保仅在您不再需要
它之后，才释放系统描述符区域。不可重新使用被释放了的系统描述符区域。