InsertPIBefore (XmlNode function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (1 revision) |
||
| Line 2: | Line 2: | ||
This callable function inserts a PI (Processing Instruction) node as the immediate | This callable function inserts a PI (Processing Instruction) node as the immediate | ||
sibling preceding the method XmlNode. | sibling preceding the method <var>XmlNode</var>. | ||
==Syntax== | ==Syntax== | ||
{{Template:XmlNode:InsertPIBefore syntax}} | {{Template:XmlNode:InsertPIBefore syntax}} | ||
| Line 8: | Line 8: | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%nod</th> | <tr><th>%nod</th> | ||
<td>If specified, an XmlNode that is set to point to the PI node that is inserted. </td></tr> | <td>If specified, an <var>XmlNode</var> that is set to point to the PI node that is inserted. </td></tr> | ||
<tr><th>nod</th> | <tr><th>nod</th> | ||
<td>XmlNode pointing to the (non-Root) node before which the PI node is inserted. </td></tr> | <td><var>XmlNode</var> pointing to the (non-Root) node before which the PI node is inserted. </td></tr> | ||
<tr><th>name</th> | <tr><th>name</th> | ||
<td>A Unicode string that is the target of the inserted 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 127 characters (100 characters prior to version 7.7 of [[Janus SOAP]]). </td></tr> | <td>A <var>Unicode</var> string that is the target of the inserted 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 127 characters (100 characters prior to version 7.7 of [[Janus SOAP]]). </td></tr> | ||
<tr><th>value</th> | <tr><th>value</th> | ||
<td>A Unicode string that is the value of the inserted PI node; stored exactly as is, that is, without whitespace normalization.</td></tr> | <td>A <var>Unicode</var> string that is the value of the inserted PI node; stored exactly as is, that is, without whitespace normalization.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>As of ''Sirius Mods'' version 7.3, the InsertPIBefore method arguments may | <li>As of ''Sirius Mods'' version 7.3, the <var>InsertPIBefore</var> method arguments may | ||
include only non-null EBCDIC characters that translate to Unicode. | include only non-null EBCDIC characters that translate to <var>Unicode</var>. | ||
As of ''Sirius Mods'' version 7.6, these argument strings are Unicode or are | As of ''Sirius Mods'' version 7.6, these argument strings are <var>Unicode</var> or are | ||
converted to Unicode. | converted to <var>Unicode</var>. | ||
For more information about the effects of this version 7.6 | For more information about the effects of this version 7.6 | ||
change, see [[Strings and Unicode]]. | change, see [[Strings and Unicode]]. | ||
<li>Since the return value of InsertPIBefore is frequently not needed, | <li>Since the return value of <var>InsertPIBefore</var> is frequently not needed, | ||
you may want to Call it instead of saving its return value. | you may want to Call it instead of saving its return value. | ||
<li>There is a very small "one-time" processing cost | <li>There is a very small "one-time" processing cost | ||
if certain XPath operations are performed after using this method, because | if certain XPath operations are performed after using this method, because | ||
Insert-Before methods are guaranteed to add a node out of document order. | 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 | 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). | you add nodes in document order (that is, top-to-bottom, left-to-right). | ||
<li>To modify the value stored in a PI node, | <li>To modify the value stored in a PI node, | ||
change the Value property of an XmlNode that points to the PI node. | change the Value property of an <var>XmlNode</var> that points to the PI node. | ||
</ul> | </ul> | ||
| Line 41: | Line 41: | ||
a PI node is inserted before node "top": | a PI node is inserted before node "top": | ||
<p class="code">Begin | <p class="code">Begin | ||
%doc is Object XmlDoc | %doc is <var>Object</var> <var>XmlDoc</var> | ||
%doc = New | %doc = New | ||
Call %doc:LoadXml('<top><a><b>05</b></a></top>') | Call %doc:LoadXml('<top><a><b>05</b></a></top>') | ||
%n1 is Object XmlNode | %n1 is <var>Object</var> <var>XmlNode</var> | ||
%n1 = %doc:SelectSingleNode('top') | %n1 = %doc:SelectSingleNode('top') | ||
Call %n1:InsertPIBefore('xml-stylesheet', - | Call %n1:<var>InsertPIBefore</var>('xml-stylesheet', - | ||
'type="text/xsl" href="transfor.xsl"') | 'type="text/xsl" href="transfor.xsl"') | ||
Call %doc:Print | Call %doc:Print | ||
| Line 77: | Line 77: | ||
<li>AddPI ([[??]] reftxt=AddPI refid=addpi.) | <li>AddPI ([[??]] reftxt=AddPI refid=addpi.) | ||
also adds a PI node. | also adds a PI node. | ||
InsertPIBefore adds a PI as the immediately preceding | <var>InsertPIBefore</var> adds a PI as the immediately preceding | ||
sibling of the node pointed to by the method object. | 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 | AddPI adds a PI as the last child of the node pointed to by the | ||
Revision as of 17:46, 25 January 2011
Insert a processing instruction before this node (XmlNode class)
[Requires Janus SOAP]
This callable function inserts a PI (Processing Instruction) node as the immediate
sibling preceding the method XmlNode.
Syntax
[%outNod =] nod:InsertPIBefore( name, value)
Syntax terms
| %nod | If specified, an XmlNode that is set to point to the PI node that is inserted. |
|---|---|
| nod | XmlNode pointing to the (non-Root) node before which the PI node is inserted. |
| name | A Unicode string that is the target of the inserted 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 127 characters (100 characters prior to version 7.7 of Janus SOAP). |
| value | A Unicode string that is the value of the inserted PI node; stored exactly as is, that is, without whitespace normalization. |
Usage notes
- As of Sirius Mods version 7.3, the InsertPIBefore 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.
- Since the return value of InsertPIBefore is frequently not needed, you may want to Call it instead of saving its return value.
- 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 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.
Example
In the following example, a PI node is inserted before node "top":
Begin %doc is Object XmlDoc %doc = New Call %doc:LoadXml('<top><a>05</a></top>') %n1 is Object XmlNode %n1 = %doc:SelectSingleNode('top') Call %n1:InsertPIBefore('xml-stylesheet', - 'type="text/xsl" href="transfor.xsl"') Call %doc:Print End
The example results follow:
<?xml-stylesheet type="text/xsl" href="transfor.xsl"?> <top> <a> 05 </a> </top>
Request-Cancellation Errors
- Nod is the Root node.
- Argument name violates the rules for an XML processing instruction target.
- Argument value violates the rules for an XML processing instruction value.
See also
- AddPI (?? reftxt=AddPI refid=addpi.) also adds a PI node. InsertPIBefore adds a PI 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.
- For hints about inserting a node after a sibling node, see the "Example" section in InsertElementBefore.