Usage:
OBJECT x = CREATE "dynamic", "dyndom"
If an application wishes to use the Xerces DOM object then it should load it once and keep it loaded. Loading it each time it is used is very inefficient.
The writeToString method as implemented in KCML 6.20 has a memory leak. See the notes on the method on how to avoid it.
For further information see http://xml.apache.org/xerces-c/index.html
Xerces XML root object
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).| Method | Returns | Purpose | |
|---|---|---|---|
| createParser() | Parser | Creates DOM parser object | KCML |
| createSAXParser() | SAXParser | Creates a SAX2 parser object | KCML |
| getDOMImplementation(name$) | Implementation | Return an Implementation ref from DOM Implementation Registry | KCML |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Implementation | R | Implementation | Return an Implementation ref | KCML |
SAX2 Parser object
| Method | Returns | Purpose | |
|---|---|---|---|
| ContentHandler() | ContentHandler | Constructor for a SAX2 ContentHandler object | KCML |
| createScanToken() | ScanToken | Allocate a ScanToken for use in a progressive parse | KCML |
| getFeature(name$) | bool | Query the state of a SAX2 feature | |
| getProperty$(name$) | string | Query the state of a SAX2 property | |
| parse(URI$) | void | Parse a URI | |
| parseFirst(URI$, OBJECT token) | bool | Start a progressive parse of a URI | |
| parseFirstIS(OBJECT stream, OBJECT token) | bool | Start a progressive parse of an InputStream | |
| parseIS(OBJECT stream) | void | Parse from an InputStream | |
| parseNext(OBJECT token) | bool | Continue a progressive parse | |
| parseReset(OBJECT token) | void | Reset the parser after a progressive parse | |
| setContentHandler(OBJECT handler) | void | Specify the SAX2 ContentHandler | |
| setFeature(name$, value) | void | Specify the state of a SAX2 feature | |
| setProperty(name$, value$) | void | Specify the state of a SAX2 property |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| ErrorCount | R | int | Get error count from last parse | |
| ExitOnFirstFatalError | RW | bool | Get/set Exit On First Fatal Error flag | |
| ValidationConstraintFatal | RW | bool | Get/set Validation Constraint Fatal flag |
Object that receives callbacks from SAX2 events
| Method | Returns | Purpose | |
|---|---|---|---|
| SetCharacters(fn) | void | Set KCML handler subroutine for characters | |
| SetEndDocument(fn) | void | Set KCML handler subroutine for end of document | |
| SetEndElement(fn) | void | Set KCML handler subroutine for end of element | |
| SetIgnorableWhitespace(fn) | void | Set KCML handler subroutine for DTD defined ignorable whitespace | |
| SetResetDocument(fn) | void | Set KCML handler subroutine for restart of document | |
| SetStartDocument(fn) | void | Set KCML handler subroutine for start of document | |
| SetStartElement(fn) | void | Set KCML handler subroutine for start of element |
| Callback | Returns | Purpose | |
|---|---|---|---|
| characters(text$, length) | void | Receive notification of text. Note that the length is the number of UTF-16 characters in the string. To get the length in bytes use LEN(STR(text$)). This handler may be called more than once for a text string which contains entities. | |
| endDocument() | void | Receive notification of end of document | |
| endElement(uri$, localname$, qname$) | void | Receive notification of end of every element | |
| ignorableWhitespace(text$, length) | void | Receive notification of DTD defined ignorable whitespace | |
| resetDocument() | void | Receive notification of restart of document | |
| startDocument() | void | Receive notification of start of document | |
| startElement(uri$, localname$, qname$, attributes) | void | Receive notification of start of every element, uri$ is the combination of the NS and the tag as a URI, localname$ is the bare tag name, qname$ is the tag with its prefix,attributes is an object containing any attributes for the tag |
Scan state token for progressive parsing
A list of attributes for an element as returned by SAX2
| Method | Returns | Purpose | |
|---|---|---|---|
| Index(qname$) | integer | Returns the index of an attribute in the list by qualified name | |
| Index(uri$, localpart$) | integer | Returns the index of an attribute in the list by namespace name | |
| LocalName$(index) | string | Returns the local name of an attribute in the list by index (0 based) | |
| QName$(index) | string | Returns the qualified name of an attribute in the list by index (0 based) | |
| Type$(qname$) | string | Returns the type of an attribute in the list by qualified name. The attribute type is one of the strings 'CDATA', 'ID', 'IDREF', 'IDREFS', 'NMTOKEN', 'NMTOKENS', 'ENTITY', 'ENTITIES', or 'NOTATION' (always in upper case). | |
| URI$(index) | string | Returns the namespace URI of an attribute in the list by index (0 based) | |
| Value$(index) | string | Returns the value of an attribute in the list by position |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Length | R | unsigned int | Returns the number of elements in the list |
Parser object
| Method | Returns | Purpose | |
|---|---|---|---|
| MemBufInputSource(buf, buflen, id) | MemBufInputSource | Constructor for a memory buffer input stream | |
| adoptDocument() | Document | Adopt DOM document, caller now responsible for releasing memory | |
| applyTranslations() | int | Apply translations to currently loaded DOM | KCML |
| parse(URI$) | void | Parse a URI | |
| parseIS(OBJECT stream) | void | Parse from an inputstream | KCML |
| reset() | void | Reset parser state ready for another parse | |
| resetDocumentPool() | void | Free parser memory |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| CreateEntityReferenceNodes | RW | bool | Get/set flag controlling expansion of entities | |
| DoNamespaces | RW | bool | Get/set process namespaces flag | |
| DoSchema | RW | bool | Get/set Process schemas flag | |
| Document | R | Document | Return document object | |
| ErrorCount | R | int | Get error count from last parse | |
| ExitOnFirstFatalError | RW | bool | Get/set Exit On First Fatal Error flag | |
| ExternalNoNamespaceSchemaLocation$ | RW | string | Get/set location of an external schema or DTD | |
| ExternalSchemaLocation$ | RW | string | Get/set location of an external schema or DTD. There can be a list of more than one. It matches the target namespace of the instance document. | |
| IncludeIgnorableWhitespace | RW | bool | Get/set flag controlling how whitespace is treated (requires DTD) | |
| LoadExternalDTD | RW | bool | Get/set flag to control loading of an external DTD. If the DTD is referenced only for consistency checking and is not needed during the parse, say to supply entities, then set this flag to FALSE. | |
| ValidationConstraintFatal | RW | bool | Get/set Validation Constraint Fatal flag | |
| ValidationScheme | RW | ValScheme | Get/set validation scheme |
DOM Document object
Multiply inherits from among the following interfaces:
| Method | Returns | Purpose | |
|---|---|---|---|
| adoptNode(OBJECT source) | Node | Adopt a node from another document by changing the ownerDocument of the node and its children | |
| createAttribute(name$) | Attr | Create a new attribute node with given name | |
| createAttributeNS(namespaceURI$, qualname$) | Attr | Create a new attribute node with given name | |
| createCDATASection(data$) | CDATASection | Create a new CDATA node for given data | |
| createComment(text$) | Comment | Create a new Comment node for given text | |
| createDocumentFragment() | DocumentFragment | Create an empty DocumentFragment object | |
| createElement(tagname$) | Element | Create a new Element node | |
| createElementNS(namespaceURI$, qualname$) | Element | Create a new Element node | |
| createEntityReference(name$) | EntityReference | Create a new Entity reference node | |
| createNodeFilter() | NodeFilter | Create a node filter object | KCML |
| createNodeIterator(OBJECT root, whatToShow, OBJECT filter, entityReferenceExpansion) | NodeIterator | Create a flat tree NodeIterator | |
| createProcessingInstruction(target$, data$) | ProcessingInstruction | Create a new Processing Instruction node | |
| createTextNode(data$) | Text | Create a new Text node | |
| createTreeWalker(OBJECT root, whatToShow, OBJECT filter, entityReferenceExpansion) | TreeWalker | Create a TreeWalker iterator | |
| createWriterFilter() | WriterFilter | Create a serialization WriterFilter object | KCML |
| getElementById(id$) | Element | Return element matching an ID | |
| getElementsByTagName(pattern$) | NodeList | Make node list of elements matching a tag name or '*'. It does not support XPath. | |
| getElementsByTagNameNS(NsURI$, localname$) | NodeList | Get a node list object of descendent objects by name | |
| importNode(OBJECT importnode, deep) | Node | Import a node from another document | |
| normalizeDocument() | void | Normalize a document as if it had been saved and loaded again | |
| renameNode(OBJECT source, NsURI$, newname$) | Node | Rename a node |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Doctype | R | DocumentType | Returns the document type declaration | |
| DocumentElement | R | Element | Returns the documents root element | |
| DocumentURI$ | RW | string | Get/set document location, NULL if undefined | |
| Implementation | R | Implementation | Returns the implementation object that handles the doc | |
| InputEncoding$ | R | string | Get/set actual encoding of document | |
| StrictErrorChecking | RW | bool | Get/set error checking on node operations | |
| XmlEncoding$ | R | string | Get/set document encoding | |
| XmlStandalone | RW | bool | Get/set standalone | |
| XmlVersion$ | RW | string | Get/set document version string |
DOM Node object
Downcastable from the following interfaces:
| Method | Returns | Purpose | |
|---|---|---|---|
| appendChild(OBJECT newChild) | Node | Add child to list of children | |
| cloneNode(deep) | Node | Clone this node | |
| hasChildNodes() | bool | Return true if node has children | |
| insertBefore(OBJECT newChild, OBJECT refChild) | Node | Insert node before existing child node | |
| isSupported(feature$, version$) | bool | Supports a specified function | |
| normalize() | void | Normalize children | |
| release() | void | Free resources | Xerces |
| removeChild(OBJECT oldChild) | Node | Delete child oldchild from the list of children and return it | |
| replaceChild(OBJECT newChild, OBJECT oldChild) | Node | Replace existing child with newchild and return oldChild |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Attributes | R | NamedNodeMap | Return a list of the attributes of the node or NULL | |
| ChildNodes | R | NodeList | Return all children in a nodelist | |
| FirstChild | R | Node | Return first child of a node | |
| LastChild | R | Node | Return last child of a node | |
| LocalName$ | R | string | Return local part of the qualified name of this node | |
| NamespaceURI$ | R | string | Return namespace URI for node tag | |
| NextSibling | R | Node | Return next sibling of a node | |
| NodeName$ | R | string | Return name of a node (with any NS prefix) | |
| NodeType | R | int | Return type of a node | |
| NodeValue$ | R | string | Return value of a node, depending on type | |
| OwnerDocument | R | Document | Get the document associated with this node | |
| ParentNode | R | Node | Return parent of a node | |
| Prefix$ | RW | string | Get/set namespace prefix of this node | |
| PreviousSibling | R | Node | Return previous sibling of a node |
DOM Implementation object
Downcastable from the following interfaces:
| Method | Returns | Purpose | |
|---|---|---|---|
| createDocument(NamespaceURI$, qualifiedName$, OBJECT doctype) | Document | Creates a new XML Document object | |
| createDocument() | Document | Creates a nameless XML document object | |
| createDocumentType(qualifiedName$, publicId$, systemId$) | DocumentType | Creates a new XML DocumentType object | |
| hasFeature(feature$, version$) | bool | returns TRUE if a feature is supported |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Implementation | R | Implementation | Return a Implementation ref for this object |
DOM Document type object
Extends Node
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Entities | R | NamedNodeMap | Return a NamedNodeMap of the entities declared in the DTD | |
| InternalSubset$ | R | string | Return internal subset as a string | |
| Name$ | R | string | Return name of the DTD | |
| Notations | R | NamedNodeMap | Return a NamedNodeMap of the notations declared in the DTD | |
| PublicId$ | R | string | Return public ID of external subset | |
| SystemId$ | R | string | Return system ID of external subset |
DOM Text object
Extends CharacterData
| Method | Returns | Purpose | |
|---|---|---|---|
| isIgnorableWhitespace() | bool | Returns TRUE if node contains only ignorable whitespace (requires a DTD) | |
| isWhitespace() | bool | Returns TRUE if node contains only whitespace | KCML |
| splitText(offset) | Text | Splits node into two at offset |
DOM DocumentFragment object
DocumentFragment is a lightweight Document object allowing a program to extract part of a document tree or create a small object that looks like a Node without the overhead of a Document object.
In operations, such as inserting Nodes as children of other Nodes, that take Nodes as arguments, a DocumentFragment may be passed resulting in all the child nodes of the DocumentFragment being moved to the child list of this node.
DocumentFragment nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). For example, a DocumentFragment might have only one child and that child node could be a Text node. Such a structure model represents neither an HTML document nor a well-formed XML document.
When a DocumentFragment is inserted into a Document (or indeed any other Node that may take children) the children of the DocumentFragment and not the DocumentFragment itself are inserted into the Node. This makes the DocumentFragment very useful when the user wishes to create nodes that are siblings; the DocumentFragment acts as the parent of these nodes so that the user can use the standard methods from the Node interface, such as insertBefore() and appendChild().
Extends Node
DOM ProcessingInstruction object
Extends Node
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Data$ | RW | string | Get/set data of the element | |
| Target$ | R | string | Return target of the element |
DOM Character object
Extends Node
| Method | Returns | Purpose | |
|---|---|---|---|
| appendData(newdata$) | void | Appends character data to end of node | |
| deleteData(offset, count) | void | Deletes character data at the offset in the node | |
| insertData(offset, newdata$) | void | Inserts character data at the offset in the node | |
| replaceData(offset, count, newdata$) | void | Replaces character data at the offset in the node | |
| substringData$(offset, count) | string | Returns a substring of character data for node |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Data$ | R | string | Return data of the element | |
| Length | R | unsigned int | Return count of chars in the text |
DOM Attribute object
Extends Node
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Name$ | R | string | Return name of the attribute | |
| OwnerElement | R | Element | Return Element node the attribute is attached to or NULL if none | |
| Specified | R | bool | Return TRUE if the attribute was explicitly specified rather than assumed from the DTD default | |
| Value$ | RW | string | Get/set value of the attribute |
DOM Element object
Extends Node
| Method | Returns | Purpose | |
|---|---|---|---|
| getAttribute$(name$) | string | Get attribute of element by name | |
| getAttributeNS$(NsURI$, localname$) | string | Get attribute of element by name | |
| getAttributeNode(name$) | Attr | Get a Attr node object by name | |
| getAttributeNodeNS(NsURI$, localname$) | Attr | Get a Attr node object by name | |
| getElementsByTagName(name$) | NodeList | Get a node list object of descendent objects by name | |
| getElementsByTagNameNS(NsURI$, localname$) | NodeList | Get a node list object of descendent objects by name | |
| removeAttribute(name$) | void | Remove attribute of element by name | |
| removeAttributeNS(NsURI$, localname$) | void | Remove attribute of element by name | |
| removeAttributeNode(OBJECT name) | Attr | Remove specified Attr node | |
| setAttribute(name$, value$) | void | Set attribute of element by name | |
| setAttributeNS(NsURI$, qualname$, value$) | void | Set attribute of element by name | |
| setAttributeNode(OBJECT newattr) | Attr | Adds or replaces an Attr node | |
| setAttributeNodeNS(OBJECT newattr) | Attr | Adds or replaces an Attr node |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| TagName$ | R | string | Return name of the element (including any NS prefix). |
DOM Named Node Map object
This collection can be iterated with FOR OBJECT ... NEXT OBJECT
| Method | Returns | Purpose | |
|---|---|---|---|
| getNamedItem(name$) | Node | Return node with given name | |
| item(index) | Node | Return node with given index |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Length | R | unsigned int | Return count of nodes in the map |
DOM Node List object
This collection can be iterated with FOR OBJECT ... NEXT OBJECT
| Method | Returns | Purpose | |
|---|---|---|---|
| item(index) | Node | Return node with given index |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Length | R | unsigned int | Return count of nodes in a node list |
DOM TreeWalker object
| Method | Returns | Purpose | |
|---|---|---|---|
| firstChild() | Node | Moves to first child and returns the node | |
| getCurrentNode() | Node | Get node at which the NodeWalker is positioned | |
| lastChild() | Node | Moves to last child and returns the node | |
| nextNode() | Node | Moves to and returns next node in list | |
| nextSibling() | Node | Moves to next sibling and returns the node | |
| parentNode() | Node | Moves to and returns the closest visible ancestor node of the current node in list | |
| previousNode() | Node | Moves to and returns previous node in list | |
| previousSibling() | Node | Moves to previous sibling and returns the node | |
| setCurrentNode(OBJECT node) | void | Set node at which the NodeWalker is positioned |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| ExpandEntityReferences | R | bool | Return original ExpandEntityReferences flag | |
| WhatToShow | R | integer | Return bitmap of node types included |
DOM NodeIterator object
| Method | Returns | Purpose | |
|---|---|---|---|
| nextNode() | Node | Return next node in list | |
| previousNode() | Node | Return previous node in list |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| ExpandEntityReferences | R | bool | Return original ExpandEntityReferences flag | |
| WhatToShow | R | integer | Return bitmap of node types included |
Object that receives filter callbacks from NodeIterator and TreeWalker
The acceptNode() callback function returns one of the following enumeration
DIM _FILTER_ACCEPT=1, _FILTER_REJECT=2, _FILTER_SKIP=3
| Method | Returns | Purpose | |
|---|---|---|---|
| SetFilter(fn) | void | Set KCML callback for filtering a node |
| Callback | Returns | Purpose | |
|---|---|---|---|
| acceptNode(node) | integer |
Memory buffer based input stream object
Used to serialize a document
Features supportedThis table is taken from the Apache Xerces documentation
| normalize-characters |
true [ optional] (default) Perform the W3C Text Normalization of the characters in document as they are written out. Only the characters being written are (potentially) altered. The DOM document itself is unchanged. false [required] do not perform character normalization. |
| split-cdata-sections |
true [required] (default) Split CDATA sections containing the CDATA section termination marker ']]>' or characters that can not be represented in the output encoding, and output the characters using numeric character references. If a CDATA section is split a warning is issued. false [ required] Signal an error if a CDATASection contains an unrepresentable character. |
| validation |
true [ optional] Use the abstract schema to validate the document as it is being serialized. If validation errors are found the error handler is notified about the error. Setting this state will also set the feature use-abstract-schema to true. false [ required] (default) Don't validate the document as it is being serialized. |
| expand-entity-references |
true [ optional] Expand EntityReference nodes when serializing. false [required] (default) Serialize all EntityReference nodes as XML entity references. |
| whitespace-in-element-content |
true [required] ( default) Output all white spaces in the document. false [ optional] Only output white space that is not within element content. The implementation is expected to use the isWhitespaceInElementContent flag on Text nodes to determine if a text node should be written out or not. |
| discard-default-content |
true [required] (default ) Use whatever information available to the implementation (i.e. XML schema, DTD, the specified flag on Attr nodes, and so on) to decide what attributes and content should be serialized or not. Note that the specified flag on Attr nodes in itself is not always reliable, it is only reliable when it is set to false since the only case where it can be set to false is if the attribute was created by a Level 1 implementation. false [required] Output all attributes and all content. |
| format-canonical |
true [optional] This formatting writes the document according to the rules specified in DOM3. Setting this feature to true will set the feature "format-pretty-print" to false. false [required] (default) Don't canonicalize the output. |
| format-pretty-print |
true [optional] Formatting the output by adding whitespace to produce a pretty-printed, indented, human-readable form. The exact form of the transformations is not specified by this specification. Setting this feature to true will set the feature "format-canonical" to false. false [required] (default) Don't pretty-print the result. |
| Method | Returns | Purpose | |
|---|---|---|---|
| canSetFeature(feature$, value) | bool | Indicates whether setting a feature to a particular value will be supported | DOM3 |
| getFeature(feature$) | bool | Get the value of a standardized feature | DOM3 |
| release() | void | Free resources. Redundant, do not use | Obsolete |
| setFeature(feature$, value) | void | Set the value of a standardized feature | DOM3 |
| setFilter(OBJECT filter) | void | Apply a WriterFilter object to filter the serialized output | DOM3 |
| writeDocToString(OBJECT doc) | MemBufOutput | Serialize a UTF-8 encoded document to a string object | KCML |
| writeToString(OBJECT node) | MemBufOutput | Serialize a node to a string object. Note that in 6.20 KCML this method returns a string not an object and that this string will never be deleted causing a memory leak. In build 21043 the method as described here was added with the name writeToStringObject so that existing application code will continue to work but the new method is recommended to avoid the memory leak. | DOM3 |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| NewLine$ | RW | string | Get/Set end-of-line sequence to use when serializing. Only HEX(0A), HEX(0D) and HEX(0D0A) are acceptable. NULL means OS default. | DOM3 |
String object
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| Text$ | R | string | Return UTF-8 text | KCML |
Object that receives filter callbacks during serialization
The acceptNode() callback function returns the same enumeration as the NodeFilter callbacks namely
DIM _FILTER_ACCEPT=1, _FILTER_REJECT=2, _FILTER_SKIP=3
| Method | Returns | Purpose | |
|---|---|---|---|
| SetFilter(fn) | void | Set KCML callback for filtering a node |
| Callback | Returns | Purpose | |
|---|---|---|---|
| acceptNode(node) | integer |
| Property | Type | Returns | Purpose | |
|---|---|---|---|---|
| WhatToShow | RW | integer | Get/Set types of nodes to be serialized |
Factory methods for DOM Writer object
Extends Implementation
| Method | Returns | Purpose | |
|---|---|---|---|
| createDOMWriter() | Writer | Create a Writer serializing object | DOM3 |