sp_OAGetProperty (Transact-SQL)

適用対象: SQL Server

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

Transact-SQL 構文表記規則

構文

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

引数

objecttoken

sp_OACreateを使用して以前に作成された OLE オブジェクトのオブジェクト トークン。

propertyname

返す OLE オブジェクトのプロパティ名。

propertyvalue OUTPUT

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

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

プロパティが単一の値を返す場合は、次のいずれかを行います。

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

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

propertyvalueが指定されているが、プロパティが値を返さない場合は、エラーが発生します。 プロパティが 2 次元を超える配列を返す場合は、エラーが発生します。

インデックス

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

一部のプロパティにはパラメーターがあります。 これらのプロパティはインデックス付きプロパティと呼ばれ、パラメーターはインデックス パラメーターと呼ばれます。 プロパティには、複数のインデックス パラメーターを指定できます。

リターン コードの値

0 (成功) または 0 以外の数値 (失敗) は、OLE オートメーション オブジェクトによって返される HRESULT の整数値です。

HRESULT 戻りコードの詳細については、 OLE 自動化戻りコードとエラー情報を参照してください。

結果セット

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

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

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

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

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

解説

sp_OAMethodを使用してプロパティ値を取得することもできます。

アクセス許可

sysadmin固定サーバー ロールのメンバーシップが必要です。または、このストアド プロシージャに対して直接アクセス許可を実行します。 OLE オートメーションに関連するシステム プロシージャを使用するには、 Ole Automation Procedures サーバー構成オプションを有効にする必要があります。

例

A. ローカル変数を使用する

次の例では、(前に作成した SQLServer オブジェクトの) HostName プロパティを取得し、ローカル変数に格納します。

DECLARE @property VARCHAR(255);

EXEC @hr = sp_OAGetProperty @object,
    'HostName',
    @property OUTPUT;

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 オートメーションのサンプル スクリプト