• [アーティクル]

SQLSetStmtAttr

SQL Server Native Client ODBC ドライバーは、混合 (キーセット/動的) カーソル モデルをサポートしません。SQL_ATTR_KEYSET_SIZE を使用してキーセットのサイズを設定する場合、0 以外の値を設定すると失敗します。

アプリケーションは、すべてのステートメントで SQL_ATTR_ROW_ARRAY_SIZE を設定して、SQLFetch または SQLFetchScroll 関数呼び出しで返される行数を宣言します。ドライバーは、サーバー カーソルを指定するステートメントで SQL_ATTR_ROW_ARRAY_SIZE を使用して、カーソルからのフェッチ要求を満たすためにサーバーが生成する行ブロックのサイズを判断します。トランザクションの分離レベルが、コミット済みのトランザクションの反復可能読み取りを保証できるレベルの場合、行のメンバーシップや順序が、動的カーソルのブロック サイズに収まる範囲内で固定されます。カーソルは、この値で示されるブロック外では完全に動的になります。サーバー カーソルのブロック サイズは完全に動的で、フェッチ処理のどの時点でも変更可能です。

SQLSetStmtAttr とテーブル値パラメーター

SQLSetStmtAttr を使用すると、テーブル値パラメーター列の記述子フィールドにアクセスする前に、アプリケーション パラメーター記述子 (APD) の SQL_SOPT_SS_PARAM_FOCUS を設定できます。

SQL_SOPT_SS_PARAM_FOCUS にテーブル値パラメーター以外のパラメーターの序数を設定しようとすると、SQLSetStmtAttr は SQL_ERROR を返し、"属性の値が正しくありません" というメッセージを含む SQLSTATE = HY024 の診断レコードが作成されます。SQL_SOPT_SS_PARAM_FOCUS は、SQL_ERROR が返されたときに変更されません。

SQL_SOPT_SS_PARAM_FOCUS に 0 を設定すると、パラメーターの記述子レコードへのアクセスが復元されます。

SQLSetStmtAttr を使用して SQL_SOPT_SS_NAME_SCOPE を設定することもできます。詳細については、このトピックの後半の「SQL_SOPT_SS_NAME_SCOPE」のセクションを参照してください。

詳細については、「準備されたステートメント用のテーブル値パラメータのメタデータ」を参照してください。

テーブル値パラメーターの詳細については、「テーブル値パラメータ (ODBC)」を参照してください。

SQLSetStmtAttr によるスパース列のサポート

SQLSetStmtAttr を使用すると、SQL_SOPT_SS_NAME_SCOPE を設定できます。詳細については、このトピックの後半の「SQL_SOPT_SS_NAME_SCOPE」のセクションを参照してください。スパース列の詳細については、「スパース列のサポート (ODBC)」を参照してください。

ステートメント属性

SQL Server Native Client ODBC ドライバーは、次のドライバー固有のステートメント属性もサポートします。

SQL_SOPT_SS_CURSOR_OPTIONS

カーソルでのドライバー固有のパフォーマンス オプションを使用するかどうかを指定します。このオプションが設定されているときは、SQLGetData を使用できません。既定の設定は SQL_CO_OFF です。このオプションは、SQL Server 7.0 以降のインスタンスに接続している場合にのみ有効です。ValuePtr 値の型は SQLLEN です。

ValuePtr 値

説明

SQL_CO_OFF

既定値。高速順方向専用かつ読み取り専用のカーソルと autofetch を無効にし、高速順方向専用かつ読み取り専用のカーソルでの SQLGetData を有効にします。SQL_SOPT_SS_CURSOR_OPTIONS を SQL_CO_OFF に設定すると、カーソルの種類は変更されません。つまり、高速順方向専用カーソルは高速順方向専用カーソルのままです。カーソルの種類を変更するには、アプリケーションで SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE を使用して、別の種類を設定する必要があります。

SQL_CO_FFO

高速順方向専用かつ読み取り専用のカーソルを有効にし、高速順方向専用かつ読み取り専用のカーソルでの SQLGetData を無効にします。

SQL_CO_AF

すべてのカーソルの種類で autofetch オプションを有効にします。ステートメント ハンドルにこのオプションを設定すると、SQLExecute または SQLExecDirect では暗黙的な SQLFetchScroll (SQL_FIRST) が生成されます。カーソルが開かれ、最初の行バッチが 1 回のラウンドトリップでサーバーに返されます。

