Serial (XmlDoc/XmlNode function): Difference between revisions
m (→Syntax terms) |
m (→See also) |
||
Line 99: | Line 99: | ||
<li><var>[[AddXml (HttpRequest subroutine)|AddXml]]</var> (<var>[[HttpRequest class|HttpRequest]]</var> class) | <li><var>[[AddXml (HttpRequest subroutine)|AddXml]]</var> (<var>[[HttpRequest class|HttpRequest]]</var> class) | ||
</ul> | </ul> | ||
<li>See the description of [[XmlDoc_API_serialization_options#EBCDIC_serialization_of_untranslatable_Unicode_characters|Unicode to EBCDIC conversion]] performed by <var>Serial</var> with the <code>EBCDIC</code> option. | |||
<li>To deserialize a string, use <var>[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</var> or <var>[[WebReceive (XmlDoc function)|WebReceive]]</var>. | <li>To deserialize a string, 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 18:47, 2 February 2012
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>
Request-cancellation errors
- 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".