SQLSetStmtAttr
適用対象: 
SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)
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 とメッセージ "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」のセクションを参照してください。
詳細については、「準備されたステートメントのテーブル値パラメーター メタデータを参照してください。
テーブル値パラメーターの詳細については、「 Table-Valued Parameters (ODBC)」を参照してください。
SQLSetStmtAttr によるスパース列のサポート
SQLSetStmtAttr を使用して、SQL_SOPT_SS_NAME_SCOPEを設定できます。 詳細については、このトピックで後述する「SQL_SOPT_SS_NAME_SCOPE」セクションを参照してください。スパース列の詳細については、「 Sparse Columns Support (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 を呼び出す必要がありますが、ドライバーは閉じる通知をサーバーに送信する必要はありません。
選択リストに text、 ntext、または image 列が含まれている場合、高速順方向専用カーソルは動的カーソルに変換され、 SQLGetData が許可されます。
SQL_SOPT_SS_DEFER_PREPARE
SQL_SOPT_SS_DEFER_PREPARE属性は、ステートメントをすぐに準備するか、
| 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属性は、 text または image データを含む列に対する操作のログ記録を切り替えます。 ValuePtr 値は SQLLEN 型です。
| ValuePtr 値 | 説明 |
|---|---|
| SQL_TL_OFF | text および image データに対して実行される操作のログ記録を無効にします。 |
| SQL_TL_ON | 既定。 textおよびimageデータに対して実行された操作のログ記録を有効にします。 |
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 の診断レコードが生成されます。
カタログ関数が他の場合、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 の診断レコードが生成されます。