Einführung in die GSAK Macro Welt

Voraussetzung: Pocket Queries importieren
Nachdem die letzen Tutorials sich mit PQs und deren Nutzung in GSAK beschäftigten, geht es dieses Mal mehr um GSAK selbst.
Ich möchte heute auf eine ganz entscheidene Komponente aufmerksam machen, die Verwendung von Macros. Mit diesen steht euch ein mächtiges Tool zur Verfügung um die tägliche Arbeit mit dem Programm zu vereinfachen und zu automatisieren.
Wir wollen zum Einstieg in die Macrowelt ein solches schreiben, dass in unserer Datenbank nach gefundenden bzw. eigenen Caches sucht und diese in eine eigene Datenbank verschiebt, damit wir in unserer default Datenbank nur noch Caches halten, die wir suchen wollen.
Dazu legen wir zunächst zwei Datenbanken mit dem Namen foundDB und ownDB an, indem wir auf Database-->New klicken und den gewüschten Namen eintragen.

Abbildung 1: Unser erster eigener Filter ist nicht zu kompliziert und beinhaltet als einzige Einschränkung uns selbst als Owner

Danach begeben wir uns an die Definition der Filter. Für unsere Funde stellt uns GSAK bereits einen Filter My Found Caches (GSAK Default) bereit, für unsere selbst gelegten Caches müssen wir allerdings ein klein bischen Arbeit investieren.
Nach einem Klick auf Search->Filter (alternativ Strg + F) erscheint das Fenster aus Abb.1. Da wir uns nicht auf bestimmte Cachearten oder andere Filterkritieren einschränken wollen müssen wir lediglich in der Zeile Placed by unseren Nickname eintragen und den Filter unter dem Namen My Own Caches abspeichern. (Auch hier ist der Name eigentlich Schall und Rauch, sollte aber im Hinterkopf behalten werden, da wir ihn später im Macro benötigen).
Mit einem Klick auf Save können wir die Speicheraktion einleiten.

Abbildung 2: Um die Verschiebung der Caches zu steuern legen wir eine Moveaktion an.

Die Filter sind vorbereitet, als nächstes geht es ums Verschieben. In GSAK muss man dafür im Move/Copy Dialog (erreichbar unter Database->Move/Copy Waypoints) angeben, wohin verschoben werden soll (je nach MoveAction foundDB bzw. ownDB), ob die Werte verschoben oder kopiert werden sollen und wie mit Werten umgegangen werden soll, die bereits in der Zieldatenbank vorhanden bzw. nicht vorhanden sind. Wir wollen aus der alten Datenbank verschieben, mit Einfügen bzw. Ersetzen in der neuen Datenbank. Den gesamten Dialog speichern wir als MoveAction Move to foundDB ab um es später im Macro verwenden zu können.
Damit unser Wissen auch lang hält, dürft ihr jetzt als Übung eine MoveAction definieren, die alle eigenen Caches in die passende Datenbank verschiebt. Die benötigte Datenbank sowie Filter haben wir weiter oben bereits vorbereitet.

Abbildung 3: In unserem ersten Macro verschieben wir alle Found in die foundDB und alle eigenen Cache nach ownDB

