This chapter describes aspects of the programming interface for Oracle COM Automation Feature.
This chapter contains these topics:
Because Microsoft COM Automation uses COM Automation datatypes, and Oracle COM Automation Feature uses either PL/SQL or Java datatypes, Oracle COM Automation Feature must convert the data that it receives and pass it to the COM Automation object. Similarly, Oracle COM Automation Feature must pass the data that it receives from the COM Automation object and convert it.
Table 3-1 shows the mapping between PL/SQL datatypes and COM Automation datatypes.
This guide follows a convention where COM Automation datatypes are prefaced by an initial p when used as IN
OUT
or OUT
parameters. Datatypes without the initial p are IN
parameters.
Table 3-1 PL/SQL to COM Automation Datatypes
PL/SQL Datatype | COM Automation Datatype |
---|---|
VARCHAR2 |
BSTR, pBSTR |
BOOLEAN |
BOOL, pBOOL |
BINARY_INTEGER |
DISPATCH, pDISPATCH |
DOUBLE PRECISION |
UI1, pUI1, I2, pI2, I4, pI4, R4, pR4, R8, pR8, SCODE, pSCODE, CY, pCY, DISPATCH, pDISPATCH |
DATE |
DATE, pDATE |
Note: Oracle restricts aCY and pCY value between -9999999999.9999 and 9999999999.9999. |
Table 3-2 lists the supported COM Automation datatypes and related mappings to Java datatypes.
All the datatype mapping apply to properties, arguments, and return values, except void
, which only applies to return values.
Table 3-2 Java to COM Automation Datatypes
Java Datatype | COM Automation Datatype |
---|---|
boolean |
BOOL |
char |
CHAR |
double |
DOUBLE |
int |
INT |
long |
LONG |
float |
FLOAT |
short |
SHORT |
byte |
BYTE |
java.lang.String |
BSTR |
oracle.win.com.Currency |
CURRENCY |
java.util.Calendar |
DATE |
void |
VOID (return values only) |
oracle.win.com.Automation |
IDispatch* |
HRESULT
error codes are provided by the Microsoft Windows API.
An HRESULT
is a COM error code of the hexadecimal form 0x800nnnnn. However, it has the decimal form -214nnnnnnn. For example, passing an invalid object name when creating a COM object causes the HRESULT
of -2147221005 to be returned, which is 0x800401f3 in hexadecimal form.
For complete information on the HRESULT
return code, refer to the Microsoft documentation.
The PL/SQL APIs return an integer return code. The return code is 0
when successful, or a nonzero value of HRESULT
when an error occurs.
See Also: "GetLastError" for additional information on how to interpret the return codes from Oracle COM Automation Feature |
Oracle COM Automation for Java uses standard Java exception mechanisms. Specifically, a Java exception class, oracle.win.com.COMException
, is introduced to represent COM errors.
This exception is thrown by the Automation
Java class when an error occurs.
The error information provided by this exception is similar to that provided by the PL/SQL API GetLastError
function.
Note: TheHRESULT data member has the same meaning as the value of HRESULT returned by the PL/SQL functions. |
If the COM error is DISP_E_EXCEPTION
as indicated by the excepInfo
data member, COMException
uses the source
, description
, helpfile
, and helpid
data members. Otherwise, these data members are not valid.
The COMException
writes an error message representing the COM error to the errmsg
data member.
Table 3-3 lists the COMException
data members and their descriptions.
Table 3-3 COMException Data Members
Member | Description |
---|---|
hresult |
is an HRESULT value as defined by the Windows API. |
errmsg |
is the textual representation of HRESULT in the appropriate language. |
source |
is the source of the exception, typically the application name. |
description |
is the error description. |
helpfile |
is the fully qualified path name of the helpfile containing more information about the error. |
helpid |
is the help context ID of a topic within the helpfile specified by help file. |
excepInfo |
is DISP_E_EXCEPTION , if HRESULT returns true, and source , description , helpfile , and helpid contain more information. |
Code Sample
This example demonstrates the COMException
exception.
try { // Some code which 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); } }
This section discusses the required information and the general steps to build a solution using Oracle COM Automation Feature.
Review the following information about the COM objects that you intend to use:
You must determine the Program ID of the COM object. The Program ID, or progID, is a descriptive string that maps to the Globally Unique Identifier (GUID), a hexadecimal number that uniquely identifies a COM object.
The following string is an example of a progID:
Excel.Worksheet.1
Use the progID with the API that instantiates the COM object.
You must be aware of the types of properties and methods that are exposed through the COM object's IDispatch
interface. Usually, the ISV provides documentation describing the names and datatype of the object's properties and the prototypes of the object's methods. Properties are referred to by a descriptive string, such as xpos
or ypos
. A property can be any standard COM Automation datatype, such as INT
or BSTR
. The GetProperty
and SetProperty
APIs take the property name and a variable of the appropriate datatype. Methods are referred to by a descriptive string, such as InsertChart
. A method takes a set of parameters that are of different COM Automation datatypes and returns a COM Automation datatype.
The following is an example of a COM Automation method prototype in COM Interface Definition Language (IDL) grammar:
[id(0x6003000)] long Post([in, out] long* lngAccountNo, [in, out] long* lngAmount, [in, out] BSTR* strResult);
Interfaces define object methods and properties. COM IDL is used to specify interfaces that are defined on COM objects.
Microsoft provides a tool called the OLE/COM Object Viewer with Microsoft Visual Studio for browsing the properties and methods of COM objects on a local system. This tool enables you to quickly and easily determine the properties and methods that each COM object exposes. See Figure 3-1, "OLE/COM Object Viewer" for an example.
In a typical use of Oracle COM Automation Feature, you design a Java class or PL/SQL block to create and manipulate a COM object. The class or code block performs the following steps:
Creates the COM object as follows:
in PL/SQL, using CreateObject
in Java, using a constructor or the Create
method
Manipulates the COM object calling the following APIs:
GetProperty
to get a property value
SetProperty
to set a property value to a new value
Calls Invoke
to call a method
As part of preparation for the Invoke
API call, you use InitArg
and SetArg
in Java and you use InitArg
and SetArg
in PL/SQL to package the argument to be sent to the COM Automation method.
Calls GetLastError
in PL/SQL to get the most recent error information
Destroys the object using DestroyObject
in PL/SQL or Destroy
in Java
This section lists and then describes the APIs available for Oracle COM Automation Feature.
This section describes the PL/SQL APIs for manipulating COM objects using the COM Automation interface. Each of the following PL/SQL stored procedures resides in the package ORDCOM
.
This API instantiates a COM object in a COM Automation server.
Syntax
FUNCTION CreateObject(progid VARCHAR2, reserved BINARY_INTEGER, servername VARCHAR2, objecttoken OUT BINARY_INTEGER) RETURN BINARY_INTEGER;
Remarks
The created COM Automation object is freed with a corresponding call to DestroyObject
. This nullifies the internal representation of the object in the Oracle COM Automation Feature and releases all the interfaces associated with the object.
This procedure returns 0
when successful, or a nonzero value for HRESULT
when an error occurs.
Code Sample
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;
This API destroys a created COM Automation object.
Syntax
FUNCTION DestroyObject(objecttoken BINARY_INTEGER) RETURN BINARY_INTEGER;
Where | Is |
---|---|
objecttoken |
the object token of a COM Automation object previously created by CreateObject . |
Remarks
Calling DestroyObject
nullifies the internal representation of the object in the Oracle COM Automation Feature and releases all the interfaces associated with the object.
This procedure returns 0
when successful, or a nonzero value of HRESULT
when an error occurs.
Code Sample
HRESULT BINARY_INTEGER; applicationToken BINARY_INTEGER:=-1; /* Assume applicationToken is initialized. */ HRESULT:=ORDCOM.DestroyObject(applicationToken); IF (HRESULT!=0) THEN dbms_output.put_line(HRESULT);
This API obtains the COM Automation error information about the last error that occurred.
Syntax
FUNCTION GetLastError(source OUT VARCHAR2, description OUT VARCHAR2, helpfile OUT VARCHAR2, helpid OUT BINARY_INTEGER) RETURN BINARY_INTEGER;
Where | Is |
---|---|
source |
the source of the error information. If specified, it must be a local CHAR or VARCHAR variable. The return value is truncated to fit the local variable if necessary. |
description |
the description of the error. If specified, it must be a local CHAR or VARCHAR variable. The return value is truncated to fit the local variable if necessary. |
helpfile |
the Help file for the COM Automation object. If specified, it must be a local CHAR or VARCHAR variable. The return value is truncated to fit the local variable if necessary. |
helpid |
the Help file context ID. If specified, it must be a local INT variable. |
Remarks
Each call to an Oracle COM Automation Feature API (except GetLastError
) resets the error information, so that GetLastError
obtains error information only for the most recent Oracle COM Automation Feature API call. Because GetLastError
does not reset the last error information, it can be called multiple times to get the same error information.
This procedure returns 0
when successful, or a nonzero value of HRESULT
when an error occurs.
See "Microsoft COM Automation Errors" for a description of the types of errors that can be returned by this function.
Code Sample
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;
This API gets a property value of a COM Automation object.
Syntax
FUNCTION GetProperty(objecttoken BINARY_INTEGER, propertyname VARCHAR2, argcount BINARY_INTEGER, propertyvalue OUT any_PL/SQL_datatype) RETURN BINARY_INTEGER;
Where | Is |
---|---|
objecttoken |
the object token of a COM object previously created by CreateObject . |
propertyname |
the property name of the COM object to return. |
argcount |
the index of the property array. If the property is not an array, then the developer should specify 0 . |
propertyvalue |
the returned property value. The returned property type depends on the COM Automation datatype that is returned. You must pass the PL/SQL datatype that corresponds to the COM Automation datatype of the COM Automation property. Otherwise, the COM Automation Feature will not properly convert the COM Automation datatype. |
any_PL/SQL_datatype |
any datatype supported by COM Automation Feature. |
Remarks
If the property returns a COM object, then you must specify a local variable of datatype BINARY_INTEGER
for the propertyvalue
parameter. An object token is stored in the local variable, and this object token can be used with other COM Automation stored procedures.
When the property returns an array, if propertyvalue
is specified, then it is set to NULL
.
This procedure returns 0
when successful, or a nonzero value of HRESULT
when an error occurs.
Code Sample
/* * 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;
This API sets a property of a COM Automation object to a new value.
Syntax
FUNCTION SetProperty(objecttoken BINARY_INTEGER, propertyname VARCHAR2, newvalue any_PL/SQL_datatype, datatype VARCHAR2) RETURN BINARY_INTEGER;
Where | Is |
---|---|
objecttoken |
the object token of a COM Automation object previously created by CreateObject . |
propertyname |
the property name of the COM object to set to a new value. |
newvalue |
the new value of the property. It must be a value of the appropriate datatype. |
datatype |
the explicitly specified datatype of the value passed in. The available datatypes are:
|
any_PL/SQL_datatype |
any datatype supported by COM Automation Feature. |
Remarks
This procedure returns a 0
when successful, or a nonzero value of HRESULT
when an error occurs.
Code Sample
/* * 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;
This API initializes the parameter set passed to an Invoke
call.
Syntax
PROCEDURE InitArg();
Remarks
The InitArg
call initializes the parameter set. After InitArg
has been called, a SetArg
call sets the first parameter to the specified value. A second SetArg
call sets the second parameter in the parameter list. Subsequent calls set the nth parameters in the parameter list, where n is the number of times SetArg
has been called after an InitArg
call. Another call to InitArg
resets the argument list and a call to SetArg
sets the first parameter again.
Code Sample
See "Invoke" for sample code.
InitOutArg
must be called after a COM method is invoked in preparation for getting the values of OUT
and IN
OUT
parameters using GetArg
. After calling InitOutArg
, the first call to GetArg
gets the value for the first OUT
or IN
OUT
parameter, the second call to GetArg
gets the value for the second OUT
or IN
OUT
parameters, and so on. Calling InitOutArg
again restarts this process.
Syntax
PROCEDURE InitOutArg();
Remarks
See the section on SetArg
datatype strings in "SetArg" for information about IN
and OUT
parameters.
Code Sample
See "Invoke" for sample code.
Gets the argument of OUT
and IN
OUT
parameters after the COM method has been invoked.
Syntax
PROCEDURE GetArg(data OUT any_PL/SQL_datatype, type VARCHAR2);
Where | Is |
---|---|
data |
the value of the OUT or IN OUT parameter after the COM method has been invoked. |
type |
the COM Automation datatype of the parameter. |
The available datatypes are:
|
|
any_PL/SQL_datatype |
any datatype supported by COM Automation Feature. |
Remarks
See the section on SetArg
datatype strings in "SetArg" for information about IN
and OUT
parameters.
Code Sample
See "Invoke" for sample code.
Used to construct the parameter list for the next Invoke
call.
SetArg
sets a parameter's value to be passed by value.
Syntax
PROCEDURE SetArg(paramvalue any_PL/SQL_datatype, datatype VARCHAR2);
Where | Is |
---|---|
paramvalue |
the value of the parameter to be passed to an Invoke call. The parameter set is the nth parameter in the parameter list, where n is the number of times SetArg has been called after an InitArg call. |
datatype |
the explicitly specified datatype for the parameters.
Those datatypes prefaced by an initial |
Those datatypes without the initial p are IN parameters. The available datatypes are:
|
|
|
|
|
|
|
|
any_PL/SQL_datatype |
any datatype supported by COM Automation Feature. |
Remarks
Each SetArg
procedure sets the nth parameter value. The InitArg
call initializes the parameter set. After InitArg
has been called, a SetArg
call sets the first parameter to the specified value. A second SetArg
call sets the second parameter in the parameter list. Subsequent calls set the nth parameters in the parameter list, where n is the number of times SetArg
has been called after an InitArg
call. Another call to InitArg
resets the argument list and a call to SetArg
sets the first parameter again.
Datatypes without the initial p are IN
parameters. Those datatypes prefaced by an initial p are IN
OUT
or OUT
parameters.
Code Sample
See "Invoke" for sample code.
This API calls a method of a COM Automation object. This function uses the parameter list, previously created by the calls to InitArg
and SetArg
as input for the COM Automation method.
Syntax
FUNCTION Invoke(objecttoken BINARY_INTEGER, methodname VARCHAR2, argcount BINARY_INTEGER, returnvalue OUT any_PL/SQL_datatype) RETURN BINARY_INTEGER;
Where | Is |
---|---|
objecttoken |
the object token of a COM Automation object previously created by CreateObject . |
methodname |
the method name of the COM Automation object to call. |
argcount |
the number of arguments passed to the COM Automation object method. |
returnvalue |
the return value of the method of the COM Automation object. If specified, it must be a local variable of the appropriate datatype. |
any_PL/SQL_datatype |
any datatype supported by COM Automation Feature. |
Remarks
If the method's return value is a COM object, then the developer must specify a local variable of datatype BINARY_INTEGER
for the returnvalue
parameter. An object token is stored in the local variable, and this object token can be used with other Oracle COM Automation Feature APIs.
This procedure returns 0
when successful, or a nonzero value of HRESULT
when an error occurs.
Code Sample
/* * 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');
This section describes the Java APIs for manipulating COM objects using the COM Automation interface. These APIs are found in the Automation
and Currency
Java classes.
The Automation
Java class provides access to COM objects that support COM Automation. With this Java class, you can create a COM object and obtain a pointer to the IDispatch
interface for the COM object. You can then get and set properties on the COM object, as well as invoke methods (with or without arguments) on the COM object. This class provides a wrapper for the COM object, so there is no direct access to the COM object or to its IDispatch
interface.
The Currency
Java class represents the CURRENCY COM Automation datatype. CURRENCY is a an 8-byte number where the last four digits represent the fractional part of the value. For example, the number 12345 actually represents the value 1.2345. CURRENCY has a range of (+/-)922337203685477.5807.
COM Object Reference Counting
COM object interface reference counting is handled internally, and IUnknown::AddRef(
) and IUnknown::Release()
are not exposed. The user cannot explicitly address COM object interfaces. The lifetime of a particular COM object starts when the associated Java constructor or Create method is invoked, and it is released when the associated Destroy method is invoked.
Constructors and Destructors
Because the default constructor does not create a COM object, there are two approaches to creating a COM object:
Instantiate the Java object using the default constructor, and call one of the Create methods. Which Create
method you use depends on whether you want to specify the server name. Later, you must call the Destroy
method to free the COM object.
The Create
method can be called at any time, but if a COM object was previously created through one of the nondefault constructors or the Create
method, then you must first call the Destroy
method.
Instantiate the Java object using a nondefault constructor. Which nondefault constructor you use depends on whether you want to specify the server name. Later, you must call the Destroy
method to free the COM object.
Handling COM Object Errors
All COM errors are mapped to Java exceptions. Users can catch COM object errors through the Java exception handling mechanism.
Note: Oracle COM Automation Feature for Java does not allow in-process COM Automation servers. Developers can usedllhost to support in-process servers. |
This API creates a COM object.
Syntax
public Automation() public Automation(String progID) public Automation(String progID, String serverName)
Remarks
The default constructor public Automation()
does nothing. It is used with a Create method.
Using a constructor that takes only the progid
parameter forces Oracle COM Automation Feature to check the registry for the location of the COM object. Registry information indicates whether the COM object is local or remote.
COM Automation objects created using the nondefault constructors are freed with a corresponding call to Destroy. This nullifies the internal representation of the objects in Oracle COM Automation Feature and releases all the interfaces associated with the objects.
Oracle COM Automation Feature for Java does not allow in-process COM Automation servers. Developers can use dllhost
to support in-process servers.
The COMException
exception is thrown if an error occurs.
Code Sample
The following code sample demonstrates the nondefault constructors. // 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 machine. Automation excel = new Automation("Excel.Application", "\\ServerMachineName"); // Free the COM objects. word.Destroy(); excel.Destroy();
This API instantiates a COM object in a COM Automation server.
Syntax
public void Create(String progID) public void Create(String progID, String serverName)
Where | Is |
---|---|
progid |
the programmatic identifier (progID) of the COM Automation object to create. This character string describes the class of the COM Automation object and has the following form:
|
servername |
the name of the remote DCOM server on which the COM object is being instantiated. |
Passing a specified name forces Oracle COM Automation Feature to attempt to instantiate the COM object on a remote computer. |
Remarks
The COM Automation object created with the Create
method is freed with a corresponding call to Destroy
. This nullifies the internal representation of the object in Oracle COM Automation Feature and releases all the interfaces associated with the object.
Using the constructor that takes only the progid
parameter forces Oracle COM Automation Feature to check the registry for the location of the COM object. Registry information indicates whether the COM object is local or remote.
Oracle COM Automation Feature for Java does not allow in-process COM Automation servers. Developers can use dllhost
to support in-process servers.
The COMException
exception is thrown if an error occurs.
Code Sample
// 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 machine. excel.Create("Excel.Application", "\\ServerMachineName"); // Free the COM objects. word.Destroy(); excel.Destroy();
This API destroys a created COM Automation object.
Syntax
public void Destroy()
Remarks
Calling Destroy
nullifies the internal representation of the object in the Oracle COM Automation Feature and releases all the interfaces associated with the object.
Code Sample
See "Create" for code sample.
This API gets a property value of a COM Automation object.
Syntax
public allowed_type GetProperty(String propName, allowed_type[] propVal)
Where | Is |
---|---|
propName |
the property name of the COM object to return |
propVal |
the returned property value. The returned property type depends on the COM Automation type that is returned. The array must be big enough to hold at least one element although only the first element will be accessed to return the property. |
allowed_type |
from the following list: |
|
Remarks
If the property is a COM object, then it can be retrieved using the allowed_type
of oracle.win.com.Automation
. The Automation Java object that is returned can be used to get and set properties and call methods on the property.
GetProperty
uses an array parameter to return the property value to overload the GetProperty
method. Overloading would not be possible if the property value were returned as a return value. The array solves the problem caused by Java not having an out parameter.
The property is still returned as a return value for convenience.
The COMException exception
is thrown if an error occurs.
Code Sample
// 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);
This API sets a property of a COM Automation object to a new value.
Syntax
public void SetProperty(String propName, allowed_type propVal)
Where | Is |
---|---|
propName |
the property name of the COM object being set to a new value |
propVal |
the new value of the property. It must be a value of the appropriate datatype. |
allowed_type |
from the following list: |
|
Remarks
If the property is a COM object, it can be set using the allowed type of oracle.win.com.Automation
. The property value must be a valid Automation Java object.
The COMException exception
is thrown if an error occurs.
Code Sample
See "GetProperty" for sample code.
This API initializes the parameter set passed to an Invoke
call.
Syntax
public void InitArg()
Remarks
The InitArg
call initializes the parameter set and must be called even if the COM method does not take any parameters. After InitArg
has been called, a SetArg
call sets the first parameter to the specified value. A second SetArg
call sets the second parameter in the parameter list. Subsequent calls set the nth parameters in the parameter list, where n is the number of times SetArg
has been called after an InitArg
call. Another call to InitArg
resets the argument list and a call to SetArg
sets the first parameter again.
Code Sample
See "Invoke" for sample code.
This API is used to construct the parameter list for the next Invoke
call.
Syntax
public void SetArg(allowed_type val)
Where | Is |
---|---|
val |
the value of the parameter to be passed to an Invoke call. The parameter set is the nth parameter in the parameter list, where n is the number of times SetArg has been called after an InitArg call. |
allowed_type |
from the following list. |
|
|
|
Remarks
If a parameter is a COM object, then the allowed_type
of the corresponding argument should be oracle.win.com.Automation
. The argument should be a valid Automation Java object.
No exceptions are thrown at this time. However, if an error occurs, for example, if the wrong argument type is passed, then it will be caught when the Invoke
method is called.
Code Sample
See "Invoke" for sample code.
Calls a method of a COM Automation object. This function uses the parameter list, previously created by the calls to InitArg
and SetArg
, as input for the COM Automation method.
Syntax
public void Invoke(String methodName, allowed_type[] retVal)
public void Invoke(String methodName)
Where | Is |
---|---|
methodName |
the method name of the COM Automation object to call |
retVal |
the return value of the method of the COM Automation object. If specified, then it must be a local variable of the appropriate datatype. The array must be big enough to hold at least one element, although only the first element will be accessed to return the property. |
allowed_type |
a type from the following list: |
|
Remarks
If the COM method returns a COM object as the return value, then the allowed_type
of the return value is oracle.win.com.Automation
. The Automation Java object that is returned can be used to get and set properties, and call methods on the return value.
To overload the Invoke
method,
Invoke
uses an array parameter to return the values of COM object methods. Overloading would not be possible if the property value was returned as a return value. The array solves the problem caused by Java not having an out parameter.
The version of Invoke
that takes only one parameter, public void Invoke(String methodName)
, is used for COM object methods with void
return types.
The property is still returned as a return value for convenience.
The COMException exception
is thrown if an error occurs.
Code Sample
// 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 which takes no arguments. workSheet.InitArg(); workSheet.Invoke("ChartObjects", autorv); chartObjects = autorv[0]; // Invoke a method which takes multiple arguments. chartObjects.InitArg(); chartObjects.SetArg(xpos); chartObjects.SetArg(ypos); chartObjects.SetArg(width); chartObjects.SetArg(height); chartObjects.Invoke("Add", autorv); chartObject = autorv[0];
This API creates a currency
Java object.
Syntax
public Currency(long value)
Where | Is |
---|---|
value |
the 8-byte CURRENCY number |
This API gets the 8-byte CURRENCY number.
Syntax
public long Get()
Remarks
Returns the 8-byte CURRENCY number.