Xml (XmlDoc function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "<span style="font-size:120%; color:black"><b>Serialize XmlDoc as UTF-8 string</b></span> Xml function Category:XmlDoc API methods [[Category:Syste...")
 
 
(36 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Serialize XmlDoc as UTF-8 string</b></span>
{{Template:XmlDoc:Xml subtitle}}
[[Category:XmlDoc methods|Xml function]]
The <var>Xml</var> function converts an <var>XmlDoc</var> to its textually represented XML document (this process is called '''serialization''', because the text representation of a document is called the '''serial''' form).  
[[Category:XmlDoc API methods]]
[[Category:System methods]]
<!--DPL?? Category:XmlDoc methods|Xml function: Serialize XmlDoc as UTF-8 string-->
<!--DPL?? Category:XmlDoc API methods|Xml (XmlDoc function): Serialize XmlDoc as UTF-8 string-->
<!--DPL?? Category:System methods|Xml (XmlDoc function): Serialize XmlDoc as UTF-8 string-->
<p>
Xml is a member of the [[XmlDoc class]].
</p>


This function converts an XmlDoc to its textually represented XML document
==Syntax==
(this process is called '''serialization''',
{{Template:XmlDoc:Xml syntax}}
because the text representation of a document is called the '''serial'''
===Syntax terms===
form).
<table class="syntaxTable">
===Syntax===
<tr><th>%string</th>
  %utf8Str = doc:Xml([options])
<td>The string serialization of the <var>XmlDoc</var>, encoded in UTF-8.</td></tr>


====Syntax Terms====
<tr><th>doc</th>
<dl>
<td><var>XmlDoc</var> expression, whose content is to be serialized.</td></tr>
<dt>utf8Str
<dd>The string serialization of the XmlDoc, encoded in UTF-8.
<dt>doc
<dd>XmlDoc expression, whose content is serialized.
<dt>options
<dd>Any combination of the following options (but single occurrences only):
<br>
<ul>
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>


AllowXmlDecl, the default, produces the
<tr><th>options</th>
XML declaration (that is, <?xml&thinsp.version=...?>)
<td>A blank delimited string that can contain one or more of the following options (but no repeats).
if the declaration was set (see [[Version (XmlDoc property)|Version]]).
<p class="note">'''Note:''' These options are described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]].  </p>
NoXmlDecl omits the XML declaration.
<ul>
<li><b>Indent</b> <i><b>n</b></i>
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
Whether or not 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, and if the <var>XmlDoc</var> is not empty. <var>AllowXmlDecl</var> is the default. </li>


Inserts space characters (and line-ends, as described for the next option)
<li><b>Indent <i>n</i></b><br>
into the serialized string such that
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>
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.


If serialized output with an Indent value of 2 is displayed as a tree,
<li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), or <b>CRLF</b> (carriage-return followed by a linefeed)<br>
the spacing is as in the following:
Inserts one of these line-end options to provide line breaks in the serialized output. </li>
<pre>
    <top>
      <leaf1 xx="yy">value</leaf1>
      <sub>
        <leaf2>value</leaf2>
      </sub>
    </top>
</pre>
<i>n</i> is a non-negative integer, and it maximum value
(as of ''Sirius Mods'' version 7.0) is 254.


