UNICODE_STR or UNISTR scalar function

The UNICODE_STR function returns a string in Unicode UTF-8 or UTF-16, depending on the specified option. The string represents a Unicode encoding of the input string.

Read syntax diagramSkip visual syntax diagramUNICODE_STRUNISTR( string-expression,UTF8,UTF16)

The schema is SYSIBM.

string-expression
An expression that returns a value of a built-in character or graphic string. A character string must not be bit data. Values that are preceded by a backslash ('\') are treated as Unicode UTF-16 characters (for example '\0041' is the Unicode UTF-16 representation for 'A'). A double backslash '\\' indicates a backslash in the string. A partial surrogate character in the expression is replaced with a blank.

The argument can also be a numeric data type. The numeric argument is implicitly cast to a VARCHAR data type.

UTF8 or UTF16
Specifies the Unicode encoding of the result. If UTF8 is specified, the result is returned as a Unicode UTF-8 character string. If UTF16 is specified, the result is returned as a Unicode UTF-16 graphic string. UTF8 is the default.

The result of the function depends on the second argument:

  • VARCHAR if UTF8 is specified
  • VARGRAPHIC if UTF16 is specified

Start of changeThe length attribute of the result depends on the second argument (UTF8 or UTF16). The length attribute of the result is calculated using the formulas in Table 5. If the result is a character string, the length attribute of the result is MIN(n,32704). If the result is a graphic string, the length attribute of the result is MIN(n,16352). Where n is the result of applying the formulas in Table 5 based on input and output data types.End of change

If the actual length of the result string exceeds the maximum for the return type, an error occurs.

The result can be null; if the argument is null, the result is the null value.

Examples

Example 1:
The following example sets the host variable HV1 to a VARCHAR value that represents the Unicode UTF-8 string that corresponds to the argument: 
   SET :HV1 = UNICODE_STR('Hi, my name is \5CF0');
HV1 is assigned a Unicode UTF-8 string with the following value 'Hi, my name is Unicode character U+5CF0'