$LIST

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

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

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

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

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2)
   INTO :b
   FROM Sample.Person)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The element returned is ",b }

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2,3)
   INTO :b
   FROM Sample.Person)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
   &sql(SELECT $LIST(:b,1)
   INTO :c
   FROM Sample.Person)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The element returned is ",c }
   }

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

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2)
   INTO :sublist
   FROM Sample.Person)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
   &sql(SELECT $LIST(:sublist,1)
   INTO :c
   FROM Sample.Person)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     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)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The last element is ",b }

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

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

以下の埋め込み SQL の例で、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)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     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)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The second element is ",b }

以下の埋め込み SQL の例は "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)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The encoded sublist is"
     ZZDUMP b   ; Prints "Red Blue " 
     }

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

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

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

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

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

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

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

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,7)
   INTO :b
   FROM Sample.Person)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     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)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     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)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The sublist is"
     ZZDUMP b   ; Variable not set
     }

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

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

以下の埋め込み SQL の例は、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)
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     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 文字を使用してエンコードします。