ParseXml (HttpResponse function)

<section begin=dpl_desc/><section end=dpl_desc/>

ParseXML is a member of the HttpResponse class.

This method helps you access the document/content from Get, Post, and Send operations. ParseXML deserializes returned XML data into the Janus SOAP XmlDoc object you specify. Working with Janus SOAP XmlDoc objects is described in detail in the Janus SOAP Reference Manual.

Syntax

%rc = %httpresp:ParseXML(%xmldoc, [xmloptions])

Syntax terms

%rc	A numeric variable. Successful deserialization returns 0; failure returns a non-zero value.
%httpresp	A reference to an HTTPResponse object that was returned by a Get, Post, or Send method of an HTTPRequest object.
%xmldoc	An object of type Janus SOAP XmlDoc that contains an instantiated XmlDoc object, which must be EMPTY.
xmloptions	Any valid combination of the following (which are the same as the options of the LoadXML method of the Janus SOAP XmlDoc object): AllowUntranslatable Allows all valid Unicode strings into the XML document. When this option is not specified, Unicode strings that are not translatable to EBCDIC are not allowed. As described in "Deserializing Unicode strings", it is recommended that you use AllowUntranslatable only if the application checks for translatability when accessing parts of the XmlDoc that may have untranslatable Unicode content. The AllowUntranslatable option is available as of version 7.6 of the Sirius Mods. CrPreserve All whitespace characters in Element content are preserved, including carriage return. Unlike all other deserialization options, a carriage return in Element content does not undergo the normalization specified in the XML standard (and described in "Normalizing whitespace characters"). CrPreserve is mutually exclusive with the WspNewline, WspToken, and WspPreserve options, and with the LinefeedNoTrailingTabs option. The CrPreserve option was added in version 7.5 of the Sirius Mods, as well as implemented with a maintenance zap to the 7.4 Sirius Mods. DTDIgnore A “<!DOCTYPE&thinsp....>” clause may be present in the document, and it should be ignored. In any case, the DTD is not processed. The default behavior, that is, if DTDIgnore is not present, is to treat “<!DOCTYPE&thinsp....>” as a syntax error. DTD_Ignore is a synonym for DTDIgnore. ErrRet Errors during deserialization are tolerated, the method object is not updated (retains its pre-call state), and the request continues. If ErrRet is not present, any error will cancel the request. Note that some errors still cancel the request; errors tolerated when ErrRet is specified are: A syntax error in the text string representation of the XML document LinefeedNoTrailingTabs For a Text node that consists of an initial line-end character and one or more tab characters, this option normalizes the content so the result is a single line-end character. The initial line-end (also called "newline") character can be a linefeed character (LF) or a carriage-return (CR) by itself, or a carriage-return followed by a linefeed (CRLF), since (within Text nodes) all of these are normalized by the XML specification into a single line-end character. This option, added in Sirius Mods version 7.0, is compatible with, but takes precedence over, any of the other whitespace-handling options (WspNewline, WspToken, WspPreserve) except CrPreserve. See "Whitespace handling", below, for more information about this option and about whitespace handling. ReplaceUnicode Converts Unicode characters using the replacements (if any) specified at your site by The UNICODE command|UNICODE updating commands that use the Rep subcommand (for example, UNICODE Table Standard Rep U=2122 '(TM)'). The replacement is performed on all names, element and attribute values, comments, and PI “values” in the document, after any entity and character references have been converted to characters. For further discussion and examples, see the ReplaceUnicode discussion in "Usage Notes", below. WspNewline This option is designed to remove any whitespace inserted to make the structure of an XML document easier (for a person) to read. WspNewline removes the leading or trailing whitespace in the value of a Text node, if the whitespace sequence contains a newline (carriage return or linefeed) character. Note: This handling, the default whitespace option for this method, applies to the "physical value" of the representation of a Text node. In particular, markup such as a character reference (even of whitespace, for example, &#32;), a CDATA section, or any non-whitespace character delimits leading or trailing whitespace and is not affected. See "Whitespace handling", below, for more information about whitespace handling. WspPreserve All whitespace characters in element content are preserved (after end-of-line normalization), as described below in "Whitespace handling". Note: Wsp_Preserve is a synonym for WspPreserve. WspToken Whitespace in element content is normalized using the XPath normalize() function (leading and trailing whitespace removed, intermediate strings of whitespace replaced by a single blank character). WspToken is a good substitute for WspNewline to remove leading and trailing whitespace in cases where blanks (or tabs) and not line-end characters were used to make the document structure more readable — if it is tolerable to collapse intermediate whitespace sequences to single space characters. See "Whitespace handling" for more information about whitespace handling.

Usage Notes

• ParseXML is equivalent to, but faster than, issuing the Janus SOAP XML text-conversion method LOADXml against the longstring returned by Content.bot
• If the content type header indicates HTML, XML, or plain text, ASCII-to-EBCDIC translation is performed. If the Clsock port definition specifies a translation table for ASCII-to-EBCDIC, that table is used instead of the default.
• None of the options may be specified twice.
• The options may be specified in any case. For example, you can use WspPreserve and wsppreserve, interchangeably.
• Whitespace handling
  • The “Wsp” whitespace-handling options (WspPreserve, WspNewline, and WspToken) and the CrPreserve whitespace option are mutually exclusive; if none of them is specified, WspNewline is in effect. Although the LinefeedNoTrailingTabs option is also concerned with whitespace, it is distinct from, yet compatible with, any of the three “Wsp” options, but it is not compatible with the CrPreserve option.
  • Except for CrPreserve, the whitespace-handling options are applied after the XML standard whitespace conversions that Janus SOAP always applies. As described in "Normalizing whitespace characters", the standard specifies that all carriage return/linefeed sequences and carriage return sequences are to be converted to linefeeds when deserializing. Using the CrPreserve option bypasses this rule.
  • The whitespace-handling options do no whitespace conversion (beyond the XML standard conversions) on element content that is “protected” by the xml:space="preserve" attribute. “Protected” by the xml:space="preserve" attribute means an element E that either:
    • has the xml:space attribute with the value preserve
    • is contained in an element A with that attribute and value, and there is no element that is a descendent of A and an ancestor of E with the xml:space attribute with the value default

    Elements that are not protected by the xml:space="preserve" attribute have whitespace handled according to the option in effect for the deserialization.

  • Using WspNewline or WspToken reduces the space consumed by individual Text nodes, and in some cases collapses all whitespace content between markup to the null string, so it is not stored as a Text node. This reduces the storage required by the XmlDoc, speeds up XPath and node access processing, and makes the output of the Print subroutine easier to read.
  • The LinefeedNoTrailingTabs option only affects Text nodes that contain an initial line-end character followed by any number of tabs and nothing else. The LinefeedNoTrailingTabs effect on such a Text node, whether it is specified with or without any of the “Wsp” options, is to store the value of the node as a single line-end character. One example of the use of the LinefeedNoTrailingTabs option is an input XML document to be deserialized for which both of the following are true:
    • A digital signature is needed of a subtree in the document.
    • The input subtree contains a linefeed and one or more tabs that separate markup, and the linefeed must be kept but the tabs discarded for the signature.

    For information about exclusive canonicalization, serialization expressly designed for digital signatures, see "Canonicalization".

  • Deserializing Unicode strings
    • The ParseXml AllowUntranslatable option lets you deserialize Unicode strings that contain characters that are not translatable to EBCDIC. Otherwise, such characters in an input XML document are detected, an XmlParseError exception with reason UntranslatableUnicode is thrown, and the request is canceled. This default detection of non-translatable characters may suit your purposes. That is, it ensures that subsequent access to the deserialized content is performed without any Unicode to EBCDIC translation errors. For example:

      %doc:ParseXml ... %val Longstring %val = %doc:Value(%xpath)

      The assignment to the EBCDIC string %val will not fail due to a Unicode translation problem: if there is any untranslatable Unicode (including, of course, strings in the XML document which your application never accesses), the ParseXml operation fails.

      If you use AllowUntranslatable, all Unicode characters in a serialized input XML document are allowed and stored in the XmlDoc. Your stored data may contain content that is not translatable to EBCDIC, however. A subsequent attempt to access such content that performs Unicode to EBCDIC translation might cause request cancellation. You should therefore use AllowUntranslatable only if there is also a check for translatability when parts of the XmlDoc that may have non-translatable Unicode content are accessed.

      The code below shows a way to get the benefit of specifying AllowUntranslatable while limiting the risk of request cancellation. In the example, it is believed that only the element comments might contain untranslatable Unicode among all the data accessed from the XML document:

      %resp:ParseXml(%doc, 'AllowUntranslatable') ... %uVal Unicode %val Longstring %uVal = %node:Value('comments') Try %val = %uVal:UnicodeToEbcdic Catch CharacterTranslationException %val = %uVal:UnicodeToEbcdic(CharacterEncode=True) Print 'Untranslatable Unicode, character encoded:' - And %val End Try

    Note: Unicode values, untranslatable or not, are always allowed when they are added to an XmlDoc using one of the Janus SOAP XML Add or Insert methods which “directly store” into an XmlDoc. For example, the following fragment adds an Element node with a value that is the Unicode trademark sign:

    %node:AddElement('notation', '&#x2122;':U)

  • The ReplaceUnicode option lets you replace certain Unicode input characters with those characters you have explicitly specified (by UNICODE commands in your site's Model 204 CCAIN stream). For example, assume the following command is in CCAIN:

    UNICODE Table Standard Rep U=2122 '(tm)'

    Given the above command, the ReplaceUnicode option for LoadXml is shown in the following fragment:

    %u Unicode Initial('<a>') %u = %u:UnicodeWith('2122':X:Utf16ToUnicode) %u = %u:UnicodeWith('</a>':U) %d:LoadXml(%u, 'ReplaceUnicode') %d:Print

    The result is:

    <a>(tm)</a>

    In the preceeding example, the stream of input characters to LoadXml contains the Unicode character U+2122. Since the ReplaceUnicode option applies to both the stream of input characters and to the character value of character references, consider the following fragment (assuming the same CCAIN line as above):

    %d:LoadXml('<a>&#x2122;</a>', 'ReplaceUnicode')

    The result is also:

    <a>(tm)</a>

    In this case, U+2122 does not occur in the input character stream, but it is the value of the character reference.

    Notes:

    • It is an error to be processing a replacement string within a character reference. For example, assume the following two lines are in CCAIN:

      * Replace superscript 2 with digit '2': UNICODE Table Standard Rep U=00B2 '2'

      Given the above command, the following fragment gets a parse error, because the replacement string is being used as part of a character reference:

      %d:LoadXml('<a>&#x' With '&#xB2;':U With ';</a>', - 'ReplaceUnicode')

      As a consequence of this rule, a replacement string should not contain an ampersand character (assuming that the ReplaceUnicode option will be used).

    • Replacement of a Unicode character due to the ReplaceUnicode option is only done while processing names and values in the XML document. It is an error if the end of the name or value occurs and the replacement string has not been exhausted. In other words (again assuming that the ReplaceUnicode option will be used), a replacement string should not have “XML markup” that might end a string, such as a quotation mark or a left angle bracket (<). For example, assume the following line is in CCAIN:

      UNICODE Table Standard Rep U=2122 '(trademark)<tm>'

      Given the above command, the following fragment gets a parsing error, because the '<' that is encountered in the replacement string ends the element content:

      %d:LoadXml('<a>&#x2122;</a>':U, 'ReplaceUnicode')

    • If a parsing error occurs after processing a Unicode character that has been replaced, the error display of the input stream will contain the replacement string, and the replaced character will not be displayed. However, if the character being replaced was introduced as a character reference, the character reference remains in the display of the input stream.

Example

In the following example, ParseXml deserializes into %doc the XML data (stored in %httpresp) returned from a Post call:

%httpreq is Object HttpRequest %httpreq = new ... %httpresp = %httpreq:Post('HTTPCLI') %doc is Object XmlDoc %doc = New %httpresp:ParseXml(%doc, 'ErrRet') %doc:Print ...