Difference between revisions of "WebSend (XmlDoc subroutine)"

From m204wiki
Jump to navigation Jump to search
m
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{Template:XmlDoc:WebSend subtitle}}
 
{{Template:XmlDoc:WebSend subtitle}}
 +
<var>WebSend</var> converts an <var>XmlDoc</var> to its textually represented XML document to be sent in a response on a <var class="product">[[Janus Web Server|Janus Web Server]]</var> thread. The process of converting to a text string is called '''serialization''', because the text representation of a document is called the '''serial'''
 +
form.
  
This subroutine converts an <var>XmlDoc</var> to its textually represented XML document
+
The serialized output of <var>WebSend</var> is a UTF-8 text string. This output is added to the output buffer that is sent by a subsequent invocation of <var>[[$Web_Done]]</var> or <var>[[$Web_Form_Done]]</var>.
to be sent in a response on a <var class="product">[[Janus Web Server]]</var> thread.
 
(The process of converting to a text string is called '''serialization''',
 
because the text representation of a document is called the '''serial'''
 
form).
 
  
The serialized output of <var>WebSend</var> is a UTF-8 text string.
 
This output is added to the output buffer that is sent by a subsequent
 
invocation of <var>[[$Web_done]]</var> or <var>[[$Web_form_done]]</var>.
 
 
==Syntax==
 
==Syntax==
 
{{Template:XmlDoc:WebSend syntax}}
 
{{Template:XmlDoc:WebSend syntax}}
Line 16: Line 11:
 
<tr><th>doc</th>
 
<tr><th>doc</th>
 
<td>An expression that points to the <var>XmlDoc</var> whose content is to be serialized. </td></tr>
 
<td>An expression that points to the <var>XmlDoc</var> 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 (but no duplications) of the following options.
 +
<p class="note">'''Note:''' These options are described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]. </p>
 
<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, and if the <var>XmlDoc</var> is not empty. <var>AllowXmlDecl</var> is the default. </li>
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>
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 may also specify <code>CR</code>, <code>LF</code>, <code>CRLF</code>, or <code>Newline</code> (see below).
+
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 may also specify <var>CR</var>, <var>LF</var>, <var>CRLF</var>, or <var>Newline</var> (see below).
If <var>Indent</var> is specified and no line-end options are also specified, <var>Newline</var> is implied.
+
If <var>Indent</var> is specified and no line-end options are also specified, <var>Newline</var> is implied. </li>
  
<li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), <b>CRLF</b> (carriage-return followed by a linefeed), or <b>Newline</b> (line-end set for the ''Janus Web'' connection)<br>
+
<li><b>CR</b> (carriage-return), <b>LF</b> (linefeed), <b>CRLF</b> (carriage-return followed by a linefeed), or <b>Newline</b> (line-end set for the <var class="product">Janus Web</var> connection)<br>
Inserts one of these line-end options to provide line breaks in the serialized output.  
+
Inserts one of these line-end options to provide line breaks in the serialized output. </li>
  
 
<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>).
+
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>).
 +
<p>
 +
<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><b>OmitNullElement</b><br>
 
<li><b>OmitNullElement</b><br>
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.  
+
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>
  
 
<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). It is superseded by the <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> method <var>ExclCanonical</var> option. </li>
This deprecated option serializes namespace declarations and attributes in sorted order (from lowest to highest with Unicode code ordering).
+
</ul>
It is superseded by the <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> method <var>ExclCanonical</var> option.  
+
</td></tr>
</ul></td></tr>
 
 
</table>
 
</table>
  
 
==Usage notes==
 
==Usage notes==
 
 
<ul>
 
