InsertPIBefore (XmlNode function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
|||
| (5 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:XmlNode:InsertPIBefore subtitle}} | {{Template:XmlNode:InsertPIBefore subtitle}} | ||
The <var>InsertPIBefore</var> callable function inserts a PI (Processing Instruction) node as the immediate sibling preceding the method <var>XmlNode</var>. | The <var>InsertPIBefore</var> [[Notation_conventions_for_methods#Callable_methods|callable]] function inserts a [[XmlDoc API#XmlDoc node types|PI (Processing Instruction) node]] as the immediate sibling preceding the method <var>XmlNode</var>. | ||
==Syntax== | ==Syntax== | ||
{{Template:XmlNode:InsertPIBefore syntax}} | {{Template:XmlNode:InsertPIBefore 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 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><var>XmlNode</var> pointing to the (non-Root) node before which the PI node is inserted.</td></tr> | <td><var>XmlNode</var> pointing to the (non-<var>Root</var>) node before which the PI node is inserted.</td></tr> | ||
<tr><th>name</th> | <tr><th>name</th> | ||
<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 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7).</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 300 characters (127 characters prior to version 7.9, and 100 characters prior to version 7.7).</td></tr> | ||
<tr><th>value</th> | <tr><th>value</th> | ||
<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> | <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> | ||
| Line 18: | Line 22: | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>As of <var class="product">[[Sirius Mods]]</var> Version 7.3, the <var>InsertPIBefore</var> method arguments may include only non-null EBCDIC characters that translate to | <li>As of <var class="product">[[Sirius Mods]]</var> Version 7.3, the <var>InsertPIBefore</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 XmlDoc API"]]. | change, see [[XmlDoc API#Strings and Unicode with the XmlDoc API|"Strings and Unicode with the XmlDoc API"]]. | ||
<li>Since the return value of <var>InsertPIBefore</var> is frequently not needed, you may want to [[Notation_conventions_for_methods#Callable_methods|Call]] it instead of saving its return value. | <li>Since the return value of <var>InsertPIBefore</var> is frequently not needed, you may want to [[Notation_conventions_for_methods#Callable_methods|Call]] it instead of saving its return value. | ||
<li>There is a very small "one-time" processing cost if | |||
<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). | 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>To modify the value stored in a PI node, change the <var>[[Value_(XmlDoc/XmlNode_property)|Value]]</var> property of an <var>XmlNode</var> that points to the PI node. | |||
<li>To modify the value stored in a <var>PI</var> node, change the <var>[[Value_(XmlDoc/XmlNode_property)|Value]]</var> property of an <var>XmlNode</var> that points to the <var>PI</var> node. | |||
</ul> | </ul> | ||
==Examples== | ==Examples== | ||
In the following example, a PI node is inserted before node "top": | In the following example, a PI node is inserted before node "top": | ||
<p class="code">begin | <p class="code">begin | ||
| Line 47: | Line 53: | ||
</a> | </a> | ||
</top> | </top> | ||
</p | </p> | ||
==Request- | ==Request-cancellation errors== | ||
This list is not exhaustive: it does <i>not</i> include all the errors that are request cancelling. | |||
<ul> | <ul> | ||
<li><var class="term"> | <li>The <var class="term">nod</var> object is the <var>Root</var> node. | ||
<li><var class="term">name</var> violates the rules for an XML processing instruction target. | <li>The <var class="term">name</var> argument violates the rules for an XML processing instruction target. | ||
<li><var class="term">value</var> violates the rules for an XML processing instruction value. | <li>The <var class="term">value</var> argument violates the rules for an XML processing instruction value. | ||
</ul> | </ul> | ||
==See also== | ==See also== | ||
<ul> | <ul> | ||
<li><var>[[AddPI_(XmlDoc/XmlNode_function)|AddPI]]</var> also adds a PI node. <var>InsertPIBefore</var> adds a PI as the immediately preceding sibling of the node pointed to by the method object. <var>AddPI</var> adds a PI as the last child of the node pointed to by the method object. | <li><var>[[AddPI_(XmlDoc/XmlNode_function)|AddPI]]</var> also adds a <var>PI</var> node. <var>InsertPIBefore</var> adds a <var>PI</var> as the immediately preceding sibling of the node pointed to by the method object. <var>AddPI</var> adds a <var>PI</var> as the last child of the node pointed to by the method object. | ||
<li>For hints about inserting a node ''after'' a sibling node, see the | <li>For hints about inserting a node ''after'' a sibling node, see the <var>InsertElementBefore</var> [[InsertElementBefore_(XmlNode_function)#Examples|examples]]. | ||
</ul> | </ul> | ||
{{Template:XmlNode:InsertPIBefore footer}} | {{Template:XmlNode:InsertPIBefore footer}} | ||
Latest revision as of 21:18, 2 September 2015
Insert a processing instruction before this node (XmlNode class)
[Requires Janus SOAP]
The InsertPIBefore callable function inserts a PI (Processing Instruction) node as the immediate sibling preceding the method XmlNode.
Syntax
[%outNod =] nod:InsertPIBefore( name, value)
Syntax terms
| %outNod | 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 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 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 with the XmlDoc API".
- 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 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).
- To modify the value stored in a PI node, change the Value property of an XmlNode that points to the PI node.
Examples
In the following example, a PI node is inserted before node "top":
begin %doc is object xmlDoc %doc = new call %doc:loadXml('<top><a><b>05</b></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> <b>05</b> </a> </top>
Request-cancellation errors
This list is not exhaustive: it does not include all the errors that are request cancelling.
- The nod object is the Root 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
- 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 InsertElementBefore examples.