SQLDriverConnect() - 接続ストリングを使用してデータ・ソースに接続する

SQLDriverConnect() は、SQLConnect() の代替となる関数です。 両方の関数ともターゲット・データベースへの接続を確立しますが、SQLDriverConnect() の方は追加の接続パラメーターをサポートします。

SQLDriverConnect() の ODBC 仕様

表 1. SQLDriverConnect() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 なし なし

構文

SQLRETURN SQLDriverConnect   (SQLHDBC           hdbc,
                              SQLHWND           hwnd,
                              SQLCHAR      FAR  *szConnStrIn,
                              SQLSMALLINT       cbConnStrIn,
                              SQLCHAR      FAR  *szConnStrOut,
                              SQLSMALLINT       cbConnStrOutMax,
                              SQLSMALLINT  FAR  *pcbConnStrOut,
                              SQLUSMALLINT      fDriverCompletion);

関数の引数

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

表 2. SQLDriverConnect() の引数
データ・タイプ 引数 使用法 説明
SQLHDBC hdbc 入力 接続に使用する接続ハンドルを指定します。
SQLHWND hwindow 入力 常に値 NULL を指定します。 この引数は使用されません。
SQLCHAR * szConnStrIn 入力 完全、一部、または空 (NULL ポインター) の接続ストリング。 このストリングの説明と構文については、使用法を参照してください。
SQLSMALLINT cbConnStrIn 入力 引数 szConnStrIn が指す接続ストリングの長さ (バイト) を指定します。
SQLCHAR * szConnStrOut 出力 完全な接続ストリングが戻されるバッファーを指しています。

接続の確立が成功すると、このバッファーには完全な接続ストリングが入ります。 アプリケーションは、このバッファー用に少なくと も SQL_MAX_OPTION_STRING_LENGTH バイトを割り当てる必要があります。

SQLSMALLINT cbConnStrOutMax 入力 引数 szConnStrOut が指しているバッファーの最大サイズ (バイト) を 指定します。
SQLSMALLINT* pcbConnStrOut 出力 完全な接続ストリングのために使用可能な合計バイト数が入るバッファーを指します。

pcbConnStrOut の値が cbConnStrOutMax 以上の 場合、szConnStrOut 内の完全な接続ストリング は cbConnStrOutMax - 1 バイトに切り捨てられます。

SQLUSMALLINT fDriverCompletion 入力 Db2® ODBC が詳細情報をユーザーに要求するプロンプトをいつ出すべきかを示します。
IBM® 固有: Db2 for z/OS® は、 この引数に SQL_DRIVER_NOPROMPT の値のみサポートしています。以下の値は、サポートされていません。
  • SQL_DRIVER_PROMPT
  • SQL_DRIVER_COMPLETE
  • SQL_DRIVER_COMPLETE_REQUIRED

使用法

データ・ソースへの接続時に Db2 ODBC 初期化ファイルに定義されたキーワード値の いずれかまたはすべてを指定する場合は、SQLDriverConnect() を使用します。

接続が確立されると、完全な接続ストリングが戻されます。 アプリケーションは、今後の接続要求のためにこのストリングを保管しておくことができます。 これによって、Db2 ODBC 初期化ファイル内のいずれかまたはすべてのキーワード値を オーバーライドすることができます。

接続ストリングを使用して、接続を完了するのに必要な 1 つ以上の値を渡します。 以下の構文を用いて、引数 szConnStrln が指す接続ストリングを作成する必要があります。

構文図を読む
 接続ストリングの構文

>>-+------------------------------------------------+----------><
   | .-;------------------------------------------. |   
   | V                                            | |   
   '---+-DSN----------------------+--=--attribute-+-'   
       +-UID----------------------+                     
       +-PWD----------------------+                     
       '-DB2 ODBC-defined-keyword-'                     

接続ストリングは、以下のキーワードを含んでいます。
DSN
データ・ソース名。 データベースの名前または別名。

IBM 固有: この値が必要とされる理由は、Db2 for z/OS が 引数 fDriverCompletion に対して SQL_DRIVER_NOPROMPT の値のみをサポートするからです。

UID
許可名 (ユーザー ID)。この値は、検証、および認証済みです。

IBM 固有: Db2 for z/OS は、引数 fDriverCompletion に 対して SQL_DRIVER_NOPROMPT のみをサポートします。UID 値が無指定の場合、Db2 は アプリケーションの 1 次許可 ID を使用し、PWD キーワードは指定されても無視します。

PWD
許可名に対応するパスワード。 ユーザー ID にパスワードがない場合は、空ストリング (PWD=;) を 渡します。 この値は、検証、および認証済みです。

IBM 固有: Db2 for z/OS は、引数 fDriverCompletion に 対して SQL_DRIVER_NOPROMPT のみをサポートします。 接続ストリングで UID が無指定の場合、PWD に指定した値は無視されます。

初期化キーワードのいずれかを、接続ストリングに指定できます。どのキーワードを接続ストリング内で繰り返し指定した場合も、 指定されたキーワードの最初のものに関連した値が使用されます。

Db2 ODBC 初期化ファイルにキーワードがある場合、キーワードとそれぞれの値は、 接続ストリングで Db2 ODBC に渡される情報を追加するのに使用されます。Db2 ODBC 初期化ファイルの 情報が接続ストリングの情報と矛盾する場合は、接続ストリングの値が優先されます。

