InsertElementBefore (XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (minor formatting)
 
(6 intermediate revisions by 3 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 <var>Element</var> 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.
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.


==Syntax==
==Syntax==
{{Template:XmlNode:InsertElementBefore syntax}}
{{Template:XmlNode:InsertElementBefore syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outNod</th>
<tr><th nowrap>%outNod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the  <var>Element</var> 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>
Line 22: Line 23:
<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:
<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:
<ul>
<ul>
<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>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>
 
<li>If <var class="term">name</var> does not have a prefix:
<li>If <var class="term">name</var> does not have a prefix:
<ul>
<ul>
<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>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>
<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>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>
</ul></li>
</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 <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 the <var class="term">uri</var> argument is '''not''' present, the added element's namespace is determined by the prefix and in-scope declarations:
<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:
<ul>
<ul>
<li>If the <var class="term">name</var> is prefixed, the namespace is given by the in-scope declaration of the prefix.
<li>If the <var class="term">name</var> is prefixed, the namespace is given by the in-scope declaration of the prefix. </li>
<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.
 
</ul>
<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>
<li>As of <var class="product">Sirius Mods</var> Version 7.3, 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"]].
</ul></li>
<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>There is a very small "one-time" processing cost if certain [[XPath#XPath_syntax|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>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>
 
<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>
 
<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>
</ul>
</ul>


Line 56: Line 63:
</p>
</p>
The example results follow:
The example results follow:
<p class="code"><top>
<p class="output"><top>
   <a>
   <a>
       <c/>
       <c/>
Line 68: Line 75:
<p class="code">%nod2 = %nod1:selectSingleNode('following-sibling::node()')
<p class="code">%nod2 = %nod1:selectSingleNode('following-sibling::node()')
if %nod2 is null Then
if %nod2 is null Then
%nod2 = %nod1:aelectSingleNode('..')
  %nod2 = %nod1:selectSingleNode('..')
   call %nod2:addElement('foo')
   call %nod2:addElement('foo')
else
else
Line 76: Line 83:


==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>The <var class="term">nod</var> argument is the <var>Root</var> node.
<li>The <var class="term">nod</var> argument is the <var>Root</var> node. </li>
<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>The <var class="term">name</var> argument violates the rules for an XML element name.
<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><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><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>The <var class="term">name</var> argument violates the rules for an XML element name. </li>
<li>The <var class="term">value</var> argument violates the rules for an XML element value (that is, it contains an invalid character).<p>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>The <var class="term">uri</var> value is invalid.
<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>
<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><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>
<li>Insufficient free space exists in CCATEMP.
 
<li>The <var class="term">value</var> argument violates the rules for an XML element value (that is, it contains an invalid character).
<p>
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>The <var class="term">uri</var> value is invalid. </li>
 
<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>
</ul>
</ul>


==See also==
==See also==
<ul>
<ul>
<li>For more information about namespace declarations, see [[XML processing in Janus SOAP#Names and namespaces|"Names and namespaces"]].
<li>For more information about namespace declarations, see [[XML processing in Janus SOAP#Names and namespaces|Names and namespaces]]. </li>
<li>For more information about URIs, see [[XML_processing_in_Janus_SOAP#Uniform_Resource_Identifier_syntax|"Uniform_Resource Identifier syntax"]].
 
<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 sibling of the node pointed to by the method object; <var>AddElement</var> adds an <var>Element</var> as the last child of the node pointed to by the method object.
<li>For more information about URIs, see [[XML processing in Janus SOAP#Uniform Resource Identifier syntax|Uniform Resource Identifier syntax]]. </li>
<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>
 
<li>These methods are useful for working with namespaces:
<li>These methods are useful for working with namespaces:
<ul>
<ul>
<li><var>[[AddNamespace (XmlNode subroutine)|AddNamespace]]</var>
<li><var>[[AddNamespace (XmlNode subroutine)|AddNamespace]]</var> </li>
<li><var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var>
<li><var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var> </li>
</ul>
</ul></li>
</ul>
</ul>
{{Template:XmlNode:InsertElementBefore footer}}
{{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: