更新日期：2024年09月11日
使用 DESCRIBE INPUT 语句可在执行一个准备好的语句之前返回输入参数信
息。
在 ESQL/C 中使用此语句。
语法
元素
描述
限制
语法
descriptor
系统描述符的名
称
必须已分配系统描述
符区域
引用字符串
descriptor_var
指定系统描述符
区域的主变量
必须包含分配的系统
描述符区域的名称
特定于语言的名
称规则
sqlda_pointer
指向一个 sqlda
结构
不可以美元符号
（$）或冒号（: ）
开始。如果使用动态
的 SQL ，则 sqlda
结构是必需的
请参阅 GBase
8s ESQL/C 程序
员手册 中的
sqlda 结构
statement_id
准备好的 SQL
语句的语句标识
符
必须在先前执行的
PREPARE 语句中定义
PREPARE 语句；
PREPARE 语句；
标识符
statement_var
包含
statement_id
的值的主变量
变量和
statement_id 都必
须声明
特定于语言的名
称规则
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 556
用法
DESCRIBE INPUT 和 DESCRIBE OUTPUT 语句可以将有关准备好的语句的信息返回
到 SQL 描述符区域（sqlda）：
对于 SELECT 、EXECUTE FUNCTION （或 PROCEDURE）、INSERT
或 UPDATE 语句，DESCRIBE 语句（不带 INPUT 关键字）返回返回
值的数目、数据类型和大小以及列或表达式的名称。
对于 SELECT 、EXECUTE FUNCTION 、EXECUTE PROCEDURE 、
DELETE 、INSERT 或 UPDATE 语句，DESCRIBE INPUT 语句返回准
备好的语句的所有输入参数。
提示： 考虑到程序同旧应用程序的兼容性，当前版本支持不带 INPUT 的
DESCRIBE 语句。在新的应用程序中，您应当使用 DESCRIBE INPUT 语句来提供
有关 WHERE 子句、子查询以及其它语法上下文动态参数的信息，这些都是在旧
格式的 DESCRIBE 中无法提供的信息。
使用此信息，您可以编写代码来分配内存，从而控制那些在取得之后可以显示或
处理的检索到的值。
在使用 DESCRIBE INPUT 获取有关 UPDATE 语句的信息时，不需要设置
IFX_UPDDESC 环境变量。
描述语句类型
该语句从 PREPARE 语句获取一个语句标识符作为输入。DESCRIBE INPUT 执
行后，sqlca 的 SQLCODE 字段的值指明语句类型（即语句开始处的关键字）。
如果准备好的对象包含多个 SQL 语句，则 DESCRIBE INPUT 语句返回文本中
第一个语句的类型。
SQLCODE 设置为 0 表示一个不带 INTO TEMP 子句的 SELECT 语句。这种情
况是最普通的。对于任何其它 SQL 语句，SQLCODE 设置为一个正整数。您可
以对照定义的常量名测试该数字。在 GBase 8s ESQL/C 中，常量名定义在
sqlstypes.h 头文件中。
DESCRIBE 语句 和 DESCRIBE INPUT 语句对 SQLCODE 字段的使用不同于任
何其它语句，在某些情况下可能返回一个非零值。如果愿意，您可以修订标准的
错误检查例程以使用这种行为。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 557
检查 WHERE 子句的存在性
如果 DESCRIBE INPUT 语句检测到一个准备好的对象包含不带 WHERE 子句的
UPDATE 或 DELETE 语句，则数据库服务器将 sqlca.sqlwarn.sqlwarn4 变量设
置为 W。
当 DELETE 或 UPDATE 语句中没有指定 WHERE 子句时，数据库服务器对整
个表执行删除或更新操作。DESCRIBE INPUT 执行后检查
sqlca.sqlwarn.sqlwarn4 变量以避免不期望的对表所做的全局更改。
使用动态运行时参数描述语句
如果准备好的语句指定了这么一种参数集合，即必须在运行时提供它的基数或数
据类型，那么您可以描述这些输入值。 如果准备好的语句文本中包括以下一个语
句，则 DESCRIBE INPUT 语句会返回对列表中包括的的每个列或表达式的描
述：
EXECUTE FUNCTION（或 EXECUTE PROCEDURE）
INSERT 或 SELECT
UPDATE 或 DELETE
该描述包括以下信息：
列的数据类型，如表中定义
列的长度，以字节为单位
列或表达式的名称
有关动态参数 （在准备好的语句中表示为问号（?）的参数）的信息
如果数据库服务器无法推断表达式参数的数据类型，DESCRIBE INPUT 语句会返
回 SQLUNKNOWN 作为数据类型。
您可以将为返回的信息所设的目的地指定为一个新的或现有的系统描述符区域，
或是指定为一个指向 sqlda 结构的指针。
使用 SQL DESCRIPTOR 关键字
使用 INTO SQL DESCRIPTOR 创建新的系统描述符结构并将准备好语句列表的
描述在此结构中。
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 558
使用 USING SQL DESCRIPTOR 子句将准备好的语句列表的描述存储在先前分配的
系统描述区域中。执行 DESCRIBE INPUT . . . USING SQL DESCRIPTOR 语句以以
下方式修改现有的系统描述区域：
基于 TYPE 和 LENGTH 信息为每个项描述符的 DATA 字段分配内
存。
将系统描述符区域中的 COUNT 字段设置为语句列表中值的数目。如果
COUNT 大于系统描述符区域中项描述符的数目，则会导致一个错误。
它设置系统描述符区域中的 TYPE 、LENGTH 、NAME 、SCALE 、
PRECISION 和 NULLABLE 字段。
对于不透明数据类型的列。DESCRIBE INPUT 语句会设置项目描述符的
EXTYPEID 、EXTYPENAME 、EXTYPELENGTH 、EXTYPEOWNERLENGTH
和 EXTYPEOWNERNAME 字段。
DESCRIBE INPUT 语句执行后，SCALE 和 PRECISION 字段分别包含列的小数
位和精度。如果在 SET DESCRIPTOR 语句中设置 SCALE 和 PRECISION，并
且将 TYPE 设置为 DECIMAL 或 MONEY，则会修改 LENGTH 字段以调整十
进制值的小数位和精度。如果没有将 TYPE 设置为 DECIMAL 或 MONEY，则
不设置 SCALE 和 PRECISION 的值，并且 LENGTH 不受影响。
您必须使用 SET DESCRIPTOR 语句修改系统描述符区域的信息，以显示要接收
描述的值在内存中的地址。可以将数据类型更改为另一种兼容的类型。此更改会
在取得数据值时引起数据转换的发生。
您不能在其它支持 USING SQL DESCRIPTOR 子句（例如 EXECUTE 、
FETCH 、OPEN 和 PUT ）的语句中使用系统描述符区域。
以下的示例显示了在 DESCRIBE 语句中的使用系统描述符。在第一个示例中，系
统描述符是带引号的字符串；在第二个示例中，它嵌入了变量名称。
main()
{
. . .
EXEC SQL allocate descriptor 'desc1' with max 3;
EXEC SQL prepare curs1 FROM 'select * from tab';
EXEC SQL describe curs1 using sql descriptor 'desc1';
}
EXEC SQL describe curs1 using sql descriptor :desc1var;
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 559
系统描述符区域必须符合 X/Open 标准。
使用 INTO sqlda Pointer 子句
使用 INTO sqlda_pointer 子句可为 sqlda 结构分配内存，并将它的地址存储在一
个 sqlda 指针中。DESCRIBE INPUT 语句用描述信息填充分配的内存。
DESCRIBE INPUT 语句将 sqlda.sqld 字段设置为语句列表中的值的数目。sqlda
结构也包含一个数据描述符的数组（sqlvar 结构），语句列表中的每个值各有一
个相应的数据描述符。执行 DESCRIBE 语句之后，sqlda.sqlvar 结构便含有
sqltype 、sqllen 和 sqlname 字段集。
如果列具有不透明数据类型，则 DESCRIBE INPUT...INTO 会设置项描述符的
sqlxid、sqltypename 、sqlownerlen 、sqltypelen 和 sqlownername 字段。
一旦程序中声明了 sqlda 指针，DESCRIBE INPUT 语句就会为该指针分配内存。
但是，应用程序必须指定 sqlda.sqlvar.sqldata 字段的存储区域。
描述集合变量
如果您使用 INTO 和 USING SQL DESCRIPTOR 子句，DESCRIBE INPUT 语句
提供有关集合变量的信息。
在打开 Select 或 Insert 游标后必须执行 DESCRIBE INPUT 语句。否则，
DESCRIBE INPUT 无法获取有关集合变量的信息，因为它是指定要使用的集合变
量的名称的 OPEN . . . USING 语句。
下一个 GBase 8s ESQL/C 程序段动态地选择 :a_set 集合变量的元素进入称为
desc1 的系统描述符区域：
EXEC SQL BEGIN DECLARE SECTION;
client collection a_set;
int i, set_count;
int element_type, element_value;
EXEC SQL END DECLARE SECTION;
EXEC SQL allocate collection :a_set;
EXEC SQL allocate descriptor 'desc1';
EXEC SQL select set_col into :a_set from table1;
EXEC SQL prepare set_id from
GBase 8s SQL 指南：语法
南大通用数据技术股份有限公司 560
'select * from table(?)';
EXEC SQL declare set_curs cursor for set_id;
EXEC SQL open set_curs using :a_set;
EXEC SQL describe set_id using sql descriptor 'desc1';do
{
EXEC SQL fetch set_curs using sql descriptor 'desc1';
...
EXEC SQL get descriptor 'desc1' :set_count = count;
for (i = 1; i <= set_count; i++)
{
EXEC SQL get descriptor 'desc1' value :i
:element_type = TYPE;
switch
{
case SQLINTEGER:
EXEC SQL get descriptor 'desc1' value :i
:element_value = data;
...
} /* end switch */
} /* end for */
} while (SQLCODE == 0);
EXEC SQL close set_curs;
EXEC SQL free set_curs;
EXEC SQL free set_id;
EXEC SQL deallocate collection :a_set;
EXEC SQL deallocate descriptor 'desc1';