SQLSetStmtAttr 函式

  • 發行項

一致性
引進版本：ODBC 3.0 標準合規性：ISO 92

摘要
SQLSetStmtAttr 會設定與 語句相關的屬性。

注意

如需當 ODBC 3.x 應用程式使用 ODBC 2.x 驅動程式時，Driver Manager 將此函式對應至哪些內容的詳細資訊，請參閱 對應應用程式 回溯相容性的取代函式。

語法

  
SQLRETURN SQLSetStmtAttr(  
     SQLHSTMT      StatementHandle,  
     SQLINTEGER    Attribute,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    StringLength);

引數

StatementHandle
[輸入]語句控制碼。

屬性
[輸入]設定的選項，列在 「批註」中。

ValuePtr
[輸入]要與 Attribute 建立關聯的值。 根據 Attribute 的值 ， ValuePtr 會是下列其中一項：

  • ODBC 描述元控制碼。

  • SQLUINTEGER 值。

  • SQLULEN 值。

  • 下列其中一項的指標：

    • 以 Null 結束的字元字串。

    • 二進位緩衝區。

    • SQLLEN、SQLULEN 或 SQLUSMALLINT 類型的值或陣列。

    • 驅動程式定義的值。

如果 Attribute 引數是驅動程式特定的值， ValuePtr 可能是帶正負號的整數。

StringLength
[輸入]如果 Attribute 是 ODBC 定義的屬性，而 ValuePtr 指向字元字串或二進位緩衝區，則這個引數應該是 * ValuePtr 的長度。 如果 Attribute 是 ODBC 定義的屬性，而 ValuePtr 是整數， 則會忽略 StringLength 。

如果 Attribute 是驅動程式定義的屬性，則應用程式會藉由設定 StringLength 引數，向驅動程式管理員指出屬性的性質。 StringLength 可以具有下列值：

  • 如果 ValuePtr 是字元字串的指標， 則 StringLength 是字串的長度或SQL_NTS。

  • 如果 ValuePtr 是二進位緩衝區的指標，則應用程式會將SQL_LEN_BINARY_ATTR（ length ） 宏的結果放在 StringLength 中 。 這會在 StringLength 中 放置負值。

  • 如果 ValuePtr 是字元字串或二進位字串以外的值指標， 則 StringLength 的值應該SQL_IS_POINTER。

  • 如果 ValuePtr 包含固定長度的值，則 StringLength 會視需要SQL_IS_INTEGER或SQL_IS_UINTEGER。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLSetStmtAttr 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可能會呼叫 具有 handleType 為 SQL_HANDLE_STMT 的 SQLGetDiagRec 和 StatementHandle 句 柄 來取得相關聯的 SQLSTATE 值。 下表列出 SQLSetStmtAttr 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S02 選項值已變更 驅動程式不支援 ValuePtr 中指定的 值，或 ValuePtr 中指定的 值因為實作工作條件而無效，因此驅動程式會取代類似的值。 （ 可以呼叫 SQLGetStmtAttr 來判斷暫時替代的值。替代值對 StatementHandle 有效，直到資料指標關閉為止，此時語句屬性會還原為其先前的值。 可以變更的語句屬性如下：

SQL_ ATTR_CONCURRENCY SQL_ ATTR_CURSOR_TYPE SQL_ ATTR_KEYSET_SIZE SQL_ ATTR_MAX_LENGTH SQL_ ATTR_MAX_ROWS SQL_ ATTR_QUERY_TIMEOUT SQL_ATTR_ROW_ARRAY_SIZE SQL_ ATTR_SIMULATE_CURSOR

（函式會傳回SQL_SUCCESS_WITH_INFO。）
08S01 通訊連結失敗 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
24000 不正確資料指標狀態 屬性 已SQL_ATTR_CONCURRENCY、SQL_ATTR_CURSOR_TYPE、SQL_ATTR_SIMULATE_CURSOR或SQL_ATTR_USE_BOOKMARKS，且資料指標已開啟。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY009 不正確 Null 指標使用 Attribute 引數識別出需要字串屬性的語句屬性，而 ValuePtr 引數是 Null 指標。
HY010 函式順序錯誤 （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLSetStmtAttr 函式時 ，這個非同步函式仍在執行中。

（DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。

（DM） 呼叫 StatementHandle 的非同步執行函式，並在呼叫此函式時仍在執行。

（DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos ，並傳回SQL_NEED_DATA。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。
HY011 無法立即設定屬性 Attribute 是SQL_ATTR_CONCURRENCY、SQL_ ATTR_CURSOR_TYPE、SQL_ ATTR_SIMULATE_CURSOR或SQL_ ATTR_USE_BOOKMARKS，而且已備妥語句。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY017 自動設定描述元控制碼的使用無效 （DM） Attribute 引數已SQL_ATTR_IMP_ROW_DESC或SQL_ATTR_IMP_PARAM_DESC。

（DM） Attribute 引數是SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC，ValuePtr 中的 值是隱含配置的描述元控制碼，而不是原本配置給 ARD 或 APD 的控制碼。
HY024 不正確屬性值 指定了指定的 屬性值 ，ValuePtr 中 指定了不正確值。 （Driver Manager 只會針對接受一組離散值的連接和語句屬性傳回此 SQLSTATE，例如SQL_ATTR_ACCESS_MODE或SQL_ ATTR_ASYNC_ENABLE。針對所有其他連接和語句屬性，驅動程式必須確認 ValuePtr 中指定的 值。

Attribute 引數SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC，而 ValuePtr 是明確配置的描述元控制碼，與 StatementHandle 引數不在相同的連接 上。
HY090 不正確字串或緩衝區長度 （DM） *ValuePtr 是字元字串，而 StringLength 引數小於 0， 但未SQL_NTS。
HY092 不正確屬性/選項識別碼 （DM） 為引數 Attribute 指定的值對驅動程式支援的 ODBC 版本無效。

