EbcdicToAscii (String function): Difference between revisions

Revision as of 22:59, 21 October 2010

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&#x0A;2'                                                                                
   %a = %e:EbcdicToAscii(CharacterDecode=True)                                                    
   Print %a:StringToHex                                                                           
                                                                                                  
   %e = '&copy;'
   %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 ...

@@ Line 3: / Line 3: @@
 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===
+====Syntax Terms====
 <dl>
 <dt>%ascii
 <dd>A string variable to receive the method object string translated to Ascii.
 <dt>string
 <dd>An EBCDIC character string.
 <dt>CharacterDecode=bool
 <dd>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 ''''&amp;amp;''''. This substring is converted to a single ''''&'''' character.
 **A hexadecimal character reference (for example, the six characters '&amp;#x90;' 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 '&amp;copy;' for the ''copyright'' character). The entity reference is converted to the referenced character. A decimal character reference (for example, &amp;#172;) is ''not'' allowed.
 *If its value is ''''False'''', the default, an ampersand is treated only as a normal character.
 </dl>
@@ Line 36: / Line 36: @@
 ===Examples===
 The following fragment shows calls of EbcdicToAscii against a variety of EBCDIC characters.
-The [[Intrinsic X Function|X]] constant function is used in the example.
+The [[X (String function)|X]] constant function is used in the example.
      %e String Len 20
      %a String Len 20