Skip Headers

Oracle COM Automation Feature Developer's Guide
Release 9.2

Part Number A95499-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

3
Oracle COM Automation Feature Core Functionality

This chapter describes aspects of the programming interface for Oracle COM Automation Feature.

This chapter contains these topics:

Datatype Conversions

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, and vice versa.

Datatype Conversion for PL/SQL

Table 3-1, "PL/SQL to COM Automation Datatypes" shows the mappings 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 CY and pCY to this value: -9999999999.9999 to 9999999999.9999.


Datatype Conversion for Java

Table 3-2, "Java to COM Automation Datatypes" lists the supported COM Automation datatypes and related mappings to Java datatypes.

All the datatype mappings and return values 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

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.

See Also:

"Microsoft COM Automation Errors" for additional information

PL/SQL Use of HRESULT

The PL/SQL APIs return an integer return code. The return code is 0 when successful or a nonzero HRESULT when an error occurs.

See Also:

"GetLastError" for additional information on how to interpret the return codes from Oracle COM Automation Feature

Java Use of HRESULT

In the Java API, HRESULT is a data member of the COMException class.

See Also:

"Oracle COM Automation for Java Exception Handling"

Oracle COM Automation for Java Exception Handling

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:

The HRESULT data member has the same meaning as the 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 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 helpfile.

excepInfo

if true, then HRESULT has the value DISP_E_EXCEPTION, 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);
     }
   }

Typical COM Automation Functionality

This section discusses the required information and the general steps to build a solution using Oracle COM Automation Feature.

Information Required for COM Objects

Review the following information about the COM objects that you intend to use:

OLE/COM Object Viewer

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.

Figure 3-1 OLE/COM Object Viewer

Text description of olecom.gif follows.

Text description of the illustration olecom.gif

Using COM Automation Feature APIs

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:

  1. Creates the COM object as follows:

    • in PL/SQL, using CreateObject.

    • in Java, using a constructor or the Create method.
  2. Manipulates the COM object calling the following APIs:

    • GetProperty to get a property value.

    • SetProperty to set a property value to a new value.
  3. 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.

  4. Calls GetLastError in PL/SQL, to get the most recent error information.

  5. Destroys the object using DestroyObject in PL/SQL or Destroy in Java.

Application Programming Interfaces

This section lists and then describes the APIs available for Oracle COM Automation Feature.

PL/SQL APIs

The feature externalizes the following APIs for PL/SQL development:

Java APIs

The COM Automation Feature externalizes the following APIs for Java development:

PL/SQL APIs

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.

CreateObject

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;

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:

COMComponent.Object

COMComponent is the component name of the COM Automation server, and Object is the name of the COM Automation object. The specified COM Automation object must be creatable and must support the IDispatch interface.

reserved

a parameter currently reserved for future use. Pass a value of 0. Future versions of Oracle COM Automation Feature may use this parameter.

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. Passing an empty string, for example, `', 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. Therefore, to create a local COM object, always pass an empty string and ensure the registry indicates that the COM object exists locally. The registry information for COM objects can be configured with the tool dcomcnfg.exe.

objecttoken

the returned object token. It must be a local variable of datatype BINARY_INTEGER. This object token identifies the created COM Automation object and is used in calls to the other Oracle COM Automation Feature APIs.

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 a 0 when successful or a nonzero HRESULT when an error occurs.

Code Sample

HRESULT BINARY_INTEGER;
applicationToken BINARY_INTEGER:=-1;

HRESULT :=ORDCOM.CreateObject('Excel.Application', 0, `', applicationToken);
IF HRESULT = -1 THEN
  dbms_output.put_line(HRESULT);
END IF;

DestroyObject

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 a 0 when successful or a nonzero HRESULT when an error occurs.

Code Sample

HRESULT BINARY_INTEGER;
applicationToken BINARY_INTEGER:=-1;

/*
 At some point before this, we called CreateObject and
 got a valid applicationToken.
*/
HRESULT:=ORDCOM.DestroyObject(applicationToken);

GetLastError

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 a 0 when successful or a nonzero HRESULT when an error occurs.

See "Microsoft COM Automation Errors" on page A-4 for a description of the types of errors that can be returned by this function.

Code Sample

applicationToken BINARY_INTEGER:=-1;
HRESULT BINARY_INTEGER;
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=-1 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);
  return HRESULT;
END IF;

GetProperty

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, 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, it is set to NULL.

This procedure returns a 0 when successful or a nonzero HRESULT when an error occurs.

Code Sample

ChartObject  BINARY_INTEGER:=-1;
ChartToken    BINARY_INTEGER := -1
HRESULT           BINARY_INTEGER;
/* Previously, ChartObject was initialized calling CreateObject */
HRESULT:=ORDCOM.getProperty(ChartObject, 'Chart', 0, ChartToken);
IF HRESULT=-1 THEN
  /* Do error checking here */
  return HRESULT;
END IF;

SetProperty

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.

any_PL/SQL_datatype

any datatype supported by COM Automation Feature.

datatype

the explicitly specified datatype of the value passed in. The available datatypes are:

  • UI1 - byte integer

  • I2 - 2 byte integer

  • I4 - 4 byte integer

  • R4 - IEEE 4 byte real

  • R8 - IEEE 8 byte real

  • SCODE - error code

  • CY - currency (value - 9999999999.9999 to 9999999999.9999)

    (This is an Oracle restriction)

  • DISPATCH - dispatch pointer

  • BSTR - String

  • BOOL - boolean

  • DATE - date

Remarks

This procedure returns a 0 when successful or a nonzero HRESULT when an error occurs.

