UNIFACE 8101 - Overview

UNIFACE 8.1.01 $instanceHandle

[back to index]

$instancehandle

Return the handle of the requested instance.

Synopsis

$instancehandle{(InstName)}

Use

Allowed in all component types.

Description

The function $instancehandle returns the handle of the requested instance.

If the InstName argument is provided, it must be one of the following:

The literal name of any instance of a component. For example, $instanceparent(MYINSTANCE).

A string that evaluates to the name of an instance. For example, $instancehandle("MYINSTANCE").

A variable, function, or parameter that evaluates to a string that contains the name of an entity. For example:

$instancehandle ($1), where $1 contains "MYINSTANCE".
$instancehandle (PARAM1), where PARAM1 contains "MYINSTANCE".
$instancehandle ($instancename), where $instancename is "MYINSTANCE".

An indirect reference to a field, where the target field evaluates to a string that contains the name of an instance. For example, $instancehandle (@$1), where $1 contains "FLD1" and FLD1 contains "MYINSTANCE".

If the InstName argument is omitted, the current instance is used.

Return value

The function $instancehandle returns the handle of the instance with a name InstName.

An null handle is returned if an error occurred or in the following circumstances:

InstName is not a correct instance name.
The instance with the name InstName has been deleted.

If an error occurs during the evaluation of this function, the function $procerror contains a negative value that identifies the exact error. Values of $procerror commonly returned by this function are:

-57	<UACTERR_NO_INSTANCE>	The named instance cannot be found in the component pool.
-1101	<UPROCERR_FIELD>	An incorrect field name was provided; either the field name is not valid syntactically or the field is not available in the component.

Related Information

Proc:

$occhandle

$collhandle