SQLDataSources 函式

  • 發行項

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

摘要
SQLDataSources 會傳回資料來源的相關資訊。 此函式只會由驅動程式管理員實作。

語法

  
SQLRETURN SQLDataSources(  
     SQLHENV          EnvironmentHandle,  
     SQLUSMALLINT     Direction,  
     SQLCHAR *        ServerName,  
     SQLSMALLINT      BufferLength1,  
     SQLSMALLINT *    NameLength1Ptr,  
     SQLCHAR *        Description,  
     SQLSMALLINT      BufferLength2,  
     SQLSMALLINT *    NameLength2Ptr);

引數

EnvironmentHandle
[輸入]環境控制碼。

方向
[輸入]決定驅動程式管理員傳回相關資訊的資料來源。 可為以下項目：

SQL_FETCH_NEXT（若要擷取清單中的下一個資料來源名稱）、SQL_FETCH_FIRST（從清單開頭擷取）、SQL_FETCH_FIRST_USER（擷取第一個使用者 DSN），或SQL_FETCH_FIRST_SYSTEM（擷取第一個系統 DSN）。

當 Direction 設定為SQL_FETCH_FIRST時 ，將 Direction 設為 SQL_FETCH_NEXT的 SQLDataSources 後續呼叫 會同時傳回使用者和系統 DSN。 當 Direction 設定為SQL_FETCH_FIRST_USER時 ，所有後續對 SQLDataSources 的呼叫都會將 Direction 設定為 SQL_FETCH_NEXT只傳回使用者 DSN。 當 Direction 設定為SQL_FETCH_FIRST_SYSTEM時 ，所有後續對 SQLDataSources 的呼叫 都會將 Direction 設定為 SQL_FETCH_NEXT只傳回系統 DSN。

ServerName
[輸出]要在其中傳回資料來源名稱之緩衝區的指標。

如果 ServerName 為 Null， NameLength1Ptr 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 ServerName 所指向的 緩衝區中傳回。

BufferLength1
[輸入]* ServerName 緩衝區的長度，以字元為單位;這不需要超過SQL_MAX_DSN_LENGTH加上 null 終止字元。

NameLength1Ptr
[輸出]緩衝區的指標，此緩衝區會傳回可在 * ServerName 中傳回的字元總數（不包括 Null 終止字元）。 如果可用傳回的字元數大於或等於 BufferLength1 ，則 * ServerName 中的資料來源名稱會截斷為 BufferLength1 減去 Null 終止字元的長度。

說明
[輸出]緩衝區的指標，用來傳回與資料來源相關聯之驅動程式的描述。 例如，dBASE 或 SQL Server。

如果 Description 為 Null， NameLength2Ptr 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 Description 所指向 的緩衝區中傳回。

BufferLength2
[輸入]* Description 緩衝區的字元長度。

NameLength2Ptr
[輸出]緩衝區的指標，用來傳回 * Description 中傳回的字元總數（不包括 Null 終止字元）。 如果可用傳回的字元數大於或等於 BufferLength2 ，則 * Description 中的驅動程式描述會截斷為 BufferLength2 減去 Null 終止字元的長度。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

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

SQLSTATE 錯誤 描述
01000 一般警告 （DM） 驅動程式管理員特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01004 字串資料，右截斷 （DM） 緩衝區 * ServerName 不夠大，無法傳回完整的資料來源名稱。 因此，名稱已截斷。 整個資料來源名稱的長度會在 * NameLength1Ptr 中 傳回。 （函式會傳回SQL_SUCCESS_WITH_INFO。）

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

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

註解

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

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

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

驅動程式會決定資料來源名稱如何對應至實際的資料來源。

如需下列資訊 請參閱
探索和列出連線至資料來源所需的值 SQLBrowseConnect 函式
連線到資料來源 SQLConnect 函式
使用連接字串或對話方塊連接到資料來源 SQLDriverConnect 函式
傳回驅動程式描述和屬性 SQLDrivers 函式

另請參閱

ODBC API 參考
ODBC 標頭檔