AddPI (XmlDoc/XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(30 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Add Processing Instruction to XmlDoc Root or to Element XmlNode</b></span>
{{Template:XmlDoc/XmlNode:AddPI subtitle}}
[[Category:XmlDoc methods|AddPI function]]
The <var>AddPI</var> [[Notation conventions for methods#Callable functions|callable]] function adds a [[XmlDoc API#XmlDoc node types|PI (Processing Instruction) node]] as the last child of the <var>Root</var> node or <var>Element</var> node referenced by the method object.
[[Category:XmlNode methods|AddPI function]]
 
[[Category:XmlDoc API methods]]
==Syntax==
[[Category:System methods]]
{{Template:XmlDoc/XmlNode:AddPI syntax}}
<!--DPL?? Category:XmlDoc methods|AddPI function: Add Processing Instruction to XmlDoc Root or to Element XmlNode-->
 
<!--DPL?? Category:XmlNode methods|AddPI function: Add Processing Instruction to XmlDoc Root or to Element XmlNode-->
===Syntax terms===
<!--DPL?? Category:XmlDoc API methods|AddPI (XmlDoc/XmlNode function): Add Processing Instruction to XmlDoc Root or to Element XmlNode-->
<table class="syntaxTable">
<!--DPL?? Category:System methods|AddPI (XmlDoc/XmlNode function): Add Processing Instruction to XmlDoc Root or to Element XmlNode-->
<tr><th nowrap>%nod</th>
<p>
<td>If specified, an <var>XmlNode</var> that is set to point to the <var>PI</var> node that is added.</td></tr>
AddPI is a member of the [[XmlDoc class|XmlDoc]] and [[XmlNode class|XmlNode]] classes.
</p>


This callable function adds a PI (Processing Instruction) node as the last child
<tr><th>nr</th>
of the Root node or Element node referenced by the method object.
<td>An <var>XmlDoc</var> or <var>XmlNode</var> that refers to the <var>Root</var> or <var>Element</var> node that is the parent of the added <var>PI</var> node.</td></tr>
===Syntax===
  [%nod =] nr:AddPI(name, value)


====Syntax Terms====
<tr><th>name</th>
<dl>
<td>A <var>Unicode</var> string that is the target of the added <var>PI</var> node; this can be thought of as the "name" of the <var>PI</var>. It must conform to the XML syntax rules for a PI target; the maximum length of the name is 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7).</td></tr>
<dt>%nod
<dd>If specified, an XmlNode that is set to point to the PI node that is added.
<dt>nr
<dd>An XmlDoc or XmlNode that refers to the Root or Element node
that is the parent of the added PI node.
<dt>name
<dd>A Unicode string that is the target of the added PI node;
this can be thought of as the &ldquo;name&rdquo; of the PI.
It must conform to the XML syntax rules for a PI target; the
maximum length of the name is 127 characters
(100 characters prior to version 7.7 of [[Janus SOAP]]).
<dt>value
<dd>A Unicode string that is the value of the added PI node;
stored exactly as is, that is, without whitespace normalization.


</dl>
<tr><th>value</th>
<td>A <var>Unicode</var> string that is the value of the added <var>PI</var> node; stored exactly as is, that is, without whitespace normalization.</td></tr>
</table>


===Usage Notes===
==Usage notes==
<ul>
<ul>
<li>Since the return value of AddPI is frequently not needed,
<li>Since the return value of <var>AddPI</var> is frequently not needed, you may want to [[Notation_conventions_for_methods#Callable_methods|Call]] it instead of saving its return value.
you may want to Call it instead of saving its return value.
<li>Processing of 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>
<li>Processing of an XmlDoc is likely to be more efficient if
you add nodes in document
order (that is, top-to-bottom, left-to-right).
<li>To modify the value stored in an PI node,
change the Value property of an XmlNode that points to
the PI node.
<li>As of ''Sirius Mods'' version 7.3, the 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]].
</ul>


===Example===
<li>To modify the value stored in a <var>PI</var> node, change the <var>Value</var> property of an <var>XmlNode</var> that points to the <var>PI</var> node. </li>


In the following example, one PI node is added
<li>As of <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.3, the method arguments may include only non-null EBCDIC characters that translate to <var>Unicode</var>.  As of <var class="product">Sirius Mods</var> Version 7.6, these argument strings are <var>Unicode</var> or are converted to <var>Unicode</var>. 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"]]. </li>
as the last child of element &ldquo;b&rdquo;:
</ul>
<pre>
    Begin
    %doc is Object XmlDoc
    %doc = New
    %doc:LoadXml('<top><a><b>05</b></a></top>')
    %n1 is Object XmlNode
    %n1 = %doc:SelectSingleNode('top/a/b')
    Call %n1:AddPI('processing_app', 'ignore pre-2004')
    Call %doc:Print
    End
</pre>


The example result, showing the serialized format of the processing
==Examples==
instruction, follows:
In the following example, one PI node is added as the last child of element "b":
<pre>
<p class="code">begin
    <top>
  %doc is object xmlDoc
      <a>
  %doc = new
          <b>
  %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]<nowiki>('<top><a><b>05</b></a></top>')</nowiki>
            05
  %n1 is object xmlNode
            <?processing_app ignore pre-2004?>
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a/b')
          </b>
  [[Notation_conventions_for_methods#Callable_methods|Call]] %n1:addPI('processing_app', 'ignore pre-2004')
      </a>
  call %doc:print
    </top>
end
</pre>
</p>
The example result, showing the serialized format of the processing instruction, follows:
<p class="code"><nowiki><top>
<a>
    <b>
      05
      <?processing_app ignore pre-2004?>
    </b>
</a>
</top></nowiki>
</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>Nr</i> is neither the Root nor an Element node.
<li>The <var class="term">nr</var> object is neither the <var>Root</var> nor an <var>Element</var> node.
<li>Argument <i>name</i> violates the rules for an
<li>The <var class="term">name</var> argument violates the rules for an XML processing instruction target.
XML processing instruction target.
<li>The <var class="term">value</var> argument violates the rules for an XML processing instruction value.
<li>Argument <i>value</i> violates the rules for an
XML processing instruction value.
</ul>
</ul>


 
==See also==
===See Also===
 
<ul>
<ul>
<li>[[??]] reftxt=InsertPIBefore refid=inspi. also adds a PI node.
<li><var>[[InsertPIBefore (XmlNode function)|InsertPIBefore]]</var> also adds a <var>PI</var> node. <var>AddPI</var> adds a <var>PI</var> as the last child of the node pointed to by the method object; <var>InsertPIBefore</var> adds a <var>PI</var> as the immediately preceding sibling of the node pointed to by the method object.
AddPI adds a PI as the last child of the node pointed to by the
method object;
InsertPIBefore adds a PI as the immediately preceding
sibling of the node pointed to by the method object.
</ul>
</ul>
{{Template:XmlDoc/XmlNode:AddPI footer}}

Latest revision as of 21:01, 2 September 2015

Add Processing Instruction to XmlDoc Root or to Element XmlNode (XmlDoc and XmlNode classes)

[Requires Janus SOAP]

The AddPI callable function adds a PI (Processing Instruction) node as the last child of the Root node or Element node referenced by the method object.

Syntax

[%nod =] nr:AddPI( name, value)

Syntax terms

%nod If specified, an XmlNode that is set to point to the PI node that is added.
nr An XmlDoc or XmlNode that refers to the Root or Element node that is the parent of the added PI node.
name A Unicode string that is the target of the added PI node; this can be thought of as the "name" of the PI. It must conform to the XML syntax rules for a PI target; the maximum length of the name is 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7).
value A Unicode string that is the value of the added PI node; stored exactly as is, that is, without whitespace normalization.

Usage notes

  • Since the return value of AddPI is frequently not needed, you may want to Call it instead of saving its return value.
  • Processing of an XmlDoc is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
  • To modify the value stored in a PI node, change the Value property of an XmlNode that points to the PI node.
  • As of Sirius Mods Version 7.3, the 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".

Examples

In the following example, one PI node is added as the last child of element "b":

begin %doc is object xmlDoc %doc = new %doc:loadXml('<top><a><b>05</b></a></top>') %n1 is object xmlNode %n1 = %doc:selectSingleNode('top/a/b') Call %n1:addPI('processing_app', 'ignore pre-2004') call %doc:print end

The example result, showing the serialized format of the processing instruction, follows:

<top> <a> <b> 05 <?processing_app ignore pre-2004?> </b> </a> </top>

Request-cancellation errors

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

  • The nr object is neither the Root nor an Element node.
  • The name argument violates the rules for an XML processing instruction target.
  • The value argument violates the rules for an XML processing instruction value.

See also

  • InsertPIBefore also adds a PI node. AddPI adds a PI as the last child of the node pointed to by the method object; InsertPIBefore adds a PI as the immediately preceding sibling of the node pointed to by the method object.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=AddPI_(XmlDoc/XmlNode_function)&oldid=80432"