符合性
推出版本：ODBC 1.0 標準合規性：ODBC
總結
SQLNativeSQL 會回傳由驅動程式修改的 SQL 字串。
SQLNativeSQL 不會執行 SQL 陳述式。
Syntax
SQLRETURN SQLNativeSql(
SQLHDBC ConnectionHandle,
SQLCHAR * InStatementText,
SQLINTEGER TextLength1,
SQLCHAR * OutStatementText,
SQLINTEGER BufferLength,
SQLINTEGER * TextLength2Ptr);
論點
ConnectionHandle
[輸入] 連線控制代碼。
聲明正文
[輸入]SQL 文字串需要翻譯。
正文長度1
[輸入]*InStatementText 文字字串的字元長度。
出聲明正文
[輸出]指標指向緩衝區，回傳翻譯後的 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。
Diagnostics
當 SQLNativeSQL 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可透過呼叫 SQLGetDiagRec 取得對應的 SQLSTATE 值，並將 HandleType 為 SQL_HANDLE_DBC，Handle 為 ConnectionHandle 。 下表列出 SQLNativeSQL 常回傳的 SQLSTATE 值，並在此函式情境中解釋每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | Description |
|---|---|---|
| 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
相關函數
None.