SQLSetStmtAttr 函數

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

總結
SQLSetStmtAttr 會設定與語句相關的屬性。

注意

如需當 ODBC 3.x 應用程式 與 odbc 2.x 驅動程式搭配 使用時,驅動程式管理員會將此函式對應至的詳細資訊,請參閱對應取代函式 以取得應用程式的回溯相容性

語法

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

引數

StatementHandle
輸出語句控制碼。

Attribute
輸出要設定的選項,列在 [批註] 中。

ValuePtr
輸出要與 屬性 相關聯的值。 根據 屬性 的值, ValuePtr 會是下列其中一項:

  • ODBC 描述項控制碼。

  • SQLUINTEGER 值。

  • SQLULEN 值。

  • 下列其中一項的指標:

    • 以 null 結束的字元字串。

    • 二進位緩衝區。

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

    • 驅動程式定義的值。

如果 屬性 引數是驅動程式特定的值,則 ValuePtr 可能是帶正負號的整數。

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

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

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

  • 如果 ValuePtr 是二進位緩衝區的指標,則應用程式會將 SQL_LEN_BINARY_ATTR (長度) 宏的結果放在 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 時,可以藉由呼叫 SQLGetDiagRecHandleType (SQL_HANDLE_STMT)和 StatementHandle控制碼 來取得相關聯的 SQLSTATE 值。 下表列出 SQLSetStmtAttr 常傳回的 SQLSTATE 值,並在此函式的內容中說明每一個值;「 (DM) 」標記法優先于驅動程式管理員所傳回的 SQLSTATEs 描述。 除非另有說明,否則會 SQL_ERROR 與每個 SQLSTATE 值相關聯的傳回碼。

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。 SQLGetDiagRec* MessageText 緩衝區中傳回的錯誤訊息會描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY009 Null 指標的用法無效 屬性 引數識別出需要字串屬性的語句屬性,且 ValuePtr 引數為 null 指標。
HY010 函數順序錯誤 (DM) 以非同步方式執行的函式,是與 StatementHandle 相關聯的連接控制碼所呼叫。 呼叫 SQLSetStmtAttr 函式時,仍在執行此非同步函式。

針對 StatementHandle 呼叫 SQLExecuteSQLEXECDIRECTSQLMoreResults () DM,並傳回 SQL_PARAM_DATA_AVAILABLE。 在抓取所有資料流程參數的資料之前,會呼叫此函數。

(DM) 針對 StatementHandle 呼叫非同步執行的函式,但在呼叫此函式時仍在執行。

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

(DM) 屬性 引數是 SQL_ATTR_APP_ROW_DESC 或 SQL_ATTR_APP_PARAM_DESC,且 ValuePtr 中的值是隱含配置的描述項控制碼,而非原本針對 ARD 或 APD 配置的控制碼。
HY024 不正確屬性值 由於指定的 屬性 值,在 ValuePtr 中指定了不正確值。 (驅動程式管理員只會針對接受一組離散值的連接和語句屬性傳回這個 SQLSTATE,例如 SQL_ATTR_ACCESS_MODE 或 SQL_ ATTR_ASYNC_ENABLE。 對於所有其他連接和語句屬性,驅動程式必須確認 ValuePtr 中指定的值。 )

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

(DM) 為引數 屬性 指定的值為唯讀屬性。
HY117 由於未知的交易狀態,連接已暫止。 只允許中斷連接和唯讀功能。 (DM) 如需暫停狀態的詳細資訊,請參閱 SQLEndTran 函數
HYC00 未執行選用功能 針對引數 屬性 指定的值是驅動程式所支援之 odbc 版本的有效 odbc 語句屬性,但驅動程式不支援此屬性。

屬性 引數是 SQL_ATTR_ASYNC_ENABLE 的 ,且 SQL_ASYNC_MODE InfoType 的呼叫會傳回 SQL_AM_CONNECTION。

