EbcdicToAscii (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(44 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This [[Intrinsic classes|intrinsic]] function converts an EBCDIC string to ASCII (ISO 8859-1)                   
{{Template:String:EbcdicToAscii subtitle}}
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====
<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>                                                                                             
===Exceptions===                                                                                 
This [[Intrinsic classes|intrinsic]] function can throw the following exception:                 
<dl>                                                                                             
<dt>[[CharacterTranslationException]]                                                             
<dd>If the method encounters a translation problem,                                               
properties of the exception object may indicate the location and type of problem.                 
</dl>                                                                                             
===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 (String function)|AsciiToEbcdic]].


===Examples===                                                                                   
<var>EbcdicToAscii</var> is an [[Intrinsic classes|intrinsic]] function that converts an EBCDIC string to ASCII (ISO 8859-1) using the current [[Unicode#Support for the ASCII subset of Unicode|Unicode tables]]. Optionally, character references, entity references, and individual ampersand (<tt>&amp;</tt>) references are converted to the represented ASCII character.
The following fragment shows calls of EbcdicToAscii against a variety of EBCDIC characters.                                                                             
The [[X (String function)|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&amp;#x0A;2'                                                                               
    %a = %e:EbcdicToAscii(CharacterDecode=True)                                                   
    Print %a:StringToHex                                                                         
                                                                                                 
    %e = '&amp;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 ...


===See also===                                                                                       
==Syntax==
[[List of intrinsic String methods]]
{{Template:String:EbcdicToAscii syntax}}


[[Category:Intrinsic String methods|EbcdicToAscii function]]
===Syntax terms===
[[Category:Intrinsic methods]]
<table class="syntaxTable">
[[Category:System methods]]
<tr><th>%outString</th>
<td>A string variable to receive the method object, <var class="term">string</var>, translated to Ascii.</td></tr>
 
<tr><th>string</th>
<td>An EBCDIC character string.</td></tr>
 
<tr><th><var>CharacterDecode</var></th>
<td>The optional (name required) <var>CharacterDecode</var> argument is a <var>[[Boolean enumeration|Boolean]]</var> enumeration:
<ul>
<li>If its value is <code>True</code>, an ampersand (<tt>&amp;</tt>) in the input EBCDIC string is allowed <b><i>only</i></b> as the beginning of one of these types of character or entity reference:
<ul>
<li>The substring <code>&amp;amp;</code>. This substring is converted to a single <code>&amp;</code> character.
 
<li>A hexadecimal character reference (for example, the six characters <code>'&amp;#x90;'</code> for the ASCII "Device Control String" character (X'90')). The character reference is converted to the referenced character.
 
<li>As of <var class=product>Sirius Mods</var> version 7.6, an XHTML entity reference (for example, the six characters <code>&amp;copy;</code> for the <i>copyright</i> character <code>&copy;</code>). The entity reference is converted to the referenced character.
</ul>
<p>
A decimal character reference (for example, <code>&amp;#172;</code>) is <b><i>not</i></b> allowed.</p><li>If its value is <code>False</code>, the default, an ampersand is treated only as a normal character.
</ul></td></tr>
</table>
 
==Exceptions==
<var>EbcdicToAscii</var> can throw the following exception:
<dl>
<dt><var>[[CharacterTranslationException class|CharacterTranslationException]]</var>
<dd>If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.
</dl>
 
==Usage notes==
<ul>
<li><var>EbcdicToAscii</var> is available as of <var class="product">Sirius Mods</var> version 7.3.
</ul>
 
==Examples==
The following fragment shows calls of <var>EbcdicToAscii</var> against a variety of EBCDIC characters.
The [[X (String function)|X]] constant function is used in the example.
<p class="code">%e string Len 20
%a string Len 20
%e = '12'
%a = %e:EbcdicToAscii
Print %a:StringToHex
 
%e = '1&amp;#x0A;2'
%a = %e:EbcdicToAscii(CharacterDecode=True)
Print %a:StringToHex
 
%e = '&amp;copy;'
%a = %e:EbcdicToAscii(CharacterDecode=True)
Print %a:StringToHex
 
%e = 'F1FFF2':X
%a = %e:EbcdicToAscii
 
</p>
The result is:
<p class="output">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 ...
</p>
 
==See also==
<ul><li>You can find the list of XHTML entities on the Internet at the following URL:
<p class="code">http://www.w3.org/TR/xhtml1/dtds.html#h-A2
</p>
<li>There is more information about the [[Unicode#Support_for_the_ASCII_subset_of_Unicode|Unicode tables]].
<li>The inverse of the <var>EbcdicToAscii</var> method is <var>[[AsciiToEbcdic (String function)|AsciiToEbcdic]]</var>.
</ul>
{{Template:String:EbcdicToAscii footer}}

Latest revision as of 19:13, 6 November 2012

Convert EBCDIC string to ASCII (String class)


EbcdicToAscii is an intrinsic function that converts an EBCDIC string to ASCII (ISO 8859-1) using the current Unicode tables. Optionally, character references, entity references, and individual ampersand (&) references are converted to the represented ASCII character.

Syntax

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

Syntax terms

%outString A string variable to receive the method object, string, translated to Ascii.
string An EBCDIC character string.
CharacterDecode The optional (name required) CharacterDecode argument is a Boolean enumeration:
  • 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;. This substring is converted to a single & character.
    • A hexadecimal character reference (for example, the six characters '&#x90;' for the ASCII "Device Control String" character (X'90')). 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 &copy; for the copyright character ©). The entity reference is converted to the referenced character.

    A decimal character reference (for example, &#172;) is not allowed.

  • If its value is False, the default, an ampersand is treated only as a normal character.

Exceptions

EbcdicToAscii 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

  • EbcdicToAscii is available as of Sirius Mods version 7.3.

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 ...

See also