CHARACTER_LENGTH スカラー関数

CHARACTER_LENGTH 関数は、指定されたストリング単位で式の長さを返します。

スキーマは SYSIBM です。

expression

組み込みの文字ストリング、バイナリー・ストリング、または GRAPHIC ストリング、あるいはブール値を返す式。

CODEUNITS16、CODEUNITS32、または OCTETS

結果のストリング単位を指定します。

CODEUNITS16 は、結果が 16 ビット UTF-16 コード単位で表現されることを指定します。
CODEUNITS32 は、結果が 32 ビット UTF-32 コード単位で表現されることを指定します。
OCTETS は、結果がバイト単位で表現されることを指定します。

ストリング単位が CODEUNITS16 または CODEUNITS32 と指定され、expression がバイナリー・ストリングまたは FOR BIT DATA ストリングである場合は、エラーが戻されます (SQLSTATE 428GC)。

ストリング単位引数が指定されておらず、expression が FOR BIT DATA 以外の文字ストリングであるか、グラフィック・ストリングである場合、デフォルトは CODEUNITS32 です。それ以外の場合、デフォルトは OCTETS です。

詳しくは、『文字ストリング』の『組み込み関数のストリング単位』を参照してください。

結果

この関数の結果は長精度整数 (large integer) です。引数が NULL になる可能性がある場合、結果も NULL になる可能性があります。引数が NULL であれば、結果は NULL 値です。

文字および GRAPHIC ストリングの長さには、末尾ブランクが含まれます。可変長ストリングの長さは、最大長ではなく実際の長さです。

例

NAME が VARCHAR(128) 列であり、Unicode UTF-8 でエンコードされ、値 'Jürgen' を含んでいるとします。以下の 2 つの照会は、値 6 を戻します。

   SELECT CHARACTER_LENGTH(NAME, CODEUNITS32)
   FROM T1 WHERE NAME = 'Jürgen'

   SELECT CHARACTER_LENGTH(NAME, CODEUNITS16) 
   FROM T1 WHERE NAME = 'Jürgen'

以下の 2 つの照会は、値 7 を戻します。

   SELECT CHARACTER_LENGTH(NAME, OCTETS)
   FROM T1 WHERE NAME = 'Jürgen'

   SELECT LENGTH(NAME)
   FROM T1 WHERE NAME = 'Jürgen'

以下の例は、Unicode ストリング '&N~AB' に対応します。 '&' は音楽のト音記号、'~' は結合チルド文字です。以下の例では、このストリングを異なる Unicode エンコード方式で示しています。

	'&'	'N'	'~'	'A'	'B'
UTF-8	X'F09D849E'	X'4E'	X'CC83'	X'41'	X'42'
UTF-16BE	X'D834DD1E'	X'004E'	X'0303'	X'0041'	X'0042'
UTF-32BE	X'0001D11E'	X'0000004E'	X'00000303'	X'00000041'	X'00000042'

変数 UTF8_VAR に、ストリングの UTF-8 表現が格納されると想定します。

   SELECT CHARACTER_LENGTH(UTF8_VAR, CODEUNITS16),
     CHARACTER_LENGTH(UTF8_VAR, CODEUNITS32),
     CHARACTER_LENGTH(UTF8_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1

それぞれ、値 6、5、9 を戻します。

変数 UTF16_VAR に、ストリングの UTF-16BE 表現が格納されると想定します。

   SELECT CHARACTER_LENGTH(UTF16_VAR, CODEUNITS16),
      CHARACTER_LENGTH(UTF16_VAR, CODEUNITS32),
      CHARACTER_LENGTH(UTF16_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1

それぞれ、値 6、5、12 を戻します。