UnicodeToEbcdic (Unicode function)

From m204wiki
Revision as of 20:02, 6 November 2012 by JAL (talk | contribs) (→‎Syntax terms)
Jump to navigation Jump to search

Translate to Ebcdic (Unicode class)

UnicodeToEbcdic converts a Unicode string to EBCDIC. Optionally, untranslatable characters can be represented with XML style hexadecimal character references.

Syntax

%string = unicode:UnicodeToEbcdic[( [CharacterEncode= boolean])] Throws CharacterTranslationException

Syntax terms

%string A string variable to receive the method object string translated to EBCDIC.
unicode A Unicode string to be translated.
CharacterEncode The optional (name required) CharacterEncode argument is a Boolean enumeration:
  • If its value is False, the default, an exception is thrown if the input contains any Unicode character not translatable to EBCDIC.
  • If its value is True, any Unicode character not translatable to EBCDIC is replaced with the hexadecimal character reference of the character, and the ampersand character is replaced with &. For example, the eight characters “ replace the Unicode left double-quotation mark ().

Exceptions

This function can throw the following exception:

CharacterTranslationException
If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.

Usage notes

  • Unless the CharacterEncode argument is used, or you want to Catch a CharacterTranslationException, this function is generally not needed, because a Unicode string is implicitly converted to EBCDIC when used in an EBCDIC context. See the following example.
  • The UnicodeToEbcdic function is available as of Sirius Mods Version 7.3.

Examples

The following example shows multiple calls of UnicodeToEbcdic.

%u Unicode Initial('1':U) print %u:UnicodeToEbcdic %u = '1€2':U print %u:UnicodeToEbcdic(CharacterEncode=True) print %u:UnicodeToEbcdic

The result of the above fragment is:

1 1€2 CANCELLING REQUEST: MSIR.0751: Class STRING, function UNICODETOEBCDIC: CHARACTER TRANSLATIONEXCEPTION exception: Unicode character U+0080 without valid translation to EBCDIC at byte position 5 ...

Note: Because of the implicit conversion of Unicode strings (in this case to String), the Print %u:UnicodeToEbcdic statements in the example above could be replaced by Print %u statements and the results would be the same.

See also