共用方式為


SQLSetStmtAttr

適用於:SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse Analytics Analytics Platform System (PDW)

SQL Server Native Client ODBC 驅動程式不支援混合式 (keyset/dynamic) 數據指標模型。 如果設定的值不等於0,嘗試使用 SQL_ATTR_KEYSET_SIZE設定索引鍵集大小將會失敗。

應用程式會在所有語句上設定SQL_ATTR_ROW_ARRAY_SIZE,以宣告在 SQLFetchSQLFetchScroll 函數呼叫上傳回的數據列數目。 在指出伺服器數據指標的語句上,驅動程式會使用SQL_ATTR_ROW_ARRAY_SIZE來判斷伺服器產生的數據列區塊大小,以滿足數據指標的擷取要求。 在動態數據指標的區塊大小內,如果交易隔離等級足以確保認可交易的可重複讀取,則會修正數據列成員資格和順序。 數據指標在此值所指示的區塊外部完全動態。 伺服器數據指標區塊大小是完全動態的,而且可以在擷取處理的任何時間點變更。

SQLSetStmtAttr 和數據表值參數

SQLSetStmtAttr 可用來在應用程式參數描述元 (APD) 中設定SQL_SOPT_SS_PARAM_FOCUS,再存取數據表值參數數據行的描述項字段。

如果嘗試將SQL_SOPT_SS_PARAM_FOCUS設定為不是數據表值參數的參數序數,SQLSetStmtAttr 會傳回SQL_ERROR,並使用 SQLSTATE = HY024 建立診斷記錄,以及訊息「屬性值無效」。 傳回SQL_ERROR時,SQL_SOPT_SS_PARAM_FOCUS不會變更。

將SQL_SOPT_SS_PARAM_FOCUS設定為 0 可還原參數描述項記錄的存取權。

SQLSetStmtAttr 也可以用來設定SQL_SOPT_SS_NAME_SCOPE。 如需詳細資訊,請參閱本主題稍後的一節。

如需詳細資訊,請參閱 備妥語句的數據表值參數元數據。

如需資料表值參數的詳細資訊,請參閱 資料表值參數 (ODBC)

疏鬆數據行的 SQLSetStmtAttr 支援

SQLSetStmtAttr 可用來設定SQL_SOPT_SS_NAME_SCOPE。 如需詳細資訊,請參閱本主題稍後的一節。如需疏鬆資料行的詳細資訊,請參閱 疏鬆資料行支援 (ODBC)

陳述式屬性

SQL Server Native Client ODBC 驅動程式也支援下列驅動程式特定的語句屬性。

SQL_SOPT_SS_CURSOR_OPTIONS

SQL_SOPT_SS_CURSOR 屬性會指定驅動程式是否會在數據指標上使用驅動程式特定的效能選項。 設定這些選項時,不允許 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 在任何數據指標類型上啟用自動擷取選項。 為語句句柄設定此選項時,SQLExecuteSQLExecDirect 會產生隱含的 SQLFetchScrollSQL_FIRST)。 數據指標隨即開啟,而第一批數據列會在單一往返伺服器時傳回。
SQL_CO_FFO_AF 使用自動擷取選項啟用快速向前數據指標。 與指定SQL_CO_AF和SQL_CO_FFO相同。

設定這些選項時,伺服器會在偵測到已擷取最後一個數據列時自動關閉數據指標。 應用程式仍必須呼叫 SQLFreeStmt (SQL_CLOSE) 或 SQLCloseCursor,但驅動程式不需要將關閉通知傳送至伺服器。

勾選取清單包含 text、ntext 或 image 資料行,則快速轉寄資料指標會轉換成動態資料指標,並允許 SQLGetData。

SQL_SOPT_SS_DEFER_PREPARE

SQL_SOPT_SS_DEFER_PREPARE屬性會判斷語句是否已立即備妥或延遲,直到 執行 SQLExecuteSQLDescribeColSQLDescribeParam 為止。 在 SQL Server 7.0 和更早版本中,會忽略這個屬性(沒有延遲的準備)。 ValuePtr 值的類型為 SQLLEN。

ValuePtr 描述
SQL_DP_ON 預設。 呼叫 SQLPrepare 函式之後,語句準備會延後,直到 呼叫 SQLExecute 或中繼屬性作業(SQLDescribeColSQLDescribeParam) 執行為止。
SQL_DP_OFF 一旦 執行 SQLPrepare ,語句就會立即備妥。

SQL_SOPT_SS_REGIONALIZE

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

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_MSGTEXT屬性會傳回查詢通知要求的訊息正文。

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

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

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 使用疏鬆數據行功能時,不論column_set成員資格為何,SQLColumns 都會傳回所有數據行。
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。 SQLSTATE HY010 會產生診斷記錄,並顯示「函式順序錯誤(SQL_SOPT_SS_NAME_SCOPE未設定為 SQL_SS_NAME_SCOPE_TABLE)」訊息。

另請參閱

SQLGetStmtAttr 函式
ODBC API 實作詳細數據