$LISTBUILD (SQL)

文字列からリストを作成するリスト関数。

Synopsis

$LISTBUILD(element [,...])

引数

引数	説明
element	任意の式、または式のコンマ区切りのリスト。

説明

$LISTBUILD は 1 つまたは複数の式を取り、1 つの式に対して 1 つの要素があるリストを返します。

リストの作成には、以下の関数を使用できます。

$LISTBUILD は、複数の文字列から、要素ごとに 1 つの文字列を含むリストを作成します。
$LISTFROMSTRING は、複数の区切られた要素を持つ 1 つの文字列からリストを作成します。
$LIST は、既存のリストからサブリストを抽出します。

$LISTBUILD は、他の InterSystems SQL リスト関数 ($LIST、$LISTDATA、$LISTFIND、$LISTFROMSTRING、$LISTGET、$LISTLENGTH、$LISTTOSTRING) と共に使用されます。

Note:

$LISTBUILD とその他の $LIST 関数は、最適化された 2 進数の表現を使用してデータ要素を格納します。このため、$LIST データで予期されているような等価テストが利用できない場合もあります。他のコンテキストでは同等と見なされるデータが、異なる内部表現を持つこともあります。例えば、$LISTBUILD(1) と $LISTBUILD("1") は同じではありません。

同じ理由から、$LISTBUILD によって返されたリスト文字列値は、$PIECE や 2 つの引数形式の $LENGTH など、区切り文字を使用する文字検索や関数の解析には使用するべきではありません。$LISTBUILD で生成されたリストの要素は、区切り文字によってマークされないので、任意の文字を含むことができます。

例

以下の埋め込み SQL の例では、3 つの文字列を受け取り、3 つの要素を持つリストを作成します。

  SET x="Red"
  SET y="White"
  SET z="Blue"
  &sql(SELECT $LISTBUILD(:x,:y,:z)
       INTO :listout)
  IF SQLCODE=0 {WRITE listout," length ",$LISTLENGTH(listout)}
  ELSE {WRITE "Error code:",SQLCODE}

メモ

引数の省略

要素式を省略すると、値が NULL の要素が生成されます。例えば、以下の埋め込み SQL には 2 つの $LISTBUILD 文がありますが、どちらも、3 つの要素を持つリストを生成し、2 つ目の要素には未定義 (NULL) 値が格納されます。

  SET x="Red"
  SET y="White"
  SET z="Blue"
  &sql(SELECT $LISTBUILD(:x,,:z),
              $LISTBUILD(:x,'',:z)
       INTO :list1,list2)
  IF SQLCODE=0 {WRITE list1," length ",$LISTLENGTH(list1),!
                WRITE list2," length ",$LISTLENGTH(list2)}
  ELSE {WRITE "Error code:",SQLCODE}

また、$LISTBUILD 式が未定義のときは、対応するリスト要素が未定義の値となります。以下の埋め込み SQL の例では 2要素リストを生成します。リストの先頭要素は "Red" で 2 つ目の要素は未定義値です。

  &sql(SELECT $LISTBUILD('Red',:z)
       INTO :list1)
  IF SQLCODE=0 {WRITE list1," length ",$LISTLENGTH(list1)}
  ELSE {WRITE "Error code:",SQLCODE}

以下の埋め込み SQL の例では、2 要素のリストを生成します。末尾のコンマは、2 つ目の要素が未定義の値を持つことを示します。

  &sql(SELECT $LISTBUILD('Red',)
       INTO :list1)
  IF SQLCODE=0 {WRITE list1," length ",$LISTLENGTH(list1)}
  ELSE {WRITE "Error code:",SQLCODE}

引数を指定しない

引数を指定しないで $LISTBUILD 関数を呼び出すと、データ値が未定義の要素を 1 つ含むリストが返されます。これは、NULL と同じではありません。以下は、“空” のリストを作成する有効な $LISTBUILD 文です。

  &sql(SELECT $LISTBUILD(),
              $LISTBUILD(NULL)
       INTO :list1,:list2)
  IF SQLCODE=0 {
     ZZDUMP list1
     WRITE !,"length ",$LISTLENGTH(list1),!
     ZZDUMP list2
     WRITE !,"length ",$LISTLENGTH(list2),!
  }
  ELSE {WRITE "Error code:",SQLCODE}

以下は、空文字列を含むリスト要素を作成する有効な $LISTBUILD 文です。

  &sql(SELECT $LISTBUILD(''),
              $LISTBUILD(CHAR(0))
       INTO :list1,:list2)
  IF SQLCODE=0 {
     ZZDUMP list1
     WRITE !,"length ",$LISTLENGTH(list1),!
     ZZDUMP list2
     WRITE !,"length ",$LISTLENGTH(list2),!
  }
  ELSE {WRITE "Error code:",SQLCODE}

リストの入れ子

リストの要素自体がリストである場合もあります。例えば、以下の文は 3 つ目の要素が "Walnut,Pecan" という 2 つの要素を持つリストである、3 つの要素を持つリストを作成します。

SELECT $LISTBUILD('Apple','Pear',$LISTBUILD('Walnut','Pecan'))

リストの連結

SQL 連結演算子 (||) を使用して 2 つのリストを連結すると、別のリストが生成されます。例えば、以下の SELECT 項目は同じリスト "A,B,C" を作成します。

SELECT $LISTBUILD('A','B','C') AS List,
  $LISTBUILD('A','B')||$LISTBUILD('C') AS CatList

以下の例で、最初の 2 つの選択項目は同じ 2 つの要素を持つリストを生成し、3 つ目の選択項目は NULL となり (NULL は何と連結しても NULL になります)、4 つ目と 5 つ目の選択項目は同じ 3 つの要素を持つリストを生成します。

SELECT
  $LISTBUILD('A','B') AS List,
  $LISTBUILD('A','B')||'' AS CatEStr,
  $LISTBUILD('A','B')||NULL AS CatNull,
  $LISTBUILD('A','B')||$LISTBUILD('') AS CatEList,
  $LISTBUILD('A','B')||$LISTBUILD(NULL) AS CatNList

Unicode

リスト要素の 1 つ、または複数の文字がワイド (Unicode) 文字の場合、その式のすべての文字がワイド文字として表されます。複数のシステムにまたがる互換性を保証するために、$LISTBUILD はハードウェア・プラットフォームに関係なく、これらのバイトを常に同じ順序で格納します。ワイド文字はバイト文字列として記述されます。詳細は、"ObjectScript リファレンス" の ObjectScript の "$LISTBUILD" 関数を参照してください。