SelectionNamespace (XmlDoc property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
Line 18: Line 18:
==Usage notes==
==Usage notes==
<ul>
<ul>
<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> 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 <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 XPath 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><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 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>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"

Revision as of 18:53, 6 June 2011

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

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

See also