EbcdicToAscii (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (first pass, match syntax diagram to template and fix tags; still some broken links)
Line 1: Line 1:
{{Template:String:EbcdicToAscii subtitle}}
{{Template:String:EbcdicToAscii subtitle}}


This [[Intrinsic classes|intrinsic]] function converts an EBCDIC string to ASCII (ISO 8859-1)
<var>EbcdicToAscii</var> is an <var>[[Intrinsic classes|intrinsic]]</var> function that converts an EBCDIC string to ASCII (ISO 8859-1) using the current <var>[[Unicode]]</var> tables. Optionally, character references, entity references, and <code>'&'</code> references are converted to the represented ASCII character.
using the current <var>Unicode</var> tables.
Optionally, character references, entity references, and ''''&amp.amp;'''' references are converted to the represented ASCII character.


The <var>EbcdicToAscii</var> function is available as of version 7.3 of the <var class=product>Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:String:EbcdicToAscii syntax}}
{{Template:String:EbcdicToAscii syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%ascii</th>
<tr><th>%string</th>
<td>A string variable to receive the method object string translated to Ascii. </td></tr>
<td>A string variable to receive the method object <var class="term">string</var> translated to Ascii.</td></tr>
<tr><th>string</th>
<tr><th><var class="term">string</var></th>
<td>An EBCDIC character string.       </td></tr>
<td>An EBCDIC character string.</td></tr>
<tr><th>CharacterDecode=bool</th>
<tr><th><var class="term">CharacterDecode</var></th>
<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 <var>String</var>'' control character). The character reference is converted to the referenced character. **As of <var class=product>Sirius Mods</var> 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>
<td>The optional (name required) <var class="term">CharacterDecode</var> argument is a [[Boolean enumeration]]:
<ul><li>If its value is <code>True</code>, an ampersand (<code>&</code>) 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 ''''&amp;amp;''''. This substring is converted to a single ''''&'''' character.<li>A hexadecimal character reference (for example, the six characters <code>'&amp;#x90;'</code> for the ASCII <i>Device Control String</i> 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). The entity reference is converted to the referenced character. A decimal character reference (for example, &amp;#172;) is <b><i>not</i></b> allowed.</ul><li>If its value is <code>False</code>, the default, an ampersand is treated only as a normal character.</ul></td></tr>
</table>
</table>


===Exceptions===
===Exceptions===
This [[Intrinsic classes|intrinsic]] function can throw the following exception:
<var>EbcdicToAscii</var> can throw the following exception:
<dl>
<dl>
<dt>[[CharacterTranslationException]]
<dt><var>[[CharacterTranslationException class|CharacterTranslationException]]</var>
<dd>If the method encounters a translation problem,
<dd>If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.
properties of the exception object may indicate the location and type of problem.
</dl>
</dl>
==Usage notes==
==Usage notes==
*You can find the list of XHTML entities on the Internet at the following URL:
<ul>
<p class="code">http://www.w3.org/TR/xhtml1/dtds.html#h-A2
<li><var>EbcdicToAscii</var> is available as of <var class="product">Sirius Mods</var> version 7.3.
</p>
</ul>
*There is more information about the [[Unicode tables]].
*The inverse of the <var>EbcdicToAscii</var> method is [[AsciiToEbcdic (String function)|AsciiToEbcdic]].


==Examples==
==Examples==
The following fragment shows calls of <var>EbcdicToAscii</var> against a variety of EBCDIC characters.
<ol><li>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.
The [[X (String function)|X]] constant function is used in the example.
<p class="code">%e <var>String</var> Len 20
<p class="code">%e string Len 20
%a <var>String</var> Len 20
%a string Len 20
%e = '12'
%e = '12'
%a = %e:<var>EbcdicToAscii</var>
%a = %e:EbcdicToAscii
Print %a:<var>String</var>ToHex
Print %a:StringToHex


%e = '1&amp;#x0A;2'
%e = '1&amp;#x0A;2'
%a = %e:<var>EbcdicToAscii</var>(CharacterDecode=True)
%a = %e:EbcdicToAscii(CharacterDecode=True)
Print %a:<var>String</var>ToHex
Print %a:StringToHex


%e = '&amp;copy;'
%e = '&amp;copy;'
%a = %e:<var>EbcdicToAscii</var>(CharacterDecode=True)
%a = %e:EbcdicToAscii(CharacterDecode=True)
Print %a:<var>String</var>ToHex
Print %a:StringToHex


%e = 'F1FFF2':X
%e = 'F1FFF2':X
%a = %e:<var>EbcdicToAscii</var>
%a = %e:EbcdicToAscii


</p>
</p>
Line 57: Line 53:
310A32
310A32
A9
A9
CANCELLING REQUEST: MSIR.0751: Class STRING, function
CANCELLING REQUEST: MSIR.0751: Class STRING, function EBCDICTOASCII:
   EBCDICTOASCII: CHARACTER TRANSLATIONEXCEPTION
   CHARACTER TRANSLATIONEXCEPTION exception: EBCDIC character X'FF'
  exception: EBCDIC character X'FF' without valid
  without valid translation to ASCII at byte position 2 ...
  translation to ASCII at byte position 2 ...
</p>
</ol>


==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>
</p>
==See also==
<li>There is more information about the [[Unicode tables]].
<li>The inverse of the <var>EbcdicToAscii</var> method is [[AsciiToEbcdic (String function)|AsciiToEbcdic]].
</ul>
{{Template:String:EbcdicToAscii footer}}
{{Template:String:EbcdicToAscii footer}}

Revision as of 05:09, 31 January 2011

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 '&' references are converted to the represented ASCII character.

Syntax

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

Syntax terms

%string 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

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

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=EbcdicToAscii_(String_function)&oldid=631"