ODBC 診斷

請將此指引與 Microsoft ODBC 驅動程式 17 或 18 搭配使用。 它描述了 ODBC 診斷合約;並未定義特定版本的原生錯誤映射。

ODBC 函式會回傳描述該呼叫結果的程式碼。 診斷紀錄提供更多細節。 應用程式介面(API)可報告來自驅動程式管理器、驅動程式、資料來源或多個元件的紀錄。 不要把回傳碼、SQLSTATE、原生錯誤碼和訊息當作可以互換。

解讀返回碼

在處理輸出或決定是否重試前,先檢查回傳碼。 對於 SQL_ERROR 和 SQL_SUCCESS_WITH_INFO,從函式所用的 handle 中取得診斷結果。 其他回傳碼在功能合約允許時,也可能包含診斷紀錄。

回傳碼 含義與回應
SQL_SUCCESS 功能已順利完成。 檢查函式的輸出規格。
SQL_SUCCESS_WITH_INFO 函式已完成,並帶有警告資訊。 檢索每一個診斷記錄,檢查輸出是否完整、已轉換或已截斷。
SQL_ERROR 功能失敗。 在呼叫同一句柄上的另一個函式前,先取得所有診斷紀錄。
SQL_INVALID_HANDLE 函式偵測到空控制代碼或錯誤型別的控制代碼。 ODBC 不提供此退回代碼的診斷紀錄。 請查看功能參考以了解額外的控制代碼需求。
SQL_NO_DATA 目前已無更多操作資料可用。 請檢查函式參考,因為意義和任何狀態紀錄都取決於函式本身。

欲了解更多完整回傳碼約定資訊,請參閱 ODBC 回傳碼。

取回所有診斷紀錄

呼叫 SQLGetDiagRec,從記錄編號 1 開始取得狀態記錄。 持續直到函式返回 SQL_NO_DATA,或透過以 SQL_DIAG_NUMBER 呼叫 SQLGetDiagField,從標頭記錄 0 讀取記錄計數。 SQLGetDiagRec 回傳記錄的 SQLSTATE、原生錯誤碼及訊息文字。 需要其他標頭或記錄欄位時使用 SQLGetDiagField 。

不要在第一筆記錄後停止。 ODBC 元件可以在保留其他元件診斷資料的同時,新增包含自身層級資訊的狀態紀錄。 記錄順序與內容有助於辨識錯誤來源。

請儘快收集紀錄。 使用相同句柄的後續 ODBC 呼叫會取代其診斷區域,除了呼叫 SQLGetDiagRec、 SQLGetDiagField及舊有 SQLError 函式。 在新的程式碼中使用 SQLGetDiagRec 和 SQLGetDiagField。

SQLGetDiagRec 的訊息緩衝區太小時,可能會傳回 SQL_SUCCESS_WITH_INFO。 紀錄被回傳,但訊息內容被截斷。 檢查回報的文字長度,如果需要完整文字,請用較大緩衝區檢索訊息。 不要把這個回 SQLGetDiagRec 傳代碼和原本 ODBC 函式的回傳代碼搞混。

欲了解更多診斷檢索資訊,請參閱 診斷記錄、 使用 SQLGetDiagRec 與 SQLGetDiagField,以及 SQLGetDiagRec 與 SQLGetDiagField 參考資料。

收集 C++ 的診斷紀錄

使用這個 C++11 輔助工具搭配現有的 ODBC 句柄。 它呼叫 SQLGetDiagRecW 以收集 SQLSTATE、原生錯誤碼及 Unicode 訊息文字於記憶體中,但不會記錄訊息。

#ifdef _WIN32
#include <windows.h>
#endif
#include <sql.h>
#include <sqlext.h>
#include <algorithm>
#include <limits>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>

struct DiagnosticRecord {
    std::string sqlstate;
    SQLINTEGER native_error;
    std::vector<SQLWCHAR> message;
    bool message_truncated;
};

std::vector<DiagnosticRecord> ReadDiagnostics(SQLSMALLINT type, SQLHANDLE handle) {
    const SQLSMALLINT limit = (std::numeric_limits<SQLSMALLINT>::max)();
    std::vector<DiagnosticRecord> records;
    for (SQLINTEGER number = 1; ; ++number) {
        if (number > limit) {
            throw std::runtime_error("Diagnostic record number exceeds SQLSMALLINT.");
        }
        SQLWCHAR state[6] = {};
        SQLINTEGER native = 0;
        std::vector<SQLWCHAR> message(256);
        auto read = [&]() {
            return SQLGetDiagRecW(type, handle, static_cast<SQLSMALLINT>(number),
                state, &native, message.data(),
                static_cast<SQLSMALLINT>(message.size()), nullptr);
        };

        SQLRETURN result = read();
        if (result == SQL_NO_DATA) {
            return records;
        }
        if (result == SQL_SUCCESS_WITH_INFO) {
            message.resize(limit);
            result = read(); // Retrieve the same record, not the next one.
        }
        if (result != SQL_SUCCESS && result != SQL_SUCCESS_WITH_INFO) {
            throw std::runtime_error("SQLGetDiagRecW couldn't retrieve a diagnostic record.");
        }
        message.erase(std::find(message.begin(), message.end(), SQLWCHAR{0}), message.end());
        records.push_back({
            std::string(state, state + 5),
            native,
            std::move(message),
            result == SQL_SUCCESS_WITH_INFO
        });
    }
}

輔助器會以 SQLGetDiagRecW 可接受的最大正緩衝區長度重試截斷的訊息。 如果訊息仍然放不下,則保留可用文字並設定 message_truncated。 它會繼續到下一個紀錄,而不是把那個截斷當作診斷列表的最後。 當擷取失敗或記錄編號超出 API 的 SQLSMALLINT 範圍時,會拋出例外。

