Interface IRunningObjects

#### Search Results

Search

# Interface IRunningObjects

This document covers the following topics:

- About IRunningObjects

- Methods in IRunningObjects

## About IRunningObjects

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.

#### Example

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>

#### Example

    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.

#### Example

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.5'
    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

## Methods in IRunningObjects

The following methods are available:

- Next (IRunningObjects)

- Reset (IRunningObjects)

### Next (IRunningObjects)

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.

#### Parameters

Name | Natural Type | Variant Type | Remark
--- | --- | --- | ---
Return value | A | VT_BSTR |

> Return Value

>   The name of the next object in the ROT.

### Reset (IRunningObjects)

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.

### On this page

- About IRunningObjects
- Methods in IRunningObjects