SUBSTR2 スカラー関数

SUBSTR2 関数は、ストリングのサブストリングを戻します。結果のサブストリングは、ストリング内の指定の位置から開始され、指定の長さまたはデフォルトの長さまで続きます。開始引数と長さ引数は、16 ビットの UTF-16 ストリング単位で表されます (CODEUNITS16)。

スキーマは SYSIBM です。

string

結果のサブストリングを取り出すストリングを指定する式。式は、組み込み文字ストリング、グラフィック・ストリング、数値、日時のいずれかのデータ・タイプの値を戻す必要があります。文字ストリングに FOR BIT DATA 属性は設定できません (SQLSTATE 428GC)。値がストリング・データ・タイプでない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。string のサブストリングは、string 内のゼロ個以上の連続したバイトです。

start

結果のサブストリングを開始する string 内の開始位置を 16 ビットの UTF-16 ストリング単位で指定する式。式は、組み込みデータ・タイプである数値、CHAR、VARCHAR、GRAPHIC、VARGRAPHIC のいずれかの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。

start が正の場合、開始位置はストリングの先頭から計算されます。 start が 16 ビットの UTF-16 ストリング単位の string の長さよりも大きい場合には、長さゼロのストリングが戻されます。

start が負の場合、開始位置はストリングの末尾から逆方向にカウントして計算されます。 start の絶対値が 16 ビットの UTF-16 ストリング単位の string の長さより大きい場合、長さゼロのストリングが戻されます。

start が 0 の場合、開始位置として 1 が使用されます。

length

結果のサブストリングの長さを 16 ビットの UTF-16 ストリング単位で指定する式。 length を指定する場合、式は組み込む数値、CHAR、VARCHAR、GRAPHIC、VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。

length の値がストリングの開始位置から末尾までの 16 ビットの UTF-16 ストリング単位の数よりも大きい場合、結果のサブストリングの長さは、16 ビットの UTF-16 ストリング単位の最初の引数の長さから開始位置を引いて 1 を加えた長さになります。

length の値がゼロ以下の場合、結果は長さゼロのストリングになります。

length のデフォルト値は、start で指定された位置から string の最後のバイトまでの CODEUNITS16 の数です。

string が CHAR または VARCHAR データ・タイプの場合、関数の結果は VARCHAR データ・タイプになります。string が CLOB の場合、この関数の結果も CLOB です。 string が GRAPHIC または VARGRAPHIC データ・タイプの場合、関数の結果は VARGRAPHIC データ・タイプになります。string が DBCLOB の場合、この関数の結果も DBCLOB になります。最初の引数がホスト変数の場合には、結果のコード・ページはセクション・コード・ページになります。それ以外の場合には、最初の引数のコード・ページです。

結果の長さ属性は、最初の引数の長さ属性と同じになります。ただし、開始引数または長さ引数が定数として指定される場合は例外です。定数を指定すると、結果の長さ属性は以下の表に記載されている適用可能な最初の行に基づきます。

