View source for ToXPathStringlist and XPathNodeID (XmlDoc/XmlNode functions)

{{Template:XmlDoc/XmlNode:ToXPathStringlist and XPathNodeID subtitle}}
<var>ToXPathStringlist</var> and <var>XPathNodeID</var> 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 <var>ToXPathStringlist</var> and <var>XPathNodeID</var> interchangeably.

<var>XPathNodeID</var> 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.

<var>[[ToXPathString (XmlDoc/XmlNode function)|ToXPathString]]</var> is the same as <var>XPathNodeID</var> except its output is a string instead of a <var>Stringlist</var>.  <var>ToXPathString</var> lets <var class="product">[[SirFact]]</var>, <var class="product">[[Debugger|Janus Debugger]]</var>, and <var class="product">[[Debugger|TN3270 Debugger]]</var> users extract XPath information when needed. <var>XPathNodeID</var> does not work in those environments because of its object (<var>Stringlist</var>) output.

==Syntax==
{{Template:XmlDoc/XmlNode:ToXPathStringlist syntax}}
{{Template:XmlDoc/XmlNode:XPathNodeID syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%sl</th>
<td>A <var>Stringlist</var> to contain one or more items that identify the node identified by <var class="term">selectionXpath</var>.</td></tr>
<tr><th>nr</th>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <var class="term">selectionXpath</var> expression. If an <var>XmlDoc</var>, the <var>Root</var> node is the context node.</td></tr>
<tr><th>selectionXpath</th>
<td>A <var>Unicode</var> string that is an [[XPath#XPath_syntax|Xpath expression]]  that results in a nodelist. The head of the nodelist is the node to process. Any other nodes in the nodelist are ignored.
<p>
This is an optional argument, and its default is a period (<tt>.</tt>), that is, the node referenced by the method object (<var class="term">nr</var>). </p>Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this argument is an EBCDIC string.</td></tr>
</table>

==Usage notes==
<ul>
<li>If the absolute XPath expression returned by <var>XPathNodeID</var> contains no prefixes, the <var>Stringlist</var> <var class="term">%sl</var> 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 <var>Stringlist</var> items for each such URI (an item for the associated prefix, then an item for the URI).
<p class="note"> '''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, <var>XPathNodeID</var> 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 <var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var>).  A generated prefix is shown in the example, below. </p>
</ul>

==Examples==
The following document contained in an <var>XmlDoc</var> is used as the
method object for <var>XPathNodeID</var>:
<p class="code"><nowiki><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></nowiki>
</p>
When applied to the above document, the following table shows the <var>Stringlist</var>'s item(s) returned for each of various <var>XPathNodeID</var> arguments:
<p class="code"><nowiki>
Argument:                      Returned Stringlist 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
                               </nowiki><i>Two prefix/URI items:</i><nowiki>
                               x
                               u:a

*/*[2]/*[2]                    /a/x:a/_xpID.00:y
                               </nowiki><i>Four prefix/URI items:</i><nowiki>
                               x
                               u:a
                               _xpID.00
                               u:c
</nowiki></p>

==Request-cancellation errors==
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
<ul>
<li>The <var class="term">selectionXpath</var> expression is invalid.
<li>Insufficient free space exists in CCATEMP.
</ul>

==See also==
{{Template:XmlDoc/XmlNode:XPathNodeID footer}}