WebSend (XmlDoc subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (fix broken →‎Usage notes)
m (1 revision)
(No difference)

Revision as of 17:26, 24 May 2011

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:
  • 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 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
    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.
These options are described in greater detail in "XmlDoc API serialization options"

Usage notes

  • The method object Doc must be well-formed (that is, it must contain an Element node). For more information, see "Well-formed documents and validation".
  • 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 &amp;quot;. Prior to "Sirius Mods" Version 7.6, this convention was not strictly observed.

Examples

  1. 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

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

See also

  • Use the Serial function to serialize an XmlDoc for sending in some other fashion than as a Web response.
  • Additional serializing methods include:
  • The function that receives and deserializes a Web XML request is WebReceive.