UnicodeToEbcdic (Unicode function): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (→Usage notes) |
||
| (10 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Unicode:UnicodeToEbcdic subtitle}} | {{Template:Unicode:UnicodeToEbcdic subtitle}} | ||
<var>UnicodeToEbcdic</var> converts a <var>Unicode</var> string to EBCDIC. Optionally, untranslatable characters can be represented with XML style hexadecimal character references. | <var>UnicodeToEbcdic</var> converts a <var>Unicode</var> string to EBCDIC. Optionally, untranslatable characters can be represented with XML style hexadecimal character references. | ||
==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. </td></tr> | <td>A <var>Unicode</var> string to be translated.</td></tr> | ||
<tr><th>CharacterEncode</th> | |||
<td>The optional ( | <tr><th><var>CharacterEncode</var></th> | ||
For example, the eight characters <code>&#x201C;</code> replace the Unicode | <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;</code>. For example, the eight characters <code>&#x201C;</code> replace the Unicode left double-quotation mark (<tt>“</tt>). | |||
</ul></td></tr> | |||
</table> | </table> | ||
==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 | |||
</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 < | <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 <var>Unicode</var> string is | |||
implicitly converted to EBCDIC when used in an EBCDIC context. | |||
See the | |||
<li>The <var>UnicodeToEbcdic</var> function is available as of | |||
</ul> | </ul> | ||
==Examples== | ==Examples== | ||
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('&#x31;':[[U (String function)|U]]) | |||
<p class="code">%u Unicode Initial('&#x31;':U) | print %u:UnicodeToEbcdic | ||
%u = '1&#x80;2':U | %u = '1&#x80;2':U | ||
print %u:UnicodeToEbcdic(CharacterEncode=True) | |||
print %u:UnicodeToEbcdic | |||
</p> | </p> | ||
The result of the above fragment is: | The result of the above fragment is: | ||
| Line 56: | Line 50: | ||
translation to EBCDIC at byte position 5 ... | translation to EBCDIC at byte position 5 ... | ||
</p> | </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 | |||
Because of the implicit conversion of <var>Unicode</var> strings (in this case to <var>String</var>), | <code>Print %u</code> statements and the results would be the same. | ||
the < | |||
replaced by < | |||
==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> | |||
{{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:
|
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
Catcha 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('1':U) print %u:UnicodeToEbcdic %u = '1€2':U print %u:UnicodeToEbcdic(CharacterEncode=True) print %u:UnicodeToEbcdic
The result of the above fragment is:
1 1€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
- The intrinsic String method: EbcdicToUnicode converts an EBCDIC string to Unicode.