$LIST

$LIST(list[,position[,end]])

list	有効なリストに評価される式。リストにはエンコードが含まれるので、list は Caché ObjectScript $LISTBUILD 関数を使用して作成されるか、または $LIST を使用して他のリストから抽出されなければなりません。
position	オプション — 指定されたリストの開始位置。整数に評価される式です。
end	オプション — 指定されたリストの終了位置。整数に評価される式です。

$LIST は、リストから要素を返します。返される要素は、使用する引数によって決まります。

1 つ以上の要素を含む、エンコードされたリスト文字列。リストは、Caché ObjectScript $LISTBUILD 関数を使用して作成されます。以下の例に示すように、ホスト変数を使用して、SQL $LIST 関数にリストを指定できます。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2)
   INTO :b
   FROM Sample.Person)
   WRITE !,"The element returned is ",b

リストは、$LIST 関数を使用して、別のリストから抽出することもできます。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2,3)
   INTO :b
   FROM Sample.Person)
   &sql(SELECT $LIST(:b,1)
   INTO :c
   FROM Sample.Person)
   WRITE !,"The element returned is ",c

以下の例では、subList は有効な list 引数ではありません。これは通常の文字列として返された 1 つの要素であり、エンコードされたリスト文字列ではないためです。3-引数形式の $LIST のみが、エンコードされたリスト文字列を返します。この場合は、SQL –400 の致命的なエラーが発生します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2)
   INTO :sublist
   FROM Sample.Person)
   &sql(SELECT $LIST(:sublist,1)
   INTO :c
   FROM Sample.Person)
   WRITE !,"Error code ",SQLCODE
   WRITE !,"The sublist is"
   ZZDUMP c   ; Variable not set

返されるリスト要素の位置。リスト要素は、1 から始まります。position が省略されている場合は、最初の要素が返されます。position の値が 0、またはリストの要素の数よりも大きい場合、Caché SQL は値を返しません。position の値がマイナス 1 (–1) の場合、$LIST はリストの最後の要素を返します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,-1)
   INTO :b
   FROM Sample.Person)
   WRITE !,"The last element is ",b

end 引数が指定されている場合、position は要素範囲の最初の要素を指定します。(position と end が同じ値のとき) 要素が 1 つだけ返されますが、その要素はエンコードされた文字列として返されます。したがって、$LIST(x,2) (要素を通常の文字列として返す) は $LIST(x,2,2) (要素をエンコードされた文字列として返す) と同じではありません。

要素範囲の最後の要素の位置。end を指定するには、position を指定する必要があります。end が指定されている場合、返される値はエンコードされたリスト文字列です。このような文字列はエンコードされているため、他の $LIST 関数によってのみ処理されます。

end を指定する場合、position 値はゼロ (0) に指定できます。この場合、0 は 1 と同じです。

以下の例の 2 つの WRITE 文は、ともにリストの先頭要素である “Red” を返します。最初の WRITE 文では、既定で先頭要素が記述され、2 番目の WRITE 文では、position 引数が 1 に設定されているため先頭要素が記述されます。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a),$LIST(:a,1)
   INTO :b,:c
   FROM Sample.Person)
   WRITE !,"The one-arg sublist is ",b
   WRITE !,"The two-arg sublist is ",c

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2)
   INTO :b
   FROM Sample.Person)
   WRITE !,"The second element is ",b

以下の例は “Red Blue” を返します。“Red Blue” は先頭要素で開始して、2 つ目の要素で終了する 2 要素リスト文字列です。WRITE ではなく ZZDUMP を使用しますが、これは特殊 (印字不可能) 文字をリストに含むことが可能なためです。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,1,2)
   INTO :b
   FROM Sample.Person)
   WRITE !,"The encoded sublist is"
   ZZDUMP b   ; Prints "Red Blue "

以下の例は、長さが分からないリストの最後の要素を返します。最初の WRITE 文では、最後の要素が通常の文字列として返され、2 番目の WRITE 文では、エンコードされた文字列として返されます。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LISTLENGTH(:a),$LIST(:a,-1)
   INTO :b,:plain
   FROM Sample.Person)
   &sql(SELECT $LIST(:a,:b,-1)
   INTO :encoded
   FROM Sample.Person)
   WRITE !,"The final element as a string: ",plain
   WRITE !,"The final element as an encoded string: "
   ZZDUMP encoded

list 引数の式が有効なリストに評価されない場合は、SQL –400 の致命的なエラーが発生します。

   SET a="the quick brown fox"
   &sql(SELECT $LIST(:a,1)
   INTO :b
   FROM Sample.Person)
   WRITE !,"Error code ",SQLCODE
   WRITE !,"The sublist is"
   ZZDUMP b   ; Variable not set

position 引数または end 引数の値が -1 よりも小さい場合は、SQL –400 の致命的なエラーが発生します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,-2,3)
   INTO :b
   FROM Sample.Person)
   WRITE !,"Error code ",SQLCODE
   WRITE !,"The sublist is"
   ZZDUMP b   ; Variable not set

position 引数の値が存在しないリスト・メンバを参照するときに end 引数が使用されていない場合は、SQL –400 の致命的なエラーが発生します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,7)
   INTO :b
   FROM Sample.Person)
   WRITE !,"Error code ",SQLCODE
   WRITE !,"The sublist is"
   ZZDUMP b   ; Variable not set

ただし、end 引数が使用されている場合は、エラーは発生せず、NULL 文字列が返されます。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,7,-1)
   INTO :b
   FROM Sample.Person)
   WRITE !,"Error code ",SQLCODE
   WRITE !,"The sublist is"
   ZZDUMP b   ; Prints a null string

position 引数の値が、値が未定義の要素を指す場合は、SQL –400 の致命的なエラーが発生します。

   SET a=$LISTBUILD("Red",,"Green")
   &sql(SELECT $LIST(:a,2)
   INTO :b
   FROM Sample.Person)
   WRITE !,"Error code ",SQLCODE
   WRITE !,"The sublist is"
   ZZDUMP b   ; Variable not set

$LIST(list,1) と $LIST(list,1,1) は同じではありません。前者は文字列を返すのに対し、後者は要素が 1 つのリスト文字列を返します。返す要素がない場合、2-引数形式は値を返さず、3-引数形式は NULL 文字列を返します。

リスト要素内に Unicode 文字が 1 つでもあれば、リスト要素全体が Unicode (ワイド) 文字として表されます。リスト内の他の要素は影響されません。

以下の例は、2 つのリストを示しています。a リストは、ASCII 文字のみが含まれる 2 つの要素で構成されます。b リストは 2 つの要素で構成され、最初の要素には Unicode 文字 ($CHAR(960)、つまり pi 記号) が含まれ、2 番目の要素には ASCII 文字のみが含まれます。

   SET a=$LISTBUILD("ABC"_$CHAR(68),"XYZ")
   SET b=$LISTBUILD("ABC"_$CHAR(960),"XYZ")
   &sql(SELECT $LIST(:a,1),$LIST(:a,2),$LIST(:b,1),$LIST(:b,2)
   INTO :a1,:a2,:b1,:b2
   FROM Sample.Person)
   WRITE !,"The ASCII list a elements: "
   ZZDUMP a1
   ZZDUMP a2
   WRITE !,"The Unicode list b elements: "
   ZZDUMP b1
   ZZDUMP b2

Caché は、b の先頭要素全体をワイド Unicode 文字でエンコードすることに注意してください。b の 2 番目の要素には Unicode 文字が含まれないため、Caché は 1 バイトの ASCII 文字を使用してエンコードします。