So funktionieren Funktionen in Transformationen, Variablen und Aufrufbedingungen

Sie erreichen sie über den Dialog Transformation des zugewiesenen Werts bearbeiten, und überall, wo Transformationen vorkommen, wird dieselbe Engine verwendet.

Jede Transformation läuft in zwei Phasen ab, immer in dieser Reihenfolge:

1. Der primäre Ausdruck wird einmal ausgewertet und erzeugt einen Wert.
2. Anschließend wird eine Kette von Transformationsaktionen nacheinander auf diesen Wert angewendet.

[data] ist der Platzhalter für „den Wert, der gerade bearbeitet wird“. Nach der Ausführung des Ausdrucks enthält [data] dessen Ergebnis. Bei jeder ausgeführten Aktion wird [data] auf die Ausgabe dieser Aktion aktualisiert und an die nächste Aktion übergeben.

Worauf Sie verweisen können

In einem Ausdruck (und in den meisten Aktionsfeldern) können Sie verschiedene Arten von Elementen einfügen. Die Symbolleistenschaltflächen Spalte einfügen, Variable einfügen und Wert einfügen – oder das Kontextmenü – fügen die korrekte Notation für Sie ein.

Notation	Verweist auf
[My field name]	Eine Quellspalte in DataETL- und Dateiverwaltungs-Transformationen.
[<my variable>]	Eine von Ihnen definierte Variable.
[<#my auto generated variable>]	Eine automatisch generierte Variable. Identisch mit einer normalen Variable – das Präfix # kennzeichnet lediglich, dass sie generiert und nicht von Ihnen erstellt wurde.
[data]	Den aktuellen Wert – typunabhängig, wird während der Ausführung der Aktionskette aktualisiert.
[original]	Den vom primären Ausdruck zurückgegebenen Wert, bevor eine Transformationsaktion ihn verändert hat.

[data] wandert mit der Kette mit; [original] ändert sich nach der Ausführung des Ausdrucks nie mehr. Verwenden Sie [original] in einer späteren Aktion, wenn Sie den Wert vor den Aktionen wieder benötigen.

Verweise auf Spalten innerhalb eines ForEach

Eine ForEach-Komponente generiert beim Speichern der Komponente für jede ihrer Quellspalten eine Variable. Innerhalb des ForEach können Sie daher auf zwei Arten auf eine Quellspalte verweisen:

• Über ihre generierte Variable – [<#my auto generated variable>]
• Über die Quellspalten-Notation – [#source columns]

Beide liefern denselben Wert.

Das Ziel bestimmt den Typ

Das Ergebnis einer Transformation wird in ein Ziel geschrieben, dessen Datentyp fest auf Text, Datum/Zeit oder Zahl eingestellt ist. Ihr Ausdruck (und der endgültige Wert nach allen Aktionen) muss diesen Typ liefern. Ein Ziel vom Typ Zahl akzeptiert keinen Wert, den die Engine nicht als Zahl lesen kann, und so weiter.

[data] selbst ist typunabhängig – es enthält einfach den jeweils aktuellen Wert. Wenn Sie einer Zielspalte oder einer Zielvariable einen Wert zuweisen, repräsentiert [data] diesen Wert.

Phase 1 – der primäre Ausdruck

Im Ausdruck verrichten Funktionen ihre Arbeit: If(), Pos(), Dec(), Char() und die übrigen. Die vollständige Liste mit Signaturen und Beispielen finden Sie hinter der Schaltfläche Ausdrucksdokumentation. Mit Ausdruck testen können Sie einen Ausdruck mit einem Testwert ausprobieren, den Sie für den Platzhalter [data] eingeben, bevor Sie ihn übernehmen.

Ein Ausdruck darf kein literales doppeltes Anführungszeichen (") enthalten. Wenn Sie eines ausgeben müssen, erzeugen Sie es mit Char(34) – Char() kann das Zeichen " ausgeben, obwohl Sie es im Ausdruck nicht direkt eingeben können.

Rechtsklick: Einfügen, Funktionen und Kommentare

Ein Rechtsklick im Ausdruckseditor öffnet ein Kontextmenü, das oft schneller ist als die Symbolleiste:

• Suchen und ersetzen – Suchen/Ersetzen innerhalb des Ausdruckstexts selbst.
• [data] einfügen – fügt den Platzhalter [data] ein.
• Funktion einfügen – ein Untermenü mit allen integrierten Funktionen, gruppiert nach Kategorien: Logisch, Zeichenfolge, Numerisch, Datum und Zeit, Dateiverarbeitung, Ordner, Sonstige, SQL und SharePoint. Wenn Sie eine Funktion auswählen, wird ihr Grundgerüst mit den Argumentnamen in den Editor eingefügt, z. B. Mid( 'string', start {, length } ) oder IndexValue( 'sourcestring', 'delimiterstring', indexnumber ). In { } angezeigte Argumente sind optional.
• Spalte einfügen… / Variable einfügen… – wie die Schaltflächen der Symbolleiste.
• Auskommentieren / Kommentar entfernen – schaltet Kommentarzeichen in den ausgewählten Zeilen um, sodass Sie einen Teil eines Ausdrucks deaktivieren können, ohne ihn zu löschen.
• Die Standardbefehle Kopieren, Ausschneiden, Einfügen, Löschen.

Einige Zeichenfolgenfunktionen, die Sie früh kennen sollten: Char(34) für ein doppeltes Anführungszeichen, GenerateGUID(), JSONDecode() / JSONEncode(), ExtractMetadataColumn('metadata','column name','default value') und SkipString('My reason'), um den Wert mit einer protokollierten Begründung zu überspringen. Die vollständige, nach Kategorien geordnete Liste finden Sie in der Funktionsreferenz.

Ein SQL SELECT als Ausdruck verwenden

Aktivieren Sie SQL SELECT 1 Zeile/Spalte, und die Auswahl Datenbankverbindungen verwalten wird geöffnet. Dort wählen Sie eine beliebige konfigurierte Verbindung (SQL Server, MS Access, ODBC oder die interne Datenbank). Ihr Ausdruck wird dann zu einem einzelnen SQL-SELECT, das eine Spalte zurückgibt:

SELECT dbo.bindtest.col_customer_name FROM dbo.bindtest WHERE mycol = [data]

Das einzige im Ausdruck unterstützte SQL-Schlüsselwort ist SELECT. Außerdem kann das SQL SELECT nur im ersten, primären Ausdruck verwendet werden.

Regeln für die SQL-SELECT-Form:

• Die Anweisung muss eine Spalte zurückgeben.
• Werden mehrere Zeilen zurückgegeben, werden sie mit %NewLine% verbunden, und es werden maximal 250 Zeilen verarbeitet.
• Sie können [data], Spalten und Variablen an beliebiger Stelle in der Anweisung als Argumente verwenden:

SELECT Max(MyCol) FROM MyTable WHERE abc = [<MyVar>] AND xyz = [data]

Phase 2 – Transformationsaktionen

Sobald der Ausdruck einen Wert erzeugt hat, fügen Sie über das Menü Aktion hinzufügen Aktionen hinzu. Sie werden von oben nach unten ausgeführt, wobei jede die Ausgabe der vorherigen Aktion als [data] erhält. Es gibt fünf:

Aktion	Funktion
Datenvalidierung	Prüft den Wert und schreibt Meldungen in das Sitzungsprotokoll des Auftrags; kann die Kette anhalten.
Ausdruck	Wendet einen weiteren Ausdruck auf den Wert an.
XML/JSON-Tag extrahieren	Liest den Wert bzw. die Werte benannter Tags aus einer XML-/JSON-Zeichenfolge aus.
Nachschlagen	Ordnet den Wert 1:1 über eine Wertzuordnungsliste zu.
Vorkommen ersetzen	Sucht und ersetzt innerhalb des Werts anhand einer Wertzuordnungsliste.

Datenvalidierung

Der Eingabetyp ist String, und die Aktion muss einen String zurückgeben, der mit einem dieser Präfixe beginnt. Der Text nach dem Doppelpunkt wird in das Sitzungsprotokoll des Auftrags geschrieben.

Präfix	Wirkung
Ok:	Wert akzeptiert. Es wird keine Zeile zum Sitzungsprotokoll hinzugefügt.
Warning:	Der Text nach dem Doppelpunkt wird als Warnung protokolliert.
Error:	Der Text nach dem Doppelpunkt wird als Fehler protokolliert.
Ignore:	Der Text nach dem Doppelpunkt wird protokolliert; der Wert wird ignoriert.
Return:	Beendet die Auswertung weiterer Aktionen.

Sowohl [data] als auch [original] stehen zur Verfügung. Beispiele:

If( Dec('[data]') > 100.01 , 'Error:[data]>100.01' , 'Ok:' )
If( 'xyz' + [data] = 'xyz1' , 'Ok:' , 'Warning:[data]' )
If( Pos( '[data]' , 'Apple' ) > 0 , 'Ok:[data]' , 'Ignore:' )
If( Pos( '[data]' , 'Apple' ) > 0 , 'Ok:' , 'Return:[data]' )

Ausdruck (Aktion)

Ein zweiter Ausdruck, jedoch mit einer Einschränkung, die für den primären Ausdruck nicht gilt: Er muss denselben Datentyp zurückgeben, den er erhalten hat. [data] ist der aktuelle Wert, [original] das Ergebnis des primären Ausdrucks.

Wert aus XML/JSON-Tag extrahieren

Geben Sie einen oder mehrere Tag-Namen, getrennt durch Semikolons, ein; die Aktion gibt deren Wert(e) zurück. Zwei Optionen:

• Wenn ein Tag gefunden wird, Verarbeitung der übrigen Aktionen beenden.
• Wenn das Tag nicht gefunden wird, Wert auf leere Zeichenfolge setzen.

Nachschlagen (1:1 zuordnen)

Ordnet den aktuellen Wert über eine Wertzuordnungsliste zu – ein Treffer in der Spalte Suchwert der Liste liefert den zugehörigen Ersetzungswert. Wählen Sie die Liste aus, oder erstellen Sie eine mit Neue Zuordnungsliste / Zuordnungswerte bearbeiten.

Die Einstellung Wenn keine Zuordnung gefunden steuert das Ausweichverhalten:

Option	Verhalten ohne Treffer
<No mapping>	Wert unverändert lassen.
<No mapping - Add to Mapping List>	Wert unverändert lassen und zur Liste hinzufügen.
<Map to blank>	Durch eine leere Zeichenfolge ersetzen.
Map to the value I type here	Durch einen von Ihnen angegebenen festen Wert ersetzen.

Aktivieren Sie Bei Zuordnung Verarbeitung der übrigen Aktionen beenden, um die Kette nach einer erfolgreichen Zuordnung zu beenden.

Vorkommen ersetzen

Ebenfalls über eine Wertzuordnungsliste gesteuert, ersetzt diese Aktion jedoch innerhalb des Werts, statt den gesamten Wert zuzuordnen. Zwei Einstellungen bestimmen das Verhalten:

Ersetzungsbereich – welche Treffer ersetzt werden:

• Alle Vorkommen
• Alle außer dem ersten Vorkommen
• Alle außer dem letzten Vorkommen
• Nur das erste Vorkommen
• Nur das letzte Vorkommen

Wertepaare – welcher Ersetzungswert verwendet wird, wenn mehrere Listeneinträge zutreffen:

• Alle gefundenen Ersetzungswerte verwenden
• Nur den ersten gefundenen Ersetzungswert verwenden
• Durch den ersten gefundenen Ersetzungswert substituieren
• Durch die Liste der gefundenen Ersetzungswerte substituieren

Optionen: Bei Ersetzung Verarbeitung der Aktionen beenden und Wenn keine Ersetzung erfolgt, Wert auf leere Zeichenfolge setzen.

Wertzuordnungslisten

Sowohl Nachschlagen als auch Vorkommen ersetzen greifen auf Wertzuordnungslisten zurück, die Sie über Zuordnungslisten verwalten pflegen. Jede Liste enthält Zeilen der Form Suchwert → Ersetzungswert mit einer Spalte Reihenfolge.

Sie können eine Liste auf drei Arten pflegen:

• Manuell – im Fenster Wertzuordnungsliste bearbeiten (Neu, Kopieren, Löschen, Speichern, Sortierreihenfolge neu nummerieren).
• Aus Excel – kopieren Sie zwei Spalten (Suchwert und Ersetzungswert) in Excel und laden Sie sie mit Aus Zwischenablage/Excel einfügen in einem Schritt. Listen können auch nach Excel oder in den Editor (Notepad) exportiert werden.
• Aus einem Auftrag – DataETL kann Zeilen von Zuordnungslisten programmgesteuert einfügen, aktualisieren und löschen, sodass eine Liste im Rahmen eines Laufs automatisch erstellt oder aktualisiert werden kann, statt nur manuell.

Richten Sie DataETL auf die interne Datenbank aus, um Werte von Zuordnungslisten programmgesteuert zu bearbeiten.

Ausdrücke als Aufrufbedingungen in einer Collection

Dieselbe Ausdrucks-Engine steuert auch Aufrufbedingungen innerhalb einer Collection. Eine Collection fasst mehrere Komponenten (Schritte) zu einer Einheit zusammen – und eine Collection kann weitere Collections enthalten. Jede Komponente kann eine mit Bedingung erstellen festgelegte Bedingung besitzen, die zur Laufzeit entscheidet, ob diese Komponente aufgerufen wird.

Eine Aufrufbedingung ist stärker eingeschränkt als eine Transformation. Sie:

• ist ein einzelner Ausdruck – es gibt keine Kette von Transformationsaktionen und keinen Platzhalter [data];
• kann nur auf Variablen verweisen – in der Notation [<MyVariable>]. In diesem Kontext gibt es keine Quellspalten, daher ist Variable einfügen die einzige Einfügeschaltfläche (neben Ausdruck testen und Ausdrucksdokumentation).

Der Ausdruck muss einen String zurückgeben, und dieser String ist ein Steuerschlüsselwort, das dem Auftrag mitteilt, wie mit der Komponente zu verfahren ist:

Rückgabewert	Wirkung
True	Komponente ausführen.
False	Komponente überspringen.
ExitGroup	Diese und die übrigen Komponenten der Gruppe überspringen.
ExitGroupWarning	Wie ExitGroup, protokolliert jedoch eine Warnung.
StopJob	Auftrag sofort stoppen.
StopJobWarning	Auftrag sofort stoppen und eine Warnung protokollieren.

Wie bei den Präfixen der Datenvalidierung können Sie nach einem Doppelpunkt eine Meldung anhängen, die in das Sitzungsprotokoll des Auftrags geschrieben wird:

If( [<MyVariable>] > 0 , 'True' , 'False' )
If( [<MyVariable>] > 0 , 'True' , 'StopJob:Job cannot continue' )