SQLSetStmtAttrSQLSetStmtAttr

適用対象: yesSQL Server yesAzure SQL Database yesAzure Synapse Analytics (SQL DW) yesParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database yesAzure Synapse Analytics (SQL DW) yesParallel Data Warehouse

SQL ServerSQL Server Native Client ODBC ドライバーは、混合 (キーセット/動的) カーソル モデルをサポートしません。The SQL ServerSQL Server Native Client ODBC driver does not support the mixed (keyset/dynamic) cursor model. SQL_ATTR_KEYSET_SIZE を使用してキーセットのサイズを設定する場合、0 以外の値を設定すると失敗します。Attempts to set the keyset size using SQL_ATTR_KEYSET_SIZE will fail if the value set is not equal to 0.

このアプリケーションでは、 sqlfetchまたはsqlfetchscroll関数呼び出しで返される行の数を宣言するために、すべてのステートメントに SQL_ATTR_ROW_ARRAY_SIZE を設定します。The application sets SQL_ATTR_ROW_ARRAY_SIZE on all statements to declare the number of rows returned on a SQLFetch or SQLFetchScroll function call. ドライバーは、サーバー カーソルを指定するステートメントで SQL_ATTR_ROW_ARRAY_SIZE を使用して、カーソルからのフェッチ要求を満たすためにサーバーが生成する行ブロックのサイズを判断します。On statements indicating a server cursor, the driver uses SQL_ATTR_ROW_ARRAY_SIZE to determine the size of the block of rows the server generates to satisfy a fetch request from the cursor. トランザクションの分離レベルが、コミット済みのトランザクションの反復可能読み取りを保証できるレベルの場合、行のメンバーシップや順序が、動的カーソルのブロック サイズに収まる範囲内で固定されます。Within the block size of a dynamic cursor, row membership and ordering are fixed if the transaction isolation level is sufficient to ensure repeatable reads of committed transactions. カーソルは、この値で示されるブロック外では完全に動的になります。The cursor is completely dynamic outside of the block indicated by this value. サーバー カーソルのブロック サイズは完全に動的で、フェッチ処理のどの時点でも変更可能です。Server cursor block size is completely dynamic and can be changed at any point in fetch processing.

SQLSetStmtAttr とテーブル値パラメーターSQLSetStmtAttr and Table-Valued Parameters

SQLSetStmtAttr を使用すると、テーブル値パラメーターの列の記述子フィールドにアクセスする前に、アプリケーションパラメーター記述子 (APD) で SQL_SOPT_SS_PARAM_FOCUS を設定できます。SQLSetStmtAttr can be used to set SQL_SOPT_SS_PARAM_FOCUS in the application parameter descriptor (APD) before accessing descriptor fields for table-valued parameter columns.

SQL_SOPT_SS_PARAM_FOCUS をテーブル値パラメーターではないパラメーターの序数に設定しようとした場合、SQLSetStmtAttr は SQL_ERROR を返し、"属性値が無効です" というメッセージで SQLSTATE = HY024 の診断レコードが作成されます。If an attempt is made to set SQL_SOPT_SS_PARAM_FOCUS to the ordinal of a parameter that is not a table-valued parameter, SQLSetStmtAttr returns SQL_ERROR and a diagnostic record is created with SQLSTATE = HY024 and the message "Invalid attribute value". SQL_SOPT_SS_PARAM_FOCUS は、SQL_ERROR が返されたときに変更されません。SQL_SOPT_SS_PARAM_FOCUS is not changed when SQL_ERROR is returned.

SQL_SOPT_SS_PARAM_FOCUS に 0 を設定すると、パラメーターの記述子レコードへのアクセスが復元されます。Setting SQL_SOPT_SS_PARAM_FOCUS to 0 restores access to descriptor records for parameters.

SQLSetStmtAttr を使用して SQL_SOPT_SS_NAME_SCOPE を設定することもできます。SQLSetStmtAttr can also be used to set SQL_SOPT_SS_NAME_SCOPE. 詳細については、このトピックの後半の「SQL_SOPT_SS_NAME_SCOPE」のセクションを参照してください。For more information, see the SQL_SOPT_SS_NAME_SCOPE section, later in this topic.

詳細については、「準備されたステートメントのテーブル値パラメーターのメタデータ」を参照してください。For more information, see Table-Valued Parameter Metadata for Prepared Statements.

テーブル値パラメーターの詳細については、「テーブル値パラメーター (の)ODBC」を参照してください。For more information about table-valued parameters, see Table-Valued Parameters (ODBC).

SQLSetStmtAttr によるスパース列のサポートSQLSetStmtAttr Support for Sparse Columns

