SQLColAttribute -返回列属性

在线编辑

SQLColAttribute() 获取结果集的列的属性，并且还用于确定列数。 SQLColAttribute() 是 SQLDescribeCol() 函数的更可扩展的替代方法。

在调用此函数之前，必须调用 SQLPrepare() 或 SQLExecDirect() 。

如果应用程序不知道列的各种属性 (例如数据类型和长度) ，那么必须在 SQLBindCol()之前调用此函数 (或 SQLDescribeCol())。

Unicode (UTF-16) 等效: 此函数还可以与 Unicode (UTF-16) 字符集配合使用。 相应的 Unicode 函数是 SQLColAttributeW() 。有关 DB2® CLI 的 Unicode 支持的更多信息，请参阅 Db2 for i CLI 中的 Unicode 。

语法

SQLRETURN SQLColAttribute  (SQLHSTMT       StatementHandle,
                            SQLSMALLINT    ColumnNumber,
                            SQLSMALLINT    FieldIdentifier,
                            SQLPOINTER     CharacterAttributePtr,
                            SQLSMALLINT    BufferLength,
                            SQLSMALLINT    *StringLengthPtr,
                            SQLPOINTER     NumericAttributePtr);

函数自变量

表 1. SQLColAttribute 自变量
数据类型 自变量 使用 描述
SQLHSTMT StatementHandle 输入 语句句柄。
SQLSMALLINT ColumnNumber 输入 IRD 中要从中检索字段值的记录的编号。 此自变量对应于从 1 开始按从左到右顺序排序的结果数据的列号。 可以按任何顺序描述列。 可以在此自变量中指定列 0 ，但除 SQL_DESC_TYPE 和 SQL_DESC_OCTET_LENGTH 以外的所有值都将返回未定义的值。
SQLSMALLINT FieldIdentifier 输入 要返回的 IRD 的行 ColumnNumber 中的字段 表 2。
SQLPOINTER CharacterAttributePtr 输出 一个指向缓冲区的指针，如果该字段是字符串，那么该缓冲区将返回 IRD 的 ColumnNumber 行的 FieldIdentifier 字段中的值。 否则，将不使用该字段。
SQLSMALLINT BufferLength 输入 如果字段是字符串，存储 *CharacterAttributePtr 缓冲所需的 SQLCHAR 元素（或此函数的 Unicode 变体的 SQLWCHAR 元素）的数目。 否则，将忽略该字段。
SQLSMALLINT * StringLengthPtr 输出

指向缓冲区的指针，用于返回 *CharacterAttributePtr 中可用的字节总数（不包括字符数据的空终止字符字节数）。 对于字符数据，如果可返回的字节数大于或等于 BufferLength, ，*CharacterAttributePtr 中的描述符信息将被截断为 BufferLength 减去空终止字符的长度，并以 DB2 CLI 为空终止。 对于所有其他类型的数据，BufferLength 的值将被忽略，DB2 CLI 假定 *CharacterAttributePtr 的大小为 32 位。
SQLPOINTER NumericAttributePtr 输出 一个指向缓冲区的指针，如果该字段是数字描述符类型 (例如 SQL_DESC_COLUMN_LENGTH) ，那么该缓冲区将返回 IRD 的 ColumnNumber 行的 FieldIdentifier 字段中的值。 否则，将不使用该字段。
表 2。 字段标识描述符类型
描述符 类型 描述
SQL_DESC_AUTO_INCREMENT INTEGER 如果在将新行插入到表时可以自动递增列，那么这是 SQL_TRUE。 SQL_FALSE (如果列不能自动递增)。
SQL_DESC_BASE_COLUMN CHAR(128) 在其中构建此列的底层表中实际列的名称。

要检索此属性，必须将语句句柄或连接句柄的属性 SQL_ATTR_EXTENDED_COL_INFO 设置为 SQL_TRUE。
SQL_DESC_BASE_SCHEMA CHAR(128) 构建了此列的底层表的模式名称。

要检索此属性，必须将语句句柄或连接句柄的属性 SQL_ATTR_EXTENDED_COL_INFO 设置为 SQL_TRUE。
SQL_DESC_BASE_TABLE CHAR(128) 构建此列所基于的底层表的名称。

要检索此属性，必须将语句句柄或连接句柄的属性 SQL_ATTR_EXTENDED_COL_INFO 设置为 SQL_TRUE。
SQL_DESC_COLUMN_CCSID INTEGER ColumnNumber 中标识的列的 CCSID 将在 NumericAttributePtr 中返回。 这是结果集列数据的 CCSID ，因为在将该列绑定到应用程序之前，数据库知道该列数据的 CCSID ，并且可能不包含为该列返回到应用程序的数据的 CCSID。 例如，对于仅由基本表的列组成的结果集列，此字段将包含该列的 CCSID-与 SYSCOLUMNS 视图的 CCSID 列中显示的 CCSID 值相同。 另一方面，将根据表达式和运行语句的作业环境来设置派生结果集列 (例如包含表达式的列) 的 CCSID。 对于 CCSID 不适用的数据类型，将返回值 0。
SQL_DESC_COUNT INTEGER 结果集中的列数在 NumericAttributePtr 中返回。

SQL_DESC_DISPLAY_SIZE

SMALLINT

以字符形式显示数据所需的最大字节数在 NumericAttributePtr 中返回。
SQL_DESC_LABEL CHAR(128) 此列的标签 (如果存在)。 否则，为零长度字符串。

