SQLDataSources() - データ・ソースのリストを取得する

SQLDataSources() は、一度に 1 つずつ、使用可能なターゲット・データベースのリストを戻します。接続を行う前に SQLDataSources() を呼び出して使用可能なデータベースを判別します。

SQLDataSources() の ODBC 仕様

表 1. SQLDataSources() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

SQLRETURN   SQLDataSources   (SQLHENV           henv,
                              SQLUSMALLINT      fDirection,
                              SQLCHAR     FAR   *szDSN,
                              SQLSMALLINT       cbDSNMax,
                              SQLSMALLINT FAR   *pcbDSN,
                              SQLCHAR     FAR   *szDescription,
                              SQLSMALLINT       cbDescriptionMax,
                              SQLSMALLINT FAR   *pcbDescription);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLDataSources() の引数
データ・タイプ 引数 使用法 説明
SQLHENV henv 入力 環境ハンドルを指定します。
SQLUSMALLINT fDirection 入力 リストの最初のデータ・ソース名を要求するか、もしくはリストの次のデータ・ソース名を要求します。 fDirection は、以下の値のみを含むことができます。
  • SQL_FETCH_FIRST
  • SQL_FETCH_NEXT
SQLCHAR * szDSN 出力 取り出されたデータ・ソース名の入っているバッファーを指すポインターを指定します。
SQLSMALLINT cbDSNMax 入力 引数 szDSN が指すバッファーの最大長 (バイト) を指定します。 これは、SQL_MAX_DSN_LENGTH + 1 以下でなければなりません。
SQLSMALLINT * pcbDSN 出力 szDSN に戻すのに使用できる最大バイト数が保管される ロケーションを指すポインターを指定します。
SQLCHAR * szDescription 出力

データ・ソースの説明が戻されるバッファーを指すポインターを指定 します。Db2® ODBC は、データベース管理システムにカタログされたデータベースに関連 したコメント・フィールドを戻します。

IBM® 固有: IBM リレーショナル・データベース管理システムでは、常に、30 バイトをブランクで埋めた記述を戻します。

SQLSMALLINT cbDescriptionMax 入力 szDescription バッファーの最大長 (バイト) を指定します。

IBM 固有: Db2 for z/OS® ODBC は常に NULL を戻します。

SQLSMALLINT * pcbDescription 出力 実バイト数 (データ・ソースの全記述を収容するのに 必要となるバイト数) をこの関数が戻すロケーションへのポインターを指定します。

IBM 固有: Db2 for z/OS は常にゼロを戻します。

使用法

引数 fDirection が SQL_FETCH_FIRST もしくは SQL_FETCH_NEXT に設定されていれば、 いつでもこの関数を呼び出すことができます。

SQL_FETCH_FIRST を指定すると、リストの最初のデータベースが常に戻されます。

SQL_FETCH_NEXT を指定すると、戻されるデータベースは、いつ SQLDataSources() を呼び出すかによって異なります。 アプリケーションの以下の時点により、SQLDataSources() は異なるデータベース名を戻します。
  • SQL_FETCH_FIRST 呼び出しの直後の場合には、リストの 2 番目のデータベースが戻されます。
  • 他のすべての SQLDataSources() 呼び出しの前には、リストの最初のデータベースが戻されます。
  • リストにデータベースが残っていない場合には、SQL_NO_DATA_FOUND が戻されます。 関数を再度呼び出すと、最初のデータベースが戻されます。
  • その他の場合は、いずれもリストの次のデータベースが戻されます。

戻りコード

SQLDataSources() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA_FOUND

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLDataSources() の SQLSTATE
SQLSTATE 説明 説明
01004 データが切り捨てられました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 引数 szDSN に戻されたデータ・ソース名は、 引数 cbDSNMax で指定された値より長い値です。 引数 pcbDSN には、データ・ソース名全体の長さ (バイト) が入っています。
  • 引数 szDescription に戻されたデータ・ソース名は、 引数 cbDescriptionMax で指定された値より長い値です。 引数 pcbDescription には、データ・ソース記述全体の長さ (バイト) が入っています。

(SQLDataSources() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)

58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY000 一般エラー。 具体的な SQLSTATE が定義されないエラーが起こり ました。SQLGetDiagRec() によって引数 MessageText に戻されたエラー・メッセージに、エラーとその原因が記述されています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY090 ストリングまたはバッファーの長さが無効です。 引数 cbDSNMax または引数 cbDescriptionMax の いずれかに指定された値が 0 より小さい値です。
HY103 方向オプションが範囲外です。 引数 fDirection が、SQL_FETCH_FIRST または SQL_FETCH_NEXT に 設定されていません。

例

以下の例は、SQLDataSources() で使用可能なデータ・ソースのリストを印刷するアプリケーションを示しています。
図 1. 使用可能なデータ・ソースをリストするアプリケーション
/* ... */
/*******************************************************
**    - Demonstrate SQLDataSource function
**    - List available servers
**      (error checking has been ignored for simplicity)
**
**  Functions used:
**
**    SQLAllocHandle      SQLFreeHandle
**    SQLDataSources
********************************************************/
#include <stdio.h>
#include <stdlib.h>
#include "sqlcli1.h"
int
main()
{
    SQLRETURN       rc;
    SQLHENV         henv;
    SQLCHAR         source[SQL_MAX_DSN_LENGTH + 1], description[255];
    SQLSMALLINT     buffl, desl;
    /* Allocate an environment handle   */
    SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);     
    /* List the available data sources (servers)         */
    printf("The following data sources are available:¥n");
    printf("ALIAS NAME                      Comment(Description)¥n");
    printf("----------------------------------------------------¥n");
    while ((rc = SQLDataSources(henv, SQL_FETCH_NEXT, source,
                   SQL_MAX_DSN_LENGTH + 1, &buffl, description, 255, &desl))
           != SQL_NO_DATA_FOUND) {
        printf("%-30s %s¥n", source, description);
    }
    SQLFreeHandle(SQL_HANDLE_ENV, henv);
    return (SQL_SUCCESS);
}
/* ... */