AddXml (HttpRequest subroutine)

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

The AddXml 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

httpRequest	A previously defined and instantiated HttpRequest object.
doc	A previously defined and instantiated XmlDoc object.
options	Any combination of the following options (but single occurrences only). Note: These options are described in greater detail in "XmlDoc API serialization options". 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 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 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 options 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. Additionally, 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 Janus SOAP XmlDoc API Serial method) 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>

Comments:

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

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