UnicodeToEbcdic (Unicode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(33 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Unicode:UnicodeToEbcdic subtitle}}
{{Template:Unicode:UnicodeToEbcdic subtitle}}
[[Category:Intrinsic Unicode methods|UnicodeToEbcdic function]]
<var>UnicodeToEbcdic</var> converts a <var>Unicode</var> string to EBCDIC.  Optionally, untranslatable characters can be represented with XML style hexadecimal character references.
[[Category:Intrinsic methods]]
<!--DPL?? Category:Intrinsic Unicode methods|UnicodeToEbcdic function: String converted from Unicode to EBCDIC-->
<!--DPL?? Category:Intrinsic methods|UnicodeToEbcdic (Unicode function): String converted from Unicode to EBCDIC-->
<!--DPL?? Category:System methods|UnicodeToEbcdic (Unicode function): String converted from Unicode to EBCDIC-->


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==
==Syntax==
{{Template:Unicode:UnicodeToEbcdic syntax}}
{{Template:Unicode:UnicodeToEbcdic syntax}}
===Syntax terms===
===Syntax terms===
<dl>
<table class="syntaxTable">
<dt><i>%ebcdic</i>
<tr><th>%string</th>
<dd>A string variable to receive the method object string translated to EBCDIC.
<td>A string variable to receive the method object string translated to EBCDIC.</td></tr>
<dt><i>unicode</i>
<dd>A Unicode string.
<dt><b>CharacterEncode=</b><i>bool</i>
<dd>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;amp;</tt>.


For example, the eight characters <tt>&amp;#x201C;</tt> replace the Unicode
<tr><th>unicode</th>
"left double-quotation mark."
<td>A <var>Unicode</var> string to be translated.</td></tr>
</ul>


</dl>
<tr><th><var>CharacterEncode</var></th>
===Exceptions===
<td>The optional ([[Notation conventions for methods#Named parameters|name required]]) <var>CharacterEncode</var> argument is a <var>[[Boolean enumeration]]</var>:
<ul>
<li>If its value is <code>False</code>, the default, an exception is thrown if the input contains any Unicode character not translatable to EBCDIC. <li>If its value is <Code>True</code>, any Unicode 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 (<tt>&#X201C;</tt>).
</ul></td></tr>
</table>


==Exceptions==
This function can throw the following exception:
This function 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.
See [[CharacterTranslationException exception class]].
</dl>
</dl>
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Unless the CharacterEncode argument is used, or
<li>Unless the <var>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|example]].
you want to <tt>Catch</tt> a CharacterTranslationException,
<li>The <var>UnicodeToEbcdic</var> function is available as of <var class="product">Sirius Mods</var> Version 7.3.
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.
<li>The [[EbcdicToUnicode (String function)|EbcdicToUnicode]] method
converts an EBCDIC string to Unicode.
</ul>
</ul>


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


The following example shows multiple calls of UnicodeToEbcdic.
%u = '1&amp;#x80;2':U
The [[U (String function)|U constant function]] is used in the example.
print %u:UnicodeToEbcdic(CharacterEncode=True)
<pre>
print %u:UnicodeToEbcdic
    %u Unicode Initial('&amp;#x31;':U)
</p>
    Print %u:UnicodeToEbcdic
The result of the above fragment is:
<p class="output">1
1&amp;#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 ...
</p>
<b>Note:</b> Because of the implicit conversion of <var>Unicode</var> strings (in this case to <var>String</var>), the <code>Print %u:UnicodeToEbcdic</code> statements in the example above could be replaced by
<code>Print %u</code> statements and the results would be the same.


    %u = '1&amp;#x80;2':U
==See also==
    Print %u:UnicodeToEbcdic(CharacterEncode=True)
<ul>
    Print %u:UnicodeToEbcdic
<li>The intrinsic <var>[[String class|String]]</var> method: <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> converts an EBCDIC string to <var>Unicode</var>.
</pre>
</ul>
The result of the above fragment is:
{{Template:Unicode:UnicodeToEbcdic footer}}
<pre>
    1
    1&amp;#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 ...
</pre>
'''Note:'''
Because of the implicit conversion of Unicode strings (in this case to String),
<br>
the <tt>Print %u:UnicodeToEbcdic</tt> statements in the example above could be
<br>
replaced by <tt>Print %u</tt>  statements and the results would be the same.

Latest revision as of 20:03, 6 November 2012

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 to be translated.
CharacterEncode The optional (name required) CharacterEncode argument is a Boolean enumeration:
  • 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 example.
  • The UnicodeToEbcdic function is available as of Sirius Mods Version 7.3.

Examples

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

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=UnicodeToEbcdic_(Unicode_function)&oldid=12171"