Skip Headers

Oracle® XML API Reference 10g Release 1 (10.1) Part No. B10789-01 |
| Contents

## Node Interface

Table 4-8 summarizes the methods of available through the `Node` interface.

Table 4-8 Summary of Text Methods; DOM Package

Function | Summary
--- | ---
XmlDomAppendChild | Append new child to node's list of children.
XmlDomCleanNode | Clean a node (free DOM allocations).
XmlDomCloneNode | Clone a node.
XmlDomFreeNode | Free a node allocated with `XmlDomCreateXXX`.
XmlDomGetAttrs | Return attributes of node.
XmlDomGetChildNodes | Return children of node.
XmlDomGetDefaultNS | Get default namespace for node.
XmlDomGetFirstChild | Returns first child of node.
XmlDomGetFirstPfnsPair | Get first prefix namespace pair.
XmlDomGetLastChild | Returns last child of node.
XmlDomGetNextPfnsPair | Get subsequent prefix namespace pair.
XmlDomGetNextSibling | Return next sibling of node.
XmlDomGetNodeLocal | Get local part of node's qualified name as `NULL`-terminated string.
XmlDomGetNodeLocalLen | Get local part of node's qualified name as length-encoded string.
XmlDomGetNodeName | Get node's name as `NULL`-terminated string.
XmlDomGetNodeNameLen | Get node's name as length-encoded string.
XmlDomGetNodePrefix | Return namespace prefix of node.
XmlDomGetNodeType | Get node's numeric type code.
XmlDomGetNodeURI | Return namespace URI of node as a `NULL`-terminated string.
XmlDomGetNodeURILen | Return namespace URI of node as length-encoded string.
XmlDomGetNodeValue | Get node's value as `NULL`-terminated string.
XmlDomGetNodeValueLen | Get node value as length-encoded string.
XmlDomGetNodeValueStream | Get node value stream-style (chunked).
XmlDomGetOwnerDocument | Get the owner document of node.
XmlDomGetParentNode | Get parent node.
XmlDomGetPrevSibling | Return previous sibling of node.
XmlDomGetSourceEntity | Return the entity node if the input file is an external entity.
XmlDomGetSourceLine | Return source line number of node.
XmlDomGetSourceLocation | Return source location (path, URI, and so on) of node.
XmlDomHasAttr | Does named attribute exist?
XmlDomHasChildNodes | Test if node has children.
XmlDomInsertBefore | Insert new child in to node's list of children.
XmlDomNormalize | Normalize a node by merging adjacent text nodes.
XmlDomNumAttrs | Return number of attributes of element.
XmlDomNumChildNodes | Return number of children of node.
XmlDomPrefixToURI | Get namespace URI for prefix.
XmlDomRemoveChild | Remove an existing child node.
XmlDomReplaceChild | Replace an existing child of a node.
XmlDomSetDefaultNS | Set default namespace for node.
XmlDomSetNodePrefix | Set namespace prefix of node.
XmlDomSetNodeValue | Set node value.
XmlDomSetNodeValueLen | Set node value as length-encoded string.
XmlDomSetNodeValueStream | Set node value stream-style (chunked).
XmlDomValidate | Validate a node against current DTD.

### XmlDomAppendChild

Appends the node to the end of the parent's list of children and returns the new node. If `newChild` is a `DocumentFragment`, all of its children are appended in original order; the `DocumentFragment` node itself is not.

Syntax

    xmlnode* XmlDomAppendChild(
       xmlctx *xctx,
       xmlnode *parent,
       xmlnode *newChild)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    parent
    IN
| parent to receive a new node
    newChild
    IN
| node to add

Returns

`(xmlnode *)` node added

See Also: XmlDomInsertBefore, XmlDomReplaceChild

### XmlDomCleanNode

Frees parts of the node which were allocated by DOM itself, but does not recurse to children or touch the node's attributes. After freeing part of the node (such as name), a DOM call to get that part (such as `XmlDomGetNodeName`) should return a `NULL` pointer. Used to manage the allocations of a node parts of which are controlled by DOM, and part by the user. Calling clean frees all allocations may by DOM and leaves the user's allocations alone. The user is responsible for freeing their own allocations.

