EbcdicToAscii (String function)

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.

EbcdicToAscii syntax

  %ascii = string:EbcdicToAscii([CharacterDecode=bool]) 

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