SQLGetLength 函数 (CLI)-检索字符串值的长度

检索在当前事务期间从服务器返回的大对象定位器 (作为访存或 SQLGetSubString() 调用的结果) 所引用的大对象值的长度。

规范：

  • CLI 2.1

语法

SQLRETURN  SQLGetLength   (SQLHSTMT          StatementHandle,  /* hstmt */
                           SQLSMALLINT       LocatorCType,
                           SQLINTEGER        Locator,
                           SQLINTEGER        *StringLength,
                           SQLINTEGER        *IndicatorValue);

函数参数

表 1. SQLGetLength 自变量
数据类型 自变量 使用 描述
SQLHSTMT StatementHandle 输入 语句句柄。 这可以是已分配但当前没有为其分配预编译语句的任何语句句柄。
SQLSMALLINT LocatorCType 输入 源 LOB 定位器的 C 类型。 这可能是:
  • SQL_C_BLOB_LOCATOR
  • SQL_C_CLOB_LOCATOR
  • SQL_C_DBCLOB_LOCATOR
SQLINTEGER 定位器 输入 必须设置为 LOB 定位器值。
SQLINTEGER * StringLength 输出 rgbValue 中返回的信息的长度 (以字节为单位)a (如果目标 C 缓冲区类型旨在用于二进制或字符串变量而不是定位器值)。

如果指针设置为 NULL ，那么将返回 SQLSTATE HY009。
SQLINTEGER * IndicatorValue 输出 始终设置为零。
注：
a
这是 DBCLOB 数据的字符。

用法

SQLGetLength() 可用于确定由 LOB 定位器表示的数据值的长度。 应用程序使用它来确定引用的 LOB 值的整体长度，以便可以选择用于获取部分或全部 LOB 值的相应策略。 长度由数据库服务器使用服务器代码页计算，因此如果应用程序代码页与服务器代码页不同，那么计算客户机上的空间需求可能存在一些复杂性。 如果需要，应用程序将需要允许代码页扩展。

Locator 参数可以包含任何有效的 LOB 定位器，这些定位器未使用 FREE LOCATOR 语句显式释放，也未隐式释放，因为创建该定位器的事务已结束。

语句句柄不得与任何预编译语句或目录函数调用相关联。

返回码

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_STILL_正在执行
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

表 2. SQLGetLength SQLSTAT
SQLSTATE 描述 说明
07006 无效的转换。 LocatorCType 和 Locator 的组合无效。
40003 08S01 通信链路故障。 在功能完成之前，应用程序与数据源之间的通信链路失败。
58004 意外的系统故障。 不可恢复的系统错误。
HY001 内存分配故障。 Db2® CLI 无法分配支持执行或完成该功能所需的内存。 应用程序进程有可能已用完进程级内存。 请参阅操作系统配置以获取有关进程级别内存限制的信息。
HY003 程序类型超出范围。 LocatorCType 不是 SQL_C_CLOB_LOCATOR ， SQL_C_BLOB_LOCATOR 或 SQL_C_DBCLOB_LOCATOR 之一。
HY009 参数值无效。 指向 StringLength 的指针为 NULL。
HY010 函数顺序错误。 指定的 StatementHandle 未处于 已分配 状态。

在 data-at-execute (SQLParamData()， SQLPutData()) 操作中调用了此函数。

在 BEGIN 复合和 END 复合 SQL 操作中调用了该函数。

对 StatementHandle 调用了异步执行函数 (而不是此函数) ，并且在调用此函数时仍在执行。
HY013 发生意外的内存处理错误。 Db2 CLI 无法访问支持执行或完成该功能所需的内存。
HYC00 驱动程序不支持。 应用程序当前已连接到不支持大对象的数据源。
0F001 LOB 标记变量当前不表示任何值。 为 Locator 指定的值未与 LOB 定位器相关联。

限制

当连接到不支持大对象的 Db2 服务器时，此功能不可用。 在函数类型设置为 SQL_API_SQLGETLENGTH 的情况下调用 SQLGetFunctions() ，并检查 fExists 输出参数以确定当前连接是否支持该函数。

示例

  /* get the length of the whole CLOB data */
  cliRC = SQLGetLength(hstmtLocUse,
                       SQL_C_CLOB_LOCATOR,
                       clobLoc,
                       &clobLen,
                       &ind);