GetObject function (LotusScript® Language)

Opens an OLE Automation object contained in an application file, or returns the currently active OLE Automation object of the specified class.

Note: GetObject is not supported on UNIX™ or on HCL Nomad. It is supported on the Mac as long as OLE support is installed.

Syntax

GetObject ( [pathName] [ , className ] )

Elements

pathName

Either a string containing the full path and file name of an application file or an empty string. The application must support OLE Automation. If pathName is the empty string ("") or is missing, you must specify a className.

className

A string of the form appName.appClass that identifies the application in which the class is defined and the class of the object to retrieve.

appName is the name of an application that supports OLE Automation. appClass is the name of the class of which you want to retrieve an instance.

Return value

GetObject returns an OLE Automation object reference.

Usage

Use the Set statement to assign the object reference returned by GetObject to a Variant variable.

If the application specified by appName is not already running, GetObject starts it before retrieving the OLE Automation object. References to the object remain valid only while the application is running. If the application terminates while you are using the object reference, LotusScript® generates a run-time error.

If pathName is the empty string ("") or is missing, GetObject retrieves the currently active object of the specified class. If no object of that class is active, an error occurs.

If className is omitted, GetObject determines the application to run and the object to retrieve based on the pathName. This form of GetObject is useful only when the application file contains a single object.

Each product that supports OLE Automation provides one or more classes. See the product's documentation for details.

LotusScript® supports the following return types for OLE properties and methods. Only an OLE method or property can return a type designated as "OLE only."


OLE return type	Description
VT_EMPTY	(No data)
VT_NULL	(No data)
VT_I2	2-byte signed integer
VT_I4	4-byte signed integer
VT_R4	4-byte real
VT_R8	8-byte real
VT_CY	Currency
VT_DATE	Date
VT_BSTR	String
VT_DISPATCH	IDispatch, OLE only
VT_ERROR	Error, OLE only
VT_BOOL	Boolean
VT_DECIMAL	Decimal, converted to Double
VT_VARIANT	(A reference to data of any other type)
VT_UNKNOWN	IUnknown, OLE only
VT_ARRAY	(An array of data of any other type)

Note: If the application specified by appName is registered as a single-instance object, call CreateObject to get that object as GetObject will cause an error. This is different from Visual Basic; in Visual Basic, if GetObject is called with an empty string as first parameter, it behaves the same as CreateObject.

You can use a ForAll loop to iterate over the members of OLE collections.

LotusScript® supports passing arguments to OLE properties. For example:

' Set v.prop to 4; v.prop takes two arguments.
v.prop(arg1, arg2) = 4

LotusScript® does not support identifying arguments for OLE methods or properties by name rather than by the order in which they appear, nor does LotusScript® support using an OLE name by itself (without an explicit property) to identify a default property.

Results are unspecified for arguments to OLE methods and properties of type boolean, byte, and date that are passed by reference. LotusScript® does not support these data types.

The word GetObject is not a LotusScript® keyword.

Example