LOCATE_IN_STRING スカラー関数

LOCATE_IN_STRING 関数は、あるストリング (source-string、ソース・ストリングと呼ばれる) の中の、別のストリング (search-string、検索ストリングと呼ばれる) の開始位置を戻します。

スキーマは SYSIBM です。

search-string が見つからず、どちらの引数も NULL でない場合、結果はゼロになります。 search-string が見つかった場合、結果は 1 から source-string の実際の長さまでの数値になります。検索には、データベースの照合が使用されます。ただし、 search-string または source-string がバイナリー・ストリングまたは FOR BIT DATA で定義されている場合は除きます。その場合は、バイナリー比較によって検索が行われます。

オプションの start が指定されている場合、それは、source-string 中での検索が開始される文字位置を示します。 start が指定されている場合は、インスタンスの出現回数も指定できます。 instance 引数は、source-string 中の search-string のうち、出現回数が指定した値となるものの位置を特定するために使用されます。オプションのストリング単位は、start と関数の結果がどの単位で表現されるかを表すために指定できます。

search-string の長さがゼロの場合、関数によって返される結果は 1 になります。 source-string の長さがゼロの場合、関数によって返される結果は 0 になります。そのどちらでもなく、search-string の値が source-string の値の中に隣接して位置する同じ長さのサブストリングと等しい場合、関数によって返される結果は、source-string 値内のそのサブストリングの開始位置になります。そうでない場合、関数によって返される結果は 0 になります。

ソース・ストリング

その中で検索が行われるストリングを指定する式。式は、組み込みストリング、数値、ブール値、または日時のいずれかのデータ・タイプの値を返す必要があります。値がストリング・データ・タイプでない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。

検索ストリング

検索の対象となるストリングを指定する式。式は、組み込み CHAR、VARCHAR、GRAPHIC、VARGRAPHIC、バイナリー・ストリング、数値、ブール、または日時のいずれかのデータ・タイプの値を戻す必要があります。値が CHAR、VARCHAR、GRAPHIC、VARGRAPHIC、またはバイナリー・ストリングのデータ・タイプではない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。 LOB ファイル参照変数でこの式を指定することはできません。

start

一致検索が開始される source-string 内の位置を指定する式。式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。

INTEGER の値が 0 より大きい場合、検索は start の位置から開始され、ストリングの末尾にいたるまで各位置で実行されます。 INTEGER の値が 0 より小さい場合、検索は LENGTH (source-string) + start + 1 の位置から開始され、ストリングの先頭にいたるまで、各位置で実行されます。

start が指定されていない場合、デフォルトは 1 です。 OCTETS を指定し、source-string がグラフィック・データである場合、整数の値は奇数でなければなりません (SQLSTATE 428GC)。整数の値がゼロの場合、エラーが戻されます (SQLSTATE 42815)。

インスタンス

source-string の中の検索する search-string のインスタンスを指定する式。式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。 instance が指定されていない場合、デフォルトは 1 です。この INTEGER の値は 1 以上でなければなりません (SQLSTATE 42815)。

CODEUNITS16、CODEUNITS32、または OCTETS

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

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

ストリング単位が明示的に指定されていない場合、および source-string が文字ストリングまたはグラフィック・ストリングである場合、source-string のストリング単位によって、結果と start (指定されている場合) に使用される単位が決まります。それ以外の場合、これらはバイト単位で表されます。

ロケールに依存する UCA ベースの照合がこの関数に使用される場合は、CODEUNITS16 オプションから最も適したパフォーマンスの特性を得られます。

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

1 番目と 2 番目の引数は、互換性のあるストリング・タイプを持たなければなりません。互換性について詳しくは、ストリング変換の規則を参照してください。 Unicode データベースでは、一方のストリング引数が文字で (FOR BIT DATA ではない)、他方のストリング引数が GRAPHIC である場合、search-string は、処理のために source-string のデータ・タイプに変換されます。一方の引数が文字 FOR BIT DATA である場合、他方の引数は GRAPHIC であってはなりません (SQLSTATE 42846)。

各検索位置で、その検索位置から LENGTH (search-string) - 1 の値だけ右にある位置までの source-string のサブストリングが、search-string と等しい場合に、一致が検出されます。

この関数の結果は長精度整数 (large integer) です。結果は、source-string 中の search-string のインスタンスの開始位置です。この値は、start 指定に関わらず、ストリングの開始位置を意味します。引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。引数のいずれかが NULL の場合、その結果は NULL 値です。

LOCATE_IN_STRING の同義語として INSTR を使用できます。

INSTRB スカラー関数は、開始位置と結果がバイト単位で示されることを示す OCTETS を指定した (指定可能な場合) LOCATE_IN_STRING 関数の呼び出しに相当します。

例

例 1: ストリング Jürgen lives on Hegelstraße 内で文字 ß をストリングの末尾から検索して、そのストリング内での位置を CODEUNITS32 単位でホスト変数 POSITION に設定します。
```
    SET :POSITION = LOCATE_IN_STRING('Jürgen lives on Hegelstraße',
                                    'ß',-1,CODEUNITS32);
```
ホスト変数 POSITION の値は 26 に設定されます。
例 2: ストリング WINNING 内で文字 N が 3 回目に出現する位置を、ストリングの開始位置から検索して特定し、その文字のストリング内での位置を、バイト単位でホスト変数 POSITION に設定します。
```
    SET :POSITION =
    LOCATE_IN_STRING('WINNING','N',1,3,OCTETS);
```
ホスト変数 POSITION の値は 6 に設定されます。