命名SQL描述符区域

命名SQL描述符区域由头部描述符（Header）以及一个或多个条目描述符（Item Descriptor）构成。头部描述符存储与整个结果集相关的全局元数据，而每个条目描述符则精准描述结果行中某一具体列的属性与数据。

1. 分配与释放描述符。
   在使用SQL描述符区域之前，必须显式分配内存空间：

   EXEC SQL ALLOCATE DESCRIPTOR identifier;

   当不再需要这个描述符区域时，应及时释放：

   EXEC SQL DEALLOCATE DESCRIPTOR identifier;

2. 将结果集绑定至描述符。
   在提取游标数据时，可以使用INTO子句将查询结果直接填充至指定的描述符区域中：

   EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc;

   即使查询返回的结果集为空，该描述符区域仍会正确填充并保留该查询的列元数据信息。

   对于尚未执行的预编译语句，可以使用DESCRIBE得到其结果集的元数据：

   EXEC SQL BEGIN DECLARE SECTION; 
   char *sql_stmt = "SELECT * FROM table1"; 
   EXEC SQL END DECLARE SECTION;  
   
   EXEC SQL PREPARE stmt1 FROM :sql_stmt; 
   EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;

   在DESCRIBE和FETCH语句中，INTO与USING关键字作用相似：均用于接收并生成结果集及其对应的描述符元数据。

3. 检索描述符区域的元数据与数据。
   通过以下指令从头部获取全局信息并存入指定的宿主变量：

   EXEC SQL GET DESCRIPTOR name :hostvar = field;

   当前只定义了一个头部描述符区域COUNT，用于获取结果集中包含的总列数（存入整数型宿主变量）。

   要从特定列（第num列）中提取具体的属性或数据项，使用如下语法：

   EXEC SQL GET DESCRIPTOR name VALUE num :hostvar = field;

   num可以是一个字符整数或者一个包含整数的宿主变量。可能的类型如下：

   • CARDINALITY（整数）：结果集中的行数。
   • DATA：实际提取到的数据项（变量数据类型须与查询字段相匹配）。
   • DATETIME_INTERVAL_CODE（整数）：当TYPE是9时，DATETIME_INTERVAL_CODE将具有以下值之一：1表示DATE，2表示TIME，3表示TIMESTAMP，4表示TIME WITH TIME ZONE，5表示TIMESTAMP WITH TIME ZONE。
   • INDICATOR（整数）：空值指示符，用于标识该字段是否为NULL或数据被截断（0表示正常，-1表示NULL）。
   • LENGTH（整数）：以字符计的数据长度。
   • NAME(字符串)：列字段名称。
   • OCTET_LENGTH（整数）：以字节计的数据字符表达的长度。
   • PRECISION（整数）：数字类型的精度（用于类型numeric）。
   • RETURNED_LENGTH（整数）：以字符数计的实际返回数据长度。
   • RETURNED_OCTET_LENGTH（整数）：以字节计的数据字符表达的长度。
   • SCALE（整数）：数字类型的小数位数/比例（专用于numeric类型）。
   • TYPE（整数）：该列数据类型的底层数字编码。
4. 通过描述符设置输入参数。
   当需要手动构建描述符区域以向动态查询或游标提供动态输入参数时，可使用SET DESCRIPTOR指令绑定宿主变量：

   EXEC SQL SET DESCRIPTOR name VALUE numfield = :hostvar;

5. 使用数组宿主变量批量提取多行数据。
   在结合游标进行批量检索时，可以使用FETCH提取多行记录，并配合C语言数组类型的宿主变量一次性接收数据：

   EXEC SQL BEGIN DECLARE SECTION; 
   int id[5]; 
   EXEC SQL END DECLARE SECTION;  
   
   /* 批量提取5行数据填充至描述符 */
   EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc;  
   
   /* 将描述符中第1列的批量数据提取至数组宿主变量id中 */
   EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :id = DATA;