This document covers the following topics:
This interface is an iterator across the names of the objects that are contained in the running objects table (ROT). The ROT is a system table that is provided and maintained by Windows. It allows applications to make the objects or documents on which the user is currently working available to other applications.
Each object contained in this table is identified by a so-called "moniker". A moniker is a name that follows a specific syntax. For instance, there are file monikers that identify a file in the file system. A file moniker in its readable form is nothing else than a file name with full path name, like c:\MyDoc.doc. As another example, there are URL monikers that identify a resource in the internet and the protocol to be used to access it. A URL moniker in its readable form is just a common URL, like http://www.myorg.org/MyDoc.doc.
An application that wants to access an object in the ROT specifies the moniker that identifies the object and receives an interface pointer (an object handle) to the object.
Applications often enter the object or document on which the user is currently working in the ROT.
If you open the document c:\MyDoc.doc in Microsoft Word, Microsoft Word will enter the name of this document (that is: c:\MyDoc.doc) and an interface pointer to this document into the ROT.
When a Natural Studio session is started, Natural Studio enters the
Automation root interface
INatAutoStudio of this session
into the ROT. The interface is identified by a name built as follows:
NaturalStudio/<version>/<userid>/>processid>
NaturalStudio/n.n/SCULLY/42
where n.n is the product version.
By specifying this name, other applications can retrieve the Automation root interface in the ROT and use it to access the Natural Studio session.
The interface IRunningObjects allows iterating
across the names of all objects currently contained in the ROT. The found names
can then be used in the method INaturalXUtilities::BindToObject
to retrieve an interface pointer (object handle) to the corresponding
object.
In the following sample program, the characters n.n stand for the Natural product version. Please, replace these characters by the current Natural product version if you want to run the sample program.
define data
local
1 #util handle of object
1 #studio handle of object
1 #objects handle of object
1 #progs handle of object
1 #prog handle of object
1 #rot handle of object
1 #ro (a) dynamic
end-define
*
* Create an instance of the Utilities class.
create object #util of 'SoftwareAG.NaturalX.Utilities.4'
if #util eq null-handle
escape routine
end-if
*
* Retrieve the running objects table.
send 'GetRunningObjects' to #util return #rot
if #rot eq null-handle
escape routine
end-if
*
* Iterate across the running objects table.
repeat
send 'Next' to #rot return #ro
if #ro eq ' '
escape bottom
end-if
* If we hit a running Natural Studio session,...
if substring(#ro,1,17) eq 'NaturalStudio/n.n'
* ...we access it,...
send 'BindToObject' to #util
with #ro (ad=o) return #studio
* ...open a Program Editor in that session...
#objects := #studio.objects
#progs := #objects.programs
send 'Add' to #progs
with 1009 return #prog
* ...and display the identifier of this session in the editor.
compress 'This is' #ro to #ro
#prog.source := #ro
end-if
end-repeat
*
end
The following methods are available:
Returns the name of the next object in the ROT. The name can then be
used in the method INaturalXUtilities::BindToObject
to retrieve an interface pointer (object handle) to the corresponding
object.
| Name | Natural Type | Variant Type | Remark |
|---|---|---|---|
| Return value | A | VT_BSTR |
- Return Value
The name of the next object in the ROT.
Resets the iterator to its initial state. After having called
Reset, a subsequent call to
Next returns the name of the first object in the
ROT.