每個訊息包含 SQLWCHAR 個代碼單元,不含空終止符。 不要把它們重新解讀成 wchar_t,因為不同類型可能有不同的寬度。 當你需要處理或顯示訊息時,將它們轉換成應用程式的文字編碼。

在操作回傳錯誤或警告後立即呼叫助手。 此片段假設 statement 是一個有效且已準備好的語句句柄,且非同步執行被禁用:

#include <iostream>

SQLRETURN ExecuteWithDiagnostics(SQLHSTMT statement) {
    SQLRETURN result = SQLExecute(statement);
    if (result == SQL_ERROR || result == SQL_SUCCESS_WITH_INFO) {
        const auto records = ReadDiagnostics(SQL_HANDLE_STMT, statement);
        for (const auto& record : records) {
            std::cerr << "SQLExecute: SQLSTATE=" << record.sqlstate
                      << " native_error=" << record.native_error
                      << " message_truncated=" << record.message_truncated << '\n';
        }
    } else if (result == SQL_INVALID_HANDLE) {
        throw std::runtime_error("SQLExecute returned SQL_INVALID_HANDLE.");
    }
    return result;
}

包裝器會保留原始的回傳碼,包括 SQL_SUCCESS_WITH_INFO。 將相同的模式套用於其他 ODBC 呼叫,使用該操作相關的句柄類型與句柄。 根據該函式的契約處理其他回傳碼。

輸出會故意省略 record.message。 如果你需要在日誌中記錄訊息文字,請依照應用程式的資料政策在將其寫入日誌前將其遮蔽。 助手不會清理記憶體中儲存的訊息。

閱讀診斷欄位

這些欄位回答了不同的問題:

Field 它告訴你的
SQLSTATE 一個五字元的代碼,用來識別標準化的診斷病況。 它的類別是前兩個字元。
原生錯誤碼 一個特定於資料來源或 ODBC 元件的值。 它不是通用的錯誤編號,也不應該假設它是 SQL Server 的錯誤編號。
消息正文 易讀的說明。 用 SQLSTATE 和原生錯誤碼來讀取;不要把它當成穩定的機器可讀合約來解析。

驅動程式管理員、驅動程式與資料來源各自能產生診斷資料。 新增記錄的元件不得替換或遮蔽其他元件的錯誤或警告。 原生錯誤碼可能無法取得,或對元件產生的診斷沒有實質意義。 欲了解更多元件規則資訊,請參閱 診斷處理規則。 欲了解更多關於 SQLSTATE 類別與值的資訊,請參見 SQLSTATEs。

將記錄與函式回傳碼及操作一起使用。 例如,SQL_SUCCESS_WITH_INFO 表示該函數已完成,但並不保證每個輸出值都是完整的。 截斷警告需要你檢查回傳的長度,並決定是否要取回剩餘的資料。 欲了解更多資訊,請參見 資料長度、緩衝區長度與截斷。

蒐集可靠證據

對於支援案例,記錄函式名稱、句柄類型、回傳碼及每個診斷記錄。 包含驅動程式與驅動管理員版本、作業系統、架構及資料來源類型。 在儲存或分享輸出之前,先遮蔽憑證、存取權杖、連線字串祕密、查詢文字、參數值,以及個人或受管制的資料。 診斷訊息與追蹤日誌可包含應用資料。

將追蹤限制在你所需的最短重現步驟。 將日誌儲存在僅執行該應用程式的帳戶可存取的目錄中,並使用明確的日誌路徑,而非共用或暫時的預設。 複製結束後停止追蹤,不再需要時再移除追蹤檔案。

選擇描圖層

應用程式診斷與追蹤回答了不同的問題:

階層 它捕捉了什麼 用它來做
應用程式診斷 來自個別 ODBC 呼叫的回傳代碼與診斷記錄 找出失敗或回傳警告的函式,並保留其所有診斷欄位。
ODBC 驅動程式管理器追蹤 應用程式、驅動程式管理器與驅動程式之間的 ODBC API 呼叫 看看應用程式打了哪些電話,以及回傳的代碼。 追蹤引數可能會暴露敏感值。
特定驅動程式追蹤 內部驅動程式事件,當驅動程式記錄受支援的控制時 調查 API 追蹤無法顯示的驅動程式行為。 不要假設驅動程式管理員追蹤會啟用此功能。

在 Windows 上,ODBC 驅動程式管理員支援透過 ODBC 資料來源管理員的追蹤標籤以及 SQL_ATTR_TRACE 和 SQL_ATTR_TRACEFILE 屬性進行追蹤。 追蹤預設會依每位使用者分別進行。 全機追蹤需要本地管理員權限,並可擷取以其他本地身份執行的應用程式呼叫。 建議採用逐用戶追蹤,並在重現結束後立即停止。 欲了解更多資訊,請參閱 設定追蹤選項、 啟用追蹤及 SQLSetConnectAttr。

在 Linux 和 macOS 上,請參閱 Linux 和 macOS 上 ODBC 驅動程式的資料存取追蹤 ,以了解 unix ODBC 驅動程式管理器的設定。

現有的 Linux 與 macOS 程式設計指引 保留了歷史聲明,即內建診斷(BID)追蹤在 ODBC 驅動程式 17.3 之前並未被驗證。 那個備註並沒有描述目前驅動程式專屬的追蹤控制。 unixODBC 程序會擷取驅動程式管理員 API 呼叫,而非 BID 事件。