EbcdicToUnicode (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
Line 1: Line 1:
{{Template:String:EbcdicToUnicode subtitle}}
{{Template:String:EbcdicToUnicode subtitle}}


This [[Intrinsic classes|intrinsic]] function converts an EBCDIC string to Unicode
This [[Intrinsic classes|intrinsic]] function converts an EBCDIC string to <var>Unicode</var>
using the current Unicode tables.
using the current <var>Unicode</var> tables.
As an option, XML style hexadecimal character references, XHTML entity references,
As an option, XML style hexadecimal character references, XHTML entity references,
and ''''&amp;amp;'''' references are converted to the represented Unicode character.
and ''''&amp;amp;'''' references are converted to the represented <var>Unicode</var> character.
An additional option lets you specify how to handle untranslatable EBCDIC characters.
An additional option lets you specify how to handle untranslatable EBCDIC characters.


Line 13: Line 13:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%unicode</th>
<tr><th>%unicode</th>
<td>A string variable to receive the method object string translated to Unicode.</td></tr>
<td>A string variable to receive the method object string translated to <var>Unicode</var>.</td></tr>
<tr><th>string</th>
<tr><th>string</th>
<td>An EBCDIC character string.</td></tr>
<td>An EBCDIC character string.</td></tr>
<tr><th>CharacterDecode=bool</th>
<tr><th>CharacterDecode=bool</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 eight characters '&amp;#x201C;' for the Unicode ''Left double quotation mark''). 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.
<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 eight characters '&amp;#x201C;' for the <var>Unicode</var> ''Left double quotation mark''). 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>
If its value is ''''False'''', the default, an ampersand is treated only as a normal character. </td></tr>
<tr><th>Untranslatable=char</th>
<tr><th>Untranslatable=char</th>
<td>The optional (name required) Untranslatable argument is a single character or a null string that specifies how to handle EBCDIC input characters that are not translatable to Unicode:
<td>The optional (name required) Untranslatable argument is a single character or a null string that specifies how to handle EBCDIC input characters that are not translatable to <var>Unicode</var>:
*If the value is a single Unicode character, any untranslatable EBCDIC characters are replaced with that Unicode character.
*If the value is a single <var>Unicode</var> character, any untranslatable EBCDIC characters are replaced with that <var>Unicode</var> character.
*If the value is the null string, any untranslatable EBCDIC characters are removed from the input string.                The ''''Untranslatable'''' parameter is optional. If it is omitted and an EBCDIC character is encountered that is not translatable to Unicode, a [[CharacterTranslationException]] exception is thrown.
*If the value is the null string, any untranslatable EBCDIC characters are removed from the input string.                The ''''Untranslatable'''' parameter is optional. If it is omitted and an EBCDIC character is encountered that is not translatable to <var>Unicode</var>, a [[CharacterTranslationException]] exception is thrown.


The Untranslatable parameter is available as of <var class=product>Sirius Mods</var> version 7.5. It provides the functionality formerly provided by the EbcdicTranslateNonUnicode and the EbcdicRemoveNonUnicode methods, which are invalid as of <var class=product>Sirius Mods</var> 7.5.</td></tr>
The Untranslatable parameter is available as of <var class=product>Sirius Mods</var> version 7.5. It provides the functionality formerly provided by the EbcdicTranslateNon<var>Unicode</var> and the EbcdicRemoveNon<var>Unicode</var> methods, which are invalid as of <var class=product>Sirius Mods</var> 7.5.</td></tr>
</table>
</table>


