sp_cursoropen （Transact-SQL）

  • 發行項

適用於：SQL Server

開啟資料指標。 sp_cursoropen定義與資料指標和資料指標選項相關聯的 SQL 語句，然後填入資料指標。 sp_cursoropen相當於 Transact-SQL 語句DECLARE_CURSOR和 OPEN 的組合。 這個程式是藉由在表格式資料流程 （TDS） 封包中指定 ID =2 來叫用。

Transact-SQL 語法慣例

語法

  
sp_cursoropen cursor OUTPUT, stmt  
    [, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ]  
    [ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]

引數

cursor
SQL Server 產生的資料指標識別碼。 cursor 是一個 控制碼 值，必須在涉及資料指標的所有後續程式上提供，例如sp_cursorfetch。 cursor 是具有 int 傳回值的必要參數。

cursor 允許在單一資料庫連接上使用多個資料指標。

stmt
這是定義資料指標結果集的必要參數。 任何字串類型的任何有效查詢字串（語法和系結）都可以做為有效的 stmt 實數值型別。

scrollopt
捲動選項。 scrollopt 是選擇性參數，需要下列 其中一個 int 輸入值。

值 Description
0x0001 KEYSET
0x0002 DYNAMIC
0x0004 FORWARD_ONLY
0x0008 STATIC
0x10 FAST_FORWARD
0x1000 PARAMETERIZED_STMT
0x2000 AUTO_FETCH
0x4000 AUTO_CLOSE
0x8000 CHECK_ACCEPTED_TYPES
0x10000 KEYSET_ACCEPTABLE
0x20000 DYNAMIC_ACCEPTABLE
0x40000 FORWARD_ONLY_ACCEPTABLE
0x80000 STATIC_ACCEPTABLE
0x100000 FAST_FORWARD_ACCEPTABLE

由於要求的值不適合 stmt 所 定義的資料指標，因此此參數會同時做為輸入和輸出。 在這種情況下，SQL Server 會指派適當的值。

ccopt
並行控制選項。 ccopt 是選擇性參數，需要下列 其中一個 int 輸入值。

值 Description
0x0001 READ_ONLY
0x0002 SCROLL_LOCKS （先前稱為 LOCKCC）
0x0004 開放式 （先前稱為 OPTCC）
0x0008 開放式 （先前稱為 OPTCCVAL）
0x2000 ALLOW_DIRECT
0x4000 UPDT_IN_PLACE
0x8000 CHECK_ACCEPTED_OPTS
0x10000 READ_ONLY_ACCEPTABLE
0x20000 SCROLL_LOCKS_ACCEPTABLE
0x40000 OPTIMISTIC_ACCEPTABLE
0x80000 OPTIMISITC_ACCEPTABLE

如同 scrollopt ，SQL Server 可以覆寫所要求的 ccopt 值。

rowcount
要搭配AUTO_FETCH使用的擷取緩衝區資料列數目。 預設值為 20 個數據列。 當指派為輸入值與傳回值時，rowcount 的行為會有所不同。

作為輸入值 作為傳回值
指定 scrollopt 值時， AUTO_FETCH scrollopt 值 代表要放入提取緩衝區的資料列數目。

注意： > 當指定AUTO_FETCH時，0 是有效的值，但否則會忽略。		 表示結果集中的資料列數目，但指定 scrollopt AUTO_FETCH 值時 除外。

-

boundparam
表示使用其他參數。 boundparam 是選擇性參數，如果 scrollopt PARAMETERIZED_STMT 值設定為 ON，則應該指定此參數。

傳回碼值

如果沒有引發錯誤，sp_cursoropen會傳回下列其中一個值。

0
程式已順利執行。

0x0001
執行期間發生錯誤（次要錯誤，不足以引發作業中的錯誤）。

0x0002
非同步作業正在進行中。

0x0002
FETCH 作業正在進行中。

A
此資料指標已由 SQL Server 解除配置，且無法使用。

引發錯誤時，傳回值可能會不一致，且無法保證正確性。

當 rowcount 參數指定為傳回值時，會發生下列結果集。

-1
如果資料列數目未知或不適用，則傳回 。

-n
當非同步母體擴展生效時傳回。 表示指定 scrollopt AUTO_FETCH 值時 ，放入提取緩衝區的資料列數目。

如果 RPC 正在使用中，則傳回值如下所示。

0
程式成功。

1
程式失敗。

2
索引鍵集資料指標正以非同步方式產生。

16
快轉游標已自動關閉。

注意

如果sp_cursoropen程式執行成功，則會傳送具有 TDS 資料行格式資訊（0xa0 0xa1 & 訊息）的 RPC 傳回參數和結果集。 如果失敗，就會傳送一或多個 TDS 錯誤訊息。 不論是哪一種情況，都不會傳回任何資料列資料，而完成 的 訊息計數將會是零。 如果您使用 7.0 之前的 SQL Server 版本，0xa0會傳回0xa1（SELECT 語句的標準）以及0xa5和0xa4權杖資料流程。 如果您使用 SQL Server 7.0，則會傳回0x81（SELECT 語句的標準），以及0xa5和0xa4權杖資料流程。

