SQLGetDiagField 函式

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

摘要
SQLGetDiagField 傳回診斷數據結構記錄的目前值，其中包含錯誤、警告和狀態資訊。

語法

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

參數

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。 如果 DiagIdentifier 自變數指出診斷標頭的任何欄位 ，則會忽略 recNumber。 如果沒有，它應該超過 0。

DiagIdentifier
[輸入]指出要傳回其值之診斷的欄位。 如需詳細資訊，請參閱中的<DiagIdentifier Argument>一節。

DiagInfoPtr
[輸出]要在其中傳回診斷信息的緩衝區指標。 數據類型取決於 DiagIdentifier的值。 如果 DiagInfoPtr 是整數類型，應用程式應該使用 SQLULEN 的緩衝區，並在呼叫此函式之前將值初始化為 0，因為某些驅動程式可能只會寫入較低 32 位或 16 位的緩衝區，並將較高順序位保持不變。

如果 DiagInfoPtr 為 NULL，StringLengthPtr 仍然會傳回可用 DiagInfoPtr所指向之緩衝區中傳回的位元組總數（不包括 null 終止字元）。

BufferLength
[輸入]如果 DiagIdentifier 是 ODBC 定義的診斷，且 DiagInfoPtr 指向字元字串或二進位緩衝區，則此自變數應該是 *DiagInfoPtr長度。 如果 diagIdentifier 為 ODBC 定義的欄位，而 *DiagInfoPtr 為整數，則會忽略 BufferLength 。 如果 *DiagInfoPtr 中的值是 Unicode 字串串（呼叫 SQLGetDiagFieldW時），BufferLength 自變數必須是偶數。

如果 DiagIdentifier 是驅動程式定義的欄位，則應用程式會藉由設定 bufferLength 自變數，將字段的本質設定為 Driver Manager。 BufferLength 可以有下列值：

• 如果 diagInfoPtr 是字元字串的指標，BufferLength 是字串或SQL_NTS的長度。

• 如果 diagInfoPtr 是二進位緩衝區的指標，則應用程式會將SQL_LEN_BINARY_ATTR（長度）巨集的結果放在 bufferLength。 這會在 BufferLength 中放置負值。

• 如果 DiagInfoPtr 是字元字串或二進位字串以外的值指標，BufferLength 應該具有值SQL_IS_POINTER。

• 如果 *DiagInfoPtr 包含固定長度的數據類型，BufferLength 會視需要SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT或SQL_IS_USMALLINT。

StringLengthPtr
[輸出]緩衝區的指標，用於傳回字元數據之 *DiagInfoPtr中傳回的位元組總數（不包括 Null 終止字元所需的位元組數目）。 如果可用的位元組數目大於或等於 BufferLength，則 *DiagInfoPtr 中的文字會截斷為 BufferLength 減去 null 終止字元的長度。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE或SQL_NO_DATA。

診斷

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

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

• SQL_SUCCESS_WITH_INFO： *DiagInfoPtr 太小，無法保留要求的診斷字段。 因此，診斷欄位中的數據已截斷。 若要判斷發生截斷，應用程式必須將 BufferLength 與實際可用的位元組數目進行比較，這會寫入 *StringLengthPtr。

• SQL_INVALID_HANDLE：handleType 和 Handle 表示的句柄不是有效的句柄。

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

  • DiagIdentifier 自變數不是其中一個有效值。

  • DiagIdentifier 自變數SQL_DIAG_CURSOR_ROW_COUNT、SQL_DIAG_DYNAMIC_FUNCTION、SQL_DIAG_DYNAMIC_FUNCTION_CODE或SQL_DIAG_ROW_COUNT，但 Handle 不是語句句柄。 （驅動程式管理員會傳回此診斷。）

  • 當 diagIdentifier 指出診斷記錄中的欄位時，recNumber 自變數為負數或 0。 標頭欄位會忽略 recNumber 。

  • 要求的值為字元字串，BufferLength 小於零。

  • 使用異步通知時，句柄上的異步操作尚未完成。

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