Syntax

    void XmlDomCleanNode(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| node to clean

See Also: XmlDomFreeNode

### XmlDomCloneNode

Creates and returns a duplicate of a node. The duplicate node has no parent. Cloning an element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but it does not copy any text it contains unless it is a deep clone, since the text is contained in a child text node. Cloning any other type of node simply returns a copy of the node. Note that a clone of an unspecified attribute node is specified. If deep is `TRUE`, all children of the node are recursively cloned, and the cloned node will have cloned children; a non-deep clone will have no children.

Syntax

    xmlnode* XmlDomCloneNode(
       xmlctx *xctx,
       xmlnode *node,
       boolean deep)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    deep
    IN
| `TRUE` to recursively clone children

Returns

`(xmlnode *)` duplicate (cloned) node

See Also: XmlDomImportNode

### XmlDomFreeNode

Free a node allocated with `XmlDomCreate` `XXX`. Frees all resources associated with a node, then frees the node itself. Certain parts of the node are under DOM control, and some parts may be under user control. DOM keeps flags tracking who owns what, and only frees its own allocations. The user is responsible for freeing their own parts of the node before calling XmlDomFreeNode.

Syntax

    void XmlDomFreeNode(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node to free

See Also: XmlDomCleanNode

### XmlDomGetAttrs

Returns a `NamedNodeMap` of attributes of an element node, or `NULL` if it has no attributes. For other node types, `NULL` is returned. Note that if an element once had attributes, but they have all been removed, an empty list will be returned. So, presence of the list does not mean the element has attributes. You must check the size of the list with `XmlDomNumAttrs` or use `XmlDomHasChildNodes` first.

Syntax

    xmlnamedmap* XmlDomGetAttrs(
       xmlctx *xctx,
       xmlelemnode *elem)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    elem
    IN
| XML element node

Returns

`(xmlnamedmap *)` `NamedNodeMap` of node's attributes

See Also: XmlDomNumAttrs, XmlDomHasChildNodes

### XmlDomGetChildNodes

Returns a list of the node's children, or `NULL` if it has no children. Only `Element`, `Document`, DTD, and `DocumentFragment` nodes may have children; all other types will return `NULL`.

Note that an empty list may be returned if the node once had children, but all have been removed! That is, the list may exist but have no members. So, presence of the list alone does not mean the node has children. You must check the size of the list with `XmlDomNumChildNodes` or use `XmlDomHasChildNodes` first.

The xmlnodelist structure is opaque and can only be manipulated with functions in the `NodeList` interface.

The returned list is live; all changes in the original node are reflected immediately.

Syntax

    xmlnodelist* XmlDomGetChildNodes(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlnodelist *)` live `NodeList` containing all children of node

### XmlDomGetDefaultNS

Gets the default namespace for a node.

Syntax

    oratext* XmlDomGetDefaultNS(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| element or attribute DOM node

Returns

`(oratext *)` default namespace for node [data encoding; may be `NULL`]

### XmlDomGetFirstChild

Returns the first child of a node, or `NULL` if the node has no children. Only `Element`, `Document`, DTD, and `DocumentFragment` nodes may have children; all other types will return `NULL`.

Syntax

    xmlnode* XmlDomGetFirstChild(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlnode *)` first child of node

See Also: XmlDomGetLastChild, XmlDomHasChildNodes, XmlDomGetChildNodes, XmlDomNumChildNodes

### XmlDomGetFirstPfnsPair

This function is to allow implementations an opportunity to speedup the iteration of all available prefix-URI bindings available on a given node. It returns a state structure and the prefix and URI of the first prefix-URI mapping. The state structure should be passed to `XmlDomGetNextPfnsPair` on the remaining pairs.

Syntax

    xmlpfnspair* XmlDomGetFirstPfnsPair(
       xmlctx *xctx,
       xmlnode *node,
       oratext **prefix,
       oratext **uri)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    prefix
    OUT
| prefix of first mapping; data encoding
    uri
    OUT
| URI of first mapping; data encoding

Returns

`(xmlpfnspair *)` iterating object or `NULL` of no prefixes

### XmlDomGetLastChild

Returns the last child of a node, or `NULL` if the node has no children. Only `Element`, `Document`, DTD, and `DocumentFragment` nodes may have children; all other types will return `NULL`.

Syntax

    xmlnode* XmlDomGetLastChild(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlnode *)` last child of node

See Also: XmlDomGetFirstChild, XmlDomHasChildNodes, XmlDomGetChildNodes, XmlDomNumChildNodes

### XmlDomGetNextPfnsPair

This function is to allow implementations an opportunity to speedup the iteration of all available prefix-URI bindings available on a given node. Given an iterator structure from `XmlDomGetFirstPfnsPair`, returns the next prefix-URI mapping; repeat calls to `XmlDomGetNextPfnsPair` until `NULL` is returned.

Syntax

    xmlpfnspair* XmlDomGetNextPfnsPair(
       xmlctx *xctx
       xmlpfnspair *pfns,
       oratext **prefix,
       oratext **uri)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    prefix
    OUT
| prefix of next mapping; data encoding
    uri
    OUT
| URI of next mapping; data encoding

Returns

`(xmlpfnspair *)` iterating object, `NULL` when no more pairs

### XmlDomGetNextSibling

Returns the node following a node at the same level in the DOM tree. That is, for each child of a parent node, the next sibling of that child is the child which comes after it. If a node is the last child of its parent, or has no parent, `NULL` is returned.

Syntax

    xmlnode* XmlDomGetNextSibling(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlnode *)` node immediately following node at same level

See Also: XmlDomGetPrevSibling

### XmlDomGetNodeLocal

Returns the namespace local name for a node as a `NULL`-terminated string. If the node's name is not fully qualified (has no prefix), then the local name is the same as the name.

A length-encoded version is available as `XmlDomGetNodeLocalLen` which returns the local name as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetNodeLocal(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(oratext *)` local name of node [data encoding]

See Also: XmlDomGetNodeLocalLen, XmlDomGetNodePrefix, XmlDomGetNodeURI

### XmlDomGetNodeLocalLen

Returns the namespace local name for a node as a length-encoded string. If the node's name is not fully qualified (has no prefix), then the local name is the same as the name.

A `NULL`-terminated version is available as `XmlDomGetNodeLocal` which returns the local name as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and `NULL`-terminate the data.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

    oratext* XmlDomGetNodeLocalLen(
       xmlctx *xctx,
       xmlnode *node,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of local name, in characters

Returns

`(oratext *)` local name of node [data encoding]

See Also: XmlDomGetNodeLocal, XmlDomGetNodePrefix, XmlDomGetNodeURILen

### XmlDomGetNodeName

Returns the (fully-qualified) name of a node (in the data encoding) as a `NULL`-terminated string, for example `bar\0` or `foo:bar\0`.

Note that some node types have fixed names: "`#text`", "`#cdata-section`", "#`comment`", "`#document`", "`#document-fragment`".

A node's name cannot be changed once it is created, so there is no matching `SetNodeName` function.

A length-based version is available as `XmlDomGetNodeNameLen` which returns the node name as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetNodeName(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(oratext *)` name of node [data encoding]

See Also: XmlDomGetNodeNameLen

### XmlDomGetNodeNameLen

Returns the (fully-qualified) name of a node (in the data encoding) as a length-encoded string, for example `"bar", 3` or `"foo:bar", 7`.

Note that some node types have fixed names: "`#text`", "`#cdata-section`", "`#comment`", "`#document`", "`#document-fragment`".

A node's name cannot be changed once it is created, so there is no matching SetNodeName function.

A `NULL`-terminated version is available as XmlDomGetNodeName which returns the node name as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the node's name will be stored internally as length-encoded. Using the length-encoded `Get` `XXX` functions will avoid having to copy and `NULL`-terminate the name.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and `len` will return the actual length.

Syntax

    oratext* XmlDomGetNodeNameLen(
       xmlctx *xctx,
       xmlnode *node,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of name, in characters

Returns

`(oratext *)` name of node, with length of name set in 'len'

See Also: XmlDomGetNodeName

### XmlDomGetNodePrefix

Returns the namespace prefix for a node (as a `NULL`-terminated string). If the node's name is not fully qualified (has no prefix), `NULL` is returned.

Syntax

    oratext* XmlDomGetNodePrefix(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(oratext *)` namespace prefix of node [data encoding; may be `NULL`]

### XmlDomGetNodeType

Returns the type code of a node. The type names and numeric values match the DOM specification:

- `ELEMENT_NODE=1`

- `ATTRIBUTE_NODE=2`

- `TEXT_NODE=3`

- `CDATA_SECTION_NODE=4`

- `ENTITY_REFERENCE_NODE=5`

- `ENTITY_NODE=6`

- `PROCESSING_INSTRUCTION_NODE=7`

- `COMMENT_NODE=8`

- `DOCUMENT_NODE=9`

- `DOCUMENT_TYPE_NODE=10`

- `DOCUMENT_FRAGMENT_NODE=11`

- `NOTATION_NODE=12`

Additional Oracle extension node types are as follows:

- `ELEMENT_DECL_NODE`

- `ATTR_DECL_NODE`

- `CP_ELEMENT_NODE`

- `CP_CHOICE_NODE`

- `CP_PCDATA_NODE`

- `CP_STAR_NODE`

- `CP_PLUS_NODE`

- `CP_OPT_NODE`

Syntax

    xmlnodetype XmlDomGetNodeType(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlnodetype)` numeric type-code of the node

### XmlDomGetNodeURI

Returns the namespace URI for a node (in the data encoding) as a `NULL`-terminated string. If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be `NULL`).

A length-encoded version is available as `XmlDomGetNodeURILen` which returns the URI as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetNodeURI(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(oratext *)` namespace URI of node [data encoding; may be `NULL`]

See Also: XmlDomGetNodeURILen, XmlDomGetNodePrefix, XmlDomGetNodeLocal

### XmlDomGetNodeURILen

Returns the namespace URI for a node (in the data encoding) as length-encoded string. If the node's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be `NULL`).

A `NULL`-terminated version is available as `XmlDomGetNodeURI` which returns the URI value as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and `NULL`-terminate the data.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and `len` will return the actual length.

Syntax

    oratext* XmlDomGetNodeURILen(
       xmlctx *xctx,
       xmlnode *node,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of URI, in characters

Returns

`(oratext *)` namespace URI of node [data encoding; may be `NULL`]

See Also: XmlDomGetNodeURI, XmlDomGetNodePrefix, XmlDomGetNodeLocal

### XmlDomGetNodeValue

Returns the "value" (associated character data) for a node as a `NULL`-terminated string. Character and general entities will have been replaced. Only `Attr`, `CDATA`, `Comment`, `ProcessingInstruction` and `Text` nodes have values, all other node types have `NULL` value.

A length-encoded version is available as `XmlDomGetNodeValueLen` which returns the node value as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetNodeValue(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(oratext *)` value of node

See Also: XmlDomSetNodeValue, XmlDomGetNodeValueLen

### XmlDomGetNodeValueLen

Returns the "value" (associated character data) for a node as a length-encoded string. Character and general entities will have been replaced. Only `Attr`, `CDATA`, `Comment`, PI and `Text` nodes have values, all other node types have `NULL` value.

A `NULL`-terminated version is available as `XmlDomGetNodeValue` which returns the node value as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the node's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and `NULL`-terminate the data.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than `buflen`, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

    oratext* XmlDomGetNodeValueLen(
       xmlctx *xctx,
       xmlnode *node,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of value, in bytes

Returns

`(oratext *)` value of node

See Also: XmlDomSetNodeValueLen, XmlDomGetNodeValue

### XmlDomGetNodeValueStream

Returns the large data for a node and sends it in pieces to the user's output stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to access chunked data of that type. Only `XMLType` chunks its data (sometimes); XDK's data is always contiguous.

Syntax

    xmlerr XmlDomGetNodeValueStream(
       xmlctx *xctx,
       xmlnode *node,
       xmlostream *ostream)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    ostream
    IN
| output stream object

Returns

`(xmlerr)` numeric error code, `0` on success

See Also: XmlDomSetNodeValueStream, XmlDomGetNodeValue, XmlDomGetNodeValueLen

### XmlDomGetOwnerDocument

Returns the `Document` node associated with a node. Each node may belong to only one document, or may not be associated with any document at all (such as immediately after `XmlDomCreateElem`, and so on). The "owning" document [node] is returned, or `NULL` for an orphan node.

Syntax

    xmldocnode* XmlDomGetOwnerDocument(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmldocnode *)` document node is in

### XmlDomGetParentNode

Returns a node's parent node. All nodes types except `Attr`, `Document`, `DocumentFragment`, `Entity`, and `Notation` may have a parent (these five exceptions always have a `NULL` parent). If a node has just been created but not yet added to the DOM tree, or if it has been removed from the DOM tree, its parent is also `NULL`.

Syntax

    xmlnode* XmlDomGetParentNode(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlnode *)` parent of node

### XmlDomGetPrevSibling

Returns the node preceding a node at the same level in the DOM tree. That is, for each child of a parent node, the previous sibling of that child is the child which came before it. If a node is the first child of its parent, or has no parent, `NULL` is returned.

Syntax

    xmlnode* XmlDomGetPrevSibling(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlnode *)` node immediately preceding node at same level

See Also: XmlDomGetNextSibling

### XmlDomGetSourceEntity

Returns the external entity node whose inclusion caused the creation of the given node.

Syntax

    xmlentnode* XmlDomGetSourceEntity(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(xmlentnode *)` entity node if the input is from an external entity

### XmlDomGetSourceLine

Returns the line# in the original source where the node started. The first line in every input is line #1.

Syntax

    ub4 XmlDomGetSourceLine(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(ub4)` line number of node in original input source

### XmlDomGetSourceLocation

Return source location (path, URI, and so on) of node. Note this will be in the compiler encoding, not the data encoding!

Syntax

    oratext* XmlDomGetSourceLocation(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(oratext *)` full path of input source [in compiler encoding]

### XmlDomHasAttrs

Test if an element has attributes. Returns `TRUE` if any attributes of any sort are defined (namespace or regular).

Syntax

    boolean XmlDomHasAttrs(
       xmlctx *xctx,
       xmlelemnode *elem)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    elem
    IN
| XML element node

Returns

`(boolean)` `TRUE` if element has attributes

### XmlDomHasChildNodes

Test if a node has children. Only `Element`, `Document`, DTD, and `DocumentFragment` nodes may have children. Note that just because `XmlDomGetChildNodes` returns a list does not mean the node actually has children, since the list may be empty, so a non-`NULL` return from `XmlDomGetChildNodes` should not be used as a test.

Syntax

    boolean XmlDomHasChildNodes(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(boolean)` `TRUE` if the node has any children

### XmlDomInsertBefore

Inserts the node `newChild` before the existing child node `refChild` in the parent node. If `refChild` is `NULL`, appends to parent's children as for each `XmlDomAppendChild`; otherwise it must be a child of the given parent. If `newChild` is a `DocumentFragment`, all of its children are inserted (in the same order) before`refChild`; the `DocumentFragment` node itself is not. If `newChild` is already in the DOM tree, it is first removed from its current position.

Syntax

    xmlnode* XmlDomInsertBefore(
       xmlctx *xctx,
       xmlnode *parent,
       xmlnode *newChild,
       xmlnode *refChild)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    parent
    IN
| parent that receives a new child
    newChild
    IN
| node to insert
    refChild
    IN
| reference node

Returns

`(xmlnode *)` node being inserted

See Also: XmlDomAppendChild, XmlDomReplaceChild, XmlDomRemoveChild

### XmlDomNormalize

Normalizes the subtree rooted at an element, merges adjacent `Text` nodes children of elements. Note that adjacent `Text` nodes will never be created during a normal parse, only after manipulation of the document with DOM calls.

Syntax

    void XmlDomNormalize(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

### XmlDomNumAttrs

Returns the number of attributes of an element. Note that just because a list is returned by `XmlDomGetAttrs` does not mean it contains any attributes; it may be an empty list with zero length.

Syntax

    ub4 XmlDomNumAttrs(
       xmlctx *xctx,
       xmlelemnode *elem)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    elem
    IN
| XML element node

Returns

`(ub4)` number of attributes of node

### XmlDomNumChildNodes

Returns the number of children of a node. Only `Element`, `Document`, DTD, and `DocumentFragment` nodes may have children, all other types return 0. Note that just because `XmlDomGetChildNodes` returns a list does not mean that it contains any children; it may be an empty list with zero length.

Syntax

    ub4 XmlDomNumChildNodes(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node

Returns

`(ub4)` number of children of node

### XmlDomPrefixToURI

Given a namespace prefix and a node, returns the namespace URI mapped to that prefix. If the given node doesn't have a matching prefix, its parent is tried, then its parent, and so on, all the way to the root node. If the prefix is undefined, `NULL` is returned.

Syntax

    oratext* XmlDomPrefixToURI(
       xmlctx *xctx,
       xmlnode *node,
       oratext *prefix)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    prefix
    IN
| prefix to map

Returns

`(oratext *)` URI for prefix [data encoding; `NULL` if no match]

### XmlDomRemoveChild

Removes a node from its parent's list of children and returns it. The node is orphaned; its parent will be `NULL` after removal.

Syntax

    xmlnode* XmlDomRemoveChild(
       xmlctx *xctx,
       xmlnode *oldChild)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    oldChild
    IN
| node to remove

Returns

`(xmlnode *)` node removed

See Also: XmlDomAppendChild, XmlDomInsertBefore, XmlDomReplaceChild

### XmlDomReplaceChild

Replaces the child node `oldChild` with the new node `newChild` in `oldChild`'s parent, and returns `oldChild` (which is now orphaned, with a `NULL` parent). If `newChild` is a `DocumentFragment`, all of its children are inserted in place of `oldChild`; the `DocumentFragment` node itself is not. If `newChild` is already in the DOM tree, it is first removed from its current position.

Syntax

    xmlnode* XmlDomReplaceChild(
       xmlctx *xctx,
       xmlnode *newChild,
       xmlnode *oldChild)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    newChild
    IN
| new node that is substituted
    oldChild
    IN
| old node that is replaced

Returns

`(xmlnode *)` node replaced

See Also: XmlDomAppendChild, XmlDomInsertBefore, XmlDomRemoveChild

### XmlDomSetDefaultNS

Set the default namespace for a node

Syntax

    void XmlDomSetDefaultNS(
       xmlctx *xctx,
       xmlnode *node,
       oratext *defns)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| element or attribute DOM node
    defns
    IN
| new default namespace for the node

### XmlDomSetNodePrefix

Sets the namespace prefix of node (as `NULL`-terminated string). Does not verify the prefix is defined. Just causes a new qualified name to be formed from the new prefix and the old local name; the new qualified name will be under DOM control and should not be managed by the user.

Syntax

    void XmlDomSetNodePrefix(
       xmlctx *xctx,
       xmlnode *node,
       oratext *prefix)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    prefix
    OUT
| new namespace prefix

### XmlDomSetNodeValue

Sets a node's value (character data) as a `NULL`-terminated string. Does not allow setting the value to `NULL`. Only `Attr`, `CDATA`, `Comment`, PI and `Text` nodes have values; trying to set the value of another type of node is a no-op. The new value must be in the data encoding. It is not verified, converted, or checked.

The value is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

    xmlerr XmlDomSetNodeValue(
       xmlctx *xctx,
       xmlnode *node,
       oratext *value)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    value
    IN
| node's new value; data encoding; user control

Returns

`(xmlerr)` numeric error code, `0` on success

See Also: XmlDomGetNodeValue, XmlDomSetNodeValueLen

### XmlDomSetNodeValueLen

Sets the value (associated character data) for a node as a length-encoded string.

A `NULL`-terminated version is available as `XmlDomSetNodeValue` which takes the node value as a `NULL`-terminated string. If the backing store is known to be `XMLType`, then the node's data will be stored internally as length-encoded. Using the length-based Set functions will avoid having to copy and `NULL`-terminate the data.

Syntax

    xmlerr XmlDomSetNodeValueLen(
       xmlctx *xctx,
       xmlnode *node,
       oratext *value,
       ub4 len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    value
    IN
| node's new value; data encoding; user control
    len
    IN
| length of value, in bytes

Returns

`(xmlerr)` numeric error code, `0` on success

See Also: XmlDomSetNodeValueLen, XmlDomSetNodeValue

### XmlDomSetNodeValueStream

Sets the large "value" (character data) for a node piecemeal from an input stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to store chunked data of that type. Used only for `XMLType` data; XDK's data is always contiguous.

Syntax

    xmlerr XmlDomSetNodeValueStream(
       xmlctx *xctx,
       xmlnode *node,
       xmlistream *istream)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| XML node
    istream
    IN
| input stream object

Returns

`(xmlerr)` numeric error code, `0` on success

See Also: XmlDomGetNodeValueStream, XmlDomSetNodeValue

### XmlDomValidate

Given a root node, validates it against the current DTD.

Syntax

    xmlerr XmlDomValidate(
       xmlctx *xctx,
       xmlnode *node)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    node
    IN
| node to validate

Returns

`(xmlerr)` error code, `XMLERR_OK [0]` means node is valid