SQLSetStmtAttr を使用して SQL_SOPT_SS_NAME_SCOPE を設定できます。SQLSetStmtAttr can be used to set SQL_SOPT_SS_NAME_SCOPE. 詳細については、このトピックの「SQL_SOPT_SS_NAME_SCOPE」を参照してください。スパース列の詳細については、「スパース(列)のサポート ODBC」を参照してください。For more information, see the SQL_SOPT_SS_NAME_SCOPE section, later in this topic.For more information about sparse columns, see Sparse Columns Support (ODBC).

ステートメント属性Statement Attributes

SQL ServerSQL Server Native Client ODBC ドライバーは、次のドライバー固有のステートメント属性もサポートします。The SQL ServerSQL Server Native Client ODBC driver also supports the following driver-specific statement attributes.

SQL_SOPT_SS_CURSOR_OPTIONSSQL_SOPT_SS_CURSOR_OPTIONS

カーソルでのドライバー固有のパフォーマンス オプションを使用するかどうかを指定します。The SQL_SOPT_SS_CURSOR attribute specifies whether the driver will use driver-specific performance options on cursors. これらのオプションが設定されている場合、 SQLGetDataは許可されません。SQLGetData is not allowed when these options are set. 既定の設定は SQL_CO_OFF です。The default setting is SQL_CO_OFF. Valueptr値の型は SQLLEN です。The ValuePtr value is of type SQLLEN.

ValueptrValuePtr value [説明]Description
SQL_CO_OFFSQL_CO_OFF 既定値です。Default. 高速順方向専用、読み取り専用のカーソル、および autofetch を無効にして、前方参照専用の読み取り専用カーソルに対してSQLGetDataを有効にします。Disables fast forward-only, read-only cursors and autofetch, enables SQLGetData on forward-only, read-only cursors. SQL_SOPT_SS_CURSOR_OPTIONS を SQL_CO_OFF に設定すると、カーソルの種類は変更されません。When SQL_SOPT_SS_CURSOR_OPTIONS is set to SQL_CO_OFF, the cursor type will not change. つまり、高速順方向専用カーソルは高速順方向専用カーソルのままです。That is, fast forward-only cursor will remain a fast forward-only cursor. カーソルの種類を変更するには、 SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE を使用して、アプリケーションで別の種類のカーソルを設定する必要があります。To change the cursor type, the application must now set a different cursor type using SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE.
SQL_CO_FFOSQL_CO_FFO 高速順方向専用の読み取り専用カーソルを有効にし、順方向専用、読み取り専用のカーソルでのSQLGetDataを無効にします。Enables fast forward-only, read-only cursors, disables SQLGetData on forward-only, read-only cursors.
SQL_CO_AFSQL_CO_AF すべてのカーソルの種類で autofetch オプションを有効にします。Enables the autofetch option on any cursor type. このオプションがステートメントハンドルに対して設定されている場合、 SqlexecuteまたはSQLExecDirectは暗黙的なsqlfetchscroll (SQL_FIRST) を生成します。When this option is set for a statement handle, SQLExecute or SQLExecDirect will generate an implicit SQLFetchScroll (SQL_FIRST). カーソルが開かれ、最初の行バッチが 1 回のラウンドトリップでサーバーに返されます。The cursor is opened and the first batch of rows is returned in a single roundtrip to the server.
SQL_CO_FFO_AFSQL_CO_FFO_AF autofetch オプションを設定して高速順方向専用カーソルを有効にします。Enables fast forward-only cursors with the autofetch option. これは、SQL_CO_AF と SQL_CO_FFO の両方を指定した場合と同じです。It is the same as if both SQL_CO_AF and SQL_CO_FFO are specified.

これらのオプションを設定すると、サーバーは最後の行がフェッチされたことを検出した時点で、カーソルを自動的に閉じます。When these options are set, the server closes the cursor automatically when it detects that the last row has been fetched. アプリケーションは依然としてSQLFreeStmt (SQL_CLOSE) またはsqlcloを呼び出す必要がありますが、ドライバーは、サーバーに終了通知を送信する必要はありません。The application must still call SQLFreeStmt (SQL_CLOSE) or SQLCloseCursor, but the driver does not have to send the close notification to the server.

Select リストにtextntext、またはimage列が含まれている場合、高速順方向専用カーソルは動的カーソルに変換され、 SQLGetDataは許可されます。If the select list contains a text, ntext, or image column, the fast forward-only cursor is converted to a dynamic cursor and SQLGetData is allowed.

SQL_SOPT_SS_DEFER_PREPARESQL_SOPT_SS_DEFER_PREPARE

SQL_SOPT_SS_DEFER_PREPARE 属性は、ステートメントを直ちに準備するか、 SqlexecuteSQLDescribeCol 、またはSQLDescribeParamが実行されるまで遅延させるかを決定します。The SQL_SOPT_SS_DEFER_PREPARE attribute determines whether the statement is prepared immediately or deferred until SQLExecute, SQLDescribeCol or SQLDescribeParam is executed. SQL ServerSQL Server 7.0 以前のバージョンでは、このプロパティは無視されます (準備は遅延されません)。In SQL ServerSQL Server 7.0 and earlier, this property is ignored (no deferred prepare). Valueptr値の型は SQLLEN です。The ValuePtr value is of type SQLLEN.

ValueptrValuePtr value [説明]Description
SQL_DP_ONSQL_DP_ON 既定値です。Default. SQLPrepare 関数を呼び出した後、 sqlexecuteが呼び出されるか、メタプロパティ操作 (SQLDescribeColまたはSQLDescribeParam) が実行されるまで、ステートメントの準備は遅延されます。After calling SQLPrepare Function, the statement preparation is deferred until SQLExecute is called or metaproperty operation (SQLDescribeCol or SQLDescribeParam) is executed.
SQL_DP_OFFSQL_DP_OFF SQLPrepareが実行されるとすぐに、ステートメントが準備されます。The statement is prepared as soon as SQLPrepare is executed.

SQL_SOPT_SS_REGIONALIZESQL_SOPT_SS_REGIONALIZE

ステートメント レベルのデータ変換を決定します。The SQL_SOPT_SS_REGIONALIZE attribute is used to determine data conversion at the statement level. この属性を設定すると、日付、時刻、通貨の値を文字列値に変換する際に、ドライバーはクライアントのロケール設定を使用します。The attribute causes the driver to respect the client locale setting when converting date, time, and currency values to character strings. この場合の変換は、SQL ServerSQL Server ネイティブ データ型から文字列への変換のみです。The conversion is from SQL ServerSQL Server native data types to character strings only.

Valueptr値の型は SQLLEN です。The ValuePtr value is of type SQLLEN.

ValueptrValuePtr value [説明]Description
SQL_RE_OFFSQL_RE_OFF 既定値です。Default. ドライバーは、日付、時刻、通貨の値を文字列データに変換する際に、クライアントのロケール設定を使用しません。The driver does not convert date, time, and currency data to character string data using the client locale setting.
SQL_RE_ONSQL_RE_ON ドライバーは、日付、時刻、通貨の値を文字列データに変換する際に、クライアントのロケール設定を使用します。The driver uses the client locale setting when converting date, time, and currency data to character string data.

地域別の変換の設定は、通貨、数値、日付、および時刻のデータ型に適用されます。Regional conversion settings apply to currency, numeric, date, and time data types. 変換の設定は、通貨、数値、日付、または時刻の値を文字列に変換するときの出力変換にのみ適用されます。The conversion setting is only applicable to output conversions when currency, numeric, date, or time values are converted to character strings.

注意

ステートメント オプション SQL_SOPT_SS_REGIONALIZE が有効な場合、ドライバーは現在のユーザーのロケール レジストリ設定を使用します。When the statement option SQL_SOPT_SS_REGIONALIZE is on, the driver uses the locale registry settings for the current user. アプリケーションがSetthreadlocaleを呼び出すなどして、現在のスレッドのロケールを設定している場合、ドライバーはそのロケールを優先しません。The driver does not honor the current thread's locale if the application sets it by, for example, calling SetThreadLocale.

データ ソースの地域別の動作を変更すると、アプリケーション エラーが発生することがあります。Altering the regional behavior of a data source can cause application failure. 日付文字列を解析し、ODBC の定義に従った形式の日付文字列を受け付けるアプリケーションは、地域別の動作の値を変更することによって、悪影響を受ける可能性があります。An application that parses date strings and expects date strings to appear as defined by ODBC, could be adversely affected by altering this value.

SQL_SOPT_SS_TEXTPTR_LOGGINGSQL_SOPT_SS_TEXTPTR_LOGGING

SQL_SOPT_SS_TEXTPTR_LOGGING 属性は、テキストまたはイメージデータを含む列に対する操作のログ記録を切り替えます。The SQL_SOPT_SS_TEXTPTR_LOGGING attribute toggles logging of operations on columns containing text or image data. Valueptr値の型は SQLLEN です。The ValuePtr value is of type SQLLEN.