評論

應用程式通常會呼叫 SQLGetDiagField，以達成三個目標之一：

1. 當函式呼叫傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時取得特定錯誤或警告資訊（或 sqlBrowseConnect 函式的 SQL_NEED_DATA）。

2. 若要使用呼叫 sqlExecute、SQLExecDirect、SQLBulkOperations或 SQLSetPos SQL_DIAG_ROW_COUNT 或 SQLSetPos 或判斷目前開啟數據指標中存在的數據列數目，判斷數據源中受影響的數據列數目。 如果驅動程式可以提供此資訊（從SQL_DIAG_CURSOR_ROW_COUNT標頭字段）。

3. 若要判斷呼叫 SQLExecDirect 或 SQLExecute （從 SQL_DIAG_DYNAMIC_FUNCTION 和 SQL_DIAG_DYNAMIC_FUNCTION_CODE 標頭字段 執行的函式）。

每次呼叫 ODBC 函式時，任何 ODBC 函式都可以張貼零或多個診斷記錄，因此應用程式可以在任何 ODBC 函數呼叫之後呼叫 SQLGetDiagField。 任何一次都可以儲存的診斷記錄數目沒有任何限制。 SQLGetDiagField 只會擷取最近與 Handle 自變數中指定的診斷數據結構相關聯的診斷資訊。 如果應用程式呼叫 SQLGetDiagField 或 SQLGetDiagRec以外的 ODBC 函式，則會遺失先前具有相同句柄之呼叫的任何診斷資訊。

只要 SQLGetDiagField 傳回 SQL_SUCCESS，應用程式就可以藉由 遞增 recNumber來掃描所有診斷記錄。 狀態記錄的數目會在 [SQL_DIAG_NUMBER標頭] 欄位中指出。 SQLGetDiagField 的呼叫對標頭和記錄欄位不具破壞性。 應用程式可以在稍後再次呼叫 SQLGetDiagField，以從記錄擷取字段，只要診斷函式以外的函式尚未在過渡期間呼叫，這會在相同的句柄上張貼記錄。

應用程式可以隨時呼叫 SQLGetDiagField 以傳回任何診斷字段，但 SQL_DIAG_CURSOR_ROW_COUNT 或 SQL_DIAG_ROW_COUNT 除外，如果 Handle 不是語句句柄，則會傳回SQL_ERROR。 如果未定義任何其他診斷欄位，則呼叫 sqlGetDiagField 會傳回SQL_SUCCESS（如果沒有遇到其他診斷），而且會傳回字段未定義的值。

如需詳細資訊，請參閱 使用 SQLGetDiagRec 和 SQLGetDiagField 和 實作 SQLGetDiagRec 和 SQLGetDiagField。

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

HandleType 自變數

每個句柄類型都可以有與其相關聯的診斷資訊。 HandleType 自變數指出 handle句柄類型的句柄類型。

無法針對環境、連接、語句和描述項句柄傳回某些標頭和記錄字段。 下列「標題欄位」和「記錄欄位」區段中會指出不適用欄位的句柄。

如果 HandleType 是SQL_HANDLE_ENV，Handle 可以是共用或未共用的環境句柄。

任何驅動程式特定的標頭診斷字段都不應該與環境句柄相關聯。

為描述項句柄定義的唯一診斷標頭欄位是SQL_DIAG_NUMBER和SQL_DIAG_RETURNCODE。

DiagIdentifier 自變數

這個自變數表示診斷數據結構所需的欄位標識碼。 如果 RecNumber 大於或等於 1，則欄位中的數據會描述函式傳回的診斷資訊。 如果 RecNumber 為 0，則欄位位於診斷數據結構的標頭中，因此包含與傳回診斷資訊之函數調用相關的數據，而不是傳回特定信息的數據。

驅動程式可以在診斷數據結構中定義驅動程式特定的標頭和記錄欄位。

