Eine Verarbeitungsprozedur verhält sich beim Ablauf so, als würde sie von der XML-Anweisung über PERFORM aktiviert, ähnlich zu einer INPUT/OUTPUT PROCEDURE bei SORT, siehe auch Abschnitt „SORT-Anweisung". Es gelten daher für die Angabe in der XML-Anweisung die gleichen Regeln und Einschränkungen wie für eine PERFORM-Anweisung.
Ereignisse
Innerhalb der Verarbeitungsprozedur kann die Anwendung für Ereignisse, die von Interesse sind, weitere Verarbeitungen vornehmen. Fast alle Ereignisse stellen zu diesem Zweck spezifischen Daten im Sonderregister XML-TEXT bzw. XML-NTEXT bereit. Spalte nsp in der folgenden Tabelle kennzeichnet Ereignisse, bei denen auch die Namensraum-Sonder-register versorgt sind. Dabei handelt es sich um XML-NAMESPACE und XML-NAME-SPACE-PREFIX bzw. XML-NNAMESPACE und XML-NNAMESPACE-PREFIX. Wenn kein Namensraum oder der leere Namensraum angegeben ist, ist die aktuelle Länge der Sonderregister gleich 0; bei einem Standardnamensraum ist die aktuelle Länge der Präfix-Sonderregister gleich 0.
Die Hochkommas bei den diversen Zeichenfolgen in der folgenden Tabelle dienen nur der Hervorhebung. Sie sind nicht Bestandteil der Zeichenfolge.
Name des Ereignisses (in XML-EVENT) | Inhalt von XML-TEXT bzw. XML-NTEXT | nsp |
ATTRIBUTE-CHARACTERS | Wert des Attributs ohne die öffnenden und schließenden Literalbegrenzer | |
ATTRIBUTE-NAME | Lokaler Name des Attributs | X |
COMMENT | Inhalt des Kommentars, ohne die Zeichenfolgen '<!--' am Anfang und '->' am Ende | |
CONTENT-CHARACTER | Ein einzelnes Zeichen, das einer vordefinierten Entitätenreferenz entspricht | |
CONTENT-CHARACTERS | Teil-Zeichenfolge zwischen Beginn- und Ende-Tag eines Elements.Dies ist nur dann der ganze Wert, wenn er keine weiteren Elemente oder Entitätsreferenzen enthält. | |
CONTENT-NATIONAL-CHARACTER | Nur in XML-NTEXT für Dokumente, die in einem alphanumerischen Datenfeld bereitgestellt sind: Ein einzelnes nationales Zeichen, das einer numerischen Entität entspricht, die nicht als alphanumerisches Zeichen darstellbar ist. XML-TEXT hat bei diesem Ereignis immer die aktuelle Länge 0. | |
DEFAULTED-ATTRIBUTE-NAME | Lokaler Name eines Attributs, das im XML-Dokument nicht enthalten ist, aber in der verwendeten DTD (Document Type Definition) mit einem Vorgabewert erklärt ist. | X |
DOCUMENT-TYPE-DECLARATION | Die gesamte Dokumenttypdefinition, ein schließlich der Zeichenfolge '<!DOCTYPE' am Anfang und '>' am Ende. | |
ENCODING-DECLARATION | Zeichensatzname (wie von XHCS erwartet), der für die Interpretation des Dokuments angenommen wird. | |
END-OF-CDATA-SECTION | Die Zeichenfolge ']]>' | |
END-OF-DOCUMENT | Leer, d.h. aktuelle Länge = 0 | |
END-OF-ELEMENT | Lokaler Name des Elements | X |
EXCEPTION | Beginn des Dokuments bis einschließlich der Fehlerstelle | |
NAMESPACE-DECLARATION | Leer, d.h. aktuelle Länge = 0 | X |
PROCESSING-INSTRUCTION-DATA | Inhalt der Steueranweisung nach dem Namen, ohne die Zeichenfolge '?>' am Ende. Führende Durchschüsse (white spaces) sind nicht Bestandteil, endständige jedoch schon. | |
PROCESSING-INSTRUCTION-TARGET | Name der Steueranweisung (ohne die Zeichenfolge '<?' am Anfang) | |
STANDALONE-DECLARATION | Die Zeichenfolge 'yes' oder 'no' aus der XML-Deklaration | |
START-OF-CDATA-SECTION | Die Zeichenfolge '<![CDATA[' | |
START-OF-DOCUMENT | Das gesamte Dokument | |
START-OF-ELEMENT | Lokaler Name des Elements | X |
VERSION-INFORMATION | Wert aus der Versionsangabe der XML-Deklaration ohne die öffnenden und schließenden Literalbegrenzer |
Fehlerbehandlung
Der Parser teilt der Verarbeitungsprozedur gefundene Fehler durch das Ereignis 'EXCEPTION' mit. Das Sonderregister XML-CODE hat dann einen Wert ungleich 0, der den Fehler genauer beschreibt. Bei allen anderen Ereignissen hat dieses Sonderregister den Wert 0.
Der Inhalt des Sonderregisters XML-CODE beim Verlassen der Verarbeitungsprozedur steuert die Fortsetzung der XML-Anweisung. Die Verarbeitungsprozedur signalisiert durch Setzen entsprechender Werte die gewünschte Fortsetzung:
-1 | Beenden der XML-Anweisung mit 'Fehler'. Dies ist bei jedem Ereignis möglich, auch wenn zuvor das Ereignis EXCEPTION nicht aufgetreten ist. |
0 | Fortsetzung der XML-Anweisung. Wenn bereits ein Fehler gemeldet wurde, ist die Fortsetzung nur bei 'leichten' Fehlern möglich. Sie beschränkt sich aber auf die Suche nach weiteren Fehlern. Bei 'schweren' Fehlern wird die XML-Anweisung trotzdem immer abgebrochen. |
andere | Das weitere Verhalten ist undefiniert. |
Vorhandene EXCEPTION- bzw. NOT EXCEPTION-Klauseln werden nach Ende der XML-Anweisung ausgeführt, abhängig davon, wie die Anweisung beendet wurde:
NOT EXCEPTION | Bei regulärer Beendigung |
EXCEPTION | Bei irregulärer Beendigung wegen Fehlern. Das schließt den aktiven Abbruch durch Setzen des XML-CODE-Sonderregisters in der Verarbeitungsprozedur mit ein. |
Beispiel 12-57 Ereignisse und Inhalt der Sonderregister
DATA DIVISION. WORKING-STORAGE SECTION. ... 01 dokument. 02 VALUE "<?xml version='1.1'?>". 02 VALUE "<dok xmlns:r='http://www.efg'>". 02 VALUE "111". 02 VALUE "<a att='XX'/>". 02 VALUE "<![CDATA[tse-da-da segdschn]]">"". 02 VALUE "222". 02 VALUE "<r:b>". 02 VALUE "yyyyy ". 02 VALUE "</r:b>". 02 VALUE "</dok>".
Die Zerlegung des Dokuments durch die XML-Anweisung führt zu nachstehender Folge von Ereignissen und Inhalten der Sonderregister:
XML-EVENT | XML-TEXT | XML-NAME-SPACE | XML- |
VERSION-INFORMATION | 1.1 | ||
START-OF-DOCUMENT | <?xml version='1.1'?> <dok xmlns:r='http://www.efg'>111<a att='XX'/><![CDATA [tse-da-da segdschn]]> 222<r:b>yyyyy'BLANK''BLANK''BLANK'</r:b></dok> | ||
START-OF-ELEMENT | dok | ||
NAMESPACE-DECLARATION | http://www.efg | r | |
CONTENT-CHARACTERS | 111 | ||
START-OF-ELEMENT | a | ||
ATTRIBUTE-NAME | att | ||
ATTRIBUTE-CHARACTERS | XX | ||
END-OF-ELEMENT | a | ||
START-OF-CDATA-SECTION | <![CDATA[ | ||
CONTENT-CHARACTERS | tse-da-da̺segdschn | ||
END-OF-CDATA-SECTION | ]]> | ||
CONTENT-CHARACTERS | 222 | ||
START-OF-ELEMENT | b | http://www.efg | r |
CONTENT-CHARACTERS | yyyyy'BLANK''BLANK''BLANK' | ||
END-OF-ELEMENT | b | http://www.efg | r |
END-OF-ELEMENT | dok | ||
END-OF-DOCUMENT |
Anmerkungen:
Der Wert (111222) des Elements 'dok' ist durch das eingeschobene Element 'a' in zwei Teile aufgespalten. Aufgrund der sequenziellen Verarbeitung des XML-Dokuments liefert der Parser die Teilstücke getrennt – unterbrochen durch die Ereignisse zu Element 'a' – jeweils mit dem Ereignis CONTENT-CHARACTERS.
Ein leerer Eintrag zeigt an, dass das Sonderregister bei dem Ereignis die aktuelle Länge 0 hat.
Beispiel 12-58 XML-Anweisung und Verarbeitungsprozedur
PROCEDURE DIVISION.
...
XML PARSE dokument
PROCESSING PROCEDURE IS ereignis
ON EXCEPTION ...
NOT ON EXCEPTION ...
END-XML.
...
ereignis.
EVALUATE XML-EVENT
WHEN "VERSION-INFORMATION"
IF XML-TEXT NOT = "1.0"
DISPLAY "XML Version nicht 1.0"
MOVE -1 TO XML-CODE
END-IF
WHEN "CONTENT-CHARACTERS"
...
WHEN "START-OF-ELEMENT"
IF FUNCTION LENGTH(XML-TEXT) > 31
DISPLAY "Elementname zu lang"
MOVE -1 to XML-CODE
ELSE
MOVE XML-TEXT TO ...
END-IF
WHEN "END-OF-ELEMENT"
...
WHEN OTHER
CONTINUE
END-EVALUATE.
Anmerkungen:
Das Programm möchte nur XML-Dokumente der Version 1.0 verarbeiten und für alle anderen Versionen die Verarbeitung beenden: Wenn das Sonderregister XML-CODE mit dem Wert -1 in der Verarbeitungsprozedur versorgt wird, signalisiert dies den Wunsch nach sofortigem Abbruch der XML-Anweisung.
-1 im Sonderregister XML-CODE bei Rückkehr zur XML-Anweisung bedeutet irreguläres Ende und Fortsetzung mit den Anweisungen bei der ON EXCEPTION-Angabe.
Das Programm verarbeitet nur Elemente und deren Werte. Andere Ereignisse 'verschluckt' die Verarbeitungsprozedur, ohne dafür etwas zu tun (WHEN OTHER).
Das Programm möchte nur Elementnamen mit maximal 31 Zeichen akzeptieren. Wenn im Dokument längere Elementnamen vorkommen, wird die XML-Anweisung sofort beendet. Die Länge eines im Sonderregister XML-TEXT bereitgestellten Elementnamen entspricht der aktuellen Länge des Sonderregisters: sie wird von FUNCTION LENGTH geliefert.
Auch wenn für einzelne Sonderregister keine Definition mit herkömmlichen COBOL-Sprachmitteln möglich ist, dürfen sie in COBOL-Anweisungen verwendet werden. Sie verhalten sich wie alphanumerische bzw. nationale Gruppen variabler Länge, z.B. als Sendefeld in der MOVE-Anweisung.