sp_OAMethod (Transact-SQL)

呼叫 OLE 物件的方法。

Transact-SQL 語法慣例

語法

sp_OAMethod objecttoken , methodname
    [ , returnvalue OUTPUT ] 
    [ , [ @parametername = ] parameter [ OUTPUT ] [ ...n ] ] 

引數

• objecttoken
  這是先前利用 sp_OACreate 所建立之 OLE 物件的物件 Token。

• methodname
  這是要呼叫之 OLE 物件的方法名稱。

• returnvalue OUTPUT
  這是 OLE 物件的方法傳回值。如果指定的話，它必須是適當資料類型的本機變數。

  如果方法傳回單一值，請在 returnvalue 中指定一個本機變數，這會在本機變數中傳回方法傳回值，或不指定 returnvalue，這會將方法傳回值當作單一資料行、單一資料列結果集來傳回用戶端。

  如果方法傳回值是一個 OLE 物件，returnvalue 就必須是 int 資料類型的本機變數。物件 Token 儲存在本機變數中，這個物件 Token 可以搭配其他 OLE Automation 預存程序來使用。

  當方法傳回值是陣列時，如果指定 returnvalue，它會設為 NULL。

  當發生下列中的任何狀況時，都會產生錯誤：

  • 指定了 returnvalue，但方法並沒有傳回值。
  • 方法傳回含有超出二維的陣列。
  • 方法在輸出參數中傳回陣列。

• [ @parametername**=** ] parameter[ OUTPUT ]
  這是一個方法參數。如果指定的話，parameter 必須是適當資料類型的值。

  若要取得輸出參數的傳回值，parameter 必須是適當資料類型的本機變數，您必須指定 OUTPUT。如果指定常數參數，或未指定 OUTPUT，便會忽略輸出參數的任何傳回值。

  如果指定的話，parametername 必須是 Microsoft Visual Basic 具名參數的名稱。請注意，@parametername 不是 Transact-SQL 本機變數。parametername 移除了 @ 記號 (@)，它會以參數名稱的方式傳給 OLE 物件。您必須在指定好所有位置性參數之後，指定所有具名參數。

• n
  這是一個預留位置，表示可以指定多個參數。

  附註：
  @parametername 可以是具名參數，因為它是指定方法的一部份，且會傳遞給物件。這個預存程序的其他參數是依照位置來指定，而不是名稱。

傳回碼值

0 (成功) 或非零數字 (失敗)，這個數字是 OLE Automation 物件所傳回之 HRESULT 的整數值。

如需有關 HRESULT 傳回碼的詳細資訊，請參閱＜OLE Automation 傳回碼與錯誤資訊＞。

結果集

如果方法傳回值是含有一或兩個維度的陣列，就會將陣列傳回用戶端作為結果集：

• 一維陣列會以單一資料列結果集的方式傳回給用戶端，這個資料列中有多個資料行，資料行數目等於陣列的元素數目。換言之，這個陣列是以 (columns) 的方式傳回。
• 二維陣列會以多資料列結果集的方式傳回給用戶端，這個資料列中有多個資料行，資料行數目等於陣列的元素數目。資料行數目等於陣列第一維的元素數目，資料列數目等於陣列第二維的元素數目。換言之，這個陣列是以 (columns, rows) 的方式傳回。

當屬性傳回值或方法傳回值是陣列時，sp_OAGetProperty 或 sp_OAMethod 會將結果集傳回給用戶端。(方法輸出參數不能是陣列。)這些程序會掃描陣列中的所有資料值來判斷適當的 SQL Server 資料類型，以及結果集中每個資料行所用的資料長度。對於特定資料行，這些程序會利用資料類型和長度來表示這個資料行中的所有資料值。

當資料行中的所有資料值都共用相同的資料類型時，整個資料行都會使用這個資料類型。當資料行中的資料值是不同資料類型時，便會根據下表來選擇整個資料行的資料類型。

	int	float	money	datetime	varchar	nvarchar
int	int	float	money	varchar	varchar	nvarchar
float	float	float	money	varchar	varchar	nvarchar
money	money	money	money	varchar	varchar	nvarchar
datetime	varchar	varchar	varchar	datetime	varchar	nvarchar
varchar	varchar	varchar	varchar	varchar	varchar	nvarchar
nvarchar	nvarchar	nvarchar	nvarchar	nvarchar	nvarchar	nvarchar

備註

您也可以利用 sp_OAMethod 來取得屬性值。

權限

需要系統管理員 (sysadmin) 固定伺服器角色中的成員資格。

範例

A. 呼叫方法

下列範例會呼叫先前建立的 SQLServer 物件之 Connect 方法。

EXEC @hr = sp_OAMethod @object, 'Connect', NULL, 'my_server',
    'my_login', 'my_password'
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END

B. 取得屬性

下列範例會取得 (先前建立的 SQLServer 物件的) HostName 屬性，將它儲存在本機變數中。

DECLARE @property varchar(255)
EXEC @hr = sp_OAMethod @object, 'HostName', @property OUT
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END
PRINT @property

請參閱

參考

OLE Automation 預存程序 (Transact-SQL)

其他資源

OLE Automation 範例指令碼

說明及資訊

取得 SQL Server 2005 協助