sp_OAMethod (Transact-SQL)

發行項
12/22/2023

適用於：SQL Server

呼叫 OLE 物件的方法。

語法

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

引數

objecttoken
這是先前使用 sp_OACreate 建立之 OLE 對象的物件標記。

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

returnvalueOUTPUT
這是 OLE 物件的方法傳回值。如果指定，它必須是適當數據類型的局部變數。

如果方法傳回單一值，請為 returnvalue 指定局部變數，以傳回局部變數中的方法傳回值，或不指定 returnvalue，以單一數據行單一數據列結果集的形式將方法傳回值傳回給用戶端。

如果方法傳回值是 OLE 物件， returnvalue 必須是數據類型 int 的局部變數。物件令牌會儲存在局部變數中，而且此物件令牌可以與其他 OLE Automation 預存程式搭配使用。

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

發生下列任一項時，就會引發錯誤：

會指定 returnvalue ，但方法不會傳回值。
方法會傳回具有兩個以上維度的陣列。
方法會以輸出參數的形式傳回數位。

[ _@parametername = ] parameter[ OUTPUT ] 這是方法參數。如果指定，參數必須是適當數據類型的值。

若要取得輸出參數的傳回值，參數必須是適當數據類型的局部變數，而且 必須指定 OUTPUT 。如果指定常數參數，或 未指定 OUTPUT ，則會忽略輸出參數的任何傳回值。

如果指定， parametername 必須是 Microsoft Visual Basic 具名參數的名稱。請注意， @_parametername_is不是 Transact-SQL 局部變數。拿掉 at sign （@），並將 parametername 傳遞至 OLE 物件做為參數名稱。所有具名參數都必須在指定所有位置參數之後指定。

n
這是一個佔位元元，表示可以指定多個參數。

注意

@parametername可以是具名參數，因為它是指定方法的一部分，而且會傳遞至物件。這個預存程式的其他參數是由位置指定，而不是名稱。

傳回碼值

0 （success）或非零數位（failure），這是 OLE Automation 物件所傳回之 HRESULT 的整數值。

如需 HRESULT 傳回碼、 OLE 自動化傳回碼和錯誤資訊的詳細資訊。

結果集

如果方法傳回值是具有一或兩個維度的陣列，則會以結果集的形式傳回數位給用戶端：

一維陣列會以單一資料列結果集的方式傳回給用戶端，這個資料列中有多個資料行，資料行數目等於陣列的元素數目。換句話說，陣列會以（columns）的形式傳回。
二維陣列會以多資料列結果集的方式傳回給用戶端，這個資料列中有多個資料行，資料行數目等於陣列的元素數目。資料行數目等於陣列第一維的元素數目，資料列數目等於陣列第二維的元素數目。換句話說，陣列會傳回為（資料行、數據列）。

當屬性傳回值或方法傳回值是陣列時， 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 來取得屬性值。

權限

需要系統管理員固定伺服器角色的成員資格，或直接在此預存程式上執行許可權。 Ole Automation Procedures 必須啟用組態，才能使用任何與 OLE Automation 相關的系統程式。

範例

A. 呼叫方法

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

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

B. 取得屬性

下列範例會取得 HostName 屬性（先前建立 的 SQLServer 物件），並將其儲存在局部變數中。

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 自動化範例腳本