EbcdicToAscii (String function): Difference between revisions

Revision as of 05:39, 19 January 2011

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&#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 9: / Line 9: @@
 {{Template:String:EbcdicToAscii syntax}}
 ===Syntax terms===
-<dl>
+<table class="syntaxTable">
-<dt>%ascii
+<tr><th>%ascii                                                                                                       </th>
-<dd>A string variable to receive the method object string translated to Ascii.
+<td>A string variable to receive the method object string translated to Ascii. </td></tr>
-<dt>string
+<tr><th>string                                                                                                       </th>
-<dd>An EBCDIC character string.
+<td>An EBCDIC character string.       </td></tr>
-<dt>CharacterDecode=bool
+<tr><th>CharacterDecode=bool                                                                                 </th>
-<dd>The optional (name required) CharacterDecode argument is a Boolean:
+<td>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.</td></tr>
-*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:
+</table>
-**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>
 ===Exceptions===
 This [[Intrinsic classes|intrinsic]] function can throw the following exception: