AddPI (XmlDoc/XmlNode function): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
mNo edit summary |
||
| Line 1: | Line 1: | ||
{{Template:XmlDoc/XmlNode:AddPI subtitle}} | |||
[[Category:XmlDoc methods|AddPI function]] | [[Category:XmlDoc methods|AddPI function]] | ||
[[Category:XmlNode methods|AddPI function]] | [[Category:XmlNode methods|AddPI function]] | ||
| Line 13: | Line 13: | ||
This callable function adds a PI (Processing Instruction) node as the last child | This callable function adds a PI (Processing Instruction) node as the last child | ||
of the Root node or Element node referenced by the method object. | of the Root node or Element node referenced by the method object. | ||
==Syntax== | |||
{{Template:XmlDoc/XmlNode:AddPI syntax}} | |||
===Syntax terms=== | |||
<dl> | <dl> | ||
<dt>%nod | <dt>%nod | ||
| Line 25: | Line 24: | ||
<dt>name | <dt>name | ||
<dd>A Unicode string that is the target of the added PI node; | <dd>A Unicode string that is the target of the added PI node; | ||
this can be thought of as the | this can be thought of as the "name" of the PI. | ||
It must conform to the XML syntax rules for a PI target; the | It must conform to the XML syntax rules for a PI target; the | ||
maximum length of the name is 127 characters | maximum length of the name is 127 characters | ||
| Line 35: | Line 34: | ||
</dl> | </dl> | ||
==Usage notes== | |||
<ul> | <ul> | ||
<li>Since the return value of AddPI is frequently not needed, | <li>Since the return value of AddPI is frequently not needed, | ||
| Line 56: | Line 55: | ||
In the following example, one PI node is added | In the following example, one PI node is added | ||
as the last child of element | as the last child of element "b": | ||
<pre> | <pre> | ||
Begin | Begin | ||
Revision as of 16:56, 22 January 2011
Add Processing Instruction to XmlDoc Root or to Element XmlNode (XmlDoc and XmlNode classes)
[Requires Janus SOAP]
AddPI is a member of the XmlDoc and XmlNode classes.
This 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 127 characters (100 characters prior to version 7.7 of Janus SOAP).
- 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 an 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.
Example
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
- Nr is neither the Root nor an Element 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
- 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.