SUBSTR4 スカラー関数

SUBSTR4 関数は、ストリングのサブストリングを戻します。 結果のサブストリングは、ストリング内の指定の位置から開始され、指定の長さまたはデフォルトの長さまで続きます。 開始引数と長さ引数は、32 ビットの UTF-32 ストリング単位で表されます (CODEUNITS32)。
構文図を読む構文図をスキップするSUBSTR4(string, start,length)

スキーマは SYSIBM です。

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

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

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

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

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

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

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

length のデフォルト値は、start で指定された位置から string の最後のストリング単位までの CODEUNITS32 の数です。

string が CHAR または VARCHAR データ・タイプの場合、関数の結果は VARCHAR データ・タイプになります。string が CLOB の場合、この関数の結果も CLOB です。 string が GRAPHIC または VARGRAPHIC データ・タイプの場合、関数の結果は VARGRAPHIC データ・タイプになります。string が DBCLOB の場合、この関数の結果も DBCLOB になります。 最初の引数がホスト変数の場合には、結果のコード・ページはセクション・コード・ページになります。 それ以外の場合には、最初の引数のコード・ページです。
結果の長さ属性は、最初の引数の長さ属性と同じになります。 ただし、開始引数または長さ引数が定数として指定される場合は例外です。 定数を指定すると、結果の長さ属性は以下の表に記載されている適用可能な最初の行に基づきます。結果のストリング単位は、最初の引数のストリング単位と同じになります。
表 1. 引数に定数が含まれる場合の SUBSTR4 結果の長さ属性
ストリング引数 開始引数 1 長さ引数 結果の長さ属性 2
長さ属性 A を持つ文字タイプ 任意の有効な引数 定数値 L<=0 0
長さ属性 A を持つ文字タイプ 定数値 S および |(S)|>A 指定しない、または任意の有効な引数 0
長さ属性 A を持つ文字タイプ 定数以外 定数値 L>0 string のストリング単位が OCTETS である場合は MIN(A, L×4)
string のストリング単位が CODEUNITS32 である場合は MIN(A, L)
長さ属性 A を持つ文字タイプ 定数値 S>0 指定しない、または定数以外 A-S+1
長さ属性 A を持つ文字タイプ 定数値 S<0 指定しない、または定数以外 string のストリング単位が OCTETS である場合は MIN(A, |(S)×4|)
string のストリング単位が CODEUNITS32 である場合は MIN(A, |S|)
長さ属性 A を持つ文字タイプ 定数値 S>0 定数値 L>0 string のストリング単位が OCTETS である場合は MIN(A-S+1, L×4)
string のストリング単位が CODEUNITS32 である場合は MIN(A-S+1, L)
長さ属性 A を持つ文字タイプ 定数値 S<0 定数値 L>0 string のストリング単位が OCTETS である場合は MIN(A,|(S)×4|, L×4)
string のストリング単位が CODEUNITS32 である場合は MIN(A, |S|, L)
長さ属性 A を持つグラフィック・タイプ 任意の有効な引数 定数値 L<=0 0
長さ属性 A を持つグラフィック・タイプ 定数値 S および |(S)|>A 指定しない、または任意の有効な引数 0
長さ属性 A を持つグラフィック・タイプ 定数以外 定数値 L>0 string のストリング単位が 2 バイトまたは CODEUNITS16 である場合は MIN(A, L*2)
string のストリング単位が CODEUNITS32 である場合は MIN(A, L)
長さ属性 A を持つグラフィック・タイプ 定数値 S>0 指定しない、または定数以外 A-S+1
長さ属性 A を持つグラフィック・タイプ 定数値 S<0 指定しない、または定数以外 string のストリング単位が 2 バイトまたは CODEUNITS16 である場合は MIN(A, |(S) * 2|)
string のストリング単位が CODEUNITS32 である場合は MIN(A, |S|)
長さ属性 A を持つグラフィック・タイプ 定数値 S>0 定数値 L>0 string のストリング単位が 2 バイトまたは CODEUNITS16 である場合は MIN(A-S+1, L*2)
string のストリング単位が CODEUNITS32 である場合は MIN(A-S+1, L)
長さ属性 A を持つグラフィック・タイプ 定数値 S<0 定数値 L>0 string のストリング単位が 2 バイトまたは CODEUNITS16 である場合は MIN(A, |(S)*2|, L*2)
string のストリング単位が CODEUNITS32 である場合は MIN(A, |S|, L)
注:

1 開始引数に値 0 を指定する場合、この表を参照する際には S に値 1 を使用してください。

2 一部の文字結果タイプの結果の長さ属性には、係数 4 が乗算される定数が含まれています。この乗数は、ストリング単位が OCTETS の文字データ・タイプの長さ属性で使用するため、32 ビット UTF-32 ストリング単位のカウントからバイト単位のカウントに切り替えるために 4 を乗算することで生じる最悪の場合の拡張をカバーします。
一部のグラフィック結果タイプの結果の長さ属性には、係数 2 が乗算される定数が含まれています。この乗数は、UTF-32 の 4 バイト文字をグラフィック・ストリングで最大 2 バイト文字で表される可能性があるため、2 を乗算することで生じる最悪の場合の拡張をカバーします。
SUBSTR4 関数の引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。引数のいずれかが NULL の場合、その結果は NULL 値です。

注

  • string に結合文字が含まれている場合、結果には、開始と長さの値に応じて、結合文字のない基本文字または基本文字のない結合文字が含まれる可能性があります。
  • SUBSTR4 は SUBSTR 関数に似ていますが、以下の例外があります。
    • SUBSTR4 は、処理をストリングの末尾から開始することを示す負の開始値をサポートしています。
    • SUBSTR4 は、計算結果の長さよりも大きい length 値をサポートしています。 その場合、短い方のストリングが戻され、エラーは戻されません。
    • SUBSTR4 は、入力データ・タイプが CHAR の場合にはデータ・タイプ VARCHAR を結果として戻します。入力タイプが GRAPHIC の場合には、VARGRAPHIC が結果として戻されるデータ・タイプです。
    • SUBSTR4 の結果の長さ属性は、最初の引数の長さ属性と同じになるか、あるいは、開始属性または長さ属性に基づいて導出されます (どちらかが定数の場合)。
    • SUBSTR4 は、最初の引数の長さ属性と同じ長さ属性を結果として戻します。 ただし、開始引数または長さ引数が定数として指定されている場合は例外です。定数を指定すると、結果の長さ属性は開始属性または長さ属性に基づいて導出されます (上の表を参照)。