Code Sample

RangeToken  BINARY_INTEGER:=-1;
HRESULT           BINARY_INTEGER;

/* 
 Previously, RangeToken has been initialized to a valid object token with a 
property by the name of value.
*/
HRESULT:=ORDCOM.SetProperty(RangeToken, 'Value', `EmpNo', `BSTR');
IF HRESULT=-1 THEN
  /* Do error checking here */
  return HRESULT;
END IF;

InitArg

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

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.

GetArg

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.

any_PL/SQL_datatype

any datatype supported by COM Automation Feature.

datatype

the COM Automation datatype of the parameter.

The available datatypes are:

  • pUI1 - byte integer

  • pI2 - 2 byte integer

  • pI4 - 4 byte integer

  • pR4 - IEEE 4 byte real

  • pR8 - IEEE 8 byte real

  • pSCODE - error code

  • pCY - currency (value -9999999999.9999 to 9999999999.9999) (This is an Oracle restriction)

  • pDISPATCH - dispatch pointer

  • pBSTR - String

  • pBOOL - boolean

  • pDATE - date

Remarks

See the section on SetArg datatype strings in "SetArg" for information about IN and OUT parameters.

Code Sample

See "Invoke" for sample code.

SetArg

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 numbers of times SetArg has been called after an InitArg call.

datatype

the explicitly specified datatype for the parameters.

Those datatypes prefaced by an initial p are IN OUT or OUT parameters. The p indicates that the VT_BYREF flag will be set for the COM Automation datatype.

Those datatypes without the initial p are IN parameters. The available datatypes are:

  • UI1 - byte integer

  • pUI1 - byte integer

  • I2 - 2 byte integer

  • pI2 - 2 byte integer

  • I4 - 4 byte integer
  • pI4 - 4 byte integer

  • R4 - IEEE 4 byte real

  • pR4 - IEEE 4 byte real

  • R8 - IEEE 8 byte real

  • pR8 - IEEE 8 byte real

  • SCODE - error code

  • pSCODE - error code
  • CY - currency (value -9999999999.9999 to 9999999999.9999)

    (This is an Oracle restriction)

  • pCY - currency (value -9999999999.9999 to 9999999999.9999)

    (This is an Oracle restriction)

  • DISPATCH - dispatch pointer

  • pDISPATCH - dispatch pointer

  • BSTR - String

  • pBSTR - String
  • BOOL - boolean

  • pBOOL - boolean

  • DATE - date

  • pDATE - date

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.

Invoke

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 a 0 when successful or a nonzero 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);
  */

 applicationToken binary_integer:=-1;
 i 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');

 i:=ORDCOM.Invoke(applicationToken, 'TestOutArg', 3, x4);

 ORDCOM.InitOutArg();
 ORDCOM.GetArg(x1, 'pI2');
 ORDCOM.GetArg(x3, 'pI2');

Java APIs

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 4 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:

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 use dllhost to support in-process servers.


Automation Constructor

Creates a COM object.

Syntax

  public Automation()
  public Automation(String progID)
  public Automation(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:

COMComponent.Object

COMComponent is the component name of the COM Automation server, and Object is the name of the COM Automation object. The specified COM Automation object must be creatable and must support the IDispatch interface.

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 default constructor public Automation() does nothing. It is used with a Create method.

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.

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 the 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 exception COMException 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();

Create

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:

COMComponent.Object

COMComponent is the component name of the COM Automation server, and Object is the name of the COM Automation object. The specified COM Automation object must be creatable and must support the IDispatch interface.

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 the 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 exception COMException 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();

Destroy

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.

GetProperty

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 in order to return the property.

allowed_type

from the following list:

  • boolean

  • byte

  • char

  • short

  • int

  • long

  • float

  • double

  • java.long.String

  • oracle.win.com.Automation

  • oracle.win.com.Currency

  • java.util.Calendar

Remarks

If the property is a COM object, 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 in order to overload the GetProperty method. Overloading would not be possible if the property value were simply 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 exception, COMException, 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);

SetProperty

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:

  • boolean

  • byte

  • char

  • short

  • int

  • long

  • float

  • double

  • java.long.String

  • oracle.win.com.Automation

  • oracle.win.com.Currency

  • java.util.Calendar

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 exception, COMException, is thrown if an error occurs.

Code Sample

See "GetProperty" for sample code.

InitArg

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.

SetArg

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 numbers of times SetArg has been called after an InitArg call.

allowed_type

from the following list.

  • boolean

  • byte

  • char

  • short

  • int

  • long

  • float

  • double
  • java.long.String

  • oracle.win.com.Automation

  • oracle.win.com.Currency

  • java.util.Calendar

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.

Invoke

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, 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 in order to return the property.

allowed_type

a type from the following list:

  • boolean

  • byte

  • char

  • short

  • int

  • long

  • float

  • double

  • java.long.String

  • oracle.win.com.Automation

  • oracle.win.com.Currency

  • java.util.Calendar

Remarks

If the COM method returns a COM object as the return value, 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.

In order 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 simply 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 exception COMException 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];

Currency Constructor

Creates a currency Java object.

Syntax

public Currency(long value)

Where Is

value

the 8-byte CURRENCY number.

Get

Gets the 8-byte CURRENCY number.

Syntax

public long Get()

Remarks

Returns the 8-byte CURRENCY number.

Set

Sets the 8-byte CURRENCY number.

Syntax

public void Set(long value)

Where Is

value

the 8-byte CURRENCY number.


Go to previous page Go to next page
Oracle
Copyright © 1999, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback