EbcdicToAscii (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
Line 17: Line 17:
<td>The optional (name required) <var>CharacterDecode</var> argument is a <var>[[Boolean enumeration|Boolean]]</var> enumeration:
<td>The optional (name required) <var>CharacterDecode</var> argument is a <var>[[Boolean enumeration|Boolean]]</var> enumeration:
<ul>
<ul>
<li>If its value is <code>True</code>, an ampersand (<code>&amp;</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 <code>&</code>. This substring is converted to a single <code>&amp;</code> character.
<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>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.

Revision as of 19:10, 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 2' %a = %e:EbcdicToAscii(CharacterDecode=True) Print %a:StringToHex %e = '©' %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