<ul>
<li>The <var>XmlDoc</var> method object must be well-formed (that is,
+
<li>The method object, <var class="term">doc</var>, must be [[XML processing in Janus SOAP#Well-formed documents and validation|well-formed]] (that is, it must contain an <var>Element</var> node).  
it must contain an <var>Element</var> node).
+
<li>The output line-breaking <var class="term">options</var> make the serialized stream easier to read, for example, for a browser's "view page source" facility to display XHTML produced with <var class="product">[[Janus SOAP]]</var>.
For more information, see
+
<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 <var>Attribute</var> value is serialized as <code>&amp;quot;</code>. Prior to <var class="product">Sirius Mods</var> Version 7.6, this convention was not strictly observed.
[[XML processing in Janus SOAP#Well-formed documents and validation|"Well-formed documents and validation"]].
 
<li>The output line-breaking <var class="term">options</var> make the serialized stream
 
easier to read, for example, for a browser's "view page source" facility
 
to display XHTML produced with <var class="product">[[Janus SOAP]]</var>.
 
<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 <code>&amp;quot;</code>.
 
Prior to version 7.6, this convention was not strictly observed.
 
 
 
 
</ul>
 
</ul>
===Example===
 
  
The following <var class="product">[[Janus Web Server]]</var> program uses
+
==Examples==
WebReceive to obtain the XML document from the HTTP request,
+
The following <var class="product">Janus Web Server</var> program uses <var>[[WebReceive_(XmlDoc_function)|WebReceive]]</var> to obtain the XML document from the HTTP request, then uses <var>WebSend</var> to buffer some of the received data:
then uses <var>WebSend</var> to buffer some of the received data:
+
<p class="code">begin
<p class="code"> Begin
+
  %d object xmlDoc
%d Object XmlDoc
+
  %d = new
%d = New
+
  %d:webReceive
%d:WebReceive
+
  %d2 object xmlDoc
%d2 Object XmlDoc
+
  %d2 = new
%d2 = New
+
  %d2:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<sum>' with -
%d2:LoadXml('<sum>' With -
+
      %d:[[Value_(XmlDoc/XmlNode_property)|value]]('/*/*[1]') + %d:value('/*/*[2]') -
%d:Value('/*/*[1]') + %d:Value('/*/*[2]') -
+
      with '</sum>')
    With '</sum>')
+
  %d2:webSend
%d2:WebSend
+
end
End
 
 
</p>
 
</p>
  
===Request-cancellation errors===
+
==Request-cancellation errors==
 +
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
 
<ul>
 
<ul>
<li><var>XmlDoc</var> does not contain an <var>Element</var>.
+
<li>Method object <var class="term">doc</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:WebSend footer}}
+
<ul>
 +
<li>Use the <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> function to serialize an <var>XmlDoc</var> for sending in some other fashion than as a Web response. </li>
  
<ul>
 
<li>Use the <var>[[Serial (XmlDoc/XmlNode function)|Serial]]</var> function to
 
serialize an <var>XmlDoc</var> for sending in some other fashion than as a Web response.
 
 
<li>Additional serializing methods include:
 
<li>Additional serializing methods include:
 
<ul>
 
<ul>
<li><var>[[Print (XmlDoc/XmlNode subroutine)|Print]]</var>
+
<li><var>[[Print (XmlDoc/XmlNode subroutine)|Print]]</var> </li>
<li><var>[[AddXml]]</var> (<var>[[HttpRequest]]</var> class)
+
 
</ul>
+
<li><var>[[Audit (XmlDoc/XmlNode subroutine)|Audit]]</var>, <var>[[Trace (XmlDoc/XmlNode subroutine)|Trace]]</var> </li>
<li>The function that receives and deserializes a Web XML request is
+
 
<var>[[WebReceive (XmlDoc function)|WebReceive]]</var>.
+
<li><var>[[AddXml (HttpRequest subroutine)|AddXml]]</var> (<var>[[HttpRequest class|HttpRequest]]</var> class) </li>
 +
</ul> </li>
 +
 
 +
<li>For additional discussion about serialization, see [[XmlDoc API#Transport: receiving and sending XML|Transport: receiving and sending XML]].</li>
 +
 
 +
<li>The function that receives and deserializes a Web XML request is <var>[[WebReceive (XmlDoc function)|WebReceive]]</var>. </li>
 
</ul>
 
</ul>
 +
{{Template:XmlDoc:WebSend footer}}

Latest revision as of 21:08, 18 March 2014

Serialize XmlDoc as Web response (XmlDoc class)

WebSend converts an XmlDoc to its textually represented XML document to be sent in a response on a Janus Web Server thread. The process of converting to a text string is called serialization, because the text representation of a document is called the serial form.

The serialized output of WebSend is a UTF-8 text string. This output is added to the output buffer that is sent by a subsequent invocation of $Web_Done or $Web_Form_Done.

Syntax

doc:WebSend[( [options])]

Syntax terms

doc An expression that points to the XmlDoc whose content is to be serialized.
options A blank delimited string that can contain one or more (but no duplications) of the following options.

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 may also specify CR, LF, CRLF, or Newline (see below). If Indent is specified and no line-end options are also specified, Newline is implied.
  • CR (carriage-return), LF (linefeed), CRLF (carriage-return followed by a linefeed), or Newline (line-end set for the Janus Web connection)
    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

  • The method object, doc, must be well-formed (that is, it must contain an Element node).
  • The output line-breaking options make the serialized stream easier to read, for example, for a browser's "view page source" facility to display XHTML produced with Janus SOAP.
  • 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 Sirius Mods Version 7.6, this convention was not strictly observed.

Examples

The following Janus Web Server program uses WebReceive to obtain the XML document from the HTTP request, then uses WebSend to buffer some of the received data:

begin %d object xmlDoc %d = new %d:webReceive %d2 object xmlDoc %d2 = new %d2:loadXml('<sum>' with - %d:value('/*/*[1]') + %d:value('/*/*[2]') - with '</sum>') %d2:webSend end

Request-cancellation errors

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

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

See also