Print (XmlDoc/XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
Line 12: Line 12:
<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 (.), 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. No option may be repeated. <ul> <li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>
<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>  


Whether or not the XML declaration (<?xml version=...?>) is produced &mdash; if the XML version number (as returned by the [[Version (XmlDoc property)|Version]] is not the null string, and the node selected by <i>XPath</i> is the Root. AllowXmlDecl is the default. AllowXmlDecl and NoXmlDecl may not both be specified.
<li><b>CharacterEncodeAll</b><br>
<li><b>CharacterEncodeAll</b>
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 to display <var>Unicode</var> characters that do not translate to EBCDIC. If this option is not specified (as of ''Sirius Mods'' 7.6), only non-translatable <var>Unicode</var> characters in Attribute or Element values are displayed as character references.
 
For more information about this option, see the "Usage Notes" item [[??]] reftxt=* refid=ucharef..
<li><b>Indent <i>n</i></b><br>
The CharacterEncodeAll option is available as of ''Sirius Mods'' version 7.6.
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>Indent</b> <i><b>n</b></i>
 
Element children (and, depending on the compaction option, below, in effect, attributes and the closing characters "/>" of an empty Element) are indented ''n'' spaces 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>
If the Indent option is omitted, the default indent is 3 spaces. <i>n</i> is non-negative, and its maximum (as of ''Sirius Mods'' version 7.0) is 254. <br> <li><b>NoEmptyElt</b>
 
An empty element is serialized with a start tag followed by an end tag. For example: <pre>     <middleName>    </middleName> </pre> If NoEmptyElt is not specified, the default is to serialize an empty element with an empty element tag: <pre>     <middleName/> </pre> <li><b>OmitNullElement</b>
<li>One of the following mutually exclusive '''output formats''': <ul> <li><b>Compact</b>
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. The serialization of a child-less and Attribute-less Element is omitted, even if the Element's serialization would contain Namespace declarations in its start tag.
If an Element node has no Attributes, but has (only) Element children (one or more), and all of its children are Attribute-less and child-less, then that parent Element is serialized, even though its content in the serialization is empty. That parent is serialized with a start tag and an end tag (and an inserted line separator, if called for by the serializing method's parameter options).
For example, if the <var>Print</var> method display of a particular <var>XmlDoc</var> is the following when no <var>Print</var> options are specified: <pre>    <top>        <middle>          <empty/>          <p:empty2 xmlns:p="uri:stuff"/>        </middle>    </top> </pre>
Here is the display of the <var>XmlDoc</var> with the OmitNullElement option specified: <pre>    <top>        <middle>        </middle>    </top> </pre>
But if you attempt to display only the <tt>empty</tt> subtree of the <var>XmlDoc</var> using OmitNullElement, the <tt>empty</tt> node is not suppressed, and the result is: <pre>    <empty/> </pre>
The OmitNullElement option is available as of ''Sirius Mods'' version 7.3. <li>One of the following mutually exclusive '''output formats''': <ul> <li><b>Compact</b>
This is the default. An element's entire start tag is printed on a single line, which includes attributes and namespace declarations. If it has no children or has a single Text child, and does '''not''' have attributes nor namespace declarations, then the Text child is serialized on the same line as the start and end tags. For example: <pre>    <top>        <in1 a="xyz" b="foo">          content1        </in1>        <in2>content2</in2>    </top> </pre> <li><b>Expanded</b>
This is the default. An element's entire start tag is printed on a single line, which includes attributes and namespace declarations. If it has no children or has a single Text child, and does '''not''' have attributes nor namespace declarations, then the Text child is serialized on the same line as the start and end tags. For example: <pre>    <top>        <in1 a="xyz" b="foo">          content1        </in1>        <in2>content2</in2>    </top> </pre> <li><b>Expanded</b>
A new line is started for each attribute, namespace declaration, and child. For example: <pre>    <top>        <in1          a="xyz"          b="foo"        >          content1        </in1>        <in2>          content2        </in2>    </top> </pre> <li><b>AttributeCompact</b>
A new line is started for each attribute, namespace declaration, and child. For example: <pre>    <top>        <in1          a="xyz"          b="foo"        >          content1        </in1>        <in2>          content2        </in2>    </top> </pre> <li><b>AttributeCompact</b>
Attributes and namespace declarations are printed on the same line as the start tag. For example: <pre>    <top>        <in1 a="xyz" b="foo">          content1        </in1>        <in2>          content2        </in2>    </top> </pre> <li><b>ElementCompact</b>
Attributes and namespace declarations are printed on the same line as the start tag. For example: <pre>    <top>        <in1 a="xyz" b="foo">          content1        </in1>        <in2>          content2        </in2>    </top> </pre> <li><b>ElementCompact</b>
An entire element is printed on one line, if it has no attributes nor namespace declarations and has no children other than possibly a Text child. For example: <pre>    <top>        <in1          a="xyz"          b="foo"          >          content1        </in1>        <in2>content2</in2>    </top> </pre> <li><b>BothCompact</b>
An entire element is printed on one line, if it has no attributes nor namespace declarations and has no children other than possibly a Text child. For example: <pre>    <top>        <in1          a="xyz"          b="foo"          >          content1        </in1>        <in2>content2</in2>    </top> </pre> <li><b>BothCompact</b>
The most compacted format, this combines the effect of AttributeCompact and ElementCompact. It displays on one line an element that has no children or that has a single Text child. For example: <pre>    <top>        <in1 a="xyz" b="foo">content1</in1>        <in2>content2</in2>    </top> </pre> </ul> <li><b>SortCanonical</b>
The most compacted format, this combines the effect of AttributeCompact and ElementCompact. It displays on one line an element that has no children or that has a single Text child. For example: <pre>    <top>        <in1 a="xyz" b="foo">content1</in1>        <in2>content2</in2>    </top> </pre> </ul>  
This indicates that namespace declarations (based on the prefix being declared) and attributes (based on the namespace URI followed by the local name) are serialized in sorted order. This can be useful, for instance, to serialize a portion of an XML document for a signature.
 
The sort order for namespace declarations and attributes is from lowest to highest, and it uses the <var>Unicode</var> code ordering (for example, numbers are lower than letters).
<li><b>NoEmptyElt</b><br>
Added in ''Sirius Mods'' version 6.9 as a step towards support for canonicalization, this option is superseded by the Serial method ExclCanonical option ([[??]] refid=exclcan.), which provides full support for canonicalized serialization. </ul></td></tr>
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 <code><middleName/></code>).
 
<li><b>OmitNullElement</b><br>
An <var>Element</var> node that has no children and no <var>Attributes</var> will not be serialized, unless it is the top level <var>Element</var> in the subtree being serialized.  
 
<li><b>SortCanonical</b><br>
 
This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).
It is superseded by the <var>ExclCanonical</var> option.
 
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
Ensures that 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 top of the subtree being serialized is the <var>Root</var> node.
 
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>
 
Whether or not the XML declaration (<?xml version=...?>) is produced &mdash; if the XML version number (as returned by the [[Version (XmlDoc property)|Version]] is not the null string, and the node selected by <i>XPath</i> is the Root. AllowXmlDecl is the default. AllowXmlDecl and NoXmlDecl may not both be specified.  
 
</ul></td></tr>
</table>
</table>


Line 89: Line 102:
To serialize to EBCDIC, the <var>Print</var> method uses the <var>Unicode</var> tables
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.
(described further in [[??]] refid=u80.) to convert the <var>XmlDoc</var> content.
</ul>


One feature of the conversion from <var>Unicode</var> is that
the <var>Print</var> method displays non-translatable <var>Unicode</var> characters
stored in Attribute or Element values as character references.
For example:
<p class="code">%doc:AddElement('top', '&amp;#x2122;':U)
%doc:Print
</p>
The result of this fragment is:
<p class="output"><top>&amp;#x2122;</top>
</p>
However, with default serialization options, when an untranslatable
<var>Unicode</var> character occurs in a context other than Element or Attribute value
(that is, a name, comment, or PI), character encoding is '''not''' used.
Because it is an element name, for example, the following statements result in a
request cancellation:
<p class="code">%doc:AddElement('&amp;#x2122;':U)
%doc:Print
</p>
The <var>Print</var> method fails, attempting
to translate the element name, the U+2122 character, to EBCDIC.
This request cancellation can be prevented by using
the <tt>CharacterEncodeAll</tt> option:
<p class="code">%doc:AddElement('&amp;#x2122;':U)
%doc:Print(, 'CharacterEncodeAll')
</p>
The result of the above fragment is:
<p class="output"><&amp;#x2122;/>
</p>
'''Note:'''
The result of a <var>Print</var> with CharacterEncodeAll can be misleading.
Request cancellation is avoided, but it produces multiple EBCDIC characters
where only a single <var>Unicode</var> character is stored.
The <var>XmlDoc</var>, <tt>%doc</tt>, above is not a legal XML document,
because the ampersand (<tt>&</tt>) is not a legal name character.
Similarly, for
an untranslatable <var>Unicode</var> character added to a document
with AddComment or AddPI: printing with <tt>CharacterEncodeAll</tt>
produces a stream of characters that informs about
a single character reference but, if deserialized, would result in multiple
stored characters.
The standard XML syntax does not recognize character references as such in
names, Comments, and PIs.
</ul>
==Example==
==Example==


Revision as of 22:57, 14 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":
  • 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.
  • Indent n
    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.
  • Compact, Expanded, AttributeCompact, ElementCompact, or BothCompact
  • One of the following mutually exclusive output formats:
    • Compact This is the default. An element's entire start tag is printed on a single line, which includes attributes and namespace declarations. If it has no children or has a single Text child, and does not have attributes nor namespace declarations, then the Text child is serialized on the same line as the start and end tags. For example: 
           <top>        <in1 a="xyz" b="foo">          content1        </in1>        <in2>content2</in2>     </top>
    • Expanded A new line is started for each attribute, namespace declaration, and child. For example: 
           <top>        <in1          a="xyz"          b="foo"        >          content1        </in1>        <in2>          content2        </in2>     </top>
    • AttributeCompact Attributes and namespace declarations are printed on the same line as the start tag. For example: 
           <top>        <in1 a="xyz" b="foo">          content1        </in1>        <in2>           content2        </in2>     </top>
    • ElementCompact An entire element is printed on one line, if it has no attributes nor namespace declarations and has no children other than possibly a Text child. For example: 
           <top>        <in1           a="xyz"           b="foo"           >          content1        </in1>        <in2>content2</in2>     </top>
    • BothCompact The most compacted format, this combines the effect of AttributeCompact and ElementCompact. It displays on one line an element that has no children or that has a single Text child. For example: 
           <top>        <in1 a="xyz" b="foo">content1</in1>        <in2>content2</in2>     </top>
  • 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). It is superseded by the ExclCanonical option.
  • AllowXmlDecl or NoXmlDecl
    Ensures that 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 top of the subtree being serialized is the Root node.
  • AllowXmlDecl or NoXmlDecl Whether or not the XML declaration (<?xml version=...?>) is produced — if the XML version number (as returned by the Version is not the null string, and the node selected by XPath is the Root. AllowXmlDecl is the default. AllowXmlDecl and NoXmlDecl may not both be specified.

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.
  • The Print method output is not affected if one of the output format options or Indent is specified, and an element to be serialized has the xml:space="preserve" or xml:space="default" attribute.
  • As of version 6.7, the Print 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:
    • Attribute
    • Text

    These character references are used:

    tab
    &#x9;
    CR
    &#xD;
    LF
    &#xA;

    The EBCDIC and corresponding ASCII encodings of the characters is:

    &thinsp.
    EBCDIC ASCII
    tab
    X'05' X'09'
    CR
    X'0D' X'0D'
    LF
    X'25' X'0A'
  • 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.
  • As of Sirius Mods version 7.6, XmlDoc content is stored in Unicode. To serialize to EBCDIC, the Print method uses the Unicode tables (described further in ?? refid=u80.) to convert the XmlDoc content.

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 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 ?? reftxt=Audit refid=audit. and ?? reftxt=Trace refid=trace., inserts line breaks and performs indentation.
  • Additional serializing methods include:
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Print_(XmlDoc/XmlNode_subroutine)&oldid=11278"