@XMLSelectSingleNode

Diese @Function führt einen XPath-Ausdruck relativ zu einem XML-Knoten aus und liefert das erste gefundene XML-Element zurück.
Optional können zusätzlich Namespace-Präfixe und die zugehörigen Namespace-URIs angegeben werden. Diese werden vor der Auswertung im XPath-Kontext registriert.
Es sind genau zwei Aufrufvarianten zulässig: entweder mit zwei Parametern oder mit vier Parametern. Eine Variante mit drei Parametern ist nicht zulässig.
Die XPath-, Präfix- und Namespace-Parameter werden entsprechend den für das XML-Handle gesetzten Zeichensatz-Flags nach UTF-8 konvertiert.
Die vom übergebenen XML-Node-Handle geerbten Flags werden auf das zurückgegebene XML-Node-Handle übernommen.

VSPECHXMLNODE XMLN:
Handle des XML-Knotens, der als Ausgangspunkt für die XPath-Auswertung verwendet werden soll.
XMLN muss ein gültiges VSPECHXMLNODE (XMLN) Handle enthalten, das auf einen XML-Knoten verweist.

TEXT XPath:
XPath-Ausdruck, der relativ zum übergebenen XML-Knoten ausgewertet wird.
Das Ergebnis muss ein Node-Set enthalten. Aus diesem wird das erste XML-Element zurückgegeben.

TEXT/TEXTLIST Prefix (Optional):
Namespace-Präfix oder Liste von Namespace-Präfixen, die innerhalb des XPath-Ausdrucks verwendet werden.

TEXT/TEXTLIST Namespace (Optional):
Namespace-URI oder Liste von Namespace-URIs, die den angegebenen Präfixen zugeordnet werden.
Prefix und Namespace müssen dieselbe Anzahl von Elementen enthalten.
Die angegebenen Präfixe und Namespace-URIs werden paarweise im XPath-Kontext registriert.

Return-Wert:
Wird mindestens ein passendes XML-Element gefunden, liefert die @Function ein VSPECHXMLNODE (XMLN) Handle auf das erste gefundene Element zurück.
Werden mehrere Knoten gefunden, wird das Node-Set zunächst sortiert und anschließend der erste Eintrag verwendet.
Wird kein passendes Objekt gefunden, liefert die XPath-Auswertung kein Node-Set, ist das erste gefundene Objekt kein XML-Element oder tritt ein anderer Fehler auf, liefert die @Function @ERROR.

Beispiel: @XMLSelectSingleNode(XMLN;XPath);

XML := "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<customers>" +
" <customer id=\"1\"><name>Example GmbH</name></customer>" +
" <customer id=\"2\"><name>Sample GmbH</name></customer>" +
"</customers>";
hXMLD := @XMLParse(XML);
hXMLRoot := @XMLGetRoot(hXMLD);
hCustomer := @XMLSelectSingleNode(hXMLRoot;"customer[@id=’2′]");
@XMLRelease(hXMLD);

Das Beispiel sucht relativ zum Root-Element nach dem ersten "<customer>"-Element mit dem Attribut id="2".

Beispiel: @XMLSelectSingleNode(XMLN;XPath;Prefix;Namespace);

XML := "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<customers xmlns:c=\"https://example.com/customer\">" +
" <c:customer id=\"1\"><c:name>Example GmbH</c:name></c:customer>" +
" <c:customer id=\"2\"><c:name>Sample GmbH</c:name></c:customer>" +
"</customers>";
hXMLD := @XMLParse(XML);
hXMLRoot := @XMLGetRoot(hXMLD);
hCustomer := @XMLSelectSingleNode(
hXMLRoot;
"c:customer[@id=’2′]";
"c";
"https://example.com/customer"
);
@XMLRelease(hXMLD);

Das Beispiel registriert das Präfix "c" für die Namespace-URI "https://example.com/customer" und sucht anschließend nach dem ersten passenden "<c:customer>"-Element.