SUBSTRING スカラー関数

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

スキーマは SYSIBM です。

expression結果を取り出すストリングを指定する式。式は、組み込みの文字ストリング、数値、ブール値、または日時値を返す必要があります。文字ストリングでない値は、関数の評価の前に VARCHAR に暗黙的にキャストされます。

入力式のサブストリングは、入力式における、連続したゼロ個以上のストリング単位で構成されます。

startサブストリングを計算する起点となる、入力式の先頭からの相対位置を指定する式。以下に例を示します。

位置 1 は、入力式における 1 番目のストリング単位です。ステートメント SUBSTRING('abc',1,2) は 'ab'を返します。
位置 2 は、位置 1 から右方に 1 つ目の位置です。ステートメント SUBSTRING('abc',2,2) は 'bc'を返します。
位置 0 は、位置 1 から左方に 1 つ目の位置です。ステートメント SUBSTRING('abc',0,2) は 'a'を返します。
位置 -1 は、位置 1 から左方に 2 つ目の位置です。ステートメント SUBSTRING('abc',-1,2) は、長さがゼロのストリングを返します。

この式は、組み込みの数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC の値を返す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。

開始値は、正、負、またはゼロにすることができます。 OCTETS が指定され、入力式に GRAPHIC データが含まれる場合、start の値は奇数でなければなりません (SQLSTATE 428GC)。

length結果の長さを指定する式。この式は、組み込みの数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC の値を返す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。

入力式に応じて以下のようになります。

固定長ストリングの場合、デフォルトの長さは CHARACTER_LENGTH(expression USING string-unit) - start + 1 です。これは、入力式の開始位置から最終位置までの、ストリング単位 (CODEUNITS16、CODEUNITS32、または OCTETS) の数です。
可変長ストリングの場合、デフォルトの長さはゼロまたは CHARACTER_LENGTH(expression USING string-unit) - start + 1 のいずれか大きい方です。

指定した長さがゼロの場合、結果は空ストリングです。

値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。値はゼロ以上でなければなりません。 n より大きい値が指定される場合、n が結果のサブストリングの長さとして使用されます。ここで、n は (expression の長さ属性) - start + 1 です。値は、明示的に指定されたストリング単位で表現されます。 OCTETS が指定され、入力式に GRAPHIC データが含まれる場合、長さは偶数でなければなりません (SQLSTATE 428GC)。

CODEUNITS16、CODEUNITS32、または OCTETS

start および length のストリング単位を指定します。 CODEUNITS16 は、 start および length を 16 ビットの UTF-16 コード単位で表すことを指定します。 CODEUNITS32 は、 start および length が 32 ビットの UTF-32 コード単位で表現されることを指定します。 OCTETS は、start および length をバイト単位で表すことを指定します。

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

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

CODEUNITS16、CODEUNITS32、および OCTETS について詳しくは、文字ストリングの組み込み関数のストリング単位を参照してください。

SUBSTRING 関数が OCTETS を使用して呼び出され、source-string がコード・ポイントごとに複数のバイトを必要とするコード・ページでエンコードされる場合 (混合または MBCS)、SUBSTRING 操作は、マルチバイト・コード・ポイントを分割し、結果のサブストリングは部分的なコード・ポイントで開始または終了する場合があります。これが発生する場合、関数は結果のバイト長を変更しない仕方で、先頭または末尾の部分的コード・ポイントのバイトをブランクで置き換えます。 (『例』セクションで関連する例を参照)。

結果

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

表 1. SUBSTRING の結果のデータ・タイプ
最初の引数のデータ・タイプ	結果のデータ・タイプ
CHAR または VARCHAR	VARCHAR
CLOB	CLOB
GRAPHIC または VARGRAPHIC	VARGRAPHIC
DBCLOB	DBCLOB
BINARY または VARBINARY	VARBINARY
BLOB	BLOB

結果の長さ属性は、入力式の長さ属性と同じになります。関数のいずれかの引数が NULL 値の可能性がある場合、結果も NULL 値になる可能性があります。いずれかの引数が NULL 値の場合、結果は NULL 値になります。結果にいずれかの文字が埋め込まれることはありません。入力式の実際の長さが 0 である場合、結果の実際の長さも 0 になります。

注

結果の長さ属性は、入力式の長さ属性と同じになります。この動作は SUBSTR 関数の動作とは異なります。その場合の長さ属性は、関数の start および length 引数から導出されます。

例

例 1: FIRSTNAME は、表 T1 の VARCHAR(12) 列です。その値の 1 つは、6 文字のストリング 'Jürgen' です。 FIRSTNAME が以下の値を持つ場合:

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
SUBSTRING(FIRSTNAME,0,2,CODEUNITS32)  'J' -- x'4AC3BC'

例 2: 以下では、ストリングの長さの単位が OCTETS の場合、SUBSTRING が先頭または末尾の部分的マルチバイト・コード・ポイントのバイトをブランクで置き換える例を示しています。 UTF8_VAR に Unicode ストリング '&N~AB' の UTF-8 表記が含まれていると想定します。ここで '&' は音楽のト音記号、'~' は結合チルド記号文字です。
```
   SUBSTRING(UTF8_VAR, 2, 5, OCTETS)
```
3 つのブランク・バイトが 'N' に先行し、1 つのブランク・バイトが 'N' に続きます。