仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLConnect() は、ターゲット・データベースに対する接続を確立します。アプリケーションは、ターゲット SQL データベース、およびオプションとして許可名と認証ストリングを与える必要があります。
この関数を呼び出す前に、SQLAllocHandle() を使用して接続ハンドルを割り振る必要があります。
この関数は、SQLAllocHandle() を使用してステートメント・ハンドルを割り振る前に、呼び出さなければなりません。
構文
SQLRETURN SQLConnect ( SQLHDBC ConnectionHandle, /* hdbc */ SQLCHAR *FAR ServerName, /* szDSN */ SQLSMALLINT NameLength1, /* cbDSN */ SQLCHAR *FAR UserName, /* szUID */ SQLSMALLINT NameLength2, /* cbUID */ SQLCHAR *FAR Authentication, /* szAuthStr */ SQLSMALLINT NameLength3); /* cbAuthStr */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHDBC | ConnectionHandle | 入力 | 接続ハンドル |
SQLCHAR * | ServerName | 入力 | データ・ソース: データベースの名前または別名。 |
SQLSMALLINT | NameLength1 | 入力 | ServerName 引き数の内容の長さ。 |
SQLCHAR * | UserName | 入力 | 許可名 (ユーザー識別子) |
SQLSMALLINT | NameLength2 | 入力 | UserName 引き数の内容の長さ。 |
SQLCHAR * | Authentication | 入力 | 認証ストリング (パスワード) |
SQLSMALLINT | NameLength3 | 入力 | Authentication 引き数の内容の長さ。 |
使用法
IBM RDBMS のターゲット・データベース (データ・ソース とも呼ぶ) は、データベース別名です。アプリケーションは、SQLDataSources() を呼び出して、接続できるデータベースのリストを取得することができます。
SQLDataSources() がこの情報を返す前に、データベースをカタログ作成する必要があります。 Windows では、ODBC ドライバー・マネージャーを使用して、ユーザーがデータベースのカタログ作成を 2 回行わなければなりません。
これは、DB2 クライアント・アプリケーション・イネーブラー製品に組み込まれている DB2 クライアント・セットアップを使用することによって、 1 回の操作で終えることができます。カタログ作成の方法は ODBC ドライバー・マネージャーと IBM DBMS とで違いますが、 DB2 CLI アプリケーションはこの必要がありません。 (コール・レベル・インターフェースの利点の 1 つは、実行時に SQLConnect() を呼び出すまでアプリケーションがターゲット・データベースについて認識する必要がないという点です。) 実際の DBMS へのデータ・ソース名のマッピングは、 CLI アプリケーションの有効範囲と責任の範囲外です。
ODBC ドライバー・マネージャーを使用しない環境で DB2 CLI を使用する場合には、 IBM DBMS は 1 回カタログ化するだけで済みます。カタログ化の詳細については、第 4 章, CLI の構成およびサンプル・アプリケーションの実行を参照してください。
SQLConnect() の入力長さ引き数 (NameLength1、 NameLength2、NameLength3) は、その関連データの実際の長さ (ヌル終了文字を含まない) に設定するか、または SQL_NTS に設定して関連データがヌル終了になることを指定することができます。
ServerName および UserName 引き数値にはブランクを入れてはなりません。
アプリケーションが以下のことをする必要がある場合には、より拡張性の高い SQLDriverConnect() 関数を接続の際に使用します。
種々の接続特性 (オプション) を、 ServerName データ・ソース引き数に関連付けて db2cli.ini (および odbc.ini) 初期化ファイルのセクション内でエンド・ユーザーが指定するか、または SQLSetConnectAttr() を使用するアプリケーションを用いて設定することができます。拡張された接続関数 SQLDriverConnect() も、追加の接続オプションを指定して呼び出すことができます。
DB2 CLI を使用して書かれたストアード・プロシージャーで、 null の SQLConnect() 呼び出しを行う必要があります。 null の SQLConnect() とは、ServerName、 UserName、および Authentication 引き数ポインターがすべて NULL に設定され、そのそれぞれの長さ引き数がすべて 0 に設定されているものです。 null の SQLConnect() では最初に SQLAllocEnv() と SQLAllocConnect() を呼び出さなければなりませんが、必ずしも SQLDisconnect() の前に SQLTransact() を呼び出す必要はありません。詳細については、ストアード・プロシージャーの例を参照してください。
戻りコード
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
08001 | データ・ソースに接続できませんでした。 | DB2 CLI はデータ・ソース (サーバー) との接続を確立できませんでした。
組み込み SQL を経由して確立された接続がすでにあるため、接続要求が拒否されました。 |
08002 | 接続が使用中です。 | 指定された ConnectionHandle はデータ・ソースとの接続を確立するためにすでに使用されており、接続がまだオープンしています。 |
08004 | アプリケーション・サーバーが、接続の確立を拒否しました。 | データ・ソース (サーバー) は、接続の確立を拒否しました。
MAXCONN キーワードによって指定された接続数に達しました。 |
28000 | 許可指定が無効です。 | 引き数 UserName で指定された値または引き数 Authentication で指定された値が、データ・ソースで定義されている制限に違反しました。 |
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 NameLength1 に指定された値は 0 より小さい値でしたが、
SQL_NTS に等しくなく、引き数 ServerName は NULL ポインターではありませんでした。
引き数 NameLength2 に指定された値は 0 より小さい値でしたが、 SQL_NTS に等しくなく、引き数 UserName は NULL ポインターではありませんでした。
引き数 NameLength3 に指定された値は 0 より小さい値でしたが、 SQL_NTS に等しくなく、引き数 Authentication は NULL ポインターではありませんでした。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY501 | データ・ソース名が無効です。 | 引き数 ServerName 内に、無効なデータ・ソース名を指定しました。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
IBM RDBMS の暗黙接続 (または省略時データベース) オプションは、サポートされません。 SQLConnect() を呼び出さないと、SQL ステートメントを実行できません。
(ここで完全サンプル utilcli.c を使用することもできます 。)
/* From the CLI sample utilcli.c */ /* ... */ /* connect to the database */ printf( "\nConnecting to %s ...\n", dbAlias ) ; sqlrc = SQLConnect( *pHdbc, (SQLCHAR *)dbAlias, SQL_NTS, (SQLCHAR *)user, SQL_NTS, (SQLCHAR *)pswd, SQL_NTS ) ; HANDLE_CHECK( SQL_HANDLE_DBC, *pHdbc, sqlrc, pHenv, pHdbc ) ; printf( "Connected to %s.\n", dbAlias ) ; return( 0 ) ; }
参照