表 1. 引数に定数が含まれる場合の SUBSTR2 結果の長さ属性
ストリング引数	開始引数 ¹	長さ引数	結果の長さ属性 ²
長さ属性 A を持つ文字タイプ	任意の有効な引数	定数値 L<=0	0
長さ属性 A を持つ文字タイプ	定数値 S および \|(S)\|>A	指定しない、または任意の有効な引数	0
長さ属性 A を持つ文字タイプ	定数以外	定数値 L>0	MIN(A, L×4)
長さ属性 A を持つ文字タイプ	定数値 S>0	指定しない、または定数以外	A-S+1
長さ属性 A を持つ文字タイプ	定数値 S<0	指定しない、または定数以外	MIN(A, \|(S)×4\|)
長さ属性 A を持つ文字タイプ	定数値 S>0	定数値 L>0	MIN(A-S+1, L×4)
長さ属性 A を持つ文字タイプ	定数値 S<0	定数値 L>0	MIN(A,\|(S)×4\|, L×4)
長さ属性 A を持つグラフィック・タイプ	任意の有効な引数	定数値 L<=0	0
長さ属性 A を持つグラフィック・タイプ	定数値 S および \|(S)\|>A	指定しない、または任意の有効な引数	0
長さ属性 A を持つグラフィック・タイプ	定数以外	定数値 L>0	MIN(A, L)
長さ属性 A を持つグラフィック・タイプ	定数値 S>0	指定しない、または定数以外	A-S+1
長さ属性 A を持つグラフィック・タイプ	定数値 S<0	指定しない、または定数以外	\|(S)\|
長さ属性 A を持つグラフィック・タイプ	定数値 S>0	定数値 L>0	MIN(A-S+1, L)
長さ属性 A を持つグラフィック・タイプ	定数値 S<0	定数値 L>0	MIN(\|(S)\|, L)\|
注: ¹ 開始引数に値 0 を指定する場合、この表を参照する際には S に値 1 を使用してください。 ² 一部の文字タイプの結果の長さ属性には、係数 4 で乗算する定数が含まれています。この乗数は、以下の要因によって生じる最悪の場合の拡張をカバーしています。文字データ・タイプの長さ属性で使用するため、16 ビットの UTF-16 ストリング単位のカウントからバイト単位のカウントに切り替えるために 2 で乗算します。 UTF-16 の 2 バイト文字は文字ストリングで最大 4 バイトで表現される可能性があるので、もう一度 2 で乗算します。

SUBSTR2 関数の引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。引数のいずれかが NULL の場合、その結果は NULL 値です。

注

動的 SQL では、string、start、および length を、パラメーター・マーカーで表すことができます。ストリングに非型付きパラメーター・マーカーを使用すると、オペランドは NULL 可能になり、データベースがグラフィック・データ・タイプをサポートしている場合にはオペランドのデータ・タイプは VARGRAPHIC(16336) になります。その他の場合には、データ・タイプは VARCHAR(32672) となります。
string が 1 バイトとマルチバイトの混合文字ストリングの場合、結果には、start と length の値によってはマルチバイト文字のフラグメントが入る可能性があります。例えば、結果がマルチバイト文字の 3 番目のバイトから始まったり、マルチバイト文字の最初のバイトで終わったりする可能性があります。 SUBSTR2 関数はこうした部分的な文字を検出し、不完全な文字の各バイトを単一のブランク文字に置き換えます。
SUBSTR2 は SUBSTR 関数に似ていますが、以下の例外があります。
- SUBSTR2 は、処理をストリングの末尾から開始することを示す負の開始値をサポートしています。
- SUBSTR2 は、計算結果の長さよりも大きい length 値をサポートしています。その場合、短い方のストリングが戻され、エラーは戻されません。
- SUBSTR2 は、入力データ・タイプが CHAR の場合にはデータ・タイプ VARCHAR を結果として戻します。入力タイプが GRAPHIC の場合には、VARGRAPHIC が結果として戻されるデータ・タイプです。
- SUBSTR2 の結果の長さ属性は、最初の引数の長さ属性と同じになるか、あるいは、開始属性または長さ属性に基づいて導出されます (どちらかが定数の場合)。
- SUSTR2 は、最初の引数の長さ属性と同じ長さ属性を結果として戻します。ただし、開始引数または長さ引数が定数として指定されている場合は例外です。定数を指定すると、結果の長さ属性は開始属性または長さ属性に基づいて導出されます (上の表を参照)。

例

例 1: 以下のホスト変数があるとします。
- NAME (VARGRAPHIC(50) に値「Roméo Jürgen」が入っている
- SURNAME POS (INTEGER) に値 7 が入っている
```
SUBSTR2(:NAME, :SURNAME_POS)
```
値 Jürgen が戻されます。
```
SUBSTR2(:NAME, :SURNAME_POS,2)
```
値 Jü が戻されます。
例 2: PROJECT 表から、'ING' で終わるすべての行を選択します。
```
SELECT * FROM PROJECT
   WHERE SUBSTR2(PROJNAME,-3) = 'ING'
```