Parameter in benutzerdefinierten Funktionen

www.altova.com Dieses Kapitel drucken Vorherige Seite Eine Ebene nach oben Nächste Seite

Startseite >  Funktionen > Benutzerdefinierte Funktionen >

Parameter in benutzerdefinierten Funktionen

Wenn Sie eine benutzerdefinierte Funktion erstellen, müssen Sie angeben, welche Input-Parameter (falls überhaupt) diese erhalten soll und welchen Output die Funktion erzeugen soll. Während Input-Parameter manchmal nicht benötigt werden, ist ein Output-Parameter in jedem Fall erforderlich (d.h. eine Funktion muss immer ein Ergebnis haben). Die Funktion unten hat z.B. keine Input-Komponenten und einen Output, der den Text "hello" an die aufrufende Komponente zurückgibt:

mf_udf_04

Funktionsparameter können einen simpleType (wie z.B. String oder Ganzzahl) oder eine komplexe Struktur haben. So hat etwa die unten gezeigte benutzerdefinierte Funktion "FindArticle" zwei Input- und einen Output-Parameter.

 

POArtNr ist ein Input-Parameter vom simpleType "string"
Amount  ist ein Input-Parameter vom simpleType "integer"
CompletePO  ist ein Output-Parameter vom XML-Typ complexType.

mf_udf_09

LookupArticle.mfd

Dieses Mapping steht als Demo unter dem folgenden Pfad zur Verfügung: <Dokumente>\Altova\MapForce2019\MapForceExamples\LookupArticle.mfd.

 

Hinzufügen von Parametern

 

So fügen Sie einen Input- oder Output-Parameter hinzu:

1.Erstellen Sie ein benutzerdefiniertes Funktionsmapping (siehe Erstellen benutzerdefinierter Funktionen) oder öffnen Sie ein vorhandenes (siehe Bearbeiten von benutzerdefinierten Funktionen).
2.Wählen Sie eine der folgenden Methoden:

 

Wählen Sie den Menübefehl Funktion | Input-Komponente einfügen bzw. Funktion | Output-Komponente einfügen.
Klicken Sie auf die Symbolleisten-Schaltflächen Input-Komponente einfügen ( mf_ic_udf_input ) oder Output-Komponente einfügen ( mf_ic_udf_output ).

mf_udf_08

3.Wählen Sie im obigen Dialogfeld aus, ob es sich beim Input- bzw. Output-Parameter um einen simpleType (wie String oder Ganzzahl) oder eine komplexe Struktur (wie eine XML-Struktur) handeln soll. Um einen Parameter zu erstellen, der ein komplexer XML-Typ ist, klicken Sie neben "Struktur" auf Auswählen und navigieren Sie zum XML-Schema, das die erforderliche Struktur beschreibt.

 

Wenn das Funktionsmapping bereits XML-Schemas enthält, stehen Sie als Strukturen zur Auswahl. Andernfalls können Sie ein komplett neues Schema für die Struktur des Parameters auswählen.

 

Sie können bei XML-Strukturen ein Root-Element für Ihre Struktur auswählen, wenn es das XML-Schema erlaubt. Um ein Root-Element zu definieren, klicken Sie neben "Root" auf Auswählen und wählen Sie die Root im daraufhin angezeigten Dialogfeld aus.

 

Falls das Kontrollkästchen Strukturdateipfad relativ zur MFD-Datei speichern aktiviert ist, wird der absolute Pfad der Strukturdatei beim Speichern des Mappings in einen Pfad umgewandelt, der relativ zum aktuellen Mapping ist. Nähere Informationen dazu finden Sie unter Verwenden relativer Pfade in einer Komponente.

 

Eine Erläuterung zu den Kontrollkästchen Input ist erforderlich und Input ist eine Sequenz finden Sie in den folgenden Abschnitten.

 

Obligatorische Parameter

Um einen Parameter in einer benutzerdefinierten Funktion zu einem obligatorischen Parameter zu machen, aktivieren Sie das Kontrollkästchen Input ist erforderlich. Wenn ein Parameter obligatorisch ist, kommt es zu einem Validierungsfehler, wenn Sie keinen Input damit verbinden.

 

Um einen Parameter optional zu machen, deaktivieren Sie das Kontrollkästchen Input ist erforderlich. Optionale Parameter werden im Hauptmapping etwas anders angezeigt - Ihr Input-Konnektor (das kleine Dreieck) hat eine gestrichelte Umrandung.

 

Außerdem können Sie einen Standardparameterwert definieren, indem Sie ihn mit dem Input "default" eines Parameters verbinden, z.B.:

mf_udf_18

