SelectionNamespace (XmlDoc property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:XmlDoc:SelectionNamespace subtitle}}
{{Template:XmlDoc:SelectionNamespace subtitle}}
<var>SelectionNamespace</var> indicates the value of the namespace <var>URI</var> associated with a prefix, when the prefix is used in an <var>[[XML processing in Janus SOAP#XML Path Language (XPath) in the XmlDoc API|XPath]]</var> expression.
<var>SelectionNamespace</var> indicates the value of the namespace URI associated with a prefix, when the prefix is used in an [[XML processing in Janus SOAP#XML Path Language (XPath) in the XmlDoc API|XPath]] expression.


==Syntax==
==Syntax==
Line 11: Line 11:
<td>An <var>XmlDoc</var> expression.</td></tr>
<td>An <var>XmlDoc</var> expression.</td></tr>
<tr><th>prefix</th>
<tr><th>prefix</th>
<td>The prefix to be used in <var>XPath</var> expressions. This is a <var>Unicode</var> string argument; prior to <var class="product">"Sirius Mods"</var> Version 7.6, this is an EBCDIC string. </td></tr>
<td>The prefix to be used in XPath expressions. This is a <var>Unicode</var> string argument; prior to <var class="product">Sirius Mods</var> Version 7.6, this is an EBCDIC string. </td></tr>
<tr><th>newUnicode</th>
<tr><th>newUnicode</th>
<td>The namespace absolute URI to associate with <var class="term">prefix</var>, or the null string, if the <var class="term">prefix</var> is not associated with the URI of a namespace. This is a <var>Unicode</var> string argument; prior to <var class="product">"Sirius Mods"</var> Version 7.6, this is an EBCDIC string. </td></tr>
<td>The namespace absolute URI to associate with <var class="term">prefix</var>, or the null string, if the <var class="term">prefix</var> is not associated with the URI of a namespace. This is a <var>Unicode</var> string argument; 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>When you use a name in an <var>XPath</var> expression to select an element or attribute in an <var>XmlDoc</var>, you locate only elements or attributes whose <var>LocalName</var> and <var>URI</var> match the <var>XPath</var> name.  You use  <var>SelectionNamespace</var> to specify a prefix you can use for the name in your <var>XPath</var> expression to identify the <var>URI</var> of the element or attribute you are trying to locate.
<li>When you use a name in an XPath expression to select an element or attribute in an <var>XmlDoc</var>, you locate only elements or attributes whose <var>LocalName</var> and <var>URI</var> values match the XPath name.  You use  <var>SelectionNamespace</var> to specify a prefix you can use for the name in your XPath expression to identify the URI of the element or attribute you are trying to locate.
<p><b>Note</b> Your <var>XPath</var> expression need not use a prefix if the element or attribute name to be matched does not have a <var>URI</var>.  However, if an element or attribute name you want to match has a prefix, you cannot select the element or attribute by prefix and name ''until the prefix is defined via the <var>SelectionNamespace</var> method''.</p>
<p class="note"><b>Note:</b> Your XPath expression need not use a prefix if the element or attribute name to be matched does not have a URI.  However, if an element or attribute name you want to match has a prefix, you cannot select the element or attribute by prefix and name ''until the prefix is defined via the <var>SelectionNamespace</var> method''.</p>
<li>An element (but not an attribute) name with no prefix may still have a <var>URI</var>.  Such an element may have an in-scope "default namespace declaration" (see [[XML_processing_in_Janus_SOAP#Name_and_namespace_syntax|"Names and namespace syntax"]]).  To locate this element by name with an <var>XPath</var> expression, you must use <var>SelectionNamespace</var> to associate a prefix with the <var>URI</var> of the element name, and use the prefix and local name of the element in the <var>XPath</var> expression.
 
<li>An element (but not an attribute) name with no prefix may still have a URI.  Such an element may have an in-scope "default namespace declaration" (see [[XML_processing_in_Janus_SOAP#Name_and_namespace_syntax|"Names and namespace syntax"]]).  To locate this element by name with an XPath expression, you must use <var>SelectionNamespace</var> to associate a prefix with the <var>URI</var> of the element name, and use the prefix and local name of the element in the XPath expression.
 
<li>All well-formed <var>XmlDoc</var>s implicitly include this namespace declaration in scope at the top-level document element:
<li>All well-formed <var>XmlDoc</var>s implicitly include this namespace declaration in scope at the top-level document element:
<p class="code">xmlns:xml="http://www.w3.org/XML/1998/namespace"
<p class="code">xmlns:xml="http://www.w3.org/XML/1998/namespace"
Line 27: Line 29:
<ul>
<ul>
<li>Use any other "xml" prefixed element or attribute names
<li>Use any other "xml" prefixed element or attribute names
<li>Add a namespace declaration (see [[AddNamespace (XmlNode subroutine)|AddNameSpace]]) for the "xml" prefix for a URI other than <nowiki>"http://www.w3.org/xml/1998/namespace".</nowiki>
<li>Add a namespace declaration (see <var>[[AddNamespace (XmlNode subroutine)|AddNameSpace]]</var>) for the "xml" prefix for a URI other than <nowiki>"http://www.w3.org/xml/1998/namespace".</nowiki>
<li>Add a namespace declaration for <nowiki>"http://www.w3.org/xml/1998/namespace"</nowiki> that has any other prefix besides "xml"
<li>Add a namespace declaration for <nowiki>"http://www.w3.org/xml/1998/namespace"</nowiki> that has any other prefix besides "xml"
</ul>
</ul>
The URI <nowiki>"http://www.w3.org/xml/1998/namespace"</nowiki> is the value of <var>SelectionNamespace</var> if "xml" is the method argument.
The URI <nowiki>"http://www.w3.org/xml/1998/namespace"</nowiki> is the value of <var>SelectionNamespace</var> if "xml" is the method argument.
<li>Prior to <var class="product">[[Sirius Mods]]</var> Version 7.0, if the <var>URI</var> associated with a prefix is the null string, that prefix cannot be used in an <var>XPath</var> expression.  The <var class="product">"Sirius Mods"</var> Version 7.0 (and later) interpretation of a null-string setting (null string means "no namespace") is a Sirius extension to the <var>XPath</var> recommendation.
 
<li>The initial <var>URI</var> associated with any prefix is the null string. Therefore, prior to <var class="product">"Sirius Mods"</var> Version 7.0, you had to set the <var>SelectionNamespace</var> property for ''any'' prefix to a non-null string before it could be used in an <var>XPath</var> expression.  For <var class="product">"Sirius Mods"</var> Version 7.0, and later, you have to set the <var>SelectionNamespace</var> property for any prefix ''that is associated with a namespace URI''.
<li>Prior to <var class="product">Sirius Mods</var> Version 7.0, if the <var>URI</var> associated with a prefix is the null string, that prefix cannot be used in an XPath expression.  The <var class="product">Sirius Mods</var> Version 7.0 (and later) interpretation of a null-string setting (null string means "no namespace") is a Sirius extension to the XPath recommendation.
 
<li>The initial <var>URI</var> associated with any prefix is the null string. Therefore, prior to <var class="product">Sirius Mods</var> Version 7.0, you had to set the <var>SelectionNamespace</var> property for ''any'' prefix to a non-null string before it could be used in an XPath expression.  For <var class="product">Sirius Mods</var> Version 7.0, and later, you have to set the <var>SelectionNamespace</var> property for any prefix ''that is associated with a namespace URI''.
</ul>
</ul>


==Examples==
==Examples==
<ol><li>
In the following example, the <var>SelectionNamespace</var> setting associates
In the following example, the <var>SelectionNamespace</var> setting associates
the prefix "SOAP" with its URI, enabling the use of that prefix
the prefix "SOAP" with its URI, enabling the use of that prefix
later in the XPath expression in the SelectSingleNode method invocation.
later in the XPath expression in the <var>[[SelectSingleNode_(XmlDoc/XmlNode_function)|SelectSingleNode]]</var> method invocation.
A subsequent invocation of <var>SelectionNamespace</var> returns the URI
A subsequent invocation of <var>SelectionNamespace</var> returns the URI
currently associated with the specified prefix.
currently associated with the specified prefix.
Line 51: Line 54:
       <nowiki>'http://SCHEMAS.XMLSOAP.ORG/soap/'</nowiki>
       <nowiki>'http://SCHEMAS.XMLSOAP.ORG/soap/'</nowiki>
   %n1 is object xmlNode
   %n1 is object xmlNode
   %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a/SOAP:b')
   %n1 = %doc:electSingleNode('top/a/SOAP:b')
   [[Notation_conventions_for_methods#Callable_methods|Call]] %n1:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('c')
   [[Notation_conventions_for_methods#Callable_methods|Call]] %n1:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('c')
   call %doc:print
   call %doc:print
Line 70: Line 73:
The URI of node SOAP:b is: <nowiki>http://SCHEMAS.XMLSOAP.ORG/soap/</nowiki>
The URI of node SOAP:b is: <nowiki>http://SCHEMAS.XMLSOAP.ORG/soap/</nowiki>
The URI for SOAP as an XPath prefix is: <nowiki>http://SCHEMAS.XMLSOAP.ORG/soap/</nowiki>
The URI for SOAP as an XPath prefix is: <nowiki>http://SCHEMAS.XMLSOAP.ORG/soap/</nowiki>
</p></ol>
</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">Prefix</var> is not a valid name prefix.
<li>Argument <var class="term">prefix</var> is not a valid name prefix.
<li>Argument <var class="term">newUniCode</var> is not a valid absolute Uniform Resource Identifier.
<li>Argument <var class="term">newUniCode</var> is not a valid absolute Uniform Resource Identifier.
</ul>
</ul>

Latest revision as of 21:04, 3 March 2014

Bind prefix to URI (or null) for XPath (XmlDoc class)

SelectionNamespace indicates the value of the namespace URI associated with a prefix, when the prefix is used in an XPath expression.

Syntax

%currentUnicode = doc:SelectionNamespace( prefix) doc:SelectionNamespace( prefix) = newUnicode

Syntax terms

%currentUnicode A Unicode string %variable, set to the namespace URI associated with prefix. Prior to Sirius Mods Version 7.6, this is an EBCDIC string.
doc An XmlDoc expression.
prefix The prefix to be used in XPath expressions. This is a Unicode string argument; prior to Sirius Mods Version 7.6, this is an EBCDIC string.
newUnicode The namespace absolute URI to associate with prefix, or the null string, if the prefix is not associated with the URI of a namespace. This is a Unicode string argument; prior to Sirius Mods Version 7.6, this is an EBCDIC string.

Usage notes

  • When you use a name in an XPath expression to select an element or attribute in an XmlDoc, you locate only elements or attributes whose LocalName and URI values match the XPath name. You use SelectionNamespace to specify a prefix you can use for the name in your XPath expression to identify the URI of the element or attribute you are trying to locate.

    Note: Your XPath expression need not use a prefix if the element or attribute name to be matched does not have a URI. However, if an element or attribute name you want to match has a prefix, you cannot select the element or attribute by prefix and name until the prefix is defined via the SelectionNamespace method.

  • An element (but not an attribute) name with no prefix may still have a URI. Such an element may have an in-scope "default namespace declaration" (see "Names and namespace syntax"). To locate this element by name with an XPath expression, you must use SelectionNamespace to associate a prefix with the URI of the element name, and use the prefix and local name of the element in the XPath expression.
  • All well-formed XmlDocs implicitly include this namespace declaration in scope at the top-level document element:

    xmlns:xml="http://www.w3.org/XML/1998/namespace"

    The "xml" prefix is currently valid only for the special attributes xml:space and xml:lang. You are not allowed to:

    • Use any other "xml" prefixed element or attribute names
    • Add a namespace declaration (see AddNameSpace) for the "xml" prefix for a URI other than "http://www.w3.org/xml/1998/namespace".
    • Add a namespace declaration for "http://www.w3.org/xml/1998/namespace" that has any other prefix besides "xml"

    The URI "http://www.w3.org/xml/1998/namespace" is the value of SelectionNamespace if "xml" is the method argument.

  • Prior to Sirius Mods Version 7.0, if the URI associated with a prefix is the null string, that prefix cannot be used in an XPath expression. The Sirius Mods Version 7.0 (and later) interpretation of a null-string setting (null string means "no namespace") is a Sirius extension to the XPath recommendation.
  • The initial URI associated with any prefix is the null string. Therefore, prior to Sirius Mods Version 7.0, you had to set the SelectionNamespace property for any prefix to a non-null string before it could be used in an XPath expression. For Sirius Mods Version 7.0, and later, you have to set the SelectionNamespace property for any prefix that is associated with a namespace URI.

Examples

In the following example, the SelectionNamespace setting associates the prefix "SOAP" with its URI, enabling the use of that prefix later in the XPath expression in the SelectSingleNode method invocation. A subsequent invocation of SelectionNamespace returns the URI currently associated with the specified prefix.

begin %doc is object xmlDoc %doc = new %doc:loadXml('<top - xmlns:SOAP="http://SCHEMAS.XMLSOAP.ORG/soap/"> - <a><SOAP:b></SOAP:b></a></top>') %doc:selectionNamespace('SOAP')= - 'http://SCHEMAS.XMLSOAP.ORG/soap/' %n1 is object xmlNode %n1 = %doc:electSingleNode('top/a/SOAP:b') Call %n1:addElement('c') call %doc:print print 'The URI of node SOAP:b is: ' %n1:URI print 'The URI for SOAP as an XPath prefix is:' and - %doc:SelectionNamespace('SOAP') end

The example result follows:

<top xmlns:SOAP="http://SCHEMAS.XMLSOAP.ORG/soap/"> <a> <SOAP:b> <c/> </SOAP:b> </a> </top> The URI of node SOAP:b is: http://SCHEMAS.XMLSOAP.ORG/soap/ The URI for SOAP as an XPath prefix is: http://SCHEMAS.XMLSOAP.ORG/soap/

Request-cancellation errors

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

  • Argument prefix is not a valid name prefix.
  • Argument newUniCode is not a valid absolute Uniform Resource Identifier.

See also