Serial (XmlDoc/XmlNode function)

Serialize selected subtree as string (XmlDoc and XmlNode classes)

This function 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

%utfOrEbcd	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, which are identified below and described in greater detail in "XmlDoc API serialization options": 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, as described for the next option) 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. One of the line-end options, below, must also be specified. CR (carriage-return), LF (linefeed), or CRLF (carriage-return followed by a linefeed) Inserts one of these line-end options to provide line breaks in the serialized output If an AddTrailingDelimiter=false argument is also specified, no line-end character is added at the end of the serialized subtree. 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. For example: <middleName></middleName> 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: This option is only a supplement to the ExclCanonical option: specifying WithComments without specifying ExclCanonical has no effect. Specifying ExclCanonical without specifying WithComments causes all Comment nodes to be suppressed 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, and if the XmlDoc is not empty. XmlDecl may only be specified if the top of the subtree being serialized is the Root node.
AddTrailingDelimiter	This Boolean, name required parameter 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 specified as 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 is new 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

• To obtain a Longstring that is the UTF-8 serialization of an entire XmlDoc, including the "XML declaration," use ??Xml.
• The options argument values may be specified in any case. For example, XmlDecl and xmldecl are interchangeable.
• Line-end/whitespace characters:
  • Using one of the line-end character options (CR, LF, CRLF) produces output that is similar to the BothCompact option of the Print method (??Print).
  • If one of the line-end (CR, LF, CRLF) options is specified, and an element to be serialized has the xml:space="preserve" attribute, then within the serialization of that element and its descendants, no line-end characters are inserted. In addition, the xml:space="default" attribute has no effect under these options: specified by itself, it does not influence serialization, nor does it cause resumption of readability line-ends or indents if they were suspended by a containing xml:space="preserve".
  • As of version 6.7, the Serial 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 following whitespace characters:
    • For Attribute nodes: tab, carriage return (CR), and linefeed (LF)
    • For Text nodes: carriage return

    Since the character references are not subject to the standard XML whitespace normalization (?? refid=normwhi.), a serialized document (or subtree) that is then deserialized will retain this whitespace.

    These character references are used:

    tab

    	

    CR

    

    LF

    


    The EBCDIC and corresponding ASCII encodings of the characters is:

    	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 ". Prior to 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.
• Options are invalid.
• Insufficient free space exists in CCATEMP.

See also

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods

• The subroutine that serializes an XmlDoc and sends it as a Web response is ??WebSend, described below.
• Additional serializing methods include:
  • Xml
  • Print
  • AddXml (HttpRequest class, described in the Janus SocketsR.)
• To deserialize a string, use ??LoadXml or ??WebReceive.
• For more information about using XPath expressions, see XPath.