WebSend (XmlDoc subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(42 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Serialize XmlDoc as Web response</b></span>
{{Template:XmlDoc:WebSend subtitle}}
[[Category:XmlDoc methods|WebSend subroutine]]
<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'''
[[Category:XmlDoc API methods]]
form.
<!--DPL?? Category:XmlDoc methods|WebSend subroutine: Serialize XmlDoc as Web response-->
<!--DPL?? Category:XmlDoc API methods|WebSend (XmlDoc subroutine): Serialize XmlDoc as Web response-->
<!--DPL?? Category:System methods|WebSend (XmlDoc subroutine): Serialize XmlDoc as Web response-->
<p>
WebSend is a member of the [[XmlDoc class]].
</p>


This subroutine converts an XmlDoc 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 [[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.
==Syntax==
This output is added to the output buffer that is sent by a subsequent
{{Template:XmlDoc:WebSend syntax}}
invocation of $Web_done or $Web_form_done.
===Syntax terms===
===Syntax===
<table class="syntaxTable">
  Call doc:WebSend([options])
<tr><th>doc</th>
<td>An expression that points to the <var>XmlDoc</var> whose content is to be serialized. </td></tr>


====Syntax Terms====
<tr><th>options</th>
<dl>
<td>A blank delimited string that can contain one or more (but no duplications) of the following options.  
<dt>doc
<p class="note">'''Note:''' These options are described in greater detail in [[XmlDoc API serialization options|"XmlDoc API serialization options"]]. </p>
<dd>An expression that points to the XmlDoc
<ul>  
whose content is to be serialized.
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b><br>
<dt>options
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>
<dd>Any combination of the following options (but single occurrences only):
<ul>
<li><b>AllowXmlDecl</b> or <b>NoXmlDecl</b>


AllowXmlDecl, the default, produces the
<li><b>Indent <i>n</i></b><br>
XML declaration (that is, <?xml&thinsp.version=...?>)
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 the declaration was set (see [[Version (XmlDoc property)|Version]]).
If <var>Indent</var> is specified and no line-end options are also specified, <var>Newline</var> is implied. </li>
NoXmlDecl indicates that the XML declaration is not produced.
<li><b>Indent</b> <i><b>n</b></i>


Inserts space characters (and line-ends, as described for the next option)
<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>
into the serialized string such that
Inserts one of these line-end options to provide line breaks in the serialized output. </li>
if the string is broken 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.


For example, <tt>Indent 2</tt> would produce spacing like the following:
<li><b>NoEmptyElt</b><br>
<pre>
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>).
    <top>
<p>
      <leaf1 xx="yy">value</leaf1>
<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>
      <sub>
        <leaf2>value</leaf2>
      </sub>
    </top>
</pre>


<i>n</i> is a non-negative integer, and its maximum value
<li><b>OmitNullElement</b><br>
(as of ''Sirius Mods'' version 7.0) is 254.
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>


Indent may be used with one of the line-end options, above,
<li><b>SortCanonical</b><br>  
including Newline.
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>
If Indent is specified and no line-end options are also specified,
Newline is implied.
<li>One of the '''line-end options''' below, to provide line breaks in
the output after any of the following is serialized:
<ul>
<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>
</ul>
<dl>
</td></tr>
<dt>CR
</table>
<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.
<dt>Newline
<dd>Insert the line-end sequence defined for this [[Janus Web Server]] connection
(by the JANUS DEFINE command or $WEB_SET)
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
==Usage notes==
followed by an end tag.
<ul>
For example:
<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).
<pre>
<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>.
    <middleName></middleName>
<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.
</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
no Attributes will not be serialized, unless it is the top level Element in
the subtree being serialized.
The serialization of a child-less and Attribute-less Element is omitted,
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
(one or more), and all of its children are Attribute-less and child-less,
then that parent Element is serialized, even though its content in the
serialization is empty.
That parent is serialized with a start tag and an end tag
(and an inserted line separator, if called for by the serializing
method's parameter options).
 
For example, if the Serial method display of an XmlDoc in tree format
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 Serial 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).
 
Added in ''Sirius Mods'' version 6.9 as a step towards support for canonicalization,
this option is superseded by the Serial method ExclCanonical
option ([[??]] refid=exclcan.), which provides full support for
canonicalized serialization.
</ul>
</ul>


</dl>
==Examples==
===Usage Notes===
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:
<p class="code">begin
  %d object xmlDoc
  %d = new
  %d:webReceive
  %d2 object xmlDoc
  %d2 = new
  %d2:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<sum>' with -
      %d:[[Value_(XmlDoc/XmlNode_property)|value]]('/*/*[1]') + %d:value('/*/*[2]') -
      with '</sum>')
  %d2:webSend
end
</p>


==Request-cancellation errors==
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
<ul>
<ul>
<li>The <i>XmlDoc</i> method object must be well-formed (that is,
<li>Method object <var class="term">doc</var> does not contain an <var>Element</var>.
it must contain an Element node).
<li>An <var class="term">options</var> setting is invalid.
For more information about well-formed documents, see [[??]] refid=welform..
<li>Insufficient free space exists in CCATEMP.
<li>The output line-breaking ''options'' make the serialized stream
easier to read, for example, for a browser's &ldquo;view page source&rdquo; facility
to display XHTML produced with [[Janus SOAP]].
<li>As of version 6.7, the WebSend 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>
<li>For Attribute nodes: tab, carriage return, and linefeed
<li>For Text nodes: carriage return
</ul>
</ul>


Since the character references are not subject to the standard XML whitespace
==See also==
normalization ([[??]] refid=normwhi.),
<ul>
a serialized document (or subtree) that is then deserialized
<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>
will retain this whitespace.


These character references are used:
<li>Additional serializing methods include:
<dl>
<ul>
<dt>tab
<li><var>[[Print (XmlDoc/XmlNode subroutine)|Print]]</var> </li>
<dd>&amp;#x9;
<dt>CR
<dd>&amp;#xD;
<dt>LF
<dd>&amp;#xA;
</dl>


The EBCDIC and corresponding ASCII encodings of the characters is:
<li><var>[[Audit (XmlDoc/XmlNode subroutine)|Audit]]</var>, <var>[[Trace (XmlDoc/XmlNode subroutine)|Trace]]</var> </li>
<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>
<li><var>[[AddXml (HttpRequest subroutine)|AddXml]]</var> (<var>[[HttpRequest class|HttpRequest]]</var> class) </li>
===Example===
</ul> </li>


The following [[Janus Web Server]] program uses
<li>For additional discussion about serialization, see [[XmlDoc API#Transport: receiving and sending XML|Transport: receiving and sending XML]].</li>
WebReceive to obtain the XML document from the HTTP request,
then uses WebSend to buffer some of the received data:
<pre>
    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
</pre>


===Request-Cancellation Errors===
<li>The function that receives and deserializes a Web XML request is <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>
 
 
===See Also===
 
<ul>
<li>Use the [[Serial (XmlDoc/XmlNode function)|Serial]] function to
serialize an XmlDoc for sending in some other fashion than as a Web response.
<li>Additional serializing methods include:
<ul>
<li>[[Print (XmlDoc/XmlNode subroutine)|Print]]
<li>AddXml (HttpRequest class, described in the [[Janus Sockets]]R.)
</ul>
<li>The function that receives and deserializes a Web XML request is
??[[WebReceive (XmlDoc function)|WebReceive]].
</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

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=WebSend_(XmlDoc_subroutine)&oldid=68074"