Serial (XmlDoc/XmlNode function): Difference between revisions
m (→Syntax terms) |
|||
Line 10: | Line 10: | ||
<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 [[XPath#XPath_syntax|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 [[XPath#XPath_syntax|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>). | ||
<p>Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr> | <p>Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr> | ||
<tr><th><div id="options"></div>options</th> | <tr><th><div id="options"></div>options</th> | ||
<td>A blank delimited string that can contain one or more of the following options (but no repeats). < | <td>A blank delimited string that can contain one or more of the following options (but no repeats). <p class="note">'''Note:''' These options are described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]. </p> | ||
<ul> | <ul> | ||
<li><b>CharacterEncodeAll</b><br> | <li><b>CharacterEncodeAll</b><br> | ||
If the <var>EBCDIC</var> option is specified, use character encoding in all contexts (that is, not only in <var>Attribute</var> or <var>Element</var> values) to display Unicode characters that do not translate to EBCDIC. This option is available starting with version 8.0 of the <var class="product">Sirius Mods</var>. | If the <var>EBCDIC</var> option is specified, use character encoding in all contexts (that is, not only in <var>Attribute</var> or <var>Element</var> values) to display Unicode characters that do not translate to EBCDIC. This option is available starting with version 8.0 of the <var class="product">Sirius Mods</var>. | ||
<li><b>EBCDIC</b> | <li><b>EBCDIC</b> | ||
<br>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>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). | <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). | ||
<li><b>Indent <i>n</i></b> | <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). | <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> | ||
<li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), or <b>CRLF</b> (carriage-return followed by a linefeed) | <li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), or <b>CRLF</b> (carriage-return followed by a linefeed) | ||
<br>Inserts one of these line-end characters to provide line breaks in the serialized output. | <br>Inserts one of these line-end characters to provide line breaks in the serialized output. </li> | ||
<div id="noempty"></div> | <div id="noempty"></div> | ||
<li><b>NoEmptyElt</b> | <li><b>NoEmptyElt</b> | ||
<br> | <br>This deprecated option 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>). | ||
<p> | |||
<var>NoEmptyElt</var> is deprecated in order to deter users from using it to serialize HTML: The recommended approach for HTML is shown on the <var>[[NoEmptyElement (XmlNode property)#browserExample|NoEmptyElement]]</var> property page — some tags (<code><div></code>) <b>require</b> separate start and end tags, while other tags (<code><br></code>) <b>do not allow</b> separate start and end tags. </p></li> | |||
<li><b>OmitNullElement</b> | <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. | <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> | ||
<li><b>SortCanonical</b> | <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. | <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> | ||
<li><b>UTF-8</b> | <li><b>UTF-8</b> | ||
<br>Produces serialized output in UTF-8. This is the default. | <br>Produces serialized output in UTF-8. This is the default. </li> | ||
<li><b>WithComments</b> | <li><b>WithComments</b> | ||
<br>Includes in the serialized output all <var>Comment</var> nodes in the specified subtree. | <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 class="note">'''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> | ||
<li><b>XmlDecl</b> | <li><b>XmlDecl</b> | ||
<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. | <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. </li> | ||
</ul> | </ul> | ||
</td></tr> | </td></tr> | ||
<tr><th><var>AddTrailingDelimiter</var></th> | <tr><th><var>AddTrailingDelimiter</var></th> | ||
<td>This [[Methods#Named parameters|name required]] parameter is a <var>[[Enumerations#Using Boolean enumerations|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 [[Methods#Named parameters|name required]] parameter is a <var>[[Enumerations#Using Boolean enumerations|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. | ||
<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> | <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> | ||
<p><var>AddTrailingDelimiter</var> was introduced 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.</p></td></tr> | <p> | ||
Specifying the <var>AddTrailingDelimiter</var> argument without also specifying one of the line-end options has no effect on the resulting serialization.</p> | |||
<p> | |||
<var>AddTrailingDelimiter</var> was introduced 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.</p></td></tr> | |||
</table> | </table> | ||
Revision as of 18:00, 9 March 2014
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). Note: These options are 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
andxmldecl
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
"
. Prior to Sirius Mods Version 7.6, this convention was not strictly observed.
Examples
- 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>
- In the following fragment, the Serial method EBCDIC formatting of a document with untranslatable Unicode is shown.
%doc2:addElement('circumference', - '2 * π * r':U) print %doc2:serial(, 'ebcdic')
The result follows (the Unicode codepoint for the Greek letter π has the hexadecimal value 03C0):
<circumference>2 * π * r</circumference>
Request-cancellation errors
This list is not exhaustive: it does not include all the errors that are request cancelling.
- xpath argument is invalid.
- Result of xpath is empty.
- An options setting is invalid.
- Insufficient free space exists in CCATEMP.
See also
- The subroutine that serializes an XmlDoc and sends it as a Web response is WebSend.
- Additional serializing methods include:
- Xml
- AddXml (HttpRequest class)
- See the description of Unicode to EBCDIC conversion performed by Serial with the
EBCDIC
option. - To deserialize a string, use LoadXml or WebReceive.
- For more information about using XPath expressions, see "XPath".