| Oracle® COM Automation機能開発者ガイド 11g リリース2 (11.2) B58875-02 |
|
 前 |
 次 |
この章では、Oracle COM Automation機能のプログラム・インタフェースについて説明します。
この章の項目は次のとおりです。
Microsoft COM Automation機能ではCOM Automation機能データ型が使用され、Oracle COM Automation機能ではPL/SQLまたはJavaのデータ型が使用されるため、Oracle COM Automation機能では、受け取ったデータを変換してCOM Automation機能オブジェクトに渡す操作を行う必要があります。同様に、Oracle COM Automation機能ではCOM Automation機能オブジェクトから受け取ったデータを渡して変換する必要があります。
表3-1は、PL/SQLデータ型とCOM Automationデータ型の間のマッピングを示したものです。
このマニュアルでは、COM Automationデータ型がIN OUTパラメータまたはOUTパラメータとして使用される場合、先頭にpを付けて表記しています。先頭の文字がp以外のデータ型は、INパラメータです。
表3-1 PL/SQLデータ型からCOM Automationデータ型への変換
| PL/SQLデータ型 | COM Automationデータ型 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
注意: Oracleでは、CYおよびpCYの値を-9999999999.9999から9999999999.9999の範囲内に制限しています。 |
表3-2は、サポートされるCOM Automationデータ型およびJavaデータ型への関連マッピングを示したものです。
戻り値のみに適用されるvoidを除き、すべてのデータ型マッピングは、プロパティ、引数および戻り値に適用されます。
HRESULTエラー・コードは、Microsoft Windows APIにより提供されています。
HRESULTは、0x800nnnnnという形式の16進数のCOMエラー・コードです。ただし、-214nnnnnnnという10進数形式もあります。たとえば、COMオブジェクトの作成時に不正なオブジェクト名が渡されると、HRESULT値-2147221005(16進形式では0x800401f3)が返されます。
HRESULTリターン・コードの詳細は、Microsoft社のドキュメントを参照してください。
Java用のOracle COM Automationは、標準のJava例外メカニズムを使用します。具体的には、Java例外クラスoracle.win.com.COMExceptionが、COMエラーを表すために組み込まれています。
この例外は、エラーの発生時にJavaのAutomationクラスでスローされます。
この例外で提供されるエラー情報は、PL/SQL APIのGetLastErrorファンクションで提供される情報と同様です。
|
注意: HRESULTデータ・メンバーは、PL/SQLファンクションから返されるHRESULTの値と同じ意味を持ちます。 |
excepInfoデータ・メンバーで示されるCOMエラーがDISP_E_EXCEPTIONの場合、COMExceptionはsource、description、helpfileおよびhelpidの各データ・メンバーを使用します。それ以外の場合、データ・メンバーは無効です。
COMExceptionは、COMエラーを表すエラー・メッセージをerrmsgデータ・メンバーに書き込みます。
表3-3は、COMExceptionデータ・メンバーと、その説明を示したものです。
表3-3 COMExceptionデータ・メンバー
| メンバー | 説明 |
|---|---|
|
|
Windows APIにより定義されている |
|
|
適切な言語での |
|
|
例外の |
|
|
エラーの説明です。 |
|
|
エラーの詳細が含まれる |
|
|
|
|
|
HRESULTがtrueを返す場合、 |
コード・サンプル
この例では、COMException例外を示します。
try
{
// Some code that might throw a COMException exception.
}
catch(COMException e)
{
System.out.println(e.toString());
if(e.excepInfo)
{
System.out.println(e.source);
System.out.println(e.description);
System.out.println(e.helpfile);
System.out.println(e.helpid);
}
}
この項では、Oracle COM Automation機能を使用したソリューションの開発に必要な情報および一般的な開発手順について説明します。
使用するCOMオブジェクトに関して次の情報を確認します。
COMオブジェクトのプログラムIDを決定する必要があります。プログラムID(progID)は、COMオブジェクトを一意に識別する16進数のグローバル一意識別子(GUID)にマップされる説明的な文字列です。
次の文字列は、progIDの例です。
Excel.Worksheet.1
progIDは、COMオブジェクトをインスタンス化するAPIで使用します。
COMオブジェクトのIDispatchインタフェースを通じて公開されるプロパティとメソッドの種類を知る必要があります。通常、オブジェクトのプロパティの名前とデータ型、およびオブジェクトのメソッドのプロトタイプが記述されたドキュメントがISVから提供されます。プロパティはxposやyposのような説明的な文字列によって参照されます。プロパティにはINTやBSTRなど、任意の標準COM Automationデータ型を使用できます。APIのGetPropertyとSetPropertyは、プロパティ名と適切なデータ型の変数を受け取ります。メソッドはInsertChartのような説明的な文字列によって参照されます。メソッドは、様々な種類のCOM Automationデータ型のパラメータ・セットを受け取り、COM Automationデータ型を返します。
次に示すのは、COMインタフェース定義言語(IDL)の文法で記述された、COM Automationメソッドのプロトタイプの例です。
[id(0x6003000)]
long Post([in, out] long* lngAccountNo,
[in, out] long* lngAmount,
[in, out] BSTR* strResult);
インタフェースは、オブジェクト・メソッドおよびプロパティを定義します。COM IDLを使用し、COMオブジェクトに定義されているインタフェースを指定します。
Microsoft社は、ローカル・システム上のCOMオブジェクトのプロパティおよびメソッドの表示用に、Microsoft Visual StudioのOLE-COMオブジェクト ビューアというツールを提供しています。このツールを使用することで、各COMオブジェクトが提供するプロパティとメソッドをすばやく、かつ容易に判断できます。図3-1の例を参照してください。
Oracle COM Automation機能の代表的な使用例では、JavaクラスまたはPL/SQLブロックを設計し、COMオブジェクトを作成および操作します。クラスまたはコード・ブロックは、次の手順を実行します。
COMオブジェクトを次のように作成します。
PL/SQLでは、CreateObjectを使用します。
Javaでは、コンストラクタまたはCreateメソッドを使用します。
次のAPIをコールしてCOMオブジェクトを操作します。
GetPropertyをコールして、プロパティ値を取得します。
SetPropertyをコールして、プロパティ値を新しい値に設定します。
Invokeをコールして、メソッドをコールします。
Invokeコールを準備するには、InitArgとSetArgを使用して、COM Automationメソッドに送られる引数をパッケージ化します。
PL/SQLのGetLastErrorをコールして、最新のエラー情報を取得します。
PL/SQLのDestroyObjectまたはJavaのDestroyを使用してオブジェクトを破棄します。
この項では、Oracle COM Automation機能で使用可能なAPIをリストし、説明します。
この項では、COM Automationインタフェースを使用してCOMオブジェクトを操作するためのPL/SQL APIについて説明します。これらのPL/SQLストアド・プロシージャはそれぞれORDCOMパッケージに含まれています。
このAPIは、COM Automationサーバー内のCOMオブジェクトをインスタンス化します。
構文
FUNCTION CreateObject(progid VARCHAR2, reserved BINARY_INTEGER, servername VARCHAR2, objecttoken OUT BINARY_INTEGER) RETURN BINARY_INTEGER;
備考
作成されたCOM Automationオブジェクトは、対応するDestroyObjectのコールによって解放されます。このコールにより、Oracle COM Automation機能内でのオブジェクトの内部表現が破棄され、オブジェクトに関連付けられたすべてのインタフェースが解放されます。
このファンクションは、成功のときは0を返し、エラーが発生したときは0以外のHRESULTを返します。
コード・サンプル
HRESULT BINARY_INTEGER;
applicationToken BINARY_INTEGER:=-1;
HRESULT :=ORDCOM.CreateObject('Excel.Application', 0, '', applicationToken);
IF (HRESULT!=0) THEN
dbms_output.put_line(HRESULT);
END IF;
このAPIは、作成されたCOM Automationオブジェクトを破棄します。
構文
FUNCTION DestroyObject(objecttoken BINARY_INTEGER) RETURN BINARY_INTEGER;
| パラメータ | 説明 |
|---|---|
objecttoken |
事前にCreateObjectによって作成されたCOM Automationオブジェクトのオブジェクト・トークン。 |
備考
DestroyObjectをコールすると、Oracle COM Automation機能内でのオブジェクトの内部表現が破棄され、オブジェクトに関連付けられたすべてのインタフェースが解放されます。
このファンクションは、成功のときは0を返し、エラーが発生したときは0以外のHRESULTを返します。
コード・サンプル
HRESULT BINARY_INTEGER; applicationToken BINARY_INTEGER:=-1; /* Assume applicationToken is initialized. */ HRESULT:=ORDCOM.DestroyObject(applicationToken); IF (HRESULT!=0) THEN dbms_output.put_line(HRESULT);
このAPIは、最後に発生したエラーについてのCOM Automationエラー情報を取得します。
構文
FUNCTION GetLastError(source OUT VARCHAR2, description OUT VARCHAR2, helpfile OUT VARCHAR2, helpid OUT BINARY_INTEGER) RETURN BINARY_INTEGER;
| パラメータ | 説明 |
|---|---|
source |
エラー情報のソース。指定する場合、この値はCHAR型またはVARCHAR型のローカル変数である必要があります。戻り値は必要に応じて、ローカル変数として適切な値になるよう切り捨てられます。 |
description |
エラーの説明。指定する場合、この値はCHAR型またはVARCHAR型のローカル変数である必要があります。戻り値は必要に応じて、ローカル変数として適切な値になるよう切り捨てられます。 |
helpfile |
COM Automationオブジェクトについてのヘルプ・ファイル。指定する場合、この値はCHAR型またはVARCHAR型のローカル変数である必要があります。戻り値は必要に応じて、ローカル変数として適切な値になるよう切り捨てられます。 |
helpid |
ヘルプ・ファイルのコンテキストID。指定する場合、この値はINT型のローカル変数である必要があります。 |
備考
(GetLastErrorを除く)Oracle COM Automation機能 APIコールごとにエラー情報がリセットされるため、GetLastErrorでは、最新のOracle COM Automation機能 APIコールに対するエラー情報のみが取得されます。GetLastErrorでは最後のエラー情報がリセットされないため、同じエラー情報が取得するために何度もコールできます。
このファンクションは、成功のときは0を返し、エラーが発生したときは0以外のHRESULTを返します。
このファンクションによって返される可能性のあるエラーの種類については、「Microsoft COM Automationのエラー」を参照してください。
コード・サンプル
HRESULT BINARY_INTEGER;
applicationToken BINARY_INTEGER:=-1;
error_src VARCHAR2(255);
error_description VARCHAR2(255);
error_helpfile VARCHAR2(255);
error_helpID BINARY_INTEGER;
HRESULT:=ORDCOM.CreateObject('Excel.Application', 0, '', applicationToken);
IF (HRESULT!=0) THEN
ORDCOM.GetLastError(error_src, error_description, error_helpfile,
error_helpID);
dbms_output.put_line(error_src);
dbms_output.put_line(error_description);
dbms_output.put_line(error_helpfile);
END IF;
このAPIは、COM Automationオブジェクトのプロパティ値を返します。
構文
FUNCTION GetProperty(objecttoken BINARY_INTEGER, propertyname VARCHAR2, argcount BINARY_INTEGER,
propertyvalue OUT any_PL/SQL_data type) RETURN BINARY_INTEGER;
| パラメータ | 説明 |
|---|---|
objecttoken |
事前にCreateObjectによって作成されたCOMオブジェクトのオブジェクト・トークン。 |
propertyname |
返されるCOMオブジェクトのプロパティ名。 |
argcount |
プロパティ配列のインデックス。プロパティが配列でない場合、この値には0を指定する必要があります。 |
propertyvalue |
返されるプロパティ値。返されるプロパティの型は、返されるCOM Automationのデータ型によって異なります。COM AutomationプロパティのCOM Automationデータ型に対応するPL/SQLデータ型を渡す必要があります。そのようにしないと、COM Automation機能によってCOM Automation機能データ型が適切に変換されません。 |
any_PL/SQL_data type |
COM Automation機能でサポートされる任意のデータ型。 |
備考
プロパティがCOMオブジェクトを返す場合、propertyvalueパラメータにデータ型BINARY_INTEGERのローカル変数を指定する必要があります。オブジェクト・トークンはローカル変数に格納され、このオブジェクト・トークンは他のCOM Automationストアド・プロシージャとともに使用できます。
プロパティが配列を返すとき、propertyvalueを指定するとその値はNULLに設定されます。
このファンクションは、成功のときは0を返し、エラーが発生したときは0以外のHRESULTを返します。
コード・サンプル
/* * This is an excerpt from a Microsoft Excel application. */ HRESULT BINARY_INTEGER; ChartObject BINARY_INTEGER := -1; ChartToken BINARY_INTEGER := -1; /* Assume ChartObject is initialized. */ HRESULT := ORDCOM.GetProperty(ChartObject, 'Chart', 0, ChartToken); IF (HRESULT!=0) THEN dbms_output.put_line(HRESULT); END IF;
このAPIは、COM Automationオブジェクトのプロパティを新しい値に設定します。
構文
FUNCTION SetProperty(objecttoken BINARY_INTEGER, propertyname VARCHAR2, newvalue any_PL/SQL_data type, data type VARCHAR2) RETURN BINARY_INTEGER;
| パラメータ | 説明 |
|---|---|
objecttoken |
事前にCreateObjectによって作成されたCOM Automationオブジェクトのオブジェクト・トークン。 |
propertyname |
新しい値を設定するCOMオブジェクトのプロパティ名。 |
newvalue |
プロパティの新しい値。この値は適切なデータ型の値である必要があります。 |
data type |
渡される値の、明示的に指定されるデータ型。使用可能なデータ型は、次のとおりです。
|
any_PL/SQL_data type |
COM Automation機能でサポートされる任意のデータ型。 |
備考
このファンクションは、成功のときは0を返し、エラーが発生したときは0以外のHRESULTを返します。
コード・サンプル
/* * This is an excerpt from a Microsoft Excel application. */ HRESULT BINARY_INTEGER; RangeToken BINARY_INTEGER := -1; /* Assume RangeToken is initialized. */ HRESULT := ORDCOM.SetProperty(RangeToken, 'Value', 'EmpNo', 'BSTR'); IF (HRESULT!=0) THEN dbms_output.put_line(HRESULT); END IF;
このAPIは、Invokeコールに渡されるパラメータ・セットを初期化します。
構文
PROCEDURE InitArg();
備考
InitArgのコールにより、パラメータ・セットが初期化されます。InitArgのコール後、SetArgをコールすることにより、最初のパラメータが指定の値に設定されます。SetArgの2回目のコールでは、パラメータ・リストの2番目のパラメータが設定されます。以後のコールにより、パラメータ・リストのn番目のパラメータが設定されます(nは、InitArgのコール後にSetArgがコールされた回数です)。InitArgを再度コールすると、引数リストがリセットされ、SetArgをコールすると、最初のパラメータが再度設定されます。
コード・サンプル
「Invoke」の項を参照してください。
InitOutArgは、GetArgを使用してOUTおよびIN OUTパラメータの値を取得する準備として、COMメソッドがコールされた後にコールする必要があります。InitOutArgのコール後、GetArgの最初のコールで最初のOUTパラメータまたはIN OUTパラメータの値が取得され、2回目のGetArgコールで2番目のOUTパラメータまたはIN OUTパラメータが取得されます(以降も同様に取得されます)。InitOutArgを再度コールすると、このプロセスが再度開始されます。
構文
PROCEDURE InitOutArg();
備考
INパラメータおよびOUTパラメータの詳細は、「SetArg」のSetArgデータ型に関する記載を参照してください。
コード・サンプル
「Invoke」の項を参照してください。
COMメソッドがコールされた後にOUTパラメータおよびIN OUTパラメータの引数を取得します。
構文
PROCEDURE GetArg(data OUT any_PL/SQL_data type, type VARCHAR2);
| パラメータ | 説明 |
|---|---|
data |
COMメソッドがコールされた後のOUTパラメータまたはIN OUTパラメータの値。 |
type |
パラメータのCOM Automationデータ型。 |
使用可能なデータ型は、次のとおりです。
|
|
any_PL/SQL_data type |
COM Automation機能でサポートされる任意のデータ型。 |
備考
INパラメータおよびOUTパラメータの詳細は、「SetArg」のSetArgデータ型に関する記載を参照してください。
コード・サンプル
「Invoke」の項を参照してください。
このAPIを使用して、Invokeを次回コールするためのパラメータ・リストを構成します。
SetArgは、渡されるパラメータの値を設定します。
構文
PROCEDURE SetArg(paramvalue any_PL/SQL_data type, data type VARCHAR2);
| パラメータ | 説明 |
|---|---|
paramvalue |
Invokeコールに渡されるパラメータの値。設定されるパラメータは、パラメータ・リスト中のn番目のパラメータです(nは、InitArgのコール後にSetArgがコールされた回数です)。 |
data type |
明示的に指定されるパラメータのデータ型。
先頭の文字が |
先頭の文字がp以外のデータ型は、INパラメータです。使用可能なデータ型は、次のとおりです。
|
|
|
|
|
|
|
|
any_PL/SQL_data type |
COM Automation機能でサポートされる任意のデータ型。 |
備考
各SetArgプロシージャによってn番目のパラメータ値が設定されます。InitArgのコールにより、パラメータ・セットが初期化されます。InitArgのコール後、SetArgをコールすることにより、最初のパラメータが指定の値に設定されます。SetArgの2回目のコールでは、パラメータ・リストの2番目のパラメータが設定されます。以後のコールにより、パラメータ・リストのn番目のパラメータが設定されます(nは、InitArgのコール後にSetArgがコールされた回数です)。InitArgを再度コールすると、引数リストがリセットされ、SetArgをコールすると、最初のパラメータが再度設定されます。
先頭の文字がp以外のデータ型は、INパラメータです。先頭の文字がpのデータ型は、IN OUTパラメータまたはOUTパラメータです。
コード・サンプル
「Invoke」の項を参照してください。
このAPIは、COM Automationオブジェクトのメソッドをコールします。このファンクションでは、COM Automationメソッドへの入力値として、InitArgおよびSetArgのコールによって事前に作成されたパラメータ・リストが使用されます。
構文
FUNCTION Invoke(objecttoken BINARY_INTEGER, methodname VARCHAR2, argcount BINARY_INTEGER,
returnvalue OUT any_PL/SQL_data type) RETURN BINARY_INTEGER;
| パラメータ | 説明 |
|---|---|
objecttoken |
事前にCreateObjectによって作成されたCOM Automationオブジェクトのオブジェクト・トークン。 |
methodname |
コールするCOM Automationオブジェクトのメソッド名。 |
argcount |
COM Automationオブジェクトのメソッドに渡される引数の数。 |
returnvalue |
COM Automationオブジェクトのメソッドの戻り値。指定される場合、この値は適切なデータ型のローカル変数である必要があります。 |
any_PL/SQL_data type |
COM Automation機能でサポートされる任意のデータ型。 |
備考
ファンクションの戻り値がCOMオブジェクトである場合、開発者は、returnvalueパラメータに対してBINARY_INTEGERデータ型のローカル変数を指定する必要があります。オブジェクト・トークンはローカル変数に格納され、このオブジェクト・トークンは、他のOracle COM Automation機能 APIで使用できます。
このファンクションは、成功のときは0を返し、エラーが発生したときは0以外のHRESULTを返します。
コード・サンプル
/* * Following is the IDL definition of the COM Automation method * being called: * * HRESULT TestOutArg([in, out] short *x1, * [in] short x2, * [out] short *x3, * [out, retval] short *x4); */ HRESULT BINARY_INTEGER := -1; applicationToken BINARY_INTEGER := -1; x1 DOUBLE PRECISION := 12; x2 DOUBLE PRECISION := 7; x3 DOUBLE PRECISION := 0; x4 DOUBLE PRECISION := 0; /* Assume applicationToken is initialized. */ ORDCOM.InitArg(); ORDCOM.SetArg(x1, 'pI2'); ORDCOM.SetArg(x2, 'I2'); ORDCOM.SetArg(x3, 'pI2'); HRESULT := ORDCOM.Invoke(applicationToken, 'TestOutArg', 3, x4); IF (HRESULT!=0) THEN dbms_output.put_line(HRESULT); END IF; ORDCOM.InitOutArg(); ORDCOM.GetArg(x1, 'pI2'); ORDCOM.GetArg(x3, 'pI2');
この項では、COM Automationインタフェースを使用してCOMオブジェクトを操作するためのJava APIについて説明します。これらのAPIは、JavaのAutomationクラスおよびCurrencyクラスにあります。
JavaのAutomationクラスを使用し、COM AutomationをサポートするCOMオブジェクトにアクセスできます。このJavaクラスでは、COMオブジェクトを作成し、COMオブジェクトのIDispatchインタフェースへのポインタを取得できます。さらに、COMオブジェクトに対してプロパティを取得および設定できる他、COMオブジェクトに対して(引数あり、または引数なしで)メソッドをコールできます。このクラスは、COMオブジェクトのラッパーを提供するため、COMオブジェクトまたはそのIDispatchインタフェースには直接アクセスしません。
JavaクラスCurrencyは、COM Automationデータ型のCURRENCYに相当します。CURRENCYは8バイトの数値で、最後の4桁は値の小数部を表します。たとえば、12345という数値は、実際には1.2345という値を表します。CURRENCYの範囲は、(+/-)922337203685477.5807です。
COMオブジェクト参照カウンティング
COMオブジェクト・インタフェース参照カウンティングは内部的に処理され、IUnknown::AddRef()およびIUnknown::Release()は公開されません。ユーザーは、COMオブジェクト・インタフェースを明示的にアドレス指定できません。特定のCOMオブジェクトの存続期間は、関連するJavaコンストラクタまたはCreateメソッドがコールされたときに開始し、対応するDestroyメソッドがコールされたときに解放されます。
コンストラクタおよびデストラクタ
デフォルトのコンストラクタはCOMオブジェクトを作成しません。COMオブジェクトを作成するには、2つの方法があります。
デフォルトのコンストラクタを使用してJavaオブジェクトをインスタンス化し、Createメソッドの1つをコールします。使用するCreateメソッドは、サーバー名を指定するかどうかによって決まります。後でDestroyメソッドをコールし、COMオブジェクトを解放する必要があります。
Createメソッドはいつでもコールできますが、COMオブジェクトが以前にデフォルト以外のコンストラクタの1つまたはCreateメソッドを介して作成された場合は、最初にDestroyメソッドをコールする必要があります。
デフォルト以外のコンストラクタを使用してJavaオブジェクトをインスタンス化します。使用するデフォルト以外のコンストラクタは、サーバー名を指定するかどうかによって決まります。後でDestroyメソッドをコールし、COMオブジェクトを解放する必要があります。
COMオブジェクト・エラーの処理
すべてのCOMエラーはJavaの例外にマップされます。ユーザーは、Javaの例外処理メカニズムによりCOMオブジェクト・エラーを捕捉できます。
|
注意: Java用のOracle COM Automation機能では、インプロセスCOM Automation機能サーバーを使用できません。開発者は、dllhostを使用し、インプロセス・サーバーをサポートできます。 |
このAPIは、COMオブジェクトを作成します。
構文
public Automation()
public Automation(String progID)
public Automation(String progID, String serverName)
備考
デフォルトのコンストラクタpublic Automation()は何も行いません。このコンストラクタはCreateメソッドで使用されます。
progIDパラメータのみを受け取るコンストラクタを使用すると、Oracle COM Automation機能はCOMオブジェクトの場所についてレジストリをチェックします。レジストリ情報は、COMオブジェクトがローカルかリモートかを示します。
デフォルト以外のコンストラクタを使用して作成されたCOM Automationオブジェクトは、対応するDestroyのコールによって解放されます。このコールにより、Oracle COM Automation機能内でのオブジェクトの内部表現が破棄され、オブジェクトに関連付けられたすべてのインタフェースが解放されます。
Java用のOracle COM Automation機能では、インプロセスCOM Automation機能サーバーを使用できません。開発者は、dllhostを使用し、インプロセス・サーバーをサポートできます。
エラーが発生した場合は、例外COMExceptionがスローされます。
コード・サンプル
次のコード・サンプルは、デフォルト以外のコンストラクタを示しています。
// Use the registry to determine where to create the COM object.
Automation word = new Automation("Word.Basic");
// Create the COM object on the specified server.
Automation excel = new Automation("Excel.Application",
"\\ServerName");
// Free the COM objects.
word.Destroy();
excel.Destroy();
このAPIは、COM Automationサーバー内のCOMオブジェクトをインスタンス化します。
構文
public void Create(String progID) public void Create(String progID, String serverName)
| パラメータ | 説明 |
|---|---|
progID |
作成するCOM Automationオブジェクトのプログラム識別子(progID)です。この文字列は、COM Automationオブジェクトのクラスを説明し、形式は次のとおりです。
|
serverName |
COMオブジェクトがインスタンス化されるリモートDCOMサーバーの名前。 |
| 名前を明示的に指定すると、Oracle COM Automation機能はリモート・コンピュータ上でCOMオブジェクトのインスタンス化を試みます。 |
備考
Createメソッドで作成されたCOM Automationオブジェクトは、対応するDestroyのコールによって解放されます。このコールにより、Oracle COM Automation機能内でのオブジェクトの内部表現が破棄され、オブジェクトに関連付けられたすべてのインタフェースが解放されます。
progIDパラメータのみを受け取るコンストラクタを使用すると、Oracle COM Automation機能はCOMオブジェクトの場所についてレジストリをチェックします。レジストリ情報は、COMオブジェクトがローカルかリモートかを示します。
Java用のOracle COM Automation機能では、インプロセスCOM Automation機能サーバーを使用できません。開発者は、dllhostを使用し、インプロセス・サーバーをサポートできます。
エラーが発生した場合は、例外COMExceptionがスローされます。
コード・サンプル
// Use the default constructor.
Automation word = new Automation();
Automation excel = new Automation();
// Use the registry to determine where to create the COM object.
word.Create("Word.Basic");
// Create the COM object on the specified server system.
excel.Create("Excel.Application", "\\ServerName");
// Free the COM objects.
word.Destroy();
excel.Destroy();
このAPIは、作成されたCOM Automationオブジェクトを破棄します。
構文
public void Destroy()
備考
Destroyをコールすると、Oracle COM Automation機能内でのオブジェクトの内部表現が破棄され、オブジェクトに関連付けられたすべてのインタフェースが解放されます。
コード・サンプル
「Create」の項を参照してください。
このAPIは、COM Automationオブジェクトのプロパティ値を取得します。
構文
public allowed_type GetProperty(String propName, allowed_type[] propVal)
| パラメータ | 説明 |
|---|---|
propName |
返されるCOMオブジェクトのプロパティ名。 |
propVal |
返されるプロパティ値。返されるプロパティの型は、返されるCOM Automationの型によって異なります。プロパティを返すためにアクセスされる要素は最初の要素のみですが、配列は少なくとも1つの要素を保持できる大きさである必要があります。 |
allowed_type |
次のリストのいずれかの型。 |
|
備考
プロパティがCOMオブジェクトの場合は、oracle.win.com.Automationのallowed_typeを使用して取得できます。返されるオートメーションJavaオブジェクトは、プロパティの取得と設定、およびプロパティに対するメソッドのコールに使用できます。
GetPropertyは、GetPropertyメソッドをオーバーロードするために、配列パラメータを使用してプロパティ値を返します。プロパティ値が戻り値として返された場合はオーバーロードできません。配列は、outパラメータを持たないJavaが原因で発生する問題を解決します。
プロパティは、便宜上戻り値として返されます。
エラーが発生した場合は、例外COMExceptionがスローされます。
コード・サンプル
// A Microsoft Excel ChartObject object.
Automation chartObject = null;
// A Microsoft Excel Chart object.
Automation chart = null;
// Used for properties of type Automation.
Automation[] autoProp = { null };
// Assume the Microsoft Excel ChartObject object is initialized.
// Get the Chart property.
chartObject.GetProperty("Chart", autoProp);
chart = autoProp[0];
// Set the Chart property.
chartObject.SetProperty("Chart", chart);
このAPIは、COM Automationオブジェクトのプロパティを新しい値に設定します。
構文
public void SetProperty(String propName, allowed_type propVal)
| パラメータ | 説明 |
|---|---|
propName |
新しい値を設定するCOMオブジェクトのプロパティ名。 |
propVal |
プロパティの新しい値。この値は適切なデータ型の値である必要があります。 |
allowed_type |
次のリストのいずれかの型。 |
|
備考
プロパティがCOMオブジェクトの場合は、oracle.win.com.Automationのallowed_typeを使用して設定できます。プロパティ値は、有効なオートメーションJavaオブジェクトである必要があります。
エラーが発生した場合は、例外COMExceptionがスローされます。
コード・サンプル
「GetProperty」の項を参照してください。
このAPIは、Invokeコールに渡されるパラメータ・セットを初期化します。
構文
public void InitArg()
備考
InitArgコールは、パラメータ・セットを初期化し、COMメソッドがパラメータを取らない場合でもコールする必要があります。InitArgのコール後、SetArgをコールすることにより、最初のパラメータが指定の値に設定されます。SetArgの2回目のコールでは、パラメータ・リストの2番目のパラメータが設定されます。以後のコールにより、パラメータ・リストのn番目のパラメータが設定されます(nは、InitArgのコール後にSetArgがコールされた回数です)。InitArgを再度コールすると、引数リストがリセットされ、SetArgをコールすると、最初のパラメータが再度設定されます。
コード・サンプル
「Invoke」の項を参照してください。
このAPIを使用して、Invokeを次回コールするためのパラメータ・リストを構成します。
構文
public void SetArg(allowed_type val)
| パラメータ | 説明 |
|---|---|
val |
Invokeコールに渡されるパラメータの値。設定されるパラメータは、パラメータ・リスト中のn番目のパラメータです(nは、InitArgのコール後にSetArgがコールされた回数です)。 |
allowed_type |
次のリストのいずれかの型。 |
|
|
|
備考
パラメータがCOMオブジェクトの場合、対応する引数のallowed_typeはoracle.win.com.Automationである必要があります。引数は、有効なオートメーションJavaオブジェクトである必要があります。
この時点で例外はスローされません。ただし、エラーが発生した場合、たとえば不正な引数の型が渡された場合は、Invokeメソッドがコールされたときにエラーが捕捉されます。
コード・サンプル
「Invoke」の項を参照してください。
COM Automationオブジェクトのメソッドをコールします。このファンクションでは、COM Automationメソッドへの入力値として、InitArgおよびSetArgへのコールによって事前に作成されたパラメータ・リストが使用されます。
構文
public void Invoke(String methodName, allowed_type[] retVal)
public void Invoke(String methodName)
| パラメータ | 説明 |
|---|---|
methodName |
コールするCOM Automationオブジェクトのメソッド名。 |
retVal |
COM Automationオブジェクトのメソッドの戻り値。指定される場合、この値は適切なデータ型のローカル変数である必要があります。プロパティを返すためにアクセスされる要素は最初の要素のみですが、配列は少なくとも1つの要素を保持できる大きさである必要があります。 |
allowed_type |
次のリストのいずれかの型。 |
|
備考
COMメソッドが戻り値としてCOMオブジェクトを返す場合、戻り値のallowed_typeはoracle.win.com.Automationです。返されるオートメーションJavaオブジェクトは、プロパティの取得と設定、および戻り値に対するメソッドのコールに使用できます。
Invokeメソッドをオーバーロードするには、Invokeが配列パラメータを使用してCOMオブジェクト・メソッドの値を返す必要があります。プロパティ値が戻り値として返された場合はオーバーロードできません。配列は、outパラメータを持たないJavaが原因で発生する問題を解決します。
1つのパラメータのみを受け取るInvokeのpublic void Invoke(String methodName)は、戻り値がvoid型のCOMオブジェクト・メソッドで使用されます。
プロパティは、便宜上戻り値として返されます。
エラーが発生した場合は、例外COMExceptionがスローされます。
コード・サンプル
// A Microsoft Excel Worksheet object.
Automation workSheet = null;
// A Microsoft Excel ChartObjects collection object.
Automation chartObjects = null;
// A Microsoft Excel ChartObject object.
Automation chartObject = null;
// Used for return values of type Automation.
Automation[] autorv = { null };
// Dimensions for a Microsoft Excel ChartObject object.
short xpos = 100, ypos = 30, width = 400, height = 250;
// Assume the Microsoft Excel Worksheet object is initialized.
// Invoke a method that takes no arguments.
workSheet.InitArg();
workSheet.Invoke("ChartObjects", autorv);
chartObjects = autorv[0];
// Invoke a method that takes multiple arguments.
chartObjects.InitArg();
chartObjects.SetArg(xpos);
chartObjects.SetArg(ypos);
chartObjects.SetArg(width);
chartObjects.SetArg(height);
chartObjects.Invoke("Add", autorv);
chartObject = autorv[0];
このAPIは、Javaオブジェクトcurrencyを作成します。
構文
public Currency(long value)
| パラメータ | 説明 |
|---|---|
value |
8バイトのCURRENCY数値 |