（DM） 為引數 Attribute 指定的值是唯讀屬性。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
HYC00 未實作選擇性功能 為引數 Attribute 指定的值是驅動程式所支援之 ODBC 版本的有效 ODBC 語句屬性，但驅動程式不支援。

Attribute 引數已SQL_ATTR_ASYNC_ENABLE，且 呼叫具有 infoType SQL_ASYNC_MODE的 SQLGetInfo 會傳回SQL_AM_CONNECTION。

Attribute 引數已SQL_ATTR_ENABLE_AUTO_IPD，而連接屬性的值SQL_ATTR_AUTO_IPD SQL_FALSE。
HYT01 已超過連線逾時 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。
S1118 驅動程式不支援非同步通知 如果呼叫 SQLSetStmtAttr 來設定SQL_ATTR_ASYNC_STMT_EVENT;驅動程式不支援非同步通知。

註解

語句的語句屬性會維持有效狀態，直到由另一個 SQLSetStmtAttr 呼叫 變更，或直到呼叫 SQLFreeHandle 卸載語句為止。 使用 SQL_CLOSE、SQL_UNBIND 或 SQL_RESET_PARAMS 選項呼叫 SQLFreeStmt 並不會重設語句屬性。

如果資料來源不支援 ValuePtr 中指定的 值，某些語句屬性支援替代類似的值。 在這種情況下，驅動程式會傳回 SQL_SUCCESS_WITH_INFO 和 SQLSTATE 01S02 （選項值已變更）。 例如，如果 Attribute 是SQL_ATTR_CONCURRENCY且 ValuePtr 是SQL_CONCUR_ROWVER，而且資料來源不支援，則驅動程式會取代SQL_CONCUR_VALUES並傳回SQL_SUCCESS_WITH_INFO。 若要判斷替代的值，應用程式會呼叫 SQLGetStmtAttr 。

使用 ValuePtr 設定的資訊格式取決於指定的 屬性 。 SQLSetStmtAttr 接受兩種不同格式之一的屬性資訊：字元字串或整數值。 屬性的描述中會指出每個 格式。 此格式適用于 SQLGetStmtAttr 中 每個屬性傳回的資訊。 SQLSetStmtAttr 的 ValuePtr 引數所 指向的 字元字串長度為 StringLength 。

注意

已在 ODBC 3.x 中取代呼叫 SQLSetConnectAttr 而在連接層級設定陳述式屬性的能力。 ODBC 3.x 應用程式絕對不應該在連接層級設定陳述式屬性。 ODBC 3.x 語句屬性不能在連接層級設定，但SQL_ATTR_METADATA_ID和SQL_ATTR_ASYNC_ENABLE屬性除外，這些屬性都是連接屬性和語句屬性，而且可以在連接層級或語句層級設定。

注意

ODBC 3.x 驅動程式只有在應該使用連接層級設定 ODBC 2.x 語句選項的 ODBC 2.x 應用程式時，才需要支援此功能。 如需詳細資訊，請參閱附錄 G：回溯相容性的驅動程式指導方針中的 SQLSetConnectOption 對應 底下的 。

設定描述項欄位的語句屬性

許多語句屬性會對應至描述元的標頭欄位。 設定這些屬性實際上會導致描述元欄位的設定。 藉由呼叫 SQLSetStmtAttr 而不是 對 SQLSetDescField 設定欄位的優點是，不需要為函式呼叫取得描述項控制碼。

警告

針對一個語句呼叫 SQLSetStmtAttr 可能會影響其他語句。 當明確配置與 語句相關聯的 APD 或 ARD，也與其他語句相關聯時，就會發生這種情況。 因為 SQLSetStmtAttr 會修改 APD 或 ARD，因此修改會套用至與此描述元相關聯的所有語句。 如果這不是必要的行為，應用程式應該將這個描述元與其他語句解除關聯（藉由呼叫 SQLSetStmtAttr 將SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC欄位設定為不同的描述元控制碼），然後再再次呼叫 SQLSetStmtAttr 。

當描述項欄位設定為所設定之對應語句屬性的結果時，欄位只會針對目前與 StatementHandle 引數所識別 之語句相關聯的適用描述項進行設定，而且屬性設定不會影響未來可能與該語句相關聯的任何描述項。 當同時為語句屬性的描述元欄位是由 SQLSetDescField 的呼叫 所設定時，就會設定對應的語句屬性。 如果明確配置的描述元與語句分離，對應至標頭欄位的語句屬性會還原為隱含配置描述元中的域值。

配置語句時（請參閱 SQLAllocHandle ），會自動設定四個描述元控制碼，並與 語句相關聯。 明確配置的描述元控制碼可以藉由呼叫 SQLAllocHandle 搭配 SQL_HANDLE_DESC 的 fHandleType 來配置描述元控制碼，然後呼叫 SQLSetStmtAttr ，將描述元控制碼與語句產生關聯。

下表中的語句屬性會對應至描述項標頭欄位。

