@XMLParse

Diese @Function ließt ein XML-Dokument aus einem Text oder Binärpuffer ein und erzeugt daraus eine interne XML-Dokumentstruktur.
Die zurückgegebene XML-Dokumentreferenz kann mit den weiteren @XML…-Funktionen verarbeitet werden. Nach Abschluss der Verarbeitung sollte sie mit @XMLRelease wieder freigegeben werden.
Intern wird die XML-Dokumentstruktur in UTF-8 gespeichert, daher bietet @XMLParse die Option (Siehe Flags) automatische Konvertierungen der Input- bzw. Output-Parameter vorzunehmen.

TEXT/VSPECBINBUFFER XML:
Das XML-Dokument, das eingelesen werden soll.
Das XML-Dokument muss syntaktisch gültiges XML enthalten.

FN Flags (Optional):
Numerischer Wert mit zusätzlichen Optionen für das Einlesen des XML-Dokuments.

BIT   DEC   HEX   BEDEUTUNG wenn gesetzt
01   000001   00001   XML_FLAG_OUTPUT_TRANSLATE_LMBCS   (Konvertiert die Abfrage-Ergebnisse nach LMBCS)
02   000002   00002   XML_FLAG_QUERY_TRANSLATE_UTF8   (Konvertiert die Abfrage-Parameter nach UTF-8)
03   000004   00004   XML_FLAG_INPUT_TRANSLATE_UTF8   (Konvertiert die Eingabedaten vor dem Parsen nach UTF-8)
Die Flags können miteinander kombiniert werden und werden an abgeleitete Handle vererbt.

Return-Wert:
Kann die Eingabe nicht als gültiges XML interpretiert werden, liefert @XMLParse @ERROR, andernfalls einen VSPECHXMLDOC (XMLD) Handle zurück.

Die Fehlermeldung enthält dabei die Position des Fehlers innerhalb der JSON-Daten sowie einen Fehlercode und eine Beschreibung des Parser-Fehlers.
Soweit vom XML-Parser verfügbar, enthält die Fehlermeldung auch Zeilen- und Spaltennummer, beispielsweise:
XML parsing failed at line 12, column 7: …
Ist keine detaillierte Parser-Fehlermeldung verfügbar, wird gemeldet, dass das XML-Dokument nicht wohlgeformt ist.

Hinweise:
Externe Netzwerkressourcen werden beim Parsen nicht geladen. Ebenso ist die Verarbeitung externer XML-Entities deaktiviert.
Die mit @XMLParse erzeugte XML-Dokumentreferenz bleibt gültig, bis sie mit @XMLRelease freigegeben wird.

Beispiel: @XMLParse(INPUT);

XML := "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<customer>" +
" <name>Example GmbH</name>" +
" <city>Berlin</city>" +
"</customer>";

hXMLD := @XMLParse(XML);
hXMLRoot := @XMLGetRoot(hXMLD);
@XMLRelease(hXMLD);

Das Beispiel liest ein XML-Dokument ein, ermittelt dessen Root-Element "<customer>" und gibt die XML-Struktur anschließend wieder frei.

Beispiel: @XMLParse(INPUT;FLAGS);

XML := "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<customer>" +
" <name>Müller GmbH</name>" +
" <city>Berlin</city>" +
"</customer>";

Flags:=7;
hXMLD := @XMLParse(XML;Flags);
hXMLRoot := @XMLGetRoot(hXMLD);
@XMLRelease(hXMLD);

Das Beispiel liest ein XML-Dokument ein, ermittelt dessen Root-Element "<customer>" und gibt die XML-Struktur anschließend wieder frei.
Alle Eingabe-Parameter bzw. Query-Ergebnisse werden jeweils von LMBCS nach UTF-8 bzw. umgekehr konvertiert.
Vor dem Parsen wird also das ‚ü‘ in "Müller" von LMBCS nach UTF-8 konvertiert.