AddNamespace (XmlNode subroutine)

From m204wiki
Revision as of 19:26, 20 April 2011 by Dme (talk | contribs)
Jump to navigation Jump to search

Add namespace declaration to Element node (XmlNode class)

[Requires Janus SOAP]


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.
  • /div>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 an attribute with the same prefix if the attribute's URI differs from the AddNamespace URI.
      • Prior to version 7.7, a namespace declaration may not be added to an Element that has Element children. See the "Namespace conflict" example below.
      • Starting with version 7.7, this restriction does not apply when a non-default namespace declaration is being added to the top-level Element of the XmlDoc. See the "Add to top element" example below.
      • Starting with version 7.9, a default namespace declaration can be added to a prefixed Element if all of its Element children themselves have default namespace declarations. See the "Add default namespace" example below.
  • 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

Add namespace to "leaf" element

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/

Namespace conflict

As mentioned in one of the Usage notes above, AddNamespace may not be used to change the namespace of an existing node in the XmlDoc. Here is an example which shows the result of such an attempt:

%top = %doc:AddElement('p1:top', , 'u:p1') %lev2 = %top:AddElement('p2:lev2', , 'u:p2') %lev2:AddElement('p1:lev3') %doc:Print %lev2:AddNamespace('p1', 'u:p3')

The result of the above fragment is:

<p1:top xmlns:p1="u:p1"> <p2:lev2 xmlns:p2="u:p2"> <p1:lev3/> </p2:lev2> </p1:top> *** 1 CANCELLING REQUEST: MSIR.0750: Class XmlNode, subroutine AddNamespace: can't expose descendants to new non-default namespace in line ...

Add to top element

Add default namespace

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