語句屬性 標頭欄位 Desc.
SQL_ATTR_PARAM_BIND_OFFSET_PTR SQL_DESC_BIND_OFFSET_PTR APD
SQL_ATTR_PARAM_BIND_TYPE SQL_DESC_BIND_TYPE APD
SQL_ATTR_PARAM_OPERATION_PTR SQL_DESC_ARRAY_STATUS_PTR APD
SQL_ATTR_PARAM_STATUS_PTR SQL_DESC_ARRAY_STATUS_PTR IPD
SQL_ATTR_PARAMS_PROCESSED_PTR SQL_DESC_ROWS_PROCESSED_PTR IPD
SQL_ATTR_PARAMSET_SIZE SQL_DESC_ARRAY_SIZE APD
SQL_ATTR_ROW_ARRAY_SIZE SQL_DESC_ARRAY_SIZE ARD
SQL_ATTR_ROW_BIND_OFFSET_PTR SQL_DESC_BIND_OFFSET_PTR ARD
SQL_ATTR_ROW_BIND_TYPE SQL_DESC_BIND_TYPE ARD
SQL_ATTR_ROW_OPERATION_PTR SQL_DESC_ARRAY_STATUS_PTR ARD
SQL_ATTR_ROW_STATUS_PTR SQL_DESC_ARRAY_STATUS_PTR IRD
SQL_ATTR_ROWS_FETCHED_PTR SQL_DESC_ROWS_PROCESSED_PTR IRD

陳述式屬性

下表顯示目前定義的屬性及其引進的 ODBC 版本：預期驅動程式會定義更多屬性，以利用不同的資料來源。 ODBC 會保留一系列屬性;驅動程式開發人員必須保留值，才能從 Open Group 使用自己的驅動程式特定用途。 如需詳細資訊，請參閱驅動程式特定的資料類型、描述項類型、資訊類型、診斷類型及屬性。

屬性 ValuePtr 內容
SQL_ATTR_APP_PARAM_DESC （ODBC 3.0） APID 的控制碼，供語句控制碼上後續呼叫 SQLExecute 和 SQLExecDirect 。 此屬性的初始值是一開始配置 語句時隱含配置的描述元。 如果這個屬性的值設定為SQL_Null_DESC或原本為描述項配置的控制碼，則先前與語句控制碼相關聯的明確配置的 APD 控制碼會與其解除關聯，而語句控制碼會還原為隱含配置的 APD 控制碼。

此屬性不能設定為隱含配置給另一個語句的描述元控制碼，或設定為在相同語句上隱含設定的另一個描述元控制碼;隱含配置的描述元控制碼不能與多個語句或描述元控制碼相關聯。
SQL_ATTR_APP_ROW_DESC （ODBC 3.0） ARD 的控制碼，用於語句控制碼上的後續擷取。 此屬性的初始值是一開始配置 語句時隱含配置的描述元。 如果這個屬性的值設定為SQL_Null_DESC或原本配置給描述元的控制碼，則先前與語句控制碼相關聯的明確配置的 ARD 控制碼會與其解除關聯，而語句控制碼會還原為隱含配置的 ARD 控制碼。

此屬性不能設定為隱含配置給另一個語句的描述元控制碼，或設定為在相同語句上隱含設定的另一個描述元控制碼;隱含配置的描述元控制碼不能與多個語句或描述元控制碼相關聯。
SQL_ATTR_ASYNC_ENABLE （ODBC 1.0） SQLULEN 值，指定是否以非同步方式執行以指定語句呼叫的函式：

SQL_ASYNC_ENABLE_OFF = 停用語句層級非同步執行支援 （預設值）。

SQL_ASYNC_ENABLE_ON = 啟用語句層級非同步執行支援。

如需詳細資訊，請參閱非同步地執行 (輪詢方法)。

對於具有語句層級非同步執行支援的驅動程式，語句屬性SQL_ATTR_ASYNC_ENABLE是唯讀的。 其值與配置語句控制碼時具有相同名稱的連接層級屬性值相同。

當 SQL_ASYNC_MODE InfoType 傳回SQL_AM_CONNECTION 傳回 SQLSTATE HYC00 時，呼叫 SQLSetStmtAttr 來設定SQL_ATTR_ASYNC_ENABLE（未實作選擇性功能）。 如需詳細資訊，請參閱 SQLSetConnectAttr 函式 以取得詳細資訊。
SQL_ATTR_ASYNC_STMT_EVENT （ODBC 3.8） SQLPOINTER 值，這是事件控制碼。

藉由呼叫 SQLSetStmtAttr 來設定 SQL_ATTR_ASYNC_STMT_EVENT 屬性並指定事件控制碼，即可啟用非同步函式完成的通知。
SQL_ATTR_ASYNC_STMT_PCALLBACK （ODBC 3.8） 非同步回呼函式的 SQLPOINTER。

只有驅動程式管理員可以使用這個屬性呼叫驅動程式的 SQLSetStmtAttr 函 式。
SQL_ATTR_ASYNC_STMT_PCONTEXT （ODBC 3.8） 內容結構的 SQLPOINTER

只有驅動程式管理員可以使用這個屬性呼叫驅動程式的 SQLSetStmtAttr 函 式。
SQL_ATTR_CONCURRENCY （ODBC 2.0） 指定資料指標並行的 SQLULEN 值：

SQL_CONCUR_READ_ONLY = 資料指標是唯讀的。 不允許任何更新。

SQL_CONCUR_LOCK = 資料指標會使用足以確保資料列可以更新的最低鎖定層級。

SQL_CONCUR_ROWVER = 資料指標使用開放式並行控制，比較 SQLBase ROWID 或 Sybase TIMESTAMP 等資料列版本。

SQL_CONCUR_VALUES = 資料指標使用開放式並行控制，比較值。

SQL_ATTR_CONCURRENCY的預設值為 SQL_CONCUR_READ_ONLY。

無法為開啟的資料指標指定這個屬性。 如需詳細資訊，請參閱 並行類型 。

如果 SQL_ATTR_CURSOR_TYPE Attribute 變更為不支援目前值SQL_ATTR_CONCURRENCY的類型，則會在執行時間變更SQL_ATTR_CONCURRENCY的值，並在呼叫 SQLExecDirect 或 SQLPrepare 時 發出警告。

