ToXPathString (XmlDoc/XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
 
(12 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:XmlDoc/XmlNode:ToXPathString subtitle}}
{{Template:XmlDoc/XmlNode:ToXPathString subtitle}}
<var>ToXPathString </var> returns, in a string, an absolute XPath expression that identifies the node that a given XPath expression actually selects.  <var>ToXPathString</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</var> is the same as <var>[[XPathNodeID (XmlDoc/XmlNode function)|XPathNodeID]]</var> except its output is a string instead of a <var>Stringlist</var> (<var>ToXPathStringlist</var> is a synonym for <var>XPathNodeID</var>).  <var>ToXPathString</var> lets <var class="product">[http://m204wiki.rocketsoftware.com/images/f/fb/FactrNew.pdf SirFact]</var>, <var class="product">[[Debugger|Janus Debugger]]</var>, and <var class="product">[[Debugger|Sirius Debugger]]</var>  users extract XPath information when needed.  The <var>XPathNodeID</var> method does not work in those environments because of its object (<var>Stringlist</var>) output.


This function returns in a string an absolute XPath expression that identifies the
==Syntax==
node that a given XPath expression actually selects.
{{Template:XmlDoc/XmlNode:ToXPathString syntax}}
<var>ToXPathString</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</var> is the same as <var>[[XPathNodeID (XmlDoc/XmlNode function)|XPathNodeID]]</var>
except its output is a string instead of a <var>Stringlist</var>
(<var>ToXPathStringlist</var> is a synonym for <var>XPathNodeID</var>).
<var>ToXPathString</var> lets
[[SirFact]], [[Janus Debugger]], and [[Sirius Debugger]] users extract XPath information when needed.
The XPathNodeID method does not work in those environments because of its
object (<var>Stringlist</var>) output.
<var>ToXPathString</var> is new as of version 7.3 of the ''Sirius Mods''.
==Syntax==
{{Template:XmlDoc/XmlNode:ToXPathtring syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%string</th>
<tr><th>%string</th>
<td>A string or longstring that identifies the node identified by ''selectionXpath''. </td></tr>
<td>A string or <var>Longstring</var> that identifies 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 <i>selectionXpath</i> 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 expression that selects a node from the method object. Prior to ''Sirius Mods'' version 7.6, this 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 is an EBCDIC string.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>If the absolute XPath expression returned by <var>ToXPathString</var>
<li>If the absolute XPath expression returned by <var>ToXPathString</var> contains no prefixes, the string <var class="term">%string</var> contains only one item: the expression. However, if the expression uses
contains no prefixes, the string ''%str''
an element or attribute that has one or more non-null namespace URIs, the expression contains an additional pair of blank-delimited substrings for each such URI (a substring for the associated prefix, then a substring for the URI).  
contains only one item: the expression.
<p>
However, if the expression uses
an element or attribute that has one or more non-null namespace URIs,
the expression
contains an additional pair of blank-delimited substrings for each such URI
(a substring for the associated prefix, then a substring for the URI).
'''Note:'''
'''Note:'''
If the expression uses a URI that is without a prefix in the document
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>ToXPathString</var> generates an "invented" prefix.
or if a single prefix in the document
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>
is used for two different URIs, <var>ToXPathString</var> generates an "invented" prefix.
<li><var>ToXPathString</var> is available in <var class="product">Sirius Mods</var> Version 7.3 and later.
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 (XmlDoc property)|SelectionNamespace]]).
A generated prefix is shown in the example, below.
</ul>
</ul>
===Example===


The following document contained in an <var>XmlDoc</var> is used as the
==Examples==
method object for <var>ToXPathString</var>:
The following document contained in an <var>XmlDoc</var> is used as the method object for <var>ToXPathString</var>:
<p class="code"><nowiki><a>
<p class="code"><nowiki><a>
   <?p1?>
   <?p1?>
Line 67: Line 45:
</a></nowiki>
</a></nowiki>
</p>
</p>
 
When applied to the above document, the following table shows the strings returned for each of various <var>ToXPathString</var> arguments. Notice that the last two arguments produce strings that include prefix/URI substrings.
The following table shows the strings returned for each of various
<p class="output"><nowiki>
<var>ToXPathString</var> arguments.
Notice that the last two arguments produce strings that include prefix/URI substrings.
<p class="code"><nowiki>
Argument:                      Returned string:
Argument:                      Returned string:
-----------------------------  ---------------------------
-----------------------------  ---------------------------
Line 85: Line 60:
</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><i>selectionXpath</i> is invalid.
<li><var class="term">selectionXpath</var> expression is invalid.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>
==See also==
==See also==
{{Template:XmlDoc/XmlNode:ToXPathString footer}}
{{Template:XmlDoc/XmlNode:ToXPathString footer}}

Latest revision as of 20:59, 19 February 2015

XPath expression for selected node (XmlDoc and XmlNode classes)

ToXPathString returns, in a string, an absolute XPath expression that identifies the node that a given XPath expression actually selects. ToXPathString 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 (ToXPathStringlist is a synonym for XPathNodeID). ToXPathString lets SirFact, Janus Debugger, and Sirius Debugger users extract XPath information when needed. The XPathNodeID method does not work in those environments because of its object (Stringlist) output.

Syntax

%string = nr:ToXPathString[( [selectionXpath])] Throws XPathError

Syntax terms

%string A string or Longstring that identifies 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 is an EBCDIC string.

Usage notes

  • If the absolute XPath expression returned by ToXPathString contains no prefixes, the string %string 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 contains an additional pair of blank-delimited substrings for each such URI (a substring for the associated prefix, then a substring 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, ToXPathString 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.

  • ToXPathString is available in Sirius Mods Version 7.3 and later.

Examples

The following document contained in an XmlDoc is used as the method object for ToXPathString:

<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 strings returned for each of various ToXPathString arguments. Notice that the last two arguments produce strings that include prefix/URI substrings.

Argument: Returned string: ----------------------------- --------------------------- */* /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 x u:a */*[2]/*[2] /a/x:a/_xpID.00:y 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.

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

See also