Sequencer Tutorial

Innerhalb dieses Tutorials wird ein kleines Demo-Projekt erstellt das mehrere einfache Sequenzen enthält. Das Tutorial gibt eine Einführung darüber wie man den Sequencer einsetzen kann und erklärt dessen grundlegende Konzepte.

1. Wechsel des Arbeitsbereiches

Für jedes Projekt legt man mit dem Sequenzer einen eigenen Projektordner an. Dieser Ordner wird auch Arbeitsbereich genannt und in ihm werden die Sequenzen abgespeichert die zu diesem Projekt gehören. In ihm sollten auch alle projektbezogenen Dokumente und Resourcen gespeichert werden da der Sequencer an vielen Stellen Schnellzugriffe auf diesen Ordner bereitstellt, z.B hier:

drücke um den Arbeitsbereich im Dateibrowser zu öffnen

gehe mit der Maus über den Namen des Arbeitsbereiches um seinen Pfad im Tooltip zu sehen

Der erste Arbeitsbereich wird automatisch im Benutzerverzeichnis angelegt. Wir werden dieses Tutorial als kleines eigenes Projekt betrachten, also legen wir für es einen eigenen Arbeitsbereich an:

drücke um den aktuellen Arbeitsbereich zu wechseln

gebe den Namen für den neuen Arbeitsbereich ein, z.B. „TutorialWS“

drücke „create…“ und wähle den Ort für den neuen Ordner des Arbeitsbereiches

2. Die erste Sequenz

Die erste Sequenz soll „Hallo Welt“ in einem Dokument anzeigen und eine Messagebox öffnen.

drücke um eine Sequenz zu erzeugen, nenne sie „Hallo Welt“

Nun müssen wir die Aktionen hinzufügen die sich um das Dokument und um die Messagebox kümmern. Welche Aktionstypen verfügbar sind sieht man wenn man auf drückt und mit der Maus über die einzelnen Knöpfe geht. Um ein Dokument anzuzeigen gibt es bereits einen standard Aktionstyp und für die Messagebox werden wir eine Zeile Script schreiben.

Dokument:

drücke und wähle den Aktionstyp „Lade Dokument“

Noch ist der Aktion keine Dokumentdatei zugewiesen die geladen werden soll, daher ist die Aktion Rot und kann nicht ausgeführt werden. Wir werden nun kein bereits vorhandenes Dokument auswählen sondern ein neues erstellen:

drücke „Neu“ in der Aktion und benenne das Dokument „HalloWeltDoc“

füge ein Text Object auf der ersten Seite hinzu und beschrifte es mit „Hallo Welt!

speichere das Dokument (es liegt im Arbeitsbereich) und schließe es

Messagebox:

drücke und wähle den Aktionstyp „Script Ausführung“

drücke „Neu“ und benenne das Script file „ShowMessageBox“

schreibe die Zeile

MessageBox("Hallo Welt!")

speichere das Script

Das war’s, die Sequenz kann nun durch Drücken auf den Play Knopf (Sequenzbereich) ausgeführt werden.

Die Aktionen können auch einzeln ausgeführt werden. Drücke hierfür den Play Knopf im Aktionsbereich oder doppelklicke die Aktion in der Sequenzliste.

speichere die Sequenzkonfiguration im Arbeitsbereich

3. Grundlegendes Daten-Handling

Um die Aktionstypen „Datenaustausch“ und „Dateibrowser“ vorzustellen werden wir nun erst einmal zwei kleine Datenfiles erstellen:

erstelle eine neue Datei „Data1.csv“ im Ordner des Arbeitsbereiches und schreibe in diese:

Time, Torque
s, Nm
1, 50
2, 150
3, 120

Denke daran den Arbeitsbereich hier öffnen zu können:

erstelle eine zweite Datei „Data2.csv“ im Arbeitsbereich und schreibe in diese:

Time, Torque
s, Nm
1, 110
2, 40
3, 60

lade „Data1.csv“ in den Datenbrowser

Nun wollen wir die Daten in einem 2D x/y Chart in unserem Dokument anzeigen. Nach der Ausführung der „Lade Dokument“ Aktion wird das Dokument als Kopie geladen. Dies verhindert das versehentliche Überschreiben des Originaldokuments in Workflows bei denen das finale Dokument aus einem Basisdokument heraus generiert wird. Den Unterschied zwischen „Ausführen“ und „Bearbeiten“ sieht man z.B. in der Menüzeile von Uniplot. Wir wollen unser Dokument also bearbeiten:

selektiere die „Lade Dokument“ Aktion und drücke „Bearbeiten“

selektiere „Time“ als X-Kanal and „Torque“ als Y-Kanal im Datenbrowser und drücke „Laden“

speichere das Dokument

Es sollte nun folgendermaßen aussehen:

Nun werden wir unser zweites Datenfile während der Sequenzausführung in unser Dokument laden:

füge zur Sequenz eine Aktion „Datenaustausch“ hinzu

selektiere in dieser „Data2.csv“ aus dem Arbeitsbereich über

die Script Aktion kann nun mit der Checkbox in der Sequenzliste abgeschaltet werden

