View source for XmlParseError class

__NOTOC__
The <var>XmlParseError</var> exception class catches parsing errors (including syntax, translation, and encoding errors) thrown by the deserialization methods: <var>[[LoadXml_(XmlDoc/XmlNode_function)|LoadXml]]</var> and <var>[[WebReceive_(XmlDoc_function)|WebReceive]]</var> of the <var class="product">Janus SOAP</var> <var>[[XmlDoc API]]</var>, and the <var>[[ParseXml (HttpResponse function)|ParseXml]]</var> method of the <var>[[HttpResponse class|HttpResponse ]]</var> class.
 
This class is available as of <var class="product">[[Sirius Mods]]</var> Version 7.6.
 
==The XmlParseError methods==
{{Template:List of XmlParseError methods}}
 
The methods in the class are described in the subsections that follow. In addition:
<ul>
<li>[[Notation conventions for methods]] has information
about the conventions followed.
<li>[[XmlParseError methods syntax]] is a single page that contains the syntax diagrams of all the methods in the class.
</ul>
 
 
==CharacterPosition property==
{{Template:XmlParseError:CharacterPosition subtitle}}
 
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a number that indicates the position within the input character stream (starting with 1) at or before which the error was detected.
 
===Syntax===
{{Template:XmlParseError:CharacterPosition syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%number</th>
<td>The position at or before which the error was detected.</td></tr>

<tr><th>xmlParsError</th>
<td>A reference to an instance of an <var>[[XmlParseError_class|XmlParseError]]</var> object.</td></tr>
</table>
 
===Usage notes===
<ul>
<li>The number of bytes that constitute a character depends on the type of string that causes the exception:
<ul>
<li>If EBCDIC, one byte corresponds to one character.
<li>If [[Unicode|Unicode]], two bytes correspond to one character.
<li>If UTF-16, two bytes correspond to one character.
<li>If UTF-8, the relationship between bytes and characters is variable, depending on the code points.
</ul>
</ul>
  
==Description property==
{{Template:XmlParseError:Description subtitle}}
 
This <var>ReadOnly</var> property returns a string that contains a brief description of the exception.
 
===Syntax===
{{Template:XmlParseError:Description syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%string</th>
<td>A string to receive the description of the exception.</td></tr>

<tr><th>xmlParsError</th>
<td>A reference to an instance of a <var>[[XmlParseError_class|XmlParseError]]</var> object.</td></tr>
</table>
 
 
==InputHexValue property==
{{Template:XmlParseError:InputHexValue subtitle}}
 
This <var>ReadOnly</var> property returns a string that contains the hexadecimal representation of the bytes that caused the exception to be thrown.
 
<var>InputHexvalue</var> returns a value for all [[Reason (XmlParseError property)|reasons]] except <var>SyntaxError</var>.
 
===Syntax===
{{Template:XmlParseError:InputHexValue syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%string</th>
<td>A string to receive the hexadecimal value of the bytes that caused the exception to be thrown.</td></tr>

<tr><th>xmlParsError</th>
<td>A reference to an instance of a <var>[[XmlParseError_class|XmlParseError]]</var> object.</td></tr>
</table>
 
 
==New constructor==
{{Template:XmlParseError:New subtitle}}
 
This <var>Constructor</var> generates an instance of an <var>XmlParseError</var> exception. As shown in the syntax that follows, the <var>New</var> method arguments set the values of the class properties that have the corresponding names.
 
Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>XmlParseError</var> object.

===Syntax===
{{Template:XmlParseError:New syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>xmlParsError</th>
<td>A reference to an instance of a <var>[[XmlParseError_class|XmlParseError]]</var> object.</td></tr>

<tr><th><var>[%(XmlParseError):]</var></th>
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr>

<tr><th><var>Reason</var></th>
<td>This [[Methods#Named parameters|name required]] parameter specifies the value to be assigned to the exception object's <var>[[Reason_(XmlParseError_property)|Reason]]</var> property.
<var>Reason</var> settings are <var>[[#XmlParseErrorReason enumeration|XmlParseErrorReason]]</var> enumeration values.
The <var>Reason</var> parameter is '''not''' optional.</td></tr>

<tr><th><var>CharacterPosition</var></th>
<td>This optional, but name required, parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[CharacterPosition_(XmlParseError_property)|CharacterPosition]]</var> property. Its default value is 0.</td></tr>

<tr><th><var>Description</var></th>
<td>This optional, but name required, parameter  specifies the string value (<var class="term">string</var>) to be assigned to the object's <var>[[Description_(XmlParseError_property)|Description]]</var> property. Its default value is a null string.</td></tr>

<tr><th><var>InputHexValue</var></th>
<td>This optional, but name required, parameter  specifies the string value (<var class="term">string</var>) to be assigned to the object's <var>[[InputHexValue_(XmlParseError_property)|InputHexValue]]</var> property. Its default value is a null string.</td></tr>
</table>
 

==Reason property==
{{Template:XmlParseError:Reason subtitle}}
 
This <var>ReadOnly</var> property returns an <var>XmlParseErrorReason</var> enumeration value that describes the error that caused the <var>[[XmlParseError_class|XmlParseError]]</var> exception.
 
===Syntax===
{{Template:XmlParseError:Reason syntax}}

====Syntax terms====
<table class="syntaxTable">
<tr><th>%xmlParseErrorReason</th>
<td>This <var>XmlParseErrorReason</var> enumeration value (see below) describes the parsing error.</td></tr>

<tr><th>xmlParsError</th>
<td>A reference to an instance of a <var>[[XmlParseError_class|XmlParseError]]</var> object.</td></tr>
</table>
 
====XmlParseErrorReason enumeration====
An <var>XmlParseErrorReason</var> [[Enumerations|enumeration]] may have one of the following values, each of which is demonstrated in the [[#Example|examples]] below.
<table class="thJustBold">
<tr><th>InvalidUnicodeCharacter
</th><td>The Unicode input contains an invalid character.</td></tr>

<tr><th>InvalidUTF8Encoding
</th><td>The input UTF8 stream is invalid.</td></tr>

<tr><th>InvalidUTF16Encoding
</th><td>The input UTF16 stream is invalid.</td></tr>

<tr><th>SyntaxError
</th><td>A violation of the syntax of an XML document.</td></tr>

<tr><th>UntranslatableEBCDIC
</th><td>The EBCDIC input contains a character that is not translatable to Unicode.</td></tr>

<tr><th>UntranslatableISOn
</th><td>The ISO-8859-n input contains a character that is not translatable to Unicode.</td></tr>

<tr><th>UntranslatableUnicode
</th><td>The Unicode input contains a character that is not translatable to EBCDIC. This exception can be avoided using the <var>AllowUntranslatable</var> option of the deserialization method.</td></tr>
</table>

===Usage notes===
<ul>
<li>As with all enumerations, the <var>ToString</var> method implicitly converts an enumeration value to a character string whose value is the name of the enumeration value. For more information about methods available to all enumerations, see [[Enumerations#Common enumeration methods|Common enumeration methods]].
</ul>
 
===Example===
The following template is used to apply the <var>[[LoadXml_(XmlDoc/XmlNode_function)|LoadXml]]</var> deserialization method to a series of test <code>input-string</code> values to demonstrate the <var>XmlParseError</var> exception output:
<p class="code">[[Exceptions#Try and Catch|try]]
   [[PrintText statement|printText]] {~}: {%d:LoadXml(''input-string'')}
[[Exceptions#Try and Catch|catch]] XmlParseError to %err
   print ' '
   print 'Error Reason:' And %err:Reason:ToString
   print 'Error Description:' And %err:Description
   print 'Error Character Position:' And %err:CharacterPosition
   print 'Error Input Hex Value:' And %err:InputHexValue
   print ' - - -'
end try
</p>
<ul>
<li>When called with:
<p class="code">'''%d:LoadXml('<a>'):'''
</p>
The results are:
<p class="output">Error Reason: SyntaxError
Error Description: XML doc parse error: missing ETag for top
      level element near or before position 4 (end of input)
Error Character Position: 4
Error Input Hex Value:
 - - -
</p>

<li>When called with:
<p class="code">'''%d:LoadXml('<' With 'FF':X With '>')'''
</p>
The results are:
<p class="output">Error Reason: UntranslatableEBCDIC
Error Description: XML doc parse error: EBCDIC character not
      translatable to Unicode near or before position 3
Error Character Position: 3
Error Input Hex Value: FF
 - - -
</p>

<li>When called with:
<p class="code">'''%d:LoadXml('<a>&amp;#x2122;</a>':[[U (String function)|U]])'''
</p>
The results are:
<p class="output">Error Reason: UntranslatableUnicode
Error Description: XML doc parse error: invalid Unicode
      character - not translatable to EBCDIC near or
      before position 5
Error Character Position: 5
Error Input Hex Value: 2122
 - - -
</p>

<li>When called with:
<p class="code">'''%d:LoadXml('FEFF003C33':[[X (String function)|X]])'''
</p>
The results are:
<p class="output">Error Reason: InvalidUTF16Encoding
Error Description: XML doc parse error: expecting additional
      byte of UTF-16 encoding near or before position 2
      (end of input)
Error Character Position: 2
Error Input Hex Value: 33
 - - -
</p>

<li>When called with:
<p class="code">'''%d:LoadXml('FEFFD800':X)'''
</p>
The results are:
<p class="output">Error Reason: InvalidUnicodeCharacter
Error Description: XML doc parse error: surrogate point in
      UTF-16 input near or before position 1
Error Character Position: 1
Error Input Hex Value: D800
 - - -
</p>

<li>When called with:
<p class="code">'''%d:LoadXml('C181':X)'''
</p>
The results are:
<p class="output">Error Reason: InvalidUTF8Encoding
Error Description: XML doc parse error: byte 1 of 2 too
      low in UTF-8 encoding near or before position 2
Error Character Position: 2
Error Input Hex Value: C181
 - - -
</p>

<li>When called with:
<p class="code">'''%d:LoadXml('FF818256':X)'''
</p>
The results are:
<p class="output">Error Reason: InvalidUTF8Encoding
Error Description: XML doc parse error: attempt to use
      4-byte UTF-8 encoding of surrogate point near or
      before position 2
Error Character Position: 2
Error Input Hex Value: FF
 - - -
</p>

<li>When called with:
<p class="code">'''%d:LoadXml('EDA080':X)'''
</p>
The results are:
<p class="output">Error Reason: InvalidUnicodeCharacter
Error Description: XML doc parse error: invalid Unicode
      character (surrogate range) near or before position 2
Error Character Position: 2
Error Input Hex Value: EDA080
 - - -
</p>
</ul>
 
[[Category:System exception classes]]