屬性 引數是 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 (選項值) 變更。 例如,如果 屬性 是 SQL_ATTR_CONCURRENCY,且 ValuePtr 是 SQL_CONCUR_ROWVER,而且如果資料來源不支援這種情況,驅動程式就會替代 SQL_CONCUR_VALUES 並傳回 SQL_SUCCESS_WITH_INFO。 為了判斷取代的值,應用程式會呼叫 SQLGetStmtAttr

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

注意

藉由呼叫 SQLSetConnectAttr 在連接層級設定語句屬性的能力, 在 ODBC 3.x 中已經被取代。 ODBC 3.x 應用程式絕對不應該在連接層級設定語句屬性。 ODBC 3.x 語句屬性無法在連接層級設定,但 SQL_ATTR_METADATA_ID 和 SQL_ATTR_ASYNC_ENABLE 屬性(兩者都是連接屬性和語句屬性)除外,而且可以在連接層級或語句層級設定。

注意

如果 ODBC 3.x 驅動程式應該使用 odbc 2.x 應用程式 ,而這些應用程式會在連接層級設定 odbc 2.x 語句選項 ,則只需要支援此功能。 For more information, see "Setting Statement Options on the Connection Level" under SQLSetConnectOption Mapping in Appendix G: Driver Guidelines for Backward Compatibility.

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

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

警告

