使用 OPEN 语句来激活游标。
语法
元素
描述
限制
语法
cursor_id
游标的名称
必须已由 DECLARE
语句声明
标识符
cursor_id_var
主变量 = cursor_id
必须为字符数据类
型
特定于语言
descriptor
系统描述符区域的名
称
必须已分配
引用字符串
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 755
元素
描述
限制
语法
descriptor_var
标识系统描述符区域
的主变量
必须已分配了系统
描述符区域
引用字符串
parameter_var
在准备好的 SQL 语句
中以其内容替代问号
（?）占位符的主变量
必须为字符或集合
数据类型
特定于语言
sqlda_pointer
指向 sqlda 结构的指
针，定义数据类型和
在准备好的语句中要
代替问号（?）的值的
内存位置
不可以美元（$）符
号或冒号（:）开
头。您必须以动态
的 SQL 语句使用
sqlda 结构。
DESCRIBE
语句
用法
请随同 GBase 8s ESQL/C 或随同 SPL 使用此语句。
游标是与返回有序的值集的 SQL 语句相关联的标识符。OPEN 语句激活
DELARE 语句定义的游标。
可通过游标相关联的 SQL 语句进行归类：
Select 游标：与 SELECT 语句相关联的游标
Function 游标：与 EXECUTE FUNCTION（或 EXECUTE
PROCEDURE）语句相关联的游标
Insert 游标：与 INSERT 语句相关联的游标
Collection 游标：在集合变量上操作的 Select 或 Insert 游标。
在以 SPL 语言编写的 UDR 中，OPEN 语句仅可引用 Select 或 Function 游
标，且这些必须指定游标的标识符，而不是存储 cursor_id 的变量。OPEN 语句
不可引用 SPL 的 FOREACH 语句已经声明的直接游标。
依赖于游标相关联的语句，数据库服务器执行的特定操作有所不同。在 ESQL/C
中，当您将先前的语句与游标直接地关联（即，您未准备该语句，且将该语句标
识符与游标关联），OPEN 语句隐式地准备该语句。（这不是 SPL 例程中
OPEN 的特性，在 SPL 例程中 DECLARE 语句将游标与现有的准备好的语句的
标识符相关联，而不是直接地与 SQL 语句文本相关联。）
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 756
在符合 ANSI 的数据库中，如果您试图打开一已经打开的游标，则会收到错误代
码。
打开 Select 游标
当您打开以 SELECT… FOR UPDATE 语法创建的 Select 游标或更新游标时，将
SELECT 语句以 USING 子句中指定的任何值传递到数据库服务器。数据库服务
器处理该查询到定位或构造活动集合的第一行的点。下列示例展示 GBase 8s
ESQL/C 中的简单 OPEN 语句：
EXEC SQL declare s_curs cursor for select * from orders;
EXEC SQL open s_curs;
SPL 例程不可引用 OPEN 语句中的更新游标。
在事务内部打开 Update 游标
如果您正在带有显式事务的数据库中工作，则必须在事务内打开更新游标。如果
您使用 WITH HOLD 选项声明了该游标，则放弃此要求。
打开 Function 游标
当您打开 Function 游标时，随同在 USING 子句中指定的任何值，将 EXECUTE
FUNCTION（或 EXECUTE PROCEDURE）语句传递到数据库服务器。
将 USING 子句中的值作为参数传递给用户定义的函数。必须声明此用户定义的
函数来接受值。（如果先前准备了该语句，则在准备的时候将该语句传递给数据
库服务器。）数据库服务器执行该函数来指出它返回第一个值集的位置。
下列示例展示 GBase 8s ESQL/C 中的一个简单的 OPEN 语句：
EXEC SQL declare s_curs cursor for
execute function new_func(arg1,arg2)
into :ret_val1, :ret_val2;
EXEC SQL open s_curs;
重新打开 Select 或 Function 游标
仅当数据库服务器打开 Select 游标或 Function 游标时，它才计算在 OPEN 语句
的 USING 子句中指定的值。在打开游标时，在 USING 子句中对程序变量的后
续更改不更改游标的活动集合。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 757
在符合 ANSI 的数据库中，如果您试图打开一已打开的游标，则会收到错误代
码。
在不符合 ANSI 的数据库中，后续的 OPEN 语句关闭该游标，然后重新打开
它。当数据库服务器重新打开游标时，它基于 USING 子句中变量的当前值创建
新的活动集合。如果自从先前的 OPEN 语句以来这些变量已经更改，则重新打开
该游标可生成一完全不同的活动集合。
即使这些变量的值未改变，在下列情况下，该活动集合中的值也可不同：
如果用户定义的函数采用了与在 Function 游标上的先前的 OPEN 语句
不同的执行路径
自从 Select 游标上的先前的 OPEN 语句以来，如果表中的数据更改了
当数据库服务器打开 Select 或 Function 游标时，它可动态地处理大多数查询，
无需预先取回所有行。因此，如果其他用户在同一时间正在修改该用表正在处理
的表，则活动集合可能反映这些活动的结果。
对于一些查询，当数据库服务器打开该游标时，它计算整个活动集合。这些查询
包括具有下列特性的那些：
要求排序的查询：那些带有 ORDER BY 子句或带有 DISTINCT 或
UNIQUE 关键字的
要求散列的查询：那些带有结合或带有 GROUP BY 子句的
对于这些查询，在游标正在处理时其他用户对该表的任何更改都不反映在活动集
合中。
与 Select 和 Function 游标相关的错误
由于数据库服务器首次看到该查询，它可能检测错误。在这种情况下，它不实际
地返回数据的第一行，但它重置 SQLCODE 变量和 sqlca 的 sqlca.sqlcode 字
段。该值或为负数或为零，如下表所示。
代码值 含义
负数 在 SELECT 语句中检测到错误
零 SELECT 语句有效
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 758
与 ESQL/C 例程不同，SPL 例程没有对 sqlca 结构的直接访问。ESQL/C 例程
必须显式地调用内建的 SQLCODE 函数来访问与 OPEN 引用的游标相关联的
SELECT、EXECUTE FUNCTION 或 EXECUTE PROCEDURE 语句的返回代
码。
如果 SELECT、SELECT…FOR UPDATE、EXECUTE FUNCTION（或 EXECUTE
PROCEDURE）语句有效，但没有与其条件相匹配的行，则第一个 FETCH 返回值
100（SQLNOTFOUND），表示未找到行。
提示： 当您遇到 SQLCODE 错误时，还存在相应的 SQLSTATE 错误值。要了
解关于如何查看消息文本的信息，请参考 使用 SQLSTATE 错误状态代码。
打开 Insert 游标（ESQL/C）
当您打开 Insert 游标时，该游标将 INSERT 语句传递给数据库服务器，数据库
服务器检查关键字和列名称的有效性。数据库服务器还为插入缓冲区分配内存来
保留新数据。（请参阅 DECLARE 语句。）
对与 INSERT 语句相关联的游标的 OPEN 语句包括 USING 子句。
打开 Insert 游标的示例
下列 GBase 8s ESQL/C 示例展示带有 Insert 游标的 OPEN 语句：
EXEC SQL prepare s1 from
'insert into manufact values ('npr', 'napier')';
EXEC SQL declare in_curs cursor for s1;
EXEC SQL open in_curs;
EXEC SQL put in_curs;
EXEC SQL close in_curs;
重新打开 Insert 游标
当您重新打开已打开的 Insert 游标时，会有效地刷新插入缓冲区；存储在插入缓
冲区中的任何行都会写到数据库表内。数据库服务器首先关闭导致刷新的游标，
然后重新打开该游标。要获取关于如何检查错误和对插入的行计数的信息，请参
阅 错误检查。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 759
在符合 ANSI 的数据库中，如果您试图打开一已打开的游标，则会收到错误代
码。
打开 Collection 游标（ESQL/C）
您可声明集合变量上的 Select 和 Insert 游标。这些游标称为 Collection 游标。
您必须使用 OPEN 语句来激活这些游标。
使用 OPEN 语句的 USING 子句中的集合变量的名称。要获取更多关于以集合变
量使用 OPEN ... USING 的信息，请参阅 从集合游标访存 和 插入到 Collection
游标内。
USING 子句
当游标与一个包括问号（?）占位符和准备好的语句相关联时，需要 USING 子
句，如下：
在其 WHERE 子句中带有输入参数的 SELECT 语句
带有输入参数作为其用户定义的函数的参数的 EXECUTE FUNCTION
（或 EXECUTE PROCEDURE）语句
在其 VALUES 子句中带有输入参数的 INSERT 语句（在 ESQL/C
中）。
在 SPL 例程中，您必须指定这些参数作为 SPL 变量。
在 ESQL/C 中，您可以下列方式之一支持这些参数的值：
您可指定一个或多个主变量。
您可指定系统描述符区域。
您可指定指向 sqlda 结构的指针。
要获取更多信息，请参阅 PREPARE 语句。
如果您知道在运行时要提供的参数的数目和顺序及其数据类型，则可在程序中通
过该语句将所需参数定义为主变量。通过以 USING 关键字打开游标，您按位置
将参数传递给数据库服务器，后跟依其序列顺序的变量的名称。从左至右，这些
变量以一一对应的方式与 SELECT 或 EXECUTE FUNCTION（或 EXECUTE
PROCEDURE）语句问号（?）占位符相匹配。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 760
在变量的列表中，您不可包括 ESQL/C 的指示符变量。要使用指示符变量，您必
须包括 SELECT 或 EXECUTE FUNCTION（或 EXECUTE PROCEDURE）语句
文本作为 DECLARE 语句的一部分，而不是准备好的语句的标识符。
您必须为每一占位符提供一个主变量名称。每一变量的数据类型必须与准备好的
语句所需要的相应的类型相兼容。下列 GBase 8s ESQL/C 代码片段打开 Select
游标并在 USING 子句中指定主变量：
sprintf (select_1, "%s %s %s %s %s",
"SELECT o.order_num, sum(total price)",
"FROM orders o, items i",
"WHERE o.order_date > ? AND o.customer_num = ?",
"AND o.order_num = i.order_num",
"GROUP BY o.order_num");
EXEC SQL prepare statement_1 from :select_1;
EXEC SQL declare q_curs cursor for statement_1;
EXEC SQL open q_curs using :o_date, :o.customer_num;
下列示例展示在 GBase 8s ESQL/C 代码片段中，带有 EXECUTE FUNCTION 语
句的 OPEN 语句的 USING 子句：
stcopy ("EXECUTE FUNCTION one_func(?, ?)", exfunc_stmt);
EXEC SQL prepare exfunc_id from :exfunc_stmt;
EXEC SQL declare func_curs cursor for exfunc_id;
EXEC SQL open func_curs using :arg1, :arg2;
指定系统描述符区域（ESQL/C）
如果您不知道在运行时要提供的参数的数目及其数据类型，则可从系统描述符区
域关联输入值。系统描述符区域描述要代替问号（?）占位符的一个或多个值的数
据类型和内存位置。
系统描述符区域符合 X/Open 标准。
使用 SQL DESCRIPTOR 关键字来引入系统描述符区域的名称作为参数的位置。
系统描述符中的 COUNT 字段对应于准备好的语句中的动态参数的数目。
COUNT 的值必须小于或等于当以 ALLOCATE DESCRIPTOR 语句分配系统描述
符区域时指定的项描述符的数目。您可以 GET DESCRIPTOR 语句获取字段的
值，并以 SET DESCRIPTOR 语句设置该值。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 761
下列示例展示 OPEN ... USING SQL DESCRIPTOR 语句：
EXEC SQL allocate descriptor 'desc1';
...
EXEC SQL open selcurs using sql descriptor 'desc1';
正如该示例显示的，在 OPEN 语句中引用系统描述符区域之前，您必须分配它。
指定指向 sqlda 结构的指针（ESQL/C）
如果您不知道在运行时要提供的参数的数目，或其数据类型，可从 sqlda 结构关
联输入值。sqlda 结构罗列要替代问号（?）占位符的一个或多个值的数据类型和
内存位置。
使用 DESCRIPTOR 关键字来引入指向 sqlda 结构的指针，作为参数的位置。
sqlda 值指定在 sqlvar 的并发中描述的输入值的数目。此数目必须对应于准备好
的语句中的动态参数的数目。
指定指向 sqlda 结构的指针的示例
下列示例展示 OPEN ... USING DESCRIPTOR 语句：
struct sqlda *sdp;
...
EXEC SQL open selcurs using descriptor sdp;
使用 WITH REOPTIMIZATION 选项（ESQL/C）
使用 WITH REOPTIMIZATION 关键字来重新优化您的查询计划。当您准备
SELECT、EXECUTE FUNCTION 或 EXECUTE PROCEDURE 语句时，数据库
服务器使用查询计划来优化该查询。如果后来您修改与准备好的语句相关联的数
据，则可折中那个语句的查询的有效性。换句话说，如果您更改数据，您可能重
新优化您的查询。要确保您的查询的优化，可再次准备该语句，或使用 WITH
REOPTIMIZATION 选项再次打开游标。
通常您应使用 WITH REOPTIMIZATION 选项，因为它提供下列较再次准备语句的优
势：
仅重建查询计划，而不是整个语句
使用较少的资源
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 762
减少开销
需要更少的时间
在处理 OPEN 游标语句之前，WITH REOPTIMIZATION 选项强制数据库服务器
来优化查询设计计划。
下列示例使用 WITH REOPTIMIZATION 关键字：
EXEC SQL open selcurs using descriptor sdp with reoptimization;
OPEN 与 FREE 之间的关系
数据库服务器为准备好的语句分配资源并打开游标。如果您执行 FREE
statement_id 或 FREE statement_id_var 语句，则仍可打开与释放的语句 ID 相关
联的游标。然而，如果您以 FREE cursor_id 或 FREE cursor_id_var 语句释放资
源，则不可使用游标，除非您在此声明该游标。
类似地，如果您对一个或多个游标使用 SET AUTOFREE 语句，则当程序关闭特
定的游标时，数据库服务器自动地释放与游标相关的资源。在这种情况下，您不
可使用游标，除非您再次声明该游标。
对游标引用的表的 DDL 操作
各种 DDL 语句可删除、重命名或更改在定义游标的 DECLARE 语句中直接地
（或通过准备好的语句的标识符间接地）引用的表的模式。对该游标的后续的
OPEN 操作可能失败并报 error -710，或可能产生意外的结果。更改列的数目或列
的数据类型会有此影响，且对引用其模式已被修改的表的任何 SPL 例程，用户通
常必须重新发出 DESCRIBE 语句、PREPARE 语句和（对于与例程关联的游标）
UPDATE STATISTICS 语句。
然而，当为准备好了的对象和对引用表的 SPL 例程（例程引用那些 ALTER
TABLE、CREATE INDEX 或 DROP INDEX 操作已经修改了的表）启用了自动
重新编译时，如果添加或删除索引，则这些限制不适用。这是 GBase 8s 的缺省
的行为。要获取更多关于在模式更改之后启用或禁用自动重新编译的更多信息，
请参阅对 SET ENVIRONMENT 语句的 IFX_AUTO_REPREPARE 选项的描述。
要获取更多关于 AUTO_REPREPARE 配置参数的信息，请参阅 GBase 8s 管理员
参考手册。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 763
然而，当 AUTO_REPREPARE 配置参数和 IFX_AUTO_REPREPARE 会话环境
变量设置为禁用准备好的对象的重新编译时，将索引添加到在 DECLARE 语句中
直接地或间接地引用的表，可类似地使相关的游标无效。指定该无效游标的后续
的 OPEN 语句失败，即使它们包括 WITH REOPTIMIZATION 关键字。在禁用
自动重新编译时，如果将索引添加到与游标相关联的表，则在您打开该游标之
前，必须再次准备该语句并再次声明该游标。对于与调用 SPL 例程相关联的游
标，对于那些引用已经添加或删除了索引的表的例程，您必须运行 UPDATE
STATISTICS 语句。您不可简单地重新打开基于不再有效的准备好的语句的游
标。