SQLSetConnectAttr() - 接続属性を設定する
SQLSetConnectAttr() は、接続の局面を制御する属性を設定します。
SQLSetConnectAttr() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 3.0 | 可 | 可 |
構文
SQLRETURN SQLSetConnectAttr (SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHDBC | ConnectionHandle | 入力 | 接続ハンドル。 |
| SQLINTEGER | 属性 | 入力 | 設定する接続属性。 属性の完全なリストについては 表 4 を参照してください。 |
| SQLPOINTER | ValuePtr | 入力 | Attribute に関連付けられる値を指すポインター。 *ValuePtr は、Attribute の値によって異なり、32 ビットの符号なし整数値または NUL 終了文字ストリングを指します。 Attribute 引数がドライバー固有値の場合は、*ValuePtr の値は 符号付き整数になる場合があります。 |
| SQLINTEGER | StringLength | 入力 | *ValuePtr 引数についての情報。
|
使用法
アプリケーションは、接続が割り当てられているか、解放されている間はいつでも、SQLSetConnectAttr() を 呼び出すことができます。接続のアプリケーションが設定に成功した接続属性とステートメント属性はすべて、 接続時に SQLFreeHandle() を呼び出すまで持続します。
接続属性によっては、接続が行われる前のみ、または後でのみ設定できるものもあります。 その他の属性は、ステートメントが割り当てられた後では設定できません。次の表は 、それぞれの接続属性をいつ設定できるかを示しています。
| 属性 | 接続前 | 接続後 | ステートメントを割り当てた後 |
|---|---|---|---|
| SQL_ATTR_ACCESS_MODE | 可 | 可 | 可1 |
| SQL_ATTR_AUTOCOMMIT | 可 | 可 | 可2 |
| SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION | 可 | 可 | 可 |
| SQL_ATTR_CONNECTTYPE | 可 | 不可 | 不可 |
| SQL_ATTR_CURRENT_SCHEMA | 可 | 可 | 可 |
| SQL_ATTR_DB2EXPLAIN | 可 | 可 | 可 |
| SQL_ATTR_DECFLOAT_ROUNDING_MODE | 可 | 可 | 可 |
| SQL_ATTR_EXTENDED_INDICATORS | 可 | 可 | 可 |
| SQL_ATTR_MAXCONN | 可 | 不可 | 不可 |
| SQL_ATTR_SYNC_POINT | 可 | 不可 | 不可 |
| SQL_ATTR_TXN_ISOLATION | 不可 | 可 | 可 |
注:
|
|||
表 4 は SQLSetConnectAttr() の Attribute 値をリストしています。 ODBC 初期化ファイルで指定されていない限り、太字で示されている値 はデフォルト値です。Db2® ODBC は、ODBC 3.0 で名前変更されたすべての ODBC 2.0 の Attribute 値を サポートします。
ODBC 3.0 で名前変更された Attribute 値の要約については、『SQLSetConnectAttr() 属性の変更』を参照してください。
ステートメント属性を設定する必要のある ODBC アプリケーションは、SQLSetStmtAttr() を使用してください。ステートメント属性を接続レベルで設定することもサポートされていますが、お勧めできません。
| 属性 | ValuePtr |
|---|---|
| SQL_ATTR_ACCESS_MODE | 以下のいずれかとなる 32 ビット整数値。
この接続では、未解決トランザクションがあってはなりません。 |
| SQL_ATTR_AUTOCOMMIT1 | 自動コミット・モードまたは手動コミット・モードのいずれを使用するかを
指定する 32 ビット整数値。
多くの Db2 環境では、SQL ステートメントの実行とコミットは 別々にデータベース・サーバーに流されるため、自動コミットはコストがかかる可能性があります。 アプリケーション開発者は、自動コミット・モードを選択する場合は、 このことを考慮に入れておいてください。 手動コミット・モードから自動コミット・モードに変更すると、その接続上の オープン・トランザクションはすべてコミットされます。 この属性の設定については、トピック『自動コミットを使用不可にしてネットワークの流れを削減する』を参照してください。 |
| SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION | ロックされているデータに対する同時アクセスをアプリケーションが解決する方法を指定する 32 ビットの整数値。
SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION は、接続を確立する前でも確立した後でも設定可能です。 ステートメントを割り振った後に設定することもできますが、設定が反映されるのは、それより後に割り振られたステートメントに限られます。 |
| SQL_ATTR_CONNECTTYPE2 | このアプリケーションを整合して動く分散環境で実行するか、または協調せずに動く分散環境で
実行するかを指定する 32 ビット整数値。
処理を調整する必要がある場合は、SQL_SYNC_POINT 接続属性と一緒にこの属性を考慮する必要があります。
可能な値には、以下のものがあります。
この属性は、接続要求を行う前に設定する必要があります。 そのようにしない場合には、SQLSetConnectAttr() 呼び出しはリジェクトされます。 アプリケーション内のすべての接続には、 SQL_ATTR_CONNECTTYPE および SQL_ATTR_SYNC_POINT 値が同じである必要があります。最初の接続で、以後の接続の受け入れ可能な属性が決定されます。 IBM 固有: この属性は、IBM が規定した拡張機能です。 推奨事項: アプリケーションは、SQL_ATTR_CONNECTTYPE 属性を接続ごと設定せず、 環境レベルで設定するようにしてください。 整合して動く複数の Db2 トランザクションを利用するために作成された ODBC アプリケーション は、SQLSetEnvAttr() が ODBC でサポートされていないため、それぞれの接続ごとに、 接続レベルでこれらの属性を設定する必要があります。 |
| SQL_ATTR_CURRENT_SCHEMA | szSchemaName ポインターが NULL に設定されている場合、SQLColumns() 呼び出しで Db2 ODBC が
使用するスキーマの名前を含む NULL 終了文字ストリング。 この属性をリセットするには、引数 vParam に 長さゼロまたは NULL ポインターを用いて、この属性を指定します。 この属性は、アプリケーション開発者が、スキーマ名によって 結果セットを制限しない SQLColumns() の総称呼び出しを コーディングしたときに役にたちますが、結果セットをコード内の 分離した場所に限定する必要があります。 この属性はいつでも設定することができ、szSchemaName ポインターが NULL である次の SQLColumns() 呼び出しで有効になります。 IBM 固有: この属性は、IBM が規定した拡張機能です。 |
| SQL_ATTR_DB2EXPLAIN | EXPLAIN 情報を収集するかどうかを指定する 32 ビット整数値。この属性で CURRENT EXPLAIN
MODE 特殊レジスターを設定します。以下のいずれかの値を指定できます。
新規 SQL_ATTR_DB2EXPLAIN 設定は、当該接続の次のステートメント準備で有効になります。 または、DB2EXPLAIN 初期設定キーワードまたは SET CURRENT EXPLAIN MODE SQL ステートメントを使用することで、ODBC アプリケーション用の CURRENT EXPLAIN MODE 特殊レジスターを設定できます。CURRENT EXPLAIN MODE 特殊レジスターを EXPLAIN に設定する場合、SET CURRENT EXPLAIN MODE SQL ステートメントを使用する必要があります。 IBM 固有: この属性は、IBM が規定した拡張機能です。 |
| SQL_ATTR_DECFLOAT_ROUNDING_MODE | アプリケーションによって DECFLOAT データ・タイプ値の丸め方式を制御する 32 ビット整数値。可能な値は、以下のとおりです。
|
| SQL_ATTR_EXTENDED_INDICATORS | EXTENDEDINDICATOR 初期設定キーワード値をオーバーライドする 32 ビット整数値。
|
| SQL_ATTR_MAXCONN3 | アプリケーションがセットアップを希望する最大同時接続数に対応する 32 ビット整数値。
デフォルト値は 0 で、これは最大値がないことを
意味します。アプリケーションはシステム・リソースで許される
個数の接続を設定することができます。整数値は 0 または正数でなければなりません。
これは、アプリケーション単位の最大接続数の管理プログラムとして 使用することができます。 最初の接続が確立される時点で有効な値が、使用される値になります。 最初の接続が確立されると、この値を変更しようとするとリジェクトされます。 IBM 固有: この属性は、IBM が規定した拡張機能です。 推奨事項: アプリケーションは、SQL_ATTR_MAXCONN 属性を接続ごとに設定せず、 環境レベルで設定するようにしてください。ODBC では SQLSetEnvAttr() がサポートされて いないため、ODBC アプリケーションは接続レベルでこの属性を設定する必要があります。 |
| SQL_ATTR_SYNC_POINT | アプリケーションが、1 フェーズの整合トランザクションまたは 2 フェーズの
整合トランザクションのいずれかを選択できるようにする、32 ビットの整数値。
可能な値には、以下のものがあります。
この属性は接続要求の前に設定する必要があります。 そのようにしない場合は、属性設定要求はリジェクトされます。 アプリケーション内のすべての接続には、 SQL_ATTR_CONNECTTYPE および SQL_ATTR_SYNC_POINT 値が同じである必要があります。 最初の接続で、以後の接続の受け入れ可能な属性が決定されます。 推奨事項: アプリケーションは、SQL_ATTR_CONNECTTYPE 属性を接続レベルではなく、環境レベルで設定するようにしてください。 |
| SQL_ATTR_TXN_ISOLATION4 | hdbc で参照される現行の接続のトランザクション分離レベルを
設定する 32 ビットのビット・マスク。SQL_TXN_ISOLATION_OPTION が設定された InfoType 指定
で SQLGetInfo() を呼び出すことによって、vParam の有効値を実行時に判別することが
できます。Db2 ODBC は以下の値を受け入れますが、それぞれのサーバーがこれらの分離レベル
のサブセットしかサポートしない場合があります。
いずれかのステートメント・ハンドルにオープン・カーソルがある間は、 あるいはこの接続で未解決トランザクションがある間は、 この属性は指定できません。指定すると、関数呼び出しの際 に SQL_ERROR (SQLSTATE HY011) が戻されます。 ヒント: IBM 拡張によって、それぞれの個々のステートメント・ハンドルで、 トランザクション分離レベルを設定することができます。SQLSetStmtAttr() の関数の説明で 、SQL_ATTR_STMTTXN_ISOLATION 属性を参照してください。 |
| 注:
|
|
戻りコード
- SQL_SUCCESS
- SQL_INVALID_HANDLE
- SQL_ERROR
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01000 | 警告。 | 通知メッセージ。(SQLSetConnectAttr() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 01S02 | オプション値が変更されました。 | SQL_ATTR_SYNC_POINT が SQL_TWOPHASE に変更されました。SQL_ONEPHASE はサポートされません。 |
| 08S01 | データ・ソースに接続できません。 | アプリケーションとデータ・ソースとの間の通信リンクに、 関数が完了する前に障害が発生しました。 |
| 08003 | 接続はクローズされています。 | オープン接続を必要とする Attribute 値が指定されましたが、ConnectionHandle が 接続された状態にありません。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は指定されたハンドルにメモリーを割り振ることができません。 |
| HY009 | NULL ポインターの使用は無効です。 | ValuePtr に NULL ポインターが渡され、*ValuePtr の値はストリング値でした。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | ステートメント・ハンドルで SQLExecute() または SQLExecDirect() が 呼び出され、SQL_NEED_DATA が戻されました。この関数は、すべての実行時データ・パラメーターまたは列にデータが送られる前に 呼び出されます。 実行時データ条件を取り消すには、SQLCancel() を呼び出してください。 |
| HY011 | この時点では操作は無効です。 | 引数 Attribute は SQL_ATTR_TXN_ISOLATION であり、 トランザクションはオープンされています。 |
| HY024 | 属性値が無効です。 | 指定された Attribute 値について、無効な値が *ValuePtr に指定されました。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | StringLength 引数は 0 より小さい値ですが、SQL_NTS ではありません。 |
| HY092 | オプションのタイプが範囲外です。 | 引数 Attribute に指定された値は、Db2 ODBC のこのバージョンでは無効です。 |
| HYC00 | ドライバーは使用できません。 | 引数 Attribute に指定された値は、Db2 ODBC ドライバーのこのバージョンに対して有効な接続かステートメント属性ですが、データ・ソースでサポートされていません。 |
例
rc=SQLSetConnectAttr( hdbc,SQL_ATTR_AUTOCOMMIT,
(void*) SQL_AUTOCOMMIT_OFF, SQL_NTS);
CHECK_HANDLE( SQL_HANDLE_DBC, hdbc, rc ) ;