AddNamespace (XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Add namespace declaration to Element XmlNode</b></span>
{{Template:XmlNode:AddNamespace subtitle}}
[[Category:XmlNode methods|AddNamespace subroutine]]
[[Category:XmlNode methods|AddNamespace subroutine]]
[[Category:XmlDoc API methods]]
[[Category:XmlDoc API methods]]
Line 11: Line 11:
This subroutine adds a namespace declaration to an Element node.
This subroutine adds a namespace declaration to an Element node.


===Syntax===
==Syntax==
  Call nod:AddNamespace(prefix, URI)
{{Template:XmlNode:AddNamespace syntax}}
 
===Syntax terms===
====Syntax Terms====
<dl>
<dl>
<dt>nod
<dt>nod
Line 30: Line 29:
</dl>
</dl>


===Usage Notes===
==Usage notes==
<ul>
<ul>
<li>If a URI argument is specified, the XmlDoc's [[Namespace (XmlDoc property)|Namespace]] property must be <tt>On</tt>.
<li>If a URI argument is specified, the XmlDoc's [[Namespace (XmlDoc property)|Namespace]] property must be <tt>On</tt>.
Line 61: Line 60:
     xmlns:xml="http://www.w3.org/XML/1998/namespace"
     xmlns:xml="http://www.w3.org/XML/1998/namespace"
</pre>
</pre>
The &ldquo;xml&rdquo; prefix is currently valid only for the special attributes
The "xml" prefix is currently valid only for the special attributes
<tt>xml:space</tt> and <tt>xml:lang</tt>.
<tt>xml:space</tt> and <tt>xml:lang</tt>.
You are ''not'' allowed to:
You are ''not'' allowed to:
<ul>
<ul>
<li>Use any other &ldquo;xml&rdquo; prefixed element or attribute names
<li>Use any other "xml" prefixed element or attribute names
<li>Add a namespace declaration
<li>Add a namespace declaration
for the &ldquo;xml&rdquo; prefix
for the "xml" prefix
for a URI other than <nowiki>"http://www.w3.org/xml/1998/namespace"</nowiki>;
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>
<li>Add a namespace declaration for <nowiki>"http://www.w3.org/xml/1998/namespace"</nowiki>
that has any other prefix besides &ldquo;xml&rdquo;
that has any other prefix besides "xml"
</ul>
</ul>
</ul>
</ul>

Revision as of 16:58, 22 January 2011

Add namespace declaration to Element node (XmlNode class)

[Requires Janus SOAP]

AddNamespace is a member of the XmlNode class.

This subroutine adds a namespace declaration to an Element node.

Syntax

nod:AddNamespace( prefix, uri)

Syntax terms

nod
An XmlNode that points to the Element node where the namespace declaration is added.
prefix
The prefix that is being declared. It must conform to the XML syntax rules for a namespace prefix; the maximum length of the prefix is 127 characters (100 characters prior to version 7.7 of Janus SOAP).
URI
An absolute Uniform Resource Identifier, identifying the namespace the prefix is declared within.

Usage notes

  • If a URI argument is specified, the XmlDoc's Namespace property must be On.
  • As of Sirius Mods version 7.3, the AddNamespace method arguments may include only non-null EBCDIC characters that translate to Unicode. As of Sirius Mods version 7.6, these argument strings are Unicode or are converted to Unicode. For more information about the effects of this version 7.6 change, see Strings and Unicode with the XmlDoc API.
  • Namespace declarations are serialized in the order in which they are added.
  • Adding the same declaration multiple times on an element is allowed.
  • To ensure that URIs of already added nodes are preserved:
    • A namespace declaration may not be added to an Element that has the same prefix (including no prefix, in the case of the default namespace declaration) if the Element's URI differs from the AddNamespace URI.
    • A namespace declaration may not be added to an Element that has the same prefix if the Element's URI differs from any of the Element's attributes.
    • A namespace declaration may not be added to an Element that has Element children. As of Sirius Mods version 7.7, this restriction does not apply to the top-level Element of a subtree.
  • 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 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"

Example

In the following example, the AddNamespace method adds a namespace to a node that has an existing namespace. Subsequent elements are added to that node using each of the eligible namespace prefixes.

    Begin
    %doc is Object XmlDoc
    %doc = New
    %doc:LoadXml('<top   -
       xmlns:SOAP="http://SCHEMAS.XMLSOAP.ORG/soap/">  -
       <a><SOAP:b></SOAP:b></a></top>')
    %n1 is Object XmlNode
    %n2 is Object XmlNode
    %n3 is Object XmlNode
    %n1 = %doc:SelectSingleNode('top/*/*')
    Call %n1:AddNamespace('sirius', 'http://sirius-software.com')
    Print 'The URI of node SOAP:b is: ' %n1:URI
    %n2 = %n1:AddElement('sirius:c')
    %n3 = %n1:AddElement('SOAP:c')
    Call %doc:Print
    Print 'The URI of node sirius:c is: ' %n2:URI
    Print 'The URI of node SOAP:c is: ' %n3:URI
    End

The example result follows:

    The URI of node SOAP:b is: http://SCHEMAS.XMLSOAP.ORG/soap/
    <top xmlns:SOAP="http://SCHEMAS.XMLSOAP.ORG/soap/">
       <a>
          <SOAP:b xmlns:sirius="http://sirius-software.com">
             <sirius:c/>
             <SOAP:c/>
          </SOAP:b>
       </a>
    </top>
    The URI of node sirius:c is: http://sirius-software.com
    The URI of node SOAP:c is: http://SCHEMAS.XMLSOAP.ORG/soap/

Request-Cancellation Errors

  • Nod does not point to an Element node.
  • Element pointed to by nod contains one or more child Element nodes.
  • Prefix is an invalid prefix.
  • URI is an invalid URI.
  • Prefix is the same as the prefix of the Element that nod points to, but URI is different from the namespace URI of the Element.
  • A declaration for the same prefix with a different URI is already present (not merely in scope) at the Element pointed to by nod.
  • The XmlDoc's Namespace property is not On.

See Also