如果驅動程式支援 SELECT FOR UPDATE 語句，而且當 SQL_ATTR_CONCURRENCY 的值設定為 SQL_CONCUR_READ_ONLY 時，就會執行這類語句，則會傳回錯誤。 如果SQL_ATTR_CONCURRENCY的值已變更為驅動程式支援某些值SQL_ATTR_CURSOR_TYPE，但不是目前SQL_ATTR_CURSOR_TYPE值的值，則會在執行時間變更SQL_ATTR_CURSOR_TYPE的值，而且呼叫 SQLExecDirect 或 SQLPrepare 時 ，會發出 SQLSTATE 01S02 （選項值變更）。

如果資料來源不支援指定的平行存取，驅動程式會替代不同的平行存取，並傳回 SQLSTATE 01S02 （選項值已變更）。 針對SQL_CONCUR_VALUES，驅動程式會取代 SQL_CONCUR_ROWVER，反之亦然。 針對SQL_CONCUR_LOCK，驅動程式會依序取代SQL_CONCUR_ROWVER或SQL_CONCUR_VALUES。 在執行時間之前，不會檢查替代值的有效性。

如需SQL_ATTR_CONCURRENCY與其他資料指標屬性之間關聯性的詳細資訊，請參閱 資料指標特性和資料指標類型 。
SQL_ATTR_CURSOR_SCROLLABLE （ODBC 3.0） SQLULEN 值，指定應用程式所需的支援層級。 設定此屬性會影響後續對 SQLExecDirect 和 SQLExecute 的 呼叫。

SQL_NONSCROLLABLE = 語句控制碼上不需要可捲動的資料指標。 如果應用程式在此控制碼上呼叫 SQLFetchScroll ，則 FetchOrientation 的唯一有效值 會SQL_FETCH_NEXT。 這是預設值。

SQL_SCROLLABLE = 語句控制碼上需要可捲動的資料指標。 呼叫 SQLFetchScroll 時，應用程式可以指定 FetchOrientation 的任何有效值 ，以循序模式以外的模式達到資料指標定位。

如需可捲動資料指標的詳細資訊，請參閱 可捲動的資料 指標。 如需SQL_ATTR_CURSOR_SCROLLABLE與其他資料指標屬性之間關聯性的詳細資訊，請參閱 資料指標特性和資料指標類型
SQL_ATTR_CURSOR_SENSITIVITY （ODBC 3.0） SQLULEN 值，指定語句控制碼上的資料指標是否顯示另一個資料指標對結果集所做的變更。 設定此屬性會影響後續對 SQLExecDirect 和 SQLExecute 的 呼叫。 應用程式可以讀取此屬性的值，以取得應用程式最近設定的初始狀態或狀態。

SQL_UNSPECIFIED = 未指定資料指標類型是什麼，以及語句控制碼上的資料指標是否顯示另一個資料指標對結果集所做的變更。 語句控制碼上的資料指標可能會讓可見的無、部分或所有這類變更。 這是預設值。

SQL_INSENSITIVE = 語句控制碼上的所有資料指標都會顯示結果集，而不會反映任何其他資料指標對它所做的任何變更。 不區分資料指標是唯讀的。 這會對應至靜態資料指標，其具有唯讀的平行存取。

SQL_SENSITIVE = 語句控制碼上的所有資料指標都會顯示由另一個資料指標對結果集所做的所有變更。

如需SQL_ATTR_CURSOR_SENSITIVITY與其他資料指標屬性之間關聯性的詳細資訊，請參閱 資料指標特性和資料指標類型 。
SQL_ATTR_CURSOR_TYPE （ODBC 2.0） 指定資料指標類型的 SQLULEN 值：

SQL_CURSOR_FORWARD_ONLY = 資料指標只會向前捲動。

SQL_CURSOR_STATIC = 結果集中的資料是靜態的。

SQL_CURSOR_KEYSET_DRIVEN = 驅動程式會儲存並使用索引鍵，以取得在 SQL_ATTR_KEYSET_SIZE 語句屬性中指定的資料列數目。

SQL_CURSOR_DYNAMIC = 驅動程式儲存並只使用資料列集中資料列的索引鍵。

預設值為 SQL_CURSOR_FORWARD_ONLY。 在備妥 SQL 語句之後，無法指定這個屬性。

如果資料來源不支援指定的資料指標類型，驅動程式會替代不同的資料指標類型，並傳回 SQLSTATE 01S02 （選項值已變更）。 對於混合或動態資料指標，驅動程式會依序取代索引鍵集驅動或靜態資料指標。 若為索引鍵集驅動資料指標，驅動程式會取代靜態資料指標。

如需可捲動資料指標類型的詳細資訊，請參閱 可捲動的資料指標類型 。 如需SQL_ATTR_CURSOR_TYPE與其他資料指標屬性之間關聯性的詳細資訊，請參閱 資料指標特性和資料指標類型 。
SQL_ATTR_ENABLE_AUTO_IPD （ODBC 3.0） SQLULEN 值，指定是否執行 IPD 的自動母體擴展：

SQL_TRUE = 在呼叫 SQLPrepare 之後開啟 IPD 的自動母體擴展。 SQL_FALSE = 在呼叫 SQLPrepare 之後關閉 IPD 的自動擴展。 （應用程式仍可藉由呼叫 來取得 IPD 欄位資訊如果支援，SQLDescribeParam 。）語句屬性SQL_ATTR_ENABLE_AUTO_IPD的預設值為 SQL_FALSE。 如需詳細資訊，請參閱 IPD 的自動母體擴展。
SQL_ATTR_FETCH_BOOKMARK_PTR （ODBC 3.0） 指向二進位書簽值的 SQLLEN * 。 當呼叫與 fFetchOrientation 等於 SQL_FETCH_BOOKMARK 的 SQLFetchScroll 時 ，驅動程式會從此欄位挑選書簽值。 此欄位預設為 Null 指標。 如需詳細資訊，請參閱 依書簽 捲動。

