CharacterTranslationException class

Various methods throw a CharacterTranslationException exception when they encounter character translation problems. To avert request cancellation, you can catch such an exception, optionally catching to an object of this class.

This class is available as of Sirius Mods Version 7.3.

The CharacterTranslationException methods

The following are the available CharacterTranslationException class methods.

Method	Description
BytePosition	Position of byte at which the exception was thrown
CharacterPosition	Position of character at which the exception was thrown
Description	Brief description of the exception
HexValue	Hexadecimal value of bytes causing the exception
New	Create a new CharacterTranslationException object
Reason	Enumerated cause of the exception

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

• "Notation conventions for methods" has information about the conventions followed.
• "CharacterTranslationException methods syntax" is a single page that contains the syntax diagrams of all the methods in the class.

BytePosition property

Position of byte at which the exception was thrown (CharacterTranslationException class)

Syntax

%number = characterTranslationException:BytePosition

Syntax terms

%number	The position of the byte at which the exception was thrown.
characterTranslationException	A reference to an instance of a CharacterTranslationException object.

CharacterPosition property

Position of character at which the exception was thrown (CharacterTranslationException class)

Syntax

%number = characterTranslationException:CharacterPosition

Syntax terms

%number	The position of the character at which the exception was thrown.
characterTranslationException	A reference to an instance of a CharacterTranslationException 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.

Description property

Brief description of the exception (CharacterTranslationException class)

Syntax

%string = characterTranslationException:Description

Syntax terms

%string	A string to receive the description of the exception.
characterTranslationException	A reference to an instance of a CharacterTranslationException object.

HexValueproperty

Hexadecimal value of bytes causing the exception (CharacterTranslationException class)

Syntax

%string = characterTranslationException:HexValue

Syntax terms

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

New constructor

Create a new CharacterTranslationException object (CharacterTranslationException class) Each argument to New sets the value of the corresponding property of the newly constructed CharacterTranslationException object.

Syntax

%characterTranslationException = [%(CharacterTranslationException):]New( Reason= translationExceptionReason, - [HexValue= string], - [BytePosition= number], - [CharacterPosition= number], - [Description= string])

Syntax terms

%characterTranslationException	A reference to the newly created instance of a CharacterTranslationException object.
%(CharacterTranslationException)	The class name in parentheses denotes a shared method.
Reason	Reason is a non-optional, name required parameter specifying the value to be assigned to the exception object's Reason property. As described for the Reason]] property, the translationExceptionReason enumeration values are InvalidEncoding, InvalidCharacterReference, and UntranslatableCharacter.
HexValue	This name required parameter specifies the string value (string) to be assigned to the object's HexValue property.
BytePosition	This name required parameter specifies the numeric value (number) to be assigned to the object's BytePosition property.
CharacterPosition	This name required parameter specifies the numeric value (number) to be assigned to the object's CharacterPosition property.
Description	This name required parameter specifies the string value (string) to be assigned to the object's Description property.

Reason property

Enumerated cause of the exception (CharacterTranslationException class)

Syntax

%translationExceptionReason = characterTranslationException:Reason

Syntax terms

%translationExceptionReason	This TranslationExceptionReason enumeration value describes the reason for the translation failure.
characterTranslationException	A reference to an instance of a CharacterTranslationException object.

Usage notes

• A TranslationExceptionReason enumeration may have one of the following values:

  InvalidEncoding

  An example of invalid encoding is UTF-16 string input to Utf16ToUnicode that contains bytes whose hexadecimal value is D800 (which is in the surrogates range).

  InvalidCharacterReference

  An XML-style hexadecimal character reference (for example, ™ for the trademark character) may validly represent a Unicode character to be translated. Any other string that begins with by an ampersand (&) — except the string & — might cause an exception explained by an InvalidCharacterReference enumeration.

  For example, such an exception occurs if EbcdicToUnicode is called, the method argument is CharacterDecode=True, and the method input contains an ampersand followed by a space.

  UntranslatableCharacter

  The following are examples of untranslatable characters (with the translation tables as delivered by Sirius):

  • The EBCDIC input to the EbcdicToUnicode method contains a byte whose hexadecimal value is X'FF.
  • The Unicode input to UnicodeToEbcdic contains one of the many Unicode characters that is not translated to an EBCDIC character (for example, U+20AC, the Euro currency symbol).

• As with all enumerations, you use the ToString method to convert an enumeration value to a character string whose value is the name of the enumeration value.