備註

stmt 參數

如果 stmt 指定預存程式的執行，則輸入參數可以定義為 stmt 字串的 一部分常數，或指定為 boundparam 引數。 宣告的變數可以透過這種方式傳遞為系結參數。

stmt 參數允許的內容 取決於 ccopt ALLOW_DIRECT傳回值是否已 由 OR 連結至 ccopt 值的其餘部分 ，也就是：

  • 如果未指定ALLOW_DIRECT，則必須使用呼叫包含單一 SELECT 語句之預存程式的 Transact-SQL SELECT 或 EXECUTE 語句。 此外，SELECT 語句必須限定為數據指標;也就是說，它不能包含 SELECT INTO 或 FOR BROWSE 關鍵字。

  • 如果指定了ALLOW_DIRECT，這可能會導致一或多個 Transact-SQL 語句，包括接著使用多個語句執行其他預存程式。 非 SELECT 語句或任何包含 SELECT INTO 或 FOR BROWSE 關鍵字的 SELECT 語句只會執行，而且不會產生資料指標的建立。 在多個語句批次中包含的任何 SELECT 語句也是如此。 如果 SELECT 語句包含只與資料指標相關的子句，則會忽略那些子句。 例如，當 ccopt 的值 0x2002時，這是要求：

    • 如果只有單一 SELECT 語句限定為數據指標，則具有捲動鎖定的資料指標，或

    • 如果有多個語句、單一非 SELECT 語句或不符合資料指標資格的 SELECT 語句，則為直接語句執行。

scrollopt 參數

前五 個 scrollopt 值（KEYSEY、DYNAMIC、FORWARD_ONLY、STATIC 和 FAST_FORWARD）互斥。

PARAMETERIZED_STMT和CHECK_ACCEPTED_TYPES可由 OR 連結到前五個值中的任何一個。

AUTO_FETCH和AUTO_CLOSE可以透過 OR 連結至FAST_FORWARD。

如果CHECK_ACCEPTED_TYPES為 ON，則最後五 個滾動軸 值中至少一個 （KEYSET_ACCEPTABLE , DYNAMIC_ACCEPTABLE、FORWARD_ONLY_ACCEPTABLE、STATIC_ACCEPTABLE 或 FAST_FORWARD_ACCEPTABLE） 也必須是 ON。

靜態資料指標一律會開啟為READ_ONLY。 這表示基礎資料表無法透過這個資料指標更新。

ccopt 參數

前四 個 ccopt 值（READ_ONLY、SCROLL_LOCKS和兩個 OPTIMISTIC 值）互斥。

注意

選擇前四 個 ccopt 值之一會決定資料指標是唯讀的，還是使用鎖定或開放式方法來防止遺失的更新。 如果未指定 ccopt 值，預設值為 OPTIMISTIC。

ALLOW_DIRECT和CHECK_ACCEPTED_TYPES可由 OR 連結到前四個值中的任何一個。

UPDT_IN_PLACE可由 OR 連結至READ_ONLY、SCROLL_LOCKS或任一開放式值。

如果CHECK_ACCEPTED_TYPES為 ON，則最後四 個 ccopt 值中至少一個 （READ_ONLY_ACCEPTABLE、 SCROLL_LOCKS_ACCEPTABLE和其中一個OPTIMISTIC_ACCEPTABLE值） 也必須是 ON。

定位的 UPDATE 和 DELETE 函式只能在擷取緩衝區內執行，而且只有在 ccopt 值等於 SCROLL_LOCKS 或 OPTIMISTIC 時才 執行。 如果SCROLL_LOCKS是指定的值，則保證作業會成功。 如果 OPTIMISTIC 是指定的值，則如果資料列自上次擷取後已變更，作業將會失敗。

此失敗的原因是當 OPTIMISTIC 是指定的值時，開放式貨幣控制函式會藉由比較 SQL Server 所決定的時間戳記或總和檢查碼值來執行。 如果其中任何一個資料列不相符，作業將會失敗。

將UPDT_IN_PLACE指定為傳回值會控管下列結果：

  • 如果在具有唯一索引的資料表上執行定點更新時未設定，資料指標會從其工作資料表中刪除資料列，並將它插入資料指標所使用之任何索引鍵資料行的結尾，藉此變更這些資料行。

  • 如果設定 ON，資料指標只會更新工作資料表原始資料列中的索引鍵資料行。

bound_param參數

指定PARAMETERIZED_STMT時，參數名稱應該是 paramdef ，根據程式碼中的錯誤訊息。 未指定PARAMETERIZED_STMT時，錯誤訊息中未指定任何名稱。

RPC 考慮

RPC RETURN_METADATA輸入旗標可以設定為 0x0001，要求 TDS 資料流程中傳回資料指標選取清單中繼資料。

範例

bound_param參數

第五個之後的任何參數會以輸入參數的形式傳遞至語句計畫。 第一個這類參數必須是格式如下的字串：

{ 區域變數名稱資料類型 }[,...n]

後續參數會用來傳遞值，以取代 語句中的區域變數名稱 。

另請參閱

sp_cursorfetch （Transact-SQL）
系統預存程序 (Transact-SQL)