Interface INaturalXUtilities

This document covers the following topics:

Purpose

This is the main interface of the component SoftwareAG.NaturalX.Utilities. It is returned when a new instance of the component is created.

Example: 

define data
local
1 #util handle of object
end-define
*
* Create an instance of the class SoftwareAG.NaturalX.Utilities.
create object #util of 'SoftwareAG.NaturalX.Utilities.5'
if #util eq null-handle
  escape routine
end-if
*
end

After successful execution of the CREATE OBJECT statement, the variable #util contains an interface of the type INaturalXUtilities.

Methods

The following methods are available:

GetThisNaturalStudio

Retrieves the root interface INatAutoStudio of the current Natural Studio session. After having retrieved this interface, the client has access to Natural Studio functionality as it is provided by the Natural Studio Automation interface.

Parameters

Name Natural Type Variant Type Remark
Return value HANDLE OF OBJECT VT_DISPATCH (INatAutoStudio)  
Return Value

The root interface INatAutoStudio of the current Natural Studio session. NULL-HANDLE, if the method is called in a Natural session that is not a Natural Studio session.

GetRunningObjects

Returns an interface IRunningObjects that is used to iterate across the names of the objects contained in the running objects table (ROT).

Parameters

Name Natural Type Variant Type Remark
Return value HANDLE OF OBJECT VT_DISPATCH (IRunningObjects)  
Return Value

An interface IRunningObjects that is used to iterate across the names of the objects contained in the running objects table (ROT).

BindToObject

Returns an interface to an object that is identified by a specific kind of name, a so-called "moniker" (Windows terminology). See Interface IRunningObjects for the necessary information about monikers.

Parameters

Name Natural Type Variant Type Remark
Return value HANDLE OF OBJECT VT_DISPATCH  
Name A VT_BSTR By value
Return Value

An interface to the object identified by the name specified in Name.

Name

Used to identify a specific object by name. The name must be from one of the following categories:

  • A file moniker, for instance c:\MyDoc.doc.

  • An URL moniker, for instance http://www.myorg.org/MyDoc.doc or ftp://ftp.myorg.org/MyDoc.doc.

  • A name of an object contained in the ROT. The names of the objects in the ROT can be retrieved using the interface IRunningObjects.

If a file or URL moniker is specified, the corresponding object is loaded into the application that is registered for the corresponding file extension and an interface pointer (object handle) to the object is returned. If the object is already loaded into the application, an interface pointer (object handle) to the already running instance is returned.

Example:

define data
local
1 #util handle of object
1 #obj handle of object
1 #content handle of object
1 #word handle of object
1 #doc (a) dynamic
1 #text (a) dynamic
end-define
*
* Create an instance of the utilities class.
create object #util of 'SoftwareAG.NaturalX.Utilities.5'
if #util eq null-handle
  escape routine
end-if
*
* Load a document into Microsoft Word.
* The option (ad=o) is essential, because the
* method expects a by value parameter.
#doc := 'c:\word.doc'
send 'BindToObject' to #util with #doc (ad=o) return #obj
if #obj eq null-handle
  escape routine
end-if
*
* Access the content of the document.
#content := #obj.Content
#text := #content.Text
write 'Content:' #text (al=60)
*
* Close Microsoft Word.
#word := #obj.Application
send 'Quit' to #word
*
end