AsciiToEbcdic (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (first pass, match syntax diagram to template and fix tags; still some broken links)
Line 1: Line 1:
{{Template:String:AsciiToEbcdic subtitle}}
{{Template:String:AsciiToEbcdic subtitle}}
<var>AsciiToEbcdic</var> is an <var>[[Intrinsic classes|intrinsic]]</var> function to convert an ASCII (ISO-8859-1) string to EBCDIC using the current <var>[[Unicode]]</var> tables. Optionally, untranslatable characters are represented with character references.


This [[Intrinsic classes|intrinsic]] function converts an ASCII (ISO-8859-1) string to EBCDIC
using the current <var>Unicode</var> tables.
Optionally,
untranslatable characters are represented with character references.
The <var>AsciiToEbcdic</var> function is available as of version 7.3 of the <var class=product>Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:String:AsciiToEbcdic syntax}}
{{Template:String:AsciiToEbcdic syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%ebcdic</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>string</th>
<tr><th><var class="term">string</var></th>
<td>A string that is presumed to consist of ASCII characters.                               </td></tr>
<td>A string that is presumed to consist of ASCII characters.</td></tr>
<tr><th>CharacterEncode=bool</th>
<tr><th>CharacterEncode</th>
<td>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 ASCII character not translatable to EBCDIC.               *If its value is ''''True'''', any ASCII character not translatable to EBCDIC is replaced with the XML style hexadecimal character reference of the character, and the ampersand character is replaced with ''''&amp.amp;''''.                                                                                                   For instance, the six characters '&amp;#x90;' replace the ASCII                     ''Device Control <var>String</var>'' character (X'90').                                 A similar example is shown below.</td></tr>
<td>The optional, but <var>[[Methods#Named parameters|NameRequired]]</var>, argument <var class="term">CharacterEncode</var> argument is a <var>[[Boolean]]</var>; if you specify a value, the parameter name <var class="term">CharacterEncode</var> is required.<ul><li>If its value is <code>False</code>, the default, an exception is thrown if the input <var class="term">string</var> contains any ASCII character not translatable to EBCDIC.<li>If its value is <code>True</code>, any ASCII character not translatable to EBCDIC is replaced with the XML style hexadecimal character reference of the character, and the ampersand character is replaced with <code>'&'</code>.<li>For instance, the six characters <code>'&amp;#x90;'</code> replace the ASCII <i>"Device Control String"</i> character (X'90'). A similar example is shown below.</ul></td></tr>
</table>
</table>


===Exceptions===
==Exceptions==
 
<var>AsciiToEbcdic</var> can throw the following exception:
This [[Intrinsic classes|intrinsic]] 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.
</dl>
</dl>
==Usage notes==
==Usage notes==
*More information is available about the [[Unicode Tables|Unicode tables]].
<ul><li>More information is available about the [[Unicode Tables|Unicode tables]].
*The inverse of the <var>AsciiToEbcdic</var> method is [[EbcdicToAscii (String function) | EbcdicToAscii]].
<li>The <var>AsciiToEbcdic</var> function is available as of <var class="product">Sirius Mods</var> version 7.3.</ul>


==Examples==
==Examples==
 
<ol><li>
The following fragment shows calls of <var>AsciiToEbcdic</var> against strings with and
The following fragment shows calls of <var>AsciiToEbcdic</var> against strings with and without non-translatable characters.
without non-translatable characters.
<p class="code">%a <var>String</var> Len 20
<p class="code">%a <var>String</var> Len 20
%a = [[Intrinsix X function|'31':X]]
%a = [[Intrinsic X function|'31':X]]
Print %a:<var>AsciiToEbcdic</var>
Print %a:<var>AsciiToEbcdic</var>


Line 50: Line 43:


</p>
</p>
</ol>
==See also==
==See also==
<ul><li>The inverse of the <var>AsciiToEbcdic</var> method is <var>[[EbcdicToAscii (String function) | EbcdicToAscii]]</var>.</ul>
{{Template:String:AsciiToEbcdic footer}}
{{Template:String:AsciiToEbcdic footer}}

Revision as of 03:08, 31 January 2011

Convert ASCII string to EBCDIC (String class)

AsciiToEbcdic is an intrinsic function to convert an ASCII (ISO-8859-1) string to EBCDIC using the current Unicode tables. Optionally, untranslatable characters are represented with character references.

Syntax

%outString = string:AsciiToEbcdic[( [CharacterEncode= boolean])] Throws CharacterTranslationException

Syntax terms

%string A string variable to receive the method object string translated to EBCDIC.
string A string that is presumed to consist of ASCII characters.
CharacterEncode The optional, but NameRequired, argument CharacterEncode argument is a Boolean; if you specify a value, the parameter name CharacterEncode is required.
  • If its value is False, the default, an exception is thrown if the input string contains any ASCII character not translatable to EBCDIC.
  • If its value is True, any ASCII character not translatable to EBCDIC is replaced with the XML style hexadecimal character reference of the character, and the ampersand character is replaced with '&'.
  • For instance, the six characters '&#x90;' replace the ASCII "Device Control String" character (X'90'). A similar example is shown below.

Exceptions

AsciiToEbcdic 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

  • More information is available about the Unicode tables.
  • The AsciiToEbcdic function is available as of Sirius Mods version 7.3.

Examples

  1. The following fragment shows calls of AsciiToEbcdic against strings with and without non-translatable characters.

    %a String Len 20 %a = '31':X Print %a:AsciiToEbcdic %a = '318132':X Print %a:AsciiToEbcdic(CharacterEncode=True) Print %a:AsciiToEbcdic

    The result is:

    1 1&#x81;2 CANCELLING REQUEST: MSIR.0751: Class STRING, function ASCIITOEBCDIC: CHARACTER TRANSLATIONEXCEPTION exception: ASCII character X'81' without valid translation to EBCDIC at byte position 1 ...

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=AsciiToEbcdic_(String_function)&oldid=325"