4 Der XML-Cursor (doccursor)

Das doccursor-Objekt ist immer ein Kind eines XML-Dokuments. Es verweist auf einen Knoten des DOM-Baums, der im XML-Dokument (dem Vater) gespeichert ist.

Mittels Methoden kann der Verweis auf einen anderen Knoten des DOM-Baumes gesetzt werden. Verständlicher formuliert bedeutet dies, dass der XML-Cursor mittels Methoden im DOM-Baum bewegt werden kann. Er bleibt natürlich ein Kind des XML-Dokuments.

Definition

{ export | reexport } { model } doccursor { <Bezeichner> }
{
  [ <Attributdefinition> ]
  [ <Methodendefinition> ]
}

Außer den normalen Dialog Manager Attributen, besitzt der XML-Cursor Attribute, um auf Eigenschaften wie Name, Wert oder Attribute des DOM-Knotens zuzugreifen. Da dies Laufzeitattribute sind, sind diese nicht vererbbar. Außerdem sind viele dieser Attribut auch nur lesbar, da die entsprechende Eigenschaft des DOM-Knotens nicht geändert werden kann.

Der XML-Cursor ist zunächst ungültig, wird jedoch beim ersten Zugriff automatisch auf die Wurzel des DOM-Baums positioniert. Achtung, dies geschieht auch, wenn der XML-Cursor durch irgendeine Aktion ungültig geworden ist. Das Attribut .mapped liefert Auskunft darüber, ob der XML-Cursor gültig ist.

Ereignisse

keine

Kinder

Vater

Menü

keins

Methoden

4.1 Attribute

.attribute[integer]

attribute[string]

.data

.dataselect[attribute]

.dataselectattr[attribute]

.dataselectcount[attribute]

.dataselecttype[attribute]

.transformer[integer]

.userdata

value

.xml

4.2 Objektspezifische Attribute

.attribute[integer]
attribute[string]

Das Attribut attribute dient je nach Indizierung zum Abfragen des Namens oder des Wertes eines Attributs des DOM-Knotens.

Ist der Index eine Zahl, dann wird der Name des entsprechenden Attributs des DOM-Knotens geliefert. Es ist zu beachten, dass Attribute eines DOM-Knotens primär unsortiert sind.

Ist der Index ein String, dann stellt der Index den Namen eines Attributs dar und es wird der Wert des Attributs zurückgeliefert. Eine Zuweisung auf das mit einem String indizierte Attribut attribute legt ein entsprechendes Attribut am DOM-Knoten an. Eine Zuweisung eines Leerstrings löscht das entsprechende Attribute des DOM-Knotens.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.data

Dient zum Setzen und Abfragen der Daten des DOM-Knotens. Das Attribut ist nur verfügbar, wenn der nodetype entweder nodetype_cdata_section oder nodetype_processing_instruction ist.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.dataselect[attribute] (ab IDM A.06.01.b)

Mit diesem Datenmodellattribut werden gleichzeitig das als Index angegebene Datamodel-Attribut und ein als Wert zugewiesenes Selektionsmuster für Knoten eines XML-Dokuments definiert.

.dataselectattr[attribute] (ab IDM A.06.01.b)

Dieses Datenmodellattribut definiert, mit welchem Knotenattribut das als Index angegebene Datamodel-Attribut verknüpft ist.

.dataselectcount[attribute] (ab IDM A.06.01.b)

Dieses Datenmodellattribut definiert die Kardinalität des als Index angegebenen Datamodel-Attributs.

.dataselecttype[attribute] (ab IDM A.06.01.b)

Dieses Datenmodellattribut definiert den Datentyp, in den die Werte des als Index angegebenen Datamodel-Attributs konvertiert werden.

.idispatch

Über das idispatch Attribut kann unter Microsoft Windows auf den IDispatch COM Interface Pointer des XML-Cursors zugegriffen werden.

In der Regelsprache darf das Attribut nur demselben Attribut eines anderen Dialog Manager Objekts zugewiesen werden. In den Programmierschnittstellen ist zu beachten, dass das COM Objekt nur so lange gültig ist, wie der Dialog Manager dieses verwendet. Eine Anwendung sollte deshalb den Referenzzähler sofort erhöhen (COM Methode: IUnknown->AddRef). Wenn das Objekt nicht mehr gebraucht wird, muss der Zähler wieder heruntergezählt werden (COM Methode: IUnknown->Release). Es darf aber auf gar keinen Fall der Zähler öfter erniedrigt als erhöht werden, da sonst das COM Objekt freigegeben wird. Der Dialog Manager kann diese Situation nicht erkennen und wird abstürzen.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.ixmldomnode

Über das ixmldomnode Attribut kann unter Microsoft Windows auf den IXMLDOMNode COM Interface Pointer des XML-Cursors zugegriffen werden.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.ixmldomnodelist

