LOCATE スカラー関数

LOCATE 関数は、あるストリング (search-string と呼ばれる) が別のストリング (source-string と呼ばれる) 内で、最初のオカレンスの開始位置を戻します。

スキーマは SYSIBM です。 LOCATE 関数の SYSFUN バージョンは引き続き使用可能です。ただし、データベースの照合に依存しているわけではありません。

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

オプションの start が指定されている場合、それは、source-string 中での検索が開始される文字位置を示します。オプションのストリング単位は、start と関数の結果がどの単位で表現されるかを表すために指定できます。

search-string の長さがゼロの場合、関数によって返される結果は 1 になります。ソース・ストリングの長さが 0 の場合、関数によって戻される結果は 0 です。それ以外の場合は、次のとおりです。

search-string の値が source-string の値内の、連続する複数の位置にある同じ長さのサブストリングと等しい場合、関数によって戻される結果は、source-string 値内のその最初のサブストリングの開始位置になります。
それ以外の場合、この関数によって戻される結果は 0 です。

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

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

start

検索が開始される source-string 内の位置を指定する式。式は組み込み数値、CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のいずれかのデータ・タイプの値を戻す必要があります。値がタイプ INTEGER でない場合、その値は関数を評価する前に暗黙的に INTEGER にキャストされます。整数の値はゼロ以上でなければなりません。. start が指定された場合、LOCATE 関数は以下のようになります。

   POSITION(search-string,
     SUBSTRING(source-string, start, string-unit),
     string-unit) + start - 1

ここで、 string-unit は CODEUNITS16、 CODEUNITS32、または OCTETS のいずれかです。

start が指定されない場合、検索はソース・ストリングの先頭の位置から開始され、LOCATE 関数は以下のようになります。

   POSITION(search-string, source-string, string-unit)

OCTETS を指定し、source-string がグラフィック・データである場合、整数の値は奇数でなければなりません (SQLSTATE 428GC)。

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)。

この関数の結果は長精度整数 (large integer) です。引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。引数のいずれかが NULL の場合、その結果は NULL 値です。

例

例 1: ストリング "DINING" 中に最初に現れる文字 "N" の位置を探す。
```
   SELECT LOCATE('N', 'DINING')
   FROM SYSIBM.SYSDUMMY1
```
結果は値 3 になります。
例 2: IN_TRAY という名前の表の中のすべての行について、RECEIVED 列と SUBJECT 列を選択し、NOTE_TEXT 列内のストリング "GOOD" の開始位置を選択する。
```
   SELECT RECEIVED, SUBJECT, LOCATE('GOOD', NOTE_TEXT)
   FROM IN_TRAY
   WHERE LOCATE('GOOD', NOTE_TEXT) <> 0
```
例 3: ストリング "Jürgen lives on Hegelstraße" 内の、文字 "ß" の位置を特定し、そのストリング内での位置を、CODEUNITS32 単位でホスト変数 LOCATION に設定する。
```
   SET :LOCATION = LOCATE('ß', 'Jürgen lives on Hegelstraße', 1, CODEUNITS32)
```
ホスト変数 LOCATION の値は 26 に設定されます。
例 4: ストリング JュルゲンがHegelstra弦上にある中で文字「shadow 」を見つけ、ストリング内の CODEUNITS16 単位で測定された位置を使用してホスト変数 LOCATION を設定します。
```
   SET :LOCATION = LOCATE('ß', 'Jürgen lives on Hegelstraße', 1, CODEUNITS16)
```
ホスト変数 LOCATION の値は 26 に設定されます。
例 5: ストリング "Jürgen lives on Hegelstraße" 内の、文字 "ß" の位置を特定し、そのストリング内での位置を、OCTETS でホスト変数 LOCATION に設定する。
```
   SET :LOCATION = LOCATE('ß', 'Jürgen lives on Hegelstraße', 1, OCTETS)
```
ホスト変数 LOCATION の値は 27 に設定されます。
例 6: 以下の例は、Unicode ストリング “&N~AB” に対応します。“ &” は音楽のト音記号、“~” はスペースなしで続く表記のチルド文字です。以下の例では、このストリングを異なる Unicode エンコード方式で示しています。

& N ~ A B

UTF-8 X'F09D849E' X'4E' X'CC83' X'41' X'42'

UTF-16BE X'D834DD1E' X'004E' X'0303' X'0041' X'0042'
変数 UTF8_VAR に、ストリングの UTF-8 表現が格納されると想定します。
```
   SELECT LOCATE('~', UTF8_VAR, CODEUNITS16),
     LOCATE('~', UTF8_VAR, CODEUNITS32),
     LOCATE('~', UTF8_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ、値 4、3、6 を戻します。
変数 UTF16_VAR に、ストリングの UTF-16BE 表現が格納されると想定します。
```
   SELECT LOCATE('~', UTF16_VAR, CODEUNITS16),
      LOCATE('~', UTF16_VAR, CODEUNITS32),
      LOCATE('~', UTF16_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
それぞれ、値 4、3、7 を戻します。
例 7: 大/小文字を区別しない照合 CLDR181_LEN_S1 で作成された Unicode データベース内で、"The quick brown fox" という句の中の "Brown" という語の位置を検索します。
```
SET :LOCATION = LOCATE('Brown', 'The quick brown fox', CODEUNITS16)
```
ホスト変数 LOCATION の値は 11 に設定されます。

	&	N	~	A	B
UTF-8	X'F09D849E'	X'4E'	X'CC83'	X'41'	X'42'
UTF-16BE	X'D834DD1E'	X'004E'	X'0303'	X'0041'	X'0042'