LoadXml (XmlDoc/XmlNode function)
[Requires Janus SOAP]
The LoadXml callable function converts a text string representation of an XML document into an XmlDoc, or a text string representation of an XML fragment into one or more children of an Element XmlNode. This process is called deserialization, because the text representation of a document is called the serial form.
LoadXml returns a zero value if the deserialization is successful; it returns a non-zero value if deserialization is unsuccessful, the ErrRet option is used, and the particular error is tolerated.
[%errorPosition =] nr:LoadXml( input, [options]) Throws XmlParseError
|%errorPosition||A %variable set to 0 if the deserialization is successful. If |
|nr||An expression that points to the XmlDoc or XmlNode to contain the deserialized representation of the XML document or fragment, respectively.
If an XmlDoc, it must be EMPTY (see XmlDoc states) prior to invoking LoadXml. If an XmlNode that is the root node of an XmlDoc, the XmlDoc must be EMPTY.
|input||The byte string or Stringlist to be deserialized. If a Stringlist, input consists of the concatenation of the Stringlist items with insertion of line-end characters at the end of each item.
If the nr method object is an XmlDoc or the root node of an XmlDoc, input must be valid as an entire XML document (for example, only one top-level element). If nr is a non-root XmlNode, input must be an XML fragment, that is, a substring of a serialized XML document, such that:
|options||Any valid combination of the following terms:
LoadXML can throw the following exception:
- If the method encounters a parsing error, properties of the exception object may indicate the location and type of problem.
- As of Sirius Mods version 7.5,
version="1.1"is accepted in the input to be deserialized. Formerly, only
- None of the options terms may be specified twice.
- The options terms may be specified in any case.
For example, you can use
- If the LoadXml method object is an XmlDoc or a root XmlNode,
LoadXml will accept any of the input character sets specified below.
The correspondence between these input character sets and the value of
encodingin the XML declaration is explained in the Usage notes for the Encoding]] property of an XmlDoc, and it is also shown in the following two tables.
In both tables below, all of the values of
encodingin the XML declaration must be specified in all-uppercase letters, and n is a digit from 1 to 9 in the
Input bytestream XML declaration ASCII codes below X'80' UTF-8, ISO-8859-n, or none ASCII codes up to X'FF' ISO-8859-n UTF-8 (with characters above X'7F') UTF-8 or none UTF-16 UTF-16 or none EBCDIC UTF-8, ISO-8859-n, or none Unicode (SOUL) UTF-8, ISO-8859-n, or none XML declaration Input bytestream UTF-8 UTF-8 (which includes ASCII codes below X'80'), EBCDIC, or Unicode UTF-16 UTF-16 (including a two byte order mark bytes as a preamble to the XML document input stream) ISO-8859-n ASCII codes up to X'FF', EBCDIC, or Unicode none UTF-8, UTF-16, ASCII, EBCDIC, or Unicode
In certain LoadXml error cases (for example, an input containing an ASCII code above
X'7F'without an XML declaration containing ISO-8859-n), a group of error messages is issued to display:
- A line that contains the erroneous string as received
- A line with an ASCII-to-EBCDIC translation of the string
- Additional lines that display the input byte halves in base 16
For example, the following messages are output after an 8-bit ASCII input fails because no accompanying ISO-8859-n encoding was specified:
MSIR.0668: XML doc parse error: invalid first byte of UTF-8 encoding near or before position 14 MSIR.0708: C: ???????????????? MSIR.0708: E: copyright(?)</A> (ASCII to EBCDIC) MSIR.0708: X: 6677766672A23243 MSIR.0708: X: 3F0929784899CF1E MSIR.0665: |
- If the LoadXml method object is a non-root XmlNode, LoadXml accepts a Unicode string or a bytestream it treats as EBCDIC.
- As described in Support for the ASCII subset of Unicode, serializing with LoadXml may require translation of the input document using the Unicode tables. This depends on the version of the Sirius Mods (that is, whether XmlDocs are maintained in EBCDIC or Unicode) and on which of the input character sets described above is used.
- LoadXml does not provide for inserting an Attribute
into an Element node by using an XML fragment.
For example, the following does not achieve it:
%d Object XmlDoc Auto New %n Object XmlNode %n = %d:AddElement('top') %n:LoadXml('foo="bar"') %d:Print
The input to LoadXml above is simply stored as the character content of the Element containing the fragment, so the result is:
To add the Attribute
foowith the value
bar, replace LoadXml in the example above with the AddAttribute updating method:
This produces the result:
Another situation where an updating method does what LoadXml does not is controlling the formatting of empty XML elements. This is described in Information form and content.
- If the method object refers to the Root node of an XmlDoc, the
LoadXml method in the XmlNode class behaves
exactly as the LoadXml method in the XmlDoc class.
%d Object XmlDoc Auto New %n Object XmlNode %n = %d:SelectSingleNode %n:LoadXml('<?xml version="1.0"?><top><inner/></top>')
When the Root node is the method object, the serialized input must be a legal XML document (for example, the XmlDoc must be Empty, and the serialized input must contain exactly one top-level element).
- 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 applies in all other cases. As described in the Normalized line-end, 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
- has the
xml:spaceattribute with the value
- is contained in
<b>A</b>with that attribute and value, and there is no element that is a descendent of
<b>A</b>and an ancestor of
xml:spaceattribute with the value
Elements that are not protected by the
xml:space="preserve"attribute have whitespace handled according to the option in effect for the deserialization.
- has the
- There is no whitespace normalization comparable to the LoadXml whitespace-handling options for the Add and Insert...Before functions that create a Text node (AddElement, InsertElementBefore, AddText, and InsertTextBefore).
- Whitespace normalization applies to the characters in the input serialized string, not to the values after entity substitution. See Example 4, below.
- If input is a Stringlist, LoadXml inserts a linefeed character after each item in the Stringlist as part of concatenation prior to deserialization. The linefeed is then subject to the method's whitespace handling options, so it is usually removed (as leading or trailing whitespace).
- 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, say, 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 the Serial function.
Deserializing Unicode strings
The LoadXml AllowUntranslatable option lets you deserialize Unicode strings that contain characters that are not translatable to EBCDIC. For example, LoadXml accepts the Unicode trademark character (U+2122) only if you specify AllowUntranslatable, as in the following.
%u is unicode Initial('™':U) %nod:LoadXml(%u, 'AllowUntranslatable')
If you remove AllowUntranslatable, this LoadXml statement fails, because the Unicode trademark character does not translate to an EBCDIC character. By default, the method detects any untranslatable characters in the serialized input XML document; it also throws an XmlParseError exception with reason UntranslatableUnicode (unless the ErrRet option is specified).
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:LoadXml ... %val Longstring %val = %doc:Value(%xpath)
Although the Value property returns a Unicode string,
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 LoadXml 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 (like the Value property statement above) 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, for example, shows a way to get the benefit of specifying AllowUntranslatable while limiting the risk of request cancellation.
In the following example, it is believed that only the
contain untranslatable Unicode among all the data accessed from the XML document:
%resp:LoadXml(%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 "Add" or "Insert" methods that "directly store" into an XmlDoc. For example, the following fragment adds an Element node with a value that is the Unicode trademark sign:
Note: LoadXml accepts input that contains XML hex character references but not input that contains XHTML entity references (other than the five predefined entities described in "Entity references". For example, this statement successfully loads a copyright character:
And this statement successfully loads a greater-than sign:
But this statement with a copyright character entity fails:
You can load a copyright character, however, if you decode the reference and convert to Unicode before the deserialization. For example:
For more information about working with Unicode characters, see Strings and Unicode with the XmlDoc API.
Using the ReplaceUnicode option
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:
The result is:
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):
The result is also:
In this case,
U+2122 does not occur in the input character stream, but it is the value of the character reference.
- It is an error to be processing a replacement string within a character reference. For example, assume the following two lines are in CCAIN:
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 '²':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 "less than" character (<) that is encountered in the replacement string ends the element content:
- 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.
- The following code creates the XmlDoc representation of the indicated XML document:
%d object xmlDoc %d = new %d:loadXml('<zen>The Buddha dog says</zen>')
- The following code creates an XML document as plain text for a test (or for some other application):
%d object xmlDoc %d = new %sl object stringlist %sl = new text to %sl <test> <test2> supercalifragilisticexpailodocious </test2> </test> end text %d:loadXml(%sl)
- The following code calls a subroutine which uses the ErrRet option:
%d object xmlDoc %d = new %s longstring ... setup the (serialized) document in %s %d = new call intoXML(%d, %s) ... do interesting things with the XmlDoc ... setup another document in %S call intoXML(%d, %s) ... subroutine intoXML(%d object xmlDoc, %s longstring) if %d:loadXml(%s, 'ErrRet') then ... error handling code ... end if end subroutine
- As stated for the options argument in the LoadXml syntax, whitespace normalization applies to the characters in the input serialized string, not the values after entity substitution. Therefore the values of elements
foo2created by the following two LoadXml invocations are different:
%t = $X2C('05') %d:loadXml('<foo1>' With %t With %t with '</foo1>', - 'wsptoken') %d2:loadXml('<foo2>		' with '</foo2>', - 'wsptoken')
- In the following fragment, element
a, which contains leading and intermediate whitespace, is deserialized with the WspToken option, then printed:
... %d object xmlDoc auto new %le string len 16 %le = $X2C('0D25') %d:loadXml('<a foo=" bar " > x' with %le - with 'y</a>', 'WspToken') print %d:serial('.', 'EBCDIC') ...
The result shows that WspToken removes the leading whitespace — in the Element content, not in the Attribute value — and replaces the intermediate linefeed (the initial carriage return removed as the XML standard normalization dictates) with a single blank:
<a foo=" bar ">x y</a>
If WspNewline is used instead, the leading whitespace remains (it contains no line-end characters), and the intermediate linefeed (represented below by a question mark) also remains (it is not leading or trailing):
<a foo=" bar "> x?y</a>
In this example, using the WspPreserve option gives the same result as WspNewline: no whitespace is removed, except for the initial carriage return due to the XML standard normalization.
If the example is changed slightly so the Text node includes only tab characters and a leading line-end character, and LinefeedNoTrailingTabs is specified:
... %le = $x2c('0D25') %tb = $x2c('05') %d:loadXml('<a foo=" bar " >' With %le with %tb - with %tb with '</a>', 'LinefeedNoTrailingTabs') print %d:serial('.', 'EBCDIC') ...
The resulting Text node contains only the line-end character:
<a foo=" bar ">?</a>
- The ParseXml function in the HttpResponse class has the same options as LoadXml. The following fragment requests, receives, and deserializes an XML document from a Web server:
%httpreq object httpRequest %httpresp object httpResponse %doc object xmlDoc %httpreq = new %doc = new %httpreq:URL = 'foo.com/bar' %httpresp = %httpreq:Get('HTTP_CLIENT') if %httpresp:ParseXML(%doc, 'ErrRet') then ... invalid document received from Web server end If
Note: If you use $Sock_Recv and LoadXml directly instead of using an HTTP Helper object, always use the BINARY option of $Sock_Recv, so that LoadXml can recognize the character encoding inherent in the serialized XML document.
Request cancellation errors
This list is not exhaustive: it does not include all the errors that are request cancelling.
- Method object doc is not EMPTY.
- An options argument is invalid.
- Insufficient free space exists in CCATEMP.
- A syntax error occurred in the representation of the XML document in input (this is tolerated if the ErrRet options value is specified).
- To deserialize a document (which has been POSTed or PUT) using Janus Web Server, use WebReceive.
- For other transport APIs, such as Janus Sockets or Model 204 MQ Series, LoadXml can be used to deserialize a document that has been received with the transport API. As mentioned in the example above, Janus Sockets has a convenient ParseXml method for deserializing an HTTP response.
- The function that serializes an XmlDoc as a UTF-8 or EBCDIC string is Serial.
- For more information about normalization, see Normalization during deserialization.
- For additional discussion about deserialization, see Transport: receiving and sending XML.