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)