SQLSetConnectAttr() - 接続属性を設定する

SQLSetConnectAttr() は、接続の局面を制御する属性を設定します。

SQLSetConnectAttr() の ODBC 仕様

表 1. SQLSetConnectAttr() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
3.0 可 可

構文

SQLRETURN  SQLSetConnectAttr (SQLHDBC           ConnectionHandle,
                              SQLINTEGER        Attribute,
                              SQLPOINTER        ValuePtr,
                              SQLINTEGER        StringLength);

関数の引数

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

表 2. SQLSetConnectAttr() の引数
データ・タイプ 引数 使用法 説明
SQLHDBC ConnectionHandle 入力 接続ハンドル。
SQLINTEGER 属性 入力 設定する接続属性。 属性の完全なリストについては 表 4 を参照してください。
SQLPOINTER ValuePtr 入力 Attribute に関連付けられる値を指すポインター。 *ValuePtr は、Attribute の値によって異なり、32 ビットの符号なし整数値または NUL 終了文字ストリングを指します。 Attribute 引数がドライバー固有値の場合は、*ValuePtr の値は 符号付き整数になる場合があります。
SQLINTEGER StringLength 入力 *ValuePtr 引数についての情報。
  • ODBC が定義した属性の場合
    • ValuePtr が文字ストリングを指す場合、 この引数は *ValuePtr の長さにする必要があります。
    • ValuePtr が整数を指す場合、BufferLength は無視されます。
  • ドライバーが定義する属性 (IBM® 拡張) の場合
    • ValuePtr が文字ストリングを指す場合、この引数は *ValuePtr の長さまたは、 NUL 終了ストリングの場合は SQL_NTS の長さにする必要があります。
    • ValuePtr が整数を指す場合、BufferLength は無視されます。

使用法

アプリケーションは、接続が割り当てられているか、解放されている間はいつでも、SQLSetConnectAttr() を 呼び出すことができます。接続のアプリケーションが設定に成功した接続属性とステートメント属性はすべて、 接続時に SQLFreeHandle() を呼び出すまで持続します。

接続属性によっては、接続が行われる前のみ、または後でのみ設定できるものもあります。 その他の属性は、ステートメントが割り当てられた後では設定できません。次の表は 、それぞれの接続属性をいつ設定できるかを示しています。

表 3. 接続属性を設定できる時点
属性 接続前 接続後 ステートメントを割り当てた後
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 不可 可 可
注:
  1. 属性は、それ以後に割り当てられるステートメントにのみ影響します。
  2. 属性は、接続時のトランザクションがすべてクローズしている場合のみ設定できます。

表 4 は SQLSetConnectAttr() の Attribute 値をリストしています。 ODBC 初期化ファイルで指定されていない限り、太字で示されている値 はデフォルト値です。Db2® ODBC は、ODBC 3.0 で名前変更されたすべての ODBC 2.0 の Attribute 値を サポートします。

ODBC 3.0 で名前変更された Attribute 値の要約については、『SQLSetConnectAttr() 属性の変更』を参照してください。

ステートメント属性を設定する必要のある ODBC アプリケーションは、SQLSetStmtAttr() を使用してください。ステートメント属性を接続レベルで設定することもサポートされていますが、お勧めできません。

表 4. 接続属性
属性 ValuePtr
SQL_ATTR_ACCESS_MODE 以下のいずれかとなる 32 ビット整数値。
SQL_MODE_READ_ONLY
アプリケーションがこの時点からデータの更新を行わないことを示します。 このため、制限の少ない分離レベルおよびロッキングをトランザクションで使用可能です。つまり、非コミット読み取り (SQL_TXN_READ_UNCOMMITTED) が 可能です。

Db2 ODBC では、データベースへの要求が read-only であることを確認しません。 更新要求を出すと、Db2 ODBC は SQL_MODE_READ_ONLY 設定値の 結果として選択されたトランザクション分離レベルを使用して、 その要求を処理します。