使用 ODBC 2*.x* 驅動程式的 ODBC 3*.x* 應用程式，只能使用 SQL_DIAG_CLASS_ORIGIN、SQL_DIAG_CLASS_SUBCLASS_ORIGIN、SQL_DIAG_CONNECTION_NAME、SQL_DIAG_MESSAGE_TEXT、SQL_DIAG_NATIVE、SQL_DIAG_NUMBER、SQL_DIAG_RETURNCODE、SQL_DIAG_SERVER_NAME SQL_DIAG_SERVER_NAME 的 DiagIdentif ier 自變數呼叫 SQLGetDiagField 或 SQL_DIAG_SQLSTATE。 所有其他診斷欄位都會傳回SQL_ERROR。

標頭欄位

下表所列的標頭字段可以包含在 DiagIdentifier 自變數中。

記錄欄位

下表所列的記錄欄位可以包含在 DiagIdentifier 自變數中。

動態函數位段的值

下表描述SQL_DIAG_DYNAMIC_FUNCTION和SQL_DIAG_DYNAMIC_FUNCTION_CODE的值，這些值會套用至呼叫 sqlExecute 或 SQLExecDirect所執行的每個 SQL 語句類型。 驅動程式可以將驅動程式定義的值新增至列出的值。

狀態記錄的順序

狀態記錄會根據數據列號碼和診斷類型，依序排列。 驅動程式管理員會決定最終順序，以傳回它所產生的狀態記錄。 驅動程式會決定要傳回其產生狀態記錄的最終順序。

如果驅動程式管理員和驅動程式都會張貼診斷記錄，驅動程式管理員會負責訂購這些記錄。

如果有兩筆以上的狀態記錄，則記錄的順序會先由數據列編號決定。 下列規則適用於依資料列判斷診斷記錄順序：

• 未對應至任何數據列的記錄會出現在對應至特定數據列的記錄前面，因為SQL_NO_ROW_NUMBER定義為 -1。

• 數據列號碼未知的記錄會出現在所有其他記錄前面，因為SQL_ROW_NUMBER_UNKNOWN定義為 -2。

• 對於所有與特定數據列相關的記錄，記錄會依 [SQL_DIAG_ROW_NUMBER] 字段中的值排序。 列出受影響第一個數據列的所有錯誤和警告，然後列出下一個數據列的所有錯誤和警告，依此列出。

在每個數據列內，或針對未對應至數據列或數據列號碼未知的所有記錄，或針對所有數據列號碼等於SQL_NO_ROW_NUMBER的記錄，列出的第一筆記錄是使用一組排序規則來決定。 在第一筆記錄之後，影響數據列的其他記錄順序未定義。 應用程式無法假設錯誤在第一筆記錄之後的警告之前。 應用程式應該掃描完整的診斷數據結構，以取得未成功呼叫函式的完整資訊。

下列規則可用來判斷數據列內的第一筆記錄。 排名最高的記錄是第一筆記錄。 在排名記錄時，不會考慮記錄的來源（驅動程式管理員、驅動程序、網關等等）。

• 錯誤 描述錯誤的狀態記錄中，其排名最高。 下列規則會套用至排序錯誤：

  • 指出交易失敗或可能的交易失敗超過所有其他記錄的記錄。

  • 如果兩個或多個記錄描述相同的錯誤條件，則 Open Group CLI 規格（類別 03 到 HZ）所定義的 SQLSTATE 會超過 ODBC 和驅動程式定義的 SQLSTATE。

• 實作定義的無數據值 描述驅動程式定義 No Data 值 （類別 02） 的狀態記錄具有第二高等級。

• 警告 描述警告 （類別 01） 的狀態記錄具有最低等級。 如果兩筆以上的記錄描述相同的警告條件，則警告 Open Group CLI 規格所定義的 SQLSTATE 與驅動程式定義的 SQLSTATE。

相關函式

另請參閱

ODBC API 參考
ODBC 頭檔