$LISTFIND (SQL)
構文
$LISTFIND(list,value[,startafter])
概要
$LISTFIND は、指定された list で、要求された value の最初のインスタンスを検索します。startafter 引数で指定された位置の次の要素から検索を開始します。startafter 引数を省略すると、$LISTFIND は startafter 引数値を 0 と見なし、先頭要素 (要素 1) から検索を開始します。値が見つかると、$LISTFIND は一致する要素の位置を返します。値が見つからないか、startafter 引数の値が存在しないリスト・メンバを参照する場合は、$LISTFIND は 0 を返します。
この関数は、データ型 SMALLINT を返します。
引数
list
有効なリストとして評価される式。list は、1 つ以上の要素を含むエンコードされた文字列です。list を作成するには、SQL または ObjectScript の $LISTBUILD 関数または $LISTFROMSTRING 関数を使用します。既存のリストから list を抽出するには、SQL または ObjectScript の $LIST 関数を使用します。
value
検索要素を含む式。これは文字列です。
startafter
リスト位置として解釈される整数式 (オプション)。この位置の後の要素から検索を開始します。ゼロと -1 が有効値で、-1 は要素を返しません。ゼロが既定です。
例
以下の例は、要求された文字列の最初に発生した位置である 2 を返します。
SELECT $LISTFIND($LISTBUILD("Red","Blue","Green"),'Blue')
以下の例は 0 を返し、要求された文字列が見つからなかったことを表します。
SELECT $LISTFIND($LISTBUILD("Red","Blue","Green"),'Orange')
以下の 3 つの例は、startafter 引数の実行結果です。最初の例は、要求された文字列が startafter 位置にあるため、要求した文字列が見つからず 0 を返します。
SELECT $LISTFIND($LISTBUILD("Red","Blue","Green"),'Blue',2)
2 番目の例は、startafter がゼロ (既定値) に設定されているため、要求された文字列が先頭位置にあるのを見つけます。
SELECT $LISTFIND($LISTBUILD("Red","Blue","Green"),'Red',0)
3 番目の例は、要求された文字列の 1 つ目が startafter 位置より前にあるため、2 つ目を見つけて 5 を返します。
SELECT $LISTFIND($LISTBUILD("Red","Blue","Green","Yellow","Blue"),'Blue',3)
$LISTFIND 関数は、完全な要素のみと一致します。したがって、以下の例ではすべての要素に “B” が含まれているものの、リスト要素が文字列 “B” とは同じではないため、0 が返されます。
SELECT $LISTFIND($LISTBUILD("ABC","BCD","BBB"),'B')
メモ
無効な引数値
list 引数の式が有効なリストとして評価されない場合、$LISTFIND 関数を使用すると SQLCODE -400 の致命的なエラーが発生します。
SELECT $LISTFIND("Blue",'Blue')
startafter 引数の値が -1 の場合、$LISTFIND は常にゼロ (0) を返します。
SELECT $LISTFIND($LISTBUILD("Red","Blue","Green"),'Blue',-1)
startafter 引数の値が -1 より小さい場合、$LISTFIND 関数を呼び出すと、SQLCODE -400 の致命的なエラーが発生します。
SELECT $LISTFIND($LISTBUILD("Red","Blue","Green"),'Blue',-3)
