AddXml (HttpRequest subroutine)

From m204wiki
Revision as of 00:05, 17 June 2011 by JAL2 (talk | contribs)
Jump to navigation Jump to search

Add an XmlDoc to POST data for this request (HttpRequest class)


This subroutine adds a Janus SOAP XmlDoc object instance to the HTTP Post data that is subsequently sent on a Post method invocation.

Syntax

httpRequest:AddXml( doc, [options])

Syntax terms

%httpreq A previously defined and instantiated HttpRequest object.
doc An XmlDoc object that contains an instantiated XmlDoc object.
xmloptions Any combination of the following options (but single occurrences only):
  • AllowXmlDecl or NoXmlDecl
    AllowXmlDecl, the default, produces the "XML Declaration" (that is, <?xml version=...?>) if the value of the Version property in doc is a non-null string. NoXmlDecl omits the XML declaration.
  • 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.
Note: These options are described in greater detail in "XmlDoc API serialization options"

Usage notes

  • The XmlDoc that is passed is serialized into the post data of the request being built. It is not required that you serialize the XmlDoc first.
  • Invoking this method erases any post data previously added by AddXml or AddLongString method calls.
  • If you do not explicitly set a content-type HTTP request header via AddHeader, AddXml generates a content-type header of "text/xml" upon a Post. To suppress this automatic header generation, you can set the AutoSendXmlContentType property to False.
  • The xmloptions may be specified in any case, for example, you can use either NoXmlDecl or noxmldecl, interchangeably.
  • If one of the line-end (CR, LF, CRLF) options or if Indent is specified, and an element to be serialized has the xml:space="preserve" 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 xml:space="default" attribute has no effect under these options: 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 xml:space="preserve".

Examples

The following example shows the effect of the NoEmptyElt option:

Begin %d is object Xmldoc %d = new %htr is object HttpRequest %htr = new %sl is object Stringlist %sl = new Text To %sl <top p:abc="p" q:xyz="q" xmlns:p="urn:p" xmlns:q="http://q.com" name="t" id="z15" /> End Text %d:LoadXml(%sl) %htr:AddXml(%d, 'NoEmptyElt') Print %d:Serial(, 'EBCDIC NoEmptyElt') End

The Print statement above (which uses the Serial method of the Janus SOAP XmlDoc API) displays the resulting XmlDoc content added to the HttpRequest object (formatted with some newlines for the sake of instruction):

<top xmlns:p="urn:p" xmlns:q="http://q.com" p:abc="p" q:xyz="q" name="t" id="z15"> </top>

NoEmptyElt produces an STag (<top ...>) and an ETag (</top>) for an empty element, rather than just the EmptyElemTag (<top ...>).


See also