$LISTGET (SQL)
構文
$LISTGET(list[,position[,default]])
説明
$LISTGET は、指定したリスト内の要求した要素を標準文字の文字列として返します。position 引数値が存在しないメンバを参照している場合、または未定義値を持つ要素を指している場合は、指定された既定値を返します。
$LISTGET 関数は、$LIST 関数の引数が 1 つおよび 2 つの形式とまったく同じですが、$LIST が NULL 文字列を返す条件下では、$LISTGET は既定値を返します。
この関数は、データ型 VARCHAR を返します。
$LISTGET を使用すると、シリアル・コンテナ・フィールドからフィールド値を取得できます。以下の例では、Home がシリアル・コンテナ・フィールドであり、その 3 つ目の要素が Home_State です。
SELECT Name,$LISTGET(Home,3) AS HomeState
FROM Sample.Person
引数
list
1 つ以上の要素を含む、エンコードされた文字の文字列。リストは、SQL $LISTBUILD 関数または ObjectScript $LISTBUILD 関数を使用して作成できます。区切り文字列からリストへの変換は、SQL $LISTFROMSTRING 関数または ObjectScript $LISTFROMSTRING 関数を使用して行うことができます。既存のリストからのリストの抽出は、SQL $LIST 関数または ObjectScript $LIST 関数を使用して行うことができます。
position
position 引数は、必ず整数として評価される必要があります。省略する場合、関数はリストの先頭要素を既定で調べます。position 引数の値が -1 の場合は、リストの最終要素を指定するのと同じ意味です。
default
これは文字列です。default 引数を省略すると、長さゼロの文字列を既定値とします。
例
以下の例の $LISTGET 関数は、どちらもリストの先頭要素である “Red” を返します。
SELECT
$LISTGET($LISTBUILD("Red","Blue","Green")),
$LISTGET($LISTBUILD("Red","Blue","Green"),1)
以下の例の $LISTGET 関数は、どちらも、リストの最終要素である 3 つ目の要素 “Green” を返します。
SELECT
$LISTGET($LISTBUILD("Red","Blue","Green"),3),
$LISTGET($LISTBUILD("Red","Blue","Green"),-1)
以下の例の $LISTGET 関数は、どちらも、リストの未定義の 2 つ目の要素が見つかった場合に、値を返します。最初の例は、ユーザが既定値として定義した疑問符 (?) を返します。2 つ目の例は、既定値が指定されていないため NULL 文字列を返します。
SELECT
$LISTGET($LISTBUILD("Red",,"Green"),2,'?'),
$LISTGET($LISTBUILD("Red",,"Green"),2)
以下の例の $LISTGET 関数は、どちらも 3 つの要素リストの最終要素よりも大きい位置を指定します。最初の例は、既定値が指定されていないため NULL 文字列を返します。2 つ目の例は、ユーザ指定の既定値 “ERR” を返します。
SELECT
$LISTGET($LISTBUILD("Red","Blue","Green"),4),
$LISTGET($LISTBUILD("Red","Blue","Green"),4,'ERR')
以下の例の $LISTGET 関数は、どちらも NULL 文字列を返します。
SELECT
$LISTGET($LISTBUILD("Red","Blue","Green"),0),
$LISTGET(NULL)
メモ
無効な引数値
list 引数の式が有効なリストに評価されない場合は、$LISTGET が返す変数が未定義のままになるため、SQLCODE -400 の致命的なエラーが発生します。これは、以下の例に示すように default 値が指定されている場合でも発生します。
SELECT $LISTGET('fred',1,'failsafe')
position 引数の値が -1 よりも小さい場合は、$LISTGET が返す変数が未定義のままになるため、SQLCODE -400 の致命的なエラーが発生します。これは、以下の例に示すように default 値が指定されている場合でも発生します。
SELECT $LISTGET($LISTBUILD("Red","Blue","Green"),-3,'failsafe')
position が数値以外の値の場合は、このエラーは発生しません。
SELECT $LISTGET($LISTBUILD("Red","Blue","Green"),'g','failsafe')