符合性
推出版本：ODBC 3.0 標準合規：ISO 92
總結
SQLGetDiagRec 回傳包含錯誤、警告及狀態資訊的診斷記錄多個欄位的當前值。 與每次呼叫回傳一個診斷欄位的 SQLGetDiagField 不同， SQLGetDiagRec 會回傳多個常用的診斷記錄欄位，包括 SQLSTATE、原生錯誤碼及診斷訊息文字。
Syntax
SQLRETURN SQLGetDiagRec(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT RecNumber,
SQLCHAR * SQLState,
SQLINTEGER * NativeErrorPtr,
SQLCHAR * MessageText,
SQLSMALLINT BufferLength,
SQLSMALLINT * TextLengthPtr);
論點
HandleType
[輸入]句柄類型標識碼，描述需要診斷的句柄類型。 必須是下列其中一項：
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN句柄只能由驅動程式管理員和驅動程式使用。 應用程式不應該使用此句柄類型。 欲了解更多SQL_HANDLE_DBC_INFO_TOKEN資訊，請參閱《 ODBC駕駛員中培養 Connection-Pool 意識》。
處理
[輸入]診斷數據結構的句柄，HandleType所指示的類型。 如果 HandleType 是SQL_HANDLE_ENV，Handle 可以是共用或未共用的環境句柄。
RecNumber
[輸入]指出應用程式從中搜尋資訊的狀態記錄。 狀態記錄編號為 1。
SQLState
[輸出]指標指向一個緩衝區，回傳診斷記錄 RecNumber 的五字元 SQLSTATE 代碼（終止 NULL）。 前兩個字元表示職業;接下來三個代表子類別。 這些資訊包含在SQL_DIAG_SQLSTATE診斷領域中。 如需詳細資訊，請參閱 SQLSTATEs。
NativeErrorPtr
[輸出]指標指向緩衝區，回傳針對資料來源的原生錯誤碼。 這些資訊包含在SQL_DIAG_NATIVE診斷領域。
MessageText
[輸出]指標指向緩衝區，回傳診斷訊息文字串。 這些資訊包含在SQL_DIAG_MESSAGE_TEXT診斷領域。 關於字串格式，請參見 診斷訊息。
若 MessageText 為 NULL，TextLengthPtr 仍會回傳 MessageText 指向緩衝區中可返回的字元總數（不含字元資料的空終止字元）。
BufferLength
[輸入]*MessageText 緩衝區的字元長度。 診斷訊息文字沒有最大長度限制。
文字長度
[輸出]指標指向緩衝區，回傳 *MessageText 中可返回的字元總數（不含空終止字元所需的字元數）。 若可回傳的字元數大於 BufferLength，則 *MessageText 中的診斷訊息文字會被截斷為 BufferLength 減去空終止字元的長度。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。
Diagnostics
SQLGetDiagRec 不會自行發布診斷紀錄。 它會使用下列傳回值來報告其本身執行的結果：
SQL_SUCCESS：函式已成功傳回診斷資訊。
SQL_SUCCESS_WITH_INFO：*MessageText 緩衝區太小，無法容納所請求的診斷訊息。 未產生診斷紀錄。 為了判斷是否發生截斷，應用程式必須將 BufferLength 與實際可用位元組數比較，該位元組數寫入 *TextLengthPtr。
SQL_INVALID_HANDLE：handleType 和 Handle 表示的句柄不是有效的句柄。
SQL_ERROR：發生下列其中一項：
RecNumber 是負數或 0。
緩衝長度 小於零。
使用異步通知時，句柄上的異步操作尚未完成。
SQL_NO_DATA：RecNumber 大於 Handle 中所指定句柄的診斷記錄數目。 如果 Handle沒有診斷記錄，函式也會針對任何正 RecNumber 傳回SQL_NO_DATA。
評論
當先前對 ODBC 函式的呼叫回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，應用程式通常會呼叫 SQLGetDiagRec 。 然而，由於任何 ODBC 函式每次呼叫時都可以發布零或多個診斷記錄，應用程式可以在任何 ODBC 函式呼叫後呼叫 SQLGetDiagRec 。 應用程式可以多次呼叫 SQLGetDiagRec ，以回傳診斷資料結構中的部分或全部紀錄。 ODBC 對任何時候可儲存的診斷紀錄數量沒有限制。
SQLGetDiagRec 無法用於從診斷資料結構標頭回傳欄位。 （ RecNumber 參數必須大於 0。）應用程式應呼叫 SQLGetDiagField 來達成此目的。
SQLGetDiagRec 只會取得最近與 Handle 參數中指定的 handle 相關聯的診斷資訊。 若應用程式呼叫其他 ODBC 函式（除 SQLGetDiagRec、 SQLGetDiagField 或 SQLError）外，先前同一句柄呼叫中的任何診斷資訊將遺失。
應用程式可以透過迴圈、遞增 RecNumber（RecNumber）掃描所有診斷記錄，只要 SQLGetDiagRec 回傳 SQL_SUCCESS。 呼叫 SQLGetDiagRec 對標頭欄位與記錄欄位不具破壞性。 應用程式可以在之後再次呼叫 SQLGetDiagRec 以從記錄中取得欄位，只要期間除了 SQLGetDiagRec、 SQLGetDiagField 或 SQLError 外，沒有其他函式被呼叫。 應用程式也可以透過呼叫 SQLGetDiagField 取得SQL_DIAG_NUMBER欄位的值，然後呼叫 SQLGetDiagRec 來取得可用的診斷記錄總數。
關於診斷資料結構欄位的描述，請參見 SQLGetDiagField。 如需詳細資訊，請參閱 使用 SQLGetDiagRec 和 SQLGetDiagField 和 實作 SQLGetDiagRec 和 SQLGetDiagField。
呼叫非異步執行 API 的 API 會產生 HY010「函式順序錯誤」。 不過，異步操作完成之前，無法擷取錯誤記錄。
HandleType 自變數
每個句柄類型都可以有與其相關聯的診斷資訊。 HandleType 參數表示 Handle 參數的 handle 類型。
無法針對環境、連接、語句和描述項句柄傳回某些標頭和記錄字段。 那些欄位不適用的句柄會在 SQLGetDiagField 的「標頭欄位」和「記錄欄位」區塊中標示。
呼叫 SQLGetDiagRec 若 HandleType 為 SQL_HANDLE_SENV，則返回 SQL_INVALID_HANDLE，該 Handle 表示共用環境 handle。 然而，如果 HandleType 是 SQL_HANDLE_ENV，Handle 可以是共享或非共享環境的 handle。
相關函數
| 如需相關信息 | 看！ |
|---|---|
| 取得診斷記錄欄位或診斷標頭欄位 | SQLGetDiagField 函式 |