この章では、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 数値 |