Der Standardwert wird nur wirksam, wenn kein anderer Wert vorhanden ist. Wenn der optionale Parameter bei Aufruf der Funktion einen Wert erhält, so hat dieser Wert Vorrang vor dem Standardwert.

 

Sequenzparameter

Sie können optional festlegen, dass ein Funktionsparameter als Einzelwert (Standardverhalten) oder als Sequenz behandelt wird. Damit der Parameter nicht als Einzelwert, sondern als Sequenz behandelt wird, aktivieren Sie das Kontrollkästchen Input ist eine Sequenz. Beachten Sie, dass dieses Kontrollkästchen nur dann sinnvoll und verwendbar ist, wenn es sich bei der benutzerdefinierten Funktion um eine "reguläre" benutzerdefinierte Funktion handelt, siehe Inline-Funktionen und reguläre benutzerdefinierte Funktionen. Andernfalls ist das Kontrollkästchen ausgegraut.

 

Bei einer Sequenz handelt es sich um einen Bereich bestehend aus null oder mehr Werten. Ein Parameter könnte dann als Sequenz definiert werden, wenn in Ihrer benutzerdefinierten Funktion Input-Daten in Form einer Sequenz erwartet werden, um in dieser Sequenz Werte zu aggregieren (z.B. durch Aufruf von Funktionen wie avg, min, max). Ein Beispiel dazu finden Sie im folgenden Demo-Mapping: <Dokumente>\Altova\MapForce2019\MapForceExamples\InputIsSequence.mfd. In diesem Mapping ist der Filter "data" mit der benutzerdefinierten Funktion "Calculate" verbunden. Das Ergebnis des Filters ist eine Sequenz von Datenelementen, sodass der Input-Parameter der Funktion als Sequenz definiert wurde.

mf_udf_11

InputIsSequence.mfd

Intern aggregiert die Funktion "Calculate" alle Sequenzwerte (Sie führt, wie unten gezeigt, die Funktionen min, max und avg an der Input-Sequenz aus).

mf_udf_12

Im Allgemeinen gilt, dass es von den Input-Daten, bei denen es sich entweder um eine Sequenz oder nicht um eine Sequenz handelt, abhängt, wie oft die Funktion aufgerufen wird.

 

Wenn Input-Daten mit einem Sequenzparameter verbunden sind, wird die benutzerdefinierte Funktion nur einmal aufgerufen und die vollständige Sequenz wird an die benutzerdefinierte Funktion übergeben.
Wenn Input-Daten mit einem Nicht-Sequenzparameter verbunden sind, wird die benutzerdefinierte Funktion für jedes Datenelement in der Sequenz einmal aufgerufen.

 

Wenn Sie eine leere Sequenz mit einem Nicht-Sequenz-Parameter verbinden, wird die Funktion gar nicht aufgerufen.

 

Dies kann vorkommen, wenn die Quellstruktur optionale Datenelemente hat oder wenn eine Filterbedingung keine übereinstimmenden Datenelemente zurückgibt. Um dies zu vermeiden, verwenden Sie vor dem Funktions-Input entweder die Funktion substitute-missing, um sicherzustellen, dass die Sequenz nie leer ist oder setzen Sie den Parameter auf Sequenz und fügen Sie innerhalb der Funktion eine Behandlung für die leere Sequenz hinzu.

 

Das Kontrollkästchen Output ist eine Sequenz kann auch für Output-Parameter erforderlich sein. Wenn eine Funktion eine Sequenz aus mehreren Werten an ihre Output-Komponente übergibt und die Output-Komponente nicht auf Sequenz gesetzt ist, gibt die Funktion nur das erste Datenelement in der Sequenz zurück.

 

Parameterreihenfolge

Wenn eine benutzerdefinierte Funktion mehrere Input- oder Output-Parameter hat, können Sie die Reihenfolge, in der die Parameter für aufrufenden Komponenten dieser Funktion präsentiert werden, ändern. Die unten gezeigte Funktion hat z.B. drei Input-Parameter input1, input2 und input3.

mf_udf_13

Die Reihenfolge der Parameter im Funktionsmapping (von oben nach unten) bestimmt die Reihenfolge, in der diese für aufrufende Komponenten dieser Funktion angezeigt werden:

mf_udf_14

Beachten Sie die folgenden Punkte:

 

Input- und Output-Parameter werden nach ihrer Position von oben nach unten gereiht. Wenn Sie also den Parameter input3 im Funktionsmapping an die oberste Stelle verschieben, wird dieser zum ersten Parameter dieser Funktion.
Wenn zwei Parameter dieselbe vertikale Position haben, hat der linke Vorrang.
In den seltenen Fällen, in denen zwei Parameter genau die gleiche Position haben, wird automatisch die interne Komponenten-ID verwendet.

© 2019 Altova GmbH