此欄位所指向的值不會用於依書簽刪除、依書簽更新，或 SQLBulkOperations 中的 書簽作業擷取，而 SQLBulkOperations 會使用資料列集緩衝區中快取的書簽。
SQL_ATTR_IMP_PARAM_DESC （ODBC 3.0） IPD 的控制碼。 此屬性的值是一開始配置 語句時所配置的描述元。 應用程式無法設定這個屬性。

這個屬性可由對 SQLGetStmtAttr 的呼叫 擷取，但無法由呼叫 SQLSetStmtAttr 來設定。
SQL_ATTR_IMP_ROW_DESC （ODBC 3.0） IRD 的控制碼。 此屬性的值是一開始配置 語句時所配置的描述元。 應用程式無法設定這個屬性。

這個屬性可由對 SQLGetStmtAttr 的呼叫 擷取，但無法由呼叫 SQLSetStmtAttr 來設定。
SQL_ATTR_KEYSET_SIZE （ODBC 2.0） SQLULEN，指定索引鍵集驅動資料指標之索引鍵集中的資料列數目。 如果索引鍵集大小為 0（預設值），則游標會完全由索引鍵集驅動。 如果索引鍵集大小大於 0，則游標會混合（索引鍵集內由索引鍵集驅動，並在索引鍵集外部動態）。 預設索引鍵集大小為 0。 如需索引鍵集驅動資料指標的詳細資訊，請參閱 Keyset-Driven Cursors 。

如果指定的大小超過索引鍵集大小上限，驅動程式會取代該大小並傳回 SQLSTATE 01S02 （選項值已變更）。

如果索引鍵集大小大於 0 且小於資料列集大小，SQLFetch 或 SQLFetchScroll 會傳回錯誤。
SQL_ATTR_MAX_LENGTH （ODBC 1.0） SQLULEN 值，指定驅動程式從字元或二進位資料行傳回的最大資料量。 如果 ValuePtr 小於可用資料的長度， SQLFetch 或 SQLGetData 會截斷資料並傳回SQL_SUCCESS。 如果 ValuePtr 為 0（預設值），驅動程式會嘗試傳回所有可用的資料。

如果指定的長度小於資料來源可以傳回的最小資料量，或大於資料來源可以傳回的最大資料量，則驅動程式會取代該值並傳回 SQLSTATE 01S02 （選項值已變更）。

這個屬性的值可以在開啟的資料指標上設定;不過，設定可能不會立即生效，在此情況下，驅動程式會傳回 SQLSTATE 01S02 （選項值已變更），並將屬性重設為其原始值。

這個屬性的目的是要減少網路流量，而且只有在多層式驅動程式中的資料來源（與驅動程式相反）才能實作它時才支援。 應用程式不應使用此機制來截斷資料;若要截斷收到的資料，應用程式應該在 SQLBindCol 或 SQLGetData 的 BufferLength 引數中 指定緩衝區長度上限。
SQL_ATTR_MAX_ROWS （ODBC 1.0） SQLULEN 值，對應至 SELECT 語句要傳回至應用程式 的資料列數目上限。 如果 * ValuePtr 等於 0（預設值），驅動程式會傳回所有資料列。

此屬性旨在減少網路流量。 就概念上來說，它會在建立結果集時套用，並將結果集限制為第一個 ValuePtr 資料列。 如果結果集中的資料列數目大於 ValuePtr ，則會截斷結果集。

SQL_ATTR_MAX_ROWS適用于語句 上 的所有結果集，包括目錄函式所傳回的結果集。 SQL_ATTR_MAX_ROWS為數據指標資料列計數的值建立最大值。

如果驅動程式無法保證SQL_ATTR_MAX_ROWS正確實作，則驅動程式不應模擬 SQLFetch 或 SQLFetchScroll 的SQL_ATTR_MAX_ROWS行為 （如果無法在資料來源實作結果集大小限制）。

驅動程式定義SQL_ATTR_MAX_ROWS是否適用于 SELECT 語句以外的語句（例如目錄函式）。

這個屬性的值可以在開啟的資料指標上設定;不過，設定可能不會立即生效，在此情況下，驅動程式會傳回 SQLSTATE 01S02 （選項值已變更），並將屬性重設為其原始值。
SQL_ATTR_METADATA_ID （ODBC 3.0） SQLULEN 值，決定如何處理目錄函式的字串引數。

如果SQL_TRUE，則會將目錄函式的字串引數視為識別碼。 此案例並不重要。 針對非匯入字串，驅動程式會移除任何尾端空格，並將字串折迭成大寫。 對於分隔字串，驅動程式會移除任何前置或尾端空格，並以字面方式接受分隔符號之間的任何內容。 如果其中一個引數設定為 Null 指標，則函式會傳回 SQL_ERROR 和 SQLSTATE HY009 （Null 指標的無效使用）。

如果SQL_FALSE，則目錄函式的字串引數不會被視為識別碼。 此案例相當重要。 視 引數而定，它們可以包含字串搜尋模式。

預設值為 SQL_FALSE。

採用值清單的 SQLTables TableType 引數不會受到此屬性的影響。

您也可以在連線層級上設定SQL_ATTR_METADATA_ID。 （它和SQL_ATTR_ASYNC_ENABLE是唯一也是連接屬性的語句屬性。

如需詳細資訊，請參閱目錄函式中的引數。
SQL_ATTR_NOSCAN （ODBC 1.0） SQLULEN 值，指出驅動程式是否應該掃描 SQL 字串來尋找逸出序列：

SQL_NOSCAN_OFF = 驅動程式會掃描 SQL 字串以尋找逸出序列（預設值）。

