XmlParseError class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 1: Line 1:
<!-- XmlParseError class -->
<!-- XmlParseError class -->
__NOTOC__
The XmlParseError 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#The_XmlDoc_class|XmlDoc]]</var> API, and the <var>[[ParseXml]]</var> method of the <var>[[HttpResponse]]</var> class.
The XmlParseError 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#The_XmlDoc_class|XmlDoc]]</var> API, and the <var>[[ParseXml]]</var> method of the <var>[[HttpResponse]]</var> class.


Line 15: Line 16:




<h2>Name property</h2>
<h2>CharacterPosition property</h2>
{{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, 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>
<h2>New constructor</h2>
{{Template:XmlParseError:New subtitle}}
This constructor generates an instance of an <var>[[XmlParseError_class|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 shared method.</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</var> enumeration values, which are described below in [[Reason (XmlParseError property)#Syntax terms|"Reason property"]].
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>
<h2>Description property</h2>
{{Template:XmlParseError:Description subtitle}}
This <var>[[Classes and Objects#readWrite|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>
<h2>InputHexValue property</h2>
{{Template:XmlParseError:InputHexValue subtitle}}
This <var>[[Classes and Objects#readWrite|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>
<h2>Reason property</h2>
{{Template:XmlParseError:Reason subtitle}}
This <var>[[Classes and Objects#readWrite|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>%reason</th>
<td>This <var>XmlParseErrorReason</var> enumeration value 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>
==Usage notes==
<ul>
<li>An <var>XmlParseErrorReason</var> enumeration may have one of the following values, each of which is demonstrated in the [[#Example|examples]] below.
<dl>
<dt><var>InvalidUnicodeCharacter</var>
<dd>The Unicode input contains an invalid character.
<dt><var>InvalidUTF8Encoding</var>
<dd>The input UTF8 stream is invalid.
<dt><var>InvalidUTF16Encoding</var>
<dd>The input UTF16 stream is invalid.
<dt><var>SyntaxError</var>
<dd>A violation of the syntax of an XML document.
<dt><var>UntranslatableEBCDIC</var>
<dd>The EBCDIC input contains a character that is not translatable to Unicode.
<dt><var>UntranslatableISOn</var>
<dd>The ISO-8859-n input contains a character that is not translatable to Unicode.
<dt><var>UntranslatableUnicode</var>
<dd>The Unicode input contains a character that is not translatable to EBCDIC.
This exception can be avoided using the <code>AllowUntranslatable</code>
option of the deserialization method.
</dl>
</ul>
==Example==
The following template is used to apply the <var>[[LoadXml_(XmlDoc/XmlNode_function)|LoadXml]]</var> deserialization method to a series of test ''input-string'' values to demonstrate the <var>XmlParseError</var> exception output:
<p class="code">  [[try]]
      [[PrintText statement|printText]] {~}: {%d:LoadXml(''input-string'')}
  [[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)'''
</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)'''
</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]]
[[Category:System exception classes]]

Revision as of 20:17, 10 May 2011


The XmlParseError exception class catches parsing errors (including syntax, translation, and encoding errors) thrown by the deserialization methods: LoadXml and WebReceive of the Janus SOAP XmlDoc API, and the ParseXml method of the HttpResponse class.

This class is available as of Sirius Mods Version 7.6.

The XmlParseError methods

The following are the available XmlParseError class methods.

MethodDescription
CharacterPositionPosition of character at of before which the error occurred
DescriptionBrief description of the exception
InputHexValueHexadecimal value of bytes causing the exception
NewCreate a new XmlParseError object
ReasonEnumerated cause of the exception

The methods in the class are described in the subsections that follow. In addition:


CharacterPosition property

Position of character at of before which the error occurred (XmlParseError class)

This ReadOnly 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

%number = xmlParseError:CharacterPosition

Syntax terms

%number The position at or before which the error was detected.
xmlParsError A reference to an instance of an XmlParseError object.

Usage notes

  • The number of bytes that constitute a character depends on the type of string that causes the exception:
    • If EBCDIC, one byte corresponds to one character.
    • If Unicode, two bytes correspond to one character.
    • If UTF-16, two bytes correspond to one character.
    • If UTF-8, the relationship between bytes and characters is variable, depending on the code points.


New constructor

Create a new XmlParseError object (XmlParseError class)

This constructor generates an instance of an XmlParseError exception. As shown in the syntax that follows, the New method arguments set the values of the class properties that have the corresponding names.

Each argument to New sets the value of the corresponding property of the newly constructed XmlParseError object.

Syntax

%xmlParseError = [%(XmlParseError):]New( Reason= xmlParseErrorReason, - [CharacterPosition= number], - [Description= string], - [InputHexValue= string])

Syntax terms

xmlParsError A reference to an instance of a XmlParseError object.
%(XmlParseError)The class name in parentheses denotes a shared method.
Reason This name required parameter specifies the value to be assigned to the exception object's Reason property.

Reason settings are XmlParseErrorReason enumeration values, which are described below in "Reason property". The Reason parameter is not optional.

CharacterPosition This optional, but name required, parameter specifies the numeric value (number) to be assigned to the object's CharacterPosition property. Its default value is 0.
Description This optional, but name required, parameter specifies the string value (string) to be assigned to the object's Description property. Its default value is a null string.
InputHexValue This optional, but name required, parameter specifies the string value (string) to be assigned to the object's InputHexValue property. Its default value is a null string.


Description property

Brief description of the exception (XmlParseError class)

This ReadOnly property returns a string that contains a brief description of the exception.

Syntax

%string = xmlParseError:Description

Syntax terms

%string A string to receive the description of the exception.
xmlParsError A reference to an instance of a XmlParseError object.


InputHexValue property

Hexadecimal value of bytes causing the exception (XmlParseError class)

This ReadOnly property returns a string that contains the hexadecimal representation of the bytes that caused the exception to be thrown.

InputHexvalue returns a value for all reasons except SyntaxError.

Syntax

%string = xmlParseError:InputHexValue

Syntax terms

%string A string to receive the hexadecimal value of the bytes that caused the exception to be thrown.
xmlParsError A reference to an instance of a XmlParseError object.


Reason property

Enumerated cause of the exception (XmlParseError class)

This ReadOnly property returns an XmlParseErrorReason enumeration value that describes the error that caused the XmlParseErrorexception.

Syntax

%xmlParseErrorReason = xmlParseError:Reason

Syntax terms

%reason This XmlParseErrorReason enumeration value describes the parsing error.
xmlParsError A reference to an instance of a XmlParseError object.

Usage notes

  • An XmlParseErrorReason enumeration may have one of the following values, each of which is demonstrated in the examples below.
    InvalidUnicodeCharacter
    The Unicode input contains an invalid character.
    InvalidUTF8Encoding
    The input UTF8 stream is invalid.
    InvalidUTF16Encoding
    The input UTF16 stream is invalid.
    SyntaxError
    A violation of the syntax of an XML document.
    UntranslatableEBCDIC
    The EBCDIC input contains a character that is not translatable to Unicode.
    UntranslatableISOn
    The ISO-8859-n input contains a character that is not translatable to Unicode.
    UntranslatableUnicode
    The Unicode input contains a character that is not translatable to EBCDIC. This exception can be avoided using the AllowUntranslatable option of the deserialization method.

Example

The following template is used to apply the LoadXml deserialization method to a series of test input-string values to demonstrate the XmlParseError exception output:

try printText {~}: {%d:LoadXml(input-string)} 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

  • When called with:

    %d:LoadXml('<a>'):

    The results are:

    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: - - -

  • When called with:

    %d:LoadXml('<' With 'FF':X With '>')

    The results are:

    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 - - -

  • When called with:

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

    The results are:

    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 - - -

  • When called with:

    %d:LoadXml('FEFF003C33':X)

    The results are:

    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 - - -

  • When called with:

    %d:LoadXml('FEFFD800':X)

    The results are:

    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 - - -

  • When called with:

    %d:LoadXml('C181':X)

    The results are:

    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 - - -

  • When called with:

    %d:LoadXml('FF818256':X)

    The results are:

    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 - - -

  • When called with:

    %d:LoadXml('EDA080':X)

    The results are:

    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 - - -