SQLDriverConnect() - 接続ストリングを使用してデータ・ソースに接続する
SQLDriverConnect() は、SQLConnect() の代替となる関数です。 両方の関数ともターゲット・データベースへの接続を確立しますが、SQLDriverConnect() の方は追加の接続パラメーターをサポートします。
SQLDriverConnect() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| 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 の値のみサポートしています。以下の値は、サポートされていません。
|
使用法
データ・ソースへの接続時に 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 初期化ファイルの 情報が接続ストリングの情報と矛盾する場合は、接続ストリングの値が優先されます。
- 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 が戻されます。
接続が確立されると、完全な接続ストリングが戻されます。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_NO_DATA_FOUND
- SQL_INVALID_HANDLE
- SQL_ERROR
診断
この関数は、関数 SQLConnect() に似た診断を生成します。次の表は、SQLDriverConnect() が戻す追加の SQLSTATE を示しています。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 引数 szConnstrOut で指定したバッファーは、完全な接続ストリングを 入れるのに不十分です。 引数 pcbConnStrOut には、関数の戻りで使用可能な接続ストリングの実際の長さ (バイト) が 入ります。(SQLDriverConnect() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 01S00 | 接続ストリング属性が無効です。 | 無効なキーワードまたは属性が入力接続ストリングに指定されましたが、
以下いずれかのイベントが発生したため、データ・ソースへの接続は成功しました。
|
| 01S02 | オプション値が変更されました。 | MULTICONTEXT=1 の使用中に 、SQL_CONNECTTYPE が SQL_CONCURRENT_TRANS に変更されました。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY110 | ドライバーの完了が無効です。 | 引数 fDriverCompletion に指定された値が、 有効な値ではありません。 |
制約事項
Db2 ODBC は、引数 hwindow をサポートしていません。 ウィンドウ・ハンドルは、z/OS 環境では適用されません。
- SQL_DRIVER_PROMPT
- SQL_DRIVER_COMPLETE
- SQL_DRIVER_COMPLETE_REQUIRED
例
/******************************************************************/
/* 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);
}
