SUBSTRING スカラー関数

SUBSTRING 関数は、ストリングのサブストリングを戻します。

キャラクター：

図表：

2値：

スキーマは SYSIBM です。

文字

文字表現

結果を取り出すストリングを指定する式。ストリングは、組み込みの文字ストリングでなければなりません。

引数を数値データ・タイプにすることもできます。数値引数は、暗黙的に VARCHAR データ・タイプにキャストされます。

この関数の結果は文字ストリングです。

character-expression のサブストリングは、character-expression の 0 個以上の連続した単位です。 CODEUNITS32 を指定すると、単位は Unicode UTF-32 文字です。 CODEUNITS16 を指定すると、単位は Unicode UTF-16 文字です。 OCTETS を指定すると、単位はバイトです。

開始

結果の最初のストリング単位となる、character-expression 内の位置を指定する式。 start は指定したストリング単位で表され、整数値を戻す必要があります。

引数は、別の数値、文字ストリング、またはグラフィック・ストリングのデータ・タイプにすることもできます。入力は、暗黙的に DECFLOAT(34) の数値にキャストされ、その後 INTEGER 値に割り当てられます。

start の値は、正数、負数、またはゼロのいずれにもなります。 1 の値は、結果の最初のストリング単位は character-expression の最初のストリング単位であることを示します。

LENGTH

結果のサブストリングの最大長を指定する式。

文字式が固定長ストリングの場合、長さを省略すると CHARACTER_LENGTH(character-expression) - start + 1が暗黙的に指定されます。これは、開始から文字式の最後の位置までのストリング単位 (CODEUNITS16、 CODEUNITS32、または OCTETS) の数です。

文字式が可変長ストリングの場合、長さを省略すると、ゼロまたは CHARACTER_LENGTH(character-expression) - start + 1のいずれか大きい方の暗黙指定になります。結果となる長さがゼロの場合、その結果は空ストリングです。

指定する場合、length は整数データ・タイプの値を返す式であることが必要です。

値は、0 以上でなければなりません。 N より大きい値を指定した場合 ( N は character-expression - start+ 1の長さ属性)、結果のサブストリングの長さとして N が使用されます。値は明示的に指定する単位で表されます。

実際の長さと結果の厳密な説明については、こちらをご覧ください。

CODEUNITS16、CODEUNITS32、または OCTETS

start と length を表すのに使用するストリングの単位を指定します。 character-expression がビット・データとして定義された文字ストリングの場合は、CODEUNITS16 および CODEUNITS32 は指定できません。

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

CODEUNITS16、 CODEUNITS32、OCTETSの詳細については、「文字列単位仕様」を参照してください。

Graphic

グラフィック表現

結果を取り出すストリングを指定する式。ストリングは、組み込みのグラフィック・ストリングでなければなりません。この関数の結果はグラフィック・ストリングです。式に含まれる部分サロゲート文字は、ブランクに置き換えられます。

graphic-expression のサブストリングは、graphic-expression の 0 個以上の連続した単位です。 CODEUNITS32 を指定すると、単位は Unicode UTF-32 文字です。 CODEUNITS16 を指定すると、単位は Unicode UTF-16 文字です。

開始

結果の最初のストリング単位となる、graphic-expression 内の位置を指定する式。 start は指定したストリング単位で表され、整数値を戻す必要があります。 start の値は、正数、負数、またはゼロのいずれにもなります。 1 の値は、結果の最初のストリング単位は graphic-expression の最初のストリング単位であることを示します。

引数は、別の数値、文字ストリング、またはグラフィック・ストリングのデータ・タイプにすることもできます。ストリング入力は、暗黙的に DECFLOAT(34) の数値にキャストされ、その後 INTEGER 値に割り当てられます。

LENGTH

結果のサブストリングの最大長を指定する式。

グラフィック式が固定長ストリングの場合、長さを省略すると CHARACTER_LENGTH(graphic-expression) - start +1が暗黙的に指定されます。これは、グラフィック式の開始位置から最後の位置までの単位数 (CODEUNITS16、 CODEUNITS32) を明示的または暗黙的に指定したものです。グラフィック式が可変長ストリングの場合、長さを省略すると、ゼロまたは CHARACTER_LENGTH(graphic-expression) -start +1の暗黙指定になります。これは、明示的または暗黙的に指定された単位の数 (CODEUNITS16、 CODEUNITS32) のいずれか大きい方です。結果となる長さがゼロの場合、その結果は空ストリングです。

指定する場合、length は整数データ・タイプの値を返す式であることが必要です。

値は、0 以上でなければなりません。 N より大きい値を指定した場合 ( N は graphic-expression - start+ 1の長さ属性)、結果のサブストリングの長さとして N が使用されます。値は明示的に指定する単位で表されます。

実際の長さと結果の厳密な説明については、こちらをご覧ください。

CODEUNITS16 または CODEUNITS32

start と length を表すのに使用するストリングの単位を指定します。

CODEUNITS16: start と length が、16 ビットの UTF-16 コード単位の形で表現されることを指定します。
CODEUNITS32: start と length が、32 ビットの UTF-32 コード単位の形で表現されることを指定します。

