UnicodeToEbcdic (Unicode function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (1 revision) |
||
| Line 2: | Line 2: | ||
[[Category:Unicode methods|UnicodeToEbcdic function]] | [[Category:Unicode methods|UnicodeToEbcdic function]] | ||
[[Category:Intrinsic methods]] | [[Category:Intrinsic methods]] | ||
<!--DPL?? Category:Unicode methods|<var>UnicodeToEbcdic</var> function: String converted from Unicode to EBCDIC--> | <!--DPL?? Category:<var>Unicode</var> methods|<var>UnicodeToEbcdic</var> function: <var>String</var> converted from <var>Unicode</var> to EBCDIC--> | ||
<!--DPL?? Category:Intrinsic methods|<var>UnicodeToEbcdic</var> (Unicode function): String converted from Unicode to EBCDIC--> | <!--DPL?? Category:Intrinsic methods|<var>UnicodeToEbcdic</var> (<var>Unicode</var> function): <var>String</var> converted from <var>Unicode</var> to EBCDIC--> | ||
<!--DPL?? Category:System methods|<var>UnicodeToEbcdic</var> (Unicode function): String converted from Unicode to EBCDIC--> | <!--DPL?? Category:<var>System</var> methods|<var>UnicodeToEbcdic</var> (<var>Unicode</var> function): <var>String</var> converted from <var>Unicode</var> to EBCDIC--> | ||
This function converts a Unicode string to EBCDIC. | This function converts a <var>Unicode</var> string to EBCDIC. | ||
As an option, | As an option, | ||
untranslatable characters can be represented with XML style hexadecimal | untranslatable characters can be represented with XML style hexadecimal | ||
| Line 19: | Line 19: | ||
<td>A string variable to receive the method object string translated to EBCDIC. </td></tr> | <td>A string variable to receive the method object string translated to EBCDIC. </td></tr> | ||
<tr><th><i>unicode</i></th> | <tr><th><i>unicode</i></th> | ||
<td>A Unicode string. </td></tr> | <td>A <var>Unicode</var> string. </td></tr> | ||
<tr><th><b>CharacterEncode=</b><i>bool</i></th> | <tr><th><b>CharacterEncode=</b><i>bool</i></th> | ||
<td>The optional (name required) CharacterEncode argument is a Boolean: <ul> <li>If its value is <tt>False</tt>, the default, an exception is thrown if the input contains any Unicode character not translatable to EBCDIC. <li>If its value is <tt>True</tt>, any Unicode character not translatable to EBCDIC is replaced with the hexadecimal character reference of the character, and the ampersand character is replaced with <tt>&amp;</tt>. | <td>The optional (name required) CharacterEncode argument is a Boolean: <ul> <li>If its value is <tt>False</tt>, the default, an exception is thrown if the input contains any <var>Unicode</var> character not translatable to EBCDIC. <li>If its value is <tt>True</tt>, any <var>Unicode</var> character not translatable to EBCDIC is replaced with the hexadecimal character reference of the character, and the ampersand character is replaced with <tt>&amp;</tt>. | ||
For example, the eight characters <tt>&#x201C;</tt> replace the Unicode "left double-quotation mark." </ul></td></tr> | For example, the eight characters <tt>&#x201C;</tt> replace the <var>Unicode</var> "left double-quotation mark." </ul></td></tr> | ||
</table> | </table> | ||
===Exceptions=== | ===Exceptions=== | ||
| Line 28: | Line 28: | ||
This function can throw the following exception: | This function can throw the following exception: | ||
<dl> | <dl> | ||
<dt>CharacterTranslationException | <dt><var>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. | ||
| Line 36: | Line 36: | ||
<ul> | <ul> | ||
<li>Unless the CharacterEncode argument is used, or | <li>Unless the CharacterEncode argument is used, or | ||
you want to <tt>Catch</tt> a CharacterTranslationException, | you want to <tt>Catch</tt> a <var>CharacterTranslationException</var>, | ||
this function is generally not needed, because a Unicode string is | this function is generally not needed, because a <var>Unicode</var> string is | ||
implicitly converted to EBCDIC when used in an EBCDIC context. | implicitly converted to EBCDIC when used in an EBCDIC context. | ||
See the example in "Examples," below. | See the example in "Examples," below. | ||
<li>The [[EbcdicToUnicode (String function)|EbcdicToUnicode]] method | <li>The [[EbcdicToUnicode (String function)|EbcdicToUnicode]] method | ||
converts an EBCDIC string to Unicode. | converts an EBCDIC string to <var>Unicode</var>. | ||
</ul> | </ul> | ||
| Line 49: | Line 49: | ||
The [[U (String function)|U constant function]] is used in the example. | The [[U (String function)|U constant function]] is used in the example. | ||
<pre> | <pre> | ||
%u Unicode Initial('&#x31;':U) | %u <var>Unicode</var> Initial('&#x31;':U) | ||
Print %u:<var>UnicodeToEbcdic</var> | Print %u:<var>UnicodeToEbcdic</var> | ||
| Line 62: | Line 62: | ||
CANCELLING REQUEST: MSIR.0751: Class STRING, function | CANCELLING REQUEST: MSIR.0751: Class STRING, function | ||
UNICODETOEBCDIC: CHARACTER TRANSLATIONEXCEPTION | UNICODETOEBCDIC: CHARACTER TRANSLATIONEXCEPTION | ||
exception: Unicode character U+0080 without valid | exception: <var>Unicode</var> character U+0080 without valid | ||
translation to EBCDIC at byte position 5 ... | translation to EBCDIC at byte position 5 ... | ||
</pre> | </pre> | ||
'''Note:''' | '''Note:''' | ||
Because of the implicit conversion of Unicode strings (in this case to String), | Because of the implicit conversion of <var>Unicode</var> strings (in this case to <var>String</var>), | ||
<br> | <br> | ||
the <tt>Print %u:<var>UnicodeToEbcdic</var></tt> statements in the example above could be | the <tt>Print %u:<var>UnicodeToEbcdic</var></tt> statements in the example above could be | ||
<br> | <br> | ||
replaced by <tt>Print %u</tt> statements and the results would be the same. | replaced by <tt>Print %u</tt> statements and the results would be the same. | ||
Revision as of 15:49, 20 January 2011
Translate to Ebcdic (Unicode class)
This function converts a Unicode string to EBCDIC. As an option, untranslatable characters can be represented with XML style hexadecimal character references.
The UnicodeToEbcdic function is available as of version 7.3 of the Sirius Mods.
Syntax
%string = unicode:UnicodeToEbcdic[( [CharacterEncode= boolean])] Throws CharacterTranslationException
Syntax terms
| %ebcdic | A string variable to receive the method object string translated to EBCDIC. |
|---|---|
| unicode | A Unicode string. |
| CharacterEncode=bool | The optional (name required) CharacterEncode argument is a Boolean:
|
Exceptions
This 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. See CharacterTranslationException exception class.
Usage notes
- Unless the CharacterEncode argument is used, or you want to Catch a CharacterTranslationException, this function is generally not needed, because a Unicode string is implicitly converted to EBCDIC when used in an EBCDIC context. See the example in "Examples," below.
- The EbcdicToUnicode method converts an EBCDIC string to Unicode.
Examples
The following example shows multiple calls of UnicodeToEbcdic. The U constant function is used in the example.
%u <var>Unicode</var> Initial('1':U)
Print %u:<var>UnicodeToEbcdic</var>
%u = '1€2':U
Print %u:<var>UnicodeToEbcdic</var>(CharacterEncode=True)
Print %u:<var>UnicodeToEbcdic</var>
The result of the above fragment is:
1
1€2
CANCELLING REQUEST: MSIR.0751: Class STRING, function
UNICODETOEBCDIC: CHARACTER TRANSLATIONEXCEPTION
exception: <var>Unicode</var> character U+0080 without valid
translation to EBCDIC at byte position 5 ...
Note:
Because of the implicit conversion of Unicode strings (in this case to String),
the Print %u:UnicodeToEbcdic statements in the example above could be
replaced by Print %u statements and the results would be the same.