共用方式為


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 程式範例