SQLNativeSql 函数

  • 项目

一致性
引入的版本：ODBC 1.0 标准符合性：ODBC

摘要
SQLNativeSql 返回由驱动程序修改的 SQL 字符串。 SQLNativeSql 不执行 SQL 语句。

语法

  
SQLRETURN SQLNativeSql(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      InStatementText,  
     SQLINTEGER     TextLength1,  
     SQLCHAR *      OutStatementText,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   TextLength2Ptr);

自变量

ConnectionHandle
[输入] 连接句柄。

InStatementText
[输入]要翻译的 SQL 文本字符串。

TextLength1
[输入]*InStatementText 文本字符串的长度（以字符为单位）。

OutStatementText
[输出]指向要在其中返回已转换 SQL 字符串的缓冲区的指针。

如果 OutStatementText 为 NULL，TextLength2Ptr 仍将返回可用于在 OutStatementText 指向的缓冲区中返回的字符总数（不包括字符数据的 null 终止字符）。

BufferLength
[输入]*OutStatementText 缓冲区中的字符数。 本文档的过去版本错误地暗示，即使 *InStatementText 中返回的值是 Unicode 字符串（调用 SQLNativeSqlW 时），也必须有此字符计数。 没有这样的限制。 为了获得最佳互操作性，驱动程序编写器应期望将任何字符计数传递给此函数，而建议应用程序编写器始终使用偶数。

TextLength2Ptr
[输出]指向可在 *OutStatementText 中返回的字符总数（不包括 null 终止）的缓冲区的指针。 如果可返回的字符数大于或等于 BufferLength，则 *OutStatementText 中的已转换 SQL 字符串将被截断为 BufferLength 减去 null 终止字符的长度。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。

诊断

当 SQLNativeSql 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType of SQL_HANDLE_DBC 和 ConnectionHandle 句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。 下表列出了 SQLNativeSql 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。）
01004 字符串数据，右截断 缓冲区 *OutStatementText 不足以返回整个 SQL 字符串，因此 SQL 字符串被截断。 未构造的 SQL 字符串的长度在 *TextLength2Ptr 中返回。 （函数返回SQL_SUCCESS_WITH_INFO。）
08003 连接未打开 ConnectionHandle 未处于连接状态。
08S01 通信链接失败 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。
22007 日期/时间格式无效 *InStatementText 包含具有无效日期、时间或时间戳值的转义子句。
24000 游标状态无效 语句中引用的游标位于结果集的开头或结果集末尾之后。 具有本机 DBMS 游标实现的驱动程序可能不会返回此错误。
HY000 常规错误 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY009 无效使用 null 指针 （DM） *InStatementText 是空指针。
HY010 函数序列错误 （DM） 为 ConnectionHandle 调用异步执行函数，并在调用此函数时仍在执行。
HY013 内存管理错误 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。
HY090 字符串或缓冲区长度无效 （DM） 参数 TextLength1 小于 0，但不等于SQL_NTS。
（DM） 参数 BufferLength 小于 0，参数 OutStatementText 不是空指针。
HY109 光标位置无效 游标的当前行已被删除或未提取。 具有本机 DBMS 游标实现的驱动程序可能不会返回此错误。
HY117 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYT01 连接超时已过期 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驱动程序不支持此函数 （DM） 与 ConnectionHandle 关联的驱动程序不支持该函数。

注释

下面是 SQLNativeSql 对于包含标量函数 CONVERT 的以下输入 SQL 字符串可能返回的示例。 假定列 empid 在数据源中为 INTEGER 类型：

SELECT { fn CONVERT (empid, SQL_SMALLINT) } FROM employee

Microsoft SQL Server 的驱动程序可能会返回以下已翻译的 SQL 字符串：

SELECT convert (smallint, empid) FROM employee

ORACLE Server 的驱动程序可能会返回以下已翻译的 SQL 字符串：

SELECT to_number (empid) FROM employee

适用于 Ingres 的驱动程序可能会返回以下已翻译的 SQL 字符串：

SELECT int2 (empid) FROM employee

有关详细信息，请参阅 直接执行 和 准备的执行。

无。

另请参阅

ODBC API 参考
ODBC 标头文件