Wird die Sequenz jetzt gestartet wird sie das Dokument nun laden und die Daten mit unserem zeiten Datenfile ersetzen.

4. Der erste Runtime Value

Im nächsten Schritt werden wir etwas Benutzerinteraktion in unsere Sequenz einbauen, der Benutzer soll das Datenfile nun innerhalb der Sequenzausführung auswählen können. Hierfür werden wir zum ersten Mal „Runtime Values“ verwenden, da man mit deren Hilfe Aktionen aus anderen Aktionen heraus steuern kann. In userem Fall wird eine Aktion („Dateibrowser“) den Dateipfad zu den Daten bestimmen und dieser wird von einer weiteren (unserer „Datenaustausch“ Aktion) verwendet.

füge zur Sequenz eine Aktion „Dateibrowser“ hinzu und schiebe sie mit an den Anfang der Sequenz

Bei einem Blick auf die Einstellungen der neuen Aktion sieht man, daß der Pfad zur ausgewählten Datei in den Runtime Value „DATAFILEPATH“ geschrieben wird:

führe die Aktion „Dateibrowser“ einzeln aus und wähle „Data2.csv“

Der Runtime Value ist nun gesetzt, man sieht ihn nach Drücken auf im Arbeitsbereich. Nun werden wir den Pfad in unserer „Datenaustausch“ Aktion verwenden. Dafür schalten wir den Eingang von „Aus Arbeitsbereich“ zu „Aus Runtime Value“ . Der Name „DATAFILEPATH“ ist in beiden Aktionen vordefiniert um bereits überein zu stimmen, aber es können natürlich auch andere Namen verwendet werden.

Wird die Sequenz jetzt gestartet sieht man wie beide Aktionen nun zusammen spielen.

Darüber hinaus kann man den Mechanismus zur Dateiauswahl sogar noch erweitern indem man eine „Setze Runtime Values“ Aktion vorschaltet. So kann man den Wert von „DATAFILEPATH“ vordefinieren, also quasi einen default Pfad setzen. Die „Dateibrowser“ Aktion kann man nun bei Bedarf einfach dazuschalten.

5. PDF Export, weiterer Einsatz von Runtime Values

Nun wollen wir unser Dokument am Ende der Sequenz als PDF exportieren. Das ist einfach:

füge zur Sequenz eine Aktion „PDF Export“ hinzu

Drücke Play und die PDF Datei wird erzeugt.

(falls für UniPlot noch kein Ghostscript konfiguriert wurde, bitte hier schauen Datei=>PDF-Export)

Die Voreinstellung für den Dateinamen des PDF files ist „FIX“ („MyFileName“), also konstant. Nun wollen wir den Namen allerdings dynamisch erzeugen. Als Beispiel wollen wir den Namen der Datendatei nehmen und dazu das aktuelle Datum anhängen. Also werden wir den Namen in einem kleinen Script zusammenbasteln und diesen dann an die „Export PDF“ Aktion weitergeben. Auch hierfür werden wir wieder „Runtime Values“ verwenden, auf diese kann man mit Seq_GetRuntimeValue und Seq_SetRuntimeValue innerhalb eines Scriptes zugreifen:

füge zur Sequenz eine Aktion „Script Ausführung“ hinzu, drücke „Neu“ und nenne das Script „GeneratePdfFilename“

schiebe die Aktion vor die „PDF Export“ Aktion

drücke „Bearbeiten“, schreibe folgende Zeilen und speichere das Script:

sDataFilePath = Seq_GetRuntimeValue("DATAFILEPATH")

sDataFileName = SplitPath(sDataFilePath)[3]
sDate = DT_Format(DT_GetCurrentTime(), "%x")
sPdfFileName = sDataFileName + "_" + sDate

Seq_SetRuntimeValue("PDF_FILENAME", sPdfFileName)

schalte die Dateinamensdefinition in der „PDF Export“ Aktion auf

Das wars, jetzt kann man die Sequenz laufen lassen, das exportierte PDF Dokument erhält nun dynamisch seinen Namen.

6. Starten und steuern des Sequenzers aus externer Software heraus

Es ist ein üblicher Anwendungsfall eine Auswertung aus einer externen Software (z.B. Automatisierungssysteme, Datenbank Tools) heraus zu starten. Meistens müssen hierbei auch noch einzelne Parameter übergeben werden, wie z.B. der Pfad eines Datenfiles oder einige Flags zur Beeinflussung des Generierungsvorganges.

Dies ist durch die Verwendung des Sequenzers in UniPlot sehr einfach.

Hierzu muss einfach ein Batch file geschrieben werden, in dem der Ort des Arbeitsbereiches (/ws), der Name der Sequenz (/seq) und die Liste der Parameter (/rv) übergenben werden.

schalte die „Dateibrowser“ Aktion nun aus, wir wollen den Pfad zu unseren Daten nun im Batch file definieren

speichere den Arbeitsbereich mit und schließe UniPlot

erstelle ein Text file, kopiere die folgende Zeile hinein und speichere es als „MyCmd.bat“

