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 仍會傳回字元總數 (排除字元資料的 null 終止字元，) 可在 DriverDescription指向的緩衝區中傳回。
BufferLength1
[輸入]*DriverDescription 緩衝區的長度，以字元為單位。
DescriptionLengthPtr
[輸出]要傳回字元總數的緩衝區指標， (排除可在 *DriverDescription中傳回的 null 終止字元) 。 如果傳回的字元數目大於或等於 BufferLength1，則 *DriverDescription 中的驅動程式描述會截斷為 BufferLength1 減去 Null 終止字元的長度。
DriverAttributes
[輸出]用來傳回驅動程式屬性值組清單的緩衝區指標， (請參閱「批註」) 。
如果 DriverAttributes 為 Null， AttributesLengthPtr 仍然會傳回位元組總數， (排除字元資料的 null 終止字元，) 可在 DriverAttributes指向的緩衝區中傳回。
BufferLength2
[輸入]*DriverAttributes 緩衝區的長度，以字元為單位。 如果在呼叫SQLDriversW) 時，*DriverDescription值為 Unicode 字串 (，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時，可以使用 SQL_HANDLE_ENV 的HandleType和 Handle ofEnvironmentHandle呼叫SQLGetDiagRec來取得相關聯的 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) SQLExecute、 SQLExecDirect或 SQLMoreResults 已針對 StatementHandle 呼叫並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有串流參數的資料之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 不正確字串或緩衝區長度 | (DM) 指定給 Argument BufferLength1 的值小於 0。 (DM) 指定給 Argument BufferLength2 的值小於 0 或等於 1。 |
| HY103 | 擷取程式碼無效 | (DM) 指定給 Direction 引數的值不等於SQL_FETCH_FIRST或SQL_FETCH_NEXT。 |
| HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | (DM) 如需暫止狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
註解
SQLDrivers 會傳回 *DriverDescription 緩衝區中的驅動程式描述。 它會以關鍵字/值組清單的形式傳回 *DriverAttributes 緩衝區中驅動程式的其他資訊。 除了 CreateDSN 之外，所有驅動程式的系統資訊中列出的所有關鍵詞都會傳回，除了 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傳回的資訊，請參閱 選擇資料來源或驅動程式。
如果在第一次呼叫 SQLDrivers 時將SQL_FETCH_NEXT傳遞給 SQLDrivers，SQLDrivers 會傳回第一個資料來源名稱。
由於 SQLDrivers 是在驅動程式管理員中實作，因此不論特定驅動程式的標準合規性為何，都支援所有驅動程式。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 探索和列出連接到資料來源所需的值 | SQLBrowseConnect 函數 |
| 連線到資料來源 | SQLConnect 函式 |
| 傳回資料來源名稱 | SQLDataSources 函式 |
| 使用連接字串或對話方塊連接到資料來源 | SQLDriverConnect 函式 |