UnicodeToEbcdic (Unicode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "<span style="font-size:120%; color:black"><b>String converted from Unicode to EBCDIC</b></span> UnicodeToEbcdic function [[Category:Intrins...")
 
 
(38 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>String converted from Unicode to EBCDIC</b></span>
{{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]]
[[Category:System 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.
==Syntax==
As an option,
{{Template:Unicode:UnicodeToEbcdic syntax}}
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 terms===
===Syntax===
<table class="syntaxTable">
  %ebcdic = unicode:UnicodeToEbcdic([CharacterEncode=bool])
<tr><th>%string</th>
====Syntax Terms====
<td>A string variable to receive the method object string translated to EBCDIC.</td></tr>
<dl>
<dt><i>%ebcdic</i>
<dd>A string variable to receive the method object string translated to EBCDIC.
<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>
&ldquo;left double-quotation mark.&rdquo;
<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 &ldquo;Examples,&rdquo; below.
<li>The EbcdicToUnicode method (??[[EbcdicToUnicode (String function)|EbcdicToUnicode]])
converts an EBCDIC string to Unicode.
</ul>
</ul>
===Examples===


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


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

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"