リストを使用した作業
1 つのテーブルにリスト・フィールドを 1 つ以上含めることができます。リストはエンコードされた文字列であるため、これらのフィールドはデータ型 %List (%Library.List) またはデータ型 VARCHAR として定義できます。データ型 %List のフィールドは、CType (クライアント・データ型) = 6 として定義できます。
データ型は、挿入または更新の際にフィールドで許可される値を制限するものではありません。したがって、ユーザは、リスト・フィールド内のデータ値がすべてリスト・エンコードされた文字の文字列であることを確認する必要があります。SQL $LIST 関数がエンコードされていない文字列のデータ値を検出した場合、SELECT 操作は SQLCODE -400 で失敗し、%msg は "予期しないエラーが発生しました: <LIST>%0AmBuncommitted+1^%sqlcq.USER.cls61.1" のようになります。
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
}
}
例
以下の埋め込み 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 文字のみが含まれます。
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 }
InterSystems IRIS は、b の先頭要素全体をワイド Unicode 文字でエンコードすることに注意してください。b の 2 番目の要素には Unicode 文字が含まれないため、InterSystems IRIS は 1 バイトの ASCII 文字を使用してエンコードします。