| Oracle COM Automation機能開発者ガイド 11gリリース1（11.1） E05796-01 |
|
 戻る |
 次へ |
この章では、Oracle COM Automationのプログラム・インタフェースについて説明します。
この章の項目は次のとおりです。
Microsoft COM AutomationではCOMオートメーション・データ型が使用され、Oracle COM AutomationではPL/SQLまたはJavaのデータ型が使用されるため、Oracle COM Automationでは、受け取ったデータを変換してCOMオートメーション・オブジェクトに渡す操作を行う必要があります。同様に、Oracle COM AutomationではCOMオートメーション・オブジェクトから受け取ったデータを渡して変換する必要があります。
表3-1は、PL/SQLデータ型とCOMオートメーション・データ型の間のマッピングを示したものです。
このマニュアルでは、COMオートメーション・データ型がIN OUTパラメータまたはOUTパラメータとして使用される場合、先頭にpを付けて表記しています。先頭の文字がp以外のデータ型は、INパラメータです。
表3-1 PL/SQLデータ型からCOMオートメーション・データ型への変換
| PL/SQLデータ型 | COMオートメーション・データ型 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
注意: Oracleでは、CYおよびpCYの値を-9999999999.9999〜9999999999.9999の範囲内に制限しています。 |
表3-2は、サポートされるCOMオートメーション・データ型および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）は、Globally Unique Identifier（GUID）にマップされる説明的な文字列です。GUIDは16進の数値で、COMオブジェクトを一意に識別します。
次の文字列は、progIDの例です。
Excel.Worksheet.1
progIDは、COMオブジェクトをインスタンス化するAPIで使用します。
COMオブジェクトのIDispatchインタフェースを通じて公開されるプロパティとメソッドの種類を知る必要があります。通常、オブジェクトのプロパティの名前とデータ型、およびオブジェクトのメソッドのプロトタイプが記述されたドキュメントがISVから提供されます。プロパティはxposやyposのような説明的な文字列によって参照されます。プロパティにはINTやBSTRなど、任意の標準COMオートメーション・データ型を使用できます。APIのGetPropertyとSetPropertyは、プロパティ名と適切なデータ型の変数を受け取ります。メソッドはInsertChartのような説明的な文字列によって参照されます。メソッドは、様々な種類のCOMオートメーション・データ型のパラメータ・セットを受け取り、COMオートメーション・データ型を返します。
次に示すのは、COMインタフェース定義言語（IDL）の文法で記述された、COMオートメーション・メソッドのプロトタイプの例です。
[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オートメーション・メソッドに送られる引数をパッケージ化します。
PL/SQLのGetLastErrorをコールして、最新のエラー情報を取得します。
PL/SQLのDestroyObjectまたはJavaのDestroyを使用してオブジェクトを破棄します。
この項では、Oracle COM Automationで使用可能なAPIをリストし、説明します。
この項では、COMオートメーション・インタフェースを使用して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オートメーション・オブジェクトは、対応する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オートメーション・オブジェクトを破棄します。
構文
FUNCTION DestroyObject(objecttoken BINARY_INTEGER) RETURN BINARY_INTEGER;
| パラメータ | 説明 |
|---|---|
objecttoken |
事前にCreateObjectによって作成されたCOMオートメーション・オブジェクトのオブジェクト・トークン。 |
備考
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オートメーション・エラー情報を取得します。
構文
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オートメーション・オブジェクトについてのヘルプ・ファイル。指定する場合、この値はCHAR型またはVARCHAR型のローカル変数である必要があります。戻り値は必要に応じて、ローカル変数として適切な値になるよう切り捨てられます。 |
helpid |
ヘルプ・ファイルのコンテキストID。指定する場合、この値はINT型のローカル変数である必要があります。 |
備考
（GetLastErrorを除く）Oracle COM Automation APIコールごとにエラー情報がリセットされます。このため、GetLastErrorでは、最新のOracle COM Automation APIコールに対するエラー情報のみが取得されます。GetLastErrorは最後のエラー情報をリセットしないため、このAPIを複数回コールすると、同じエラー情報が取得されることがあります。
このファンクションは、成功のときは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オートメーション・オブジェクトのプロパティ値を返します。
構文
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オートメーションのデータ型によって異なります。COMオートメーション・プロパティのCOMオートメーション・データ型に対応するPL/SQLデータ型を渡す必要があります。そのようにしないと、COM AutomationによってCOMオートメーション・データ型が適切に変換されません。 |
any_PL/SQL_data type |
COM Automation機能でサポートされる任意のデータ型。 |
備考
プロパティがCOMオブジェクトを返す場合、propertyvalueパラメータにBINARY_INTEGERデータ型のローカル変数を指定する必要があります。オブジェクト・トークンはローカル変数に格納されます。格納されたオブジェクト・トークンは、他のCOMオートメーション・ストアド・プロシージャで使用できます。
プロパティが配列を返すとき、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オートメーション・オブジェクトのプロパティを新しい値に設定します。
構文
FUNCTION SetProperty(objecttoken BINARY_INTEGER, propertyname VARCHAR2, newvalue any_PL/SQL_data type, data type VARCHAR2) RETURN BINARY_INTEGER;
| パラメータ | 説明 |
|---|---|
objecttoken |
事前にCreateObjectによって作成されたCOMオートメーション・オブジェクトのオブジェクト・トークン。 |
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オートメーション・データ型。 |
使用可能なデータ型は、次のとおりです。
|
|
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オートメーション・オブジェクトのメソッドをコールします。このファンクションでは、COMオートメーション・メソッドへの入力値として、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オートメーション・オブジェクトのオブジェクト・トークン。 |
methodname |
コールするCOMオートメーション・オブジェクトのメソッド名。 |
argcount |
COMオートメーション・オブジェクトのメソッドに渡される引数の数。 |
returnvalue |
COMオートメーション・オブジェクトのメソッドの戻り値。指定される場合、この値は適切なデータ型のローカル変数である必要があります。 |
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オートメーション・インタフェースを使用してCOMオブジェクトを操作するためのJava APIについて説明します。これらのAPIは、JavaのAutomationクラスおよびCurrencyクラスにあります。
JavaのAutomationクラスを使用し、COMオートメーションをサポートするCOMオブジェクトにアクセスできます。このJavaクラスでは、COMオブジェクトを作成し、COMオブジェクトのIDispatchインタフェースへのポインタを取得できます。さらに、COMオブジェクトに対してプロパティを取得および設定できる他、COMオブジェクトに対して（引数あり、または引数なしで）メソッドをコールできます。このクラスは、COMオブジェクトのラッパーを提供するため、COMオブジェクトまたはそのIDispatchインタフェースには直接アクセスしません。
JavaのCurrencyクラスは、COMオートメーション・データ型の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オートメーション・オブジェクトは、対応する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オートメーション・オブジェクトのプログラム識別子（progID）。この文字列は、COMオートメーション・オブジェクトのクラスを記述します。形式は次のとおりです。
|
serverName |
COMオブジェクトがインスタンス化されるリモートDCOMサーバーの名前。 |
| 名前を明示的に指定すると、Oracle COM Automationはリモート・コンピュータ上でCOMオブジェクトのインスタンス化を試みます。 |
備考
Createメソッドで作成されたCOMオートメーション・オブジェクトは、対応する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オートメーション・オブジェクトを破棄します。
構文
public void Destroy()
備考
Destroyをコールすると、Oracle COM Automation内でのオブジェクトの内部表現が破棄され、オブジェクトに関連付けられたすべてのインタフェースが解放されます。
コード・サンプル
「Create」の項を参照してください。
このAPIは、COMオートメーション・オブジェクトのプロパティ値を取得します。
構文
public allowed_type GetProperty(String propName, allowed_type[] propVal)
| パラメータ | 説明 |
|---|---|
propName |
返されるCOMオブジェクトのプロパティ名。 |
propVal |
返されるプロパティ値。返されるプロパティの型は、返されるCOMオートメーションの型によって異なります。プロパティを返すためにアクセスされる要素は最初の要素のみですが、配列は少なくとも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オートメーション・オブジェクトのプロパティを新しい値に設定します。
構文
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オートメーション・オブジェクトのメソッドをコールします。このファンクションでは、COMオートメーション・メソッドへの入力値として、InitArgおよびSetArgへのコールによって事前に作成されたパラメータ・リストが使用されます。
構文
public void Invoke(String methodName, allowed_type[] retVal)
public void Invoke(String methodName)
| パラメータ | 説明 |
|---|---|
methodName |
コールするCOMオートメーション・オブジェクトのメソッド名。 |
retVal |
COMオートメーション・オブジェクトのメソッドの戻り値。指定される場合、この値は適切なデータ型のローカル変数である必要があります。プロパティを返すためにアクセスされる要素は最初の要素のみですが、配列は少なくとも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数値 |
