1. DESCRIBE 语句

使用 DESCRIBE 语句可在执行准备好的语句之前获得有关其输出参数和其它功能的信息。

在 GBase 8s ESQL/C 中使用此语句。（另见 DESCRIBE INPUT 语句。）

语法

DESCRIBE 表结构 describe的用法及短语_sql

 

元素

描述

限制

语法

descriptor

系统描述符区域的名称

必须已分配系统描述符区域

引用字符串

descriptor_var

指定系统描述符区域的主变量

必须包含分配的系统描述符区域的名称

特定于语言的名称规则

sqlda_pointer

指向 sqlda 结构

不可以美元符号（$）或冒号（: ）开始。如果使用动态的 SQL ，则 sqlda 结构是必需的

请参阅 GBase 8s ESQL/C 程序员手册 中的 sqlda 结构

statement_id

准备好的 SQL 语句的语句标识符

必须在先前的 PREPARE 语句中定义

PREPARE 语句； 标识符

statement _id_var

包含 statement_id 的值的主变量

必须在先前的 PREPARE 语句中定义

特定于语言的名称规则

用法

DESCRIBE 可以在运行时提供有关准备好的语句的信息：

  1. 准备好的 SQL 语句的类型
  2. 是 UPDATE 还是 DELETE 语句包含 WHERE 子句
  3. 对于 EXECUTE 、EXECUTE FUNCTION 、EXECUTE PROCEDURE 、INSERT 、SELECT 或 UPDATE 语句，DESCRIBE 语句也返回值的数目、数据类型和大小，以及查询返回的列或表达式的名称。
  4. 对于 SELECT 语句，DESCRIBE 还返回查询返回的列或表达式的名称。

使用此信息，您可以编写代码来分配内存，从而控制检索到的值，并且在取得这些值之后显示或处理它们。

OUTPUT 关键字

OUTPUT 关键字指定只将有关准备好的语句的输出参数的信息存储在 sqlda 描述符区域中。如果省略这个关键字，DESCRIBE 可以返回输入参数，但这仅针对 INSERT 语句（如果在数据库服务器已初始化的环境中设置了 IFX_UPDDESC 环境变量，这种情况也适用于 UPDATE ）。

描述语句类型

DESCRIBE 语句从 PREPARE 语句获取一个语句标识符作为输入。当 DESCRIBE 语句执行时，数据库服务器会设置 sqlca 的 SQLCODE 字段的值，以指明语句类型（即语句开始处的关键字）。如果准备好的语句文本包含多个 SQL 语句，则 DESCRIBE 语句返回文本中第一个语句的类型。

SQLCODE 设置为 0 表示一个不带 INTO TEMP 子句的 SELECT 语句。这种情况是最普通的。对于任何其它 SQL 语句，SQLCODE 设置为一个正整数。您可以对照定义的常量名测试该数字。在 GBase 8s ESQL/C 中，常量名定义在 sqlstypes.h 头文件中。

DESCRIBE 语句（和 DESCRIBE INPUT 语句）对 SQLCODE 字段的使用不同于任何其它语句，当它成功执行时可能返回一个非零值。如果愿意，您可以修订标准的错误检查例程以使用这种行为。

检查 WHERE 子句的存在性

如果 DESCRIBE 语句检测到一个不带 WHERE 子句的 UPDATE 或 DELETE 语句的准备好的语句，则 DESCRIBE 语句将 sqlca.sqlwarn.sqlwarn4 变量设置为 W。

当 DELETE 或 UPDATE 语句中没有指定 WHERE 子句时，数据库服务器对整个表执行删除或更新操作。检查 sqlca.sqlwarn.sqlwarn4 变量以避免不期望的对表所做的全局更改。

描述带运行时参数的语句

如果准备好的语句包含这么一种参数。即在运行时将为该参数提供参数或参数数据类型的数目，那么您可以描述这些输入值。如果准备好的语句文本包括以下一个语句，那么 DESCRIBE 语句会返回一个对表中包括的每个列或表达式的描述：

  1. EXECUTE FUNCTION （或 EXECUTE PROCEDURE）
  2. INSERT
  3. SELECT （不带 INTO TEMP 子句）
  4. UPDATE

在 GBase 8s 中，必须首先按照 GBase 8s SQL 参考指南 中的描述设置 IFX_UPDDESC 环境变量 , 然后才可以使用 DESCRIBE 来获取有关 UPDATE 语句的信息。

描述包括以下信息：

  1. 列的数据类型，如表中定义
  2. 列的长度，以字节为单位
  3. 列或表达式的名称

对于准备好的 INSERT 或 UPDATE 语句，DESCRIBE 只返回动态参数（那些由问号（?）表示的参数）。但是，使用 OUTPUT 关键字会防止返回这些参数。

您可以将为返回的信息所设置的目的地指定为一个新的或现有的系统描述符区域，或是指定为一个指向 sqlda 结构的指针。

系统描述符区域符合 X/Open 标准。

使用 SQL DESCRIPTOR 关键字

使用USING SQL DESCRIPTOR 子句可将对准备好的语句列表的描述存储在先前分配的系统描述符区域中。

使用 INTO SQL DESCRIPTOR 子句创建新的系统描述符结构并将语句列表的描述存储在该结构中。

要将一个先前提到的语言描述到一个系统描述符区域，DESCRIBE 会以以下方式更新系统描述符区域：

  1. 将系统描述符区域中的 COUNT 字段设置为语句列表中值的数目。如果 COUNT 大于系统描述符区域中项描述符的数目，则会导致一个错误。
  2. 它设置系统描述符区域中的 TYPE 、LENGTH 、NAME 、SCALE 、PRECISION 和 NULLABLE 字段。
  3. 如果列具有不透明数据类型，则数据库服务器会设置项描述符的 EXTYPEID 、EXTYPENAME 、EXTYPELENGTH 、EXTYPEOWNERLENGTH 和 EXTYPEOWNERNAME 字段。
  4. 根据 TYPE 和 LENGTH 信息，为每个项描述符的 DATA 字段分配内存。

在执行 DESCRIBE 语句之后，SCALE 和 PRECISION 字段分别包含列的小数位和精度。如果在 SET DESCRIPTOR 语句中设置了 SCALE 和 PRECISION ，并且将 TYPE 设置为 DECIMAL 或 MONEY，则会修改 LENGTH 字段以调整十进制值的小数位和精度。如果没有将 TYPE 设置为 ECIMAL 或 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;

使用 INTO sqlda Pointer 子句 

使用 INTO sqlda_pointer 子句可为 sqlda 结构分配内存，并将它的地址存储在一个 sqlda 指针中。DESCRIBE 语句用描述信息填充分配的内存。不像 USING 子句，INTO 子句创建新的 sqlda 结构以存储来自 DESCRIBE 的输出。

DESCRIBE 语句将 sqlda.sqld 字段设置为语句列表中的值的数目。sqlda 结构也包含一个数据描述符的数组（sqlvar 结构），语句列表中的每个值各有一个相应的数据描述符。执行 DESCRIBE 语句之后，sqlda.sqlvar 结构便含有 sqltype 、sqllen 和 sqlname 字段集。

如果列具有不透明数据类型，则 DESCRIBE...INTO 会设置项描述符的 sqlxid 、sqltypename 、sqltypelen 、sqlownerlen 和 sqlownername 字段。

一旦程序中声明了 sqlda 指针，DESCRIBE 语句就会为该指针分配内存。但是，应用程序必须指定 sqlda.sqlvar.sqldata 字段的存储区域。