LoadXml (XmlDoc/XmlNode function) - Revision history

Dme: /* Using the ReplaceUnicode option */

2018-11-29T20:30:23Z

Using the ReplaceUnicode option

← Older revision		Revision as of 20:30, 29 November 2018
Line 405:		Line 405:
	For more information about working with Unicode characters, see [[XmlDoc API#Strings and Unicode with the XmlDoc API\|Strings and Unicode with the XmlDoc API]].		For more information about working with Unicode characters, see [[XmlDoc API#Strings and Unicode with the XmlDoc API\|Strings and Unicode with the XmlDoc API]].

	===Using the ReplaceUnicode option===		===<b id="ucdRep"></b>Using the ReplaceUnicode option===
	The <var>ReplaceUnicode</var> option lets you replace certain Unicode input characters with those characters you have explicitly specified (by <var>UNICODE</var> commands in your site's <var class="product">Model 204</var> CCAIN stream).		The <var>ReplaceUnicode</var> option lets you replace certain Unicode input characters with those characters you have explicitly specified (by <var>UNICODE</var> commands in your site's <var class="product">Model 204</var> CCAIN stream).

ELowell: /* Syntax terms */

2015-09-02T21:29:58Z

Syntax terms

← Older revision		Revision as of 21:29, 2 September 2015
Line 10:		Line 10:
	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>%errorPosition</th>		<tr><th nowrap>%errorPosition</th>
	<td>A %variable set to 0 if the deserialization is successful. If <code>ErrRet</code> is one of the <var class="term">options</var> used, <var class="term">%errorPosition</var> is set to the character position within <var class="term">input</var> at which an error is found.</td></tr>		<td>A %variable set to 0 if the deserialization is successful. If <code>ErrRet</code> is one of the <var class="term">options</var> used, <var class="term">%errorPosition</var> is set to the character position within <var class="term">input</var> at which an error is found.</td></tr>

JAL: /* Usage notes */

2014-03-18T17:50:29Z

Usage notes

JAL: /* See also */

2014-03-13T20:35:00Z

JAL: /* Usage notes */

2014-03-12T19:55:45Z

Usage notes

← Older revision		Revision as of 19:55, 12 March 2014
Line 130:		Line 130:
	</td></tr>		</td></tr>

	<tr><td><var>Unicode</var> (~~User Language~~)		<tr><td><var>Unicode</var> (SOUL)
	</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>		</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>
	</td></tr></table>		</td></tr></table>

JAL: /* Usage notes */

2014-03-12T19:54:51Z

Usage notes

← Older revision		Revision as of 19:54, 12 March 2014
Line 96:		Line 96:
	The correspondence between these input character sets and the		The correspondence between these input character sets and the
	value of <code>encoding</code> in the XML declaration is explained		value of <code>encoding</code> in the XML declaration is explained
	in the [[Encoding (XmlDoc property)#Usage notes\|"Usage notes"]] for the <var>Encoding</var>]]		in the [[Encoding (XmlDoc property)#Usage notes\|Usage notes]] for the <var>Encoding</var>]]
	property of an <var>XmlDoc</var>, and it is also shown in the following two tables. </p>		property of an <var>XmlDoc</var>, and it is also shown in the following two tables. </p>
	<p>		<p>
Line 178:		Line 178:
	<li>If the <var>LoadXml</var> method object is a non-root <var>XmlNode</var>, <var>LoadXml</var> accepts a Unicode string or a bytestream it treats as EBCDIC.		<li>If the <var>LoadXml</var> method object is a non-root <var>XmlNode</var>, <var>LoadXml</var> accepts a Unicode string or a bytestream it treats as EBCDIC.

	<li>As described in [[Unicode#Support for the ASCII subset of Unicode\|"Support for the ASCII subset of Unicode"]], serializing with <var>LoadXml</var>		<li>As described in [[Unicode#Support for the ASCII subset of Unicode\|Support for the ASCII subset of Unicode]], serializing with <var>LoadXml</var>
	may require translation of the input document using the <var>Unicode</var> tables.		may require translation of the input document using the <var>Unicode</var> tables.
	This depends on the version of the <var class="product">Sirius Mods</var> (that is, whether <var>XmlDoc</var>s are maintained in EBCDIC or <var>Unicode</var>) and on which		This depends on the version of the <var class="product">Sirius Mods</var> (that is, whether <var>XmlDoc</var>s are maintained in EBCDIC or <var>Unicode</var>) and on which
Line 185:		Line 185:
	<li>An XML fragment '''does not''' provide for inserting an Attribute		<li>An XML fragment '''does not''' provide for inserting an Attribute
	into an Element node.		into an Element node.
	For example, the following does not achieve it:		For example, the following '''does not''' achieve it:
	<p class="code">%d Object XmlDoc Auto New		<p class="code">%d Object XmlDoc Auto New
	%n Object XmlNode		%n Object XmlNode
Line 200:		Line 200:
	replace <var>LoadXml</var> in the example above with		replace <var>LoadXml</var> in the example above with
	<code>%n:[[AddAttribute (XmlNode function)\|AddAttribute]]('foo', 'bar')</code>. </p>		<code>%n:[[AddAttribute (XmlNode function)\|AddAttribute]]('foo', 'bar')</code>. </p>
			This produces the result:
			<p class="output"><top foo="bar"/> </p>

	<li>If the method object refers to the <var>Root</var> node of an <var>XmlDoc</var>, the		<li>If the method object refers to the <var>Root</var> node of an <var>XmlDoc</var>, the
Line 443:		Line 445:
	</p>		</p>

	<li>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.		<li>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.
	</ul>		</ul>
	</blockquote>		</blockquote>

JAL at 18:41, 10 March 2014

2014-03-10T18:41:33Z

Show changes

JAL: /* Deserializing Unicode strings */

2014-03-03T20:47:13Z

Deserializing Unicode strings

← Older revision		Revision as of 20:47, 3 March 2014
Line 351:		Line 351:
	End Try		End Try
	</p>		</p>
	'''Note:'''		<blockquote class="note">
			<p>'''Note:'''
	<var>Unicode</var> values, untranslatable or not, are always allowed		<var>Unicode</var> values, untranslatable or not, are always allowed
	when they are added to an <var>XmlDoc</var> using one of the "Add" or "Insert" methods that		when they are added to an <var>XmlDoc</var> using one of the "Add" or "Insert" methods that
	"directly store" into an <var>XmlDoc</var>.		"directly store" into an <var>XmlDoc</var>.
	For example, the following fragment adds an <var>Element</var> node with		For example, the following fragment adds an <var>Element</var> node with
	a value that is the Unicode trademark sign:		a value that is the Unicode trademark sign: </p>
	<p class="code">%node:AddElement('notation', '&#x2122;':U)		<p class="code">%node:AddElement('notation', '&#x2122;':U)
	</p>		</p>
	'''Note:'''		</blockquote>

			<blockquote class="note">
			<p>'''Note:'''
	<var>LoadXml</var> accepts input that contains XML hex character references		<var>LoadXml</var> accepts input that contains XML hex character references
	but not input that contains XHTML entity references (other than		but not input that contains XHTML entity references (other than
	the five predefined entities described in [[XML processing in Janus SOAP#Entity references\|"Entity references"]].		the five predefined entities described in [[XML processing in Janus SOAP#Entity references\|"Entity references"]].
	For example, this statement successfully loads a copyright character:		For example, this statement successfully loads a copyright character: </p>
	<p class="code">%d:LoadXml('<a>&#xA9;</a>')		<p class="code">%d:LoadXml('<a>&#xA9;</a>')
	</p>		</p>
Line 380:		Line 384:
	<p class="code">%d:LoadXml('<a>&copy;</a>':U)		<p class="code">%d:LoadXml('<a>&copy;</a>':U)
	</p>		</p>
			</blockquote>

	For more information about working with Unicode characters, see [[XmlDoc API#Strings and Unicode with the XmlDoc API\|"Strings and Unicode with the XmlDoc API"]].		For more information about working with Unicode characters, see [[XmlDoc API#Strings and Unicode with the XmlDoc API\|Strings and Unicode with the XmlDoc API]].

	===Using the ReplaceUnicode option===		===Using the ReplaceUnicode option===

JAL: /* Usage notes */

2014-02-16T01:19:30Z

Usage notes

← Older revision		Revision as of 01:19, 16 February 2014
Line 99:		Line 99:

	<table>		<table>
	<tr><th>Input bytestream		<tr class="head"><th>Input bytestream
	</th><th>XML declaration		</th><th>XML declaration
	</th></tr>		</th></tr>

	<tr><td>ASCII codes below X'80'		<tr><td>ASCII codes below X'80'
	</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>		</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>
	</td></tr>		</td></tr>

	<tr><td>ASCII codes up to X'FF'		<tr><td>ASCII codes up to X'FF'
	</td><td>ISO-8859-<var class="term">n</var>		</td><td>ISO-8859-<var class="term">n</var>
	</td></tr>		</td></tr>

	<tr><td>UTF-8 (with characters above X'7F')		<tr><td>UTF-8 (with characters above X'7F')
	</td><td>UTF-8 or <var class="term">none</var>		</td><td>UTF-8 or <var class="term">none</var>
	</td></tr>		</td></tr>

	<tr><td>UTF-16		<tr><td>UTF-16
	</td><td>UTF-16 or <var class="term">none</var>		</td><td>UTF-16 or <var class="term">none</var>
	</td></tr>		</td></tr>

	<tr><td>EBCDIC		<tr><td>EBCDIC
	</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>		</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>
	</td></tr>		</td></tr>

	<tr><td><var>Unicode</var> (User Language)		<tr><td><var>Unicode</var> (User Language)
	</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>		</td><td>UTF-8, ISO-8859-<var class="term">n</var>, or <var class="term">none</var>
Line 122:		Line 128:

	<table>		<table>
	<tr><th>XML declaration		<tr class="head"><th>XML declaration
	</th><th>Input bytestream		</th><th>Input bytestream
	</th></tr>		</th></tr>

	<tr><td>UTF-8		<tr><td>UTF-8
	</td><td>UTF-8 (which includes ASCII codes below X'80'), EBCDIC, or Unicode		</td><td>UTF-8 (which includes ASCII codes below X'80'), EBCDIC, or Unicode
	</td></tr>		</td></tr>

	<tr><td>UTF-16		<tr><td>UTF-16
	</td><td>UTF-16 (including a two byte order mark bytes as a preamble to the XML document input stream)		</td><td>UTF-16 (including a two byte order mark bytes as a preamble to the XML document input stream)
	</td></tr>		</td></tr>

	<tr><td>ISO-8859-<var class="term">n</var>		<tr><td>ISO-8859-<var class="term">n</var>
	</td><td>ASCII codes up to X'FF', EBCDIC, or Unicode		</td><td>ASCII codes up to X'FF', EBCDIC, or Unicode
	</td></tr>		</td></tr>

	<tr><td><var class="term">none</var>		<tr><td><var class="term">none</var>
	</td><td>UTF-8, UTF-16, ASCII, EBCDIC, or Unicode		</td><td>UTF-8, UTF-16, ASCII, EBCDIC, or Unicode

JAL at 19:43, 14 February 2014

2014-02-14T19:43:20Z

← Older revision		Revision as of 19:43, 14 February 2014
Line 11:		Line 11:
	<tr><th>%errorPosition</th>		<tr><th>%errorPosition</th>
	<td>A %variable set to 0 if the deserialization is successful. If the <code>ErrRet</code> <var class="term">option</var> is used, <var class="term">%errorPosition</var> is set to the character position within <var class="term">input</var> at which an error is found.</td></tr>		<td>A %variable set to 0 if the deserialization is successful. If the <code>ErrRet</code> <var class="term">option</var> is used, <var class="term">%errorPosition</var> is set to the character position within <var class="term">input</var> at which an error is found.</td></tr>

	<tr><th>nr</th>		<tr><th>nr</th>
	<td>An expression that points to the <var>XmlDoc</var> or <var>XmlNode</var> to contain the deserialized representation of the XML document or fragment, respectively.		<td>An expression that points to the <var>XmlDoc</var> or <var>XmlNode</var> to contain the deserialized representation of the XML document or fragment, respectively.
Line 16:		Line 17:
	If an <var>XmlDoc</var>, it must be <var>EMPTY</var> (see [[XmlDoc_API#XmlDoc states\|"XmlDoc states"]]) prior to invoking <var>LoadXml</var>. If an <var>XmlNode</var> that is the root node of an <var>XmlDoc</var>, the <var>XmlDoc</var> must be <var>EMPTY</var>.		If an <var>XmlDoc</var>, it must be <var>EMPTY</var> (see [[XmlDoc_API#XmlDoc states\|"XmlDoc states"]]) prior to invoking <var>LoadXml</var>. If an <var>XmlNode</var> that is the root node of an <var>XmlDoc</var>, the <var>XmlDoc</var> must be <var>EMPTY</var>.
	</td></tr>		</td></tr>

	<tr><th>input</th>		<tr><th>input</th>
	<td>The byte string or <var>Stringlist</var> to be deserialized. If a <var>Stringlist</var>, <var class="term">input</var> consists of the concatenation of the <var>Stringlist</var> items with insertion of line-end characters at the end of each item.		<td>The byte string or <var>Stringlist</var> to be deserialized. If a <var>Stringlist</var>, <var class="term">input</var> consists of the concatenation of the <var>Stringlist</var> items with insertion of line-end characters at the end of each item.

	If the <var class="term">nr</var> method object is an <var>XmlDoc</var> or the root node of an <var>XmlDoc</var>, <var class="term">input</var> must be valid as an entire XML document (for example, only one top-level element). If <var class="term">nr</var> is a non-root <var>XmlNode</var>, <var class="term">input</var> must be an '''XML fragment''', that is, a substring of a serialized XML document, such that:		If the <var class="term">nr</var> method object is an <var>XmlDoc</var> or the root node of an <var>XmlDoc</var>, <var class="term">input</var> must be valid as an entire XML document (for example, only one top-level element). If <var class="term">nr</var> is a non-root <var>XmlNode</var>, <var class="term">input</var> must be an '''XML fragment''', that is, a substring of a serialized XML document, such that:
	<ul><li>The fragment may contain undeclared prefixes. Any such prefixes must have declarations which are in effect at the <var>Element</var> node referred to by the method object of <var>LoadXml</var>; these declarations (along with that Element's default namespace) are inherited by the inserted fragment.
			<ul>
			<li>The fragment may contain undeclared prefixes. Any such prefixes must have declarations which are in effect at the <var>Element</var> node referred to by the method object of <var>LoadXml</var>; these declarations (along with that Element's default namespace) are inherited by the inserted fragment.

	<li>In all other respects, the fragment, if "wrapped" within a simple element start tag and end tag (such as <code><w></code> and <code></w></code>, respectively), is a legal XML document. The fragment can contain leading and/or trailing character content and/or multiple "top-level" elements; all of these become children of the method object <var>XmlNode</var>.		<li>In all other respects, the fragment, if "wrapped" within a simple element start tag and end tag (such as <code><w></code> and <code></w></code>, respectively), is a legal XML document. The fragment can contain leading and/or trailing character content and/or multiple "top-level" elements; all of these become children of the method object <var>XmlNode</var>.
	</ul></td></tr>		</ul></td></tr>

	<tr><th><div id="options"></div>options</th>		<tr><th><div id="options"></div>options</th>
	<td>Any valid combination of the following terms:		<td>Any valid combination of the following terms:
	<ul><div id="allowUntrans"></div><li><b>AllowUntranslatable</b><br>
			<ul><div id="allowUntrans"></div>
			<li><b>AllowUntranslatable</b><br>
	Allows all valid Unicode strings into the XML document. When this option is not specified, Unicode strings that are not translatable to EBCDIC are disallowed. <var>AllowUntranslatable</var> allows untranslatable Unicode characters, but it does not affect untranslatable EBCDIC characters. As described in [[#Deserializing Unicode strings\|"Deserializing Unicode strings"]], it is recommended that you use <var>AllowUntranslatable</var> only if the application checks for translatability when accessing parts of the <var>XmlDoc</var> that may have untranslatable Unicode content. The <var>AllowUntranslatable</var> option is available as of <var class="product">Sirius Mods</var> Version 7.6.		Allows all valid Unicode strings into the XML document. When this option is not specified, Unicode strings that are not translatable to EBCDIC are disallowed. <var>AllowUntranslatable</var> allows untranslatable Unicode characters, but it does not affect untranslatable EBCDIC characters. As described in [[#Deserializing Unicode strings\|"Deserializing Unicode strings"]], it is recommended that you use <var>AllowUntranslatable</var> only if the application checks for translatability when accessing parts of the <var>XmlDoc</var> that may have untranslatable Unicode content. The <var>AllowUntranslatable</var> option is available as of <var class="product">Sirius Mods</var> Version 7.6.

← Older revision		Revision as of 20:35, 13 March 2014
Line 566:		Line 566:

	<li>For more information about normalization, see [[XML processing in Janus SOAP#Normalization during deserialization\|Normalization during deserialization]]. </li>		<li>For more information about normalization, see [[XML processing in Janus SOAP#Normalization during deserialization\|Normalization during deserialization]]. </li>

			<li>For additional discussion about deserialization, see [[XmlDoc API#Transport: receiving and sending XML\|Transport: receiving and sending XML]]. </li>
	</ul>		</ul>

	{{Template:XmlDoc/XmlNode:LoadXml footer}}		{{Template:XmlDoc/XmlNode:LoadXml footer}}

← Older revision		Revision as of 17:50, 18 March 2014
Line 183:		Line 183:
	of the input character sets described above is used.		of the input character sets described above is used.

	<li>~~An XML fragment~~ '''does not''' provide for inserting an Attribute		<li><var>LoadXml</var> '''does not''' provide for inserting an Attribute
	into an Element node.		into an Element node by using an XML fragment.
	For example, the following '''does not''' achieve it:		For example, the following '''does not''' achieve it:
	<p class="code">%d Object XmlDoc Auto New		<p class="code">%d Object XmlDoc Auto New
Line 198:		Line 198:
	<p>		<p>
	To add the Attribute <code>foo</code> with the value <code>bar</code>,		To add the Attribute <code>foo</code> with the value <code>bar</code>,
	replace <var>LoadXml</var> in the example above with		replace <var>LoadXml</var> in the example above with the <var>AddAttribute</var> updating method:
	<code>%n:[[AddAttribute (XmlNode function)\|AddAttribute]]('foo', 'bar')</code>. </p>		<code>%n:[[AddAttribute (XmlNode function)\|AddAttribute]]('foo', 'bar')</code>. </p>
	This produces the result:		This produces the result:
	<p class="output"><top foo="bar"/> </p>		<p class="output"><top foo="bar"/> </p>

			Another situation where an updating method does what <var>LoadXml</var> does not is controlling the formatting of empty XML elements. This is described in [[XmlDoc API#Information form and content\|Information form and content]].

	<li>If the method object refers to the <var>Root</var> node of an <var>XmlDoc</var>, the		<li>If the method object refers to the <var>Root</var> node of an <var>XmlDoc</var>, the