CODEUNITS16 と CODEUNITS32 の詳細については、文字列単位仕様を参照してください。

バイナリー

二項表現

結果を取り出すストリングを指定する式。ストリングは、組み込みのバイナリー・ストリングでなければなりません。この関数の結果は、バイナリー・ストリングです。

binary-expression のサブストリングは、binary-expression の 0 個以上の連続した単位です。

開始

結果の最初のバイトとなる binary-expression 内の位置を指定する式。これは整数値でなければなりません。 start は負またはゼロでも構いません。 (可変長ストリングの長さ属性は、その最大長です。) 値 1 は、サブストリングの最初のバイトが binary-expression のバイト単位であることを示します。

LENGTH

結果のサブストリングの長さを指定する式。

binary-expression が固定長文字列の場合、 length の省略は、 LENGTH(binary-expression) - start +1 を binary-expression の先頭位置から最後の位置まで暗黙的に指定することを意味します。 binary-expression が可変長の文字列である場合、長さを省略すると、ゼロまたは CHARACTER_LENGTH(binary-expression) -start +1 のいずれか大きい方を暗黙的に指定することになります。結果となる長さがゼロの場合、その結果は空ストリングです。

指定する場合、length は整数データ・タイプの値であることが必要です。値は 0 以上である必要があります。n より大きい値が指定された場合 (n は binary-expression - start+ 1 の長さ属性)、結果のサブ文字列の長さとして n が使用されます。

実際の長さと結果の厳密な説明については、こちらをご覧ください。

実際の長さと結果に関する正確な記述

この説明では、文字という用語は「ストリング単位数 (入力がバイナリーの場合は「バイト数」) で指定された単位」を意味します。

C は最初の引数の値、LC は C の文字の長さ、S は start の値とします。

length を指定する場合、L は length の値、E は S+L とします。それ以外の場合、E は、LC + 1 と S のうちの大きい方の値とします。
C、S、または L のいずれかが NULL 値の場合、この関数の結果は NULL 値です。
E が S よりも小さい場合、例外条件 (データ例外 — サブストリング・エラー) が発生します。
それ以外の場合は、次のとおりです。
- S が LC より大きい場合、または E が 1 より小さい場合、この関数の結果はゼロ長のストリングとなります。
- それ以外の場合は、次のとおりです。
  - S1 は、S と 1 のうちの大きい方の値とします。 E1 は、E と LC+1 のうちの小さい方の値とします。 L1 は E1–S1とします。
  - この関数の結果は文字ストリングであり、そこには文字数 S1 から始まる、C の L1 文字数 (その順序は各文字が C の中に現れる順序と同じ) が含まれます。

結果のデータ・タイプは、次の表に示すように、最初の引数のデータ・タイプによって決まります。

表 1. SUBSTRING の結果のデータ・タイプ
最初の引数のデータ・タイプ	結果のデータ・タイプ
CHAR または VARCHAR	VARCHAR
CLOB	CLOB character-expression が混合データである場合、結果は混合データになります。それ以外の場合、その結果は SBCS データとなります。
GRAPHIC または VARGRAPHIC	VARGRAPHIC
DBCLOB	DBCLOB
BINARY または VARBINARY	VARBINARY
BLOB	BLOB

結果の長さ属性は、最初の引数の長さ属性と同じです。 CODEUNITS16 または CODEUNITS32 が指定されている場合、結果文字列の長さ属性を計算する方法については、「最終結果の長さ属性の決定」を参照してください。

結果は NULL 値になることがあります。いずれかの引数が NULL 値である場合、結果は NULL 値になります。

最初の引数が文字データまたはグラフィック・データである場合、結果の CCSID は最初の引数の CCSID と同じです。

例 1: C1 は、表 T1の VARCHAR (12) の列です。その値の 1 つは、ストリング「ABCDEFG」です。 C1 の値が「ABCDEFG」の場合、

   Function:                        Returns:
   -------------------------------------------------------
   SUBSTRING(C1,-2,2,OCTETS)                 -- a zero-length string
   SUBSTRING(C1,-2,4,OCTETS)        'A'
   SUBSTRING(C1,-2,OCTETS)          'ABCDEFG'
   SUBSTRING(C1,0,1,OCTETS)                  -- a zero-length string

例 2: FIRSTNAME は表 T1 内の VARCHAR(12) の列です。その値の 1 つが 6 文字ストリング「Jürgen」です。 FIRSTNAME の値が「Jürgen」の場合、

   Function:                                   Returns:
   --------------------------------------------------------------
   SUBSTRING(FIRSTNAME,1,2,CODEUNITS32)       'Jü'  -- x'4AC3BC'
   SUBSTRING(FIRSTNAME,1,2,CODEUNITS16)       'Jü'  -- x'4AC3BC'
   SUBSTRING(FIRSTNAME,1,2,OCTETS)            'J '  -- x'4A20' (a truncated string)
   SUBSTRING(FIRSTNAME,8,CODEUNITS16)               -- a zero-length string
   SUBSTRING(FIRSTNAME,8,4,OCTETS)                  -- a zero-length string