FINDINSTANCE( )

Topic group Related topics Example

Returns an object of the specified class from the object heap.

Syntax

FINDINSTANCE(<classname expC> [, <previous oRef>])

<classname expC>

The name of the class you want to find an instance of. <classname expC> is not case-sensitive.

<previous oRef>

When omitted, FINDINSTANCE( ) returns the first instance of the specified class. Otherwise, it returns the instance following <previous oRef> in the object heap.

Description

Use FINDINSTANCE( ) to find any instance of a particular class, or to find all instances of a class in the object heap.

Objects are stored in the object heap in no predefined order. Creating a new instance of a class or destroying an instance may reorder all other instances of that class. A newly created object is not necessarily last in the heap.

Sometimes you will want to make sure there is only one instance of a class, and reuse that instance; a particular toolbar is the prime example. To see if there is an instance of that class, call FINDINSTANCE( ) with the class name only. If the return value is null, there is no instance of that class in memory.

Other times, you may want to iterate through all instances of a class to perform an action. For example, you may want to close all data entry forms, which are all instances of the same class. Call FINDINSTANCE( ) with the class name only to find the first instance of the class. Then call FINDINSTANCE( ) in a loop with the class name and the object reference to get the next instance in the object heap. When FINDINSTANCE( ) returns null, there are no more instances.