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 * 值，指向 SQLUSMALLINT 值陣列，用來在 SQL 語句執行期間忽略參數。 每個值都會設定為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 函式 |