@XMLSelectNodes

Diese @Function führt einen XPath-Ausdruck relativ zu einem XML-Knoten aus und liefert alle gefundenen XML-Knoten als VSPECHXMLNODELIST (XMLNL) Handle 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-NodeList-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:
Werden passende Knoten gefunden, liefert die @Function ein VSPECHXMLNODELIST (XMLNL) Handle zurück, das alle gefundenen Knoten enthält.
Die gefundenen Knoten werden vor der Rückgabe in Dokumentreihenfolge sortiert.
Die Anzahl der enthaltenen Knoten kann mit @XMLNodeListGetElements ermittelt werden. Einzelne Knoten können mit @XMLNodeListGetNode ausgelesen werden.
Das zurückgegebene NodeList-Handle sollte nach Abschluss der Verarbeitung mit @XMLNodeListRelease wieder freigegeben werden.
Wird kein passendes Objekt gefunden, liefert die XPath-Auswertung kein Node-Set, ist das übergebene XML-Node-Handle ungültig oder tritt ein anderer Fehler auf, liefert die @Function @ERROR.

Beispiel: @XMLSelectNodes(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);
hXMLNL := @XMLSelectNodes(hXMLRoot;"customer");
Elements := @XMLNodeListGetElements(hXMLNL);
@XMLNodeListRelease(hXMLNL);
@XMLRelease(hXMLD);

Das Beispiel ermittelt alle direkt untergeordneten "<customer>"-Elemente. Elements enthält anschließend den Wert 2.

Beispiel: @XMLSelectNodes(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);
hXMLNL := @XMLSelectNodes(
hXMLRoot;
"c:customer";
"c";
"https://example.com/customer"
);
Elements := @XMLNodeListGetElements(hXMLNL);
@XMLNodeListRelease(hXMLNL);
@XMLRelease(hXMLD);

Das Beispiel registriert das Präfix "c" für die Namespace-URI "https://example.com/customer" und ermittelt anschließend alle passenden "<c:customer>"-Elemente.