Serial (XmlDoc/XmlNode function)
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.
%string = nr:Serial[( [xpath], [options], [AddTrailingDelimiter= boolean])] Throws XPathError
|%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. Any other nodes in the nodelist are ignored.
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.
- The options argument values may be specified in any case. For example,
- 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.
- 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>
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.
- The subroutine that serializes an XmlDoc and sends it as a Web response is WebSend.
- Additional serializing methods include:
- See the description of Unicode to EBCDIC conversion performed by Serial with the
- To deserialize a string, use LoadXml or WebReceive.
- For more information about using XPath expressions, see XPath.
- For additional discussion about serialization, see Transport: receiving and sending XML.