SQL_NOSCAN_ON = 驅動程式不會掃描 SQL 字串是否有逸出序列。 相反地，驅動程式會將 語句直接傳送至資料來源。

如需詳細資訊，請參閱 ODBC 中的逸出序列。
SQL_ATTR_PARAM_BIND_OFFSET_PTR （ODBC 3.0） SQLULEN * 值，指向新增至指標的位移，以變更動態參數的系結。 如果此欄位為非 Null，驅動程式會取值指標、將取值新增至描述元記錄中每個延遲的欄位（SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR），並在系結時使用新的指標值。 預設會將它設定為 null。

系結位移一律會直接新增至SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR欄位。 如果位移變更為不同的值，新值仍會直接新增至描述元欄位中的值。 新的位移不會新增至域值加上任何先前的位移。

如需詳細資訊，請參閱 參數系結位移 。

設定此語句屬性會設定 APD 標頭中的SQL_DESC_BIND_OFFSET_PTR欄位。
SQL_ATTR_PARAM_BIND_TYPE （ODBC 3.0） SQLULEN 值，指出要用於動態參數的系結方向。

此欄位設定為 SQL_PARAM_BIND_BY_COLUMN （預設值） 以選取資料行型系結。

若要選取資料列系結，此欄位會設定為結構長度或將系結至一組動態參數的緩衝區實例。 此長度必須包含所有系結參數的空間，以及結構或緩衝區的任何填補，以確保當系結參數的位址以指定的長度遞增時，結果會指向下一組參數中相同參數的開頭。 在 ANSI C 中使用 sizeof 運算子時，會保證此行為。

如需詳細資訊，請參閱 系結參數 陣列。

設定此語句屬性會設定 APD 標頭中的SQL_DESC_ BIND_TYPE欄位。
SQL_ATTR_PARAM_OPERATION_PTR （ODBC 3.0） SQLUSMALLINT * 值，指向在 SQL 語句執行期間用來忽略參數的 SQLUSMALLINT 值陣列。 每個值都會設定為SQL_PARAM_PROCEED（針對要執行的參數）或SQL_PARAM_IGNORE（要忽略參數）。

您可以在處理期間忽略一組參數，方法是將 APD 中SQL_DESC_ARRAY_STATUS_PTR指向的陣列狀態值設定為 SQL_PARAM_IGNORE。 如果參數的狀態值設定為SQL_PARAM_PROCEED或陣列中未設定任何元素，則會處理一組參數。

這個語句屬性可以設定為 Null 指標，在此情況下，驅動程式不會傳回參數狀態值。 這個屬性可以隨時設定，但直到下次呼叫 SQLExecDirect 或 SQLExecute 之前 ，才會使用新的值。

沒有系結參數時，會忽略這個屬性。

如需詳細資訊，請參閱 使用參數 陣列。

設定此語句屬性會設定 APD 標頭中的SQL_DESC_ARRAY_STATUS_PTR欄位。
SQL_ATTR_PARAM_STATUS_PTR （ODBC 3.0） SQLUSMALLINT * 值，指向 SQLUSMALLINT 值陣列，其中包含呼叫 SQLExecute 或 SQLExecDirect 之後每個參數值資料列的狀態資訊。 只有當PARAMSET_SIZE大於 1 時，才需要此欄位。

狀態值可以包含下列值：

SQL_PARAM_SUCCESS：已成功針對這組參數執行 SQL 語句。

SQL_PARAM_SUCCESS_WITH_INFO：已成功針對這組參數執行 SQL 語句;不過，診斷資料結構中提供警告資訊。

SQL_PARAM_ERROR：處理這組參數時發生錯誤。 診斷資料結構中提供其他錯誤資訊。

SQL_PARAM_UNUSED：此參數集未使用，可能是因為某些先前的參數集造成錯誤而中止進一步處理，或因為SQL_PARAM_IGNORE已針對SQL_ATTR_PARAM_OPERATION_PTR所指定陣列中的該組參數設定。

SQL_PARAM_DIAG_UNAVAILABLE：驅動程式會將參數陣列視為整合型單位，因此不會產生此層級的錯誤資訊。

這個語句屬性可以設定為 Null 指標，在此情況下，驅動程式不會傳回參數狀態值。 這個屬性可以隨時設定，但直到下次呼叫 SQLExecute 或 SQLExecDirect 之前 ，才會使用新的值。 請注意，設定此屬性可能會影響驅動程式所實作的輸出參數行為。

如需詳細資訊，請參閱 使用參數 陣列。

設定此語句屬性會設定 IPD 標頭中的SQL_DESC_ARRAY_STATUS_PTR欄位。
SQL_ATTR_PARAMS_PROCESSED_PTR （ODBC 3.0） 指向緩衝區的 SQLULEN * 記錄欄位，用來傳回已處理的參數集數目，包括錯誤集。 如果這是 Null 指標，則不會傳回任何數位。

設定此語句屬性會設定 IPD 標頭中的SQL_DESC_ROWS_PROCESSED_PTR欄位。

如果呼叫 填入此屬性所指向之緩衝區的 SQLExecDirect 或 SQLExecute 不會傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，則未定義緩衝區的內容。

如需詳細資訊，請參閱 使用參數 陣列。
SQL_ATTR_PARAMSET_SIZE （ODBC 3.0） SQLULEN 值，指定每個參數的值數目。 如果SQL_ATTR_PARAMSET_SIZE大於 1、SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和 APD 指向陣列的SQL_DESC_OCTET_LENGTH_PTR。 每個陣列的基數等於此欄位的值。

沒有系結參數時，會忽略這個屬性。

如需詳細資訊，請參閱 使用參數 陣列。

