@XMLCreateRoot

Diese @Function erzeugt das Root-Element eines zuvor mit @XMLCreate erzeugten XML-Dokuments.
Optional können zusätzlich ein oder mehrere Namespace-Präfixe und die zugehörigen Namespace-URIs angegeben werden. Das erste angegebene Namespace-Paar wird dem Root-Element als dessen Namespace zugeordnet. Weitere Namespace-Paare werden am Root-Element deklariert.
Es sind genau zwei Aufrufvarianten zulässig: entweder mit zwei Parametern oder mit vier Parametern. Eine Variante mit drei Parametern ist nicht zulässig.
Der Name des Root-Elements sowie Präfixe und Namespace-URIs werden entsprechend den für das XML-Dokument gesetzten Zeichensatz-Flags nach UTF-8 konvertiert.
Die vom XML-Dokument geerbten Flags werden auf das zurückgegebene XML-Node-Handle übernommen.

VSPECHXMLDOC XMLD:
Handle des XML-Dokuments, in dem das Root-Element erzeugt werden soll.
XMLD muss ein gültiges VSPECHXMLDOC (XMLD) Handle enthalten.
Das XML-Dokument darf noch kein Root-Element besitzen.

TEXT Root:
Name des zu erzeugenden Root-Elements.
Der Name darf nicht leer sein und muss ein gültiger XML-NCName sein.

TEXT/TEXTLIST Prefix (Optional):
Namespace-Präfix oder Liste von Namespace-Präfixen.
Ein leerer Präfix ist zulässig und definiert einen Default-Namespace.
Nicht leere Präfixe müssen gültige XML-NCNames sein.

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.
Mindestens ein Namespace muss angegeben werden. Namespace-URIs dürfen nicht leer sein.
Das erste Präfix/Namespace-Paar wird dem Root-Element als dessen Namespace zugeordnet. Weitere Paare werden zusätzlich am Root-Element deklariert.

Return-Wert:
Bei erfolgreicher Ausführung liefert die @Function ein VSPECHXMLNODE (XMLN) Handle auf das neu erzeugte Root-Element zurück.
Besitzt das XML-Dokument bereits ein Root-Element, ist der Root-Name ungültig, stimmen die Anzahl der Präfixe und Namespaces nicht überein, ist ein Präfix oder Namespace ungültig oder tritt ein anderer Fehler beim Erzeugen des Elements auf, liefert die @Function @ERROR.

Beispiel: @XMLCreateRoot(XMLD;Root);

Flags := 7;
hXMLD := @XMLCreate(Flags);
hXMLRoot := @XMLCreateRoot(hXMLD;"customer");
@XMLRelease(hXMLD);

Das Beispiel erzeugt das Root-Element "<customer>" in einem zuvor neu angelegten XML-Dokument.

Beispiel: @XMLCreateRoot(XMLD;Root;Prefix;Namespace);

Flags := 7;
hXMLD := @XMLCreate(Flags);
hXMLRoot := @XMLCreateRoot(
hXMLD;
"customer";
"c";
"https://example.com/customer"
);
@XMLRelease(hXMLD);

Das Beispiel erzeugt ein Root-Element mit dem Namespace-Präfix "c" und der Namespace-URI "https://example.com/customer".
Das erzeugte Element entspricht damit sinngemäß:
<c:customer xmlns:c="https://example.com/customer"/>