Omnis Technical Note TNOO0003 April 2007

Using References

For Omnis Studio 3 or after
By Dr. Michael Hufschmidt

In Omnis Studio there is the variable type "item reference" which, just as its name suggests, can save a reference to an object in an object tree. In other development languages you might call it a pointer. In a reference variable you can save a long notation string, such as:

Set reference myRef to $root.$iwindows.wTest.$objs.Tabpane.$objs.Button

Then you can modify the properties of this button using the reference, like this:

Do myRef.$text.$assign('New Text')

You can find a description of how to use this variable type in Chapter 3 of the Omnis Programming manual, and the Set Reference command is described in the Omnis Command Reference.

Deleting References
Variables of the type "item reference" can be redefined (twisted) in any way. With the instruction:

Set reference myRef to $root.$iwindows.wTest.$objs.Tabpane.$objs.Button2

myRef would now point to a different button.

But how do you delete a reference?
The command

Calculate myRef as #NULL

results in a notation error and

Set reference myRef to #NULL

generates a valid (not empty) reference on the constant #NULL. So the answer is with:

Set reference myRef to

(without declaring a target) you can create an empty reference.

Checking of References
Quite often you may want to test whether a reference is pointing to an existing object in a tree. In most cases you can use the following code for this purpose:

If myRef
 OK message Reference Test {Reference is set}
 OK message Reference Test {Reference is NOT set}
End If

In the If statement you should not execute any calculations (for an exception please see below); "If isnull(myRef)" and "If not(myRef)" won't always deliver the expected results. If you want to test whether a reference is not set you can also use the code listed above and then only program the Else branch.

Sometimes you may want to create a reference to a variable. In this case, you must add the notation '.$ref' on the end of the variable name when you set the reference. So the code to set a reference to a variable is:

Set reference myRef to ivString.$ref

But here we discover a small problem: The above listed query with "If myRef" does not work for references on variables, that is, mistakenly it always derives in the Else branch, even when myRef points to a valid variable. But you can check the validity of a reference, i.e. whether or not the variable exists with:

If myRef.$ident

This will return kTrue when the variable ivString exists, even if it has the value #NULL. By the way, the query "If myRef.$ident" works as well when myRef points to an object instance.

Unfortunately you cannot use this test to check whether the reference of a container has been set correctly. For example, if you previously defined myRef with

Set reference myRef to $clib.$classes

Then "If myRef.$ident" always derives in the Else branch, as well. On the other hand, for containers, the query "If myRef" works. Therefore, if you want to allow for both possibilities you can program a query with

If myRef | myRef.$ident

However, you would normally know in advance whether the reference will point to an object instance, a variable or a container.