DBCLOB

The DBCLOB function returns a DBCLOB representation of a character string value (with the single-byte characters converted to double-byte characters) or a graphic string value.

Character to DBCLOB:

>>-DBCLOB(character-expression-+------------------------------------+-)-><
                               '-,--integer--+--------------------+-'     
                                             '-,--+-CODEUNITS16-+-'       
                                                  '-CODEUNITS32-'

Graphic to DBCLOB:

>>-DBCLOB(graphic-expression-+------------------------------------+-)-><
                             '-,--integer--+--------------------+-'     
                                           '-,--+-CODEUNITS16-+-'       
                                                '-CODEUNITS32-'

The schema is SYSIBM.

Character to DBCLOB

character-expression

An expression that returns a value that is an EBCDIC-encoded or Unicode-encoded character string. It cannot be BIT data. The argument does not need to be mixed data, but any occurrences of X'0E' and X'0F' in the string must conform to the rules for EBCDIC mixed data. (See Character strings for these rules.)

integer

The length attribute of the resulting DBCLOB. The value of integer must be between 1 and the maximum length of a DBCLOB, expressed in the units that are either implicitly or explicitly specified.

If CODEUNITS16 or CODEUNITS32 is specified, see Determining the length attribute of the final result for information about how to calculate the length attribute of the result string. If CODEUNITS32 is specified, the value of integer must be between 1 and the maximum length of a DBCLOB divided by two (to allow for an intermediate result string that is long enough to evaluate the function).

If integer is not specified and character-expression is an empty string constant, the length attribute of the result is 1, and the result is an empty string. Otherwise, the length attribute of the result is the same as the length attribute of character-expression.

CODEUNITS16 or CODEUNITS32

Specifies the unit that is used to express integer. If CODEUNITS16 or CODEUNITS32 is specified, the input is EBCDIC, and there is no system CCSID for EBCDIC GRAPHIC data, an error occurs.

CODEUNITS16: Specifies that integer is expressed in terms of 16-bit UTF-16 code units.
CODEUNITS32: Specifies that integer is expressed in terms of 32-bit UTF-32 code units.

For more information about CODEUNITS16 and CODEUNITS32, see String unit specifications.

The actual length of the result is the minimum of the length attribute of the result and the actual length of character-expression. If the length of character-expression, as measured in single-byte characters, is greater than the specified length of the result, as measured in double-byte characters, the result is truncated. Unless all the truncated characters are blanks appropriate for character-expression, a warning is returned.

The CCSID of the result is the graphic CCSID that corresponds to the character CCSID of character-expression.

For EBCDIC input data, each character of character-expression determines a character of the result. The argument might need to be converted to the native form of mixed data before the result is derived. Let M denote the system CCSID for mixed data. The argument is not converted if any of the following conditions is true:

The argument is mixed data and its CCSID is M.
The argument is SBCS data and its CCSID is the same as the system CCSID for SBCS data. In this case, the operation proceeds as if the CCSID of the argument is M.

Otherwise, the argument is a new string S derived by converting the characters to the coded character set identified by M. If there is no system CCSID for mixed data, conversion is to the coded character set that the system CCSID for SBCS data identifies.

The result is derived from S using the following steps:

Each shift character (X'0E' or X'0F') is removed.
Each double-byte character remains as is.
Each single-byte character is replaced by a double-byte character.

The replacement for a single-byte character is the equivalent DBCS character if an equivalent exists. Otherwise, the replacement is X'FEFE'. The existence of an equivalent character depends on M. If there is no system CCSID for mixed data, the DBCS equivalent of X'xx' for EBCDIC is X'42xx', except for X'40', whose DBCS equivalent is X'4040'.

For Unicode input data, each character of character-expression determines a character of the result. The argument might need to be converted to the native form of mixed data before the result is derived. Let M denote the system CCSID for mixed data. The argument is not converted if any of the following conditions is true:

The argument is mixed data, and its CCSID is M.
The argument is SBCS data, and its CCSID is the same as the system CCSID for SBCS data. In this case, the operation proceeds as if the CCSID of the argument is M.

Otherwise, the argument is a new string S derived by converting the characters to the coded character set identified by M.

The result is derived from S using the following steps:

Each non-supplementary character is replaced by a Unicode double-byte character (a UTF-16 code point). A non-supplementary character in UTF-8 is between 1 and 3 bytes.
Each supplementary character is replaced by a pair of Unicode double-byte characters (a pair of UTF-16 code points).

The replacement for a single-byte character is the Unicode equivalent character if an equivalent exists. Otherwise, the replacement is X'FFFD'.

Graphic to DBCLOB

graphic-expression

An expression that returns a value that is an EBCDIC-encoded or Unicode-encoded graphic string.

integer

The length attribute for the resulting varying-length graphic string. The value must be an integer between 1 and the maximum length of a DBCLOB, expressed in the units that are either implicitly or explicitly specified.

If CODEUNITS16 or CODEUNITS32 is specified, see Determining the length attribute of the final result for information about how to calculate the length attribute of the result string.

If integer is not specified and graphic-expression is an empty string constant, the length attribute of the result is 1, and the result is an empty string. Otherwise, the length attribute of the result is the same as the length attribute of graphic-expression.

CODEUNITS16 or CODEUNITS32

Specifies the unit that is used to express integer. If CODEUNITS16 or CODEUNITS32 is specified, the input is EBCDIC, and there is no system CCSID for EBCDIC GRAPHIC data, an error occurs.

CODEUNITS16: Specifies that integer is expressed in terms of 16-bit UTF-16 code units.
CODEUNITS32: Specifies that integer is expressed in terms of 32-bit UTF-32 code units.

For more information about CODEUNITS16 and CODEUNITS32, see String unit specifications.

The actual length of the result is the minimum of the length attribute of the result and the actual length of graphic-expression. If the length of graphic-expression is greater than the length attribute of the result, truncation is performed. Unless all of the truncated characters are double-byte blanks, a warning is returned.

The CCSID of the result is the same as the CCSID of graphic-expression.

The result of the function is a DBCLOB.

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

The length attribute and actual length of the result are measured in double-byte characters because the result is a graphic string.

Example 1: Assume that the application encoding scheme is Unicode. The following statement returns a graphic (UTF-16) host variable.

   VALUES DBCLOB('123')
     INTO :GHV1;

Example 2: FIRSTNAME is a VARCHAR(12) column (Unicode UTF-8 data) in table T1. One of its values is the 6-character string 'Jürgen'. When FIRSTNAME has this value:

   Function ...                           Returns ...
   DBCLOB(FIRSTNAME,3,CODEUNITS32)        'Jür'  -- x'004A00FC0072'
   DBCLOB(FIRSTNAME,3,CODEUNITS16)        'Jür'  -- x'004A00FC0072'