Über das ixmldomnodelist Attribut kann unter Microsoft Windows auf den IXMLDOMNodeList COM Interface Pointer des XML-Cursors zugegriffen werden. Über diesen Interface Pointer kann auf die direkten Kinder des XML-Cursors zugegriffen werden.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

mapped

Ist true, wenn der XML-Cursor auf einen Knoten im DOM-Baum zeigt. Es ist zu beachten, dass ein XML-Cursor, der auf keinen Knoten im DOM-Baum verweist, automatisch auf die Wurzel des DOM-Baums positioniert wird, wenn auf eines der objektspezifischen Attribute zugegriffen wird oder eine der objektspezifischen Methoden aufgerufen wird.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.name

Name oder auch Tag des DOM-Knotens.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.nodetype

Dient zur Abfrage des Typs des DOM-Knoten.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.path

Liefert eine String-Repräsentation für die Position des XML-Cursors im DOM-Baum. Mit diesem String kann die select Methode aufgerufen werden, um eine XML-Cursor auf den Knoten im DOM-Baum zu positionieren.

Wird der Wert des path Attributs an anderer Stelle gespeichert (zum Beispiel im userdata Attribut), dann ist zu beachten, dass dieser gespeicherte Wert nicht angepasst wird, wenn die Struktur des DOM-Baums verändert wird. Ein anschließender Aufruf der Methode select mit diesem gespeicherten Wert, wird demzufolge den XML-Cursor auf einen falschen DOM-Knoten zeigen lassen.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.publicid

Öffentliche Kennung des DOM-Knotens. Das Attribut ist nur verfügbar, wenn der nodetype entweder nodetype_entity oder nodetype_notation ist.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.specified

Gibt an, ob ein Attribut eines DOM-Knotens explizit angegeben wurde oder von einem Standardwert ererbt wurde. Das Attribut ist immer true, außer für den nodetype nodetype_attribute.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.systemid

Systemkennung des DOM-Knotens. Das Attribut ist nur verfügbar, wenn der nodetype entweder nodetype_entity oder nodetype_notation ist.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.target

Name der Instruktion eines DOM-Knotens. Der Wert entspricht dem Wert des name Attributes. Das Attribut ist nur verfügbar, wenn der nodetype nodetype_processing_instruction ist.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.text

Werte aller Unterknoten des DOM-Knotens. Es wird ein String geliefert, der den Text aller Unterknoten repräsentiert. Das Attribut ist hauptsächlich hilfreich, wenn man den Text eines XML-Elements benötigt und nicht erst zu dem Kindknoten, der den Text enthält, navigieren möchte.

Es ist zu beachten, dass das Setzen dieses Attributs alle Kindknoten löscht und einen neuen Textknoten anfügt.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

value

Wert des DOM-Knotens. Das Attribut ist nur verfügbar, wenn der nodetype entweder nodetype_attribute, nodetype_text, nodetype_cdata_section, nodetype_processing_instruction oder nodetype_comment ist.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

.xml

String-Darstellung des DOM-Knotens und all seiner Unterknoten.

Dieses Attribut wird nicht vererbt, da es sich auf eine Laufzeiteigenschaft bezieht.

4.3 Objektspezifische Methoden

:add()

Fügt einen Kindknoten als letzten Knoten an den aktuellen DOM-Knoten an. Der XML-Cursor wird auf das neue Element gesetzt.

:delete()

Löscht den DOM-Knoten mit allen Kindknoten. Der XML-Cursor wird auf den Vaterknoten positioniert. XML-Cursor, die in den Unterbaum des gelöschten DOM-Knotens zeigen, werden ungültig. Bei einem ungültigen XML-Cursor besitzt das Attribut .mapped den Wert false.

Werden die Werte des path Attributs an anderer Stelle gespeichert (zum Beispiel im userdata Attribut), dann ist zu beachten, dass diese gespeicherten Werte nicht angepasst werden, wenn die Struktur des DOM-Baums verändert wird. Ein anschließender Aufruf der Methode select mit einem dieser gespeicherten Werte, kann demzufolge den XML-Cursor auf einen falschen DOM-Knoten zeigen lassen.

:match()

Testet, ob der DOM-Knoten dem angegebenen Muster entspricht (siehe Kapitel „Muster für die Methoden :match() und :select()“).

:reparent()

Hängt den DOM-Knoten mit allen Kindknoten um.

:select()

Bewegt den XML-Cursor in der angegebene Richtung oder bewegt den XML-Cursor auf den ersten DOM-Knoten, der dem angegebenen Muster entspricht (siehe Kapitel „Muster für die Methoden :match() und :select()“).

:transform()

