UnicodeToEbcdic (Unicode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (syntax terms, tags and links)
Line 12: Line 12:
<td>A <var>Unicode</var> string. </td></tr>
<td>A <var>Unicode</var> string. </td></tr>
<tr><th>CharacterEncode</th>
<tr><th>CharacterEncode</th>
<td>The optional (<var>[[Methods#Named parameters|Name-Required]]</var>) <var class="term">CharacterEncode</var> argument is a Boolean: <ul><li>If its value is <code>False</code>, the default, an exception is thrown if the input contains any <var>Unicode</var> character not translatable to EBCDIC. <li>If its value is <Code>True</code>, 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 <code>&amp;amp;</code>.
<td>The optional (<var>[[Methods#Named parameters|Name-Required]]</var>) <var class="term">CharacterEncode</var> argument is a Boolean: <ul><li>If its value is <code>False</code>, the default, an exception is thrown if the input contains any <var>Unicode</var> character not translatable to EBCDIC. <li>If its value is <Code>True</code>, 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 <code>&amp;amp;</code>. For example, the eight characters <code>&amp;#x201C;</code> replace the Unicode "left double-quotation mark." (<code>&#X201C;</code>) </ul></td></tr>
For example, the eight characters <code>&amp;#x201C;</code> replace the Unicode "left double-quotation mark." </ul></td></tr>
</table>
</table>


===Exceptions===
==Exceptions==
This function can throw the following exception:
This function can throw the following exception:
<dl>
<dl>
<dt><var>CharacterTranslationException</var>
<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.
See [[CharacterTranslationException exception class]].
</dl>
</dl>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Unless the CharacterEncode argument is used, or
<li>Unless the <var class="term">CharacterEncode</var> argument is used, or you want to <code>Catch</code> a <var>CharacterTranslationException</var>, this function is generally not needed, because a <var>Unicode</var> string is implicitly converted to EBCDIC when used in an EBCDIC context. See the following examples, below.
you want to <tt>Catch</tt> a <var>CharacterTranslationException</var>,
<li>The intrinsic <var>[[String class|String]]</var> method: <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> converts an EBCDIC string to <var>Unicode</var>.
this function is generally not needed, because a <var>Unicode</var> string is
<li>The <var>UnicodeToEbcdic</var> function is available as of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.3.
implicitly converted to EBCDIC when used in an EBCDIC context.
See the example in "Examples," below.
<li>The [[EbcdicToUnicode (String function)|EbcdicToUnicode]] method
converts an EBCDIC string to <var>Unicode</var>.
<li>The <var>UnicodeToEbcdic</var> function is available as of version 7.3 of the <var class=product>Sirius Mods</var>.
</ul>
</ul>


==Examples==
==Examples==
 
<ol><li>The following example shows multiple calls of <var>UnicodeToEbcdic</var>.
The following example shows multiple calls of <var>UnicodeToEbcdic</var>.
<p class="code">%u Unicode Initial('&amp;#x31;':[[U (String function)|U]])
The [[U (String function)|U constant function]] is used in the example.
<p class="code">%u Unicode Initial('&amp;#x31;':U)
Print %u:UnicodeToEbcdic
Print %u:UnicodeToEbcdic


Line 56: Line 47:
  translation to EBCDIC at byte position 5 ...
  translation to EBCDIC at byte position 5 ...
</p>
</p>
'''Note:'''
<b><i>Note:</i></b> Because of the implicit conversion of <var>Unicode</var> strings (in this case to <var>String</var>), the
Because of the implicit conversion of <var>Unicode</var> strings (in this case to <var>String</var>),
<p class="code">Print %u:UnicodeToEbcdic</p>
<br>
statements in the example above could be replaced by
the <tt>Print %u:UnicodeToEbcdic</tt> statements in the example above could be
<p class="code">Print %u</p>
<br>
statements and the results would be the same.
replaced by <tt>Print %u</tt> statements and the results would be the same.
</ol>


==See also==
==See also==
{{Template:Unicode:UnicodeToEbcdic footer}}
{{Template:Unicode:UnicodeToEbcdic footer}}

Revision as of 05:12, 25 February 2011

Translate to Ebcdic (Unicode class)


UnicodeToEbcdic converts a Unicode string to EBCDIC. Optionally, untranslatable characters can be represented with XML style hexadecimal character references.

Syntax

%string = unicode:UnicodeToEbcdic[( [CharacterEncode= boolean])] Throws CharacterTranslationException

Syntax terms

%string A string variable to receive the method object string translated to EBCDIC.
unicode A Unicode string.
CharacterEncode The optional (Name-Required) CharacterEncode argument is a Boolean:
  • If its value is False, the default, an exception is thrown if the input contains any Unicode character not translatable to EBCDIC.
  • If its value is True, any Unicode character not translatable to EBCDIC is replaced with the hexadecimal character reference of the character, and the ampersand character is replaced with &amp;. For example, the eight characters &#x201C; replace the Unicode "left double-quotation mark." ()

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.

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 following examples, below.
  • The intrinsic String method: EbcdicToUnicode converts an EBCDIC string to Unicode.
  • The UnicodeToEbcdic function is available as of "Sirius Mods" Version 7.3.

Examples

  1. The following example shows multiple calls of UnicodeToEbcdic.

    %u Unicode Initial('&#x31;':U) Print %u:UnicodeToEbcdic %u = '1&#x80;2':U Print %u:UnicodeToEbcdic(CharacterEncode=True) Print %u:UnicodeToEbcdic

    The result of the above fragment is:

    1 1&#x0080;2 CANCELLING REQUEST: MSIR.0751: Class STRING, function UNICODETOEBCDIC: CHARACTER TRANSLATIONEXCEPTION exception: Unicode 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.

See also