Parameter in XPath-Funktionen
Einer benutzerdefinierte XPath-Funktion kann eine beliebige Anzahl von Parametern zugewiesen werden. Die Parameter der Funktion werden im Bereich "Parameter" des Dialogfelds "XPath-Funktionen" (siehe Abbildung unten) definiert. Diese Parameter können dann bei der Definition der benutzerdefinierten XPath-Funktion (im Bereich Funktionsrumpf) verwendet werden.
Funktionsweise einer benutzerdefinierten XPath-Funktion
Nachfolgend wird beschrieben, wie sich eine XPath-Funktion verhält.
1.Die Anzahl der Argumente in einem Funktionsaufruf (z.B. in einer automatischen Berechnung) muss mit der Anzahl der für die benutzerdefinierte Funktion definierten Parameter (die im Bereich Parameter der benutzerdefinierten Funktion definiert sind; siehe Abbildung unten) übereinstimmen. Zusätzlich dazu muss die Anzahl der von jedem Argument (im Funktionsaufruf) übergebenen Objekte mit der Instanzen-Definition des entsprechenden Parameters übereinstimmen. Wenn für einen Parameter (im Bereich Parameter in der Spalte "Typ") eine Datentypeinschränkung definiert wurde, so muss/müssen der/die vom Argument gelieferten Wert(e) mit diesem Datentyp übereinstimmen.
2.Die an die Parameter der Funktion übergebenen Argumente werden anschließend in der (im Bereich Funktionsrumpf; siehe Abbildung unten) definierten XPath-Funktion verwendet. Das durch die Auswertung des XPath-Ausdrucks ermittelte Ergebnis wird anschließend anhand der optionalen Definition Rückgabetyp überprüft (siehe Abbildung unten). Wenn der Datentyp dem erwarteten entspricht, wird das Ergebnis in dem XPath-Ausdruck, über den die Funktion aufgerufen wurde, verwendet.
Reihenfolge von Parametern
Die Reihenfolge der Parameter der benutzerdefinierten Funktion ist wichtig, weil die Argumente beim Funktionsaufruf den Parametern in der Reihenfolge, wie sie im Bereich "Parameter" (siehe Abbildung unten) definiert sind, zugewiesen werden.
Wenn also die benutzerdefinierte XPath-Funktion sps:Stock XPath, so wie in der Abbildung oben gezeigt, definiert ist und wenn Sie mit dem XPath-Ausdruck
sps:Stock(\$XML, Node1, Node2)
aufgerufen wird, dann werden diese drei Argumente – \$XML, Node1, Node2 – den Parametern – \$ContextStock, \$Selection und \$StockInfo – in dieser Reihenfolge zugewiesen.
Beachten Sie, dass jedes Argument im Funktionsaufruf vom nächsten durch ein Komma getrennt wird, sodass jedes Argument an den entsprechenden Parameter übergeben wird (Reihenfolge siehe Bereich Parameter in der Abbildung oben).
Die Reihenfolge der Parameter im Bereich Parameter kann mit den dort verfügbaren Symbolen Anhängen, Einfügen und Löschen geändert werden.
Datentyp von Parametern
Optional kann der Datentyp der Parameter der benutzerdefinierten Funktion definiert werden. Wenn ein Datentyp angegeben ist, wird der Datentyp des Eingabearguments anhand des Datentyps des Parameters überprüft und eine Fehlermeldung ausgegeben, wenn die Typen nicht übereinstimmen. Mit Hilfe dieser Funktion können die Eingabedaten (aus den Argumenten des Funktionsaufrufs) überprüft werden.
Instanzen
Man kann jeden Parameter der benutzerdefinierten XPath-Funktion als Sequenz betrachten. Die Eigenschaft Instanzen eines Parameters gibt an, wie viele Objekte vom entsprechenden Argument des Funktionsaufrufens für diesen Parameter geliefert werden müssen.
Sowohl in Funktionsdefinitionen als auch in Funktionsaufrufen werden die Parameter bzw. Argumente, aber auch die einzelnen Objekte innerhalb einer Sequenz durch Kommas voneinander getrennt. Daher muss unbedingt der Kontext, in dem die Kommas verwendet werden, beachtet werden: ob das Komma zum Trennen von Parametern/Argumenten oder von Sequenzobjekten dient.
•In Parametern/Argumenten werden Sequenzen - in der Funktionsdefinition (Parameter) oder im Funktionsaufruf (Argumente), falls erforderlich, durch Klammern getrennt.
•In Sequenzen werden Klammern ignoriert.
In diesem Zusammenhang sollten die folgenden Beispiele und Punkte beachtet werden:
•Klammern in Parametern/Argumenten: Einige XPath-Funktionen verwenden eine einzige Sequenz als Argument, z.B. die Funktionen avg() und count(). Wenn diese Sequenz mittels Kommatrennzeichen oder Bereichsoperatoren enumeriert wird, muss sie in Klammern eingeschlossen werden, damit eindeutig klar ist, dass es sich um eine einzige Sequenz - und nicht um mehrere, durch Kommas getrennte Sequenzen - handelt. So erhält z.B. in der Funktion avg((count(\$a), \$b, \$c)) die XPath 2.0 avg() Funktion die Einzelsequenz count(\$a),\$b,\$c als Argument. Da die einzelnen Elemente der Sequenz enumeriert sind und eine Sequenz von drei Elementen bilden, muss die Sequenz in Klammern eingeschlossen werden und als einziges Argument an die avg() Funktion: avg((count(\$a),\$b,\$c)) übergeben werden. Ohne das innere Klammerpaar hätte die Definition der avg() Funktion drei Parameter. Dies wäre ein Fehler, da die avg() Funktion ein Argument bestehend aus einer einzigen Sequenz erwartet.
•Keine Klammern in Parametern/Argumenten: Ähnlich wie oben, verwendet auch die count() Funktion eine einzige Sequenz als ihr Ein-Parameter-Argument. Da aber die einzige Sequenz in unserem Beispiel count(\$a) keine kommagetrennte enumerierte Liste ist, sondern stattdessen von der Variablen/dem Parameter \$a, abgerufen wird, muss das Argument nicht in eine innere Klammer eingeschlossen werden. Daher ist der Ausdruck count(\$a) korrekt.
•Klammern und Kommas in Funktionsaufrufen: Im Funktionsaufruf müssen die Klammern korrekt gesetzt werden, damit jedes Argument einem Parameter (wie im Dialogfeld "XPath-Funktionen im Bereich Parameter definiert) entspricht. Wenn, zum Beispiel, die benutzerdefinierte XPath-Funktion mit dem Namen MyAverage() mit dem XPath 2.0-Ausdruck avg((count(\$a),\$b,\$c)) definiert wird, dann wäre der folgende Funktionsaufruf gültig: MyAverage((1,2,3),4,5). Die Werte, die den drei Parametern \$a, \$b, und \$c entsprechen, wären die Sequenz (1,2,3), die Einzelsequenz 4 und die Einzelsequenz 5. Einzelsequenzen können optional in Klammern eingeschlossen werden. Der von MyAverage() in diesem Fall zurückgegebene Wert wäre 4.