要检索此属性，必须将语句句柄或连接句柄的属性 SQL_ATTR_EXTENDED_COL_INFO 设置为 SQL_TRUE。
SQL_DESC_LENGTH INTEGER bytes 中会返回与列相关联的数据 NumericAttributePtr 的数量。

如果 ColumnNumber 中标识的列是基于字符的，例如 SQL_CHAR ， SQL_VARCHAR 或 SQL_LONG_VARCHAR ，那么将返回实际长度或最大长度。

如果列类型为 SQL_DECIMAL 或 SQL_NUMERIC ，那么 SQL_DESC_LENGTH 为 (precision * 256) + scale。 将返回此值，以便可以将同一值作为 SQLBindCol()上的输入进行传递。 还可以使用 SQL_DESC_PRECISION 和 SQL_DESC_SCALE 作为这些数据类型的单独值来获取精度和小数位。
SQL_DESC_NAME CHAR(128) ColumnNumber 中会返回 CharacterAttributePtr 列的名称。 如果列是表达式，那么返回的结果特定于产品。
SQL_DESC_NULLABLE SMALLINT 如果 ColumnNumber 标识的列可以包含空值，则在 NumericAttributePtr 中返回 SQL_NULLABLE。

如果限制列不接受空值，则在 NumericAttributePtr 中返回 SQL_NO_NULLS。
SQL_DESC_PRECISION SMALLINT 返回列的精度属性。
SQL_DESC_SCALE SMALLINT 将返回列的 scale 属性。
SQL_DESC_SEARCHABLE INTEGER 如果不能在 WHERE 子句中使用该列，那么这是 SQL_UNSEARCHABLE。

如果该列只能与 LIKE 谓词一起在 WHERE 子句中使用，那么这是 SQL_LIKE_ONLY。

如果列可以在 WHERE 子句中与除 LIKE以外的所有比较运算符一起使用，那么这是 SQL_ALL_EXCEPT_LIKE。

如果列可以在带有任何比较运算符的 WHERE 子句中使用，那么这是 SQL_SEARCHABLE。

要检索此属性，必须将语句句柄或连接句柄的属性 SQL_ATTR_EXTENDED_COL_INFO 设置为 SQL_TRUE。
SQL_DESC_TYPE_NAME CHAR(128) ColumnNumber中标识的列的 SQL 数据类型的字符表示。 这将在 CharacterAttributePtr 中返回。 SQL 数据类型的可能值列示在表 1中。 此外，还会返回用户定义的类型 (UDT) 信息。 The format for the UDT is <schema name qualifier><job's current separator><UDT name>.
SQL_DESC_TYPE SMALLINT ColumnNumber中标识的列的 SQL 数据类型将在 NumericAttributePtr中返回。 pfSqlType 的可能值列于 Table 1 中。
SQL_DESC_未命名 SMALLINT 如果 NAME 字段是实际名称，那么这是 SQL_NAMED; 如果 NAME 字段是实现生成的名称，那么是SQL_未命名。
SQL_DESC_UPDATABLE INTEGER 列由定义的常量的值描述:
SQL_ATTR_READONLY
SQL_ATTR_WRITE
SQL_ATTR_READWRITE_UNKNOWN

SQL_COLUMN_UPDATABLE 描述结果集中列的可更新性。 是否可以更新列可基于数据类型，用户特权以及结果集本身的定义。 如果不清楚是否可以更新列，那么应返回 SQL_ATTR_READWRITE_UNKNOWN。

要检索此属性，必须将语句句柄或连接句柄的属性 SQL_ATTR_EXTENDED_COL_INFO 设置为 SQL_TRUE。

用法

可以使用 SQLColAttribute() 来指定要为特定列接收的属性，而不是返回特定参数集 (例如 SQLDescribeCol())。 如果所需的信息是字符串，则在 CharacterAttributePtr 中返回。 如果所需的信息是一个数字，它将在 NumericAttributePtr 中返回。

虽然 SQLColAttribute() 允许将来进行扩展，但对于每个列，它需要更多调用来接收与 SQLDescribeCol() 相同的信息。

如果 FieldIdentifier 描述符类型不适用于数据库服务器，则根据描述符的预期结果，在 CharacterAttributePtr 中返回空字符串，或在 NumericAttributePtr 中返回 0。

列由数字标识 (从 1 开始按从左到右顺序编号) ，并且可以按任意顺序进行描述。

在将 FieldIdentifier 设置为 SQL_DESC_COUNT 的情况下调用 SQLColAttribute() 是调用 SQLNumResultCols() 以确定是否可以返回任何列的替代方法。

在调用 SQLColAttribute() 之前调用 SQLNumResultCols() 以确定结果集是否存在。

返回码

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA_FOUND

诊断

表 3. SQLColAttribute SQLSTAT
SQLSTATE 描述 说明
01004 数据已截断 请求的信息以空端字符串形式返回，其长度超出了 cbInfoValueMax 中指定的应用程序缓冲区长度。 参数 pcbInfoValue 包含所请求信息的实际（非截断）长度。
07009 无效的列号 为自变量 ColumnNumber 指定的值小于 1。
HY009 参数值无效 为自变量 FieldIdentifier 指定的值不等于 表 1中指定的值。

参数 CharacterAttributePtr, StringLengthPtr, 或 NumericAttributePtr 是一个空指针。
HY010 函数顺序错误 在对 StatementHandle调用 SQLPrepare() 或 SQLExecDirect() 之前，将调用该函数。
HY021 内部描述符无效 无法寻址或分配内部描述符，或者它包含无效的值。
HYC00 驱动程序不支持 Db2 for i CLI 无法识别数据库服务器针对列 ColumnNumber 返回的 SQL 数据类型。

引用