ToXPathString (XmlDoc/XmlNode function): Difference between revisions
m (1 revision) |
m (1 revision) |
||
| Line 10: | Line 10: | ||
<var>ToXPathString</var> is the same as <var>[[XPathNodeID (XmlDoc/XmlNode function)|XPathNodeID]]</var> | <var>ToXPathString</var> is the same as <var>[[XPathNodeID (XmlDoc/XmlNode function)|XPathNodeID]]</var> | ||
except its output is a string instead of a Stringlist | except its output is a string instead of a <var>Stringlist</var> | ||
(<var>ToXPathStringlist</var> is a synonym for <var>XPathNodeID</var>). | (<var>ToXPathStringlist</var> is a synonym for <var>XPathNodeID</var>). | ||
<var>ToXPathString</var> lets | <var>ToXPathString</var> lets | ||
[[SirFact]], [[Janus Debugger]], and [[Sirius Debugger]] users extract XPath information when needed. | [[SirFact]], [[Janus Debugger]], and [[Sirius Debugger]] users extract XPath information when needed. | ||
The XPathNodeID method does not work in those environments because of its | The XPathNodeID method does not work in those environments because of its | ||
object (Stringlist) output. | object (<var>Stringlist</var>) output. | ||
<var>ToXPathString</var> is new as of version 7.3 of the ''Sirius Mods''. | <var>ToXPathString</var> is new as of version 7.3 of the ''Sirius Mods''. | ||
| Line 25: | Line 25: | ||
<td>A string or longstring that identifies the node identified by ''selectionXpath''. </td></tr> | <td>A string or longstring that identifies the node identified by ''selectionXpath''. </td></tr> | ||
<tr><th>nr</th> | <tr><th>nr</th> | ||
<td>An XmlDoc or XmlNode, used as the context node for the <i>selectionXpath</i> expression. If an XmlDoc, 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 <i>selectionXpath</i> expression. If an <var>XmlDoc</var>, the Root node is the context node. </td></tr> | ||
<tr><th>selectionXpath</th> | <tr><th>selectionXpath</th> | ||
<td>A Unicode 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 expression that selects a node from the method object. Prior to ''Sirius Mods'' 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 ToXPathString | <li>If the absolute XPath expression returned by <var>ToXPathString</var> | ||
contains no prefixes, the string ''%str'' | contains no prefixes, the string ''%str'' | ||
contains only one item: the expression. | contains only one item: the expression. | ||
| Line 43: | Line 43: | ||
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 | or if a single prefix in the document | ||
is used for two different URIs, ToXPathString generates an "invented" prefix. | is used for two different URIs, <var>ToXPathString</var> generates an "invented" prefix. | ||
Such a prefix is generated | Such a prefix is generated | ||
because an XPath expression requires a prefix if it names an element | because an XPath expression requires a prefix if it names an element | ||
| Line 52: | Line 52: | ||
===Example=== | ===Example=== | ||
The following document contained in an XmlDoc is used as the | The following document contained in an <var>XmlDoc</var> is used as the | ||
method object for ToXPathString: | method object for <var>ToXPathString</var>: | ||
<p class="code"><a> | <p class="code"><a> | ||
<?p1?> | <?p1?> | ||
| Line 69: | Line 69: | ||
The following table shows the strings returned for each of various | The following table shows the strings returned for each of various | ||
ToXPathString arguments. | <var>ToXPathString</var> arguments. | ||
Notice that the last two arguments produce strings that include prefix/URI substrings. | Notice that the last two arguments produce strings that include prefix/URI substrings. | ||
<p class="code">:hp2 color=black. | <p class="code">:hp2 color=black. | ||
Revision as of 17:46, 25 January 2011
XPath expression for selected node (XmlDoc and XmlNode classes)
This function 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.
ToXPathString is new as of version 7.3 of the Sirius Mods.
Syntax
%string = nr:ToXPathString[( [selectionXpath])] Throws XPathError
Syntax terms
| %str | 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 selects a node from the method object. 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 %str 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.
Example
The following document contained in an XmlDoc is used as the method object for ToXPathString:
<a> <?p1?> <c n="1"/> <c n="2"/> <?p2?> <x:a xmlns:x="u:a"> <x:b/> <y xmlns="u:c"/> </x:a> </a>
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.
:hp2 color=black. Argument: Returned string:
---------------------------
/ /
Request-Cancellation Errors
- selectionXpath is invalid.
- Insufficient free space exists in CCATEMP.