QL_MODE_READ_WRITE
アプリケーションがこの時点からデータの更新を行うことを示します。 Db2 ODBC は、この接続に関してデフォルトのトランザクション 分離レベルを使用する状態に戻ります。

SQL_MODE_READ_WRITE がデフォルトです。

この接続では、未解決トランザクションがあってはなりません。

SQL_ATTR_AUTOCOMMIT1 自動コミット・モードまたは手動コミット・モードのいずれを使用するかを 指定する 32 ビット整数値。
SQL_AUTOCOMMIT_OFF
アプリケーションは、SQLEndTran() 呼び出しを使用してトランザクションを手動で明示的にコミットまたはロールバックする必要があります。
SQL_AUTOCOMMIT_ON
Db2 ODBC は自動コミット・モードで動作します。 各ステートメントは、暗黙的にコミットされます。 照会ではない各ステートメントは、実行されるとすぐにコミットされます。 各照会は、関連付けられているカーソルがクローズするとすぐにコミットされます。 これがデフォルト値です。

例外: その接続が整合分散作業単位接続の場合は、 デフォルトは SQL_AUTOCOMMIT_OFF となります。

自動コミットを指定した場合、アプリケーションは 1 つの接続につき 未処理のステートメントは 1 つしか持つことができません。 例えば、2 つのカーソルをオープンにすることはできません。そのようにしないと、 予測不能な結果が生じます。 他の照会が実行される前に、1 つのオープン・カーソルをクローズする必要があります。

多くの Db2 環境では、SQL ステートメントの実行とコミットは 別々にデータベース・サーバーに流されるため、自動コミットはコストがかかる可能性があります。 アプリケーション開発者は、自動コミット・モードを選択する場合は、 このことを考慮に入れておいてください。

手動コミット・モードから自動コミット・モードに変更すると、その接続上の オープン・トランザクションはすべてコミットされます。

この属性の設定については、トピック『自動コミットを使用不可にしてネットワークの流れを削減する』を参照してください。
SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION ロックされているデータに対する同時アクセスをアプリケーションが解決する方法を指定する 32 ビットの整数値。
0
設定なし。これはデフォルト値です。
1
USE CURRENTLY COMMITTED。 読み取りトランザクションは、データが更新中または削除中である場合、現在のコミット済みバージョンのデータにアクセスできます。 挿入中の行はスキップされます。 SQLSetConnectAttr() によってこの値が設定されると、その接続では、すべてのユーザー SELECT ステートメントが USE CURRENTLY COMMITTED 属性を使用して準備されます。 このオプションが適用されるのは、カーソル固定 (CS) 分離が有効になっている場合のみです。
2
WAIT FOR OUTCOME。 更新中または削除中の過程にあるデータにアクセスする必要がある読み取りトランザクションは、COMMIT または ROLLBACK 操作が完了するまで待つ必要があります。 挿入中の行はスキップされません。 SQLSetConnectAttr() によってこの値が設定されると、その接続では、すべてのユーザー SELECT ステートメントが WAIT FOR OUTCOME 属性を使用して準備されます。
3
SKIP LOCKED DATA。 読み取りトランザクションは、他のトランザクションによって相容れないロックが掛けられている行をスキップできます。 SQLSetConnectAttr() によってこの値が設定されると、その接続では、すべてのユーザー SELECT ステートメントが SKIP LOCKED DATA 属性を使用して準備されます。 このオプションが適用されるのは、カーソル固定 (CS) または読み取り固定 (RS) 分離が有効になっている場合のみです。

SQL_ATTR_CONCURRENT_ACCESS_RESOLUTION は、接続を確立する前でも確立した後でも設定可能です。 ステートメントを割り振った後に設定することもできますが、設定が反映されるのは、それより後に割り振られたステートメントに限られます。