SQL_CO_FFO_AF

autofetch オプションを設定して高速順方向専用カーソルを有効にします。これは、SQL_CO_AF と SQL_CO_FFO の両方を指定した場合と同じです。

これらのオプションを設定すると、サーバーは最後の行がフェッチされたことを検出した時点で、カーソルを自動的に閉じます。その場合も、アプリケーションでは SQLFreeStmt (SQL_CLOSE) または SQLCloseCursor を呼び出す必要はありますが、ドライバーからサーバーへ、カーソルを閉じる通知を送信する必要はありません。

選択リストに text、ntext、または image 列が含まれている場合、高速順方向専用カーソルが動的カーソルに変換され、SQLGetData が有効になります。

SQL_SOPT_SS_DEFER_PREPARE

ステートメントをすぐに準備するか、SQLExecute、SQLDescribeCol、または SQLDescribeParam が実行されるまで準備を遅延するかを指定します。SQL Server 7.0 以前のバージョンでは、このプロパティは無視されます (準備は遅延されません)。ValuePtr 値の型は SQLLEN です。

ValuePtr 値

説明

SQL_DP_ON

既定値。SQLPrepare を呼び出すと、SQLExecute が呼び出されるか、メタプロパティ操作 (SQLDescribeCol または SQLDescribeParam) が実行されるまで、ステートメントの準備が遅延されます。

SQL_DP_OFF

SQLPrepare の実行直後にステートメントが準備されます。

SQL_SOPT_SS_REGIONALIZE

ステートメント レベルのデータ変換を決定します。この属性を設定すると、日付、時刻、通貨の値を文字列値に変換する際に、ドライバーはクライアントのロケール設定を使用します。この場合の変換は、SQL Server ネイティブ データ型から文字列への変換のみです。

ValuePtr 値の型は SQLLEN です。

ValuePtr 値

説明

SQL_RE_OFF

既定値。ドライバーは、日付、時刻、通貨の値を文字列データに変換する際に、クライアントのロケール設定を使用しません。

SQL_RE_ON

ドライバーは、日付、時刻、通貨の値を文字列データに変換する際に、クライアントのロケール設定を使用します。

地域別の変換の設定は、通貨、数値、日付、および時刻のデータ型に適用されます。変換の設定は、通貨、数値、日付、または時刻の値を文字列に変換するときの出力変換にのみ適用されます。

注意注

ステートメント オプション SQL_SOPT_SS_REGIONALIZE が有効な場合、ドライバーは現在のユーザーのロケール レジストリ設定を使用します。SetThreadLocale を呼び出す場合など、アプリケーションでスレッドのロケールが設定されているときは、現在のスレッドのロケールは無視されます。

データ ソースの地域別の動作を変更すると、アプリケーション エラーが発生することがあります。日付文字列を解析し、ODBC の定義に従った形式の日付文字列を受け付けるアプリケーションは、地域別の動作の値を変更することによって、悪影響を受ける可能性があります。

SQL_SOPT_SS_TEXTPTR_LOGGING

text 型または image 型のデータを含む列に対する操作のログ記録の有効と無効を切り替えます。既定の動作では、これらの操作のログは記録されます (SQL_TL_ON)。ValuePtr 値の型は SQLLEN です。

ValuePtr 値

説明

SQL_TL_OFF

text 型と image 型のデータに対して実行される操作のログ記録を無効にします。

SQL_TL_ON

既定値。text 型と image 型のデータに対して実行される操作のログ記録を有効にします。

SQL_SOPT_SS_HIDDEN_COLUMNS

SQL Server の SELECT FOR BROWSE ステートメントで非表示にされた列を結果セットに公開します。既定では、ドライバーはこのような列を公開しません。ValuePtr 値の型は SQLLEN です。

ValuePtr 値

説明

SQL_HC_OFF

既定値。FOR BROWSE 列が結果セットで非表示になります。

SQL_HC_ON

FOR BROWSE 列を公開します。

SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

クエリ通知要求のメッセージ テキストを返します。

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

クエリ通知要求で使用するオプションを指定します。オプションは、次に示すように、name=value 構文を使用した文字列で指定します。アプリケーションがサービスを作成して、キューから通知を読み取る必要があります。

