POSITION スカラー関数

POSITION 関数は、あるストリングが別のストリング内で最初に出現する箇所の開始位置を返します。

スキーマは SYSIBM です。

POSITION 関数で見つけるストリングは、search-string です。検索対象を中に含んでいるストリングは、source-string です。 POSITION 関数は、あるストリング (search-string と呼ばれる) の、別のストリング (source-string と呼ばれる) の中での、最初の出現箇所の開始位置を戻します。 search-string が見つからず、いずれの引数も NULL でない場合、結果は 0 です。 search-string が見つかった場合、結果として、1 から source-string の実際の長さまでの数が、明示的に指定されたストリング単位で表記されます。検索には、データベースの照合が使用されます。ただし、 search-string または source-string がバイナリー・ストリングまたは FOR BIT DATA で定義されている場合は除きます。その場合は、バイナリー比較によって検索が行われます。

source-string の実際の長さが 0 の場合、関数の結果は 0 です。search-string の実際の長さが 0 で、source-string が NULL 以外の場合、関数の結果は 1 です。

search-string

検索対象のストリングを指定する式。この式は、組み込みの文字ストリング、GRAPHIC ストリング、バイナリー・ストリング、数値、ブール値、または日時値のいずれかの値を返す必要があります。値が文字ストリング、GRAPHIC ストリング、またはバイナリー・ストリングのいずれでもない場合は、関数の評価の前に VARCHAR に暗黙的にキャストされます。この式は、LOB ファイル参照変数は使用できません。この式は、以下のいずれかのエレメントによって指定できます。

定数
特殊レジスター
ホスト変数
上記リスト項目のいずれかをオペランドとするスカラー関数
上記の任意の項目を連結 (CONCAT または || を使用して) する式
SQL プロシージャー・パラメーター

これらの規則は、LIKE 述部の pattern-expression に関して記述されるものと同様になります。

source-string

検索対象のストリングを指定する式。この式は、組み込みの文字ストリング、数値、ブール値、日時値のいずれかの値を返す必要があります。値がストリング・データ・タイプでない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。この式は、以下のいずれかのエレメントによって指定できます。

定数
特殊レジスター
ホスト変数 (ロケーター変数またはファイル参照変数を含む)
スカラー関数
ラージ・オブジェクトのロケーター
列名
上記の任意の項目を連結 (CONCAT または || を使用して) する式

CODEUNITS16 または CODEUNITS32 または OCTETS

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

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

ストリング単位引数が指定されておらず、search-string と source-string の両方が FOR BIT DATA 以外の文字ストリングであるか、グラフィック・ストリングである場合、デフォルトは CODEUNITS32 です。それ以外の場合、デフォルトは OCTETS です。

ロケールに依存する 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: ストリングを含む IN_TRAY 表内のすべての行の NOTE_TEXT 列内で、RECEIVED 列、SUBJECT 列、およびストリング 'GOOD BEER' の開始位置を選択します。
```
   SELECT RECEIVED, SUBJECT, POSITION('GOOD BEER', NOTE_TEXT, OCTETS)
   FROM IN_TRAY
   WHERE POSITION('GOOD BEER', NOTE_TEXT, OCTETS) <> 0
```
例 2: 文字 'ß' の位置をストリング 'Jürgen lives on Hegelstraße' から見つけ、ストリング内で CODEUNITS32 単位を尺度として、ホスト変数 LOCATION をその位置で設定します。
```
   SET :LOCATION = POSITION(
     'ß', 'Jürgen lives on Hegelstraße', CODEUNITS32
   )
```
ホスト変数 LOCATION の値は 26 に設定されます。
例 3: 文字 'ß' の位置をストリング 'Jürgen lives on Hegelstraß' から見つけ、ストリング内で OCTETS を尺度として、ホスト変数 LOCATION をその位置で設定します。
```
   SET :LOCATION = POSITION(
     'ß', 'Jürgen lives on Hegelstraße', OCTETS
   )
```
ホスト変数 LOCATION の値は 27 に設定されます。
例 4: 以下の例は、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 POSITION('N', UTF8_VAR, CODEUNITS16),
     POSITION('N', UTF8_VAR, CODEUNITS32),
     POSITION('N', UTF8_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
これは値 3、2、および 5 をそれぞれ戻します。
変数 UTF16_VAR に、ストリングの UTF-16BE 表現が格納されると想定します。
```
   SELECT POSITION('B', UTF16_VAR, CODEUNITS16),
      POSITION('B', UTF16_VAR, CODEUNITS32),
      POSITION('B', UTF16_VAR, OCTETS)
   FROM SYSIBM.SYSDUMMY1
```
これは値 6、5、および 11 をそれぞれ戻します。
例 5: 大/小文字を区別しない照合 CLDR181_LEN_S1 で作成された Unicode データベース内で、'The quick brown fox' という句の中の 'Brown' という語の位置を検索します。
```
SET :LOCATION = POSITION('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'