UnicodeToEbcdic (Unicode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (tags and edits)
 
(6 intermediate revisions by 3 users not shown)
Line 4: Line 4:
==Syntax==
==Syntax==
{{Template:Unicode:UnicodeToEbcdic syntax}}
{{Template:Unicode:UnicodeToEbcdic syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%string</th>
<tr><th>%string</th>
<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>unicode</th>
<tr><th>unicode</th>
<td>A <var>Unicode</var> string to be translated.</td></tr>
<td>A <var>Unicode</var> string to be translated.</td></tr>
<tr><th><var>CharacterEncode</var></th>
<tr><th><var>CharacterEncode</var></th>
<td>The optional (<var>[[Methods#Named parameters|NameRequired]]</var>) <var class="term">CharacterEncode</var> argument is a [[Boolean enumeration]]:<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;amp;</code>.  For example, the eight characters <code>&amp;amp;#x201C;</code> replace the Unicode left double-quotation mark (<tt>&amp;#X201C;</tt>). </ul></td></tr>
<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>
</table>


Line 23: Line 29:
==Usage notes==
==Usage notes==
<ul>
<ul>
<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|example]].
<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]].
<li>The <var>UnicodeToEbcdic</var> function is available as of <var class="product">[[Sirius Mods]]</var> Version 7.3.
<li>The <var>UnicodeToEbcdic</var> function is available as of <var class="product">Sirius Mods</var> Version 7.3.
</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;amp;#x31;':[[U (String function)|U]])
<p class="code">%u Unicode Initial('&amp;#x31;':[[U (String function)|U]])
print %u:UnicodeToEbcdic
print %u:UnicodeToEbcdic


%u = '1&amp;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
Line 39: Line 44:
The result of the above fragment is:
The result of the above fragment is:
<p class="output">1
<p class="output">1
1&amp;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
Line 47: Line 52:
<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
<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.
<code>Print %u</code> statements and the results would be the same.
</ol>


==See also==
==See also==
<ul><li>The intrinsic <var>[[String class|String]]</var> method: <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> converts an EBCDIC string to <var>Unicode</var>.</ul>
<ul>
<li>The intrinsic <var>[[String class|String]]</var> method: <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> converts an EBCDIC string to <var>Unicode</var>.
</ul>
{{Template:Unicode:UnicodeToEbcdic footer}}
{{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