本部分描述如何使用系统描述符区域来处理 INSERT...VALUES 语句。
要使用系统描述符区域来处理 INSERT 中的输入参数：
1. （以 PREPARE 语句）准备 INSERT 语句来给它一个语句标识符。
2. 以 ALLOCATE DESCRIPTOR 语句分配系统描述符区域。
3. 以 DESCRIBE...USING
SQL
DESCRIPTOR 语句来确定列的数目和数据
类型。
对于选择列表中的每一列，
DESCRIBE 语句填充一个项描述符。
以 GET DESCRIPTOR 语句来在主变量中保存未知的列的数目，其包含 COUNT 字
段的值。
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 532 -
4. 以 SET
DESCRIPTOR 语句将列设置为它们的值，其设置恰当的 DATA
和 VALUE 字段。该列值必须与它们相关联的列的数据类型相兼容。
如果您想要插入 NULL 值，则请将 INDICATOR 字段设置为 -1，并
不在 SET DESCRIPTOR 语句中指定任何 DATA 字段。
执行 INSERT 语句来将值插入至数据库内。
后面的部分演示如何执行简单的 INSERT 语句，其仅插入一行，以及使用插入游标
来从插入缓冲区插入几行的演示。
以 DEALLOCATE DESCRIPTOR 语句释放系统描述符区域。
执行简单的插入
下列步骤概括如何以系统描述符区域执行简单的 INSERT 语句：
（以 PREPARE 语句）准备 INSERT 语句，并给它一个语句标识符。
以 SET DESCRIPTOR 语句将该列设置为它们的值。
以 EXECUTE...USING SQL DESCRIPTOR 语句执行 INSERT 语句。
执行动态 INSERT 语句的样例程序
此样例程序展示如何执行动态 INSERT 语句。此 INSERT 语句不与插入游标相关联。
该程序将两个 TEXT 值插入至 txt_a 表内。
它从名为 desc_ins.txt 的命名的文件读取
该文本值。
然后，
该程序从此表选择列，
并将 TEXT 值存储在两个命名的文件 txt_out1 和
txt_out2 中。该程序说明使用系统描述符区域来处理列列表中的列。
=================================================================
======
1. EXEC SQL include locator;
2. EXEC SQL include sqltypes;
3. main()
4. {
5. EXEC SQL BEGIN DECLARE SECTION;
6. int ;
7. int cnt;
8. ifx_loc_t loc1;
9. ifx_loc_t loc2;
10. EXEC SQL END DECLARE SECTION;
11. EXEC SQL create database txt_test;
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 533 -
12. chkerr("CREATE DATABASE txt_test");
13. EXEC SQL create table txt_a (t1 text not null, t2 text);
14. chkerr("CREATE TABLE t1");
15. /* The INSERT statement could have been created at runtime. */
16. EXEC SQL prepare sid from 'insert into txt_a values (?, ?)';
17. chkerr("PREPARE sid");
=====================================================================
==
5 - 10 行
这些行声明主变量来保存要插入的列值（从用户获得）。
15 - 17 行
这些行为该语句组装字符串，并准备它作为 sid 语句标识符。该输入参数指定
INSERT 语句的找不到的行。INSERT 语句在此为硬编码，但可在运行时刻创建它。
=================================================================
======
18. EXEC SQL allocate descriptor 'desc';
19. chkerr("ALLOCATE DESCRIPTOR desc");
20. EXEC SQL describe sid using sql descriptor 'desc';
21. chkerr("DESCRIBE sid");
22. EXEC SQL get descriptor 'desc' :cnt = COUNT;
23. chkerr("GET DESCRIPTOR desc");
24. for (i = 1; i <= cnt; i++)
25. prsysdesc(i);
=====================================================================
==
18 和 19 行
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 534 -
要能够使用列的系统描述符区域，
您必须首先分配该系统描述符区域。
此 ALLOCATE
DESCRIPTOR 语句分配名为 desc 的系统描述符区域。
20 和 21 行
DESCRIBE 语句为 sid 标识的准备好的 INSERT 描述列。此 DESCRIBE 语句包括
USING SQL DESCRIPTOR 子句来指定 desc 系统描述符区域作为这些列描述的位置。
22 和 23 行
GET DESCRIPTOR 语句获得由 DESCRIBE 发现的列的数目（COUNT 字段）。在
cnt 主变量中存储此数目。
24 和 25 行
对于 INSERT 语句的列，此 for 循环详细检查项描述符。它使用 cnt 变
量来确定由 DESCRIBE 初始化的项描述符的数目。对于每一项描述符，
prsysdesc() 函数在主变量中保存诸如数据类型、长度和名称这样的信息。
=================================================================
======
26. loc1.loc_loctype = loc2.loc_loctype = LOCFNAME;
27. loc1.loc_fname = loc2.loc_fname = "desc_ins.txt";
28. loc1.loc_size = loc2.loc_size = -1;
29. loc1.loc_oflags = LOC_RONLY;
30. i = CLOCATORTYPE;
31. EXEC SQL set descriptor 'desc' VALUE 1
32. TYPE = :i, DATA = :loc1;
33. chkerr("SET DESCRIPTOR 1");
34. EXEC SQL set descriptor 'desc' VALUE 2
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 535 -
35. TYPE = :i, DATA = :loc2;
36. chkerr("SET DESCRIPTOR 2");
37. EXEC SQL execute sid using sql descriptor 'desc';
38. chkerr("EXECUTE sid");
=====================================================================
==
26 - 29 行
要插入 TEXT 值，该程序必须首先以 GBase 8s ESQL/C 定位符结构分配该值。loc1
定位符结构为 txt_a 表的 t1 列存储 TEXT 值；
loc2 是 txt_a 的 t2 列的定位符结构。
（参
见 13 行）
。
该程序包括 GBase 8s ESQL/Clocator.h 头文件
（1 行）
来定义 ifx_loc_t 结构。
两个 TEXT 值都位于名为 desc_ins.txt 的命名的文件（loc_loctype =
LOCFNAME）
中。
当您将 loc_size 字段设置为 -1 时，
该定位符结构告诉 GBase
8s ESQL/C 将 TEXT 值在单个操作中发送给数据库服务器。
30 - 36 行
第一个 SET DESCRIPTOR 语句设置 t1 列的项描述符中的 TYPE 和 DATA 字段
（VALUE 1）。该数据类型为 CLOCATORTYPE（在 GBase 8s ESQL/Csqltypes.h 头文件
中定义）来指示将列值存储在 GBase 8s ESQL/C 定位符结构中；将该数据设置为 loc1 定
位符结构。第二个 SET DESCRIPTOR 语句对 t2 列值执行相同的任务；它将它的 DATA
字段设置为 loc2 定位符结构。
37 和 38 行
数据库服务器以 EXECUTE...USING SQL DESCRIPTOR 语句执行 INSERT 语句，
来
从 desc 系统描述符区域获得新的列值。
=================================================================
======
39. loc1.loc_loctype = loc2.loc_loctype = LOCFNAME;
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 536 -
40. loc1.loc_fname = "txt_out1";
41. loc2.loc_fname = "txt_out2";
42. loc1.loc_oflags = loc2.loc_oflags = LOC_WONLY;
43. EXEC SQL select * into :loc1, :loc2 from a;
44. chkerr("SELECT");
45. EXEC SQL free sid;
46. chkerr("FREE sid");
47. EXEC SQL deallocate descriptor 'desc';
48. chkerr("DEALLOCATE DESCRIPTOR desc");
49. EXEC SQL close database;
50. chkerr("CLOSE DATABASE txt_test");
51. EXEC SQL drop database txt_test;
52. chkerr("DROP DATABASE txt_test");
53 EXEC SQL disconnect current;
54. }
55. chkerr(s)
56. char *s;
57. {
58. if (SQLCODE)
59. printf("%s error %d\n", s, SQLCODE);
60. }
=====================================================================
==
39 - 44 行
该程序使用 loc1 和 loc2 定位符结构来选择插入的值。将这些 TEXT 值读取至命名
的文件：t1 列（在 loc1 中）读取至 txt_out1，t2 列（在 loc2 中）读取至 txt_out2。
LOC_WONLY 的 loc_oflags 值意味着此 TEXT 数据重写这些输出文件中任何现有的数
据。
45 - 48 行
GBase 8s ESQL/C 编程指南
南大通用数据技术股份有限公司
- 537 -
FREE 语句（45 行）释放为 sid 准备好的语句分配的资源。一旦释放了准备好的语
句，在该程序中就不可再次使用它。DEALLOCATE DESCRIPTOR 语句（46 行）释放分
配给 desc 系统描述符区域的内存。
55 - 60 行
chkerr() 函数是一个简单的异常处理例程。它为非零值检查全局的
SQLCODE 变量。由于零指示 SQL 语句的成功执行，因此，每当发生运行时刻错
误时，都执行 printf()（58 行）。
执行与游标相关联的 INSERT
对于从插入缓冲区插入行的 INSERT 语句的列列表值，您的 GBase 8s
ESQL/C 程序必须仍使用 DESCRIBE 和 SET DESCRIPTOR 语句来使用系统描述符
区域。它还必须随同插入游标使用 PUT...USING
SQL
DESCRIPTOR 语句，如下：
准备 INSERT 语句，并以 DECLARE 语句将它与插入游标相关联。所有多行
INSERT 语句都必须有一声明了的插入游标。
以 OPEN 语句为 INSERT 语句创建该游标。
以 PUT 语句及其 USING SQL DESCRIPTOR 子句来将第一组列插入至插入缓冲区
内。
在此 PUT 语句之后，
将存储在指定的系统描述符区域中的列值存储在插入缓冲区中。
在循环内重复该 PUT 语句，直到没有更多的行要插入为止。
在插入所有行之后，退出该循环，并以 FLUSH 语句刷新该插入缓冲区。
以 CLOSE 语句关闭该插入游标。
您处理该插入游标的方式，与您处理与 SELECT 语句相关联的游标的方式
相同。