AddXml (HttpRequest subroutine)

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

Syntax

Syntax terms

%httpreq	A previously defined and instantiated HTTPRequest object.
%xmldoc	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&amp;thinsp.version=...?>) if the declaration was already defined in %xmldoc. NoXmlDecl omits the XML declaration. Indent n The display of each lower level in the serialized subtree is indented n spaces from the previous level's starting point, where n is a non-negative integer. This option may be used with one of the line-end options, below, including Newline. If Indent is specified and no line-end options are also specified, Newline is implied. Indent 2 (with a line-end option) would produce: <top> <leaf1 xx="yy">value</leaf1> <leaf2>value</leaf2> </top> One of the line-end options below, to provide line breaks in the output after any of the following in %xmldoc is serialized: An element start-tag, if it has any non-text node children An empty element tag, or an empty element end-tag A processing instruction (PI) A comment A text node, if it has any siblings CR Insert a carriage-return character as the line-end sequence in the above cases. LF Insert a line-feed character as the line-end sequence in the above cases. CRLF Insert a carriage-return character followed by a line-feed character as the line-end sequence in the above cases. Newline Insert the line-end sequence defined for this HTTP Request object, if any, as the line-end sequence in the above cases. NoEmptyElt This indicates that an empty element in %xmldoc is serialized with its start tag followed by an end tag. For example: <middleName></middleName> If this option is not specified, the default is to serialize an empty element with an empty element tag: <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. 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 Attibute-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 a tree display of %xmldoc is the following when OmitNullElement is not specified: <top> <middle> <empty/> <p:empty2 xmlns:p="uri:stuff"/> </middle> </top> This is the display of %xmldoc with the OmitNullElement option specified: <top> <middle> </middle> </top> The OmitNullElement option is available as of Sirius Mods version 7.3. SortCanonical 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, 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). This option was added in Sirius Mods version 6.9 as a step towards support for canonicalization. As of version 7.0, comprehensive support for canonicalized serialization is provided (only) by the Serial method ExclCanonical option, described in the Janus SOAP Reference Manual. SortCanonical is described in greater detail at the end of &amp;ldquo;Usage notes,&amp;rdquo; below.

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.
• As of Sirius Mods version 6.6, 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".
• As of version 6.7, the AddXml method uses the character references specified in the XML Canonicalization specification (http://www.w3.org/TR/xml-c14n) to display the following characters:
  • For Attribute nodes: tab, carriage return, and linefeed
  • For Text nodes: carriage return

  Since the character references are not subject to the standard XML whitespace normalization (so not removed), a serialized document (or subtree) that is then deserialized will retain this whitespace.

  These character references are used:

  tab		
  CR	
  LF	


  The EBCDIC and corresponding ASCII encodings of the characters is:

   	EBCDIC	ASCII
  tab	X'05'	X'09'
  CR	X'0D'	X'0D'
  LF	X'25'	X'0A'

  For more information about XML document whitespace handling, see "Normalizing whitespace characters".

• 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 (XmlDoc/XmlNode function) 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&hyph.c14n) and the Exclusive Canonical XML Recommendation (http://www.w3.org/TR/xml&hyph.exc&hyph.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.

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.
• As of Sirius Mods version 6.6, if you do not explicitly set a content-type HTTP request header via AddHeader, AddXml generates a content-type header of &amp;ldquo;text/xml&amp;rdquo; 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".
• As of version 6.7, the AddXml method uses the character references specified in the XML Canonicalization specification (http://www.w3.org/TR/xml-c14n) to display the following characters:
  • For Attribute nodes: tab, carriage return, and linefeed
  • For Text nodes: carriage return

  Since the character references are not subject to the standard XML whitespace normalization (so not removed), a serialized document (or subtree) that is then deserialized will retain this whitespace.

  These character references are used:

  tab		
  CR	
  LF	


  The EBCDIC and corresponding ASCII encodings of the characters is:

   	EBCDIC	ASCII
  tab	X'05'	X'09'
  CR	X'0D'	X'0D'
  LF	X'25'	X'0A'

  For more information about XML document whitespace handling, see "Normalizing whitespace characters".

• 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 (XmlDoc/XmlNode function) 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&amp;hyph.c14n) and the Exclusive Canonical XML Recommendation (http://www.w3.org/TR/xml&amp;hyph.exc&amp;hyph.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.