Die Vorbereitungen sind abgeschlossen, nun geht es endlich zum Macro an sich. Über Macro->Edit/Create gelangen wir zu einem Dialog wie in Abb. 3 zu sehen ist. (Genaugenommen bin ich über Macro->Run/Manage gegangen, da mein Macro bereits existierte. Da ihr es neu anlegen müsst, ist die Create Methode eure Wahl.
Die ersten Zeilen sind geprägt mit Infos über das Macro. Wer ist der Autor, wie heißt es und wichtig, falls ihr es im öffentlich Macro-GSAK-Verzeichnis einstellen wollt: Beschreibung und Version des Macros.
Alles was mit einem # beginnt ist Kommentarzeile und wird beim Abspielen des Macros nicht beachtet. So richtig los geht es erst in Zeile 8 mit der Anweisung FILTER.
Über das Attribute Name wählt ihr den vordefinierten Filter aus, der auf die akutell geöffnete Datenbank -sollte default sein-gesetzt werden soll.
Danach prüft das Macro ob es Caches gibt, für die diese Filterkriterien zutreffen. Auf deutsch: "Hab ich gerade gefundene Caches in meiner Datenbank".
Dies ist nach Zeile 10 definitiv nicht mehr so, denn hier wird mittels MOVECOPY mit den vordefinierten Einstellungen Move to foundDB alles verschoben, was der Filter hergibt.
Der Befehl ENDIF ist notwendig, falls ihr für die Caches aus dem Filter mehrere Kommandos ausführen wollt. Alles zwischen IF und ENDIF wird ausgeführt, wenn die Bedingung $_FilterCount > 0 zutrifft. $_FilterCount ist eine vordefinierte Variable von GSAK die beim Setzen eines Filters mit der Anzahl der Zeilen gefüllt wird, für die der Filter zutrifft. Um sicher zu stellen, dass ihr die weiteren Befehle nicht auf der foundDB sondern auf der Default Datenbank ausführt, setzt ihr die aktive Datenbank wieder auf Default. Es gab Versionen von GSAK, da wurde nach dem MOVECOPY die Zieldatenbank als aktive Datenbank gesetzt. Heute ist das nicht mehr so, aber sicher ist sicher und man sieht auch wie man eine Datenbank geziehlt auswählt.
Die letzten fünf Zeilen wiederholen eigenlich nur die ersten fünf, außer dass statt der gefundenen nun die eigenen gefiltert und verschoben werden.

Abbildung 4: Unser Init-Macro sollen die PQs herunterladen, gefunden und eigene Caches verschieben und abgelaufene Event entfernen.

Zum Abschluss des Tutorials erweitern wir das Aufgabengebiet unseres Macros auf alles was beim Start von GSAK durchgeführt werden soll:

• Lade die aktuellen PQs
• Verschiebe gefundene und eigene Caches
• Entferne Event, die bereits stattgefunden haben

'Moment', wird sich der aufmerksame Leser von Pocket Queries importieren denken, 'bei der Definition der PQs haben doch die gefundenen sowie eigenen Caches ausgeschlossen'.
Dies ist soweit richig. In späteren Tutorials sehen wir, wie sich GSAK hervorragend zur Statistikgenerierung eignet. Dafür ist es aber notwendig alle gefundenen Caches in einer Datenbank zu pflegen. Aus diesem Grunde lasse ich alle paar Tage eine myFinds-PQ mitlaufen, die mir die gefundenen Caches im 50 km zuschickt. Details folgen in der versprochenen Fortsetzung.
Eigene Cache landen zwar immer noch recht selten in der Default Datenbanken (höchstens durch einmalige PQs die zwischendurch geniert werden bzw durch Einzelimport per GPX file-Button auf der GC-Seite) aber der Filter und die MoveAction diesbezüglich frisst kein bzw. nicht viel Brot und stört insofern nicht weiter. Sicher ist sicher, gell.

Nun aber zum Macro, als allererstes selektieren wir die Default-DB und führen mittels GcGetPg das Abrufen und Verarbeiten der PQs aus. Hier muss darauf geachtet werden das richtige Settings zu nehmen. Damit es zum letzten Tutorial passt, müsst ihr MyPQDLSettings statt PQDLMW nehmen.
Da wir das Verschieben der Funde a) als eigenes Macro belassen möchten (um diesen Schritt alleine ausführen zu können), b) aber die Anweisungen nicht wiederholen möchten (Codeduplikation ist für den Entwickler immer ein rotes Tuch) nutzen wir die Möglichkeit das jedes Macro Untermacros ausführen kann. Mit Macro unter der Angabe des Dateinahmens führen wir so in unserem Init-Macro einfach das MoveFounds Macro aus. Beide Datei müssen dafür im selben Macroverzeichnis sein, aber das schlägt euch GSAK beim Abspeichern schon korrekt vor.

Nach dem Motto, das Beste kommt zum Schluss nutzen wir in den letzen Zeilen den MFilter. Mit diesem Tool kann man OnTheFly Filter definieren, die a) nicht gespeichert werden müssen und b) nicht die Cache-Ansicht verändern. Will heißen MFilter betrifft nur die Auswahl der Caches im Macro. Sobald das Macro endet wird der Wert verworfen, während FILTER die Auswahl der in GSAK angezeigten Caches manipuliert. Im Where Attribute von MFilter führen wir SQL-ähnlich eine Einschränkung auf den Cachetyp (Event, Z für Megaevent und CITO) sowie das Plazierungsdatum was bei Events dem Tag des Events entspricht. date('now') ist eine GSAK-, bzw. sqlite-interne Funktion um das Tagesdatum zu ermitteln.
Auch hier wird wieder kontrolliert, ob überhaupt abgelaufene Events vorhanden sind und gegebenenfalls mit macrodelete action=delscope (löscht alle selektierten Caches) und macrodelete action=commit (schreibt die zunächst lokale Änderung auf die sqlite-Datenbank durch) entfernt. Hier sieht man auch warum IF mit ENDIF abgeschossen werden muss, da zwei Zeilen von der Bedingung betroffen sind.
Dies soll für heute reichen. Beim nächsten Mal wird es etwas einfacher. Da kümmern wir uns um den Klicki-Bunti-Teil "Wie definiere ich für mein Macro nen hübschen Button?"