This appendix contains these topics:
The following is a list of Oracle COM Automation Feature PL/SQL errors and their common causes.
CreateObject as well as COM objects obtained as property values and return values.pexcepinfo should be filled in GetLastError to get this additional informationInvoke tried to set the value of a read-only property.The following is a list of Microsoft COM Automation errors and their common causes. Both the hexadecimal and binary error codes are listed.
NULL value was passed as a method parameter.NULL.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 data types, and Oracle COM Automation Feature uses either PL/SQL or Java data types, 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 data types and COM Automation data types.
This guide follows a convention where COM Automation data types are prefaced by an initial p when used as IN OUT or OUT parameters. Data types without the initial p are IN parameters.
Table 3-1 PL/SQL to COM Automation Data Types
| PL/SQL Data Type | COM Automation Data Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note: Oracle restricts aCY and pCY value to be between -9999999999.9999 and 9999999999.9999. |
Table 3-2 lists the supported COM Automation data types and related mappings to Java data types.
All data type mapping applies to properties, arguments, and return values, except void, which applies only to return values.
Table 3-2 Java to COM Automation Data Types
| Java Data Type | COM Automation Data Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 about 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 about 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 |
|---|---|
|
|
is an |
|
|
is the textual representation of |
|
|
is the |
|
|
is the error description. |
|
|
is the fully qualified path name of the |
|
|
is the help context ID of a topic within the |
|
|
is |
Code Sample
This example demonstrates the COMException exception.
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);
}
}
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 data type 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 data type, such as INT or BSTR. The GetProperty and SetProperty APIs take the property name and a variable of the appropriate data type. Methods are referred to by a descriptive string, such as InsertChart. A method takes a set of parameters that are of different COM Automation data types and returns a COM Automation data type.
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 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
To prepare for the Invoke call, you use InitArg and SetArg 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 interfaces associated with the object.
This function 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 interfaces associated with the object.
This function 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 function 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 returns the property value of a COM Automation object.
Syntax
FUNCTION GetProperty(objecttoken BINARY_INTEGER, propertyname VARCHAR2, argcount BINARY_INTEGER,
propertyvalue OUT any_PL/SQL_data type) 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 data type that is returned. You must pass the PL/SQL data type that corresponds to the COM Automation data type of the COM Automation property. Otherwise, the COM Automation Feature will not properly convert the COM Automation data type. |
any_PL/SQL_data type | any data type supported by COM Automation Feature. |
Remarks
If the property returns a COM object, then you must specify a local variable of data type 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 function 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_data type, data type 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 data type. |
data type | the explicitly specified data type of the value passed in. The available data types are:
|
any_PL/SQL_data type | any data type supported by COM Automation Feature. |
Remarks
This function 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 data type 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_data type, 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 data type of the parameter. |
The available data types are:
| |
any_PL/SQL_data type | any data type supported by COM Automation Feature. |
Remarks
See the section on SetArg data type 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_data type, data type 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. |
data type | the explicitly specified data type for the parameters.
Those data types prefaced by an initial |
Those data types without the initial p are IN parameters. The available data types are:
| |
| |
| |
| |
any_PL/SQL_data type | any data type 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.
Data types without the initial p are IN parameters. Those data types 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_data type) 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 data type. |
any_PL/SQL_data type | any data type supported by COM Automation Feature. |
Remarks
If the return value of the function is a COM object, then the developer must specify a local variable of data type 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 function 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 data type. 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 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.
Automation excel = new Automation("Excel.Application",
"\\ServerName");
// 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 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 system.
excel.Create("Excel.Application", "\\ServerName");
// 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 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 data type. |
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 data type. 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 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];
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.
Developer's Guide
11g Release 2 (11.2) for Microsoft Windows
E10591-05
January 2011
Oracle COM Automation Feature Developer's Guide, 11g Release 2 (11.2) for Microsoft Windows
E10591-05
Copyright © 1999, 2011, Oracle and/or its affiliates. All rights reserved.
Primary Author: Tulika Das
Contributors: Neeraj Gupta, Janis Greenberg, Eric Belden, Steven Caminez, Jagadish Changavi, Barmak Meftah, Valarie Moore, Vikhram Shetty, Sujith Somanathan, Alex Keh, Christian Shay, Riaz Ahmed
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Component Object Model (COM)
A binary standard that enables objects to interact with other objects, regardless of the programming language that each object was written in
Distributed Component Object Model (DCOM)
An extension of COM that enables objects to interact with other objects across a network
external procedure
A function written in a third-generation language (3GL), such as C, and callable from within PL/SQL or SQL as if it were a PL/SQL function or procedure
GUID
An identifier that uniquely identifies a COM object. GUID is an acronym for Globally Unique Identifier
listener
The server process that listens for and accepts incoming connection requests from client applications. Oracle listener processes start up Oracle Database processes to handle subsequent communications with the client
listener.ora
A configuration file that describes one or more Transparent Network Substrate (TNS) listeners on a server
messaging application programming interface (MAPI)
A messaging architecture composed of a set of common application programming interfaces that enables multiple applications to interact with multiple messaging systems across a variety of hardware platforms
Optimal Flexible Architecture (OFA)
A set of file naming and placement guidelines for Oracle software and databases
Oracle COM Automation Feature
An Oracle feature that enables PL/SQL developers to programmatically manipulate COM objects through the IDispatch COM Automation interface
Oracle Net
The Oracle client/server communication software that offers transparent operation to Oracle tools or databases over any type of network protocol and operating system
This document is your primary source of introductory, installation, postinstallation configuration, and usage information for Oracle COM Automation Feature.
|
Note: Oracle Database 11g Release 2 (11.2) is the last database version that supports Oracle COM Automation feature. Oracle Database versions, which are released after Oracle Database 11g Release 2 (11.2), will not support Oracle COM Automation feature. You can continue to use Oracle COM Automation feature with existing Oracle Database versions that are covered under the lifetime support policy of Oracle. |
This document describes the features of Oracle Database for Windows that apply to the Windows 2000, Windows XP, and Windows Server 2003 operating systems.
This Preface contains these topics:
Oracle COM Automation Feature Developer's Guide is intended for developers who develop solutions that use COM.
To use this document, you need familiarity with:
Component Object Model (COM)
OLE Automation
Structured query language (SQL)
Data definition language (DDL)
Data manipulation language (DML)
PL/SQL or Java
Oracle object-relational database management system (ORDBMS) concepts
Windows Server operating systems
Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.
Accessibility of Code Examples in Documentation
Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.
Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.
For more information, see these Oracle resources:
For information about Oracle error messages, see Oracle Database Error Messages. Oracle error message documentation is available only in HTML. If you only have access to the Oracle Documentation CD, you can browse the error messages by range. Once you find the specific range, use your browser's "find in page" feature to locate the specific message. When connected to the Internet, you can search for a specific error message using the error message search feature of the Oracle online documentation.
Many of the examples in this book use the sample schemas of the seed database, which is installed by default when you install Oracle. Refer to Oracle Database Sample Schemas for information about how these schemas were created and how you can use them yourself.
The following text conventions are used in this document:
| Convention | Meaning |
|---|---|
| boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. |
| italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. |
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |
3;P]># {DlĜ j P>0t` \`t`͒V,MH ,bV!T
j&[X`Y@ PPsǫ{o%Gߡ!z-e- 8m!ײ #+ L5| ɒΖ<ę I\Ͽrt[A
9T {
\ m E ,p1x cfP Bcl+)7d_; y
@Xa ^0$9m\ BMԌ\HKM,ĘG ՟LգiY{.L0-P >`Fe*`[ [~o} q$ [$#@@1PRj & % *}ؤ;[xQZ%P `YB [(m~00\ԍJήԱ
՝\L| w_*SSs߰
+wcU7k LbU@#`Y) [$(m߆ëA @W-0 1& & JDA3!P a3@2@?o5ȥ FmάN-,7cV pW z5, t$^HC +b./ X A 0?
_ epy,{&%< a,
7< xu ė ) Ef@/,RሎኜG:Oɴ=%h.: c0% {g_tX X{ Mp!M 'p .MׯOp | <&\~ؾ#P;~E@
@ˡ G` -
3葖
*l ?N<ɏ#UmW @t7\3P] B9 U0x pN&y &+0*n`P{VگWkԮ:G0^0Cp ~3~A'ڄ@!0F ~pj/` %`0 F=利 ".ϕ'
2 KWP,wmE P[[KsHqNLU
L!~~ `bb-1-]\\+BXX\bXMMOOd11 d__-f6 e!5" j)]~$3~,)^MR(" aÓ D1B|"J 7`! dkE.`F0x b 1 .A/p`a6РpA1P
,PA pF <\=` ř *ZYCI23AI& ,/|)0 j$Q&U`R@K 0Ä&>2tÆ
V"8j1L3ǒ1kLā\2N K
* 碆
^3cLqBK |"]0A'HNEeQG 4RI'RK/4SM7SO?5TQG%TSOE5UU\\6k T$H` 5Vix Hh10 lD6I%Y&B@[e0X@ (`EGPpF "4- H BJ_0 p!Ԑ_06z ̡ rƢU'%N~ ,8a0I/ .A a ~ K FaÑG DI(ĒK0DM8ēO@ EQH)ŔSPIEUX Wr1 EV8PA K0!`a [yBZ[݁DtIF$e<K0 ~ C 2dȐ!C 2dȐB}2dȐ!C ǐ!CO@
D? 4xaB ǐ!C 2d8P ?
!C 2dȐ!C 2dP>~ 2dȐ!CcȐ!C1d0 C 2T C 2dȐ@}2dȐ!C 2dȐ!C 2dxP ? 2dȐ!Á1dȐ@}2d!C p`> 2dȐ!CcȐ!C 2dȐ!C 2dȐA}2dȐ!C ǐ!CcȐa~1dȐ@~0? 2dȐ!Á1dȐ!C 2dȐ!C 2d>~ 2dȐ! ~ 8`A&,ϟB
ׯB
*0@'p| 8`A&TaC9t(_? :tСC :tСA} : ~ C 2dȐ!C 2dȐB}2dȐ!C ǐ!C8`AO@
DPB1dȐ!C Ǐ!CcȐ!C 2dȐ!C 2T C 2dȐ@~2d @,hA$XA .$ C 2dȐ@}24د? 2dȐ!C 2dȐ!C1dȐ!C 䧏!C 2dȐ!C !C 2dp>~ 2dȐ!C 2dȐ!C 2 QD-ŋwA$XA H| |3h ~4hРA
4h0_>}O~ H*\ȰÇ#JHE]xA}.^xExb| O| H*\Ȱ#JHE]xA}.^xE]X1_>}'p`>~ H*\ȰÇ#JH H*\ȰB~ H*\ȰÇ#JH`|
O H*\ȰÇ#JH H ˗/a &$ <0
:|1ĉ˧> ? 4xaB 6tbD)VxQ|0bĈ#B1b4 Fӗ0_>}1bĈ#F1bĨP_|1bĈa>1 Fӗ0_>}1bĈ#F1bĨP_|1bĈ|0bX_?1J̗O_|aĈ#F1bĈB}aĈ#ƃÈc~aП?ϟ?Ӈ#F1bĈ#F
ˇ#F
˗/>1 F'p~ />$XA .dC%NXES#F%O@ H*\П? 2d8 |O|'p "Lp!Æ B(q"Ŋ/Zԗ/|0bĈ1>
<0
:|>? <0
:|1ĉ+ZhQ_| Ӈ#F'p`> H*\ȰÇ O@} /_>} H*\ȰÇ#JHŋˇ_|aĈC <0
cȐ!C'P?/>$XA .dC%NXEC/_|0bĈa? ? 4xaB !C ̗/_>}ǐ!C 2dȐ!C 2dȐ!C 2dP_|'P`?$XA .d!}˗/>}=|a~=|a}0_>} >|Ç >|Ç >l/_ 8? 4xaB 6t0_| >|P`~ >|`|˧Ç >|Ç >|Ç
g | <0
:|(_? >|h_>{Ç >|Ç >|aC}O H*\ȰÃ{Ç{C˧Ç >|Ç >|Ç
W | <0
:4/_ >|Ç˧Ç >|Ç >|Ç
W ?~Ǐ ?~ >|C{Ç'p "L_|.\? 4xaB 6tbD)V/_| wŋwE]0 <0
* <0
:|1ĉ+Z/_xŋx"~Yŋwŋ/^xK/_/^/_/"ϟE}.^x ?}/^xŋ/^/_xŋx"~Yŋwŋ/^xK/_/^/_/"ϟE}.^x ?}/^xŋ/^/_xŋx"B.wŋxŋ/^x|%ԗ/ŋ/^O ,h
2lP ? :t?~ :tСC :tСC :/_sСC : /_> :t!A} :tСCsСC :tСC :tP`|˗ϡC :tp`| :tA &ϡC :t> :tСC :tСC /_|WP_| :tСCСC!B} :tСCsСC :tСC :tp |@O@
DPB
*̗/Ç >د{ÇÇ >|Ç >|`>'p| 8`A&TaC
ÇA} >/_| {h0Ç{Ç >|Ç >\`>O@}'p "Lp!Æ˗Ç
Ã=|(0|
{p ?} >|Ç >|Ç 80 ӗ/ ,h
2lPa| >|@ "Co_?}ۗO|˗?/Ç{Ç >|Ç >d`>'p?}'p "Lp!Æ˗Ç >dÇO|o߿|/߿|/Ç{Ç >|Ç >l0@ (P_| H*\ȰC{Ç|_>70߿| 7 |=|8 >|Ç >|Æ| >|Ç
Ç>~
W_>O__>$X'p "Lp!Æ B(q"Ŋ˗/|.^xb|.^_?0_| O'0| _
xŋ/^x~%ԗ/ŋ/^̗/ŋϢ>~'P ?~?}_'_ 8`A <0
:|1ĉ+ZO|.^xb|.^_?xŃ]xŋ/^x|.^xb|.^_?xŃ]xŋ/^x|.^xb|.^П]xA~.^xŋ/^ ?~O@
,h
2l`| >|C=|Ç {Ç >|Ç >>} O @~O>ǯ ,h
2lP`| >|C=|Ç {Ç >|Ç 6/_|!B˗/_} >|Æ{Ç{P ˗C >lOÇ >|Ç >|P!?}C˗/߾~ >||=|C{xP !| 6Ç >|Ç >|p_|=| |{Ç˗Ç
Ã=do`>ۗO} ܗ߿|O}'p
? 4xaB 6tbD)Vܗ/
ۗ/ +Vd/_+: B
h0~o?~Ǐ } | /_?~W!?}+VXbŊ+N/ ˗_Ŋ+*̗/_Ŋ !|W`|_70__櫈+VXbŊ%˷bEWbŊ WbE%/_~ h0|
̗ |/߿/߿8`A <0
:|1ĉ#ǯbňXbEXbE ( Ǐ A |O>~?~O`O$H A <0
:|1ĉ!ׯbʼnXbŃO@
DPB
'p> ,h`>˗ϟ?}/_~ӗO|ϟ| ˷|!4O ,h
2l!Ĉ'Rh"ƌY/_~˗|`_|߾|'П|]o? This chapter provides an overview of the Oracle COM Automation Feature installation and postinstallation configuration tasks. This chapter contains these topics: The Oracle COM Automation Feature package is included as part of the Oracle installation. It contains the features and demos that illustrate how to use this product to solve real-world problems. The COM Automation package includes the following PL/SQL and Java components: The PL/SQL components for Oracle COM Automation Feature are: Oracle COM Automation demonstration programs Message files (such as Oracle COM Automation PL/SQL feature All other components are located in the The Java components for Oracle COM Automation Feature are: The JAR file, Oracle COM Automation demonstration programs Oracle COM Automation Java feature Oracle COM Automation Feature requires: Windows XP, Windows Server 2003, Windows Server 2003 R2, Windows Vista, Windows 7, Windows Server 2008, Windows Server 2008 R2 A functioning database Note that you must have a COM Automation server in the system to use Oracle COM Automation Feature. For example, the COM Automation Feature demos require that you first install the applications that are used in the demonstration programs: The Microsoft Word, Excel, and PowerPoint demos require Microsoft Office 2000 or later. The messaging application programming interface (MAPI) demo requires Microsoft Outlook 2000 or later. The demonstrations and installations are discussed in "Overview of Oracle COM Automation Feature for PL/SQL Demos" and "Overview of Oracle COM Automation Feature for Java Demos". To upgrade Oracle COM Automation Feature from Oracle Database 10g Release 2 or Oracle Database 11g Release 1 to Oracle Database 11g Release 2, do the following: Configuration procedures differ for PL/SQL and Java as explained in the following sections: To configure Oracle COM Automation Feature for PL/SQL: Start SQL*Plus. Connect to the database as Grant the Connect to the user who will use Oracle COM Automation Feature, and run the In the preceding command, You will receive several Perform the following to configure Oracle COM Automation Feature for Java: Connect to the database as Run the Run the In the preceding command, This section describes the specific configurations for the listener.ora and tnsnames.ora files when used with Oracle COM Automation Feature for PL/SQL. Note: Because Oracle COM Automation Feature for PL/SQL relies on listener callouts, you must configure the listener and Oracle Net remote procedure call (RPC) mechanism for the feature to work. The following are examples of listener.ora and tnsnames.ora files that can be used with interprocess communication (IPC) to invoke external stored procedures. See Also: listener.ora Configuration File tnsnames.ora Configuration File An "ORA-28575: unable to open RPC connection to external procedure agent" error message indicates one of two possible listener problems. Problem 1 Problem: The listener is not started. Action: You must start the To start Oracle services from the Control Panel: Choose Start, Settings, and then Control Panel. The Control Panel window appears. Double-click Services. The Services dialog box appears. Go to To start Oracle services from the command prompt: Enter the following command: In the preceding command, service is a specific service name, such as Problem 2 Problem: The listener is not configured correctly. Action: You must modify the Oracle COM Automation Feature supports the use of Distributed Component Object Model (DCOM) to access remote Component Object Model (COM) objects over a network. To authenticate the client's access to the remote computer, DCOM passes the appropriate security credentials to the remote computer. The remote computer validates the security credentials and allows DCOM to proceed. These security credentials are based on the domain user's privileges associated with either the client's listener service or database service. Table 2-1 indicates the determining service for COM Automation for PL/SQL and Java. To use DCOM, you must configure security settings on the following: The computer that is running the database instance The computer that contains the remote COM object The configuration for the computer running the database instance requires setting the listener and the database service to the same domain user. In this procedure for setting a service to a domain user, the service to be set is selected in Step 3. You must follow this procedure twice, first to set the listener and then to set the database service. The order is unimportant. To set a service to a domain user: Choose Start, Settings, and then Control Panel. The Control Panel window appears. Double-click Services. The Services dialog box appears. Select the service and click Startup. The service should be either Select the This Account option. Enter the name or browse for a domain user. Enter and confirm the password of the selected domain user. Click OK to save the changes. Configuring the computer containing the remote object requires using the This tool enables you to set the access permissions, launch permissions, and configuration permissions for a specific COM object or all COM objects on a computer. Using the Set the DCOM security privileges so that the appropriate service (that is, listener for PL/SQL and database service for Java), operating as a domain user, has sufficient privileges to instantiate and manipulate the remote COM object. Set the remote COM object to execute with the same privileges as the service. If the COM object attempts to perform an action for which it does not have permission, DCOM denies the operation and returns a security violation to Oracle COM Automation Feature. It is essential that you configure the DCOM security properly and provide the Oracle Database with the necessary permissions. See Also: Using the Setting up the client and server computers to use DCOM This illustration shows two spaces, the Oracle process space and the external process space. The Oracle process space includes the Oracle database and database instance, COM Automation Feature, Automation class, and possibly user-written Java stored procedures. The external process space contains the COM Automation server. The COM feature communicates by COM or DCOM with a COM Automation server and returns a result to the COM feature, then communicates back to the database. This illustration shows the Microsoft OLE/COM Object Viewer, opened to the IDispatch interface for the Microsoft Excel Chart. The registry portion of the Viewer shows the Interface number and the CLSID number. This illustration shows an Oracle database with the COM feature in the center with incoming and outgoing connections. Client PCs make incoming connections through Oracle Net to the database. The diagram shows three client PCs, but the number is unimportant. From the Oracle database, arrrows indicate outgoing connections to the following: Microsoft Office (Word, PowerPoint, and Excel), any COM Automation Server, and MAPI-Compliant Applications). The APIs provided by Oracle COM Automation Feature are used by the client PCs in connection with the software applications listed. This illustration shows two spaces, the Oracle process space and the external process space. The Oracle process space includes the Oracle database and database instance, and possibly user-written PL/SQL scripts (that is, stored procedures, functions, or triggers). The external process space contains the COM feature in which the external procedures reside. The external process space also contains the Oracle listener and external procedure handler. In the Oracle process space, the PL/SQL script accesses the database, and in the external process space, the script starts the Oracle listener, which activates the external procedure handler. Once the external procedure handler is activated, it activates the COM feature. The COM feature communicates with a COM Automation server by COM or DCOM and returns a result to the COM feature. The COM feature then passes the result to the external procedure handler, which then communicates back to the database. This chapter describes the Oracle COM Automation Feature Software Development Kit (SDK) and provides an overview of the product. Read this chapter before installing or using Oracle COM Automation Feature. Note: This chapter contains these topics: Oracle COM Automation Feature enables you to use Component Object Model (COM)-based components to customize and enhance the functionality of the Oracle database on Windows operating systems. You can build your own custom components or use the thousands of prebuilt components that are available from third-party independent software vendors (ISVs). Oracle COM Automation Feature provides a mechanism to manipulate COM objects through either PL/SQL or Java. Oracle COM Automation Feature acts as a generic wrapper around the Oracle COM Automation Feature externalizes all methods supported by the COM objects expose properties, data attributes, and methods (functions that perform an action) to the developer. The Gets the value of an exposed property Sets the value of an exposed property Invokes a method on an object When an Oracle COM Automation Feature application programming interface (API) is invoked from PL/SQL or Java stored procedures, Oracle COM Automation Feature converts the parameters to the appropriate COM Automation data types and then invokes the corresponding See Also: Oracle COM Automation Feature for PL/SQL provides a PL/SQL package and exposes a set of application programming interfaces (APIs) to instantiate COM objects. Developers can call these APIs from PL/SQL subprograms, stored procedures, stored functions, or triggers to manipulate COM objects. There are no restrictions concerning where these COM objects reside. They can be local to the database or accessed remotely through the Distributed Component Object Model (DCOM). Oracle COM Automation Feature for Java provides a set of Java APIs to instantiate COM objects. Developers can call these APIs from Java stored procedures, Java functions, or Java triggers to manipulate COM objects. Oracle COM Automation Feature for Java does not allow in-process COM Automation servers. Developers can use Oracle COM Automation Feature is a powerful and enabling infrastructure technology for Oracle developers on Windows. It has the following advantages: Ease of Development Oracle COM Automation Feature exposes a simple set of APIs to manipulate COM objects. If you are familiar with COM and Microsoft Visual Basic, you can easily incorporate these APIs into your PL/SQL subprograms or Java programs. Reusability Oracle COM Automation Feature enables you to leverage prebuilt COM components that have been developed in-house or by third-party independent software vendors (ISVs). In addition, there are thousands of existing COM components from which you can choose. The COM component market is expanding rapidly and offers solutions to many common programming problems. Flexibility and Extensibility You can use Oracle COM Automation Feature to customize and enhance the functionality of the database server. Through the use of COM components, the Oracle database can be customized to: Exchange data among productivity applications, such as Microsoft Word, Microsoft Excel, and Microsoft PowerPoint. Generate reports using Seagate Crystal Reports. Send and receive e-mail with MAPI-compliant applications. The possibilities for customization and extensibility of the database server are limitless. Enhanced Integration Oracle COM Automation Feature enables you to deploy Oracle Database in a combined Oracle and Windows environment. You can be assured that Oracle COM Automation Feature integrates fully with and capitalizes on the services that are exposed by Windows, Microsoft BackOffice applications, and Microsoft Office applications. Portability and Platform-Specific Requirements Applications using Oracle COM Automation Feature are written in Java or PL/SQL, which are platform-independent. Only the database instance that needs to invoke COM components must be run on Windows. Figure 1-1 illustrates the interaction between an Oracle database with Oracle COM Automation Feature, client applications, and server applications. The architectural differences between Oracle COM Automation Feature for PL/SQL and for Java are described in the next two sections. Oracle COM Automation Feature for PL/SQL provides a package of PL/SQL APIs for manipulating COM objects. These APIs are implemented as external procedures in a dynamic-link library (DLL). Oracle supports external procedures that enable developers to call third-generation language (3GL) functions from server-based object type methods and stored procedures. External procedures are invoked exactly like standard PL/SQL stored procedures. However, unlike standard PL/SQL procedures where the body of the procedure is written in PL/SQL and stored in the database, external procedures are functions in the C programming language that reside within a DLL. You can invoke Oracle COM Automation Feature APIs in the same manner in which you call a standard PL/SQL stored procedure or function. Figure 1-2 shows an Oracle database invoking COM Automation external procedure APIs. Figure 1-2 COM Automation Feature Architecture for PL/SQL The database server invokes any of the COM Automation external procedure APIs as follows: The PL/SQL interpreter looks up the path name to the Oracle COM Automation Feature DLL ( The PL/SQL interpreter sends a message to the listener using Oracle Net to start The PL/SQL interpreter passes the procedure name, the parameters, and the path name of the DLL to The The dependence on external procedures by Oracle COM Automation Feature for PL/SQL has implications for the availability of the database server. You do not jeopardize the availability of the database server by using Oracle COM Automation Feature and custom or third-party COM objects in a production environment. Oracle COM Automation Feature operates outside of the Oracle kernel's address space. This safeguards the Oracle database from COM objects that stop abruptly. Oracle COM Automation Feature for Java is implemented by the Java Native Interface (JNI). The key components of this architecture are the The interface is the The Java-specific COM proxy, Figure 1-3 illustrates implementation of Oracle COM Automation Feature for Java. Figure 1-3 COM Automation Feature Architecture for Java This chapter describes how to use the demonstration program designed for Oracle COM Automation Feature for Java. This chapter contains these topics: Oracle COM Automation Feature for Java includes an example that demonstrates how to use the feature to build solutions. The demo provides base functionality and can serve as a foundation on which to build more customized, complex applications that use COM Automation. This demo is based on the human resources schema available with the sample schema. The demo exposes a core set of APIs that enable you to do simple operations using Oracle COM Automation Feature. Each COM Automation server, such as Word and Excel, provides more advanced capabilities than what is offered through the demo APIs. To take advantage of these advanced features, you must design and code your own Java classes. In this release, COM Automation has provided the Microsoft Word Java Demo, which exchanges data between an Oracle Database instance and Microsoft Word. The following sections describe how to install the Microsoft Word Java demo and the APIs that it exposes. This demo is provided as an example of the types of solutions that can be built with Oracle Database and Microsoft Word. The demo creates a Microsoft Word document containing the names of employees in the database. The Microsoft Word Java demo is installed in the Microsoft Word must be installed on the local computer before you install this demo. To install the demo: Run the Start SQL*Plus. Connect to the Oracle Database instance as the user who will use the Microsoft Word demo. For example: Run the To use the Word demo: Set Call This creates a Microsoft Word document ( The public class To create a custom application that uses this wrapper: Instantiate an object of this class. Create the Create a new Microsoft Word document with the Use the Save the document with the Call the Call the The following subsections describe the APIs that the Microsoft Word Java demo exposes. These APIs are primitive and do not expose all the functionalities that Microsoft Word exposes through COM Automation. This API is the constructor. It does nothing. Syntax Creates the Syntax This API destroys the Syntax This API creates a new Microsoft WORD document. Syntax Remarks This API is a wrapper for the This API loads an existing Microsoft WORD document. Syntax Remarks This API is a wrapper for the This API sets the font size. Syntax Remarks This API is a wrapper for the This API inserts text into the Microsoft Word document. Syntax Remarks This API is a wrapper for the This API inserts a new line into the Microsoft Word document. Syntax Remarks This API is a wrapper for the This API saves the Microsoft Word document using a specified name. Syntax Remarks This API is a wrapper for the This API saves the Microsoft Word document. Syntax Remarks This API is a wrapper for the This API closes the Microsoft Word document, and exits Microsoft Word. Syntax Remarks This API is a wrapper for the Copyright © 1994-2012, Oracle and/or its affiliates. All rights reserved. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services. If this document is in prerelease status: This documentation is in prerelease status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation. This chapter describes how to use Oracle COM Automation Feature demonstration programs for PL/SQL. This chapter contains these topics: Oracle COM Automation Feature for PL/SQL includes examples that demonstrate how to use the feature to build solutions. These demos provide base functionality and can serve as a foundation on which to build more customized, complex applications that use COM Automation. The demos are based on the human resources schema available with the sample schema. Each demo exposes a core set of APIs that enables you to do simple operations using COM Automation. Each COM Automation server, such as Word and Excel, provides more advanced capabilities than what is offered through the demo APIs. To take advantage of these advanced features, you must design and code your own PL/SQL procedures. In this release, COM Automation has provided the following demos: Microsoft Word Demo - Exchanges data between Microsoft Word and Oracle Database Microsoft Excel Demo - Exchanges data between Microsoft Excel and Oracle Database Microsoft PowerPoint Demo - Exchanges data between Microsoft PowerPoint and Oracle Database MAPI Demo - Exchanges data between Messaging Application Programming Interface (MAPI) compliant applications and Oracle Database The following sections describe how to install the Microsoft Word demo and the APIs that it exposes. This demo is provided as an example of the types of solutions that can be built with Oracle Database and Microsoft Word. The demo creates a Microsoft Word document containing the names of employees in the database. The Microsoft Word demo provides the following: Microsoft Word must be installed on the local computer before you install this demo. To install Microsoft Word demos: Start SQL*Plus. Connect to the Oracle database instance as the user who will use the Microsoft Word demo. For example: Run the This script creates the These messages are normal. To use the Microsoft Word demo: Run the This script creates a Microsoft Word document ( Open the The following subsections describe the APIs that the Microsoft Word demo exposes. These APIs are primitive and do not expose all the functionalities that Microsoft Word exposes through COM Automation. This API instantiates a Syntax Remarks This function must be called before any other operation can be performed. This function returns This API creates a new Microsoft Word document. Syntax Remarks This function returns This API loads a document into Microsoft Word. Syntax Remarks This function returns a This API saves the current Microsoft Word document to disk. Syntax Remarks This function returns This API saves the current Microsoft Word document as a specific file. Syntax Remarks This function returns This API closes the current Microsoft Word document. Syntax Remarks This function returns This API inserts a text string into the current Microsoft Word document. Syntax Remarks This function returns This API inserts a new line into the current Microsoft Word document. Syntax Remarks This function returns This API sets the font size for the current Microsoft Word document. Syntax Remarks This function returns The following sections detail how to install the Microsoft Excel demo and describe the APIs that it exposes. This demo is provided as an example of the types of solutions that can be built with Oracle and Microsoft Excel. The Microsoft Excel demo provides the following: Microsoft Excel must be installed on the local computer before you install this demo. To install the Microsoft Excel demo: Start SQL*Plus. Connect to the Oracle Database instance as the user who will use the Microsoft Excel demo. For example: Run the This script creates the These messages are normal. To use the Microsoft Excel demo: Run the This script creates a Microsoft Excel spreadsheet ( Open the The following subsections describe the APIs that the Microsoft Excel demo exposes. These APIs are primitive and do not expose all the functionalities that Microsoft Excel exposes through COM Automation. This API starts the Microsoft Excel COM Automation server and instantiates the objects for a workbook and a worksheet. Syntax Remarks This function returns This API inserts any kind of data into a specific cell of the current Excel worksheet. Syntax Remarks This function returns This API creates a chart of a specified range of data and inserts the chart at the x and y position of the current worksheet with the desired height and width. Syntax Remarks This function returns This API saves the current Microsoft Excel workbook as a specific file. Syntax Remarks This function returns Performs some cleanup and destroys the outstanding references to the Excel COM Automation server. This should be the last API called. Syntax Remarks This function returns a The following sections detail how to install the Microsoft PowerPoint demo and describe the APIs that it exposes. This demo is provided as an example of the types of solutions that can be built with Oracle Database instance and Microsoft PowerPoint. The Microsoft PowerPoint demo provides the following: Microsoft PowerPoint must be installed on the local computer before installing this demo. To install the Microsoft PowerPoint demo: Start SQL*Plus. Connect to the Oracle Database instance as the user who will use the Microsoft PowerPoint demo. For example: Run the This script creates the These messages are normal. To run the Microsoft PowerPoint demo: Run the This script creates a Microsoft PowerPoint presentation ( Open The following subsections describe the APIs that the Microsoft PowerPoint demo exposes. These APIs are primitive and do not expose all the functionalities that Microsoft PowerPoint exposes through COM Automation. This API starts the Microsoft PowerPoint COM Automation server and instantiates the objects for a presentation. Syntax Remarks This function returns This API inserts a new slide in the PowerPoint presentation. Syntax Remarks This function returns This API specifies the title of the PowerPoint slide. Syntax Remarks This function returns This API inserts text into the specified location on the slide. Syntax Remarks This function returns This API saves the current PowerPoint presentation. Syntax Remarks This function returns This API saves the current presentation using the specified name. Syntax Remarks This function returns This API closes the current PowerPoint presentation. Syntax Remarks This function returns This API exits the PowerPoint program. Syntax Remarks This function returns The following sections detail how to install the messaging application programming interface (MAPI) demo and describe the APIs that it exposes. This demo is provided as an example of the types of solutions that can be built with an Oracle Database instance and MAPI-compliant applications. The MAPI demo provides the following: You must set up certain related applications to use the MAPI demo. Note: To set up the environment for the MAPI demo: Install Exchange Server and create a new account as follows: Select Start, Programs, Microsoft Exchange, and then Active Directory Users and Computers. Select your domain and expand the folders. Select users and right-click to create a new user. Install Microsoft Outlook as follows: Select Custom Install. Select Collaboration Data Objects. Note: Select the Corporate or Workgroup option. Configure Microsoft Outlook and set connection information as follows: Add the account that you created on Exchange Server. Enter your incoming and outgoing mail servers, and enter the account name and password. Select the connection type (for example, LAN). Set Microsoft Outlook as the default program for the e-mail, newsgroups, and calendar tools as follows: From Internet Explorer, choose Tools, Internet Options, Programs and set the fields. Patch Update the registry settings by double-clicking The MAPI Solution invokes Extended MAPI client on behalf of the Oracle Database server. The Oracle Database service on Windows 2000 and higher, by default, runs as the system user To prepare to install the MAPI demo: Log on to Windows using your local user account or domain user account, for example, Start the MAPI server (for example, Microsoft Outlook) and configure the MAPI profile for the Windows 2000 and higher user Go to Windows Control Panel/Services. Shut down the Select the Change the Log On As to This Account and fill in Enter the password and confirm the password for Restart the Shut down the Oracle Database service. Select the Oracle Database service and click Startup. Change Log On As to This Account and fill in Enter the password and confirm the password for Restart the Oracle Database service. The MAPI application, such as Microsoft Outlook 2000 or later, must be installed on the local computer before you install this demo. To install the MAPI demo: Start SQL*Plus. Connect to the Oracle Database instance as the user who will use the MAPI demo. For example: Run the This script creates the These messages are normal. To use the MAPI demo: Open Run the This script connects to a database server, extracts the data, and sends an e-mail to a specified recipient. The following subsections describe the APIs that the MAPI demo exposes. These APIs are primitive and do not expose all the functionalities that MAPI exposes through COM Automation. This API starts the MAPI COM Automation server and instantiates the objects for a session. Syntax Remarks This function returns This API creates a new message. Syntax Remarks This function returns This API adds the e-mail address of a recipient. This is the address where the e-mail message will be sent. Syntax Remarks This function returns a This API specifies the subject of the e-mail message. Syntax Remarks This function returns This API inserts the body text of the e-mail message. Syntax Remarks This function returns This API sends the e-mail message to the specified recipients. Syntax Remarks This function returns This API exits the MAPI session. Syntax Remarks This function returns n+ӐhqH9P߳&2чev 1?gM
ZS @r5\YT
e;N;qj)]^!@pW@u?wh=4-Q (GD=}ƤptAb3uQ0F#©>2 ^xHDIpkcN:~ #XIĎ$̃5HprKd)MEbI$Ǽ&Yyp49K?2)}ݤOX$ֵ J5E ػ% cكK ā(Nf9af1:4sJ{DgA3=YM d"8(JS
FgA9!
6;`Nr}=iOm{g-q́r2&l)K*f]D\4ceIKKzԧT6 zԁA پՅSU
!PiY/0Qsw`r}x
MiUc6JUhIzm l$7RꓞCէIԟރ):AY0
&u\95$K" vD+'"PƳ9%HsM8pc$..;Ҷ5T 5ٔiTh ,SC ^e2m
ۦ;Z[K8trIjZi!O}{6U]D :$ acZ
ElЙTr8l\jˣ8 h2z8i{S JkCbA!$1r`'&m%>̨2=+/ BQ4 @[8Jx9ʄU8YmY@*w~( ^ȍrsqZIkgT45^ Ψ+UZc,1Ӕ] ^r:[]XG )Ϩ>Yl^''^z%= h˴Mƥy=cMLwB#Wy3WvF;zųFе^2]"hE`'̔v FτfxzvfʖҰluxYkF?]Mu Q5Uٴa&oÔ
}6vz9ʏsh[-k U']ypJfGA^9g._zo;ŗu8{] 7דcf)C'n[?kk;ޛE*Гe]l{ԩ3`ꃷ%9a_<|Dilq0*5K
'y콴ej}_k{Si6ml('HAӫ{O 2YQmaF$a}x {#&{p_F_~U_cz?C3DrjssR>0Ip=T-,p18b?D@ɵ6xj2FA\ ByIc+>{9t)ۭ&ST5! =CB|:1 C54%B˼78 AIs[{7b# 0)sCS!(l9qH*l03,H> L(B4$SDB
PK 7h] c] PK AA OEBPS/img_text/comdg003.htm}
2 Installing and Configuring Oracle COM Automation Feature
Oracle COM Automation Feature Components
PL/SQL Components
comus.msb)orawpcomVER.dll is located in the ORACLE_BASE\ORACLE_HOME\bin directory.ORACLE_BASE\ORACLE_HOME\com directory.
Java Components
orawcom.jarorawcomVER.dll is located in the ORACLE_BASE\ORACLE_HOME\bin directory. All other components are located in the ORACLE_BASE\ORACLE_HOME\com\java directory.
System Requirements
Upgrading from Oracle Database 10g Release 2 or Oracle Database 11g Release 1 to Oracle Database 11g Release 2
Configurations for Oracle COM Automation Feature
Configuring Oracle COM Automation Feature for PL/SQL
SYSTEM.
SQL> CONNECT SYSTEM@net_service_name
Enter password: password
CREATE LIBRARY privilege to the database users who will use Oracle COM Automation Feature. For example:
SQL> GRANT CREATE LIBRARY TO hr;
comwrap.sql script at the SQL*Plus prompt:
SQL> CONNECT hr;
Enter password: password
SQL> @ORACLE_BASE\ORACLE_HOME\com\comwrap.sql
ORACLE_BASE\ORACLE_HOME represents the Oracle home directory where Oracle COM Automation Feature is installed.ORA-04043: object XXXX does not exist messages when you run this script for the first time. These messages are usual.
Configuring Oracle COM Automation Feature for Java
SYSTEM using SQL*Plus. For example:
SQL> CONNECT SYSTEM@net_service_name
Enter password: password
grant.sql script with the name of the user who will use Oracle COM Automation Feature. You may need to capitalize all letters in the user's name. For example:
SQL> @ORACLE_BASE\ORACLE_HOME\com\java\grant.sql HR
loadjava tool at the command prompt as follows:
loadjava -force -resolve -user hr
ORACLE_BASE\ORACLE_HOME\com\java\orawcom.jar
Password: password
hr is the user who uses Oracle COM Automation Feature.
Configuring the Listener for PL/SQL
listener.ora and tnsnames.ora files for external procedures
LISTENER =
(ADDRESS_LIST =
(ADDRESS=
(PROTOCOL= IPC)
(KEY= EXTPROC0)
)
)
STARTUP_WAIT_TIME_LISTENER = 0
CONNECT_TIMEOUT_LISTENER = 10
TRACE_LEVEL_LISTENER = off
SID_LIST_LISTENER =
(SID_LIST =
(SID_DESC =
(SID_NAME = ORCL)
)
(SID_DESC =
(SID_NAME = plsextproc)
(PROGRAM=extproc)
)
)
PASSWORDS_LISTENER = (oracle)
EXTPROC_CONNECTION_DATA=
(DESCRIPTION=
(ADDRESS=
(PROTOCOL=IPC)
(KEY=EXTPROC0)
)
(CONNECT_DATA=(SID=plsextproc))
)
)
Troubleshooting Listener Problems
OracleHOME_NAMETNSListener service from the Control Panel or the command prompt.OracleHOME_NAMETNSListener in the list and verify that it has a status of Started. If it does not, select it and click Start.
C:\> net start service
OracleHOME_NAMETNSListener.listener.ora and tnsnames.ora files.
Support for DCOM
Configuring the Computer for DCOM
Configurations for the Computer Running the Database Instance
Setting Services to a Domain User
OracleHOME_NAMETNSListener or the database service.
Configuring the Computer Containing the Remote Object
dcomcnfg.exe tool provided by Microsoft to configure the computer's DCOM security settings.dcomcnfg.exe tool, set the following:
dcomcnfg.exe tool and the implications of the related permissions
PK5< < PK AA OEBPS/ch5java.htm@
1 Introducing Oracle COM Automation Feature
Overview of Oracle COM Automation Feature
Oracle COM Automation Feature Functionality
IDispatch interface.IDispatch interface.IDispatch interface supports three basic operations for any COM object:IDispatch API with the converted parameters.
Oracle COM Automation Feature for PL/SQL
Oracle COM Automation Feature for Java
dllhost to support in-process servers.
Benefits of Oracle COM Automation Feature
Oracle COM Automation Feature Architecture
PL/SQL Architecture
Description of "Figure 1-2 COM Automation Feature Architecture for PL/SQL"
Invoking COM Automation External Procedure APIs
orawpcomVER.dll) where VER is the release version.extproc.exe, if it has not already been started for the current user session.extproc.exe.extproc.exe file loads the DLL and executes the external procedure. Each of the COM Automation external procedure APIs in turn calls Win32 APIs that instantiate a COM object, set or get properties of a COM object, or invoke a method of a COM object.The extproc.exe file acts as an intermediary and handles any interaction between Oracle COM Automation Feature and the database server.
Architectural Impact on Availability Issues
Java Architecture
Automation class and the Java COM Proxy DLL, orawcomVER.dll, where VER is the release version.Automation class, a Java proxy to the COM Automation server. The Automation class provides the methods necessary for developers to manipulate COM objects through the IDispatch interface.orawcomVER.dll, enables Java functions to invoke their corresponding COM functions.
Description of "Figure 1-3 COM Automation Feature Architecture for Java"
PK#@ @ PK AA
OEBPS/toc.ncx L
5 Oracle COM Automation Java Demos
Overview of Oracle COM Automation Feature for Java Demos
Microsoft Word Java Demo
ORACLE_BASE\ORACLE_HOME\com\java\demos directory and provides the following:TestWORD.java, the Java source for the demo. In addition to the collection of APIs, it includes the demo program test.TestWORD.sql, the script that creates the call specification for the demo.
Installing the Microsoft Word Java Demo
loadjava tool from the command line:
loadjava -force -resolve -user hr ORACLE_BASE\ORACLE_HOME\com\java\demos\TestWORD.class
Password: password
C:\> sqlplus /NOLOG
SQL> connect hr
Enter password: password
TestWORD.sql script to create the call specification:
SQL> @ORACLE_BASE\ORACLE_HOME\com\java\demos\TestWORD.sql
Using the Microsoft Word Java Demo
SERVEROUTPUT on at the SQL*Plus prompt:
SQL> SET SERVEROUTPUT ON
TestWORD() at the SQL*Plus prompt:
SQL> CALL TestWORD();
worddemoj.doc) in the C:\ directory. The document contains data from the EMPLOYEES and JOBS tables. These tables are available in the human resources schema in the sample schema.
Creating a Custom Application
TestWORD API as described in "Core Functionality" , provides a wrapper around the Word.Basic COM Automation class as well as some sample code that demonstrates how to use the wrapper. This code was written to be run on the Oracle database server.Word.Basic object by calling the CreateWordObject method.FileNew method, or open an existing document with the FileLoad method.FormatFontSize, InsertText, and InsertNewLine methods to add text and formatting to the document.FileSaveAs or the FileSave method.FileClose method when you are finished with the document.DestroyWordObject method when you are finished with the Word.Basic object.
Core Functionality
public TestWORD()
Word.Basic COM object.
public void CreateWordObject(java.lang.String servername)
Where Is servername the server on which to create the COM object. Specify null or the empty string for the local server. Word.Basic COM object.
public void DestroyWordObject()
public void FileNew()
FileNewDefault COM method of the Word.Basic COM object.
public void FileLoad(java.lang.String filename)
Where Is filenamethe name of the file to load. FileOpen COM method of the Word.Basic COM object.
public void FormatFontSize(long fontsize)
Where Is fontsizethe new font size. FormatFont COM method of the Word.Basic COM object.
public void InsertText(java.lang.String textstr)
Where Is textstrthe text to insert. Insert COM method of the Word.Basic COM object.
public void InsertNewLine()
InsertPara COM method of the Word.Basic COM object.
public void FileSaveAs(java.lang.String filename)
Where Is filenamethe name of the file. FileSaveAs COM method of the Word.Basic COM object.
public void FileSave()
FileSave COM method of the Word.Basic COM object.
public void FileClose()
FileClose and FileExit COM methods of the Word.Basic COM object.
PK2,8/N I PK AA OEBPS/dcommon/prodbig.gif GIF87a !!!)))111BBBZZZsss{{ZRRcZZ!!1!91)JB9B9)kkcJJB991ssc絽Zcc!! {祽BZc!9B!c{ !)c{9{Z{{cZB1)s Jk {{Z{kBsZJ91)Z{!{ BcsRsBc{ 9Z Zk甽k Bk R!BZ 9c )JJc{!))BZks{BcR{JsBk9k)Zck ! !B Z1k!ZcRBZc ZJkBk1Z9c!R!c9kZRZR B Z9{ 9 9 !R 1{ 99R{ 1!1)c 1 J)1B ! B J Rkk{ƽ絵ތkk絵RRs{{{{JJsssBBkkk!!9ss{{ZZssccJJZZRRccRRZZ))cBBJJ99JJ!!c11991199Z11!c!!))Z!! ! 1 B R c k { )!cJBkZRZ , HP)XRÇEZ֬4jJ0 @ "8p YҴESY3CƊ @* U:lY0_0#
5tX1E: C_xޘeK TList of Figures
g C)rr9+c:b Жf*s^ fKS7^}
*{zq_@8# p F~
[VPe(nw0MW=3#kȵ z晨cy PpG#W:% drMh] 3HH<\]ԁ |_ W
HHҡb}P >k {ZErxMX@8C&qs kLۙOnO^sCk7ql2XCw5VG.S~ H 8=(s 1~ cV5z
%v|U2QF=NoW]ո?<`~}=ӬfԵ,=; "~Iy7K#g{ñJ?5$y`
zz @-~ m7 mG宝Gٱ>G&K#]y1$$t>wqjstX.b̐{Wej)Dxfc:8)=$y|L`xV8ߙ~E)HkwW$J0uʟk>6S gp~;4W+חc"=|ř9bc5 > *r g {~cj1rnI#G|8v4wĿhFb><^ pJLm[Dl1;Vx5IZ: 1* p)إ1Z bAK(1ׅ|S& 5{^
KG ^ 5r>;X K^?
s fk^8O/"J)3K]N)iLOracle Legal Notices
Copyright Notice
Trademark Notice
License Restrictions Warranty/Consequential Damages Disclaimer
Warranty Disclaimer
Restricted Rights Notice
Hazardous Applications Notice
Third-Party Content, Products, and Services Disclaimer
Alpha and Beta Draft Documentation Notice
PKE PK AA
OEBPS/toc.htm't
4 Oracle COM Automation PL/SQL Demos
Overview of Oracle COM Automation Feature for PL/SQL Demos
Microsoft Word Demo
ORDWord, a PL/SQL package that exposes several APIs for manipulating Microsoft Word. This package is created by the wordsol.sql script.worddem.sql, a script that displays the capabilities of exchanging data between Oracle Database and Microsoft Word. It exchanges data from the EMPLOYEES and JOBS tables to a Microsoft Word document. These tables are available in the human resources schema in the sample schema.
Installing the Microsoft Word Demo
C:\> sqlplus /NOLOG
SQL> connect hr
Enter password: password
wordsol.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\wordsol.sql;
ORDWord package in the current user's schema. You will receive the following error several times when you run this script for the first time:
ORA-04043: object XXXX does not exist.
Using the Microsoft Word Demo
worddem.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\worddem.sql;
worddemo.doc) in the C:\ directory. The document contains data from the EMPLOYEES and JOBS tables. These tables are available in the human resources schema in the sample schema.worddemo.doc file to see its contents.
Core Functionality
Word.Basic object in the Microsoft Word Automation server.
FUNCTION CreateWordObject() RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION FileNew() RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION FileLoad(filename VARCHAR2) RETURN BINARY_INTEGER;
Where Is filenamethe fully qualified filename of the document. 0 when successful or a nonzero HRESULT when an error occurs.
FUNCTION FileSave() RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION FileSaveAs(filename VARCHAR2) RETURN BINARY_INTEGER;
Where Is filenamethe fully qualified filename of the document. 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION FileClose() RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION InsertText(textstr VARCHAR2) RETURN BINARY_INTEGER;
Where Is textstrthe text that will be inserted into the document. 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION InsertNewLine() RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION FormatFontSize(fontsize BINARY_INTEGER) RETURN BINARY_INTEGER;
Where Is fontsizethe point size of the font. 0 when successful, or a nonzero value for HRESULT when an error occurs.
Microsoft Excel Demo
ORDExcel, a PL/SQL package that exposes several APIs for manipulating Microsoft Excel. This package is created by the excelsol.sql script.exceldem.sql, a script that displays the capabilities of exchanging data between Oracle database instance and Microsoft Excel. It exchanges data from the EMPLOYEES and JOBS tables in Oracle database instance to a Microsoft Excel spreadsheet and puts it in a graph. These tables are available in the human resources schema in the sample schema.
Installing the Microsoft Excel Demo
C:\> sqlplus /NOLOG
SQL> connect hr
Enter password: password
excelsol.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\excelsol.sql;
ORDExcel package in the schema of the current user. You will receive the following error several times when you run this script for the first time:
ORA-04043: object XXXX does not exist.
Using the Microsoft Excel Demo
exceldem.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\exceldem.sql;
excelxxxxx.xls) in the C:\ directory. The document contains data from the EMPLOYEES and JOBS tables. These tables are available in the human resources schema in the sample schema.excelxxxxx.xls file, where xxxxx is a time stamp, to see the content of this file.
Core Functionality
FUNCTION CreateExcelWorkSheet() RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION InsertData(range VARCHAR2, data any_PL/SQL_data type, data type VARCHAR2) RETURN BINARY_INTEGER;
Where Is rangea string that indicates a specific cell in the current Excel worksheet (for example, 'A1', 'B1'). datathe data that you want to insert into the current Excel worksheet. data typea string that indicates the data type of the data that you are inserting into Excel. The list of available data types are:
I2 - 2-byte integerI4 - 4-byte integerR4 - IEEE 4-byte realR8 - IEEE 8-byte realSCODE - error codeCY - currencyDISPATCH - dispatch pointerBSTR - StringBOOL - booleanDATE - dateany_PL/SQL_data typeany data type supported by COM Automation Feature. 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION InsertChart(xpos BINARY_INTEGER, ypos BINARY_INTEGER, width BINARY_INTEGER, height BINARY_INTEGER,
range VARCHAR2, type VARCHAR2) RETURN BINARY_INTEGER;
Where Is xposthe x position in the current worksheet where the chart should be inserted yposthe y position in the current worksheet where the chart should be inserted widththe width of the chart heightthe height of the chart rangethe range of cells to be graphed typethe data type of the data to be graphed 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION SaveExcelFile(filename VARCHAR2) RETURN BINARY_INTEGER;
Where Is filenamethe fully qualified file name of the Excel workbook 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION ExitExcel() RETURN BINARY_INTEGER;
0 when successful or a nonzero HRESULT when an error occurs.
Microsoft PowerPoint Demo
ORDPPT, a PL/SQL package that exposes several APIs for manipulating Microsoft PowerPoint. This package is created by the pptsol.sql script.pptdem.sql, a script that displays the capabilities of exchanging data between Oracle Database instance and Microsoft PowerPoint. It exchanges data from the EMPLOYEES and JOBS tables in Oracle Database instance to a Microsoft PowerPoint document. These tables are available in the human resources schema in the sample schema.
Installing the Microsoft PowerPoint Demo
C:> sqlplus /NOLOG
SQL> connect hr
Enter password: password
pptsol.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\pptsol.sql;
ORDPPT package in the current user's schema. You will receive the following error several times when you run this script for the first time:
ORA-04043: object XXXX does not exist.
Using the Microsoft PowerPoint Demo
pptdem.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\pptdem.sql;
pptdemo.ppt) on C:\. The document contains a list of employee names.pptdemo.ppt to see its contents.
Core Functionality
FUNCTION CreatePresentation (servername IN VARCHAR2) RETURN BINARY_INTEGER;
Where Is servernameMicrosoft Powerpoint COM Automation Server name 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION AddSlide (layout IN BINARY_INTEGER) RETURN BINARY_INTEGER;
Where Is layoutthe layout of the new slide 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION SetTitle (title IN VARCHAR2) RETURN BINARY_INTEGER;
Where Is titlePowerpoint slide title 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION InsertText (orientation IN BINARY_INTEGER, left IN BINARY_INTEGER, top IN BINARY_INTEGER,
width IN BINARY_INTEGER, height IN BINARY_INTEGER, text IN VARCHAR2) RETURN BINARY_INTEGER;
Where Is orientationorientation of the text box leftdistance between the left edge of the text box and the left edge of the slide in pixels topdistance between the top edge of the text box and the top edge of the slide in pixels widthwidth of the text box in pixels heightheight of the text box in pixels texttext entered in the text box 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION PresentationSave RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION PresentationSaveAs (filename IN VARCHAR2) RETURN BINARY_INTEGER;
Where Is filenamethe fully qualified filename of the presentation. 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION PresentationClose RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION Exit RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
MAPI Demo
ORDMAPI, a PL/SQL package that exposes several APIs for manipulating the Extended MAPI client.mapidem.sql, a script that displays the capabilities of exchanging data between Oracle Database instance and the Extended MAPI client.mapi.reg, a registration entry file that updates the registry settings.
Setting Up the Environment to Use the MAPI Demo
CDO.DLL as mentioned in the MSDN article, 268272. This patched DLL is part of Microsoft Exchange 5.5. Manually copy the patched DLL to the proper location. The default location for this DLL is:
C:\Program Files\Common Files\System\Mapi\1033\NT
MAPI.REG from the Windows Explorer. MAPI.REG is located in:
ORACLE_BASE\ORACLE_HOME\com\demos
Preparing to Install MAPI Demo
LocalSystem. The MAPI profile for user LocalSystem is not easily configured. Before using the MAPI Solution, change both the Oracle Database service and OracleHOME_NAMETNSListenerservice to start up using a login user account.DOMAIN-1\hr.DOMAIN-1\hr. Ensure that you can send out e-mail using this profile.OracleHOME_NAMETNSListener service.OracleHOME_NAMETNSListener service and click Startup.DOMAIN-1\hr.DOMAIN-1\hr.OracleHOME_NAMETNSListener service.DOMAIN-1\hr.DOMAIN-1\hr.
Installing the MAPI Demo
C:> sqlplus /NOLOG
SQL> connect hr
Enter password: password
mapisol.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\mapisol.sql;
ORDMAPI package in the current user's schema. You will receive the following error several times when you run this script for the first time:
ORA-04043: object XXXX does not exist.
Using the MAPI Demo
mapidem.sql with a text editor and change the e-mail address hr@us.oracle.com in ORDMapi.AddRecipient to your own e-mail address. If you are not using the default as your profile name, also change the profile name that is indicated in ORDMapi.CreateMAPISession, MS Exchange Settings. Save the changes.mapidem.sql script at the SQL*Plus prompt:
SQL> @ORACLE_BASE\ORACLE_HOME\com\demos\mapidem.sql;
Core Functionality
FUNCTION CreateMAPISession (servername IN VARCHAR2 DEFAULT '', profilename IN VARCHAR2 DEFAULT NULL,
password IN VARCHAR2 DEFAULT NULL) RETURN BINARY_INTEGER;
Where Is servernameMAPI server name profilenamename of the profile present in the MAPI server passwordpassword to connect to the MAPI server 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION NewMessage RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION AddRecipient (emailaddress VARCHAR2) RETURN BINARY_INTEGER;
Where Is emailaddresse-mail address of the recipient 0 when successful or a nonzero HRESULT when an error occurs.
FUNCTION SetSubject (subject VARCHAR2) RETURN BINARY_INTEGER;
Where Is subjectthe subject of the e-mail message 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION SetBody (messagetext VARCHAR2) RETURN BINARY_INTEGER;
Where Is messagetextthe body of the e-mail message 0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION SendMessage RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
FUNCTION EndMAPISession RETURN BINARY_INTEGER;
0 when successful, or a nonzero value for HRESULT when an error occurs.
PKW' ' PK AA
OEBPS/lot.htmM
Contents
List of Figures
List of Tables
Title and Copyright Information
Preface
1 Introducing Oracle COM Automation Feature
2 Installing and Configuring Oracle COM Automation Feature
3 Oracle COM Automation Feature Core Functionality
4 Oracle COM Automation PL/SQL Demos
5 Oracle COM Automation Java Demos
A COM Automation Error Messages
Glossary
Index
