Difference between revisions of "InsertElementBefore (XmlNode function)"

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (minor formatting)
 
(26 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
{{Template:XmlNode:InsertElementBefore subtitle}}
 
{{Template:XmlNode:InsertElementBefore subtitle}}
 +
The <var>InsertElementBefore</var> [[Notation_conventions_for_methods#Callable_methods|callable]] function inserts an [[XmlDoc API#XmlDoc node types|Element node]] as the sibling immediately preceding the method <var>XmlNode</var>.  <var>InsertElementBefore</var> also lets you add a <var>Text</var> node as the child of the inserted  <var>Element</var>, and it lets you specify the namespace URI for the inserted element.
  
This callable function inserts an Element node as the
 
sibling immediately preceding the method <var>XmlNode</var>.
 
<var>InsertElementBefore</var> also lets you add a Text node as the child of the inserted
 
Element, and it lets you specify the namespace URI for the inserted element.
 
 
==Syntax==
 
==Syntax==
 
{{Template:XmlNode:InsertElementBefore syntax}}
 
{{Template:XmlNode:InsertElementBefore syntax}}
 +
 
===Syntax terms===
 
===Syntax terms===
 
<table class="syntaxTable">
 
<table class="syntaxTable">
<tr><th>%nod</th>
+
<tr><th nowrap>%outNod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the Element node that is inserted. </td></tr>
+
<td>If specified, an <var>XmlNode</var> that is set to point to the <var>Element</var> node that is inserted.</td></tr>
 
<tr><th>nod</th>
 
<tr><th>nod</th>
<td><var>XmlNode</var> that points to the (non-Root) node before which the Element node is inserted. </td></tr>
+
<td><var>XmlNode</var> that points to the (non-Root) node before which the <var>Element</var> node is inserted.</td></tr>
 
<tr><th>name</th>
 
<tr><th>name</th>
<td>A <var>Unicode</var> string that is the name of the inserted Element; if prefixed, the prefix must be declared, or a <i>URI</i> argument must be provided. The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 127 characters (100 characters prior to version 7.7 of [[Janus SOAP]]). </td></tr>
+
<td>A <var>Unicode</var> string that is the name of the inserted <var>Element</var>; if prefixed, the prefix must be declared, or a <var class="term">uri</var> argument must be provided.<p>The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 300 characters (127 characters prior to <var class="product">[[Sirius Mods]]</var> Version 7.9, and 100 characters prior to Version 7.7).</p></td></tr>
 
<tr><th>value</th>
 
<tr><th>value</th>
<td>This optional argument is the content of a Text node that is added as a child of the inserted element. This <var>Unicode</var> string content is stored without any normalization, entity substitution, etc.
+
<td>This optional argument is the content of a <var>Text</var> node that is added as a child of the inserted element. This <var>Unicode</var> string content is stored without any normalization, entity substitution, etc.<p>Since <var>Text</var> nodes cannot contain the null string, this argument is ignored if it is the null string.</p></td></tr>
<p class="code">Since Text nodes cannot contain the null string, this argument is ignored if it is the null string. </td></tr>
 
</p>
 
 
<tr><th>URI</th>
 
<tr><th>URI</th>
 
<td>This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See "Usage Notes," below.</td></tr>
 
<td>This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See "Usage Notes," below.</td></tr>
Line 25: Line 21:
 
==Usage notes==
 
==Usage notes==
 
<ul>
 
<ul>
<li>If a <i>URI</i> argument is specified, the <var>XmlDoc</var>'s Namespace property
+
<li>If a <var class="term">uri</var> argument is specified, the <var>XmlDoc</var>'s <var>[[Namespace (XmlDoc property)|Namespace ]]</var> property value must be <var>On</var>, and <var class="term">uri</var> must either be the null string, or it must have the format of an absolute URI. The effect depends on whether the <var class="term">name</var> value includes a prefix:
must be <tt>On</tt>, and <i>URI</i> must either
 
be the null string, or it must have the format of an absolute URI.
 
The effect depends on whether the <i>name</i> value includes
 
a prefix:
 
 
<ul>
 
<ul>
<li>If <i>name</i> has a prefix, <i>URI</i> must '''not''' be
+
<li>If <var class="term">name</var> has a prefix, <var class="term">uri</var> must '''not''' be the null string, and <var class="term">uri</var> is the declared namespace URI associated with that prefix and added element. </li>
the null string, and <i>URI</i> is the declared namespace URI
+
 
associated with that prefix and added element.
+
<li>If <var class="term">name</var> does not have a prefix:
<li>If <i>name</i> does not have a prefix:
 
 
<ul>
 
<ul>
<li>If <i>URI</i> is the null string,
+
<li>If <var class="term">uri</var> is the null string, the added element does not have a default namespace. Any in-scope default namespace the added element might have inherited, is not inherited. </li>
the added element does not have a default namespace.
+
<li>If <var class="term">uri</var> is '''not''' the null string, the added element has <var class="term">uri</var> as the default namespace. </li>
Any in-scope default namespace the added element might have inherited,
+
</ul></li>
is not inherited.
 
<li>If <i>URI</i> is '''not''' the null string,
 
the added element has <i>URI</i> as the default namespace.
 
</ul>
 
 
</ul>
 
</ul>
 +
If a non-null string <var class="term">uri</var> argument is provided, and the namespace declaration resulting from it is not in scope for the added element, then a namespace declaration is added at that element. </li>
  
If a non-null string <i>URI</i> argument is provided, and the namespace
+
<li>If the <var class="term">uri</var> argument is '''not''' present, the added element's namespace is determined by the prefix and in-scope declarations:
declaration resulting from it is not in scope for the added element, then
 
a namespace declaration is added at that element.
 
<li>If the <i>URI</i> argument is '''not''' present, the added element's namespace
 
is determined by the prefix and in-scope declarations:
 
 
<ul>
 
<ul>
<li>If the <i>name</i> is prefixed, the namespace is given by the
+
<li>If the <var class="term">name</var> is prefixed, the namespace is given by the in-scope declaration of the prefix. </li>
in-scope declaration of the prefix.
+
 
<li>If the <i>name</i> has no prefix, the namespace is
+
<li>If the <var class="term">name</var> has no prefix, the namespace is the default namespace, if any, in scope. If there is no default namespace in scope, the added element has no namespace. </li>
the default namespace, if any, in scope.
+
</ul></li>
If there is no default namespace in scope, the added element has
+
 
no namespace.
+
<li>The <var>InsertElementBefore</var> method arguments may include only non-null EBCDIC characters that translate to Unicode.  As of <var class="product">Sirius Mods</var> 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 [[XmlDoc API#Strings and Unicode with the XmlDoc API|Strings and Unicode with the Xml API]]. </li>
</ul>
+
 
<li>As of ''Sirius Mods'' version 7.3, the <var>InsertElementBefore</var> method arguments may
+
<li>When the return value of <var>InsertElementBefore</var> is not needed, you may want to <var>Call</var> it instead of saving its return value; the return value is typically needed only to add <var>Attributes</var> or non-<var>Text</var> children of the <var>Element</var>. </li>
include only non-null EBCDIC characters that translate to <var>Unicode</var>.
+
 
As of ''Sirius Mods'' version 7.6, these argument strings are <var>Unicode</var> or are
+
<li>There is a very small "one-time" processing cost if [[XPath#ordScan|certain Xpath expression]] operations are performed after using this method, because "Insert-Before" methods are guaranteed to add a node out of document order. In general, processing an <var>XmlDoc</var> is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right). </li>
converted to <var>Unicode</var>.
 
For more information about the effects of this version 7.6
 
change, see [[Strings and Unicode]].
 
<li>When the return value of <var>InsertElementBefore</var> is not needed,
 
you may want to Call it instead of saving its return value;
 
the return value is typically needed only
 
to add attributes or non-Text children of the Element.
 
<li>There is a very small "one-time" processing cost
 
if certain XPath operations are performed after using this method, because
 
Insert-Before methods are guaranteed to add a node out of document order.
 
In general, processing an <var>XmlDoc</var> is likely to be more efficient if
 
you add nodes in document order (that is, top-to-bottom, left-to-right).
 
 
</ul>
 
</ul>
  
===Example===
+
==Examples==
 
+
<ol><li>In the following example, an element node with text is inserted as a sibling before node "b". An <var>AddElement</var> call then adds a child node to the parent of "b", and this child becomes a sibling of "b" located after it.
In the following example, an element node with text is inserted as a sibling
+
<p class="code">begin
before node "b".
+
  %doc is object xmlDoc
An AddElement call then adds
+
  %doc = new
a child node to the parent of "b", and this child becomes
+
  [[Notation_conventions_for_methods#Callable_methods|call]] %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top><a><c/><nowiki><b>05</b></nowiki></a></top>')
a sibling of "b" located after it.
+
  %n1 is object xmlNode
<p class="code">Begin
+
  %n2 is object xmlNode
%doc is <var>Object</var> <var>XmlDoc</var>
+
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a/b')
%doc = New
+
  call %n1:insertElementBefore('d', 'This comes before')
Call %doc:LoadXml('<top><a><c/><b>05</b></a></top>')
+
  %n2 = %n1:selectSingleNode('..')
%n1 is <var>Object</var> <var>XmlNode</var>
+
  call %n2:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('e', 'This comes after')
%n2 is <var>Object</var> <var>XmlNode</var>
+
  call %doc:[[Print_(XmlDoc/XmlNode_subroutine)|print]]('top')
%n1 = %doc:SelectSingleNode('top/a/b')
+
end
Call %n1:<var>InsertElementBefore</var>('d', 'This comes before')
 
%n2 = %n1:SelectSingleNode('..')
 
Call %n2:AddElement('e', 'This comes after')
 
Call %doc:Print('top')
 
End
 
 
</p>
 
</p>
 
 
The example results follow:
 
The example results follow:
<p class="code"><top>
+
<p class="output"><top>
<p class="code"><a>
+
  <a>
  <c/>
+
      <c/>
  <d>This comes before</d>
+
      <d>This comes before</d>
  <b>05</b>
+
      <nowiki><b>05</b></nowiki>
  <e>This comes after</e>
+
      <e>This comes after</e>
</a>
+
  </a>
</p>
 
 
</top>
 
</top>
 
</p>
 
</p>
:note
+
<li>The following fragment shows a way to insert a sibling node ''after'' the current node in cases where the document contents are not well known:
The following fragment shows a way to
+
<p class="code">%nod2 = %nod1:selectSingleNode('following-sibling::node()')
insert a sibling node ''after'' the current node
+
if %nod2 is null Then
in cases where the document contents are not well known:
+
  %nod2 = %nod1:selectSingleNode('..')
<p class="code">%nod2 = %nod1:SelectSingleNode('following-sibling::node()')
+
  call %nod2:addElement('foo')
If %nod2 Is Null Then
+
else
<p class="code">%nod2 = %nod1:SelectSingleNode('..')
+
  call %nod2:insertElementBefore('foo')
Call %nod2:AddElement('foo')
+
end if
</p>
+
</p></ol>
Else
 
<p class="code">Call %nod2:<var>InsertElementBefore</var>('foo')
 
</p>
 
End If
 
</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><i>Nod</i> is the Root node.
+
<li>The <var class="term">nod</var> argument is the <var>Root</var> node. </li>
<li><i>Nod</i> is a child of
+
 
the Root node and <var>XmlDoc</var> already has an Element.
+
<li><var class="term">nod</var> is a child of the <var>Root</var> node and <var>XmlDoc</var> already has an <var>Element</var>. </li>
<li>Argument <i>name</i> violates the rules for an XML element name.
+
 
<li><i>Name</i> is prefixed, but the <var>XmlDoc</var> Namespace property
+
<li>The <var class="term">name</var> argument violates the rules for an XML element name. </li>
is None.
+
 
<li><i>Name</i> prefixed and Namespace On, but URI missing and no
+
<li><var class="term">name</var> is prefixed, but the <var>XmlDoc</var> <var>[[Namespace  (XmlDoc property)|Namespace]]</var> property value is <var>None</var>. </li>
declaration for prefix in scope.
+
 
<li><i>Value</i> violates the rules for an
+
<li><var class="term">name</var> is prefixed and <var>Namespace</var> property value is <var>On</var>, but <var class="term">uri</var> is missing and no declaration for prefix is in scope. </li>
XML element value (that is, it contains an invalid character).
+
 
Note that as of
+
<li>The <var class="term">value</var> argument violates the rules for an XML element value (that is, it contains an invalid character).
''Sirius Mods'' version 7.6, this check can no longer be bypassed using the InvalidChar
+
<p>
method &mdash; see [[InvalidChar (obsolete XmlDoc property)#Usage Notes|Usage Notes for the InvalidChar property]].
+
Note that as of <var class="product">Sirius Mods</var> version 7.6, this check can no longer be bypassed using the <var>[[InvalidChar_(XmlDoc_property)|InvalidChar]]</var> method &mdash; see [[InvalidChar (XmlDoc property)#Usage notes|Usage Notes for the InvalidChar property]]. </p></li>
<li><i>URI</i> is invalid.
+
 
<li><i>URI</i> is present, but the
+
<li>The <var class="term">uri</var> value is invalid. </li>
Namespace property is not <tt>On</tt>,
+
 
or, <i>URI</i> is the null string and <i>name</i> is prefixed.
+
<li><var class="term">uri</var> is present, but the <var>Namespace</var> value is not <var>On</var>, or <var class="term">uri</var> is the null string and <var class="term">name</var> is prefixed. </li>
<li>Insufficient free space exists in CCATEMP.
+
 
 +
<li>Insufficient free space exists in CCATEMP. </li>
 
</ul>
 
</ul>
  
 +
==See also==
 +
<ul>
 +
<li>For more information about namespace declarations, see [[XML processing in Janus SOAP#Names and namespaces|Names and namespaces]]. </li>
  
==See also==
+
<li>For more information about URIs, see [[XML processing in Janus SOAP#Uniform Resource Identifier syntax|Uniform Resource Identifier syntax]]. </li>
{{Template:XmlNode:InsertElementBefore footer}}
+
<li><var>[[AddElement (XmlDoc/XmlNode function)|AddElement]]</var> also adds an <var>Element</var> node.  <var>InsertElementBefore</var> adds an <var>Element</var> as the immediately preceding <em>sibling</em> of the node pointed to by the method object; <var>AddElement</var> adds an <var>Element</var> as the last <em>child</em> of the node pointed to by the method object. </li>
  
<ul>
 
<li>For more information about
 
namespace declarations, see [[??]] refid=namsp..
 
<li>For more information about URIs, see [[??]] refid=nsuri..
 
<li>[[AddElement (XmlDoc/XmlNode function)|AddElement]]
 
also adds an Element node.
 
<var>InsertElementBefore</var> adds an Element as the immediately preceding
 
sibling of the node pointed to by the method object;
 
AddElement adds an Element as the last child of the node pointed to by the
 
method object.
 
 
<li>These methods are useful for working with namespaces:
 
<li>These methods are useful for working with namespaces:
 
<ul>
 
<ul>
<li>[[AddNamespace (XmlNode subroutine)|AddNamespace]]
+
<li><var>[[AddNamespace (XmlNode subroutine)|AddNamespace]]</var> </li>
<li>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]
+
<li><var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var> </li>
</ul>
+
</ul></li>
 
</ul>
 
</ul>
 +
 +
{{Template:XmlNode:InsertElementBefore footer}}

Latest revision as of 20:05, 8 August 2018

Insert an Element before this node (XmlNode class)

[Requires Janus SOAP]

The InsertElementBefore callable function inserts an Element node as the sibling immediately preceding the method XmlNode. InsertElementBefore also lets you add a Text node as the child of the inserted Element, and it lets you specify the namespace URI for the inserted element.

Syntax

[%outNod =] nod:InsertElementBefore( name, [value], [uri])

Syntax terms

%outNod If specified, an XmlNode that is set to point to the Element node that is inserted.
nod XmlNode that points to the (non-Root) node before which the Element node is inserted.
name A Unicode string that is the name of the inserted Element; if prefixed, the prefix must be declared, or a uri argument must be provided.

The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 300 characters (127 characters prior to Sirius Mods Version 7.9, and 100 characters prior to Version 7.7).

value This optional argument is the content of a Text node that is added as a child of the inserted element. This Unicode string content is stored without any normalization, entity substitution, etc.

Since Text nodes cannot contain the null string, this argument is ignored if it is the null string.

URI This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See "Usage Notes," below.

Usage notes

  • If a uri argument is specified, the XmlDoc's Namespace property value must be On, and uri must either be the null string, or it must have the format of an absolute URI. The effect depends on whether the name value includes a prefix:
    • If name has a prefix, uri must not be the null string, and uri is the declared namespace URI associated with that prefix and added element.
    • If name does not have a prefix:
      • If uri is the null string, the added element does not have a default namespace. Any in-scope default namespace the added element might have inherited, is not inherited.
      • If uri is not the null string, the added element has uri as the default namespace.
    If a non-null string uri argument is provided, and the namespace declaration resulting from it is not in scope for the added element, then a namespace declaration is added at that element.
  • If the uri argument is not present, the added element's namespace is determined by the prefix and in-scope declarations:
    • If the name is prefixed, the namespace is given by the in-scope declaration of the prefix.
    • If the name has no prefix, the namespace is the default namespace, if any, in scope. If there is no default namespace in scope, the added element has no namespace.
  • The InsertElementBefore 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 Xml API.
  • When the return value of InsertElementBefore is not needed, you may want to Call it instead of saving its return value; the return value is typically needed only to add Attributes or non-Text children of the Element.
  • There is a very small "one-time" processing cost if certain Xpath expression operations are performed after using this method, because "Insert-Before" methods are guaranteed to add a node out of document order. In general, processing an XmlDoc is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).

Examples

  1. In the following example, an element node with text is inserted as a sibling before node "b". An AddElement call then adds a child node to the parent of "b", and this child becomes a sibling of "b" located after it.

    begin %doc is object xmlDoc %doc = new call %doc:loadXml('<top><a><c/><b>05</b></a></top>') %n1 is object xmlNode %n2 is object xmlNode %n1 = %doc:selectSingleNode('top/a/b') call %n1:insertElementBefore('d', 'This comes before') %n2 = %n1:selectSingleNode('..') call %n2:addElement('e', 'This comes after') call %doc:print('top') end

    The example results follow:

    <top> <a> <c/> <d>This comes before</d> <b>05</b> <e>This comes after</e> </a> </top>

  2. The following fragment shows a way to insert a sibling node after the current node in cases where the document contents are not well known:

    %nod2 = %nod1:selectSingleNode('following-sibling::node()') if %nod2 is null Then %nod2 = %nod1:selectSingleNode('..') call %nod2:addElement('foo') else call %nod2:insertElementBefore('foo') end if

Request-cancellation errors

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

  • The nod argument is the Root node.
  • nod is a child of the Root node and XmlDoc already has an Element.
  • The name argument violates the rules for an XML element name.
  • name is prefixed, but the XmlDoc Namespace property value is None.
  • name is prefixed and Namespace property value is On, but uri is missing and no declaration for prefix is in scope.
  • The value argument violates the rules for an XML element value (that is, it contains an invalid character).

    Note that as of Sirius Mods version 7.6, this check can no longer be bypassed using the InvalidChar method — see Usage Notes for the InvalidChar property.

  • The uri value is invalid.
  • uri is present, but the Namespace value is not On, or uri is the null string and name is prefixed.
  • Insufficient free space exists in CCATEMP.

See also

  • For more information about namespace declarations, see Names and namespaces.
  • For more information about URIs, see Uniform Resource Identifier syntax.
  • AddElement also adds an Element node. InsertElementBefore adds an Element as the immediately preceding sibling of the node pointed to by the method object; AddElement adds an Element as the last child of the node pointed to by the method object.
  • These methods are useful for working with namespaces: