0LASubrTextFromUnicode < Main

---+ .TEXT FROM UNICODE

This subroutine transcodes a Unicode alpha field into a RAW alpha field. Added in 6.0.0

<br /><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1">%TOC%</span></span></span></span></span></span></span></span></span></span>
---++ Usage
<pre>      PASS         &lt;raw&gt;                      FIELD            SHARE? Y
      PASS         &lt;unicode_source&gt;           FIELD            SHARE? N
      PASS         &lt;encoding&gt;                 FIELD            SHARE? N
      PASS         &lt;action&gt;                   FIELD            SHARE? N
      PASS         &lt;option&gt;                   FIELD            SHARE? N
      PASS         &lt;error_text&gt;               FIELD            SHARE? Y
      GOSUB    --- .TEXT FROM UNICODE
      *        Check for errors
      IF       --- .TEXT FROM UNICODE         NE
</pre>

---++ Description

This subroutine will transcode a Unicode alpha field to a RAW alpha field with error handling for the characters that cannot be transcoded. The first 2 parameters are required. If any required parameters are missing, the subroutine will CANCEL.

&lt;raw&gt; is the RAW alpha field to contain the transcoded string (Required). This must be PASSed with Share "Y" to return the value. *This must be a RAW field type, otherwise the transcoding will fail.*

&lt;unicode_source&gt; is the field containing the Unicode string to be transcoded (Required).

&lt;encoding&gt; is the encoding to use in the RAW target field. If not specified or a blank is PASSed, it will check the environment variable APPX_RAW_ENCODING and use that encoding. If that is not present, it will default to ISO-8859-15.

&lt;action&gt; is the action to be taken if a character cannot be transcoded to RAW (Optional). If not PASSed or blank is PASSed, defaults to SKIP.
   * SKIP - skip the offending character, it will not be transcoded to the target field but the remaining characters will be.
   * STOP - stop transcoding and return an error
   * SUBS - Substitute the character in the &lt;option&gt; field for the offending character
   * ESCAPE - Escape the character according to the convention specified in the &lt;option&gt; field
&lt;option&gt; contains either the substitute character to use if &lt;action&gt; is SUBS or the convention to use if &lt;action&gt; is ESCAPE. This is required if &lt;action&gt; is SUBS or ESCAPE. If &lt;action&gt; is SUBS you may pass any single character that exists in the target encoding. If more than one character is PASSed, only the first character is used. If &lt;action&gt; is ESCAPE, then PASS one of the following:
   * <span data-mce-mark="1" style="background-color: transparent;">C - specifies C style escaping (\uXXXX or \UXXXXXXXX)</span>
   * <span data-mce-mark="1" style="background-color: transparent;">STYLE - specifies CSS2 escaping (\XXXXXX)</span>
   * <span data-mce-mark="1" style="background-color: transparent;">JAVA - specifies Java escaping (\uXXXX)</span>
   * <span data-mce-mark="1" style="background-color: transparent;">UNICODE - specifies Unicode escaping {U+XXXXX}</span>
   * <span data-mce-mark="1" style="background-color: transparent;">DECIMAL - - specifies XML decimal escaping ($#XXXX)</span>
   * <span data-mce-mark="1" style="background-color: transparent;">X - specifies XML hex escaping (&#xXXXX)</span>
&lt;error text&gt; if an error occured this field contains additional error text from the Unicode library (Optional). This must be PASSed with Share "Y" to return the value.

Note: This subroutine is designed to operate on Alpha, Text, and Token fields only. The returned results are undefined if you specify any other type of field.
---++ Examples

Given a Unicode string containing 'a&#x24F;b', here are the results with various options (the &#x24F; character does not exist in the ISO-8859-15 encoding).
| *Option* | *Result* |
| SKIP | 'ab' |
| STOP | 'a'. The field .TEXT FROM UNICODE contains ".UC_FROM_UCODE Fail" and &lt;error&gt; contains "U_INVALID_CHAR_FOUND" |
| SUBS | 'a*b', assuming '*' was passed in &lt;option&gt; field as a substitute character. |
| ESCAPE | 'a\u024Fb' if C is PASSed as &lt;option&gt; |
| ESCAPE | 'a\24F b' if STYLE is PASSed as &lt;option&gt; |
| ESCAPE | 'a\u024Fb' if JAVA is PASSed as &lt;option&gt; |
| ESCAPE | 'a{U+024F}b' if UNICODE is PASSed as &lt;option&gt; |
| ESCAPE | 'a&#x24F;b' if DECIMAL is PASSed as &lt;option&gt; |
| ESCAPE | 'a&#x24F;b' if X is PASSed as &lt;option&gt; |
 

<span style="background-color: #f6f6f6; color: #630000; font-size: 18.85px;">Comments</span>

<br /><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1">%COMMENT%</span></span></span></span></span></span></span></span></span></span>

-- <span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1"><span data-mce-mark="1">%USERSIG{JeanNeron - 2017-11-02}%</span></span></span></span></span></span></span></span></span></span>
This topic: Main > WebHome > FullAPIList > 0LASubrTextFromUnicode
Topic revision: r5 - 2023-04-10 - BrianRyan