$LIST

リスト内の要素を返すリスト関数です。

Synopsis

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

引数

list	有効なリストとして評価される式。list は、1 つ以上の要素を含むエンコードされた文字列です。list を作成するには、SQL または ObjectScript の $LISTBUILD 関数または $LISTFROMSTRING 関数を使用します。既存のリストから list を抽出するには、SQL または ObjectScript の $LIST 関数を使用します。
position	オプション — 指定したリストの開始位置。整数として評価される式です。
end	オプション — 指定したリストの終了位置。整数として評価される式です。

概要

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

$LIST(list) は、リストの最初の要素をテキスト文字列として返します。
$LIST(list,position) は、指定された位置にある要素をテキスト文字列として返します。position 引数は、必ず整数として評価される必要があります。
$LIST(list,position,end) は、指定された開始 position から指定された end 位置までの範囲の、リストの要素を含む “sublist” (エンコードされたリスト文字列) を返します。

この関数は、データ型 VARCHAR を返します。

引数

list

1 つ以上の要素を含む、エンコードされた文字の文字列。リストは、SQL $LISTBUILD 関数または ObjectScript $LISTBUILD 関数を使用して作成できます。区切り文字列からリストへの変換は、SQL $LISTFROMSTRING 関数または ObjectScript $LISTFROMSTRING 関数を使用して行うことができます。既存のリストからのリストの抽出は、SQL $LIST 関数または ObjectScript $LIST 関数を使用して行うことができます。

SQL の $LIST 関数にリストを渡すには、ホスト変数を使用するか、SQL 内で $LISTBUILD を指定します。以下の埋め込み SQL の例では、両方の方法を示しています。

   SET mylist=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:mylist,2),$LIST($LISTBUILD('Red','Blue','Green'),3)
   INTO :a,:b )
   IF SQLCODE'=0 {
     WRITE "Error code ",SQLCODE,! }
   ELSE {
     WRITE !,"The host varable list element is ",a,!
     WRITE !,"The SQL $LISTBUILD list element is ",b,! }

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

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

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

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

position

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

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,-1)
   INTO :b )
   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

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

end の値によって、次のように処理されます。

position よりも大きい場合、要素のリストを含むエンコードされた文字列が返されます。
position と等しい場合、1 つの要素を含むエンコードされた文字列が返されます。
position よりも小さい場合、値は返されません。
list の要素数よりも大きい場合、リストの最後の要素を指定するのと同じです。
マイナス -1 (–1) のとき、リストの最後の要素を指定するのと同じです。

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

例

以下の埋め込み 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 )
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"The one-arg sublist is ",b
     WRITE !,"The two-arg sublist is ",c }

以下の埋め込み SQL の例は、リストで 2 つ目の要素である “Blue” を返します。

   SET a=$LISTBUILD("Red","Blue","Green")
   &sql(SELECT $LIST(:a,2)
   INTO :b )
   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 )
   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 )
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
   &sql(SELECT $LIST(:a,:b,-1)
   INTO :encoded )
   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 )
   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 )
   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 )
   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 )
   IF SQLCODE'=0 {
     WRITE !,"Error code ",SQLCODE }
   ELSE {
     WRITE !,"Error code ",SQLCODE
     WRITE !,"The sublist is"
     ZZDUMP b   ; Prints a null string 
     }

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

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

引数が 2 つの $LIST と引数が 3 つの $LIST

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

Unicode

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

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

  IF $SYSTEM.Version.IsUnicode() {
   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 )
   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 }
  }
  ELSE {WRITE "This example requires a Unicode installation of Caché"}

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