Dokumentation
UC_FindReferences
array UC_FindReferences (int $InstanzID, int $ObjektID)
Parameterliste
| InstanzID | ID zum Util Control |
| ObjektID | ID des Objekts, dessen Verwendungen gesucht werden |
Rückgabewert
Ein Array mit einem Eintrag je Fundstelle. Jeder Eintrag enthält folgende key => value Paare:
| Index | Typ | Beschreibung |
|---|---|---|
| LineContent | string | Bei Skripten die gefundene Zeile ohne führende und folgende Leerzeichen, sonst die Art der Fundstelle (siehe Tabelle) |
| LineNumber | integer | Bei Skripten die Zeilennummer (ab 1), sonst 0 |
| LinePosition | integer | Bei Skripten die Position des ersten Treffers in der Zeile in Bytes (ab 0), sonst 0 |
| ObjectID | integer | ID des Objekts, das ObjektID verwendet |
Beschreibung
Die Funktion durchsucht das gesamte System nach Stellen, an denen das Objekt ObjektID verwendet wird, z.B. bevor eine Variable gelöscht oder ersetzt wird. Die Verwaltungskonsole nutzt sie für die Anzeige der Verwendungen eines Objekts. Folgende Fundstellen werden erkannt, in dieser Reihenfolge:
| LineContent | ObjectID | Fundstelle |
|---|---|---|
| (Zeile des Skripts) | Skript | Der Skriptinhalt enthält ObjektID als Text. Ein Eintrag je Zeile, LineNumber und LinePosition sind gesetzt |
| Variable | Variable | ObjektID ist die eigene Aktion (Aktionsskript) der Variable |
| Event (Action) | Ereignis | Ein Parameter der Aktion des Ereignisses bzw. einer Aktion des Wochenplans enthält ObjektID als Text |
| Event (Condition) | Ereignis | Eine Bedingung des Ereignisses prüft die Variable ObjektID oder vergleicht mit ihr |
| Event | Ereignis | ObjektID ist die auslösende Variable des ausgelösten Ereignisses |
| Link | Link | ObjektID ist das Ziel des Links |
| Instance | Instanz | Die Instanz führt ObjektID in ihrer Referenzliste (siehe IPS_GetReferenceList) |
| Instance (Connected) | Instanz | Die Instanz ist mit der Instanz ObjektID als übergeordneter Instanz verbunden |
| IPSView | Medienobjekt (IPSView) | Die IPSView-Datei verwendet ObjektID |
| Chart | Medienobjekt (Chart) | Ein Datensatz des Charts verwendet die Variable ObjektID |
Die Bezeichnung in LineContent kann in die Sprache des Systems übersetzt sein. Ein Objekt kann mehrfach im Ergebnis auftauchen, z.B. ein Skript mit mehreren Treffern oder ein Ereignis mit mehreren passenden Bedingungen. Wird nichts gefunden, ist das Ergebnis ein leeres Array. Ob ObjektID existiert, wird nicht geprüft. Die Suche nach der Wurzel (ID 0) ist nicht möglich und schlägt mit "Search ID cannot be 0" fehl.
Skripte und Aktionsparameter werden als Text durchsucht. Die Suche nach 12345 findet daher auch 123456 oder eine Zahl 12345, die gar keine Objekt-ID ist. Umgekehrt werden IDs nicht gefunden, die ein Skript erst zur Laufzeit ermittelt, z.B. über IPS_GetObjectIDByIdent.
Da alle Skriptdateien gelesen werden, kann die Suche in großen Systemen einige Zeit dauern.
Die ID der Util Control Instanz liefert z.B. IPS_GetInstanceListByModuleID mit der Modul-GUID {B69010EA-96D5-46DF-B885-24821B8C8DBD}. Existiert InstanzID nicht, schlägt die Funktion mit "Instance #... does not exist" fehl, gehört die Instanz zu einem anderen Modul, mit "Instance does not implement this function".
Beispiel
// ID der Util Control Instanz ermitteln
$id = IPS_GetInstanceListByModuleID('{B69010EA-96D5-46DF-B885-24821B8C8DBD}')[0];
// Alle Verwendungen der Variable 12345 ausgeben
foreach (UC_FindReferences($id, 12345) as $reference) {
if ($reference['LineNumber'] > 0) {
echo IPS_GetName($reference['ObjectID']) . ', Zeile ' . $reference['LineNumber'] . ': ' . $reference['LineContent'] . PHP_EOL;
} else {
echo IPS_GetName($reference['ObjectID']) . ' (' . $reference['LineContent'] . ')' . PHP_EOL;
}
}