SQLConnect() - データ・ソースに接続する
SQLConnect() は、ターゲット・データベースに対する接続を確立します。アプリケーションは、ターゲット SQL データベースを提供する必要があります。SQLAllocHandle() を使用して接続ハンドルを割り振ってから、SQLConnect() を呼び出す必要があります。そのあと、ステートメント・ハンドルを割り振る前に、SQLConnect() を呼び出す必要があります。
SQLConnect() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
SQLRETURN SQLConnect (SQLHDBC hdbc,
SQLCHAR FAR *szDSN,
SQLSMALLINT cbDSN,
SQLCHAR FAR *szUID,
SQLSMALLINT cbUID,
SQLCHAR FAR *szAuthStr,
SQLSMALLINT cbAuthStr);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHDBC | hdbc | 入力 | 接続のために接続ハンドルを指定します。 |
| SQLCHAR * | szDSN | 入力 | データ・ソース、すなわち、接続しようとしているデータベースの名前または別名、 を指定します。 |
| SQLSMALLINT | cbDSN | 入力 | 引数 szDSN の内容の長さ (バイト) を指定します。 |
| SQLCHAR * | szUID | 入力 | 許可名 (ユーザー ID) を指定します。 このパラメーターは、検証、および認証済みです。 |
| SQLSMALLINT | cbUID | 入力 | 引数 szUID の内容の長さ (バイト) を指定します。 このパラメーターは、検証、および認証済みです。 |
| SQLCHAR * | szAuthStr | 入力 | 認証ストリング (パスワード) を指定します。 このパラメーターは、検証、および認証済みです。 |
| SQLSMALLINT | cbAuthStr | 入力 | 引数 szAuthStr の内容の長さ (バイト) を指定します。 このパラメーターは、検証、および認証済みです。 |
使用法
IBM® リレーショナル・データベース管理システムのターゲット・データベース (データ・ソース とも呼ばれる) は、DDF が Db2® サブシステムに構成された時に SYSIBM.LOCATIONS に定義されたロケーション 名です。SQLDataSources() を呼び出して、接続で使用可能なデータベースのリストを取得します。
多くのアプリケーションでは、ローカル・データベースがアクセスされます (DDF は使用されません)。 この場合、ローカル・データベース名は、Db2 インストールの際に Db2 サブシステム の DSNTIPR インストール・パネルで 'Db2 LOCATION NAME' として設定された名前です。 ローカル Db2 の管理スタッフが、この名前を提供することができます。 あるいは、NULL 接続が使用できます。
SQLConnect() により確立された接続では、外部で作成されたコンテキストが認識され、 異なるコンテキストから同じデータ・ソースへの複数接続が可能になります。
NULL 接続の指定: NULL 接続 を用いると、データベース名を指定せずに、 デフォルトのローカル・データベースへ接続します。
- SQLSetConnectAttr()
- SQLSetEnvAttr()
- szDSN 引数ポインターが NULL、あるいは cbDSN 引数値が 0 の場合、
NULL 接続を実行します。
NULL 接続では、他の接続と同様に、接続を行う前に、環境ハンドルと接続ハンドルを 割り振る必要があります。 NULL 接続を指定する理由は以下のとおりです。
- Db2 ODBC アプリケーションが、デフォルトのデータ・ソースに接続する必要が ある。 (デフォルトのデータ・ソースは、初期化ファイルの MVSDEFAULTSSID 設定で 指定された Db2 サブシステムです。)
- Db2 ODBC アプリケーションは、組み込み SQL と Db2 ODBC 呼び出しを混合して使用しており、 アプリケーションは Db2 ODBC を呼び出す前に既にデータ・ソースに接続している。
- Db2 ODBC アプリケーションがストアード・プロシージャーとして実行する。 ストアード・プロシージャーとして実行されている Db2 ODBC アプリケーションは、 NULL 接続を出す必要があります。
- szDSN 引数ポインターが NULL ではなく、かつ cbDSN 引数値 が 0 ではない場合、Db2 ODBC はデータ・ソースに対して CONNECT ステートメントを実行します。
長さ引数の指定: SQLConnect() の入力の長さの引数 (cbDSN、cbUID、cbAuthStr) を、 関連データ (NUL 終了文字を含まない) の実際の長さ (バイト) に設定するか、 あるいは関連データが NUL 終了であることを示す SQL_NTS に設定することができます。
ユーザーの認証: ユーザーを認証するには、SQLConnect() を ユーザー ID (引数 szUID で指定) およびパスワード (引数 szAuthStr で指定) の 両方に受け渡す必要があります。 引数 szUID に NULL または空のユーザー ID を指定した場合は、SQLConnect() は引数 szAuthStr を無視して、認証用のアプリケーションに関連した 1 次許可 ID を 使用します。SQLConnect() は、引数 szUID または szAuthStr でスペース文字は 受け入れません。
SQLDriverConnect() の使用: アプリケーションでは、初期化ファイルでこのデータ・ソースに対して指定されたキーワード値の 一部またはすべてをオーバーライドする必要がある場合、より拡張可能な SQLDriverConnect() 関数 を使用して接続します。
ユーザーは、さまざまな接続特性 (属性) を、szDSN データ・ソース引数に関連した 初期化ファイルのセクションで指定することができます。 アプリケーションは、SQLSetConnectAttr() との接続属性を設定する必要があります。 追加属性を設定するには、拡張接続関数の SQLDriverConnect() を呼び出します。また、SQLDriverConnect() と NULL 接続することも可能です。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 08001 | データ・ソースに接続できません。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 08002 | 接続は使用中です。 | 指定された接続ハンドルは、データ・ソースとの接続を確立するために使用中であり、 その接続はまだオープン状態です。 |
| 08004 | アプリケーション・サーバーが接続の確立をリジェクトしました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY024 | 引数の値が無効です。 | 引数 szDSN、szUID、szAuthStr のいずれかで、 二重引用符 (") が対になっていません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY501 | データ・ソース名が無効です。 | 引数 szDSN で、無効なデータ・ソース名が指定されました。 |
制約事項
IBM リレーショナル・データベース管理システムの暗黙接続 (またはデフォルト・データベース) オプションは、 サポートされません。SQLConnect() を呼び出さないと、SQL ステートメントは実行できません。
例
/* ... */
/* Global variables for user id and password, defined in main module.
To keep samples simple, not a recommended practice.
The INIT_UID_PWD macro is used to initialize these variables.
*/
extern SQLCHAR server[SQL_MAX_DSN_LENGTH + 1];
/********************************************************************/
SQLRETURN
DBconnect(SQLHENV henv,
SQLHDBC * hdbc)
{
SQLRETURN rc;
SQLSMALLINT outlen;
/* Allocate a connection handle */
if (SQLAllocHandle(SQL_HANDLE_DBC, henv, hdbc) != SQL_SUCCESS) {
printf(">---ERROR while allocating a connection handle-----¥n");
return (SQL_ERROR);
}
/* Set AUTOCOMMIT OFF */
rc = SQLSetConnectAttr(*hdbc, SQL_ATTR_AUTOCOMMIT,(void*)
SQL_AUTOCOMMIT_OFF,SQL_NTS);
if (rc != SQL_SUCCESS) {
printf(">---ERROR while setting AUTOCOMMIT OFF ------------¥n");
return (SQL_ERROR);
}
rc = SQLConnect(*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
if (rc != SQL_SUCCESS) {
printf(">--- Error while connecting to database:
SQLDisconnect(*hdbc);
SQLFreeHandle (SQL_HANDLE_DBC, *hdbc);
return (SQL_ERROR);
} else { /* Print connection information */
printf(">Connected to
}
return (SQL_SUCCESS);
}
/********************************************************************/
/* DBconnect2 - Connect with connection type */
/* Valid connection types SQL_CONCURRENT_TRANS, SQL_COORDINATED_TRANS */
/********************************************************************/
SQLRETURN DBconnect2(SQLHENV henv,
SQLHDBC * hdbc, SQLINTEGER contype)
SQLHDBC * hdbc, SQLINTEGER contype, SQLINTEGER conphase)
{
SQLRETURN rc;
SQLSMALLINT outlen;
/* Allocate a connection handle */
if (SQLAllocHandle(SQL_HANDLE_DBC, henv, hdbc) != SQL_SUCCESS) {
printf(">---ERROR while allocating a connection handle-----¥n");
return (SQL_ERROR);
}
/* Set AUTOCOMMIT OFF */
rc = SQLSetConnectAttr(*hdbc, SQL_ATTR_AUTOCOMMIT,(void*)
SQL_AUTOCOMMIT_OFF,SQL_NTS);
if (rc != SQL_SUCCESS) {
printf(">---ERROR while setting AUTOCOMMIT OFF ------------¥n");
return (SQL_ERROR);
}
rc = SQLSetConnectAttr(hdbc[0], SQL_ATTR_CONNECTTYPE,(void*)contype,SQL_NTS);
if (rc != SQL_SUCCESS) {
printf(">---ERROR while setting Connect Type -------------¥n");
return (SQL_ERROR);
}
if (contype == SQL_COORDINATED_TRANS ) {
rc=SQLSetConnectAttr(hdbc[0],SQL_ATTR_SYNC_POINT,(void*)conphase,
SQL_NTS);
if (rc != SQL_SUCCESS) {
printf(">---ERROR while setting Syncpoint Phase --------¥n");
return (SQL_ERROR);
}
}
rc = SQLConnect(*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
if (rc != SQL_SUCCESS) {
printf(">--- Error while connecting to database:
SQLDisconnect(*hdbc);
SQLFreeHandle(SQL_HANDLE_DBC, *hdbc);
return (SQL_ERROR);
} else { /* Print connection information */
printf(">Connected to
}
return (SQL_SUCCESS);
}
/* ... */