$occhandle

Return the handle of the current occurrence of the requested entity.

Synopsis

$occhandle{(LitEntityName)}

Use

Allowed in all components types.

Description

The function $occhandle returns the handle of the current occurrence of the requested entity.

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

• The literal name of an entity painted on the component. For example, $occhandle("MYENTITY").

• A string that evaluates to the name of an entity. For example, $occhandle("MYENTITY").
• A variable, function, or parameter that evaluates to a string that contains the name of an entity. For example:
• $occhandle ($1), where $1 contains "MYENTITY".
• $occhandle (PARAM1), where PARAM1 contains "MYENTITY".
• $occhandle ($entname), where $entname is "MYENTITY".
• An indirect reference to a field, where the target field evaluates to a string that contains the name of an instance. For example, $occhandle (@$1), where $1 contains "FLD1" and FLD1 contains "MYENTITY".

If the LitEntityName argument is omitted, the current entity is used.

Return value

The function $occhandle returns the handle of the current occurrence of the entity of LitEntityName.

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

• LitEntityName is not a correct entity.
• There is no occurrence for the given entity with the name LitEntityName.

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:

Related Information

Proc:

$collhandle

$instancehandle