一致性
推出版本：ODBC 1.0 标准合规：ODBC
总结
SQLNativeSQL 返回的是驱动程序修改的 SQL 字符串。
SQLNativeSQL 不执行 SQL 语句。
Syntax
SQLRETURN SQLNativeSql(
SQLHDBC ConnectionHandle,
SQLCHAR * InStatementText,
SQLINTEGER TextLength1,
SQLCHAR * OutStatementText,
SQLINTEGER BufferLength,
SQLINTEGER * TextLength2Ptr);
Arguments
ConnectionHandle
[输入] 连接句柄。
声明正文
[输入]需要翻译的SQL文本字符串。
文本长度1
[输入]*声明内文本 字符串的字符长度。
声明正文
[输出]指向一个缓冲区，返回翻译后的SQL字符串。
如果 OutStatementText 是 NULL，TextLength2Ptr 仍然会返回 OutStatementText 指向的缓冲区中可返回的字符总数（不含字符数据的 null-终止字符）。
BufferLength
[输入]*OutStatementText 缓冲区中的字符数。 本文档的早期版本错误地暗示，即使 *InStatementText 中返回的值是Unicode字符串（调用 SQLNativeSqlW时），字符数必须为偶数。 没有这样的限制。 为了实现最佳互操作性，驱动程序编写者应预期该函数传递字符数，而应用程序编写者则建议始终使用偶数字符计数。
文本长度2Ptr
[输出]指向缓冲区，返回*OutStatementText中可返回的字符总数（不含空终止）。 如果可返回的字符数大于或等于 BufferLength，则 *OutStatementText 中的翻译 SQL 字符串会被截断为 BufferLength 减去空终止字符的长度。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。
诊断
当 SQLNativeSql 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值，HandleType 为 SQL_HANDLE_DBC，Handle 为 ConnectionHandle。 下表列出 了SQLNativeSQL 通常返回的SQLSTATE值，并在该函数的上下文中对每个SQLSTATE值进行了解释;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字符串数据，右截断 | 缓冲区 *OutStatementText 不够大，无法返回整个 SQL 字符串，因此 SQL 字符串被截断。 未截断的SQL字符串长度以*TextLength2Ptr形式返回。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 08003 | 连接未打开 | 连接 句柄 没有连接状态。 |
| 08S01 | 通信链接失败 | 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。 |
| 22007 | 日期/时间格式无效 | * InStatementText 包含一个转义子句，但日期、时间或时间戳值均为无效。 |
| 24000 | 游标状态无效 | 语句中提到的光标位于结果集开始之前或结果集结束之后。 该错误可能不会被原生DBMS光标实现的驱动程序返回。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY009 | 无效使用 null 指针 | （DM）*InStatementText 是一个空指针。 |
| HY010 | 函数序列错误 | （DM） 一个异步执行的函数被调用为连接 句柄 ，且在调用该函数时仍在执行。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY090 | 字符串或缓冲区长度无效 | （DM） 参数 TextLength1 小于0，但不等于SQL_NTS。 |
| （DM） 参数 BufferLength 小于 0，参数 OutStatementText 不是空指针。 | ||
| HY109 | 光标位置无效 | 当前光标行被删除或未被检索。 该错误可能不会被原生DBMS光标实现的驱动程序返回。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 连接句柄 关联的驱动程序不支持该函数。 |
Comments
以下是 SQLNativeSQL 可能返回的示例，针对包含标量函数CONVERT的输入SQL字符串。 假设数据源中的列 empid 类型为 INTEGER：
SELECT { fn CONVERT (empid, SQL_SMALLINT) } FROM employee
Microsoft SQL Server 的驱动程序可能会返回以下翻译后的 SQL 字符串：
SELECT convert (smallint, empid) FROM employee
ORACLE 服务器的驱动程序可能会返回以下翻译后的SQL字符串：
SELECT to_number (empid) FROM employee
Ingres 的驱动程序可能会返回以下翻译后的 SQL 字符串：
SELECT int2 (empid) FROM employee
相关函数
None.