UTF8(x) returns a CHAR value that is the UTF-8 equivalent of x.
>>-UTF8(x-+----+-)--------------------------------------------->< '-,c-'
- x
- An expression that must have one of these types: FIXED, FLOAT, PICTURE, BIT, CHAR, or WIDECHAR.
- c
- A restricted expression that specifies the code page of the source.
It is ignored if x has WIDECHAR type.
The code page must have a computational type and is converted to type FIXED BINARY (31,0). The code page must specify a valid, supported code page.
If x has the type other than WIDECHAR, the CODEPAGE option specifies the value for the code page of x when it is converted to UTF-8.
If x has the WIDECHAR type, it is converted to UTF-8 under the assumption that x holds UTF-16.
You can use UTF8(x) in restricted expressions. Therefore, you can use UTF8(x) to create UTF-8 literals.
Notes:
- If x has the CHAR type, the length of UTF8(x) might be two times as large as the length of x. If x has the WCHAR type, the length of UTF8(x) might be three times as the length of x. If the length of UTF8 exceeds the maximum length of CHAR, the generated code raises the ERROR condition.
- If x has the WCHAR type and holds invalid UTF-16 data, the generated code raises the ERROR condition.
- For example, UTF8('babb'x,1140) and UTF8('63fc'x,1141) will both return '5b5d'x. Because on code page 1140, 'ba'x and 'bb'x correspond to UTF-8 characters '5b'x and '5d'x; but on code page 1141, '63'x and 'fc'x map to UTF-8 characters '5b'x and '5d'x.