Transformiert den XML-Cursor mit dem angegebenen Schema. Wenn das Ziel ein XML-Dokument ist, wird der gespeicherte DOM-Baum gelöscht und ein neuer DOM-Baum aufgebaut. Alle bestehenden XML-Cursor werden ungültig. Bei einem ungültigen XML-Cursor besitzt das Attribut .mapped den Wert false.

Alternativ kann das Ziel der Transformation auch ein Text oder eine Datei sein. Ist das Resultat der Wandlung kein legales XML-Format, dann muss direkt in einen Text oder eine Datei gewandelt werden, da das Resultat nicht einem XML-Dokument zugewiesen werden kann. Dies ist zum Beispiel der Fall, wenn zu HTML gewandelt wird.

4.4 Muster für die Methoden :match() und :select()

Ein Muster ist ähnlich zu einem Dialog Manager Bezeichner. Das Muster bildet einen Pfad von Elementnamen. Der Pfad beginnt bei der Wurzel des DOM-Baums. Jede Hierarchiestufe wird mit dem entsprechenden Teil des Pfades verglichen. Zudem können noch bestimmte Eigenschaften wie Vorhandensein eines Attributs oder die Position innerhalb der Kinder bzw. des Vaters angegeben werden.

Im Muster ist prinzipiell jedes Zeichen mit Ausnahme der Zeichen ., [, ", ], <, >, =, \, Tab, Leerzeichen und Zeilenumbruch zulässig. Soll eines der oben erwähnten Zeichen, .mit Ausnahme des Zeilenumbruchs, verwendet werden, dann muss ein \ vorangestellt werden. Zwischen zwei Anführungszeichen ("), also innerhalb eines Strings, sind zusätzlich auch die Zeichen ., [, ], <, >, =, Tab und Leerzeichen erlaubt. Es ist zu beachten, dass im Dialog Skript das Zeichen \ in einem String schon Escape-Zeichen ist, so dass im Dialog Skript immer \\ anzugeben ist, wo ein \ benötigt wird. Ebenso muss im Dialog Skript \" angegeben werden, wo ein " benötigt wird.

{ <Name> [[.<Attr>{<Op>"<Value>"}]] {[<Idx>]} }
  [ .<Name> [[.<Attr>{<Op>"<Value>"}]] {[<Idx>]} ]

<Name>

Wird mit dem name Attribut des XML-Cursors verglichen. Der XML-Cursor muss den nodetype nodetype_element besitzen. Alternativ kann hier auch * angegeben werden, dann wird das name Attribute nicht beachtet.

Der Name eines XML-Elements beginnt mit einem Buchstaben oder einem Unterstrich und er kann Buchstaben, Ziffern, Bindestriche, Unterstriche und Punkte enthalten. Die genaue Definition für einen XML-Elementnamen kann in der XML-Spezifikation (www.w3c.org/XML) nachgelesen werden.

<Attr>

Der DOM-Knoten, auf den der XML-Cursor zeigt, muss das angegebene Attribut besitzen.

Der Name eines XML-Attributs beginnt mit einem Buchstaben oder einem Unterstrich und er kann Buchstaben, Ziffern, Bindestriche, Unterstriche und Punkte enthalten. Die genaue Definition für einen XML-Attributnamen kann in der XML-Spezifikation (www.w3c.org/XML) nachgelesen werden.

<Op>

Vergleichsoperator, um das in <Attr> angegebene Attribut mit dem <Value> zu vergleichen. Es kann auf gleich = und ungleich <> verglichen werden.

<Value>

Der Wert gegen den das <Attr> verglichen wird.

<Idx>

Der DOM-Knoten muss an dieser Position innerhalb der Kindknoten seines Vaterknotens stehen. Das erste Kind besitzt die Position 1.

Der <Idx> besteht nur aus Ziffern (0 – 9), die als Zahl interpretiert werden.

Besonderheiten

Beginnt das Muster mit einem Punkt, dann ist es relativ zum aktuellen DOM-Knoten. Der Pfad beginnt also beim aktuellen DOM-Knoten.

Zwei aufeinander folgende Punkte überspringen beliebig viele Hierarchiestufen.

[<Idx>]

Ein Index ohne weitere Angaben selektiert den DOM-Knoten an dieser Position. Der nodetype des Knotens bleibt dabei unberücksichtigt. Jeder DOM-Knoten kann somit durch einen Ausdruck der Form {[<Idx>][.[<Idx>]]} eindeutig referenziert werden (path Attribut).

Erweiterung unter Microsoft Windows

Es kann auch XPath als Mustersyntax verwendet werden. Hierzu muss das Muster entweder mit / oder ./ beginnen. Die Verwendung von XPath Mustern ist wird nicht auf jeder Plattform unterstützt und ist somit nicht portabel.