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 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 OutStatementText 所指向的 緩衝區中傳回。
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時 ，藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_DBC 的 HandleType 和 ConnectionHandle 的 HandleHandle ，即可取得相關聯的 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 是 Null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 呼叫 ConnectionHandle 的 非同步執行函式，並在呼叫此函式時仍在執行。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 不正確字串或緩衝區長度 | （DM） 引數 TextLength1 小於 0，但不等於SQL_NTS。 |
| （DM） 引數 BufferLength 小於 0，而 Argument OutStatementText 不是 Null 指標。 | ||
| 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
相關函數
無。