クエリ通知オプションの構文を次に示します。

service=<service-name>[;(local database=<database>|broker instance=<broker instance>)]

次に例を示します。

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

クエリ通知をアクティブのままにしておく秒数を指定します。既定値は 432,000 秒 (5 日) です。ValuePtr 値の型は SQLLEN です。

SQL_SOPT_SS_PARAM_FOCUS

SQL_SOPT_SS_PARAM_FOCUS 属性は、後続の SQLBindParameter、SQLGetDescField、SQLSetDescField、SQLGetDescRec、および SQLSetDescRec の各呼び出しのフォーカスを指定します。

SQL_SOPT_SS_PARAM_FOCUS の型は SQLULEN です。

既定値は 0 で、SQL ステートメントのパラメーター マーカーに対応するパラメーターが、上記の呼び出しで指定されます。テーブル値パラメーターのパラメーター番号に設定すると、そのテーブル値パラメーターの列が上記の呼び出しで指定されます。テーブル値パラメーターのパラメーター番号以外の値に設定すると、エラー IM020 ("パラメーターのフォーカスがテーブル値パラメーターを参照していません") が返されます。

SQL_SOPT_SS_NAME_SCOPE

SQL_SOPT_SS_NAME_SCOPE 属性は、後続のカタログ関数呼び出しの名前スコープを指定します。SQLColumns から返される結果セットは、SQL_SOPT_SS_NAME_SCOPE の設定によって異なります。

SQL_SOPT_SS_NAME_SCOPE の型は SQLULEN です。

ValuePtr 値

説明

SQL_SS_NAME_SCOPE_TABLE

既定値。

テーブル値パラメーターを使用する場合は、実際のテーブルのメタデータが返される必要があることを示します。

スパース列機能を使用する場合は、スパース column_set のメンバーでない列のみが返されます。

SQL_SS_NAME_SCOPE_TABLE_TYPE

アプリケーションが実際のテーブルではなくテーブル型のメタデータを必要としていること (テーブル型のメタデータが返される必要があること) を示します。次に、アプリケーションは、TableName パラメーターとして、テーブル値パラメーターの TYPE_NAME を渡します。

SQL_SS_NAME_SCOPE_EXTENDED

スパース列機能を使用する場合は、column_set のメンバーシップに関係なくすべての列が返されます。

SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET

スパース列機能を使用する場合は、スパース column_set のメンバーである列のみが返されます。

SQL_SS_NAME_SCOPE_DEFAULT

SQL_SS_NAME_SCOPE_TABLE と同等です。

テーブル値パラメーターのカタログとスキーマを識別するために、SS_TYPE_CATALOG_NAME と SS_TYPE_SCHEMA_NAME をそれぞれ、CatalogName パラメーターと SchemaName パラメーターで使用します。テーブル値パラメーターのメタデータの取得が完了すると、アプリケーションによって、SQL_SOPT_SS_NAME_SCOPE は既定値 SQL_SS_NAME_SCOPE_TABLE に設定し直す必要があります。

SQL_SOPT_SS_NAME_SCOPE が SQL_SS_NAME_SCOPE_TABLE に設定されると、リンク サーバーへのクエリは失敗します。サーバー コンポーネントが格納されているカタログを使用して SQLColumns または SQLPrimaryKeys を呼び出すと、失敗します。

SQL_SOPT_SS_NAME_SCOPE を無効な値に設定しようとすると、SQL_ERROR が返され、"属性の値が正しくありません" というメッセージを含む SQLSTATE HY024 の診断レコードが生成されます。

SQL_SOPT_SS_NAME_SCOPE が SQL_SS_NAME_SCOPE_TABLE 以外の値になっているときに、SQLTables、SQLColumns、または SQLPrimaryKeys 以外のカタログ関数が呼び出されると、SQL_ERROR が返され、"関数のシーケンス エラーです (SQL_SOPT_SS_NAME_SCOPE が SQL_SS_NAME_SCOPE_TABLE に設定されていません)" というメッセージを含む SQLSTATE HY010 の診断レコードが生成されます。

関連項目

概念

ODBC API 実装の詳細

その他の技術情報

SQLGetStmtAttr 関数