設定此語句屬性會設定 APD 標頭中的SQL_DESC_ARRAY_SIZE欄位。
SQL_ATTR_QUERY_TIMEOUT （ODBC 1.0） SQLULEN 值，對應至等候 SQL 語句在返回應用程式之前執行的秒數。 如果 ValuePtr 等於 0 （預設值），則不會逾時。

如果指定的逾時超過資料來源中的逾時上限，或小於最小逾時， SQLSetStmtAttr 會取代該值，並傳回 SQLSTATE 01S02 （選項值已變更）。

請注意，如果 SELECT 語句逾時，應用程式不需要呼叫 SQLCloseCursor 來重複使用語句。

此語句屬性中設定的查詢逾時在同步和非同步模式中都是有效的。
SQL_ATTR_RETRIEVE_DATA （ODBC 2.0） SQLULEN 值：

SQL_RD_ON = SQLFetchScroll ，而且，在 ODBC 3.x 中， SQLFetch 會在將資料指標放置在指定的位置之後擷取資料。 這是預設值。

SQL_RD_OFF = SQLFetchScroll ，而且，在 ODBC 3.x 中， SQLFetch 不會在資料指標放置之後擷取資料。

藉由將SQL_RETRIEVE_DATA設定為 SQL_RD_OFF，應用程式可以驗證資料列是否存在或擷取資料列的書簽，而不會產生擷取資料列的額外負荷。 如需詳細資訊，請參閱 捲動和擷取資料列 。

這個屬性的值可以在開啟的資料指標上設定;不過，設定可能不會立即生效，在此情況下，驅動程式會傳回 SQLSTATE 01S02 （選項值已變更），並將屬性重設為其原始值。
SQL_ATTR_ROW_ARRAY_SIZE （ODBC 3.0） SQLULEN 值，指定每次呼叫 SQLFetch 或 SQLFetchScroll 所傳回的資料列數目。 這也是 SQLBulkOperations 中大量書簽作業中使用的書簽陣列中的資料 列數目。 預設值是 1。

如果指定的資料列集大小超過資料來源所支援的資料列集大小上限，則驅動程式會取代該值並傳回 SQLSTATE 01S02 （選項值已變更）。

如需詳細資訊，請參閱 資料列集大小 。

設定此語句屬性會設定 ARD 標頭中的SQL_DESC_ARRAY_SIZE欄位。
SQL_ATTR_ROW_BIND_OFFSET_PTR （ODBC 3.0） SQLULEN * 值，指向新增至指標的位移，以變更資料行資料的系結。 如果此欄位為非 Null，驅動程式會取值指標、將取值新增至描述元記錄中每個延遲的欄位（SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR），並在系結時使用新的指標值。 預設會將它設定為 null。

設定此語句屬性會設定 ARD 標頭中的SQL_DESC_BIND_OFFSET_PTR欄位。
SQL_ATTR_ROW_BIND_TYPE （ODBC 1.0） SQLULEN 值，這個值會在相關聯語句上呼叫 SQLFetch 或 SQLFetchScroll 時 ，設定要使用的系結方向。 藉由將值設定為 SQL_BIND_BY_COLUMN，以選取資料行式系結。 藉由將值設定為結構長度，或是將結果資料行系結至其中之緩衝區的實例，即可選取資料列的系結。

如果指定長度，它必須包含所有系結資料行的空間，以及結構或緩衝區的任何填補，以確保當系結資料行的位址以指定的長度遞增時，結果會指向下一個資料列中相同資料行的開頭。 搭配 ANSI C 中的結構或等位使用 sizeof 運算子時，保證此行為。

資料行式系結是 SQLFetch 和 SQLFetchScroll 的預設系結方向 。

如需詳細資訊，請參閱 系結資料行以搭配區塊資料指標 使用。

設定此語句屬性會設定 ARD 標頭中的SQL_DESC_BIND_TYPE欄位。
SQL_ATTR_ROW_NUMBER （ODBC 2.0） SQLULEN 值，這是整個結果集中目前資料列的數目。 如果無法判斷目前資料列的數目，或沒有目前的資料列，驅動程式會傳回 0。

這個屬性可由對 SQLGetStmtAttr 的呼叫 擷取，但無法由呼叫 SQLSetStmtAttr 來設定。
SQL_ATTR_ROW_OPERATION_PTR （ODBC 3.0） SQLUSMALLINT * 值，指向使用 SQLSetPos 進行大量作業期間用來忽略資料列的 SQLUSMALLINT 值陣列。 每個值都會設定為SQL_ROW_PROCEED（針對要包含在大量作業中的資料列）或SQL_ROW_IGNORE（針對要從大量作業排除的資料列）。 （呼叫 期間 無法使用這個陣列忽略資料列SQLBulkOperations .）

這個語句屬性可以設定為 Null 指標，在此情況下，驅動程式不會傳回資料列狀態值。 這個屬性可以隨時設定，但直到下次呼叫 SQLSetPos 之前 ，才會使用新的值。

如需詳細資訊，請參閱 使用 SQLSetPos 更新資料列集中的資料列和 使用 SQLSetPos 刪除資料列集中的資料列。

設定此語句屬性會設定 ARD 中的SQL_DESC_ARRAY_STATUS_PTR欄位。
SQL_ATTR_ROW_STATUS_PTR （ODBC 3.0） SQLUSMALLINT * 值，指向呼叫 SQLFetch 或 SQLFetchScroll 之後 包含資料列狀態值的 SQLUSMALLINT 值陣列。 陣列具有與資料列集中的資料列數目一樣多的專案。

這個語句屬性可以設定為 Null 指標，在此情況下，驅動程式不會傳回資料列狀態值。 這個屬性可以隨時設定，但直到下次呼叫 SQLBulkOperations 、SQLFetch、 SQLFetchScroll 或 SQLSetPos 之後 ，才會使用新的值。

如需詳細資訊，請參閱 擷取的資料列數目和狀態 。

