Skip to main content

xSuite Interface Windows Prism 5.x – Online-Hilfe

Funktionen

Eine Funktion besteht aus dem Namen der Funktion, gefolgt von runden Klammern mit einer kommaseparierten Liste der Parameter:

{Funktionsname}({Parameter1}, …, {ParameterN})

Die Parameterliste kann komplett leer sein. Die runden Klammern müssen zur syntaktischen Kennzeichnung der Funktion als solche jedoch immer angegeben werden. Einige Funktionen haben Parameter, deren Angabe optional ist. Da die Parameter aber nicht über einen Namen gekennzeichnet sind, sondern nur über die Reihenfolge in der Parameterliste identifiziert werden, muss bei der Auslassung eines Parameters trotzdem das Trennzeichen aufgeführt werden, wenn danach noch weitere Parameterwerte folgen. Bei einer Funktion Test() mit 3 Parametern, wovon die letzten beiden optional sind, ist Test(Param1, , Param3) oder Test(Param1) beispielsweise korrekt, Test(Param1, Param3) hingegen nicht.

Abhängig von der Art der Funktion kann diese einen Ergebniswert zurückliefern oder nicht. Unabhängig davon besitzen einige Funktionen spezielle Parameter für (zusätzliche) Rückgabewerte, allerdings nur indirekt in Form eines Feldnamens, nicht einer Feldvariable. Die Funktionsparameter dienen ausschließlich als Eingabeparameter, sodass bei einer Variable @Feldname ein im Makro veränderter Wert dieses Feldes nicht direkt in die Variable zurückgeschrieben wird. Stattdessen ist der "Feldname" als Parameterwert anzugeben, über den das Makro das Feld im Dokument identifiziert und den Wert dieses Feldes verändert.

Die verfügbaren Funktionen sowie die spezifischen Parameter, die jeweils benötigt werden, finden Sie unter Makrofunktionen.

Makrofunktionen sind in die folgenden 4 Arten unterteilt, die sich in ihrer grundlegenden Aufgabe und Arbeitsweise unterscheiden:

Feldmakro

Eine Feldmakrofunktion liefert einen einzelnen Ergebniswert zurück, der in der Regel einem Feld zugewiesen wird. Makroausdrücke dieser Art können aber auch in anderem Kontext genutzt werden, insbesondere als Unterfunktionen, die einen Parameterwert für eine der anderen Makrofunktionen berechnen, und zur dynamischen Generierung von Werten bestimmter Konfigurationseigenschaften.

Unter einem Feldmakro ist nicht nur ein Ausdruck in der Syntax einer Funktion zu verstehen, sondern jeglicher Makroausdruck, der einen Ergebniswert produziert. Das kann also ebenso ein Operator mit dessen Operanden sein als auch eine einzelne Variable oder ein konstanter Wert.

Dokumentmakro

Eine Dokumentmakrofunktion führt in der Regel inhaltliche Änderungen direkt an den Daten des gerade aktiven Dokumentes durch, in dessen Kontext sie aufgerufen wird. Makroausdrücke dieser Art liefern keinen Rückgabewert als Ergebnis der Funktionsausführung zurück.

Dokumentmakros werden meist genutzt, um umfangreichere Anpassungen an den Indexdaten des Dokumentes vorzunehmen, die über einen einzelnen Feldwert hinausgehen.

Mangels Rückgabewert können Dokumentmakros nicht mit anderen Makroelementen kombiniert werden und stehen daher normalerweise auf oberster Ebene eines Makroausdrucks. Dokumentmakros können nur in speziellen Funktionen eingebunden werden, die der bedingungsabhängigen Ausführung eines Unterausdrucks dienen, z. B. in der Funktion If() .

Dateimakro

Für eine Dateimakrofunktion gilt grundsätzlich das Gleiche wie für ein Dokumentmakro. Bei einem Dateimakro beziehen sich die Anpassungen am Dokumentinhalt jedoch auf die Dateianlagen des Dokumentes und nicht auf die Indexdaten. Typischerweise bestehen diese Anpassungen aus der Konvertierung der Dateianlagen in ein anderes Dateiformat, das für die Weiterverarbeitung oder von einem Ausgabesystem benötigt wird. Allerdings existieren auch Dateimakros, die keine Konvertierung, sondern andere Aktionen anhand der Dateianlagen durchführen, z. B. die Extraktion eingebetteter Dateien oder die Generierung neuer Anlagen.