One of the line-end options, below, must also be specified.
<li><b>NoEmptyElt</b><br>
<li>One of the '''line-end options''' below, to provide line breaks in
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>).
the output after any of the following is serialized:
<p>
<ul>
<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 &mdash; some tags (<code>&#x3c;div></code>) <b>require</b> separate start and end tags, while other tags (<code>&#x3c;br></code>) <b>do not allow</b> separate start and end tags. </p></li>
<li>An element start-tag, if it has any non-text node children
<li>An empty element tag, or an empty element end-tag
<li>A processing instruction (PI)
<li>A comment
<li>A text node, if it has any siblings
</ul>
<dl>
<dt>CR
<dd>Insert a carriage-return character as the line-end sequence in the above cases.
<dt>LF
<dd>Insert a linefeed character as the line-end sequence in the above cases.
<dt>CRLF
<dd>Insert a carriage-return character followed by a
linefeed character as the line-end sequence in the above cases.
</dl>
<br>
<li><b>NoEmptyElt</b>


This indicates that an empty element is serialized with its start tag
<li><b>OmitNullElement</b><br>
followed by an end tag.
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>
For example:
<pre>
    <middleName></middleName>
</pre>
If this option is not specified, the default is to serialize an empty
element with an empty element tag:
<pre>
    <middleName/>
</pre>
<li><b>OmitNullElement</b>


An Element node that has no children and
<li><b>SortCanonical</b><br>
no Attributes will not be serialized, unless it is the top level Element in
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>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> method <var>ExclCanonical</var> option. </li>
the subtree being serialized.
</ul></td></tr>
The serialization of a child-less and Attribute-less Element is omitted,
</table>
even if the Element's serialization would contain
Namespace declarations in its start tag.


If an Element node has no Attributes, but has (only) Element children
==Usage notes==
(one or more), and all of its children are Attribute-less and child-less,
<ul>
then that parent Element is serialized, even though its content in the
<li>Options may be specified in any case, for example, you can use either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
serialization is empty.
<li>The <var>Xml</var>Doc method object must be well-formed (that is, it must contain an <var>Element</var> node).  For more information, see  [[XML processing in Janus SOAP#Well-formed documents and validation|"Well-formed documents and validation"]].
That parent is serialized with a start tag and an end tag
<li>Since the result of the <var>Xml</var> function has UTF-8 encoding, you cannot treat it as an EBCDIC string: for example, printing the string will not produce displayable characters. The [[#See also|"See Also"]] section below mentions some methods for obtaining an EBCDIC serialization of an <var>XmlDoc</var>.
(and an inserted line separator, if called for by the serializing
<li>You can use the <var>[[Print (XmlDoc/XmlNode subroutine)|Print]]</var> method to display a document on the terminal, or to ''capture'' a displayable version of a document, but <var>Print</var> is
method's parameter options).
used to insert line breaks and optional indentation, which may not be an accurate serialization of an <var>XmlDoc</var>.
 
<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 attribute value is serialized as <code>&amp;quot;</code>. Prior to Version 7.6, this convention was not strictly observed.
For example, if the Print method display of a particular XmlDoc object
is the following when OmitNullElement is ''not'' specified:
<pre>
    <top>
      <middle>
          <empty/>
          <p:empty2 xmlns:p="uri:stuff"/>
      </middle>
    </top>
</pre>
 
Here is the display of the XmlDoc with the OmitNullElement option specified:
<pre>
    <top>
      <middle>
      </middle>
    </top>
</pre>
 
The OmitNullElement option is available as of ''Sirius Mods'' version 7.3.
<li><b>SortCanonical</b>
 
This indicates that
namespace declarations (based on the prefix being declared) and
attributes (based on the namespace URI followed by the local
name) are serialized in sorted order.
This can be useful, for instance, when using the Xml method to
serialize a portion of an XML document for a signature.
 
The sort order for namespace declarations and attributes is from
lowest to highest, and it uses the Unicode code ordering (for example,
numbers are lower than letters).
 
This option was added in ''Sirius Mods'' version 6.9 as a step towards support for
canonicalization.
As of version 7.0, comprehensive support for canonicalized serialization
is provided by the Serial method ExclCanonical option ([[??]] refid=exclcan.).
</ul>
</ul>


</dl>
==Examples==
===Usage Notes===
<ol>
<li>The <var>[[AddXml (HttpRequest subroutine)|AddXml]]</var> method of the <var>[[HttpRequest class|HTtpRequest]]</var> class has nearly the same options as the <var>Xml</var> function.  The following fragment serializes an <var>XmlDoc</var> and sends it as a request to a web server.
<p>Note that if you use the <var>Xml</var> function and <var>[[$Sock_Send]]</var> directly, instead of using an <var>[[HTTP Helper]]</var> object, always use the <var>BINARY</var> option of <var>$Sock_Send</var>, because the result of the <var>Xml</var> function is UTF-8, rather than EBCDIC.</p>
<p class="code"> %httpreq object httpRequest
  %httpresp object httpResponse
  %doc object xmlDoc
  %httpreq = new
  %doc = new
  %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<inquire><stock>IBM</stock>' with -
      <dateRange/></inquire>', 'NoEmptyElt')


<ul>
  %httpreq:[[URL (HttpRequest property)|URL]] = 'foo.com/bar'
<li>Options may be specified in any case, for example, you can use
  %httpreq:[[AddXml (HttpRequest subroutine)|addXml]](%doc)
either <tt>NoXmlDecl</tt> or <tt>noxmldecl</tt>, interchangeably.
  %httpresp = %httpreq:[[Post (HttpRequest function)|post]]('HTTP_CLIENT')
<li>The <i>XmlDoc</i> method object must be well-formed (that is,
</p>
it must contain an Element node).
<li>The following fragment is a simple example for serializing an <var>XmlDoc</var>, which could then, for example, be sent on a transport such as MQ:
For more information about well-formed documents, see [[??]] refid=welform..
<p class="code"> %s longstring
<li>Since the result of the Xml function has UTF-8 encoding, you
  %s = %doc:xml
cannot treat it as an EBCDIC string: for example, printing the string
</p>
will not produce displayable characters.
</ol>
The &ldquo;See Also&rdquo; section below mentions some methods for obtaining
an EBCDIC serialization of an XmlDoc.
<li>You can use the Print method
(??[[Print (XmlDoc/XmlNode subroutine)|Print]])
to display a document on the terminal,
or to '''capture''' a displayable version of a document, but Print is
used to insert line breaks and optional indentation, which may not be an
accurate serialization of an XmlDoc.
<li>Using one of the line-end character options (CR, LF, CRLF) produces output
that is analogous to the BothCompact option of the Print method.
<li>If one of the line-end
(<tt>CR</tt>, <tt>LF</tt>, <tt>CRLF</tt>) options or if
<tt>Indent</tt> is specified, and an element to be serialized has the
<tt>xml:space="preserve"</tt> attribute, then
within the serialization of that element and its descendants, no line-end
(nor indentation) characters are inserted to provide readability.


In addition, the <tt>xml:space="default"</tt> attribute has no effect
==Request-cancellation errors==
under these options:
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
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 <tt>xml:space="preserve"</tt>.
<li>As of version 6.7, the Xml 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 characters:
<ul>
<ul>
<li>For Attribute nodes: tab, carriage return, and linefeed
<li><var class="term">doc</var> object does not contain an <var>Element</var>.
<li>For Text nodes: carriage return
<li>An <var class="term">options</var> setting is invalid.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


Since the character references are not subject to the standard XML whitespace
==See also==
normalization ([[??]] refid=normwhi.),
a serialized document (or subtree) that is then deserialized
will retain this whitespace.
 
These character references are used:
<dl>
<dt>tab
<dd>&amp;#x9;
<dt>CR
<dd>&amp;#xD;
<dt>LF
<dd>&amp;#xA;
</dl>
 
The EBCDIC and corresponding ASCII encodings of the characters is:
<dl>
<dt>&thinsp.
<dd>EBCDIC    ASCII
<dt>tab
<dd>X'05'          X'09'
<dt>CR
<dd>X'0D'          X'0D'
<dt>LF
<dd>X'25'          X'0A'
</dl>
<li>As of ''Sirius Mods'' version 7.6, ''Attribute values'' are always serialized
within double-quotation-mark (<tt>"</tt>) delimiters,
and a double-quotation mark character in an attribute value is serialized
as <tt>&amp;quot;</tt>.
Prior to version 7.6, this convention was not strictly observed.
 
</ul>
===Examples===
<ul>
<ul>
<li>The [[Janus Sockets]]R documents the HttpRequest object, whose
<li>Use <var>[[Print (XmlDoc/XmlNode subroutine)|Print]]</var> to display an XML document for debugging. </li>
AddXml method has nearly the same options as the Xml function;
the following fragment serializes an XmlDoc and sends it
as a request to a Web server.


Note that if you use the Xml function and $Sock_Send directly,
<li>Use <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> with the EBCDIC option to obtain an EBCDIC serialization of an XML document. </li>
instead of using an HTTP helper object, always use
the BINARY option of $Sock_Send, because the
result of the
Xml function is UTF-8, rather than EBCDIC.
<pre>
    %httpreq object HttpRequest
    %httpresp object HttpResponse
    %doc object XmlDoc
    %httpreq = New
    %doc = New
    %doc:LoadXml('<inquire><stock>IBM</stock>' With -
      <dateRange/></inquire>', 'NoEmptyElt')


    %httpreq:URL = 'foo.com/bar'
<li>Use <var>[[WebSend (XmlDoc subroutine)|WebSend]]</var> to serialize an <var>XmlDoc</var> and send it as an HTTP response using <var class="product">[[Janus Web Server]]</var>. </li>
    %httpreq:AddXml(%doc)
    %httpresp = %httpreq:Post('HTTP_CLIENT')
</pre>
<li>The following fragment is a simple example for serializing an XmlDoc, which
could then, for example, be sent on a transport such as MQ:
<pre>
    %s Longstring
    %s = %doc:Xml
</pre>
</ul>


===Request-Cancellation Errors===
<li>The string deserialization functions are <var>[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</var> and <var>[[WebReceive (XmlDoc function)|WebReceive]]</var>. </li>
<ul>
<li>XmlDoc does not contain an Element.
<li><i>Options</i> is invalid.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


 
{{Template:XmlDoc:Xml footer}}
===See Also===
 
<ul>
<li>Use ??[[Print (XmlDoc/XmlNode subroutine)|Print]] to display an XML document for debugging.
<li>Use ??[[Serial (XmlDoc/XmlNode function)|Serial]] with the EBCDIC option to obtain an EBCDIC serialization of
an XML document.
<li>Use ??[[WebSend (XmlDoc subroutine)|WebSend]]
to serialize an XmlDoc and send it as an HTTP response using [[Janus Web Server]].
<li>The string deserialization functions are ??[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]
and ??[[WebReceive (XmlDoc function)|WebReceive]].
</ul>

Latest revision as of 18:06, 9 March 2014

Serialize XmlDoc as UTF-8 string (XmlDoc class)

The Xml function converts an XmlDoc to its textually represented XML document (this process is called serialization, because the text representation of a document is called the serial form).

Syntax

%string = doc:Xml[( [options])]

Syntax terms

%string The string serialization of the XmlDoc, encoded in UTF-8.
doc XmlDoc expression, whose content is to be serialized.
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".

  • AllowXmlDecl or NoXmlDecl
    Whether or not 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. AllowXmlDecl is the default.
  • 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 options to provide line breaks in the serialized output.
  • NoEmptyElt
    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 <middleName/>).

    NoEmptyElt is deprecated in order to deter users from using it to serialize HTML: The recommended approach for HTML is shown on the NoEmptyElement property page — some tags (<div>) require separate start and end tags, while other tags (<br>) do not allow separate start and end tags.

  • 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 Serial method ExclCanonical option.

Usage notes

  • Options may be specified in any case, for example, you can use either NoXmlDecl or noxmldecl, interchangeably.
  • The XmlDoc method object must be well-formed (that is, it must contain an Element node). For more information, see "Well-formed documents and validation".
  • Since the result of the Xml function has UTF-8 encoding, you cannot treat it as an EBCDIC string: for example, printing the string will not produce displayable characters. The "See Also" section below mentions some methods for obtaining an EBCDIC serialization of an XmlDoc.
  • You can use the Print method to display a document on the terminal, or to capture a displayable version of a document, but Print is used to insert line breaks and optional indentation, which may not be an accurate serialization of an XmlDoc.
  • 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 Version 7.6, this convention was not strictly observed.

Examples

  1. The AddXml method of the HTtpRequest class has nearly the same options as the Xml function. The following fragment serializes an XmlDoc and sends it as a request to a web server.

    Note that if you use the Xml function and $Sock_Send directly, instead of using an HTTP Helper object, always use the BINARY option of $Sock_Send, because the result of the Xml function is UTF-8, rather than EBCDIC.

    %httpreq object httpRequest %httpresp object httpResponse %doc object xmlDoc %httpreq = new %doc = new %doc:loadXml('<inquire><stock>IBM</stock>' with - <dateRange/></inquire>', 'NoEmptyElt') %httpreq:URL = 'foo.com/bar' %httpreq:addXml(%doc) %httpresp = %httpreq:post('HTTP_CLIENT')

  2. The following fragment is a simple example for serializing an XmlDoc, which could then, for example, be sent on a transport such as MQ:

    %s longstring %s = %doc:xml

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

  • doc object does not contain an Element.
  • An options setting is invalid.
  • Insufficient free space exists in CCATEMP.

See also

  • Use Print to display an XML document for debugging.
  • Use Serial with the EBCDIC option to obtain an EBCDIC serialization of an XML document.
  • Use WebSend to serialize an XmlDoc and send it as an HTTP response using Janus Web Server.
  • The string deserialization functions are LoadXml and WebReceive.