Xml (XmlDoc function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (move footer template to actual end; edits, tags and links)
Line 1: Line 1:
{{Template:XmlDoc:Xml subtitle}}
{{Template:XmlDoc:Xml subtitle}}
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).


This 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).
==Syntax==
==Syntax==
{{Template:XmlDoc:Xml syntax}}
{{Template:XmlDoc:Xml syntax}}
Line 9: Line 7:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%string</th>
<tr><th>%string</th>
<td>The string serialization of the <var>Xml</var>Doc, encoded in UTF-8. </td></tr>
<td>The string serialization of the <var>XmlDoc</var>, encoded in UTF-8.</td></tr>
<tr><th>doc</th>
<tr><th>doc</th>
<td><var>Xml</var>Doc expression, whose content is serialized. </td></tr>
<td><var>XmlDoc</var> expression, whose content is to be serialized.</td></tr>
<tr><th>options</th>
<tr><th>options</th>
<td>A blank delimited string that can contain one or more of the following options (but no repeats), which are identified below and described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]:  
<td>A blank delimited string that can contain one or more of the following options (but no repeats), which are identified below and described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]:  
<ul>  
<ul>  
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
<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, if the <var>XmlDoc</var> is not empty,
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, if the <var>XmlDoc</var> is not empty, and if the node selected by <var class="term">xpath</var> is the <var>Root</var> node. <var>AllowXmlDecl</var> is the default.  
and if the node selected by <var class="term">xpath</var> is the <var>Root</var> node. <var>AllowXmlDecl</var> is the default.  


<li><b>Indent <i>n</i></b><br>
<li><b>Indent <i>n</i></b><br>
Line 26: Line 23:


<li><b>NoEmptyElt</b><br>
<li><b>NoEmptyElt</b><br>
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. The default is to serialize an empty element with an empty element tag (as in <code><middleName/></code>).
Deprecated as of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.0, this option ensures that all empty elements are serialized 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>).


<li><b>OmitNullElement</b><br>
<li><b>OmitNullElement</b><br>
Line 33: Line 30:
<li><b>SortCanonical</b><br>  
<li><b>SortCanonical</b><br>  


This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).
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 class="term">ExclCanonical</var> option.  
It is superseded by the <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> method <var>ExclCanonical</var> option.  
</ul></td></tr>
</ul></td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Options may be specified in any case, for example, you can use
<li>Options may be specified in any case, for example, you can use either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
either <code>NoXmlDecl</code> or <code>noxmldecl</code>, interchangeably.
<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"]].
<li>The <var>Xml</var>Doc method object must be well-formed (that is,
<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>.
it must contain an <var>Element</var> node).
<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
For more information, see  
used to insert line breaks and optional indentation, which may not be an accurate serialization of an <var>XmlDoc</var>.
[[XML processing in Janus SOAP#Well-formed documents and validation|"Well-formed documents and validation"]].
<li>As of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, <var>Attribute</var> values are always serialized within double-quotation-mark (<code>"</code>) 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.
<li>Since the result of the <var>Xml</var> function has UTF-8 encoding, you
</ul>
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>.
<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
used to insert line breaks and optional indentation, which may not be an
accurate serialization of an <var>XmlDoc</var>.


<li>As of ''Sirius Mods'' 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.
</ul>
==Examples==
==Examples==
<ul>
<ol>
<li>The <var>[[AddXml]]</var> method of the <var>[[HttpRequest]]</var> class
<li>The <var>[[AddXml]]</var> method of the <var>[[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.
has nearly the same options as the <var>Xml</var> function.
<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>
The following fragment serializes an <var>XmlDoc</var> and sends it
<p class="code"> %httpreq object httpRequest
as a request to a web server.
  %httpresp object httpResponse
  %doc object xmlDoc
  %httpreq = new
  %doc = new
  %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<inquire><stock>IBM</stock>' with -
      <dateRange/></inquire>', 'NoEmptyElt')


Note that if you use the <var>Xml</var> function and <var>[[$Sock_Send]]</var> directly,
  %httpreq:[[URL]] = 'foo.com/bar'
instead of using an <var>[[HTTP Helper]]</var> object, always use
  %httpreq:[[addXml]](%doc)
the <var>BINARY</var> option of <var>$Sock_Send</var>, because the
  %httpresp = %httpreq:[[post]]('HTTP_CLIENT')
result of the <var>Xml</var> function is UTF-8, rather than EBCDIC.
<p class="code"> %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')
</p>
</p>
<li>The following fragment is a simple example for serializing an <var>XmlDoc</var>, which
<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:
could then, for example, be sent on a transport such as MQ:
<p class="code"> %s longstring
<p class="code"> %s Longstring
  %s = %doc:xml
%s = %doc:Xml
</p>
</p>
</ul>
</ol>


===Request-cancellation errors===
==Request-cancellation errors==
<ul>
<ul>
<li><var>XmlDoc</var> does not contain an <var>Element</var>.
<li><var class="term">XmlDoc</var> does not contain an <var>Element</var>.
<li>An <var class="term">options</var> setting is invalid.
<li>An <var class="term">options</var> setting is invalid.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


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

Revision as of 11:58, 11 May 2011

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), which are identified below and 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, if the XmlDoc is not empty, and if the node selected by xpath is the Root node. 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
    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. 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 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

  • XmlDoc 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.