ValueptrValuePtr value [説明]Description
SQL_TL_OFFSQL_TL_OFF テキストおよびイメージデータに対して実行される操作のログ記録を無効にします。Disables logging of operations performed on text and image data.
SQL_TL_ONSQL_TL_ON 既定値です。Default. テキストおよびイメージデータに対して実行される操作のログ記録を有効にします。Enables logging of operations performed on text and image data.

SQL_SOPT_SS_HIDDEN_COLUMNSSQL_SOPT_SS_HIDDEN_COLUMNS

SQL ServerSQL Server の SELECT FOR BROWSE ステートメントで非表示にされた列を結果セットに公開します。The SQL_SOPT_SS_HIDDEN_COLUMNS attribute exposes, in the result set, columns hidden in a SQL ServerSQL Server SELECT FOR BROWSE statement. 既定では、ドライバーはこのような列を公開しません。The driver does not expose these columns by default. Valueptr値の型は SQLLEN です。The ValuePtr value is of type SQLLEN.

ValueptrValuePtr value [説明]Description
SQL_HC_OFFSQL_HC_OFF 既定値です。Default. FOR BROWSE 列が結果セットで非表示になります。FOR BROWSE columns are hidden from the result set.
SQL_HC_ONSQL_HC_ON FOR BROWSE 列を公開します。Exposes FOR BROWSE columns.

SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXTSQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

クエリ通知要求のメッセージ テキストを返します。The SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT attribute returns the message text for the query notification request.

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONSSQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

クエリ通知要求で使用するオプションを指定します。The SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS attribute specifies the options used for the query notification request. オプションは、次に示すように、name=value 構文を使用した文字列で指定します。These are specified in a string with name=value syntax as specified below. アプリケーションがサービスを作成して、キューから通知を読み取る必要があります。The application is responsible for creating the service and reading notifications off of the queue.

クエリ通知オプションの構文を次に示します。The syntax of the query notifications options string is:

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

例 :For example:

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUTSQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

クエリ通知をアクティブのままにしておく秒数を指定します。The SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT attribute specifies the number of seconds that the query notification is to remain active. 既定値は432000秒 (5 日) です。The default value is 432000 seconds (5 days). Valueptr値の型は SQLLEN です。The ValuePtr value is of type SQLLEN.

SQL_SOPT_SS_PARAM_FOCUSSQL_SOPT_SS_PARAM_FOCUS

SQL_SOPT_SS_PARAM_FOCUS 属性は、後続の SQLBindParameter、SQLGetDescField、SQLSetDescField、SQLGetDescRec、および SQLSetDescRec の呼び出しのフォーカスを指定します。The SQL_SOPT_SS_PARAM_FOCUS attribute specifies the focus for subsequent SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec, and SQLSetDescRec calls.

SQL_SOPT_SS_PARAM_FOCUS の型は SQLULEN です。The type for SQL_SOPT_SS_PARAM_FOCUS is SQLULEN.

既定値は 0 で、SQL ステートメントのパラメーター マーカーに対応するパラメーターが、上記の呼び出しで指定されます。The default is 0, which means that these calls address parameters that correspond to parameter markers in the SQL statement. テーブル値パラメーターのパラメーター番号に設定すると、そのテーブル値パラメーターの列が上記の呼び出しで指定されます。When set to the parameter number of a table-valued parameter, these calls address columns of that table-valued parameter. テーブル値パラメーターのパラメーター番号以外の値に設定すると、エラー IM020 ("パラメーターのフォーカスがテーブル値パラメーターを参照していません") が返されます。When set to a value that is not the parameter number of a table-valued parameter, these calls return the error IM020: "Parameter focus does not refer to a table-valued parameter".

SQL_SOPT_SS_NAME_SCOPESQL_SOPT_SS_NAME_SCOPE

SQL_SOPT_SS_NAME_SCOPE 属性は、後続のカタログ関数呼び出しの名前スコープを指定します。The SQL_SOPT_SS_NAME_SCOPE attribute specifies the name scope for subsequent catalog function calls. SQLColumns によって返される結果セットは、SQL_SOPT_SS_NAME_SCOPE の設定によって異なります。The result set returned by SQLColumns depends on the setting of SQL_SOPT_SS_NAME_SCOPE.

SQL_SOPT_SS_NAME_SCOPE の型は SQLULEN です。The type for SQL_SOPT_SS_NAME_SCOPE is SQLULEN.

ValueptrValuePtr value [説明]Description
SQL_SS_NAME_SCOPE_TABLESQL_SS_NAME_SCOPE_TABLE 既定値です。Default.