SQL_ATTR_CONNECTTYPE2 このアプリケーションを整合して動く分散環境で実行するか、または協調せずに動く分散環境で 実行するかを指定する 32 ビット整数値。 処理を調整する必要がある場合は、SQL_SYNC_POINT 接続属性と一緒にこの属性を考慮する必要があります。 可能な値には、以下のものがあります。
SQL_CONCURRENT_TRANS
アプリケーションは、1 つのデータベースまたは複数のデータベースに対して同時に複数の接続を確立できます。 この属性値は、組み込み SQL のタイプ 1 CONNECT の指定に対応しています。 各接続には、それぞれ独自のコミット範囲があります。トランザクションを協調することが強制的に行われることはありません。

SQL_SYNC_POINT 属性の現行の設定は無視されます。

これはデフォルトです。

SQL_COORDINATED_TRANS
アプリケーションは、複数のデータベース接続間で調整されたコミットとロールバックが行われるよう求めます。 この属性値は、組み込み SQL のタイプ 2 CONNECT の指定に対応 し、SQL_SYNC_POINT 接続属性と一緒に考慮する必要があります。 上記の SQL_CONCURRENT_TRANS 設定とは対照的に、 アプリケーションは 1 つのデータベースにつき 1 つのオープン接続のみを許可されます。

重要: この接続タイプでは、SQL_AUTOCOMMIT 接続属性のデフォルト は SQL_AUTOCOMMIT_OFF になります。

この属性は、接続要求を行う前に設定する必要があります。 そのようにしない場合には、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_DB2EXPLAIN_OFF
CURRENT EXPLAIN MODE 特殊レジスターを NO に設定します。これにより、EXPLAIN 機能が無効になります。
SQL_DB2EXPLAIN_MODE_ON
CURRENT EXPLAIN MODE 特殊レジスターを YES に設定します。これにより、EXPLAIN 機能が有効になります。

EXPLAIN 機能を有効にする場合、以下の要件を満たす必要があります。

  • EXPLAIN 表が存在する必要があります。
  • 現行許可 ID が、EXPLAIN 表に対する INSERT 特権を保持している必要があります。

新規 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 ビット整数値。可能な値は、以下のとおりです。
ROUND_HALF_EVEN
最も近い整数に丸めます。値が 2 つの整数から等距離にある場合、最終桁が偶数になるように丸めます。
ROUND_HALF_UP
最も近い整数に丸めます。値が 2 つの整数から等距離にある場合、切り上げます。
ROUND_DOWN
0 に丸めます。これは切り捨てに相当します。
ROUND_CEILING
正の無限大方向に丸めます。
ROUND_FLOOR
負の無限大方向に丸めます。
ROUND_HALF_DOWN
最も近い整数に丸めます。値が 2 つの整数から等距離にある場合、切り捨てます。
ROUND_UP
ゼロから離れるように丸めます。
SQL_ATTR_EXTENDED_INDICATORS EXTENDEDINDICATOR 初期設定キーワード値をオーバーライドする 32 ビット整数値。
SQL_TRUE
拡張標識サポートが有効になります。
SQL_FALSE
拡張標識サポートが無効になります。SQL_FALSE がデフォルト値です。
SQL_ATTR_MAXCONN3 アプリケーションがセットアップを希望する最大同時接続数に対応する 32 ビット整数値。 デフォルト値は 0 で、これは最大値がないことを 意味します。アプリケーションはシステム・リソースで許される 個数の接続を設定することができます。整数値は 0 または正数でなければなりません。

これは、アプリケーション単位の最大接続数の管理プログラムとして 使用することができます。

最初の接続が確立される時点で有効な値が、使用される値になります。 最初の接続が確立されると、この値を変更しようとするとリジェクトされます。

IBM 固有: この属性は、IBM が規定した拡張機能です。

推奨事項: アプリケーションは、SQL_ATTR_MAXCONN 属性を接続ごとに設定せず、 環境レベルで設定するようにしてください。ODBC では SQLSetEnvAttr() がサポートされて いないため、ODBC アプリケーションは接続レベルでこの属性を設定する必要があります。

