EbcdicToAscii (String function)

Convert EBCDIC string to ASCII (String class)

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

The EbcdicToAscii function is available as of version 7.3 of the Sirius Mods.

Syntax

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

Syntax terms

%ascii	A string variable to receive the method object string translated to Ascii.
string	An EBCDIC character string.
CharacterDecode=bool	The optional (name required) CharacterDecode argument is a Boolean: *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 control character). 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

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

• You can find the list of XHTML entities on the Internet at the following URL:

   http://www.w3.org/TR/xhtml1/dtds.html#h-A2

• There is more information about the Unicode tables.
• The inverse of the EbcdicToAscii method is AsciiToEbcdic.

Examples

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

List of intrinsic String methods