テーブル値パラメーターを使用する場合は、実際のテーブルのメタデータが返される必要があることを示します。When using table-valued parameters, indicates that metadata for actual tables should be returned.

スパース列機能を使用する場合、SQLColumns は、スパースcolumn_setのメンバーではない列のみを返します。When using the sparse columns feature, SQLColumns will return only columns that are not members of the sparse column_set.
SQL_SS_NAME_SCOPE_TABLE_TYPESQL_SS_NAME_SCOPE_TABLE_TYPE アプリケーションが実際のテーブルではなくテーブル型のメタデータを必要としていること (テーブル型のメタデータが返される必要があること) を示します。Indicates that the application requires metadata for a table type, rather than an actual table (catalog functions should return metadata for table types). その後、アプリケーションはテーブル値パラメーターの TYPE_NAME をTableNameパラメーターとして渡します。The application then passes the TYPE_NAME of the table-valued parameter as the TableName parameter.
SQL_SS_NAME_SCOPE_EXTENDEDSQL_SS_NAME_SCOPE_EXTENDED スパース列機能を使用する場合、 column_setのメンバーシップに関係なく、sqlcolumns はすべての列を返します。When using the sparse columns feature, SQLColumns returns all columns, regardless of column_set membership.
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SETSQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET スパース列機能を使用する場合、SQLColumns は、スパースcolumn_setのメンバーである列のみを返します。When using the sparse columns feature, SQLColumns returns only columns that are members of the sparse column_set.
SQL_SS_NAME_SCOPE_DEFAULTSQL_SS_NAME_SCOPE_DEFAULT SQL_SS_NAME_SCOPE_TABLE と同等です。Equal to SQL_SS_NAME_SCOPE_TABLE.

SS_TYPE_CATALOG_NAME と SS_TYPE_SCHEMA_NAME は、 CatalogNameパラメーターとSchemaNameパラメーターでそれぞれ使用され、テーブル値パラメーターのカタログとスキーマを識別します。SS_TYPE_CATALOG_NAME and SS_TYPE_SCHEMA_NAME are used with the CatalogName and SchemaName parameters, respectively, to identify the catalog and schema for the table-valued parameter. テーブル値パラメーターのメタデータの取得が完了すると、アプリケーションによって、SQL_SOPT_SS_NAME_SCOPE は既定値 SQL_SS_NAME_SCOPE_TABLE に設定し直す必要があります。When an application has finished retrieving metadata for table-valued parameters, it must set SQL_SOPT_SS_NAME_SCOPE back to its default value of SQL_SS_NAME_SCOPE_TABLE.

SQL_SOPT_SS_NAME_SCOPE が SQL_SS_NAME_SCOPE_TABLE に設定されると、リンク サーバーへのクエリは失敗します。When SQL_SOPT_SS_NAME_SCOPE is set to SQL_SS_NAME_SCOPE_TABLE, queries to linked servers fail. サーバーコンポーネントを含むカタログを使用した SQLColumns または Sqlprimarykey の呼び出しは失敗します。Calls to SQLColumns or SQLPrimaryKeys with a catalog that contains a server component will fail.

SQL_SOPT_SS_NAME_SCOPE を無効な値に設定しようとすると、SQL_ERROR が返され、"属性の値が正しくありません" というメッセージを含む SQLSTATE HY024 の診断レコードが生成されます。If you attempt to set SQL_SOPT_SS_NAME_SCOPE to an invalid value, SQL_ERROR is returned and a diagnostic record is generated with SQLSTATE HY024 and the message "Invalid attribute value".

SQL_SOPT_SS_NAME_SCOPE に SQL_SS_NAME_SCOPE_TABLE 以外の値が指定されている場合に、SQLTables、Sqltables、SQLPrimaryKeys などのカタログ関数が呼び出されると、SQL_ERROR が返されます。If a catalog function other then SQLTables, SQLColumns, or SQLPrimaryKeys is called when SQL_SOPT_SS_NAME_SCOPE has a value other than SQL_SS_NAME_SCOPE_TABLE, SQL_ERROR is returned. "関数のシーケンス エラーです (SQL_SOPT_SS_NAME_SCOPE が SQL_SS_NAME_SCOPE_TABLE に設定されていません)" というメッセージを含む SQLSTATE HY010 の診断レコードが生成されます。A diagnostic record is generated with SQLSTATE HY010 and the message "Function sequence error (SQL_SOPT_SS_NAME_SCOPE is not set to SQL_SS_NAME_SCOPE_TABLE)".

参照See Also

SQLGetStmtAttr 関数 SQLGetStmtAttr Function
ODBC API 実装の詳細ODBC API Implementation Details