Documentation
UC_FindReferences
array UC_FindReferences (int $InstanceID, int $ID)
Parameters
| InstanceID | ID for the Util Control |
| ID | ID of the object whose usages are searched |
Returns
An array with one entry per location. Each entry contains the following key => value pairs:
| Index | Type | Description |
|---|---|---|
| LineContent | string | For scripts the found line without leading and trailing spaces, otherwise the kind of location (see table) |
| LineNumber | integer | For scripts the line number (starting at 1), otherwise 0 |
| LinePosition | integer | For scripts the position of the first match in the line in bytes (starting at 0), otherwise 0 |
| ObjectID | integer | ID of the object that uses ID |
Description
The function searches the entire system for places where the object ID is used, e.g. before a variable is deleted or replaced. The management console uses it to show the usages of an object. The following locations are recognized, in this order:
| LineContent | ObjectID | Location |
|---|---|---|
| (line of the script) | Script | The script content contains ID as text. One entry per line, LineNumber and LinePosition are set |
| Variable | Variable | ID is the custom action (action script) of the variable |
| Event (Action) | Event | A parameter of the action of the event or of an action of the weekly schedule contains ID as text |
| Event (Condition) | Event | A condition of the event checks the variable ID or compares with it |
| Event | Event | ID is the triggering variable of the triggered event |
| Link | Link | ID is the target of the link |
| Instance | Instance | The instance has ID in its reference list (see IPS_GetReferenceList) |
| Instance (Connected) | Instance | The instance is connected to the instance ID as its parent |
| IPSView | Media object (IPSView) | The IPSView file uses ID |
| Chart | Media object (Chart) | A dataset of the chart uses the variable ID |
The name in LineContent may be translated into the language of the system. An object can appear several times in the result, e.g. a script with several matches or an event with several matching conditions. If nothing is found, the result is an empty array. Whether ID exists is not checked. Searching for the root (ID 0) is not possible and fails with "Search ID cannot be 0".
Scripts and action parameters are searched as text. Searching for 12345 therefore also finds 123456 or a number 12345 that is not an object ID at all. Conversely, IDs that a script only determines at runtime, e.g. with IPS_GetObjectIDByIdent, are not found.
Since all script files are read, the search can take some time in large systems.
The ID of the Util Control instance can be determined e.g. with IPS_GetInstanceListByModuleID and the module GUID {B69010EA-96D5-46DF-B885-24821B8C8DBD}. If InstanceID does not exist, the function fails with "Instance #... does not exist", if the instance belongs to another module, with "Instance does not implement this function".
Example
// Determine the ID of the Util Control instance
$id = IPS_GetInstanceListByModuleID('{B69010EA-96D5-46DF-B885-24821B8C8DBD}')[0];
// Output all usages of the variable 12345
foreach (UC_FindReferences($id, 12345) as $reference) {
if ($reference['LineNumber'] > 0) {
echo IPS_GetName($reference['ObjectID']) . ', line ' . $reference['LineNumber'] . ': ' . $reference['LineContent'] . PHP_EOL;
} else {
echo IPS_GetName($reference['ObjectID']) . ' (' . $reference['LineContent'] . ')' . PHP_EOL;
}
}