sp_OAGetProperty (Transact-SQL)

OLE オブジェクトのプロパティ値を取得します。

Transact-SQL 構文表記規則

構文

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

引数

• objecttoken
  以前に sp_OACreate で作成した OLE オブジェクトのオブジェクト トークンです。

• propertyname
  返される OLE オブジェクトのプロパティ名です。

• propertyvalueOUTPUT
  返されるプロパティ値です。指定する場合は、適切なデータ型のローカル変数でなければなりません。

  プロパティが OLE オブジェクトを返す場合は、propertyvalue は int 型のローカル変数であることが必要です。オブジェクト トークンがローカル変数に格納され、このオブジェクト トークンを他の OLE オートメーション ストアド プロシージャで使用できます。

  プロパティが単一の値を返す場合、propertyvalue にローカル変数を指定すると、プロパティ値がローカル変数で返されます。propertyvalue を指定しないと、プロパティ値が、単一列、単一行の結果セットとしてクライアントに返されます。

  プロパティが配列を返すときに、propertyvalue を指定する場合は、NULL を設定します。

  propertyvalue が指定され、プロパティが値を返さない場合は、エラーが発生します。プロパティが 3 次元以上の配列を返す場合は、エラーが発生します。

• index
  インデックス パラメータです。指定する場合、index は適切なデータ型の値にする必要があります。

  プロパティの一部はパラメータを持っています。このようなプロパティをインデックス付きプロパティ、パラメータをインデックス パラメータと呼びます。1 つのプロパティが複数のインデックス パラメータを持つことができます。

  注
  このストアド プロシージャのパラメータは、名前ではなく位置で指定します。

戻り値

成功した場合は 0 を、失敗した場合は OLE オートメーションが返す HRESULT の 0 以外の整数値をそれぞれ返します。

HRESULT のリターン コードの詳細については、「OLE オートメーションのリターン コードとエラー情報」を参照してください。

結果セット

プロパティが 1 次元または 2 次元の配列を返す場合、配列は結果セットとしてクライアントに返されます。

• 1 次元の配列の場合は、配列内の要素数と同数の列を持つ 1 行の結果セットとしてクライアントに返されます。つまり、配列は列数として返されます。

• 2 次元の配列の場合は、最初の次元の配列の要素数を列数とし、2 番目の次元の配列の要素数を行数とした結果セットとしてクライアントに返します。つまり、配列を (列数,行数) として返します。

プロパティまたはメソッドの戻り値が配列である場合、sp_OAGetProperty または sp_OAMethod は結果セットをクライアントに返します。メソッドの出力パラメータを配列にすることはできません。これらのプロシージャは、配列内のすべてのデータ値をスキャンし、結果セットのそれぞれの列に使用する SQL Server の適切なデータ型とデータ長を決定します。これらのプロシージャは必要なデータ型とデータ長を使用して、特定の列内のすべてのデータ値を表現します。

列内のすべてのデータ値が同じデータ型を共有する場合は、そのデータ型を列全体で使用します。1 列のデータ値がそれぞれ異なるデータ型である場合、列全体に適用されるデータ型は次の表を基に選択されます。

	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. 結果セットを使用する

次の例では、以前に作成した SQLServer オブジェクトの HostName プロパティを取得し、結果セットとしてクライアントに返します。

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

関連項目

参照

OLE オートメーション ストアド プロシージャ (Transact-SQL)

OLE オートメーションのサンプル スクリプト