Print (XmlDoc/XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 10: Line 10:
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <i>XPath</i> expression. If an <var>XmlDoc</var>, the Root node is the context node. </td></tr>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <i>XPath</i> expression. If an <var>XmlDoc</var>, the Root node is the context node. </td></tr>
<tr><th>xpath</th>
<tr><th>xpath</th>
<td>A <var>Unicode</var> string that is an XPath expression that results in a nodelist, the head of which is the top of the subtree to print. An optional argument, its default is a period (.), that is, the node referenced by the method object (<i>nr</i>). </td></tr>
<td>A <var>Unicode</var> string that is an XPath expression that results in a nodelist, the head of which is the top of the subtree to print. An optional argument, its default is a period (<tt>.</tt>), that is, the node referenced by the method object (<i>nr</i>). </td></tr>
<tr><th>options</th>
<tr><th>options</th>
<td>A blank delimited string that can contain one or more of the following options, which are identified below and described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]:  
<td>A blank delimited string that can contain one or more of the following options, which are identified below and described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]:  
<ul>  
<ul>  
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
Whether or not the serialization will contain the "XML Declaration" (<code><?xml version=...?></code>), if the value of the [[Version (XmlDoc property)|Version]] property is a non-null string, if the <var>XmlDoc</var> is not empty,
and if the node selected by <var class="term">xpath</var> is the <var>Root</var> node. <var>AllowXmlDecl</var> is the default.


<li><b>CharacterEncodeAll</b><br>
<li><b>CharacterEncodeAll</b><br>
Use character encoding in all contexts (that is, not only in Attribute or Element values) to display Unicode characters that do not translate to EBCDIC.  
Use character encoding in all contexts (that is, not only in Attribute or Element values) to display Unicode characters that do not translate to EBCDIC.  
<li><b>Indent <i>n</i></b><br>
Indent Element children (and, depending on the compaction option, below, in effect, attributes and the closing characters "/>" of an empty Element) ''n'' spaces (default 3) from the beginning of the Element's Start-Tag.