針對一個語句呼叫 SQLSetStmtAttr 可能會影響其他語句。 當明確配置與語句相關聯的 APD 或 ARD,而且也與其他語句相關聯時,就會發生這種情況。 由於 SQLSetStmtAttr 會修改 APD 或 ARD,因此修改會套用至與這個描述項相關聯的所有語句。 如果這不是必要的行為,則應用程式應該透過呼叫 SQLSetStmtAttr 將 SQL_ATTR_APP_ROW_DESC 或 SQL_ATTR_APP_PARAM_DESC 欄位設定為不同的描述項句) 柄,以將此描述元與其他語句中斷關聯 (,然後再呼叫 SQLSetStmtAttr

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

配置語句時 (請參閱 SQLAllocHandle) ,系統會自動設定四個描述項控制碼,並與語句建立關聯。 明確配置的描述項控制碼可以與語句建立關聯,方法是呼叫具有 SQL_HANDLE_DESC fHandleTypeSQLAllocHandle ,以配置描述項控制碼,然後呼叫 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 稅務局
SQL_ATTR_ROWS_FETCHED_PTR SQL_DESC_ROWS_PROCESSED_PTR 稅務局

陳述式屬性

下表顯示目前定義的屬性和其引進的 ODBC 版本。預期有更多屬性會由驅動程式定義,以利用不同的資料來源。 ODBC 會保留屬性範圍;驅動程式開發人員必須從開啟的群組中保留自己的驅動程式特定使用值。 如需詳細資訊,請參閱 驅動程式特定的資料類型、描述項類型、資訊類型、診斷類型與屬性

屬性 ValuePtr 內容
SQL_ATTR_APP_PARAM_DESC (ODBC 3.0) 在語句控制碼上,後續呼叫 SQLExecuteSQLExecDirect 的 APD 控制碼。 這個屬性的初始值是首次配置語句時,隱含配置的描述項。 如果這個屬性的值設定為 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 SQL_AM_CONNECTION InfoType 傳回時,呼叫 SQLSetStmtAttr 來設定 SQL_ATTR_ASYNC_ENABLE 會傳回 SQLSTATE HYC00 (未) 執行的選擇性功能。 如需詳細資訊,請參閱 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 = Cursor 最低層級的鎖定就足以確保資料列可以更新。

SQL_CONCUR_ROWVER = Cursor 使用開放式並行存取控制,比較資料列版本,例如 SQLBase ROWID 或 Sybase TIMESTAMP。

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

SQL_ATTR_CONCURRENCY 的預設值是 SQL_CONCUR_READ_ONLY。

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

如果 SQL_ATTR_CURSOR_TYPE 屬性 變更為不支援 SQL_ATTR_CONCURRENCY 目前值的類型,則在執行時間會變更 SQL_ATTR_CONCURRENCY 的值,並在呼叫 SQLExecDirectSQLPrepare 時發出警告。

如果驅動程式支援 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 的值會在執行時間變更,而 SQLSTATE 01S02 (選項值會在呼叫 SQLExecDirectSQLPrepare 時發出變更) 。

如果資料來源不支援指定的平行存取,驅動程式會替代不同的平行存取,並傳回 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 值,指定應用程式所需的支援層級。 設定此屬性會影響對 SQLExecDirectSQLExecute 的後續呼叫。

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

SQL_SCROLLABLE = 語句控制碼上需要可滾動的資料指標。 呼叫 SQLFetchScroll 時,應用程式可以指定任何有效值的 FetchOrientation,以在順序模式以外的模式下進行資料指標定位。

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

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 的自動填入。 (如果支援,應用程式仍然可以藉由呼叫 SQLDescribeParam 來取得 IPD 欄位資訊。 ) 語句屬性的預設值 SQL_ATTR_ENABLE_AUTO_IPD SQL_FALSE。 如需詳細資訊,請參閱 自動填入 IPD
SQL_ATTR_FETCH_BOOKMARK_PTR (ODBC 3.0) *指向二進位書簽值的 SQLLEN。 當呼叫 SQLFetchScroll 時, fFetchOrientation 等於 SQL_FETCH_BOOKMARK 時,驅動程式會從這個欄位挑選書簽值。 此欄位預設為 null 指標。 如需詳細資訊,請參閱 依書簽進行滾動

此欄位所指向的值不會用來依書簽刪除、依書簽更新,或是使用在資料列集緩衝區中快取的書簽來提取 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。 如需索引鍵集驅動資料指標的詳細資訊,請參閱索引 鍵集驅動的資料指標。

如果指定的大小超過最大的索引鍵集大小,則驅動程式會替代該大小,並傳回 SQLSTATE 01S02 (選項值) 變更。

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

如果指定的長度小於資料來源可傳回或大於資料來源可傳回的最大資料量的最小資料量,驅動程式會替代該值,並傳回變更) 的 SQLSTATE 01S02 (選項值。

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

這個屬性的目的是要減少網路流量,而且只有當資料來源 (而不是在多層式驅動程式中的驅動程式) 可以執行時,才支援此屬性。 應用程式不應使用此機制來截斷資料;若要截斷所接收的資料,應用程式應該在 SQLBindColSQLGetDataBufferLength 引數中指定最大緩衝區長度。
SQL_ATTR_MAX_ROWS (ODBC 1.0) SQLULEN 值,對應至要傳回給 SELECT 語句之應用程式的最大資料列數。 如果 * ValuePtr 等於 0 (預設) ,驅動程式會傳回所有資料列。

這個屬性的目的是要減少網路流量。 就概念而言,它會在建立結果集時套用,並將結果集限制為第一個 ValuePtr 資料列。 如果結果集中的資料列數目大於 ValuePtr,則會截斷結果集。

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

如果無法保證 SQLFetch 或 SQLFetchScroll 的結果集大小限制無法在資料) 源上執行,驅動程式就不應模擬或的 SQL_ATTR_MAX_ROWS 行為 (如果無法保證 SQL_ATTR_MAX_ROWS 將會正確地執行。

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

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

如果 SQL_TRUE,則會將目錄函數的字串引數視為識別碼。 這種情況並不重要。 針對 nondelimited 字串,驅動程式會移除任何尾端空格,而字串會折迭為大寫。 若為分隔的字串,驅動程式會移除任何開頭或尾端空格,並以真正的形式接受分隔符號之間的任何字元。 如果其中一個引數設定為 null 指標,則此函式會傳回 SQL_ERROR 和 SQLSTATE HY009 (不正確 null 指標) 用法。

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

預設值為 SQL_FALSE。

SQLTablesTableType 引數(接受值清單)不會受到這個屬性的影響。

您也可以在連接層級上設定 SQL_ATTR_METADATA_ID。 (它和 SQL_ATTR_ASYNC_ENABLE 是唯一同時為連接屬性的語句屬性 )

如需詳細資訊,請參閱 目錄函數中的引數
SQL_ATTR_NOSCAN (ODBC 1.0) SQLULEN 值,指出驅動程式是否應該掃描逸出序列的 SQL 字串:

SQL_NOSCAN_OFF = 驅動程式會掃描 SQL 字串是否有 (預設) 的 escape 序列。

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

如需詳細資訊,請參閱 ODBC 中的 Escape 序列
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 指標,在此情況下,驅動程式不會傳回參數狀態值。 您可以隨時設定這個屬性,但在下一次呼叫 SQLExecDirectSQLExecute 之前,並不會使用新的值。

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

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

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

狀態值可以包含下列值:

SQL_PARAM_SUCCESS:已成功執行這組參數的 SQL 語句。

SQL_PARAM_SUCCESS_WITH_INFO:已成功執行這組參數的 SQL 語句;不過,診斷資料結構中有提供警告資訊。

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

SQL_PARAM_UNUSED:未使用此參數集,可能是因為某些先前的參數集造成了中止進一步處理的錯誤,或因為 SQL_ATTR_PARAM_OPERATION_PTR 所指定之陣列中的一組參數設定 SQL_PARAM_IGNORE。

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

這個語句屬性可以設定為 null 指標,在此情況下,驅動程式不會傳回參數狀態值。 您可以隨時設定這個屬性,但在下一次呼叫 SQLExecuteSQLExecDirect 之前,並不會使用新的值。 請注意,設定此屬性可能會影響驅動程式所執行的輸出參數行為。

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

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

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

如果對 SQLExecDirectSQLExecute 的呼叫,而該屬性是填入這個屬性所指向的緩衝區,就不會傳回 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,並 SQL_DESC_OCTET_LENGTH_PTR APD 點加入陣列。 每個陣列的基數都等於這個欄位的值。

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

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

設定這個語句屬性會設定 APD 標頭中的 SQL_DESC_ARRAY_SIZE 欄位。
SQL_ATTR_QUERY_TIMEOUT (ODBC 1.0) SQLULEN 值,對應至等候 SQL 語句執行的秒數,然後再返回應用程式。 如果 ValuePtr 等於 0 (預設) ,就不會有任何超時。

如果指定的超時時間超過資料來源中的最大 timeout,或小於最小的超時時間, SQLSetStmtAttr 會取代該值,並傳回 SQLSTATE 01S02 (選項值) 變更。

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

在此語句屬性中設定的查詢 timeout 在同步和非同步模式中都是有效的。
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 值,指定每個對 SQLFetchSQLFetchScroll 的呼叫所傳回的資料列數目。 它也是在 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 值,這個值會設定在相關聯的語句上呼叫 SQLFetchSQLFetchScroll 時要使用的系結方向。 藉由將值設定為 [SQL_BIND_BY_COLUMN],即可選取資料行取向的系結。 藉由將值設定為結構的長度,或將系結結果資料行的緩衝區實例,來選取資料列取向的系結。

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

資料行取向系結是 SQLFetchSQLFetchScroll 的預設系結方向。

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

設定這個語句屬性會設定 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 * 值,這個值會指向 SQLUSMALLINT 值的陣列,這些值會在使用 SQLSetPos 的大量作業期間,用來忽略資料列。 每個值都會設定為要包含在大量作業中的資料列 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 * 值,指向 SQLFetchSQLFetchScroll 呼叫之後,指向包含資料列狀態值之 SQLUSMALLINT 值陣列的值。 陣列的元素數目與資料列集中的資料列數目相同。

這個語句屬性可以設定為 null 指標,在此情況下,驅動程式不會傳回資料列狀態值。 您可以隨時設定這個屬性,但在下一次呼叫 SQLBulkOperationsSQLFetchSQLFetchScrollSQLSetPos 之前,並不會使用新的值。

如需詳細資訊,請參閱 提取的資料列數目和狀態

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

這個屬性是 由 ODBC 2.x 驅動程式對應到 SQLExtendedFetch 呼叫中的 rgbRowStatus 陣列。
SQL_ATTR_ROWS_FETCHED_PTR (ODBC 3.0) SQLULEN * 值,這個值會指向緩衝區,以在呼叫 SQLFetchSQLFetchScroll 之後傳回所提取的資料列數; 受到大量作業所影響的資料列數目 ,這些 作業是由 SQL_REFRESH 的作業自變數,或由 SQLBulkOperations 執行的大量作業所影響的資料列數目所影響。 此數目包含錯誤的資料列。

如需詳細資訊,請參閱 提取的資料列數目和狀態

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

如果對 SQLFetchSQLFetchScroll 的呼叫,而該屬性是填入這個屬性所指向的緩衝區,就不會傳回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO,而是未定義緩衝區的內容。
SQL_ATTR_SIMULATE_CURSOR (ODBC 2.0) SQLULEN 值,這個值會指定模擬定位 update 和 delete 語句的驅動程式是否保證這類語句只會影響一個單一資料列。

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

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

SQL_SC_NON_UNIQUE = 驅動程式不保證模擬定位的 update 或 delete 語句只會影響一個資料列;這是應用程式的責任。 如果語句影響一個以上的資料列, SQLExecuteSQLExecDirectSQLSetPos 會傳回 SQLSTATE 01001 (資料指標作業衝突) 。

SQL_SC_TRY_UNIQUE = 驅動程式會嘗試保證模擬定位的 update 或 delete 語句只會影響一個資料列。 驅動程式一律會執行這類語句,即使它們可能會影響一個以上的資料列,例如當沒有唯一索引鍵時。 如果語句影響一個以上的資料列, SQLExecuteSQLExecDirectSQLSetPos 會傳回 SQLSTATE 01001 (資料指標作業衝突) 。

SQL_SC_UNIQUE = 驅動程式保證模擬定位的 update 或 delete 語句只會影響一個資料列。 如果驅動程式無法針對指定的語句保證這一點, SQLExecDirectSQLPrepare 會傳回錯誤。

如果資料來源為定位的 update 和 delete 語句提供原生 SQL 支援,而且驅動程式未模擬資料指標,則在要求 SQL_SIMULATE_CURSOR 的 SQL_SC_UNIQUE 時,就會傳回 SQL_SUCCESS。 如果要求 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。

如需詳細資訊,請參閱 模擬定位的 Update 和 Delete 語句
SQL_ATTR_USE_BOOKMARKS (ODBC 2.0) SQLULEN 值,這個值會指定應用程式是否會使用具有資料指標的書簽:

SQL_UB_OFF = Off (預設)

SQL_UB_VARIABLE = 應用程式會使用具有資料指標的書簽,而驅動程式會在支援時提供可變長度的書簽。 ODBC 3.x 中的 SQL_UB_FIXED 已被 取代。 即使 使用 odbc 2.x 驅動程式 (只支援4個位元組的固定長度書簽) ,odbc 3.x 應用程式 還是應該一律使用可變長度的書簽。 這是因為固定長度的書簽只是可變長度書簽的特殊案例。 使用 ODBC 2.x 驅動程式時, 驅動程式管理員 會將 SQL_UB_VARIABLE 對應到 SQL_UB_FIXED。

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

如需詳細資訊,請參閱抓取 書簽

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

請參閱資料取向的系結和資料取向的系結。

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

另請參閱

ODBC API 參考
ODBC 標頭檔