ToXPathStringlist and XPathNodeID (XmlDoc/XmlNode functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (link repair)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:XmlDoc/XmlNode:ToXPathStringlist and XPathNodeID subtitle}}
{{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 <var>[[XPath]]</var> expression actually selects. In the remainder of this article, you can use <var>ToXPathStringlist</var> and <var>XPathNodeID</var> interchangeably.
<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>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">[http://www.sirius-software.com/maint/factr.pdf SirFact]</var>, <var class="product">[[Debugger|Janus Debugger]]</var>, and <var class="product">[[Debugger|Sirius 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.
<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==
==Syntax==
{{Template:XmlDoc/XmlNode:ToXPathStringlist syntax}}
{{Template:XmlDoc/XmlNode:ToXPathStringlist syntax}}
{{Template:XmlDoc/XmlNode:XPathNodeID syntax}}
{{Template:XmlDoc/XmlNode:XPathNodeID syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
Line 14: Line 15:
<td>A <var>Stringlist</var> to contain one or more items that identify the node identified by <var class="term">selectionXpath</var>.</td></tr>
<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>
<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 Root node is the context node.</td></tr>
<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>
<tr><th>selectionXpath</th>
<td>A <var>Unicode</var> string that is an [[XPath#XPath_syntax|Xpath expression]] that selects a node from the method object. Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this argument is an EBCDIC string.</td></tr>
<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>
</table>


Line 22: Line 25:
<ul>
<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).
<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>  
<p class="note"> '''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.
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>
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>
<li><var>XPathNodeID</var> is available in <var class="product">[[Sirius Mods]]</var> Version 7.0 and later.
<li><var>ToXPathStringlist</var> is available in <var class="product">Sirius Mods</var> Version 7.3 and later.
</ul>
</ul>


Line 48: Line 48:
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:
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>
<p class="code"><nowiki>
Argument:                      Returned <var>Stringlist</var> item(s):
Argument:                      Returned Stringlist item(s):
-----------------------------  ---------------------------
-----------------------------  ------------------------------
*/*                            /a/b
*/*                            /a/b
*/*/*                          /a/b/c[1]
*/*/*                          /a/b/c[1]
Line 57: Line 57:
*/*/*/@*                      /a/b/c[1]/@n
*/*/*/@*                      /a/b/c[1]/@n
/                              /
/                              /
*/*[2]                        /a/x:a
*/*[2]                        /a/x:a
                          Two prefix/URI items:
                              </nowiki><i>Two prefix/URI items:</i><nowiki>
                               x
                               x
                               u:a
                               u:a
*/*[2]/*[2]                    /a/x:a/_xpID.00:y
*/*[2]/*[2]                    /a/x:a/_xpID.00:y
                          Four prefix/URI items:
                              </nowiki><i>Four prefix/URI items:</i><nowiki>
                               x
                               x
                               u:a
                               u:a
                               _xpID.00</p>
                               _xpID.00
                               u:c
                               u:c
</nowiki></p>
</nowiki></p>


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

Latest revision as of 16:06, 1 June 2018

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 TN3270 Debugger users extract XPath information when needed. XPathNodeID does not work in those environments because of its object (Stringlist) output.

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 results in a nodelist. The head of the nodelist is the node to process. Any other nodes in the nodelist are ignored.

This is an optional argument, and its default is a period (.), that is, the node referenced by the method object (nr).

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.

Examples

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>

When applied to the above document, the following table shows the Stringlist's item(s) returned for each of various XPathNodeID arguments:

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 Two prefix/URI items: x u:a */*[2]/*[2] /a/x:a/_xpID.00:y Four prefix/URI items: x u:a _xpID.00 u:c

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

  • The selectionXpath expression is invalid.
  • Insufficient free space exists in CCATEMP.

See also