SQLConnect() - データ・ソースに接続する

SQLConnect() は、ターゲット・データベースに対する接続を確立します。アプリケーションは、ターゲット SQL データベースを提供する必要があります。SQLAllocHandle() を使用して接続ハンドルを割り振ってから、SQLConnect() を呼び出す必要があります。そのあと、ステートメント・ハンドルを割り振る前に、SQLConnect() を呼び出す必要があります。

SQLConnect() の ODBC 仕様

表 1. SQLConnect() の仕様
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);

関数の引数

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

表 2. SQLConnect() の引数
データ・タイプ 引数 使用法 説明
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 接続 を用いると、データベース名を指定せずに、 デフォルトのローカル・データベースへ接続します。

NULL SQLConnect() の場合、デフォルトの接続タイプは、初期化ファイルの共通セクション で指定された CONNECTTYPE キーワードの値です。このデフォルト値をオーバーライドするには、NULL の SQLConnect() を出す前に次のいずれかの 関数を使用して、SQL_ATTR_CONNECTTYPE 属性を指定します。
  • SQLSetConnectAttr()
  • SQLSetEnvAttr()
SQLConnect() の引数 szDSN を以下のように使用します。
  • 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 接続することも可能です。

戻りコード

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

診断

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

表 3. SQLConnect() の SQLSTATE
SQLSTATE 説明 説明
08001 データ・ソースに接続できません。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • Db2 ODBC が、データ・ソースとの接続を確立できません。
  • 組み込み SQL を使用して確立された接続が既にあるため、接続要求はリジェクトされます。
08002 接続は使用中です。 指定された接続ハンドルは、データ・ソースとの接続を確立するために使用中であり、 その接続はまだオープン状態です。
08004 アプリケーション・サーバーが接続の確立をリジェクトしました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • データ・ソースは、接続の確立をリジェクトしました。
  • MAXCONN キーワードで指定された接続数に達しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY024 引数の値が無効です。 引数 szDSN、szUID、szAuthStr のいずれかで、 二重引用符 (") が対になっていません。
HY090 ストリングまたはバッファーの長さが無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 引数 cbDSN に指定された値が 0 より小さく、SQL_NTS に等しくありません。 さらに、引数 szDSN が NULL ポインターではありません。
  • 引数 cbUID に指定された値が 0 より小さく、SQL_NTS に等しくありません。 さらに、引数 szUID が NULL ポインターではありません。
  • 引数 cbAuthStr に指定された値が 0 より小さく、SQL_NTS に等しくありません。 さらに、引数 szAuthStr が NULL ポインターではありません。
HY501 データ・ソース名が無効です。 引数 szDSN で、無効なデータ・ソース名が指定されました。

制約事項

IBM リレーショナル・データベース管理システムの暗黙接続 (またはデフォルト・データベース) オプションは、 サポートされません。SQLConnect() を呼び出さないと、SQL ステートメントは実行できません。

例

以下の例 は、SQLConnect() を用いて、データ・ソース への接続を行うアプリケーションを示しています。
図 1. データ・ソースへ接続するアプリケーション
/* ... */
/* 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);
}
/* ... */