AddXml (HttpRequest subroutine)

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".
• The following example shows the effect of the SortCanonical 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" xmlns="urn:default" name="t" id="z15" /> End Text %d:LoadXml(%sl) %htr:AddXml(%d, 'SortCanonical NoEmptyElt') Print %d:Serial(, 'EBCDIC SortCanonical 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="urn:default" xmlns:p="urn:p" xmlns:q="http://q.com" id="z15" name="t" q:xyz="q" p:abc="p" > </top>

  Comments:

  • The reason for the name (SortCanonical) is that this ordering is part of the specification of the Canonical XML Recommendation (http://www.w3.org/TR/xml-c14n) and the Exclusive Canonical XML Recommendation (http://www.w3.org/TR/xml-exc-c14n), which constrain serializations to facilitate processing such as digital signatures.
  • Notice the use of the NoEmptyElt option above. This produces an STag (<top ...>) and an ETag (</top>) for an empty element, rather than just the EmptyElemTag (<top ...>). The canonical XML recommendations state that an STag/ETag pair, rather than an EmptyElemTag, is the serialization for an empty element.
  • Although SortCanonical uses the Unicode sort sequence, this is limited to Unicode values less than 256 (as of version 6.9 of Janus SOAP, so it is accomplished with an 8-byte EBCDIC to 8-byte Unicode table, which is (for all intents and purposes) merely an EBCDIC-to-ASCII translation.

See also

HttpRequest class HttpResponse class	List of HttpRequest methods List of HttpResponse methods List of HTTP Helper methods	HttpRequest methods syntax HttpResponse methods syntax
Notation conventions for methods