Vorwärts-Migrations-Script

Falls ein Element in einer neueren Bibliothek komplett geändert wurde, kann trotzdem eine Kompatibilität durch die Definition einer Migrationslogik aufrecht erhalten werden, die in diesem Script definiert wird.

Voraussetzung

Das alte Objekt muss bereits eine GUID besitzen. Also mindestens mit ArchiCAD 10 entwickelt oder gesichert worden sein. Diese GUID muss im neuen Objekt und jeder Instanz des Objektes im Plan verzeichnet sein. Reine Namensgleichheit funktioniert nicht.

Das reine neu sichern von Objekten mit ArchiCAD 10 legt in geladenen Projekten nicht sofort bei jedem Objekt die GUID mit ab. Es ist ggf. zunächst eine Zwischenmigration nötig, die noch die alten Objekte, aber mit GUID gesichert lädt und dem Projekt damit zunächst die GUIDs „nachrüstet“.

Ablauf

In der Migrationslise stehende Objekte werden beim Laden eines Projektes mit dem neuen Objektcode interpretiert. Dabei wird zunächst das Migrationsskript durchlaufen. Ergibt dies einen positiven Abschluss, dann wird das Objekt auch tatsächlich migriert.

Siehe auch SETMIGRATIONGUID

Komplikationen

Allen Instanzen eines alten Objektes (ohne GUID) in einem Projekt beizubringen, dass es eine zugewiesen bekommt und somit von dem Migrationsskript (durch die Referenz der alten GUID in der Migrationsliste) überhaupt erst erkannt wird ist nicht ganz einfach.

Ein Weg, der zumindest schon funktioniert hat:
1. Alle alten, zu migrierenden Objekte, die keine GUID beistzen mit mindestens ArchiCAD 10 sichern. (ggf. Bibliothekenkopie anlegen)
2. Das Projekt auf mindestens die nächst höhere ArchiCAD-Version migrieren, so dass alle Objekte in dem Projekt einmal automatisch „angefasst“ werden und damit eine GUID zugewiesen bekommen.
3. Dann das Projekt endgültig migrieren indem man die alten Objekte aus der Bibliothek entfernt und nur noch die neuen dazulädt.
Eingeführt mit ArchiCAD 15.

 

Erläuterungen

Normalerweise muss zum Anstoßen der Migration diese nicht manuell gestartet werden. Es reicht aus, wenn man die alte PLN-Datei in der neuen ArchiCAD-Version öffnet und nach dem Laden der Bibliothek zunächst die alte Bibliothek löscht. Anschließend (nicht in einem Schritt) lädt man die neue Bibliothek mit den Objekten, welche das Migrationsscript enthalten, dazu. Eine Migration von platzierten Objekten erfolgt nach Aussage Graphisoft jedesmal, wenn ein Bibliotheken Reload erfolgt. Wenn ein Objekt fehlen sollte, wird gesucht, ob es ein anderes Objekt gibt, welches die GUID des fehlenden Objektes in seiner Migrationstabelle listet. Ist dies der Fall, wird das Migrationsscript ausgeführt. Falls das Migrationsscript mit dem Ausdruck „setmigrationguidb actualGUID“ endet, wobei actualGUID die GUID des neuen Objektes ist, dann ist das Script erfolgreich und die Objekt-Parameter werden geändert und mit dem neuen Objekt verlinkt.

Beispiel

Wir wollen ein Objekt aus AC 15 zu einem Objekt aus AC 18 migrieren. Dazu legen wir in jeder AC-Version je ein GDL-Objekt vom selben Subtyp an und speichern beide; dadurch erhalten wir 2 Objekte mit 2 unterschiedlichen GUIDs.
Wir öffnen das AC18-Objekt, gehen dort zur Migrationstabelle und legen dort eine neue Zeile an. Als GUID tragen wir die GUID des AC15-Objektes ein (diese finden wird nicht im Objekt unter Subtypen, sondern in der XML-Version des Objektes in der zweiten Zeile: MainGUID), bei der AC-Version trägt man 15 ein.
Nehmen wir an, wir wollen einen Parameter ersetzen, d.h. in dem AC15 Objekt gab es einen Parameter, welcher durch einen anderen vom selben Typ ersetzt werden soll, dann sähe das Vorwärtsmigrationsscript wie folgt aus:

actualGUID = FROM_GUID
! ==============================================================================
! Subroutines
! ==============================================================================
_startID    = "5DF5E047-3F56-0344-A11A-90CB432C7D69"
_endID      = "EB59CE9E-7EBE-E945-BFCC-8B7250BA62AF"
gosub "migration"
! ==============================================================================
! Set Migration GUID
! ==============================================================================
setmigrationguid actualGUID
! ==============================================================================
end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! en
! ==============================================================================
! ==============================================================================
! migrationstepname
! ==============================================================================
"migration":
if actualGuid = _startID then
sts = DELETED_PAR_VALUE ("gold", goldValue)
metall = goldValue
PARAMETERS metall = metall
actualGuid = _endID
endif
return

Falls es mehrere Migrationsschritte gibt, kann man auch in dem 18er Objekt einen Teilschritt von AC15 nach 16, einen von 16 nach 17 und den letzten von 17 nach 18 durchführen. Dazu muss man in der Migrationstabelle alle GUIDs der Objekte, soweit diese sich unterscheiden, nacheinenander eintragen (mit Ausnahme der 18er GUID) in der Reihenfolge von alt nach neu.
Für jeden Teilschritt sähe dann das Script ähnlich aus wie oben, nur dass die GUIDs in jedem Teilschritt von der Version 15 zu 16, 16 zu 17, 17 zu 18 eingetragen werden.

Bug in ArchiCAD 18

Wichtiger Hinweis: Die GUIDs von in GDL-Objekten aufgerufenen Makros werden im GDL-Objekt gespeichert und können in der XML-Version der Objekte im Tag „called Macros“ abgelesen werden können.
Normalerweise werden die korrekten GUIDs der Makros im Objekt gespeichert, wenn man einen Makro-Aufruf anlegt und das Objekt sichert.
Es kan jedoch vorkommen, dass ein Makro-Name 2x in der geladenen Bibliothek vorhanden ist, z.B. dann wenn die ArchiCAD 18 Bibliothek UND die Migrationsbibliotheken (15, 16, 17) geladen sind, wenn ein Migrationsprozess durchgeführt wurde.
Öffne ich nun ein Objekt aus der Bibliothek 18, führe dort Änderungen durch und speichere das Objekt, dann werden die gespeicherten GUIDs der aufgerufenen AC 18 Makros durch die GUIDS der ebenfalls vorhandenen älteren Makros aus den Migrationsbibliotheken mit gleichem Namen ersetzt. Das ist eindeutig ein Bug in AC 18, der von uns im Januar 2015 an Graphisoft gemeldet wurde. In den meisten Fällen führt das Ändern der Makro-GUIDs in den Objekten zu Fehlermeldungen und Nichtdarstellung in 2D und 3D.
Daher ist Vorsicht geboten: Bei Änderungen von AC18-Objekten und gleichzeitig geladenen Migrationsbibliotheken sollte man unbedingt die Migrationsbebibliotheken während der Änderungsphase entladen.