C:\Uniplot\uniplot.exe /ws "D:\Projects\TutorialWS" /seq "Hello World" /rv "DATAFILEPATH = D:\Projects\TutorialWS\Data2.csv"

ändere den Pfad zur uniplot.exe wenn nötig

ändere den Pfad zum Arbeitsbereich wenn nötig

ändere den Pfad zum Daten file wenn nötig

speichere und schließe das batch file

Ein Doppelklick auf das file öffnet nun UniPlot und startet die Auswertung unter Verwendung von „Data2.csv“.

Um die automatische Auswertung nun zu vervollständigen wollen wir, daß sich UniPlot nach dem Export des PDF files automatisch schließt. Für solch kleine Aufgaben die nicht speziell konfiguriert werden müssen gibt es einen weiteren Aktionstyp, er heißt „Snippets“:

füge zur Sequenz eine Aktion „Snippet“ hinzu und wähle die Funktionalität „Shutdown“

schalte die Option „Öffne PDF“ in the „PDF Export“ Aktion aus

Speichere den Arbeitsbereich und schließe Uniplot. Starte das batch file, Uniplot ist nun bereit für eine komplett automatisierte Auswertung.

7. Bedingte Ausführung von Aktionen

Neben der Möglichkeit einzelne Aktionen mit der Checkbox in der Sequenzliste An und Aus zu schalten kann man über einen Runtime Value auch dynamisch steuern ob eine Aktion ausgeführt werden soll oder nicht.

Als Beispiel wollen wir nun einen zweiten Parameter zu unserem batch file hinzufügen welcher steuern soll ob der PDF Export ausgeführt werden soll oder nicht:

erweitere den /rv parameter im batch file mit dem Runtime Value „DO_PDF_EXPORT“

/rv „DATAFILEPATH = D:ProjectsTutorialWSData2.csv, DO_PDF_EXPORT = 1“

drücke in der „Export PDF“ Aktion

schalte „Bedingte Ausführung“ an und gib ein:

drücke „OK“

Beachte das der Hintergrund der Checkbox in der Sequenzliste lila eingefärbt ist um anzuzeigen das die Aktion nun nur unter einer bestimmten Bedingung ausgeführt wird. Steuern lässt sich diese Bedingung nun über den Parameter „DO_PDF_EXPORT“ im batch file.

8. Mehrfache Ausführung von Aktionen

Neben der bedingten Ausführung gibt es auch noch ein weiteres allgemeines Feature in jeder Aktion, und dies ist die mehrfache Ausführung bzw. das Loopen von Aktionen. Hierbei wird die Aktion abhänging von der Größe einer Liste in einem Runtime Value mehrfach ausgeführt. Um diese Feature zu zeigen werden wir zwei neue Sequenzen erstellen:

drücke und nenne die neue Sequenz „Start Sequenz“

drücke und nenne die neue Sequenz „Looped Sequenz“

füge zur Sequenz „Start Sequenz“ eine Aktion „Setze Runtime values“ hinzu

füge hier einen Runtime Value „PATH_LIST“ hinzu und setze seinen Wert auf

C:\MyFile1.txt, C:\MyFile2.txt, C:\MyFile3.txt

füge zur Sequenz „Start Sequenz“ eine Aktion „Starte Sequenz“ hinzu und wähle hier „Looped Sequenz“ aus

drücke in der „Starte Sequenz“ Aktion

aktiviere hier „Mehrfache Ausführung“ und gib ein:

drücke „OK“

drücke um in die Subsequenz zu springen

füge zur Subsequenz „Looped Sequenz“ eine Aktion „Script Ausführung“ hinzu, bearbeite und schreibe:

sPath = Seq_GetRuntimeValue("SINGLE_PATH")

sMessage = "In diesem Durchlauf der Subsequenz kannst du SINGLE_PATH\n"
sMessage = sMessage + "mit seinem Wert \"" + sPath + "\" verwenden!"

MessageBox(sMessage)

speichere das Script

Starte nun die Sequenz „Start Sequence“. Die Subsequenz „Looped Sequenz“ wird nun für jeden Eintrag aus dem Runtime Value „PATH_LIST“ aufgerufen wobei sich der Wert von „SINGLE_PATH“ jeweils ändert.

Ein geläufiger Anwendungsfall für diese Feature ist z.B. die Definition einer Dateiliste in einem batch file um mehrere Auswertungen mit verschiedenen Datenfiles über eine Aufruf anzusteuern.

9. Fazit

Glückwunsch, wir haben nun unseren ersten eigenen Abeitsbereich mit einer kleinen Liste von Sequenzen erstellt!

Versuche doch mal den Sequenzer in einem deiner nächsten Projekte einzusetzen, wir sind sicher das dieses neue Feautre das Strukturieren der Auswertungen erleichtern wird. Auch das schnelle Wechseln zwischen Projekten und die Möglichkeit separat einzelne Teile der Auswertung mit nur einem Mausklick auszuführen werden helfen.

Wir sind offen für ein allgemeines Feedback oder Vorschläge für neue Aktionstypen und Snippets!

Dies wird auch Basis dafür sein in welche Richtung wir dieses Feature weiterentwickeln.

_id-1074338