UrlDecodeUnicode and FormUrlDecodeUnicode (String functions)

From m204wiki
Revision as of 19:39, 22 August 2011 by JAL2 (talk | contribs) (→‎Usage notes)
Jump to navigation Jump to search

Decode URL encoded characters to unicode (String class)

[Introduced in Sirius Mods 7.9]

UrlDecodeUnicode and FormUrlDecodeUnicode decode data that's been URL encoded or percent-encoded to a unicode string.

Syntax

%unicode = string:UrlDecodeUnicode[( [AllowUntranslatable= boolean])] Throws CharacterTranslationException

%unicode = string:FormUrlDecodeUnicode[( [AllowUntranslatable= boolean])] Throws CharacterTranslationException

Syntax terms

%unicodeThe Unicode variable that results when string is decoded.
stringThe UTF-8 encoded string that contains a URL encoded representation of a unicode string.
boolean Indicates whether unicode characters that cannot be translated back to EBCDIC are to be allowed. If boolean is set to False a unicode character that cannot be translated back to EBCDIC results in request cancellation.

Exceptions

UrlDecodeUnicode and FormUrlDecodeUnicode 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

  • If an EBCDIC version of URL encoded data needs to be converted to unicode, the EBCDIC string must first be assigned to a unicode variable using either implicit EBCDIC to Unicode translation or doing it explicitly with EbcdicToUnicode, converted to UTF-8 using UnicodeToUtf8, and finally translated to unicode using UrlDecodeUnicode. And example below illustrates this process.
  • The difference between FormUrlDecodeUnicode and UrlDecodeUnicode is thatFormUrlDecodeUnicode converts pluses (+) to spaces while UrlDecodeUnicode expects spaces to be percent encoded as %20. UrlDecodeUnicode will throw a CharacterTranslationException exception if it encounters a plus (+). Typically form URL encoding is only used in HTML form posts when the form is posted using the x-www-form-urlencoded content type.
  • URL encoding is mostly used in web applications or for encoding a URI, possibly in an XML namespace declaration.
  • The inverse of UrlDecodeUnicode and FormUrlDecodeUnicode are UnicodeUrlEncode and UnicodeFormUrlEncode, respectively.

Examples

URL decoding an EBCDIC string

The following example URL decodes a URL encoded EBCDIC string to unicode:

b %ebcdic is longstring %unicode is unicode %ebcdic = 'I%20like%20apple%20%CF%80%20and%20eat%20it%204%20%C3%97%20a%20day.' %unicode = %ebcdic:ebcdicToUnicode:unicodeToUtf8:urlDecodeUnicode printText {~} = {%unicode} end

and outputs

%unicode = I like apple π and eat it 4 × a day.

Catching an exception when URL decoding

The following is an example of catching a URL decoding exception. In the following example, the supposedly URL encoded string contains a %2x which is not a valid percent encode hexadecimal value. This results in an exception:

begin %url is longstring %u is unicode %err is object characterTranslationException %url = 'What%20the%20deuce%2xis%20going%20on%20here?':u:unicodeToUtf8 printText ************** {~}="{%url:utf8ToUnicode}" try %u = %url:urlDecodeUnicode printText It worked! {~=%u} catch CharacterTranslationException to %err printText Caught CharacterTranslationException: printText Reason: {%err:reason} printText HexValue: {%err:hexValue} printText Position: {%err:bytePosition} printText Problem: {%err:description} end try end

This outputs:

************** %url:utf8ToUnicode="What%20the%20deuce%2xis%20going%20on%20here?" Caught CharacterTranslationException: Reason: InvalidUrlEncoding HexValue: 78 Position: 21 Problem: invalid URL encoding X'78' at byte position 21: Hexadecimal digit expected

See also