SQL_ATTR_SYNC_POINT アプリケーションが、1 フェーズの整合トランザクションまたは 2 フェーズの 整合トランザクションのいずれかを選択できるようにする、32 ビットの整数値。 可能な値には、以下のものがあります。
SQL_ONEPHASE
Db2 ODBC 3.0 ドライバーは SQL_ONEPHASE をサポートしません。
SQL_TWOPHASE
複数データベース・トランザクションにおいて、各データベースで実行された作業をコミットするために、2 フェーズ・コミットが使用されます。 これには、トランザクション・マネージャーを使用して、 このプロトコルをサポートするデータベース間での 2 フェーズ・コミットを 調整する必要があります。1 つのトランザクションの中で、複数の読み取り実施者と複数の更新実施者が 許可されます。 この属性は、SQL_ATTR_CONNECTTYPE 属性が SQL_COORDINATED_TRANS である場合のみ使用されます。 この場合、SQL_TWOPHASE がデフォルトです。SQL_ATTR_CONNECTTYPE が設定されて SQL_CONCURRENT_TRANS になっている 場合は、この属性は無視されます。

この属性は接続要求の前に設定する必要があります。 そのようにしない場合は、属性設定要求はリジェクトされます。

アプリケーション内のすべての接続には、 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_TXN_READ_UNCOMMITTED
ダーティー読み取り、反復不能読み取り、およびファントム読み取りが可能です。
SQL_TXN_READ_COMMITTED
ダーティー読み取りはできません。 反復不能読み取りおよびファントム読み取りは可能です。

これはデフォルトです。

SQL_TXN_REPEATABLE_READ
ダーティー読み取りおよび反復不能読み取りはできません。 ファントム読み取りは可能です。
SQL_TXN_SERIALIZABLE
トランザクションはシリアライズ可能です。 ダーティー読み取り、反復不能読み取り、ファントム読み取りはできません。
SQL_TXN_NOCOMMIT
すべての変更内容は操作が正常に終了した時点で有効にコミットされます。 明示的なコミットやロールバックはできません。これは、 自動コミットに類似しています。 これは ANSI/ISO SQL 規格 (1992) 分離レベルではなく 、DB2® for i のみがサポートする IBM 定義の拡張機能です。
IBM の用語では、
  • SQL_TXN_READ_UNCOMMITTED は「非コミット読み取り」です。
  • SQL_TXN_READ_COMMITTED は「カーソル固定」です。
  • SQL_TXN_REPEATABLE_READ は「読み取り固定」です。
  • SQL_TXN_SERIALIZABLE は「反復可能読み取り」です。

いずれかのステートメント・ハンドルにオープン・カーソルがある間は、 あるいはこの接続で未解決トランザクションがある間は、 この属性は指定できません。指定すると、関数呼び出しの際 に SQL_ERROR (SQLSTATE HY011) が戻されます。

ヒント: IBM 拡張によって、それぞれの個々のステートメント・ハンドルで、 トランザクション分離レベルを設定することができます。SQLSetStmtAttr() の関数の説明で 、SQL_ATTR_STMTTXN_ISOLATION 属性を参照してください。

注:
  1. ODBC 初期化ファイルの AUTOCOMMIT キーワードを用いて、この属性のデフォルト値を 変更することができます。
  2. ODBC 初期化ファイルの CONNECTTYPE キーワードを用いて、この属性のデフォルト値を 変更することができます。
  3. ODBC 初期化ファイルの MAXCONN キーワードを用いて、この属性のデフォルト値を 変更することができます。
  4. ODBC 初期化ファイルの TXNISOLATION キーワードを用いて、この属性のデフォルト値を 変更することができます。

戻りコード

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

診断

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

表 5. SQLSetConnectAttr() の 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 ドライバーのこのバージョンに対して有効な接続かステートメント属性ですが、データ・ソースでサポートされていません。

例

次の例では、SQLConnectAttr() を使用して、ステートメント属性値を設定します。
rc=SQLSetConnectAttr( hdbc,SQL_ATTR_AUTOCOMMIT,
                      (void*) SQL_AUTOCOMMIT_OFF, SQL_NTS);
CHECK_HANDLE( SQL_HANDLE_DBC, hdbc, rc ) ;