アプリケーションは、以下のような fDriverCompletion の値によって、 エラーを受け取ります。
SQL_DRIVER_PROMPT:
Db2 ODBC は SQL_ERROR を戻します。
SQL_DRIVER_COMPLETE:
Db2 ODBC は SQL_ERROR を戻します。
SQL_DRIVER_COMPLETE_REQUIRED:
Db2 ODBC は SQL_ERROR を戻します。
SQL_DRIVER_NOPROMPT:
ユーザーには、情報を要求するプロンプトが出されません。 接続ストリングに含まれている情報を用いて、接続が試行されます。 この情報が接続上不適切な場合は、SQL_ERROR が戻されます。

接続が確立されると、完全な接続ストリングが戻されます。

戻りコード

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

診断

この関数は、関数 SQLConnect() に似た診断を生成します。次の表は、SQLDriverConnect() が戻す追加の SQLSTATE を示しています。

表 3. SQLDriverConnect() の SQLSTATE
SQLSTATE 説明 説明
01004 データが切り捨てられました。 引数 szConnstrOut で指定したバッファーは、完全な接続ストリングを 入れるのに不十分です。 引数 pcbConnStrOut には、関数の戻りで使用可能な接続ストリングの実際の長さ (バイト) が 入ります。(SQLDriverConnect() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
01S00 接続ストリング属性が無効です。 無効なキーワードまたは属性が入力接続ストリングに指定されましたが、 以下いずれかのイベントが発生したため、データ・ソースへの接続は成功しました。
  • 認識できないキーワードが無視された。
  • 無効な属性値が無視され、その代わりにデフォルト値が使用された。
(SQLDriverConnect() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
01S02 オプション値が変更されました。 MULTICONTEXT=1 の使用中に 、SQL_CONNECTTYPE が SQL_CONCURRENT_TRANS に変更されました。
HY090 ストリングまたはバッファーの長さが無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 引数 cbConnStrIn に指定された値は 0 より小さく、SQL_NTS と等しくありません。
  • 引数 cbConnStrOutMax に指定された値が 0 より小さい値です。
HY110 ドライバーの完了が無効です。 引数 fDriverCompletion に指定された値が、 有効な値ではありません。

制約事項

Db2 ODBC は、引数 hwindow をサポートしていません。 ウィンドウ・ハンドルは、z/OS 環境では適用されません。

Db2 ODBC は、以下の ODBC 定義の値は、引数 fDriverCompletion では サポートしていません。
  • SQL_DRIVER_PROMPT
  • SQL_DRIVER_COMPLETE
  • SQL_DRIVER_COMPLETE_REQUIRED

例

以下の例 は、SQLConnect() の代わりに SQLDriverConnect() を 使用して、キーワード値を接続に渡すアプリケーションを示しています。
図 1. 接続時にキーワード値を渡すアプリケーション
 /******************************************************************/
 /*  Issue SQLDriverConnect to pass a string of initialization     */
 /*  parameters to compliment the connection to the data source.   */
 /******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "sqlcli1.h"
  /******************************************************************/
  /* SQLDriverConnect -----------                                   */
  /******************************************************************/
int main( )
{
   SQLHENV         hEnv    = SQL_NULL_HENV;
   SQLHDBC         hDbc    = SQL_NULL_HDBC;
   SQLRETURN       rc      = SQL_SUCCESS;
   SQLINTEGER      RETCODE = 0;
   char            *ConnStrIn =
                   "dsn=STLEC1;connecttype=2;bitdata=2;optimizefornrows=30";
   char            ConnStrOut [200];
   SQLSMALLINT     cbConnStrOut;
   int             i;
   char            *token;
   (void) printf ("**** Entering CLIP10.¥n¥n");

  /*****************************************************************/
  /* CONNECT to DB2                                                */
  /*****************************************************************/
   rc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
   if( rc != SQL_SUCCESS )
     goto dberror;
  /*****************************************************************/
  /* Allocate connection handle to DSN                             */
  /*****************************************************************/
   RETCODE = SQLAllocHandle( SQL_HANDLE_DBC, hEnv, &hDbc);
   if( RETCODE != SQL_SUCCESS )      // Could not get a Connect Handle
     goto dberror;
  /*****************************************************************/
  /* Invoke SQLDriverConnect -----------                           */
  /*****************************************************************/
   RETCODE = SQLDriverConnect (hDbc                 ,
                               NULL                 ,
                               (SQLCHAR *)ConnStrIn ,
                               strlen(ConnStrIn)    ,
                               (SQLCHAR *)ConnStrOut,                              
                               sizeof(ConnStrOut)   ,
                               &cbConnStrOut        ,
                               SQL_DRIVER_NOPROMPT);
   if( RETCODE != SQL_SUCCESS )      // Could not get a Connect Handle
   {
     (void) printf ("**** Driver Connect Failed. rc = 
     goto dberror;
   }
  /*****************************************************************/
  /* Enumerate keywords and values returned from SQLDriverConnect  */
  /*****************************************************************/
   (void) printf ("**** ConnStrOut = 
   for (i = 1, token = strtok (ConnStrOut, ";");
        (token != NULL);
        token = strtok (NULL, ";"), i++)
     (void) printf ("**** Keyword # 
  /*****************************************************************/
  /* DISCONNECT from data source                                   */
  /*****************************************************************/
   RETCODE = SQLDisconnect(hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Deallocate connection handle                                  */
  /*****************************************************************/
   RETCODE = SQLFreeHandle (SQL_HANDLE_DBC, hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
/*****************************************************************/
  /* Disconnect from data sources in connection table              */
  /*****************************************************************/
   SQLFreeHandle(SQL_HANDLE_ENV, hEnv);     /* Free  environment handle  */
   goto exit;
   dberror:
   RETCODE=12;
   exit:
   (void) printf ("**** Exiting  CLIP10.¥n¥n");
   return(RETCODE);
}