設定此語句屬性會設定 IRD 標頭中的SQL_DESC_ARRAY_STATUS_PTR欄位。

這個屬性是由 ODBC 2.x 驅動程式對應至 呼叫 SQLExtendedFetch 中的 rgbRowStatus 陣列。
SQL_ATTR_ROWS_FETCHED_PTR （ODBC 3.0） 指向緩衝區的 SQLULEN * 值，這個緩衝區會傳回呼叫 SQLFetch 或 SQLFetchScroll 之後擷取的資料列數目;呼叫 SQLSet SQL_REFRESH Pos 時所執行之大量作業所影響的資料列數目，以及 SQLBulkOperations 所執行 之大量作業所影響的資料列數目。 此數位包含錯誤資料列。

如需詳細資訊，請參閱 擷取的資料列數目和狀態 。

設定此語句屬性會設定 IRD 標頭中的SQL_DESC_ROWS_PROCESSED_PTR欄位。

如果呼叫 填入此屬性所指向之緩衝區的 SQLFetch 或 SQLFetchScroll 不會傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，則未定義緩衝區的內容。
SQL_ATTR_SIMULATE_CURSOR （ODBC 2.0） SQLULEN 值，指定模擬定點更新和刪除語句的驅動程式是否保證這類語句只會影響一個單一資料列。

為了模擬定位的更新和刪除語句，大部分驅動程式都會建構搜尋的 UPDATE 或 DELETE 語句，其中包含 WHERE 子句，指定目前資料列中每個資料行的值。 除非這些資料行構成唯一索引鍵，否則這類語句可能會影響一個以上的資料列。

為了保證這類語句只會影響一個資料列，驅動程式會決定唯一索引鍵中的資料行，並將這些資料行新增至結果集。 如果應用程式保證結果集中的資料行構成唯一索引鍵，則驅動程式不需要這麼做。 這可能會減少執行時間。

SQL_SC_NON_UNIQUE = 驅動程式不保證模擬定點更新或刪除語句只會影響一個資料列;應用程式有責任這麼做。 如果語句影響一個以上的資料列， SQLExecute 、 SQLExecDirect 或 SQLSetPos 會傳回 SQLSTATE 01001 （資料指標作業衝突）。

SQL_SC_TRY_UNIQUE = 驅動程式會嘗試保證模擬位置更新或刪除語句只會影響一個資料列。 驅動程式一律會執行這類語句，即使它們可能會影響多個資料列，例如沒有唯一索引鍵時。 如果語句影響一個以上的資料列， SQLExecute 、 SQLExecDirect 或 SQLSetPos 會傳回 SQLSTATE 01001 （資料指標作業衝突）。

SQL_SC_UNIQUE = 驅動程式保證模擬位置更新或刪除語句只會影響一個資料列。 如果驅動程式無法保證給定語句的這個值， SQLExecDirect 或 SQLPrepare 會傳回錯誤。

如果資料來源針對定位的更新和 delete 語句提供原生 SQL 支援，而且驅動程式不會模擬資料指標，SQL_SUCCESS會在要求SQL_SIMULATE_CURSOR SQL_SC_UNIQUE時傳回。 如果要求SQL_SC_TRY_UNIQUE或SQL_SC_NON_UNIQUE，則會傳回SQL_SUCCESS_WITH_INFO。 如果資料來源提供SQL_SC_TRY_UNIQUE層級的支援，且驅動程式沒有，則會針對SQL_SC_TRY_UNIQUE傳回SQL_SUCCESS，並傳回SQL_SC_NON_UNIQUE SQL_SUCCESS_WITH_INFO。

如果資料來源不支援指定的資料指標模擬類型，驅動程式會替代不同的模擬類型，並傳回 SQLSTATE 01S02 （選項值已變更）。 針對SQL_SC_UNIQUE，驅動程式會依序取代SQL_SC_TRY_UNIQUE或SQL_SC_NON_UNIQUE。 針對SQL_SC_TRY_UNIQUE，驅動程式會取代 SQL_SC_NON_UNIQUE。

預設值為 SQL_SC_UNIQUE。

如需詳細資訊，請參閱 模擬定點更新和刪除語句 。
SQL_ATTR_USE_BOOKMARKS （ODBC 2.0） SQLULEN 值，指定應用程式是否會搭配資料指標使用書簽：

SQL_UB_OFF = 關閉 （預設值）

SQL_UB_VARIABLE = 應用程式將搭配游標使用書簽，如果支援書簽，驅動程式就會提供可變長度的書簽。 ODBC 3.x 中SQL_UB_FIXED已被取代。 ODBC 3.x 應用程式應該一律使用可變長度書簽，即使使用 ODBC 2.x 驅動程式（僅支援 4 位元組、固定長度的書簽）。 這是因為固定長度書簽只是可變長度書簽的特殊案例。 使用 ODBC 2.x 驅動程式時，驅動程式管理員會將SQL_UB_VARIABLE對應至SQL_UB_FIXED。

若要搭配資料指標使用書簽，應用程式必須在開啟資料指標之前，使用SQL_UB_VARIABLE值來指定此屬性。

如需詳細資訊，請參閱 擷取書簽 。

[1] 只有當描述項是實作描述元，而不是應用程式描述元時，才能以非同步方式呼叫這些函式。

請參閱 資料行明智的系結 和資料 列的系結 。

如需下列資訊 請參閱
取消語句處理 SQLCancel 函式
傳回連接屬性的設定 SQLGetConnectAttr 函式
傳回語句屬性的設定 SQLGetStmtAttr 函式
設定連接屬性 SQLSetConnectAttr 函式
設定描述項的單一欄位 SQLSetDescField 函式

另請參閱

ODBC API 參考
ODBC 標頭檔