Line 31: Line 31:
This [[Intrinsic classes|intrinsic]] function can throw the following exception:
This [[Intrinsic classes|intrinsic]] function can throw the following exception:
<dl>
<dl>
<dt>CharacterTranslationException
<dt><var>CharacterTranslationException</var>
<dd>If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.
<dd>If the method encounters a translation problem, properties of the exception object may indicate the location and type of problem.
</dl>
</dl>
Line 40: Line 40:
*The [[EbcdicToAscii (String function)|EbcdicToAscii]] method converts an EBCDIC string to ASCII.
*The [[EbcdicToAscii (String function)|EbcdicToAscii]] method converts an EBCDIC string to ASCII.
*The [[U (String function)|U]] function is a compile-time-only equivalent of the <var>EbcdicToUnicode</var> method (with CharacterDecode argument implicitly set to ''''True'''').
*The [[U (String function)|U]] function is a compile-time-only equivalent of the <var>EbcdicToUnicode</var> method (with CharacterDecode argument implicitly set to ''''True'''').
*Using <var>EbcdicToUnicode</var> (or the U function) is necessary if the string you want to convert to Unicode may contain a hexadecimal character reference. Such a reference cannot be meaningfully assigned to a Unicode variable otherwise.
*Using <var>EbcdicToUnicode</var> (or the U function) is necessary if the string you want to convert to <var>Unicode</var> may contain a hexadecimal character reference. Such a reference cannot be meaningfully assigned to a <var>Unicode</var> variable otherwise.


==Examples==
==Examples==
The following fragment shows four calls of <var>EbcdicToUnicode</var>: respectively against translatable EBCDIC characters, a string with a character reference, a string with an entity reference, and a string with an EBCDIC character that cannot be translated to Unicode.
The following fragment shows four calls of <var>EbcdicToUnicode</var>: respectively against translatable EBCDIC characters, a string with a character reference, a string with an entity reference, and a string with an EBCDIC character that cannot be translated to <var>Unicode</var>.
The [[X (String 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
     %e <var>String</var> Len 20
     %u Unicode
     %u <var>Unicode</var>
     %e = '12'
     %e = '12'
     %u = %e:<var>EbcdicToUnicode</var>
     %u = %e:<var>EbcdicToUnicode</var>
     Print %u
     Print %u
     Print %u:UnicodeToUtf16:StringToHex
     Print %u:<var>Unicode</var>ToUtf16:<var>String</var>ToHex


     %e = '1&amp;#x2122;2'
     %e = '1&amp;#x2122;2'
     %u = %e:<var>EbcdicToUnicode</var>(CharacterDecode=True)
     %u = %e:<var>EbcdicToUnicode</var>(CharacterDecode=True)
     Print %u:UnicodeToUtf16:StringToHex
     Print %u:<var>Unicode</var>ToUtf16:<var>String</var>ToHex


     %e = '&amp;copy;'
     %e = '&amp;copy;'
Line 71: Line 71:
       EBCDICTOUNICODE: CHARACTER TRANSLATIONEXCEPTION
       EBCDICTOUNICODE: CHARACTER TRANSLATIONEXCEPTION
       exception: EBCDIC character X'FF' without valid
       exception: EBCDIC character X'FF' without valid
       translation to Unicode at byte position 2 ...
       translation to <var>Unicode</var> at byte position 2 ...
====Note====
====Note====
The initial ''''Print %u'''' statement in the example above is not very revealing because it is
The initial ''''Print %u'''' statement in the example above is not very revealing because it is
equivalent to specifying ''''Print %u:[[UnicodeToEbcdic (Unicode function)|UnicodeToEbcdic]]'''' &mdash;
equivalent to specifying ''''Print %u:[[UnicodeToEbcdic (Unicode function)|UnicodeToEbcdic]]'''' &mdash;
a Unicode string is implicitly converted to EBCDIC
a <var>Unicode</var> string is implicitly converted to EBCDIC
when it is used in an EBCDIC context like a Print statement.
when it is used in an EBCDIC context like a Print statement.
The [[UnicodeToUtf16 (Unicode function)|UnicodeToUtf16]] method, however, converts the Unicode variable to a byte-stream string, which the [[StringToHex (String function)|StringToHex]] method converts to its hex representation.
The [[UnicodeToUtf16 (Unicode function)|UnicodeToUtf16]] method, however, converts the Unicode variable to a byte-stream string, which the [[StringToHex (String function)|StringToHex]] method converts to its hex representation.

Revision as of 15:48, 20 January 2011

Convert EBCDIC string to Unicode (String class)


This intrinsic function converts an EBCDIC string to Unicode using the current Unicode tables. As an option, XML style hexadecimal character references, XHTML entity references, and '&amp;' references are converted to the represented Unicode character. An additional option lets you specify how to handle untranslatable EBCDIC characters.

The EbcdicToUnicode function is available as of version 7.3 of the Sirius Mods.

Syntax

%unicode = string:EbcdicToUnicode[( [CharacterDecode= boolean], - [Untranslatable= unicode])] Throws CharacterTranslationException

Syntax terms

%unicode A string variable to receive the method object string translated to Unicode.
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 '&amp;'. This substring is converted to a single '&' character. **A hexadecimal character reference (for example, the eight characters '&#x201C;' for the Unicode Left double quotation mark). 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.
Untranslatable=char The optional (name required) Untranslatable argument is a single character or a null string that specifies how to handle EBCDIC input characters that are not translatable to Unicode:
  • If the value is a single Unicode character, any untranslatable EBCDIC characters are replaced with that Unicode character.
  • If the value is the null string, any untranslatable EBCDIC characters are removed from the input string. The 'Untranslatable' parameter is optional. If it is omitted and an EBCDIC character is encountered that is not translatable to Unicode, a CharacterTranslationException exception is thrown.
The Untranslatable parameter is available as of Sirius Mods version 7.5. It provides the functionality formerly provided by the EbcdicTranslateNonUnicode and the EbcdicRemoveNonUnicode methods, which are invalid as of Sirius Mods 7.5.

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
  • More information is available about the Unicode tables.
  • The EbcdicToAscii method converts an EBCDIC string to ASCII.
  • The U function is a compile-time-only equivalent of the EbcdicToUnicode method (with CharacterDecode argument implicitly set to 'True').
  • Using EbcdicToUnicode (or the U function) is necessary if the string you want to convert to Unicode may contain a hexadecimal character reference. Such a reference cannot be meaningfully assigned to a Unicode variable otherwise.

Examples

The following fragment shows four calls of EbcdicToUnicode: respectively against translatable EBCDIC characters, a string with a character reference, a string with an entity reference, and a string with an EBCDIC character that cannot be translated to Unicode. The X constant function is used in the example.

   %e String Len 20
   %u Unicode
   %e = '12'
   %u = %e:EbcdicToUnicode
   Print %u
   Print %u:UnicodeToUtf16:StringToHex
   %e = '1&#x2122;2'
   %u = %e:EbcdicToUnicode(CharacterDecode=True)
   Print %u:UnicodeToUtf16:StringToHex
   %e = '&copy;'
   %u = %e:EbcdicToUnicode(CharacterDecode=True)
   Print %u
   %e = 'F1FFF2':X
   %u = %e:EbcdicToUnicode

The result of the above fragment is:

   12
   00310032
   003121220032
   ©
   CANCELLING REQUEST: MSIR.0751: Class STRING, function
     EBCDICTOUNICODE: CHARACTER TRANSLATIONEXCEPTION
     exception: EBCDIC character X'FF' without valid
     translation to Unicode at byte position 2 ...

Note

The initial 'Print %u' statement in the example above is not very revealing because it is equivalent to specifying 'Print %u:UnicodeToEbcdic' — a Unicode string is implicitly converted to EBCDIC when it is used in an EBCDIC context like a Print statement. The UnicodeToUtf16 method, however, converts the Unicode variable to a byte-stream string, which the StringToHex method converts to its hex representation.

See also

List of intrinsic String methods