EbcdicToAscii (String function)

From m204wiki
Revision as of 05:09, 31 January 2011 by Goff (talk | contribs) (first pass, match syntax diagram to template and fix tags; still some broken links)
Jump to navigation Jump to search

Convert EBCDIC string to ASCII (String class)


EbcdicToAscii is an intrinsic function that converts an EBCDIC string to ASCII (ISO 8859-1) using the current Unicode tables. Optionally, character references, entity references, and '&' references are converted to the represented ASCII character.

Syntax

%outString = string:EbcdicToAscii[( [CharacterDecode= boolean])] Throws CharacterTranslationException

Syntax terms

%string A string variable to receive the method object string translated to Ascii.
string An EBCDIC character string.
CharacterDecode The optional (name required) CharacterDecode argument is a Boolean enumeration:
  • If its value is True, an ampersand (&) in the input EBCDIC string is allowed only as the beginning of one of these types of character or entity reference:
    • The substring '&'. This substring is converted to a single '&' character.
    • A hexadecimal character reference (for example, the six characters '' for the ASCII Device Control String character (X'90')). The character reference is converted to the referenced character.
    • As of Sirius Mods version 7.6, an XHTML entity reference (for example, the six characters '©' for the copyright character). The entity reference is converted to the referenced character. A decimal character reference (for example, ¬) is not allowed.
  • If its value is False, the default, an ampersand is treated only as a normal character.

Exceptions

EbcdicToAscii 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

  • EbcdicToAscii is available as of Sirius Mods version 7.3.

Examples

  1. The following fragment shows calls of EbcdicToAscii against a variety of EBCDIC characters. The X constant function is used in the example.

    %e string Len 20 %a string Len 20 %e = '12' %a = %e:EbcdicToAscii Print %a:StringToHex %e = '1
2' %a = %e:EbcdicToAscii(CharacterDecode=True) Print %a:StringToHex %e = '©' %a = %e:EbcdicToAscii(CharacterDecode=True) Print %a:StringToHex %e = 'F1FFF2':X %a = %e:EbcdicToAscii

    The result is:

    3132 310A32 A9 CANCELLING REQUEST: MSIR.0751: Class STRING, function EBCDICTOASCII: CHARACTER TRANSLATIONEXCEPTION exception: EBCDIC character X'FF' without valid translation to ASCII at byte position 2 ...

See also