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}
Else
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.