sp_OAGetProperty (Transact-SQL)

取得 OLE 物件的屬性值。

Transact-SQL 語法慣例

語法

sp_OAGetProperty objecttoken , propertyname 
    [ , propertyvalue OUTPUT ]
    [ , index...] 

引數

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

• propertyname
  這是要傳回之 OLE 物件的屬性名稱。

• propertyvalueOUTPUT
  這是傳回的屬性值。如果指定的話，它必須是適當資料類型的本機變數。

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

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

  當屬性傳回陣列時，如果指定了 propertyvalue，它會設為 NULL。

  如果指定了 propertyvalue，但屬性未傳回值，便會發生錯誤。如果屬性傳回含有多於二個維度的陣列，就會發生錯誤。

• index
  這是一個索引參數。如果指定的話，index 必須是適當資料類型的值。

  部份屬性有參數。這些屬性稱為索引屬性，參數稱為索引參數。一個屬性可以有多個索引參數。

  附註：
  這個預存程序的參數是依照位置來指定，而不是名稱。

傳回碼值

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

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

結果集

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

• 一維陣列會以單一資料列結果集的方式傳回給用戶端，這個資料列中有多個資料行，資料行數目等於陣列的元素數目。換言之，會將陣列傳回作為資料行。
• 二維陣列會以多資料列結果集的方式傳回給用戶端，這個資料列中有多個資料行，資料行數目等於陣列的元素數目。資料行數目等於陣列第一維的元素數目，資料列數目等於陣列第二維的元素數目。換言之，這個陣列是以 (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 物件的) HostName 屬性，將它儲存在本機變數中。

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

B. 使用結果集

下列範例取得 HostName 屬性 (先前建立的 SQLServer 物件的屬性)，並將它傳回用戶端作為結果集。

EXEC @hr = sp_OAGetProperty @object, 'HostName'
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END

請參閱

參考

OLE Automation 預存程序 (Transact-SQL)

其他資源

OLE Automation 範例指令碼

說明及資訊

取得 SQL Server 2005 協助