ToXPathStringlist and XPathNodeID (XmlDoc/XmlNode functions)
XPath expression (in Stringlist) for selected node (XmlDoc and XmlNode classes)
ToXPathStringlist and XPathNodeID are synonyms; they return an absolute XPath expression that identifies the node that the argument XPath expression actually selects. In the remainder of this article, you can use ToXPathStringlist and XPathNodeID interchangeably.
XPathNodeID is designed to provide additional information when sending an error message to an XML client application, helping the application to identify an invalid node selection in its request XML document. A complex XPath expression might not be finding the node intended, for example.
ToXPathString is the same as XPathNodeID except its output is a string instead of a Stringlist. ToXPathString lets SirFact, Janus Debugger, and Sirius Debugger users extract XPath information when needed. XPathNodeID does not work in those environments because of its object (Stringlist) output.
XPathNodeID is new as of version 7.0 of the Sirius Mods. ToXPathStringlist is new in version 7.3 of the Sirius Mods.
Syntax
%sl = nr:ToXPathStringlist[( [selectionXpath])] Throws XPathError
%sl = nr:XPathNodeID[( [selectionXpath])] Throws XPathError
Syntax terms
| %sl | A Stringlist to contain one or more items that identify the node identified by selectionXpath. |
|---|---|
| nr | An XmlDoc or XmlNode, used as the context node for the selectionXpath expression. If an XmlDoc, the Root node is the context node. |
| selectionXpath | A Unicode string that is an XPath expression that selects a node from the method object. Prior to Sirius Mods version 7.6, this argument is an EBCDIC string. |
Usage notes
- If the absolute XPath expression returned by XPathNodeID contains no prefixes, the Stringlist %sl contains only one item: the expression. However, if the expression uses an element or attribute that has one or more non-null namespace URIs, the expression occupies an additional pair of Stringlist items for each such URI (an item for the associated prefix, then an item for the URI). Note: If the expression uses a URI that is without a prefix in the document or if a single prefix in the document. is used for two different URIs, XPathNodeID generates an "invented" prefix. Such a prefix is generated because an XPath expression requires a prefix if it names an element or attribute that has a URI (for more about this requirement, see SelectionNamespace). A generated prefix is shown in the example, below.
Example
The following document contained in an XmlDoc is used as the method object for XPathNodeID:
<a> <?p1?> <b> <c n="1"/> <c n="2"/> </b> <?p2?> <x:a xmlns:x="u:a"> <x:b/> <y xmlns="u:c"/> </x:a> </a>
The following table shows the Stringlist's item(s) returned for each of various XPathNodeID arguments:
Argument: Returned <var>Stringlist</var> item(s): ----------------------------- --------------------------- */* /a/b */*/* /a/b/c[1] */*/*[2] /a/b/c[2] */processing-instruction() /a/processing-instruction()[1] */processing-instruction()[2] /a/processing-instruction()[2] */*/*/@* /a/b/c[1]/@n / / */*[2] /a/x:a Two prefix/URI items: x u:a */*[2]/*[2] /a/x:a/_xpID.00:y Four prefix/URI items: x u:a _xpID.00</p> u:c
Request-Cancellation Errors
- selectionXpath is invalid.
- Insufficient free space exists in CCATEMP.