SQLDrivers 函式

一致性
引進的版本:ODBC 2.0 標準合規性:ODBC

摘要
SQLDrivers 會列出驅動程式描述和驅動程式屬性關鍵字。 此函式只會由驅動程式管理員實作。

語法

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);  

引數

EnvironmentHandle
[輸入]環境控制碼。

方向
[輸入]判斷驅動程式管理員是否會擷取清單中的下一個驅動程式描述(SQL_FETCH_NEXT),或搜尋是否從清單開頭開始(SQL_FETCH_FIRST)。

DriverDescription
[輸出]要在其中傳回驅動程式描述之緩衝區的指標。

如果 DriverDescription 為 Null, DescriptionLengthPtr 仍會傳回可供 DriverDescription 指向 的緩衝區中傳回的字元總數(不包括字元資料的 Null 終止字元)。

BufferLength1
[輸入]* DriverDescription 緩衝區的長度,以字元為單位。

DescriptionLengthPtr
[輸出]緩衝區的指標,要在其中傳回可在 * DriverDescription 中傳回的字元總數(不包括 Null 終止字元)。 如果可用傳回的字元數大於或等於 BufferLength1 ,則 * DriverDescription 中的驅動程式描述會截斷為 BufferLength1 減去 Null 終止字元的長度。

DriverAttributes
[輸出]要在其中傳回驅動程式屬性值組清單的緩衝區指標(請參閱「批註」)。

如果 DriverAttributes 為 Null, AttributesLengthPtr 仍會傳回可供 DriverAttributes 指向的緩衝區 中傳回的位元組總數(不包括字元資料的 Null 終止字元)。

BufferLength2
[輸入]* DriverAttributes 緩衝區的長度,以字元為單位。 如果 *DriverDescription 值是 Unicode 字串(呼叫 SQLDriversW 時), BufferLength 引數必須是偶數。

AttributesLengthPtr
[輸出]緩衝區的指標,用來傳回可用於在 * DriverAttributes 中傳回的位元組總數(不包括 Null 終止位元組)。 如果可用的位元組數目大於或等於 BufferLength2 ,則 * DriverAttributes 中的屬性值組清單會截斷為 BufferLength2 減去 Null 終止字元的長度。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLDrivers 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時 ,藉由呼叫 SQLGetDiagRec handleType 為 SQL_HANDLE_ENV 和 EnvironmentHandle 的 HandleHandle ,即可取得相關聯的 SQLSTATE 值。 下表列出 SQLDrivers 通常傳 回的 SQLSTATE 值,並說明此函式內容中的每個值;標記法 「(DM)」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明,否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 (DM) 驅動程式管理員特定的資訊訊息。 (函式會傳回SQL_SUCCESS_WITH_INFO。)
01004 字串資料,右截斷 (DM) 緩衝區 * DriverDescription 不夠大,無法傳回完整的驅動程式描述。 因此,描述已截斷。 完整驅動程式描述的長度會在 * DescriptionLengthPtr 中 傳回。 (函式會傳回SQL_SUCCESS_WITH_INFO。)

(DM) 緩衝區 * DriverAttributes 不夠大,無法傳回屬性值組的完整清單。 因此,清單已截斷。 屬性值組未解構清單的長度會在 * AttributesLengthPtr 中 傳回。 (函式會傳回SQL_SUCCESS_WITH_INFO。)
HY000 一般錯誤 發生錯誤,其中沒有特定的 SQLSTATE,也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 (DM) 驅動程式管理員無法配置支援執行或完成函式所需的記憶體。
HY010 函式順序錯誤 (DM) 已針對 StatementHandle 呼叫 SQLExecute SQLExecDirect SQLMoreResults ,並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前,會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫,因為基礎記憶體物件無法存取,可能是因為記憶體不足的情況。
HY090 不正確字串或緩衝區長度 (DM) 為引數 BufferLength1 指定的值小於 0。

(DM) 為引數 BufferLength2 指定的值小於 0 或等於 1。
HY103 不正確擷取程式 (DM) 為引數 Direction 指定的值不等於SQL_FETCH_FIRST或SQL_FETCH_NEXT。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 (DM) 如需暫停狀態的詳細資訊,請參閱 SQLEndTran 函式

註解

SQLDrivers 會傳回 * DriverDescription 緩衝區中的驅動程式描述。 它會以關鍵字/值組的清單傳回 * DriverAttributes 緩衝區中驅動程式的其他資訊。 除了 CreateDSN 以外,所有驅動程式的系統資訊中列出的所有關鍵詞都會傳回, 這用來提示建立資料來源,因此是選擇性的。 每個配對都會以 Null 位元組終止,而完整清單會以 Null 位元組終止(也就是兩個 Null 位元組會標示清單結尾)。 例如,使用 C 語法的檔案型驅動程式可能會傳回下列屬性清單(「\0」 代表 Null 字元):

FileUsage=1\0FileExtns=*.dbf\0\0  

如果 * DriverAttributes 不夠大而無法保存整個清單,則會截斷清單, SQLDrivers 會傳回 SQLSTATE 01004 (資料截斷),而清單的長度(不包括最終的 Null 終止位元組)則會在 * AttributesLengthPtr 中 傳回。

安裝驅動程式時,驅動程式屬性關鍵字會從系統資訊新增。 如需詳細資訊,請參閱 安裝 ODBC 元件

應用程式可以多次呼叫 SQLDrivers ,以擷取所有驅動程式描述。 驅動程式管理員會從系統資訊擷取此資訊。 當沒有其他驅動程式描述時, SQLDrivers 會傳回SQL_NO_DATA。 如果在 sqlDrivers 傳回SQL_NO_DATA之後立即以SQL_FETCH_NEXT呼叫,則會傳回第一個驅動程式描述。 如需應用程式如何使用 SQLDrivers 傳 回的資訊,請參閱 選擇資料來源或驅動程式

如果SQL_FETCH_NEXT第一次呼叫 SQLDrivers 時傳遞至 SQLDrivers SQLDrivers 會傳回第一個資料來源名稱。

因為 SQLDrivers 是在驅動程式管理員中實作,所以不論特定驅動程式的標準合規性為何,都支援所有驅動程式。

如需下列資訊 請參閱
探索和列出連線至資料來源所需的值 SQLBrowseConnect 函式
連線到資料來源 SQLConnect 函式
傳回資料來源名稱 SQLDataSources 函式
使用連接字串或對話方塊連接到資料來源 SQLDriverConnect 函式

另請參閱

ODBC API 參考
ODBC 標頭檔