SQLDataSources() - データ・ソースのリストを取得する
SQLDataSources() は、一度に 1 つずつ、使用可能なターゲット・データベースのリストを戻します。接続を行う前に SQLDataSources() を呼び出して使用可能なデータベースを判別します。
SQLDataSources() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHENV | henv | 入力 | 環境ハンドルを指定します。 |
| SQLUSMALLINT | fDirection | 入力 | リストの最初のデータ・ソース名を要求するか、もしくはリストの次のデータ・ソース名を要求します。
fDirection は、以下の値のみを含むことができます。
|
| 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 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
(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);
}
/* ... */