$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 文字を使用してエンコードします。