Serial (XmlDoc/XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (edits, tags and links)
Line 1: Line 1:
{{Template:XmlDoc/XmlNode:Serial subtitle}}
{{Template:XmlDoc/XmlNode:Serial subtitle}}
<var>Serial</var> converts an <var>XmlDoc</var> subtree to the UTF-8 or EBCDIC text string representation of the subtree.  (This process is called '''serialization''', because the text representation of a document is called the '''serial''' form.)


This function converts an <var>XmlDoc</var> subtree to the UTF-8 or EBCDIC
text string representation of the subtree.
(This process is called '''serialization''',
because the text representation of a document is called the '''serial'''
form.)
==Syntax==
==Syntax==
{{Template:XmlDoc/XmlNode:Serial syntax}}
{{Template:XmlDoc/XmlNode:Serial syntax}}
Line 11: Line 7:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%string</th>
<tr><th>%string</th>
<td>A string variable for the string serialization of the subtree, encoded either in UTF-8 or, if the <var>EBCDIC</var> option (see below) is used, in EBCDIC. </td></tr>
<td>A string variable for the string serialization of the subtree, encoded either in UTF-8 or, if the <var>EBCDIC</var> option (see below) is used, in EBCDIC.</td></tr>
 
<tr><th>nr</th>
<tr><th>nr</th>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <var class="term">xpath</var> expression. If an <var>XmlDoc</var>, the <var>Root</var> node is the context node. </td></tr>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <var class="term">xpath</var> expression. If an <var>XmlDoc</var>, the <var>Root</var> node is the context node.</td></tr>
 
<tr><th>xpath</th>
<tr><th>xpath</th>
<td>A <var>Unicode</var> string that is an [[XML processing in Janus SOAP#XML Path Language (XPath) in the XmlDoc API|XPath]] expression that results in a nodelist, the head of which is the top of the subtree to serialize. This is an optional argument; its default is a period (<tt>.</tt>), that is, the node referenced by the method object (<var class="term">nr</var>).
<td>A <var>Unicode</var> string that is an [[XML processing in Janus SOAP#XML Path Language (XPath) in the XmlDoc API|XPath]] expression that results in a nodelist, the head of which is the top of the subtree to serialize. This is an optional argument; its default is a period (<code>.</code>), that is, the node referenced by the method object(<var class="term">nr</var>).
 
<p>Prior to <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr>
Prior to <var class="product">Sirius Mods</var> version 7.6, this is an EBCDIC string. </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 (but no repeats), 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 (but no repeats):  
<ul>  
<ul>  
<li><b>EBCDIC</b><br>
<li><b>EBCDIC</b>
Produces serialized output in EBCDIC text rather than the default encoding, UTF-8.  
<br>Produces serialized output in EBCDIC text rather than the default encoding, UTF-8.  
 
<li><b>ExclCanonical</b>
<li><b>ExclCanonical</b><br>
<br>Produces serialized output in exclusive XML canonical form, as defined in the W3C "Exclusive XML Canonicalization" specification (http://www.w3.org/tr/xml-exc-c14n).
Produces serialized output in exclusive XML canonical form, as defined in the W3C "Exclusive XML Canonicalization" specification (http://www.w3.org/tr/xml-exc-c14n).  
<li><b>Indent <i>n</i></b>
 
<br>Inserts space characters and line-ends into the serialized string such that if the string is broken at the line-ends and displayed as a tree, the display of each lower level in the subtree is indented ''n'' spaces from the previous level's starting point. You must also specify <code>CR</code>, <code>LF</code>, or <code>CRLF</code> (see below).
<li><b>Indent <i>n</i></b><br>
<li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), or <b>CRLF</b> (carriage-return followed by a linefeed)
Inserts space characters and line-ends into the serialized string such that if the string is broken at the line-ends and displayed as a tree, the display of each lower level in the subtree is indented ''n'' spaces from the previous level's starting point. You must also specify <var>CR</var>, <var>LF</var>, or <var>CRLF</var> (see below).
<br>Inserts one of these line-end characters to provide line breaks in the serialized output.  
 
<li><b>NoEmptyElt</b>
<li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), or <b>CRLF</b> (carriage-return followed by a linefeed)<br>
<br>
Inserts one of these line-end characters to provide line breaks in the serialized output.  
Deprecated as of <var class="product">Sirius Mods</var> Version 7.0, this option ensures that all empty elements are serialized 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>
<li><b>NoEmptyElt</b><br>
<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.
Deprecated as of <var class="product">Sirius Mods</var> version 7.0, this option ensures that all empty elements are serialized 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>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>OmitNullElement</b><br>
<li><b>WithComments</b>
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.  
<br>Includes in the serialized output all <var>Comment</var> nodes in the specified subtree.
 
<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>WithComments</b><br>  
Includes in the serialized output all <var>Comment</var> nodes in the specified subtree.  
<p>'''Note:''' Specifying <var>WithComments</var> without specifying <var>ExclCanonical</var> has no effect. Specifying <var>ExclCanonical</var> without specifying <var>WithComments</var> suppresses all <var>Comment</var> nodes from the result.</p>  
<p>'''Note:''' Specifying <var>WithComments</var> without specifying <var>ExclCanonical</var> has no effect. Specifying <var>ExclCanonical</var> without specifying <var>WithComments</var> suppresses all <var>Comment</var> nodes from the result.</p>  
 
<li><b>XmlDecl</b>
<li><b>XmlDecl</b><br>
<br>Ensures that the serialization will contain the "XML Declaration" (<code><?xml version=...?></code>), if the value of the <var>[[Version (XmlDoc property)|Version]]</var> 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.
Ensures that the serialization will contain the "XML Declaration" (<code><?xml version=...?></code>), if the value of the <var>[[Version (XmlDoc property)|Version]]</var> property is a non-null string, if the <var>XmlDoc</var> is not empty,
</ul>
and if the top of the subtree being serialized is the <var>Root</var> node.</ul></td></tr>
These options are described in greater detail in described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]</td></tr>
 
<tr><th>AddTrailingDelimiter</th>
<tr><th><var>AddTrailingDelimiter</var></th>
<td>This <var>[[Methods#Named parameters|Name-Required]]</var> parameter is a <var>[[Boolean]]</var> value, which determines whether a final line-end character is added to the serialization when one of the <var>Serial</var> method line-end options (<var>LF</var>, <var>CR</var>, or <var>CRLF</var>) is specified.
<td>This <var>[[Boolean]]</var>, [[Methods#Named_parameters|name required]] parameter determines whether a final line-end character is added to the serialization when one of the <var>Serial</var> method line-end options (<var>LF</var>, <var>CR</var>, or <var>CRLF</var>) is specified.
<p>The default value of <var>AddTrailingDelimiter</var> is <code>True</code>, so <var>Serial</var> specified with a line-end option adds a trailing line-end by default. If <var>AddTrailingDelimiter</var> is <code>False</code>, no final line-end character is added.</p>
 
<p>Specifying the <var>AddTrailingDelimiter</var> argument without also specifying one of the line-end options has no effect on the resulting serialization.</p>
The default value of <var>AddTrailingDelimiter</var> is <var>True</var>, so <var>Serial</var> specified with a line-end option adds a trailing line-end by default. If <var>AddTrailingDelimiter</var> is <var>False</var>, no final line-end character is added.
<p><var>AddTrailingDelimiter</var> was introduced as of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.0. It may be useful if a digital signature must be created which includes line-end characters between XML tags, but the <var>XmlDoc</var> does not contain those line-end <var>Text</var> nodes.</p></td></tr>
Specifying the <var>AddTrailingDelimiter</var> argument without also specifying one of the line-end options has no effect on the resulting serialization.
<var>AddTrailingDelimiter</var> is new as of <var class="product">Sirius Mods</var> version 7.0. It may be useful if a digital signature must be created which includes line-end characters between XML tags, but the <var>XmlDoc</var> does not contain those line-end <var>Text</var> nodes.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The <var class="term">options</var> argument values may be specified in any case.
<li>The <var class="term">options</var> argument values may be specified in any case. For example, <code>XmlDecl</code> and <code>xmldecl</code> are interchangeable.
For example, <code>XmlDecl</code> and <code>xmldecl</code> are interchangeable.
<li>As of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, <var>Attribute</var> values are always serialized within double-quotation-mark (<code>"</code>) delimiters, and a double-quotation mark character in an <var>Attribute</var> value is serialized as <code>&amp;quot;</code>. Prior to <var class="product">"Sirius Mods"</var> Version 7.6, this convention was not strictly observed.
 
<li>As of <var class="product">Sirius Mods</var> version 7.6, <var>Attribute</var> values are always serialized
within double-quotation-mark (<tt>"</tt>) delimiters,
and a double-quotation mark character in an <var>Attribute</var> value is serialized
as <code>&amp;quot;</code>.
Prior to version 7.6, this convention was not strictly observed.
</ul>
</ul>


==Examples==
==Examples==
In the following example, the <var>Serial</var> method EBCDIC
<ol><li>In the following example, the <var>Serial</var> method EBCDIC formatting of a document is shown. A <var>Print</var> statement display of the default UTF-8 formatting of <var>Serial</var> is a string that is not readily decipherable.
formatting of a document is shown.
<p class="code">begin
A <var>Print</var> statement display of the default UTF-8 formatting of <var>Serial</var> is a
  %doc is object xmlDoc
string that is not readily decipherable.
  %sl is object [[Stringlist_class|stringlist]]
<p class="code">Begin
  %doc = new
%doc is Object XmlDoc
  %sl = new
%sl is Object Stringlist
%doc = New
%sl = New


text to %sl
  text to %sl
<nowiki><top>
  <nowiki><top>
  <a>
      <a>
      <b>05</b>
        <b>05</b>
  </a>
      </a>
  <c>
      <c>
      <d att="val"/>
        <d att="val"/>
  </c>
      </c>
</top></nowiki>
  </top></nowiki>
end text
  end text
 
 
Call %doc:LoadXml(%sl)
  [[Notation_conventions_for_methods#Callable_methods|Call]] %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]](%sl)
Print 'Serial method output follows:'
  print 'Serial method output follows:'
Print %doc:Serial('top', 'ebcdic')
  print %doc:serial('top', 'ebcdic')
End
end
</p>
</p>
The example results follow:
The example results follow:
<p class="output">Serial method output follows:
<p class="output">Serial method output follows:
<nowiki><top><a><b>05</b></a><c><d att="val"/></c></top></nowiki>
<nowiki><top><a><b>05</b></a><c><d att="val"/></c></top></nowiki>
</p>
</p></ol>


==Request-Cancellation Errors==
==Request-Cancellation Errors==
Line 117: Line 89:


==See also==
==See also==
<ul>
<ul>
<li>The subroutine that serializes an <var>XmlDoc</var> and sends it as a
<li>The subroutine that serializes an <var>XmlDoc</var> and sends it as a Web response is <var>[[WebSend (XmlDoc subroutine)|WebSend]]</var>.
Web response is <var>[[WebSend (XmlDoc subroutine)|WebSend]]</var>.
<li>Additional serializing methods include:
<li>Additional serializing methods include:
<ul>
<ul>
Line 127: Line 97:
<li><var>[[AddXml]]</var> (<var>[[HttpRequest]]</var> class)
<li><var>[[AddXml]]</var> (<var>[[HttpRequest]]</var> class)
</ul>
</ul>
<li>To deserialize a string,
<li>To deserialize a string, use <var>[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</var> or <var>[[WebReceive (XmlDoc function)|WebReceive]]</var>.
use <var>[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</var>
or <var>[[WebReceive (XmlDoc function)|WebReceive]]</var>.
<li>For more information about using XPath expressions, see [[XPath|"XPath"]].
<li>For more information about using XPath expressions, see [[XPath|"XPath"]].
</ul>
</ul>
{{Template:XmlDoc/XmlNode:Serial footer}}
{{Template:XmlDoc/XmlNode:Serial footer}}

Revision as of 08:01, 22 May 2011

Serialize selected subtree as string (XmlDoc and XmlNode classes)

Serial converts an XmlDoc subtree to the UTF-8 or EBCDIC text string representation of the subtree. (This process is called serialization, because the text representation of a document is called the serial form.)

Syntax

%string = nr:Serial[( [xpath], [options], [AddTrailingDelimiter= boolean])] Throws XPathError

Syntax terms

%string A string variable for the string serialization of the subtree, encoded either in UTF-8 or, if the EBCDIC option (see below) is used, in EBCDIC.
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 serialize. This is an optional argument; its default is a period (.), that is, the node referenced by the method object(nr).

Prior to "Sirius Mods" Version 7.6, this is an EBCDIC string.

options A blank delimited string that can contain one or more of the following options (but no repeats):
  • EBCDIC
    Produces serialized output in EBCDIC text rather than the default encoding, UTF-8.
  • ExclCanonical
    Produces serialized output in exclusive XML canonical form, as defined in the W3C "Exclusive XML Canonicalization" specification (http://www.w3.org/tr/xml-exc-c14n).
  • Indent n
    Inserts space characters and line-ends into the serialized string such that if the string is broken at the line-ends and displayed as a tree, the display of each lower level in the subtree is indented n spaces from the previous level's starting point. You must also specify CR, LF, or CRLF (see below).
  • CR (carriage-return), LF (linefeed), or CRLF (carriage-return followed by a linefeed)
    Inserts one of these line-end characters to provide line breaks in the serialized output.
  • NoEmptyElt
    Deprecated as of Sirius Mods Version 7.0, this option ensures that all empty elements are serialized 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.
  • WithComments
    Includes in the serialized output all Comment nodes in the specified subtree.

    Note: Specifying WithComments without specifying ExclCanonical has no effect. Specifying ExclCanonical without specifying WithComments suppresses all Comment nodes from the result.

  • XmlDecl
    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.
These options are described in greater detail in described in greater detail in "XmlDoc API serialization options"
AddTrailingDelimiter This Name-Required parameter is a Boolean value, which determines whether a final line-end character is added to the serialization when one of the Serial method line-end options (LF, CR, or CRLF) is specified.

The default value of AddTrailingDelimiter is True, so Serial specified with a line-end option adds a trailing line-end by default. If AddTrailingDelimiter is False, no final line-end character is added.

Specifying the AddTrailingDelimiter argument without also specifying one of the line-end options has no effect on the resulting serialization.

AddTrailingDelimiter was introduced as of "Sirius Mods" Version 7.0. It may be useful if a digital signature must be created which includes line-end characters between XML tags, but the XmlDoc does not contain those line-end Text nodes.

Usage notes

  • The options argument values may be specified in any case. For example, XmlDecl and xmldecl are interchangeable.
  • 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 "Sirius Mods" Version 7.6, this convention was not strictly observed.

Examples

  1. In the following example, the Serial method EBCDIC formatting of a document is shown. A Print statement display of the default UTF-8 formatting of Serial is a string that is not readily decipherable.

    begin %doc is object xmlDoc %sl is object stringlist %doc = new %sl = new text to %sl <top> <a> <b>05</b> </a> <c> <d att="val"/> </c> </top> end text Call %doc:loadXml(%sl) print 'Serial method output follows:' print %doc:serial('top', 'ebcdic') end

    The example results follow:

    Serial method output follows: <top><a><b>05</b></a><c><d att="val"/></c></top>

Request-Cancellation Errors

  • xpath is invalid.
  • Result of xpath is empty.
  • An options setting is invalid.
  • Insufficient free space exists in CCATEMP.

See also