AsciiToEbcdic (String function)

Convert ASCII string to EBCDIC (String class)

This intrinsic function converts an ASCII (ISO-8859-1) string to EBCDIC using the current Unicode tables. Optionally, untranslatable characters are represented with character references.

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

Syntax

%outString = string:AsciiToEbcdic[( [CharacterEncode= boolean])] Throws CharacterTranslationException

Syntax terms

%ebcdic

A string variable to receive the method object string translated to EBCDIC.

string

A string that is presumed to consist of ASCII characters.

CharacterEncode=bool

The optional (name required) CharacterEncode argument is a Boolean:

• If its value is 'False', the default, an exception is thrown if the input contains any ASCII character not translatable to EBCDIC.
• If its value is 'True', any ASCII character not translatable to EBCDIC is replaced with the XML style hexadecimal character reference of the character, and the ampersand character is replaced with '&amp.amp;'.

For instance, the six characters '' replace the ASCII Device Control String character (X'90'). A similar example is shown below.

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

• More information is available about the Unicode tables.
• The inverse of the AsciiToEbcdic method is EbcdicToAscii.

Examples

The following fragment shows calls of AsciiToEbcdic against strings with and without non-translatable characters.

   %a String Len 20                                                  
   %a = '31':X                                                       
   Print %a:AsciiToEbcdic                                            
                                                                     
   %a = '318132':X                                                   
   Print %a:AsciiToEbcdic(CharacterEncode=True)                      
   Print %a:AsciiToEbcdic                                            

The result is:

   1                                                                 
   12                                                          
   CANCELLING REQUEST: MSIR.0751: Class STRING, function ASCIITOEBCDIC: CHARACTER TRANSLATIONEXCEPTION                   
     exception: ASCII character X'81' without valid translation to EBCDIC at byte position 1 ...

See also

List of intrinsic String methods