SQLSetConnectAttr -- 接続に関するオプションの設定

目的

SQLSetConnectAttr() は接続に関するオプションを設定します。

構文

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

関数の引き数

表 80. SQLSetConnectAttr の引き数

使用法

接続の接続属性は、別の SQLSetConnectAttr() 呼び出しで 変更されるか、SQLDisconnect() 呼び出しでその接続が除去されるまでは有効です。

SQLSetConnectAttr() には、属性情報が入ります。属性情報の形式は、 ヌル終了文字ストリングまたは 32 ビット整数値のいずれかとなります。 それぞれの形式は、属性の説明のところで述べられています。SQLSetConnectAttr() の ValuePtr 引き数が指す文字ストリングの長さは StringLength です。

接続属性

現在定義されている属性は以下のとおりです。

SQL_ATTR_AUTOCOMMIT (DB2 CLI/ODBC)

モード・タイプを指定する 32 ビット整数値。サポートされる値は次のとおりです。

• SQL_AUTOCOMMIT_ON = それぞれのステートメントは自動的にコミットされます。これはデフォルトです。

  自動コミット・モードでは、ステートメントによって行われたすべての更新が、そのステートメントの実行後に自動的に永続化されます。 自動コミット・モード はデフォルトです。デフォルトにより、トランザクション・サポートは 使用不可となっており、さらにはステートメント・レベルのアトミシティは保証されません。 例えば、以下の UPDATE ステートメントは、処理の途中で失敗する可能性があり、 行のサブセットだけが更新される可能性があります。

  UPDATE T SET A = A + 1
  

  更新、削除、挿入の操作が失敗する理由はたくさんあります。例えば、 更新中にチェック制約に違反することがあります。その結果、表の一部が正常に更新できても、 残りの部分が更新できないことがあります。このため、変更はロールバックできません。

• SQL_AUTOCOMMIT_OFF = アプリケーションは、手動で明示的にコミットするか、 トランザクションをロールバックしなければなりません。SQLEndTran() を呼び出すと、 コミットまたはトランザクションのロールバックが行えます。SQLEndTran() の使用法については、 SQLEndTran - COMMIT または ROLLBACK の要求を参照してください。

  手動コミット・モードの場合、トランザクションは暗黙的に開始され、 初めに SQLPrepare()、SQLExecDirect() を使用してデータベースにアクセスします。 この時点では、呼び出しが失敗してもトランザクションは開始されます。 SQLEndTran() を使用して トランザクションを ROLLBACK または COMMIT すると、トランザクションは終了します。

  手動コミット・モードでは、DDL および DML (例えば、CREATE TABLE ステートメントや UPDATE ステートメント) を含む任意の SQL ステートメントをトランザクションで発行できます。

SQL_ATTR_CONNECTION_DEAD (DB2 CLI/ODBC)

接続がまだアクティブであるかどうかを示す読み取り専用の 32 ビット整数値。DB2 CLI は、以下のいずれかの値を戻します。

• SQL_CD_FALSE - 接続がまだアクティブである。
• SQL_CD_TRUE - 接続は非活動である。

SQL_ATTR_LOGIN_TIMEOUT (DB2 CLI/ODBC)

アプリケーションに制御権を戻す前に、ログイン要求の完了を待機する秒数に対応する 32 ビット整数値です。

SQL_ATTR_FILENAME_FORMAT (DB2 Everyplace)

DB2e データベース・エンジンがファイル名を長形式または 8.3 形式のどちらで作成すべきかを指定する 32 ビット整数値。 アプリケーションは、SQLSetConnectAttr が呼び出されたときに、接続されたパスにカタログ・ファイルが存在しない場合にのみ、 ファイル名の形式を変更することができます。 既にカタログ・ファイルが存在するためにファイル名の形式の変更が否認された場合は、 SQLState HY000 の SQL_ERROR が戻されます。 例えば、既に DB2 Everyplace カタログ・ファイルが存在するパスにアプリケーションが接続した場合、 ファイル名の形式を変更しようとするすべての試みが失敗します。 アプリケーションが DB2 Everyplace カタログ・ファイルの存在しないパスに接続し、 最初の CREATE TABLE ステートメントの後にファイル名の形式を変更しようとした場合にも、 SQLSetConnectAttr が SQL_ERROR を戻します。 これは、最初の CREATE TABLE ステートメントの間にカタログ・ファイルが作成されており、 カタログ・ファイルが作成された後はファイル名の形式の変更が許可されていないためです。 デフォルトのファイル名の形式は、プラットフォームごとに異なります。 現在のところ、サポートされるすべてのプラットフォームにおいて、SQL_FILENAME_FORMAT_LONG がデフォルトです。

属性値:

 SQL_FILENAME_FORMAT_LONG - ファイルは長ファイル名形式で作成されます。

 SQL_FILENAME_FORMAT_83- ファイルは 8.3 ファイル名形式で作成されます。

戻りコード

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

診断

表 81. SQLSetConnectAttr の SQLSTATE

制約事項

• トランザクション内で更新できる表の数は制限されています。DB2 Everyplace では、トランザクション内に最大 256 個のオープン・ファイルを許可しています (ただし、オペレーティング・システムも同数のオープン・ファイルを許可しているものと想定した場合)。これは通常、およそ 100 個の表が更新できることを意味しています。 表の数は、索引の使用量とステートメント・ハンドルの数によって決まります。 アクティブなステートメント・ハンドルの数が増えるにつれ、 更新できる表の数は少なくなります。 それぞれの表は、たとえトランザクション内でアクセスや更新が複数回行われても、一度しかカウントされません。
• 複数の表において複数の関連レコードを挿入したり、 一貫性のある更新を行ったりするためのトランザクションが DB2 Everyplace に追加されています。 変更は、アプリケーションがトランザクションをコミットした後に、データ表に書き込まれます。
• アプリケーションが現行トランザクションをコミットせずに早期に終了してしまうと、 そのトランザクション内の更新内容は自動的にロールバックされます。
• SQLEndTran が戻った後、トランザクションはコミットされるかロールバックされます。
• 未完のまま (アクティブ・トランザクションの実行中) に終了したデータベースにアプリケーションが接続すると、トランザクションはリカバリーされます。データベースは、以下の論理を使用してトランザクションをリカバリーします。
  • トランザクションが完了していない場合、データベースは更新されない。
  • トランザクションが完了している場合、データベースはそのトランザクションの情報で更新される。
  • リカバリーが中断された場合、次の接続時に適切なアクションが取られる。

関連した解説

• DB2 CLI 関数の説明の要点
• DB2 CLI 関数の要約
• SQLEndTran - COMMIT または ROLLBACK の要求