仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLSetConnectAttr() は、接続の各局面を管理する属性を設定します。
構文
SQLRETURN SQLSetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHDBC | ConnectionHandle | 入力 | 接続ハンドル。 |
SQLINTEGER | Attribute | 入力 | 設定する属性 (『属性値』のリストに記載)。 |
SQLPOINTER | ValuePtr | 入力 | Attribute と関連付けられる値を指すポインター。 Attribute の値に応じて、*ValuePtr は、 32 ビットの無符号整数値になるか、ヌル終了文字ストリングを指します。 Attribute 引き数がドライバー固有の値である場合、 *ValuePtr の値は符号付き整数になりますので、注意してください。 |
SQLINTEGER | StringLength | 入力 | Attribute が ODBC 定義の属性で、
ValuePtr が文字ストリングか 2 進バッファーを指している場合、この引き数の長さは *ValuePtr の長さにする必要があります。
Attribute が ODBC 定義の属性で、
ValuePtr が整数の場合、StringLength は無視されます。
Attribute が DB2 CLI 属性の場合、アプリケーションは、 StringLength 引き数の設定により、属性の性質を示します。 StringLength には以下の値が入ります。
|
使用法
SQLSetConnectAttr() を使用してステートメント属性を設定する機能はサポートされなくなりました。
SQLSetConnectAttr() を使用してステートメント属性を設定する機能はサポートされなくなりました。バージョン 5 以前に作成されたアプリケーションをサポートするには、このリリースの DB2 CLI の SQLSetConnectAttr() を使用して、いくつかのステートメント属性を設定できます。しかし、この動作に依存するすべてのアプリケーションは、代わりに SQLSetStmtAttr() を使用できるように更新する必要があります。詳細については、SQLSetConnectAttr() を使用してステートメント属性のサブセットを設定するを参照してください。
引き続き SQLSetConnectAttr() を使用してステートメント属性を設定しているバージョン 2 のアプリケーションでは、ステートメント属性が複数の活動状態のステートメントのうちどれかに設定された場合にエラーが戻されると、このステートメント属性は、後で接続に割り当てられるステートメントの省略時値として設定されます。しかし、SQLSetConnectAttr() への同じ呼び出しで直前に設定されたステートメント属性が、関数が異常終了してエラーが戻された後も設定されたままになるかどうかは、定義されていません。 SQLSetConnectAttr() を使ってステートメント属性を設定しないようお勧めする理由の 1 つはこの点にあります。
SQLSetConnectAttr() を呼び出して記述子のヘッダー・フィールドを設定するステートメント属性を設定すると、記述子フィールドは、接続にあるすべてのステートメントと現在関連しているアプリケーション記述子に設定されます。しかし、この属性設定は、今後この接続にあるステートメントと関連する可能性のある記述子には影響を与えません。
接続属性
現在定義されている属性とそれらが導入されている DB2 CLI のバージョンは、下記のとおりです。別のデータ・ソースも利用できるように、さらに多くが今後定義されるものと予想されます。
アプリケーションは、接続が割り当てられてから解放されるまでの任意の時点で SQLSetConnectAttr() を呼び出すことができます。アプリケーションが接続に正常に設定したすべての接続属性とステートメント属性は、この接続上で SQLFreeHandle() が呼び出されるまで有効です。
接続が設定される前しか設定できない接続属性もあります。接続が設定された後しか設定できない接続属性もあり、ステートメントが割り当てられてしまうと設定できないものもあります。次の表に、それぞれの接続属性を設定できるのはいつかを示します。
属性 | 接続前 | 接続後 | ステートメントを割り当てた後 |
---|---|---|---|
SQL_ATTR_ACCESS_MODE | はい | はい | はい a |
SQL_ATTR_ASYNC_ENABLE | はい | はい | いいえ b |
SQL_ATTR_AUTO_IPD (読み取り専用) | いいえ | はい | はい |
SQL_ATTR_AUTOCOMMIT | はい | はい | はい c |
SQL_ATTR_CLISCHEMA | はい | はい | はい |
SQL_ATTR_CLOSE_BEHAVIOR | いいえ | はい | はい c |
SQL_ATTR_CONN_CONTEXT | はい | いいえ | いいえ |
SQL_ATTR_CONNECT_NODE | はい | いいえ | いいえ |
SQL_ATTR_CONNECTTYPE | はい | いいえ | いいえ |
SQL_ATTR_CURRENT_SCHEMA | はい | はい | はい |
SQL_ATTR_DB2_SQLERRP (読み取り専用) | いいえ | はい | はい |
SQL_ATTR_DB2ESTIMATE | いいえ | はい | はい |
SQL_ATTR_DB2EXPLAIN | いいえ | はい | はい |
SQL_ATTR_ENLIST_IN_DTC | いいえ | はい | はい |
SQL_ATTR_INFO_ACCTSTR | いいえ | はい | はい |
SQL_ATTR_INFO_APPLNAME | いいえ | はい | はい |
SQL_ATTR_INFO_USERID | いいえ | はい | はい |
SQL_ATTR_INFO_WRKSTNNAME | いいえ | はい | はい |
SQL_ATTR_LOGIN_TIMEOUT | はい | いいえ | いいえ |
SQL_ATTR_LONGDATA_COMPAT | はい | はい | はい |
SQL_ATTR_MAXCONN | はい | いいえ | いいえ |
SQL_ATTR_OPTIMIZE_SQLCOLUMNS | はい | はい | はい |
SQL_ATTR_QUIET_MODE | はい | はい | はい |
SQL_ATTR_SYNC_POINT | はい | いいえ | いいえ |
SQL_ATTR_TRANSLATE_OPTION | はい | はい | はい |
SQL_ATTR_TXN_ISOLATION | いいえ | はい c | はい a |
SQL_ATTR_WCHARTYPE | はい | はい c | はい c |
|
データ・ソースが *ValuePtr に指定した値をサポートしない場合に、類似した値の置換をサポートする接続属性もあります。このような場合、DB2 CLI は SQL_SUCCESS_WITH_INFO と SQLSTATE 01S02 (オプション値が変更されました。) を戻します。たとえば、アプリケーションが SQL_ATTR_ASYNC_ENABLE を SQL_ASYNC_ENABLE_ON に設定しようとしたのに、サーバーがこの設定をサポートしていない場合、 DB2 CLI は代わりに値 SQL_ASYNC_ENABLE_OFF を代用します。アプリケーションは SQLGetConnectAttr() を呼び出して、代用された値を判別します。
*ValuePtr によって設定した情報の形式は、Attribute の指定により異なります。 SQLSetConnectAttr() は、2 つの異なる形式、つまり、ヌル終了文字ストリングか、32 ビット整数値のどちらかの形式で、属性情報を受け入れます。それぞれの形式の注記は、その属性の説明にあります。 SQLSetConnectAttr() の ValuePtr 引き数が指す文字ストリングの長さは、 StringLength バイトになります。
DB2 CLI バージョン 5.2 以前に導入されたすべての属性と同じく、この長さが属性で定義されている場合、 StringLength 引き数は無視されます。
以下のバージョン 2 接続属性 (SQLSetConnectOption() を使用して設定された) の名前は、バージョン 5 で変更されました。
バージョン 2 での名前 | バージョン 5 以降の名前 |
---|---|
SQL_ACCESS_MODE | SQL_ATTR_ACCESS_MODE |
SQL_AUTOCOMMIT | SQL_ATTR_AUTOCOMMIT |
SQL_CONNECTTYPE | SQL_ATTR_CONNECTTYPE |
SQL_CURRENT_SCHEMA | SQL_ATTR_CURRENT_SCHEMA |
SQL_DB2ESTIMATE | SQL_ATTR_DB2ESTIMATE |
SQL_DB2EXPLAIN | SQL_ATTR_DB2EXPLAIN |
SQL_LOGIN_TIMEOUT | SQL_ATTR_LOGIN_TIMEOUT |
SQL_LONGDATA_COMPAT | SQL_ATTR_LONGDATA_COMPAT |
SQL_MAXCONN | SQL_ATTR_MAXCONN |
SQL_QUIET_MODE | SQL_ATTR_QUIET_MODE |
SQL_SCHEMA | SQL_ATTR_SCHEMA |
SQL_SYNC_POINT | SQL_ATTR_SYNC_POINT |
SQL_TXN_ISOLATION | SQL_ATTR_TXN_ISOLATION |
SQL_WCHARTYPE | SQL_ATTR_WCHARTYPE |
DB2 CLI は、データベースに対する要求が読取専用 であることを確認しません。更新要求を出すと、 DB2 CLI は SQL_MODE_READ_ONLY 設定値の結果として選択されたトランザクション分離レベルを使用して、その要求を処理します。
SQL_MODE_READ_WRITE が省略時値です。
この接続に未解決のトランザクションがあってはなりません。
指定された接続上でステートメントを使用して呼び出された関数を非同期で実行するかどうかを指定する 32 ビット整数値。
SQL_ASYNC_ENABLE_ON を設定すると、今後この接続上に割り当てられるすべてのステートメント・ハンドルを非同期実行できるようになります。また、この設定により、この接続に関連する既存のステートメント・ハンドルの非同期実行も可能になります。接続上に活動状態のステートメントがあるのに非同期実行がオンになっていると、エラーが戻されます。
この属性により、 InfoType SQL_ASYNC_MODE を使用して呼び出される SQLGetInfo() が、 SQL_AM_CONNECTION と SQL_AM_STATEMENT のどちらを戻すかを設定できます。
関数が非同期で呼び出されると、元の関数が SQL_STILL_EXECUTING 以外のコードを戻すまでは、 StatementHandle に関連するステートメントまたは接続時に、元の関数、 SQLAllocHandle()、 SQLCancel()、SQLGetDiagField()、または SQLGetDiagRec() しか呼び出せません。 StatementHandle または StatementHandle に関連する接続時に呼び出される他の関数は、 SQLSTATE HY010 の SQL_ERROR (関数順序エラー) を戻します。関数は、他のステートメント時に呼び出せます。
一般に、アプリケーションは、シングル・スレッドのオペレーティング・システム上で、非同期で関数を実行する必要があります。マルチ・スレッドのオペレーティング・システムの場合は、同じスレッドで非同期に実行するのではなく、別々のスレッドでアプリケーションを実行すべきです。マルチ・スレッドのオペレーティング・システムでしか実行できないアプリケーションは、非同期実行をサポートする必要はありません。詳細については、マルチスレッドのアプリケーション作成および CLI の非同期実行を参照してください。
以下の関数は、非同期で実行できます。
SQLColAttribute() SQLGetTypeInfo() SQLColumnPrivileges() SQLMoreResults() SQLColumns() SQLNumParams() SQLCopyDesc() SQLNumResultCols() SQLDescribeCol() SQLParamData() SQLDescribeParam() SQLPrepare() SQLExecDirect() SQLPrimaryKeys() SQLExecute() SQLProcedureColumns() SQLFetch() SQLProcedures() SQLFetchScroll() SQLPutData() SQLForeignKeys() SQLSetPos() SQLGetData() SQLSpecialColumns() SQLGetDescField() 1* SQLStatistics() SQLGetDescRec() 1* SQLTablePrivileges() SQLGetDiagField() SQLTables() SQLGetDiagRec() 1* これらの関数は、記述子がインプリメンテーション記述子であり、 アプリケーション記述子でない場合にのみ、非同期で呼び出せます。
SQLPrepare() 呼び出しの後で IPD の自動移植をサポートするかどうかを指定する、読み取り専用の 32 ビット整数値。
SQL_ATTR_AUTO_IPD 接続性に SQL_TRUE が戻される場合は、接続属性 SQL_ATTR_ENABLE_AUTO_IPD を設定して、 IPD 自動移植のオン / オフを切り換えることができます。 SQL_ATTR_AUTO_IPD が SQL_FALSE の場合、 SQL_ATTR_ENABLE_AUTO_IPD を SQL_TRUE に設定することはできません。
SQL_ATTR_ENABLE_AUTO_IPD の省略時値は、 SQL_ATTR_AUTO_IPD の値と等しくなります。
この接続属性は、SQLGetConnectAttr() によって戻せますが、 SQLSetConnectAttr() で設定することはできません。
SQL_AUTOCOMMIT_ON は省略時値です。
注: | この値が調整された分散作業接続単位の場合、省略時値は SQL_AUTOCOMMIT_OFF になります。 |
多くの DB2 環境では、 SQL ステートメントの実行およびコミットは別個にデータベース・サーバーへ流される場合があるので、自動コミットは費用がかかることがあります。アプリケーション開発者が自動コミット・モードを選択するときに、このことを考慮に入れることをお勧めします。
注: | 手動のコミット・モードから自動コミット・モードへ変更すると、接続上のオープン・トランザクションをコミットします。 |
DB2 CLI バージョン 1 アプリケーションは、省略時値が手動コミット・モードであると想定しています。 非互換性を参照してください。
DB2 ODBC カタログ視点 (これは、使用するホスト DBMS 上に保管されている) の名前が入っているヌル終了文字ストリング。
DB2 ODBC カタログは、 DB2 コネクトを使用してホスト DBMS に接続する ODBC アプリケーションによる、表リストのスキーマ呼び出しのパフォーマンスを向上させるよう設計されています。
DB2 ODBC カタログは、ホスト DBMS 上で作成および保守されます。これには、実際の DB2 カタログに定義されているオブジェクトを表す行が入っていますが、各行に入っているのは、ODBC 操作をサポートするのに必要な列だけです。 DB2 ODBC カタログ内の表は、事前に結合されており、 ODBC アプリケーションによる高速カタログ・アクセスをサポートするための索引付けがなされています。
システム管理者は、複数の DB2 ODBC カタログ視点を作成し、それぞれに特定のユーザー・グループが必要とする行だけを含めることができます。各エンド・ユーザーは、自分が使用する DB2 ODBC カタログを (この属性を設定することによって) 選択できます。
この属性には SYSSCHEMA キーワードと似た効果がありますが、可能な場合には SQL_ATTR_CLISCHEMA の方を使用するようにしてください。 SQL_ATTR_CLISCHEMA を使用すると、データ・アクセスの効率が向上します。 SYSSCHEMA で使用するユーザー定義の表は DB2 カタログ表のミラー・イメージであり、 ODBC ユーザーに必要な情報を作成するためには、 ODBC ドライバーが複数の表の行を結合する必要がありました。また、SQL_ATTR_CLISCHEMA を使用すると、カタログ表の競合も減少します。
これに対応する DB2 CLI/ODBC ドライバー構成キーワード (CLISCHEMA) もあります。
カーソルがクローズする時、カーソルの操作時に獲得された読み取りロックの解放を DB2 サーバーに試行させるかどうかを指定する 32 ビット整数値。次のどちらかに設定できます。
分離 UR または CS でオープンされているカーソルの場合、カーソルが行から移動した後、読み取りロックは保持されません。分離 RS または RR でオープンされているカーソルの場合、 SQL_ATTR_CLOSE_BEHAVIOR はそれらの分離レベルのいくつかを変更し、 RR カーソルで非反復読み取りまたは単独読み取りが行われることがあります。
元々 RR または RS であるカーソルが、クローズされた後で SQL_ATTR_CLOSE_BEHAVIOR で再度オープンされると、新しい読み取りロックが獲得されます。
詳しくは、SQLCloseCursor - カーソルをクローズして保留の結果を廃棄するを参照してください。
接続でどのコンテキストを使用するかを示します。 SQLPOINTER は次のどちらかになります。
この属性を使用できるのは、アプリケーションが DB2 コンテキスト API を使ってマルチ・スレッド・アプリケーションを管理している場合だけです。省略時設定では、DB2 CLI は接続ハンドルごとに 1 つのコンテキストを割り当て、実行スレッドが確実に正しいコンテキストに接続されるようにすることにより、コンテキストを管理しています。
いつアプリケーションがコンテキストを管理すべきかについては、 マルチスレッドのアプリケーション作成を参照してください。
コンテキストの詳細については、 管理 API 解説書 の sqleBeginCtx() API を参照してください。
この変数を設定しないと、ターゲット論理ノードは、デフォルトにより、マシンでポート 0 として定義されている論理ノードに設定されます。
これに対応する DB2 CLI/ODBC ドライバー構成キーワード (CONNECTTYPE) もあります。
接続が依然としてアクティブであるかどうかを示す、読み取り専用 32 ビット整数値。 DB2 CLI は、次のいずれかの値を戻します。
この属性は、主に Microsoft ODBC ドライバー・マネージャー 3.5x によって、接続をプールする前に使用されます。
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
アプリケーションに戻る前に、要求が完了するまで待機する秒数に対応する 32 ビット整数値。
DB2 CLI は、常に ValuePtr が 0 (省略時値) に設定されたかのように動作します。タイムアウトはありません。
SQL_ATTR_SYNC_POINT オプションの現行設定は無視されます。
これは省略時値です。
注: | この接続タイプでは、 SQL_ATTR_AUTOCOMMIT 接続オプションの省略時値である SQL_AUTOCOMMIT_OFF の設定になります。 |
このオプションは、接続要求を行う前に設定する必要があります。そうしない場合は、SQLSetConnectOption() 呼び出しは拒否されます。
アプリケーション内のすべての接続の SQL_ATTR_CONNECTTYPE 値と SQL_ATTR_SYNC_POINT 値は、同じ値でなければなりません。最初の接続で、以後の接続のために受け入れ可能な属性を判別します。アプリケーションが SQL_ATTR_CONNECTTYPE 属性を設定するときに、接続レベルではなく、環境レベルで設定することをお勧めします。整合 DB2 トランザクションを利用するために書かれた ODBC アプリケーションは、 SQLSetEnvAttr() が ODBC でサポートされていないので、各接続の接続レベルでこれらの属性を設定する必要があります。
この省略時接続タイプは、 CONNECTTYPE DB2 CLI/ODBC 構成キーワードを使用して設定することもできます。詳しくは db2cli.ini の構成を参照してください。
注: | これは、IBM 定義の拡張機能です。 |
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
データ・ソースで使用するカタログの名前が入っているヌル終了文字ストリング。
このオプションをリセットするには、 ValuePtr 引き数を長さゼロまたはヌル・ポインターとして、このオプションを指定します。
このオプションは、アプリケーション開発者が、 SQLColumns() への一般呼び出しを次のようにコーディングしてある場合に便利です。つまり、スキーマ名で結果セットを制限せず、結果セットをコード内で孤立させて制約をかける必要がある場合です。
このオプションはいつでも設定することができ、 szSchemaName ポインターがヌルである次の SQLColumns() 呼び出しで有効になります。
注: | これは、IBM 定義の拡張機能です。 |
製品を表す 3 文字の識別子で始まり、その後にバージョン、リリース、および修正レベルを表す 5 つの数字が続きます。たとえば、SQL05000 は DB2 ユニバーサル・データベースのバージョン 5 リリース 0 修正レベル 0 を表します。
SQLCODE がエラー条件を示している場合は、このフィールドはエラーを戻したモジュールを識別します。
接続が正しく完了したときにも、このフィールドが使用されます。
sqlca およびこの特定のフィールドの詳細については、SQL 解説書 を参照してください。
これは省略時値です。
グラフィカル・ウィンドウには、最適化プログラムの評価と、この照会を続行するか取り消すかを選択するための押しボタンが表示されます。
このオプションの推奨値は 60000 です。
このオプションは、SQL_ATTR_QUIET_MODE との組み合わせで使用され、グラフィカル・ユーザー・インターフェースのあるアプリケーションのみ適用されます。アプリケーションは、このオプションを使用せずに、 SQLPrepare() の次に SQLGetSQLCA() を呼び出して照会を出し、次いで適切な情報を表示することによって、この機能を直接実装し、より統合化された包括的なインターフェースを実現できます。
新規の SQL_ATTR_DB2ESTIMATE 設定は、この接続の次のステートメント準備で有効になります。
注: | これは、IBM 定義の拡張機能です。 |
Explain 情報を生成する前に、Explain 表を作成しなければなりません。補足情報については、SQL 解説書 を参照してください。
このステートメントはトランザクションに制御されませんし、ROLLBACK の影響も受けません。新規の SQL_ATTR_DB2EXPLAIN 設定は、この接続の次のステートメント準備で有効になります。
現行の許可 ID は、Explain 表に対して INSERT 特権を持っていなければなりません。
この値は、 DB2EXPLAIN DB2 CLI/ODBC 構成キーワードを使用して設定することもできます。詳しくは db2cli.ini の構成を参照してください。
注: | これは、IBM 定義の拡張機能です。 |
次のいずれかの SQLPOINTER。
アプリケーションは、接続の状態を非分散トランザクション状態から分散トランザクション状態に変更するよう、 DB2 CLI/ODBC ドライバーに求めています。接続の参加は、分散トランザクション調整プログラム (DTC) によって行われます。
アプリケーションは、接続の状態を分散トランザクション状態から非分散トランザクション状態に変更するよう、 DB2 CLI/ODBC ドライバーに求めています。
この属性は、Microsoft Transaction Server (MTS) との接続の参加、または参加の取り止めを行うために、MTS の環境でのみ使用されます。
この属性に非ヌル・トランザクション・ポインターを指定して使用すると、直前のトランザクションは終了して、新しいトランザクションが開始されたものと想定されます。非ヌル・ポインターを指定してこの API を呼び出す前に、アプリケーションは ITransaction メンバー関数 Endtransaction を呼び出す必要があります。そうしないと、直前のトランザクションが打ち切られてしまいます。アプリケーションは、同じトランザクション・ポインターを使用して複数の接続を参加させることができます。
注: | この接続属性は、トランザクションごとに MTS が自動的に指定するものであって、ユーザー・アプリケーションがコーディングするものではありません。 |
DB2 コネクトを使用しているときに、ホスト・データベース・サーバーに送信されるクライアント会計ストリングを識別するのに使用される、ヌル文字で終了する文字ストリング。以下の点に注意してください。
注: | これは、IBM 定義の拡張機能です。 |
DB2 コネクトを使用しているときに、ホスト・データベース・サーバーに送信されるクライアント・アプリケーション名を識別するのに使用される、ヌル文字で終了する文字ストリング。以下の点に注意してください。
注: | これは、IBM 定義の拡張機能です。 |
DB2 コネクトを使用しているときに、ホスト・データベース・サーバーに送信されるクライアント・ユーザー ID を識別するのに使用される、ヌル文字で終了する文字ストリング。以下の点に注意してください。
注: | これは、IBM 定義の拡張機能です。 |
DB2 コネクトを使用しているときに、ホスト・データベース・サーバーに送信されるクライアント・ワークステーション名を識別するのに使用される、ヌル文字で終了する文字ストリング。以下の点に注意してください。
注: | これは、IBM 定義の拡張機能です。 |
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
アプリケーションに戻る前に、ログイン要求が完了するまで待機する秒数に対応する 32 ビット整数値。 ValuePtr 引き数で許可されている値は 0 だけです。つまり、接続を試行すると、接続が確立されるか、基礎となる通信層がタイムアウトになるまで待機します。
注: | これは、IBM 定義の拡張機能です。 |
これは、アプリケーション・ベースでの接続の最大数のための管理プログラムとして使用できます。
OS/2、Windows 95、および Windows NT で NetBIOS プロトコルが使用中の場合に、この値は、アプリケーションで並行してセットアップされる接続 (NetBIOS セッション) の数に対応します。 OS/2 NetBIOS の値の範囲は、1 から 254 までです。 0 (省略時値) を指定すると、5 つの予約済み 接続が行われます。他のアプリケーションは、予約済み NetBIOS セッションを使用できません。このパラメーターで指定された接続数は、 DB2 NetBIOS プロトコルがリモート・サーバーに接続するのに使用するアダプターに適用されます (アダプター番号は NetBIOS ノードのノード・ディレクトリーで指定します)。
最初の接続が確立される時点で有効な値は、使用しようとしている値です。最初の接続がすでに確立されていると、この値を変更しようとしても拒否されます。アプリケーションが SQL_ATTR_MAXCONN を設定するときに、接続レベルではなく環境レベルで設定することをお勧めしてきました。 ODBC アプリケーションは、SQLSetEnvAttr() がサポートされていないので、接続レベルでこの属性を設定する必要があります。
同時接続の最大数は、 MAXCONN DB2 CLI/ODBC 構成キーワードを使用して設定することもできます。詳しくは db2cli.ini の構成を参照してください。
注: | これは、IBM 定義の拡張機能です。 |
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
カタログ関数のストリング引き数を処理する方法を決定する SQLUINTEGER 値。
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
ドライバー・マネージャーが ODBC カーソル・ライブラリーを使用する方法を指定する 32 ビット・オプション。
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
ネットワーク・パケット・サイズをバイト単位で指定する 32 ビット整数値。
アプリケーションがこのオプションを指定して SQLSetConnectOption() を呼び出したことがない場合、 DB2 CLI はこのオプションに、 SQLGetConnectOption() に対するヌルの親ウィンドウ・ハンドルを戻し、ヌルの親ウィンドウ・ハンドルを使用してダイアログ・ボックスを表示します。たとえば、エンド・ユーザーが (DB2 CLI 初期設定ファイルの項目を介して) 最適化プログラム情報を表示するよう求めると、 DB2 CLI はヌルのウィンドウ・ハンドルを使用してこの情報が入っているダイアログ・ボックスを表示します。 (プラットフォームによっては、ダイアログ・ボックスが画面の中央に表示されます。)
ValuePtr がヌル・ポインターである場合、 DB2 CLI はダイアログ・ボックスを表示しません。エンド・ユーザーが最適化プログラム見積もりを表示するよう求める上記の例では、アプリケーションが明示的にそのようなダイアログ・ボックスをすべて抑止するので、 DB2 CLI はこれらの見積もりを表示しません。
ValuePtr がヌル・ポインターではない場合、アプリケーションの親ウィンドウ・ハンドルになるはずです。 DB2 CLI は、このハンドルを使ってダイアログ・ボックスを表示します。 (プラットフォームによっては、ダイアログ・ボックスがアプリケーションのアクティブ・ウィンドウとの関係において、中央に表示されます。)
注: | この接続オプションを、 SQLDriverConnect() ダイアログ・ボックスを隠すために使用することはできません。 (隠すためには、fDriverCompletion 引き数を SQL_DRIVER_NOPROMPT に設定します。) |
分散作業単位 (トランザクション) の詳細については、SQL 解説書 を参照してください。
アプリケーション内のすべての接続の SQL_ATTR_CONNECTTYPE 値と SQL_SYNCPOINT 値は、同じ値でなければなりません。最初の接続で、以後の接続のために受け入れ可能な属性を判別します。アプリケーションが SQL_ATTR_CONNECTTYPE 属性を設定するときに、接続レベルではなく、環境レベルで設定することをお勧めします。整合 DB2 トランザクションを利用するために書かれた ODBC アプリケーションは、 SQLSetEnvAttr() が ODBC でサポートされていないので、接続レベルでこれらの属性を設定する必要があります。
調整トランザクションのタイプを SYNCPOINT DB2 CLI/ODBC 構成キーワードを使用して設定することもできます。詳しくは db2cli.ini の構成を参照してください。
注: | これは、IBM 拡張機能です。組み込み SQL では、SYNCPOINT NONE という追加の同期点設定があります。 SYNCPOINT NONE は、同じデータベースへの複数の接続を許可していないので、 SQL_ATTR_CONNECTTYPE オプションの SQL_CONCURRENT_TRANS 設定よりも限定された設定です。結果的に、DB2 CLI は SYNCPOINT NONE をサポートする必要はありません。 |
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
トレースを実行するかどうか DB2 CLI に指示する 32 ビット整数値。
DB2 CLI トレース機能は、属性ではなく TRACE DB2 CLI/ODBC 構成キーワードを使用して設定できます。詳しくは db2cli.ini の構成を参照してください。
この接続属性は ODBC により定義されますが、DB2 CLI ではサポートされません。その結果、この属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
トレース・ファイルの名前が入っているヌルで終了する文字ストリング。
DB2 CLI トレース・ファイル名は、この属性ではなく、 TRACEFILENAME DB2 CLI/ODBC 構成キーワードを使用して設定されます。詳しくは db2cli.ini の構成を参照してください。
この接続属性は ODBC により定義されますが、Windows 3.1 の DB2 CLI でのみサポートされます。その結果、その他のプラットフォームでこの属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
DB2 クライアント・アプリケーション・イネーブラー (Windows 版) またはソフトウェア開発者キット (Windows 版) をインストールしたディレクトリーを指示します。 DB2TRANS.DLL は、コード・ページ・マッピング表が入っている DLL です。
このオプションは、DB2 (OS/2 版) バージョン 1 に接続されているとき、またはバージョン 2.3 以前のバージョンの DDCS (OS/2 版) を使用しているときに、 16 ビット・バージョンの Windows 上で使用できます。 TRANSLATEOPTION と組み合わせて使用され、NLS SBCS 文字 (ドイツ語のウムラウト文字など) と、 Windows コード・ページ 1004 の対応する文字の正確なマッピングを提供します。
注: | このオプションは、 Windows アプリケーションが接続するサーバーが下位バージョンのサーバー (たとえば DB2 バージョン 1) で、そのサーバーでは非同等コード・ページ変換がサポートされていない場合には便利です。 |
この接続属性は ODBC により定義されますが、Windows 3.1 の DB2 CLI でのみサポートされます。その結果、その他のプラットフォームでこの属性を設定または入手しようとすると、 SQLSTATE が HYC00 (ドライバーが機能しない) になります。
DB2 バージョン 1 でのデータベースのコード・ページ番号 (データベース構成パラメーターを照会すると取得できます) を定義します。 TRANSLATEDLL および TRANSLATEOPTION を指定すると、コード・ページ番号 database codepage number から Windows 1004 コード・ページに文字を変換できるようになります。
database codepage number でサポートされている値には、437 と 850 の 2 つがあります。それ以外の値を指定すると、変換が不可能であるということを示す警告が、接続要求時に戻されます。
注: | このオプションは、 Windows アプリケーションが接続するサーバーが下位バージョンのサーバー (たとえば DB2 バージョン 1) で、そのサーバーでは非同等コード・ページ変換がサポートされていない場合には便利です。 |
これは省略時値です。
IBM の用語では、
分離レベルの詳細については、SQL 解説書 を参照してください。
このオプションは、hstmt にオープン・カーソルがあったり、この接続に未解決のトランザクションがあったりすると指定できません。それ以外の場合は、関数呼び出し時に SQL_ERROR (SQLSTATE S1011) が戻されます。
この属性 (または対応するキーワード) を使用できるのは、省略時の分離レベルが使用される場合だけです。アプリケーションが特定の分離レベルを設定する場合は、この属性を設定しても効果はありません。
注: | ステートメント・ハンドルでトランザクション分離レベルの設定を許可する IBM 拡張機能があります。 SQLSetStmtOption() の関数記述にある SQL_STMTTXN_ISOLATION オプションを参照してください。 |
これは省略時値です。
マルチバイト・アプリケーション変数の使用法については、アプリケーション開発の手引き を参照してください。
注: | これは、IBM 定義の拡張機能です。 |
戻りコード
診断
DB2 CLI は、SQL_SUCCESS_WITH_INFO を戻して、オプション設定の結果に関する情報を提供することができます。
Attribute がステートメント属性の場合、SQLSetConnectAttr() は
SQLSetStmtAttr() によって戻される任意の SQLSTATE を戻すことができます。
表 151. SQLSetConnectAttr SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 一般的なエラーです。 | 通知メッセージです。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01S02 | オプション値が変更されました。 | DB2 CLI は、*ValuePtr で指定した値をサポートしておらず、類似した値を代用しました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
08002 | 接続が使用中です。 | 引き数 Attribute は SQL_ATTR_ODBC_CURSORS で、 DB2 CLI はすでにデータ・ソースに接続されていました。 |
08003 | 接続がクローズされています。 | オープン接続が必要な Attribute 値が指定されましたが、 ConnectionHandle は接続状態になっていませんでした。 |
08S01 | 通信リンクに障害が起きました。 | 関数が処理を完了する前に、DB2 CLI とその接続先データ・ソースとの間の通信リンクが失敗しました。 |
24000 | カーソル状態が無効です。 | 引き数 Attribute は SQL_ATTR_CURRENT_QUALIFIER で、結果セットは保留になっていました。 |
HY000 | 一般的なエラーです。 | 処理系固有の SQLSTATE が存在しなかったり、定義されなかった場合のエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec() が戻したエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。 |
HY009 | 引き数値が無効です。 | ValuePtr にヌル・ポインターが渡され、*ValuePtr の値はストリング値でした。 |
HY010 | 関数の順序エラーです。 | ConnectionHandle と関連する StatementHandle の非同期関数が呼び出され、
SQLSetConnectAttr() が呼び出された時点でまだ実行中でした。
ConnectionHandle と関連する StatementHandle の SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。
ConnectionHandle の SQLBrowseConnect() が呼び出され、SQL_NEED_DATA が戻されました。この関数は、 SQLBrowseConnect() が SQL_SUCCESS_WITH_INFO または SQL_SUCCESS を戻す前に呼び出されました。 |
HY011 | この段階で操作は無効です。 | 引き数 Attribute は SQL_ATTR_TXN_ISOLATION で、トランザクションはオープンされていました。 |
HY024 | 属性値が無効です。 | 指定されている Attribute 値に対して、*ValuePtr に無効値を指定しました。
(DB2 CLI がこの SQLSTATE を戻すのは、
SQL_ATTR_ACCESS_MODE や SQL_ATTR_ASYNC_ENABLE などの離散的な値セットを受け入れる接続およびステートメント属性に対してのみです。その他すべての接続およびステートメント属性の場合、
DB2 CLI は ValuePtr に指定されている値を確認する必要があります。)
Attribute 引き数は SQL_ATTR_TRACEFILE または SQL_ATTR_TRANSLATE_LIB で、 *ValuePtr は空ストリングでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | StringLength 引き数は 0 未満でしたが、SQL_NTS ではありませんでした。 |
HY092 | オプション・タイプが範囲外です。 | DB2 CLI のこのバージョンでは、引き数 Attribute の指定値が無効です。 |
HYC00 | ドライバーが機能していません。 | 引き数 Attribute に指定された値は、このバージョンの DB2 CLI ドライバーには有効な接続またはステートメント属性でしたが、データ・ソースによりサポートされていませんでした。 |
制約
なし。
(ここで完全サンプル utilcli.c を使用することもできます 。)
/* From the CLI sample utilcli.c */ /* set AUTOCOMMIT off or on */ sqlrc = SQLSetConnectAttr( *pHdbc, SQL_ATTR_AUTOCOMMIT, autocommitValue, SQL_NTS) ; HANDLE_CHECK( SQL_HANDLE_DBC, *pHdbc, sqlrc, pHenv, pHdbc ) ;
参照