fn:error

(Auszug aus "XSLT 2.0 & XPath 2.0" von Frank Bongers, Kapitel 5.)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

   

Kategorie: Fehlermeldungen und Debugging

Herkunft: XPath 2.0

Rückgabewert: Die Funktion nimmt bis zu drei Argumente entgegen und meldet Fehler an die Systemumgebung. Sie gibt jedoch unter keinen Umständen einen Wert an den Ort des Aufrufs zurück.

Aufruf/Argumente:

fn:error($fehlercode?, $beschreibung?, $fehler-objekt*)

$fehlercode:
Optional. Als erstes Argument akzeptiert die Funktion einen QName xs:QName, der den zu meldenden Fehler bezeichnet.

$beschreibung:
Optional. Eine Beschreibung des Fehlers als Klartext vom Typ xs:string. Diese Beschreibung kann an die Anwendungsumgebung übergeben werden.

$fehler-objekt:
Optional. Eine Folge beliebig vieler Items, die zusätzlich zum dann erforderlichen zweiten Argument $beschreibung zur weitergehenden Fehlerdokumentation dienen (beispielsweise können mittels XPath-Ausdrücken die den Fehler verursachenden Werte ausgegeben werden).

Verwendungszweck:

Die Verwendung der Funktion fn:error() kann anhand der Umgebung, innerhalb derer sie verwendet wird (XPath, XQuery, XSLT), variieren. Grundsätzlich jedoch gilt, dass die Funktion bei Aufruf keinen Rückgabewert (auch nicht die leere Sequenz!) an den Ort des Auf­rufs zurückgibt. Sie kann jedoch über den Standard-Output eine Fehlermeldung an die Systemumgebung absetzen.

Die Funktion existiert mit verschiedenen Signaturen, kann daher mit null bis drei Argumenten aufgerufen werden. Die Signaturen mit zwei oder drei Argumenten erfordern jedoch mindestens die Übergabe einer leeren Seuquenz als erstes Argument

Um die Abwesenheit eines Rückgabewertes zu verdeutlichen, wurde für die Beschreibung der Funktionssignatur der formalsemantische Typ none eingeführt. Dieser gilt formal als ein "von jedem Typ abgeleiteter Subtyp", verursacht also in keinem Zusammenhang einen statischen Typfehler – was auch bedeutet, dass die Funktion fn:error() in beliebigem Kontext einsetzbar ist.

Beispiele:

Beispiel 1 –Aufruf von fn:error() ohne Argumente:

fn:error()

Der Aufruf ohne Argument entspricht der Übergabe des QNames, der den Fehlercode err:FOER0000, bezeichnet, also einem (durch den User explizit hervorgerufenen) Fehler »Unidentified error«. Da der Namensraum des Präfixes err dem String "http://www.w3.org/2005/xqt-errors" entspricht, übergibt die Funktion an die Systemumgebung entweder einen (durch Fragment-Identifier ergänzten) URI-String "http://www.w3.org/2005/xqt-errors#FOER0000" oder unmittelbar den QName err:FOER0000, der den Fehler bezeichnet.

Beispiel 2 – Aufruf von fn:error() mit einem Argument:

fn:error(fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000'))

Wird ein einzelnen Argument übergeben, so muss es sich um einen QName handeln. Dies wird in diesem Beispiel durch fn:QName() erzwungen, die den QName aus seinen beiden Stringargumenten erzeugt. Das Beispiel entspricht in der Wirkung dem Aufruf ohne Argumente.

Beispiel 3 – Aufruf von fn:error() mit zwei Argumenten:

fn:error((), 'Das war wohl nichts!')

Es ist formal nicht gestattet, der Funktion einfach eine Zeichenkette (beispielsweise als individuelle Beschreibung eines usergenerierten Fehlers) zu übergeben, ohne gleichzeitig einen QName als erstes Argument mitzuliefern. (Achtung: In früheren Versionen von XPath 2.0 war dies anders. Einzelne Anwendungen mögen ein Stringargument daher noch unterstützen. Grundsätzlich ist dies jedoch nicht korrekt.) Als erstes Argument darf jedoch, wie hier, die leere Sequenz erscheinen. In diesem Fall liefert die Funktion den gleichen Fehlercode, wie beim Aufruf ohne Argument, also err:FOER0000 und zusätzlich die Zeichenkette des zweiten Arguments an die Umgebung.

Beispiel 4 – Aufruf mit drei nicht-leeren Argumenten:

fn:error(xs:QName('fehler:err0815'), "Wert außerhalb des Bereichs:", fn:string($wert))

Hier erhält die Funktion drei Argumente, von denen das erste einen Fehlercode darstellt – beachten Sie, dass das Präfix fehler an einen Namensraum gebunden sein muss, der die Fehlermeldungen der System­umgebung bezeichnet. Argu­ment zwei und drei erläutern den durch das erste Argument bezeichneten Fehler und geben den fraglichen Wert an die Sys­tem­umgebung aus.

Beispiel 5 – Aufruf in einem XPath-Ausdruck:

if ($eingabe=0) then fn:error((), 'Argument ist Null') else (1 div $eingabe)

Die Funktion kann innerhalb eines XPath-Ausdrucks eingesetzt werden, um bei Auftreten eines nicht erwünschten Variablenwertes einen Fehler zu melden. Hier wird die Division durch 0 verhindert, die sonst den Wert INF ergeben würde, was jedoch für sich kein Fehler wäre.

Funktionsdefinition:

XPath 1.0:

Funktion nicht verfügbar

XPath 2.0:

fn:error() as none

fn:error($error as xs:QName) as none

fn:error($error as xs:QName?,
         $description as xs:string) as none

fn:error($error as xs:QName?,
         $description as xs:string,
         $error-object as item()*)  as none

Der Typ none – ein formaler semantischer Typ
Der Typ none ist ein eigener, in der Semantikspezifikation für XQuery und XPath (XQuery 1.0 and XPath 2.0 Formal Semantics) definierter formaler Typ. Dieser steht aber dem Nutzer nicht wirklich zur Verfügung, sondern dient in dieser Definition lediglich dazu, klarzustellen, dass die Funktion keinerlei Rückgabewert hat – auch nicht die leere Sequenz!

   

<< zurück

vor >>