SQLConnect - データ・ソースへの接続

目的

SQLConnect() は、ターゲット・データベースへの接続を確立します。

接続ハンドルは、この関数の呼び出し前に、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 */

関数の引き数

表 36. SQLConnect の引き数

注意事項

未登録 ユーザー (DB2eSYSUSERS 表に存在しないユーザー) が、SQLGetDiagRec() CLI 関数の呼び出し中に暗号化された DB2 Everyplace データベースへ接続しようとすると、このユーザーは警告メッセージ 42704 (オブジェクトが未定義) を受け取ります。 登録済み ユーザーは、この警告を受け取りません。 対照的に、SQLConnect() 関数の呼び出し中には未登録ユーザーと登録済みユーザーの両者がデータベースに接続でき、 警告メッセージも受け取りません。

使用法

SQLConnect() を使用して、異なる場所のデータ・ソースを接続することができます。

ローカル・デバイスのデータ・ソースにアクセスするには、ServerName 引き数にデータ・ソース名を設定します。 DB2 Everyplace はデータ・ソース名を無視し、ローカル・データ・ソースにアクセスします。

2 次ストレージ装置を使用するアプリケーションの場合、引き数 ServerName には、DataSource の位置を指す ストリングを入れることができます。DataSource は、ローカルにあるかまたは IBM マイクロドライブ、Sony メモリー・スティック、 コンパクト・フラッシュ、SD メモリー・カード、MultiMediaCard のような 2 次ストレージ装置にあります。ServerName ストリングの形式は、次のとおりです。

ServerName=Device:/Path/DataSource

Device

これは、DataSource が保管されているデバイスの名前です。 コンパクト・フラッシュをサポートしている Palm OS デバイスの コンパクト・フラッシュ (CF) タイプ II ストレージ・デバイスにアクセスするには、 予約済み文字 # を使用します。 2 次ストレージは、予約済み文字 # で指定されます。#0 および #1 は 、アクセスする 2 次ストレージ・スロットを指定します。# は #0 と同じです。 以下に例を示します。

ServerName=#:/storage/

DB2 Everyplace は、最初の CF スロットに入っている IBM マイクロドライブの storage ディレクトリーにある DataSource に接続します。

Path

これは、Device にある DataSource へのパスです。 Path を Device:/ なしで指定すると、 アプリケーションの位置との相対的なローカル・ファイル・システム・パスが 使用されます。ファイルを、ボリュームのルート・ディレクトリーに書き込んではいけません。 ルート・ディレクトリー内のファイルは、一部のメディア・タイプでサポートされません。 例えば、次の場合、

ServerName=dir1/dir2/DATA1

注:

DB2 Everyplace ではパスの長さに制限はありません。

アプリケーションがローカル・ファイル・システムの /myapp に ある場合、DB2 Everyplace は /myapp/dir1/dir2/ にある DataSource に 接続します。 DataSource 名の DATA1 は無視されます。

DataSource

オプショナル: 接続するデータ・ソースの名前。この名前は、DB2 Everyplace では無視されます。

リモート照会およびストアード・プロシージャー・アダプターを使用してリモート・ストアード・プロシージャーに アクセスするには、ServerName 引き数を使用してデータベースの場所と名前を指定します。 リモート照会およびストアード・プロシージャー・アダプターを使用して リモート・データベースにアクセスするアプリケーションの場合、 引き数 ServerName には以下の URL 形式を入れることができます。

http://IPAddress:portNumber/path?DB=DataSource 

標準的なファイル・システムではなく、Windows CE のオブジェクト記憶を使用している場合は、以下のいずれかの手順を実行します。

• CLI 関数 SQLConnect のパス・パラメーターを "@:¥" に設定する

または

• CLP で、'connect to @:¥' を実行する

Windows CE のオブジェクト記憶には、「ディレクトリー」という概念はありません。 オブジェクト記憶を使用している場合、ユーザーは表の作成先のディレクトリー、 つまりパスを指定することはできません。 オブジェクト記憶内のすべての表は、同じネーム・スペースに作成されます。 こうした制限から、オブジェクト記憶への複数の同時接続は確立できません。 接続のシリアライゼーションを目的としたロック・ファイルが、 ファイル・システムのルート・パスに作成されます。

オブジェクト記憶を使用している場合は、標準的なファイル・システムの場合とは異なり、DB2 Everyplace ファイルを手動で削除することはできません。

例

ローカルの c:¥dir1¥dir2¥ にあるデータ・ソースに接続します。 データ・ソース名 DS1 は無視されます。

ServerName=c:/dir1/dir2/DS1

ローカルの /dir1/dir2/ にあるデータ・ソースに、UNIX のファイル・システム表記で接続します。

ServerName=/dir1/dir2/

アプリケーション・パスから見て、ローカルの dir1¥ ディレクトリーにあるデータ・ソースに接続します。 アプリケーションが c:¥myapp¥ にある場合は、c:¥myapp¥dir1¥ データ・ソースがアクセスされます。

ServerName=dir1¥

2 次ストレージ・スロット 1 に入っているストレージ・メモリーの /dir1/ ディレクトリーにある データ・ソースに接続します。

ServerName=#1:/dir1/

リモート照会およびストアード・プロシージャー・アダプターを使用して、DB2 Everyplace 同期サーバー 192.168.0.1 のポート 8080 でデータベース mysample に接続します。

ServerName=
 http://192.168.0.1:8080/db2e/servlet/com.ibm.mobileservices.adapter
                .agent.AgentServlet?DB=mysample

Windows CE のストレージを使用して、データ・ソースに接続します。

ServerName=@:¥
 

接続のシリアライゼーション

接続のシリアライゼーションについては、接続のシリアライゼーションを参照してください。

接続の認証

データベースの暗号化には、基礎となるユーザー認証が必要です。 DB2 Everyplace では、UserName および Authentication を使用して、接続時にユーザーの認証を実行します。

認証は次のように行われます。SQLConnect の接続先のデータベースに DB2eSYSUSERS カタログ表が存在しない場合、UserName と Authentication の情報は無視されます。DB2 Everyplace では登録済み ユーザーと未登録 ユーザーとを区別しています。 登録済みユーザーとは、GRANT SQL ステートメントを使用して追加された DB2eSYSUSERS 表にリストされているユーザーのことです。接続時において、DB2eSYSUSERS 表が存在し、UserName が登録済みユーザーのものであれば、認証は行われます。 Authentication パラメーターに指定されたパスワードが正しくない場合は、エラー (42505) が戻されます。 UserName が未登録である場合は、SQLConnect 関数は正常に実行されます。ただし、後続の SQLGetDiagRec への呼び出しでは、警告 42704 (オブジェクトが未定義) が戻されます。 これにより、正常に接続している登録済みユーザーと正常に接続された未登録ユーザーとの区別が、アプリケーションで可能となります。 詳しくは、ローカル・データ暗号化の概要、DB2eSYSUSERS、およびGRANTを参照してください。

戻りコード

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

診断

表 37. SQLConnect の SQLSTATE

制約事項

SQL ステートメントの実行前に、SQLConnect() を呼び出す必要があります。

関連した概念

• 接続のシリアライゼーション
• SQLAllocHandle - ハンドルの割り当て
• SQLDisconnect - データ・ソースからの切断

関連した解説

• DB2 CLI 関数の説明の要点
• DB2 CLI 関数の要約
• SQLAllocHandle - ハンドルの割り当て
• SQLDisconnect - データ・ソースからの切断