In allen Fällen bleiben die Quelldateien, die als Grundlage für eine Aktion herangezogen werden, als Dateianlagen am Dokument erhalten. Bei einer Konvertierung wird somit beispielsweise nicht direkt die Quelldatei durch die Zieldatei in dem neuen Format ersetzt, sondern eine zusätzliche Dateianlage im Zielformat an das Dokument angefügt. Welches der alternativen Formate der gleichen Datei in weiteren Arbeitsschritten herangezogen wird, ist an den betreffenden Stellen über Dateinamensfilter zu konfigurieren. Für die Übergabe an ein Ausgabesystem ist das beispielsweise die Eigenschaft OutputSystem[].FileFilter.

Die Parameterliste für Dateimakros folgt einem festen Schema. Die ersten beiden Parameter sind für alle Makros dieses Typs identisch. Erst ab der dritten Position folgen die individuellen Parameter des jeweiligen Makros.

  1. Der erste Standardparameter dient der optionalen Definition des Namensfilters für die vorhandenen Dateianlagen, die als Quelle für die Funktionsausführung dienen sollen. Wenn dieser Parameter nicht angegeben wird, greift ein zur jeweiligen Funktion passender Vorgabewert, z. B. *.pdf bei einer Funktion, die PDF-Quelldateien verarbeiten soll. Grundsätzlich verarbeitet die Funktion nacheinander alle gefundenen Dateianlagen, die zum angegebenen Muster passen. Bei Mehrdeutigkeiten, z. B. wenn mehrere PDF-Dateianlagen vorhanden sind, muss der Namensfilter möglicherweise spezifischer formuliert werden, z. B. unter Einbeziehung von Bestandteilen des Dateinamens anstatt nur der Dateiendung.

    Die Verarbeitungsreihenfolge der Quelldateien kann durch die Reihenfolge der Definition mehrerer Teilfilter beeinflusst werden. Mit einem Filter der Form A*.pdf | B*.pdf | *.pdf werden z. B. zuerst alle PDF-Quelldateien beginnend mit A, dann alle beginnend mit B und zum Schluss alle übrigen PDF-Quelldateien verarbeitet. Dabei sind nur die definierten Positiv-Filter von Bedeutung. Negative Teilfilter mit NOT(…) sind nutzbar, haben aber keinen Einfluss auf die Reihenfolge.

  2. Als zweiter Standardparameter ist optional ein Name oder Namensmuster für die Benennung der erstellten Zieldatei oder Zieldateien definierbar. Als dynamische Bestandteile können in diesem Konfigurationswert Dateivariablen verwendet werden (siehe Dateivariablen unter Variablen).

    Beispiel: Eine Funktion führ eine Formatkonvertierung von PDF nach TIFF durch. Als Parameterwert ist "%FileBaseName%.tiff" angegeben. Durch diesen Parameterwert erhält die Zieldatei den gleichen Basisnamen wie die Quelldatei, nur eine abweichende Endung. Für Funktionen, die in ein vom Quellformat abweichendes Zielformat konvertieren, stellt diese Art der Namensgebung den Standard dar, wenn der Parameter leer gelassen wird. Wenn das Quellformat und das Zielformat und somit die Dateiendung jedoch identisch sind, erhalten die Zieldateien standardmäßig einen zur jeweiligen Funktion passenden Basisnamenszusatz wie .split oder .extracted, um von der Quelldatei unterscheidbar zu sein. Grundsätzlich können mehrere Dateianlagen zwar identische Namen tragen, aber im Sinne einer gezielten Auswahl der Anlagen in nachfolgenden Verarbeitungsschritten sollte auf eine eindeutige Namensgebung geachtet werden.

Globales Makro

Globale Makros sind primär für den Einsatz in einem Task eines Schedule-Workers, d.h. für globale Aktionen, die unabhängig von einem Verarbeitungsszenario ausgeführt werden.

Diese Makrofunktion wird nicht im Kontext eines Dokumentes ausgeführt, sodass weder der Dokumentinhalt verändert noch auf dokumentspezifische Variablen zugegriffen werden kann. Außerdem liefert diese Funktion keinen Ergebniswert zurück, sondern generiert nur einen Log-Eintrag über das Ausführungsergebnis.

In der Regel wird ein globales Makro als alleinstehender Funktionsaufruf konfiguriert und nicht mit anderen Makroelementen verknüpft. Lediglich ein Bezug auf allgemeine System- und Umgebungsvariablen ist möglich, um z. B. eine bedingte Ausführung des Makros zu steuern.

Globale Makros können auch im Rahmen eines Verarbeitungsszenarios genutzt werden, auch wenn dies nicht ihr vorrangiger Einsatzzweck ist. Die genannten Einschränkungen entfallen dann weitgehend und ihre Verwendung entspricht der von Dokumentmakros. Der einzige Unterschied ist, dass die verfügbaren globalen Makrofunktionen nicht darauf ausgelegt sind, Änderungen am Dokumentinhalt vorzunehmen.

In diesem Abschnitt: