ConvertChar function

Syntax

ConvertChar(source_str, source_str_category, output_str, target_char_code)

Description

Use the ConvertChar function to convert every character in source_str to type target_char_code, if possible, and place the converted string in output_str. ConvertChar supports the following conversions:

Conversion among Japanese Hankaku (half-width) Katakana, Zenkaku (full-width) Katakana, and Hiragana .
Conversion of Japanese Hankaku (half-width) Katakana, Zenkaku (full-width) Katakana, and Hiragana to Hepburn Romaji (Latin representation).
Conversion of full-width alphanumeric characters to their half-width equivalents.
Conversion of full-width punctuation characters to their half-width equivalents.

Other source_str and target_char_code combinations are either passed through without conversion, or not supported. Character types 0 and 1 (alphanumeric and extended Latin-1) are always passed through to output_str without conversion. See the Supported Conventions section later in this reference entry for details.

If ConvertChar is unable to determine whether the characters in source_str belong to the specified character set, the function returns a value of UNKNOWN (-1). If source_str can be partially converted, ConvertChar will partially convert string, echo the remaining characters to the output string as-is, and return a value of -2 (Completed with Issues).

Parameters

Parameter	Description
Source_str	String to be converted.
Source_str_category	Language category of input string. You can specify either a number or a constant.

Numeric Value	Constant Value	Description
0	%ConvertChar_AlphaNumeric	Half-width AlphaNumeric
1	%ConvertChar_ExtendedLatin1	Extended Latin-1 Characters (ISO8859-1 accents, Spanish, French etc.)
2	%ConvertChar_Japanese	Japanese (any)

Parameter	Description
Output_str	A String variable to receive the converted string.
Target_char_code	Either a Number or a constant representing the conversion target character type. You can specify either a character code numeric value or a constant:

Numeric Value	Constant Value	Description
0	%CharType_AlphaNumeric	Half-width AlphaNumeric — results in a Hepburn Romaji conversion when the input string contains Hiragana or Katakana
2	%CharType_HankakuKatakana	Hankaku Katakana (half—width Japanese Katakana)
3	%CharType_ZenkakuKatakana	Zenkaku Katakana (full-width Japanese Katakana)
4	%CharType_Hiragana	Hiragana (Japanese)
6	%CharType_DBAlphaNumeric	Full-width AlphaNumeric (Japanese)

The following target values are not supported; if the source string is of the same type as any of these values, then the string is passed through without conversion.

Numeric Value	Constant Value	Description
1	%CharType_ExtendedLatin1	Extended Latin-1 characters (ISO8859-1 accents for Spanish, French, etc.)
5	%CharType_Kanji	Chinese, Japanese and Korean ideographic characters.
10	%CharType_JapanesePunctuation	Full- and half-width punctuation, including space (U+0020) and Fullwidth / Ideographic Space (U+3000).

Returns

Returns either a Number or a constant with one of the following values, depending on what you’re checking for:

Numeric Value	Constant Value	Description
1	%ConvertChar_Success	String successfully converted.
0	%ConvertChar_NotConverted	String not converted.
-1	%ConvertChar_Unknown	UNKNOWN: unable to determine whether character is of set char_code. This occurs if the character being checked is an unallocated Unicode codepoint, or was added in a version of Unicode greater than that supported by PeopleTools.
-2	%ConvertChar_Issues	Completed with issues. Conversion executed but there were one or more characters encountered that were either not recognized, or whose conversion is not supported.

Note:

If any character cannot be translated, it is echoed as-is to output_str. output_str could therefore be a mixture of converted and non-converted characters.

Example

This example attempts to convert a string to Hiragana:

&RETVALUE = ConvertChar(&INSTR, 2, &OUTSTR, 4); 
If &RETVALUE = 1 Then 
   WinMessage("Conversion to Hiragana successful"); 
Else 
   If &RETVALUE = 0 Then 
      WinMessage("Conversion to Hiragana failed"); 
   Else 
      If &RETVALUE = - 1 Then 
         WinMessage("Input string is UNKNOWN character type."); 
      Else 
         WinMessage("Some characters could not be converted."); 
      End-If 
   End-If 
End-If

Supported Conversions

The following table shows which conversions are supported, which are passed through without conversion, and which are not supported:

Source	Target	Conversion
0 (Alphanumeric US-ASCII)	0-6 (All supported character types)	Pass through without conversion
1 (Extended Latin-1 characters)	0-6 (All supported character sets)	Pass through without conversion
2 (Hankaku Katakana)	0 (Alphanumeric — Hepburn romaji)	Conversion supported
	1 (Extended Latin)	Not supported
	2 (Hankaku Katakana)	Pass through without conversion
	3 (Zenkaku Katakana)	Conversion supported
	4 (Hiragana)	Conversion supported
	5 (Kanji)	Not supported
	6 (Full-width alphanumeric)	Not supported
3 (Zenkaku Katakana)	0 (Alphanumeric)	Conversion supported
	1 (Extended Latin)	Not supported
	2 (Hankaku Katakana)	Conversion supported
	3 (Zenkaku Katakana)	Pass through without conversion
	4 (Hiragana)	Conversion supported
	5 (Kanji)	Not supported
	6 (Full-width alphanumeric)	Not supported
4 (Hiragana)	0 (Alphanumeric- Hepburn Romaji)	Conversion supported
	1 (Extended Latin)	Not supported
	2 (Hankaku Katakana)	Conversion supported
	3 (Zenkaku Katakana)	Conversion supported
	4 (Hiragana)	Pass through without conversion
	5 (Kanji)	Not supported
	6 (Full-width alphanumeric)	Not supported
5 (Kanji)	0-4, 6	Not supported
	5 (Kanji)	Pass through without conversion
6 (Full-width alphanumeric)	0 (Alphanumeric)	Conversion supported
	1-5	Not supported
	6 (Full-width alphanumeric)	Pass through without conversion
10 (Japanese punctuation)	0 (Alphanumeric)	Conversion supported
	1 (Extended Latin)	Not supported
	3-6, 10	Pass through without conversion

Related Topics