<li><b>Compact</b>, <b>Expanded</b>, <b>AttributeCompact</b>, <b>ElementCompact</b>, or <b>BothCompact</b> <br>
<li><b>Compact</b>, <b>Expanded</b>, <b>AttributeCompact</b>, <b>ElementCompact</b>, or <b>BothCompact</b> <br>
One of these mutually exclusive [[XmlDoc API serialization options#outformat|output formats]], which control the degree of expansion or compression of the display of a serialized element's content.  
One of these mutually exclusive [[XmlDoc API serialization options#outformat|output formats]], which control the degree of expansion or compression of the display of a serialized element's content.  
<li><b>Indent <i>n</i></b><br>
Indent Element children (and, depending on the compaction option, above, in effect, attributes and the closing characters "/>" of an empty Element) ''n'' spaces (default 3) from the beginning of the Element's Start-Tag.


<li><b>NoEmptyElt</b><br>
<li><b>NoEmptyElt</b><br>
Line 32: Line 36:
<li><b>SortCanonical</b><br>  
<li><b>SortCanonical</b><br>  
This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).   
This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).   
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
Whether or not the serialization will contain the "XML Declaration" (<code><?xml version=...?></code>), if the value of the [[Version (XmlDoc property)|Version]] property is a non-null string, if the <var>XmlDoc</var> is not empty,
and if the node selected by <var class="term">xpath</var> is the <var>Root</var> node. <var>AllowXmlDecl</var> is the default.


</ul></td></tr>
</ul></td></tr>
Line 44: Line 44:
<li>Options may be specified in any case.
<li>Options may be specified in any case.
For example, you can use
For example, you can use
either <tt>NoXmlDecl</tt> or <tt>noxmldecl</tt>, interchangeably.
either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
<li>As a debugging aide, <var>Print</var> may be issued for the root node of an
<li>As a debugging aide, <var>Print</var> may be issued for the root node of an
<var>XmlDoc</var> that is not well-formed, that is, does not contain an Element.
<var>XmlDoc</var> that is not well-formed, that is, does not contain an <var>Element</var>.
<li>The <var>Print</var> method output is '''not''' affected if one of the output
format options or
<tt>Indent</tt> is specified, and an element to be serialized has the
<tt>xml:space="preserve"</tt> or <tt>xml:space="default"</tt> attribute.
<li>As of version 6.7, the <var>Print</var> method uses the hexadecimal
character references specified in the XML Canonicalization specification
(:hp0 color=SirLink.http://www.w3.org/TR/xml-c14n:ehp0.) to
display the tab, carriage return, and linefeed characters
for the following XML document node types:
<ul>
<li>Attribute
<li>Text
</ul>
 
These character references are used:
<dl>
<dt>tab
<dd>&amp;#x9;
<dt>CR
<dd>&amp;#xD;
<dt>LF
<dd>&amp;#xA;
</dl>


The EBCDIC and corresponding ASCII encodings of the characters is:
<dl>
<dt>&thinsp.
<dd>EBCDIC    ASCII
<dt>tab
<dd>X'05'          X'09'
<dt>CR
<dd>X'0D'          X'0D'
<dt>LF
<dd>X'25'          X'0A'
</dl>
<li>As of ''Sirius Mods'' version 7.6, Attribute values are always serialized
<li>As of ''Sirius Mods'' version 7.6, Attribute values are always serialized
within double-quotation-mark (<tt>"</tt>) delimiters,
within double-quotation-mark (<tt>"</tt>) delimiters,
and a double-quotation mark character in an attribute value is serialized
and a double-quotation mark character in an attribute value is serialized
as <tt>&amp;quot;</tt>.
as <code>&amp;quot;</code>.
Prior to version 7.6, this convention was not strictly observed.
Prior to version 7.6, this convention was not strictly observed.
<li>As of ''Sirius Mods'' version 7.6, <var>XmlDoc</var> content is stored in <var>Unicode</var>.
To serialize to EBCDIC, the <var>Print</var> method uses the <var>Unicode</var> tables
(described further in [[??]] refid=u80.) to convert the <var>XmlDoc</var> content.
</ul>
</ul>


Line 97: Line 60:
in its default form with no arguments,
in its default form with no arguments,
then with explicit values for its options:
then with explicit values for its options:
<p class="code">Begin
<p class="code"> Begin
Print 'Print method'
Print 'Print method'
Print '***********'
Print '***********'
%doc is Object XmlDoc
%doc is Object XmlDoc
%doc = New
%doc = New
Call %doc:LoadXml<nowiki>('<top><a><b>05</b></a><a2/></top>')</nowiki>
Call %doc:LoadXml<nowiki>('<top><a><b>05</b></a><a2/></top>')</nowiki>
%doc:Version ='1.0'
%doc:Version ='1.0'
Call %doc:Print
Call %doc:Print
Print 'Non-default display:'
Print 'Non-default display:'
Call %doc:Print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded')
Call %doc:Print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded')
End
End
</p>
</p>


The example results follow:
The example results follow:
<p class="code"><nowiki><?xml version="1.0"?>
<p class="code"> <nowiki><?xml version="1.0"?>
<top>
<top>
  <a>
    <a>
      <b>05</b>
      <b>05</b>
  </a>
    </a>
  <a2/>
    <a2/>
</top></nowiki>
</top></nowiki>
Non-default display:
Non-default display:
<nowiki><top>
<nowiki><top>
  <a>
    <a>
      <b>
      <b>
            05
            05
      </b>
      </b>
  </a>
    </a>
  <a2>
    <a2>
  </a2>
    </a2>
</top></nowiki>
</top></nowiki>
</p>
</p>
==Request-Cancellation Errors==
==Request-cancellation errors==
<ul>
<ul>
<li><i>XPath</i> is invalid.
<li><var class="term">xpath</var> is invalid.
<li>Result of (<i>XPath</i>) is empty.
<li>Result of <var class="term">xpath</var> is empty.
<li><i>Options</i> are invalid.
<li><var class="term">options</var> values are invalid.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>
Line 141: Line 104:
{{Template:XmlDoc/XmlNode:Print footer}}
{{Template:XmlDoc/XmlNode:Print footer}}
<ul>
<ul>
<li>For more information about using XPath expressions, see [[XPath]].
<li>For more information about using XPath expressions, see [[XPath|"XPath"]].
<li>To more accurately serialize an <var>XmlDoc</var>, as opposed to providing
<li>To more accurately serialize an <var>XmlDoc</var>, as opposed to providing
a "displayable" form, use the [[Serial (XmlDoc/XmlNode function)|Serial]] function.
a "displayable" form, use the [[Serial (XmlDoc/XmlNode function)|Serial]] function.
The <var>Print</var> subroutine, like its analogs [[??]] reftxt=Audit refid=audit.
The <var>Print</var> subroutine, like its analogs [[Audit (XmlDoc/XmlNode subroutine)|Audit]]
and [[??]] reftxt=Trace refid=trace.,
and [[Trace (XmlDoc/XmlNode subroutine)|Trace]], inserts line breaks and performs indentation.
inserts line breaks and performs indentation.
<li>Additional serializing methods include:
<li>Additional serializing methods include:
<ul>
<ul>
<li>[[WebSend (XmlDoc subroutine)|WebSend]]
<li>[[WebSend (XmlDoc subroutine)|WebSend]]
<li>AddXml (HttpRequest class, described in the [[Janus Sockets]]R.)
<li>[[AddXml]] ([[HttpRequest]] class)
</ul>
</ul>
</ul>
</ul>

Revision as of 01:34, 16 February 2011

Print selected subtree (XmlDoc and XmlNode classes)


This subroutine displays an XmlDoc subtree in a readable form, useful for debugging, for example.

Syntax

nr:Print[( [xpath], [options])] Throws XPathError

Syntax terms

nr An XmlDoc or XmlNode, used as the context node for the XPath expression. If an XmlDoc, the Root node is the context node.
xpath A Unicode string that is an XPath expression that results in a nodelist, the head of which is the top of the subtree to print. An optional argument, its default is a period (.), that is, the node referenced by the method object (nr).
options A blank delimited string that can contain one or more of the following options, which are identified below and described in greater detail in "XmlDoc API serialization options":
  • AllowXmlDecl or NoXmlDecl
    Whether or not the serialization will contain the "XML Declaration" (<?xml version=...?>), if the value of the Version property is a non-null string, if the XmlDoc is not empty, and if the node selected by xpath is the Root node. AllowXmlDecl is the default.
  • CharacterEncodeAll
    Use character encoding in all contexts (that is, not only in Attribute or Element values) to display Unicode characters that do not translate to EBCDIC.
  • Compact, Expanded, AttributeCompact, ElementCompact, or BothCompact
    One of these mutually exclusive output formats, which control the degree of expansion or compression of the display of a serialized element's content.
  • Indent n
    Indent Element children (and, depending on the compaction option, above, in effect, attributes and the closing characters "/>" of an empty Element) n spaces (default 3) from the beginning of the Element's Start-Tag.
  • NoEmptyElt
    Deprecated as of Sirius Mods version 7.0, serializes all empty elements with a start tag followed by an end tag. The default is to serialize an empty element with an empty element tag (as in <middleName/>).
  • OmitNullElement
    An Element node that has no children and no Attributes will not be serialized, unless it is the top level Element in the subtree being serialized.
  • SortCanonical
    This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).

Usage notes

  • Options may be specified in any case. For example, you can use either NoXmlDecl or noxmldecl, interchangeably.
  • As a debugging aide, Print may be issued for the root node of an XmlDoc that is not well-formed, that is, does not contain an Element.
  • As of Sirius Mods version 7.6, Attribute values are always serialized within double-quotation-mark (") delimiters, and a double-quotation mark character in an attribute value is serialized as &quot;. Prior to version 7.6, this convention was not strictly observed.

Example

In the following example, the Print method is called first in its default form with no arguments, then with explicit values for its options:

Begin Print 'Print method' Print '***********' %doc is Object XmlDoc %doc = New Call %doc:LoadXml('<top><a><b>05</b></a><a2/></top>') %doc:Version ='1.0' Call %doc:Print Print 'Non-default display:' Call %doc:Print('/', 'NoXmlDecl NoEmptyElt Indent 6 Expanded') End

The example results follow:

<?xml version="1.0"?> <top> <a> <b>05</b> </a> <a2/> </top> Non-default display: <top> <a> <b> 05 </b> </a> <a2> </a2> </top>

Request-cancellation errors

  • xpath is invalid.
  • Result of xpath is empty.
  • options values are invalid.
  • Insufficient free space exists in CCATEMP.


See also

  • For more information about using XPath expressions, see "XPath".
  • To more accurately serialize an XmlDoc, as opposed to providing a "displayable" form, use the Serial function. The Print subroutine, like its analogs Audit and Trace, inserts line breaks and performs indentation.
  • Additional serializing methods include: