UNICODE_STR

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

The length attribute of the result is 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 MAX(n,32704). If the result is a graphic string, the length attribute of the result is MAX(n,16352). Where n is the result of applying the formulas in Table 5 based on input and output data types.

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.

UNISTR can be specified as a synonym for UNICODE_STR.

Example: 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 '