$LISTGET

リスト内の要素または指定された既定値を返すリスト関数です。

Synopsis

$LISTGET(list[,position[,default]])

引数

list	有効なリストとして評価される式。list は、1 つ以上の要素を含むエンコードされた文字列です。list を作成するには、SQL または ObjectScript の $LISTBUILD 関数または $LISTFROMSTRING 関数を使用します。既存のリストから list を抽出するには、SQL または ObjectScript の $LIST 関数を使用します。
position	オプション — 指定したリスト内の位置として解釈される式。
default	オプション — list 要素が未定義の値を持つときに、返り値を作成する式。

概要

$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 引数を省略すると、長さゼロの文字列を既定値とします。

例

以下の埋め込み SQL の例の $LISTGET 関数は、どちらもリストの先頭要素である Red を返します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LISTGET(:a),$LISTGET(:a,1)
   INTO :b,:c)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The one-arg element returned is ",b
     WRITE !,"The two-arg element returned is ",c }

以下の埋め込み SQL の例の $LISTGET 関数は、どちらも、リストの最終要素である 3 つ目の要素 Green を返します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LISTGET(:a,3),$LISTGET(:a,-1)
   INTO :b,:c)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The third element is ",b
     WRITE !,"The last element is ",c }

以下の埋め込み SQL の例の $LISTGET 関数は、どちらも、リストの未定義の 2 つ目の要素が見つかった場合に値を返します。最初の例は、ユーザが既定値として定義した疑問符 (?) を返します。2 つ目の例は、既定値が指定されていないため NULL 文字列を返します。

   SET a=$LISTBUILD("Red",,"Green")
   &sql(SELECT $LISTGET(:a,2,'?'),$LISTGET(:a,2)
   INTO :b,:c)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The default value is ",b
     WRITE !,"The no-default value is ",c }

以下の埋め込み SQL の例の $LISTGET 関数は、どちらも 3 つの要素リストの最終要素よりも大きい位置を指定します。最初の例は、既定値が指定されていないため NULL 文字列を返します。2 つ目の例は、ユーザ指定の既定値 “ERR” を返します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LISTGET(:a,4),$LISTGET(:a,4,'ERR')
   INTO :b,:c)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The no-default 4th element is ",b
     WRITE !,"The default for 4th element is ",c }

以下の埋め込み SQL の例の $LISTGET 関数は、どちらも NULL 文字列を返します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LISTGET(:a,0),$LISTGET(NULL)
   INTO :b,:c)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The zero element is ",b
     WRITE !,"The NULL element is ",c }

メモ

無効な引数値

list 引数の式が有効なリストに評価されない場合は、$LISTGET が返す変数が未定義のままになるため、SQLCODE -400 の致命的なエラーが発生します。これは、以下の埋め込み SQL の例に示すように default 値が指定されている場合でも発生します。

   &sql(SELECT $LISTGET('fred',1,'failsafe') INTO :b)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The non-list element is ",b  ; Variable not set
   }

position 引数の値が -1 よりも小さい場合は、$LISTGET が返す変数が未定義のままになるため、SQLCODE -400 の致命的なエラーが発生します。これは、以下の埋め込み SQL の例に示すように default 値が指定されている場合でも発生します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LISTGET(:a,-3,'failsafe') INTO :c)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"A neg-num position returns ",c  ; Variable not set
   }

position が数値以外の値の場合は、このエラーは発生しません。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LISTGET(:a,'g','failsafe') INTO :c)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"A nonnumeric position returns ",c }