SQLGetDiagRec 函式

  • 發行項

一致性
引進版本：ODBC 3.0 標準合規性：ISO 92

摘要
SQLGetDiagRec 會傳回診斷記錄之多個欄位的目前值，其中包含錯誤、警告和狀態資訊。 不同于 每個呼叫傳回一個診斷欄位的 SQLGetDiagField ，SQLGetDiagRec 會傳回數個常用的診斷記錄欄位， 包括 SQLSTATE、原生錯誤碼和診斷訊息文字。

語法

  
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 驅動程式 中開發連線集區感知。

Handle
[輸入]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 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 MessageText 所指向的 緩衝區中傳回。

BufferLength
[輸入]字元中的 * MessageText 緩衝區長度。 診斷郵件內文的長度沒有上限。

TextLengthPtr
[輸出]緩衝區的指標，其中要傳回字元總數（不包括 Null 終止字元所需的字元數），以在 *MessageText 中 傳回。 如果可用傳回的字元數大於 BufferLength ，則 *MessageText 中的 診斷郵件內文會截斷為 BufferLength 減去 Null 終止字元的長度。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。

診斷

SQLGetDiagRec 不會自行張貼診斷記錄。 它會使用下列傳回值來報告其本身執行的結果：

  • SQL_SUCCESS：函式已成功傳回診斷資訊。

  • SQL_SUCCESS_WITH_INFO：* MessageText 緩衝區太小，無法保存要求的診斷訊息。 未產生診斷記錄。 若要判斷發生截斷，應用程式必須比較 BufferLength 與實際可用的位元組數目，這會寫入 * TextLengthPtr 。

  • SQL_INVALID_HANDLE：HandleType 和 Handle 所 指示的控制碼 不是有效的控制碼。

  • SQL_ERROR：發生下列其中一項：

    • RecNumber 為負數或 0。

    • BufferLength 小於零。

    • 使用非同步通知時，控制碼上的非同步作業尚未完成。

  • SQL_NO_DATA： RecNumber 大於 Handle 中所 指定控制碼的診斷記錄數目。 如果 Handle 沒有診斷記錄 ，函式也會針對任何正 RecNumber 傳回SQL_NO_DATA。

註解

當 ODBC 函式先前呼叫傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，應用程式通常會呼叫 SQLGetDiagRec 。 不過，因為每次呼叫 ODBC 函式時，任何 ODBC 函式都可以張貼零或多個診斷記錄，所以應用程式可以在任何 ODBC 函數呼叫之後呼叫 SQLGetDiagRec 。 應用程式可以多次呼叫 SQLGetDiagRec ，以傳回診斷資料結構中的部分或所有記錄。 ODBC 不會限制任何一次可儲存的診斷記錄數目。

SQLGetDiagRec 無法用來從診斷資料結構的標頭傳回欄位。 （The RecNumber 引數必須大於 0。）應用程式應該為此呼叫 SQLGetDiagField 。

SQLGetDiagRec 只會擷取最近與 Handle 引數中指定的 控制碼相關聯的診斷資訊。 如果應用程式呼叫另一個 ODBC 函式，但 SQLGetDiagRec 、 SQLGetDiagField 或 SQLError 除外 ，則相同控制碼上先前呼叫的任何診斷資訊都會遺失。

只要 SQLGetDiagRec 傳回SQL_SUCCESS，應用程式就可以迴圈、遞 增 RecNumber 來掃描所有診斷記錄。 對 SQLGetDiagRec 的 呼叫對標頭和記錄欄位不具破壞性。 只要 SQLGetDiagRec、SQLGetDiagField 或 SQLError 在過渡期間已呼叫 SQLGetDiagRec 、 SQLGetDiagField 或 SQLError ，應用程式 就可以 從記錄擷取欄位。 應用程式也可以呼叫 SQLGetDiagField 來擷取SQL_DIAG_NUMBER欄位的值，然後多次呼叫 SQLGetDiagRec ，以擷取可用的診斷記錄總數。

如需診斷資料結構欄位的描述，請參閱 SQLGetDiagField 。 如需詳細資訊，請參閱 使用 SQLGetDiagRec 和 SQLGetDiagField 和 實作 SQLGetDiagRec 和 SQLGetDiagField 。

呼叫非非同步執行 API 的 API 會產生 HY010「函式順序錯誤」。 不過，非同步作業完成之前，無法擷取錯誤記錄。

HandleType 引數

每個控制碼類型都可以有與其相關聯的診斷資訊。 HandleType 引數表示 Handle 引數的 控制碼類型。

無法針對環境、連接、語句和描述項控制碼傳回某些標頭和記錄欄位。 這些欄位不適用的控制碼會以 SQLGetDiagField 中的 [標頭欄位] 和 [記錄欄位] 區段來指出。

如果 HandleType 是SQL_HANDLE_SENV，則對 SQLGetDiagRec 的呼叫 會傳回SQL_INVALID_HANDLE，這表示共用環境控制碼。 不過，如果 HandleType 是SQL_HANDLE_ENV， Handle 可以是共用或未共用的環境控制碼。

如需下列資訊 請參閱
取得診斷記錄的欄位或診斷標頭的欄位 SQLGetDiagField 函式

另請參閱

ODBC API 參考
ODBC 標頭檔
ODBC 程式範例