SQLSetStmtAttr

  • [アーティクル]

適用対象:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

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

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

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

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

テーブル値パラメーターではないパラメーターの序数にSQL_SOPT_SS_PARAM_FOCUSを設定しようとすると、SQLSetStmtAttr はSQL_ERRORを返し、SQLSTATE = HY024 とメッセージ "Invalid attribute value" を使用して診断レコードが作成されます。 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 です。 ValuePtr 値の型は SQLLEN です。

ValuePtr 値 説明
SQL_CO_OFF 既定値。 高速順方向専用の読み取り専用カーソルと自動フェッチを無効にし、前方専用の読み取り専用カーソルで 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 を呼び出す必要がありますが、ドライバーは閉じる通知をサーバーに送信する必要はありません。

選択リストに テキスト、 ntext、または イメージ 列が含まれている場合、高速順方向専用カーソルは動的カーソルに変換され、 SQLGetData が許可されます。

SQL_SOPT_SS_DEFER_PREPARE

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

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

Note

ステートメント オプション SQL_SOPT_SS_REGIONALIZE が有効な場合、ドライバーは現在のユーザーのロケール レジストリ設定を使用します。 アプリケーションで SetThreadLocale を呼び出すなどによって設定された場合、ドライバーは現在のスレッドのロケールを受け入れません。

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

SQL_SOPT_SS_TEXTPTR_LOGGING

SQL_SOPT_SS_TEXTPTR_LOGGING属性は、 テキスト または 画像 データを含む列に対する操作のログ記録を切り替えます。 ValuePtr 値の型は SQLLEN です。

ValuePtr 値 説明
SQL_TL_OFF テキストデータと画像データに対して実行される操作のログ記録を無効にします。
SQL_TL_ON 既定値。 テキストデータと画像データに対して実行される操作のログ記録を有効にします。

SQL_SOPT_SS_HIDDEN_COLUMNS

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

クエリ通知をアクティブのままにしておく秒数を指定します。 既定値は 432000 秒 (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 既定値。

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

スパース列機能を使用すると、SQLColumns はスパース column_setのメンバーではない列のみを返します。
SQL_SS_NAME_SCOPE_TABLE_TYPE アプリケーションが実際のテーブルではなくテーブル型のメタデータを必要としていること (テーブル型のメタデータが返される必要があること) を示します。 次に、アプリケーションはテーブル値パラメーターのTYPE_NAMEを TableName パラメーターとして渡します。
SQL_SS_NAME_SCOPE_EXTENDED スパース列機能を使用すると、SQLColumns はメンバーシップに関係なく、すべての列 column_set 返します。
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET スパース列機能を使用すると、SQLColumns はスパース 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 の診断レコードが生成されます。

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

参照

SQLGetStmtAttr 関数
ODBC API 実装の詳細