SUBSTR スカラー関数

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

スキーマは SYSIBM です。

string

サブストリングの派生元ストリングを指定する入力式。この式は、組み込みの文字ストリング、数値、ブール値、日時値のいずれかの値を返す必要があります。文字ストリングでない値は、関数の評価の前に VARCHAR に暗黙的にキャストされます。この式のサブストリングは、この式の任意の数 (ゼロ以上) の連続ストリング単位で構成されます。

start

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

位置 1 は、入力式における 1 番目のストリング単位です。ステートメント SUBSTR('abcd',1,2) は 'ab' を返します。
位置 2 は、位置 1 から右に 1 つ目の位置です。ステートメント SUBSTR('abcd',2,2) は 'bc' を返します。

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

length

結果の長さを指定する式。指定する場合、式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。整数の値は 0 から n の範囲でなければなりません。ここで、n は、 (ストリング単位での string の長さ属性) - start + 1 です (その範囲外の場合は SQLSTATE 22011)。

length を明示的に指定した場合、string の右側に必要な数のブランク文字 (文字ストリングの場合は 1 バイト、GRAPHIC ストリングの場合は 2 バイト) が、またバイナリー・ストリングの場合には必要な数の 16 進ゼロ文字がそれぞれ効率的に付加されて、指定したサブストリングが存在するようにされます。デフォルトの長さは、start で指定したストリング単位から string の最後のストリング単位までのストリング単位数です。ただし、string が可変長ストリングで、その長さが start 未満の場合、デフォルト値はゼロになり、結果は空ストリングになります。これは、アプリケーション・コード・ページではなく、データベース・コード・ページのコンテキスト内にあるストリング単位の数として指定しなければなりません。 (例えば、データ・タイプ VARCHAR(18)、値 'MCKNIGHT' の列 NAME の場合、 SUBSTR(NAME,10) では空ストリングが戻されます。)

string は次のように処理されます。

固定長ストリングの場合、デフォルトの長さは LENGTH(string) - start +1 です。
可変長ストリングの場合、デフォルトの長さは、ゼロまたは LENGTH(string) - start + 1 のいずれか長いほうになります。

結果

string が文字ストリングの場合、結果は、その最初の引数のコード・ページおよびストリング単位で示された文字ストリングになります。バイナリー・ストリングの場合には、結果もバイナリー・ストリングになります。 GRAPHIC ストリングの場合は、結果も最初の引数のコード・ページおよびストリング単位で示された GRAPHIC ストリングになります。バイナリー・ストリングでも FOR BIT DATA 文字ストリングでもないホスト変数が最初の引数である場合、結果のコード・ページは、データベースのコード・ページになります。 SUBSTR 関数のいずれかの引数が NULL 値の可能性がある場合、結果も NULL 値になる可能性があります。いずれかの引数が NULL 値の場合、結果は NULL 値になります。

表 1 に、入力のタイプと属性ごとに、 SUBSTR 関数の結果タイプと長さがどうなるかを示しています。

表 1. SUBSTR の結果のデータ・タイプと長さ
ストリング引数のデータ・タイプ	長さ引数	結果データ・タイプ
CHAR(A)	定数 (l<n) ストリングの単位は、以下のとおりです。 OCTETS, n=256 CODEUNITS32, n=64	CHAR(l)
CHAR(A)	指定しない。start 引数は定数	CHAR(A-start+1)
CHAR(A)	定数以外	VARCHAR(A)
VARCHAR(A)	定数 (l<n) ストリングの単位は、以下のとおりです。 OCTETS, n=256 CODEUNITS32, n=64	CHAR(l)
VARCHAR(A)	定数 (m<l<n) ストリングの単位は、以下のとおりです。 OCTETS, m=256 および n=32673 CODEUNITS32, m=63 および n=8169	VARCHAR(l)
VARCHAR(A)	定数以外、または指定しない。	VARCHAR(A)
CLOB(A)	定数 (l)	CLOB(l)
CLOB(A)	定数以外、または指定しない。	CLOB(A)
GRAPHIC(A)	定数 (l<n) ストリングの単位は、以下のとおりです。 2 バイトまたは CODEUNITS16, n=128 CODEUNITS32, n=64	GRAPHIC(l)
GRAPHIC(A)	指定しない。start 引数は定数	GRAPHIC(A-start+1)
GRAPHIC(A)	定数以外	VARGRAPHIC(A)
VARGRAPHIC(A)	定数 (l<n) ストリングの単位は、以下のとおりです。 2 バイトまたは CODEUNITS16, n=128 CODEUNITS32, n=64	GRAPHIC(l)
VARGRAPHIC(A)	定数 (m<l<n) ストリングの単位は、以下のとおりです。 2 バイトまたは CODEUNITS16, m=127 および n=16337 CODEUNITS32, m=63 および n=8169	VARGRAPHIC(l)
VARGRAPHIC(A)	定数以外	VARGRAPHIC(A)
DBCLOB(A)	定数 (l)	DBCLOB(l)
DBCLOB(A)	定数以外、または指定しない。	DBCLOB(A)
BINARY(A)	定数 (l<256)	BINARY(l)
BINARY(A)	指定しない。start 引数は定数	BINARY(A-start+1)
BINARY(A)	定数以外	VARBINARY(A)
VARBINARY(A)	定数 (l<256)	BINARY(l)
VARBINARY(A)	定数 (255<l<32673)	VARBINARY(l)
VARBINARY(A)	定数以外、または指定しない。	VARBINARY(A)
BLOB(A)	定数 (l)	BLOB(l)
BLOB(A)	定数以外、または指定しない。	BLOB(A)

注: データ・タイプ LONG VARCHAR と LONG VARGRAPHIC は、引き続きサポートされていますが、非推奨になっています。

注

動的 SQL では、string、start、および length を、パラメーター・マーカーで表すことができます。string にパラメーター・マーカーが使用されると、オペランドのデータ・タイプは VARCHAR になり、オペランドは NULL 可能になります。
上記の結果定義には明確には述べられていませんが、この意味体系は、string が 1 バイト文字/マルチバイト文字混合ストリングの場合、 start と length の値によっては、結果にマルチバイト文字のフラグメントが入る可能性があるということを暗黙に示しています。例えば、場合によっては、結果がマルチバイト文字の 2 番目のバイトから始まったり、マルチバイト文字の最初のバイトで終わったりする可能性があります。 SUBSTR 関数は、このようなフラグメント化の検出を行わず、またこのようなフラグメント化があっても特別な処理は何も行われません。

例

例 1: ホスト変数 NAME (VARCHAR(50)) に値 'BLUE JAY' が含まれると想定します。
- 以下のステートメントでは、'BLUE' という値が戻されます。
```
   SUBSTR(:NAME,1,4)
```
- 以下のステートメントでは、'JAY' という値が戻されます。
```
   SUBSTR(:NAME,6)
```
- 以下のステートメントでは、'JA' という値が戻されます。
```
   SUBSTR(:NAME,6,2)
```
例 2: PROJECT 表から、語 'OPERATION' で始まるプロジェクト名 (PROJNAME) の行を全選択します。
```
   SELECT * FROM PROJECT
     WHERE SUBSTR(PROJNAME,1,10) = 'OPERATION '
```
定数の最後にあるスペースは、'OPERATIONAL' などの語を除外するために必要です。