第七十九章 SQL函数 $LIST（一）

返回列表中元素的列表函数。

大纲

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

参数

list - 计算结果为有效列表的表达式。列表是包含一个或多个元素的编码字符串。可以使用 SQL 或 ObjectScript 的 $LISTBUILD 或 $LISTFROMSTRING 函数创建列表。可以使用 SQL 或 ObjectScript $LIST 函数从现有列表中提取列表。
position - 可选 - 指定列表中的起始位置。计算结果为整数的表达式。
end - 可选 - 指定列表中的结束位置。计算结果为整数的表达式。

描述

$LIST 从列表中返回元素。返回的元素取决于使用的参数。
- $LIST(list) 将列表中的第一个元素作为文本字符串返回。
- $LIST(list,position) 将指定位置指示的元素作为文本字符串返回。位置参数必须计算为整数。
- $LIST(list,position,end) 返回一个“子列表”（编码的列表字符串），其中包含从指定开始位置到指定结束位置的列表元素。

此函数返回 VARCHAR 类型的数据。

参数

list

包含一个或多个元素的编码字符串。可以使用 SQL $LISTBUILD 函数或 ObjectScript $LISTBUILD 函数创建列表。可以使用 SQL $LISTFROMSTRING 函数或 ObjectScript $LISTFROMSTRING 函数将分隔字符串转换为列表。您可以使用 SQL $LIST 函数或 ObjectScript $LIST 函数从现有列表中提取列表。

position

要返回的列表元素的位置。列表元素从 1 开始计数。如果省略 position，则返回第一个元素。如果 position 的值是 0 或大于列表中的元素数， SQL 不会返回值。如果 position 的值为负一 (–1)，则 $LIST 返回列表中的最后一个元素。

/// d ##class(PHA.TEST.SQLCommand).Li()
ClassMethod Li()
{
   s a = $lb("Red", "Blue", "Green")
    &sql(
        SELECT $LIST(:a,-1)
        INTO :b 
    )
    if SQLCODE '= 0 {
        w !,"Error code ",SQLCODE 
    } else {
        w !,"The last element is ",b 
    }
}

DHC-APP>d ##class(PHA.TEST.SQLCommand).Li()

The last element is Green

如果指定了 end 参数，则 position 指定元素范围中的第一个元素。即使只返回一个元素（当位置和结束是相同的数字时），该元素也会作为编码列表字符串返回。因此，$LIST(x,2)（将元素作为普通字符串返回）与 $LIST(x,2,2)（将元素作为编码列表字符串返回）不同。

end

元素范围内最后一个元素的位置。必须指定位置才能指定结束。当指定 end 时，返回的值是一个编码的列表字符串。由于这种编码，此类字符串只能由其他 $LIST 函数处理。

如果 end 的值为：

大于位置，则返回包含元素列表的编码字符串。
等于位置，返回一个包含一个元素的编码字符串。
小于位置，不返回值。
大于列表中的元素个数，相当于指定列表中的最后一个元素。
负一 (–1)，相当于指定列表中的最后一个元素。

指定 end 时，可以指定零 (0) 的位置值。在这种情况下，0 等于 1。

使用列表

一个表可以包含一个或多个列表字段。因为列表是编码字符串，所以这些字段可以定义为数据类型 %List (%Library.List) 或数据类型 VARCHAR。数据类型 %List 的字段可以标识为 CType（客户端数据类型）= 6。

数据类型在插入或更新时不限制字段的允许值。因此，用户必须确保 List 字段中的所有数据值都是 List 编码字符串。如果 SQL $LIST函数遇到未编码的字符串数据值，则 SELECT 操作将失败并返回带有 %msg 的 SQLCODE -400，如下所示：Unexpected error occurred: <LIST>%0AmBuncommitted+1^%sqlcq.USER.cls61.1.

可以通过使用主变量或通过在 SQL 中指定 $LISTBUILD 将列表提供给 SQL $LIST 函数。两者都显示在以下嵌入式 SQL 示例中：

/// d ##class(PHA.TEST.SQLCommand).Li1()
ClassMethod Li1()
{
    s mylist = $lb("Red", "Blue", "Green")
    &sql(
        SELECT $LIST(:mylist, 2), $LIST($LISTBUILD('Red', 'Blue', 'Green'), 3)
        INTO :a,:b 
    )
    if SQLCODE '= 0 {
        w !,"Error code ",SQLCODE 
    } else {
        w !,"The host varable list element is ",a,!
        w !,"The SQL $LISTBUILD list element is ",b,! 
    }
}

DHC-APP>d ##class(PHA.TEST.SQLCommand).Li1()

The host varable list element is Blue

The SQL $LISTBUILD list element is Green

可以使用 $LIST 函数从另一个列表中提取列表：

/// d ##class(PHA.TEST.SQLCommand).Li2()
ClassMethod Li2()
{
    s a = $lb("Red", "Blue", "Green")
    &sql(
        SELECT $LIST(:a,2, 3)
        INTO :b 
    )
    if SQLCODE '= 0 {
        w !,"Error code ",SQLCODE 
    } else {
        &sql(
            SELECT $LIST(:b,1)
            INTO :c 
        )
        if SQLCODE '= 0 {
            w !,"Error code ",SQLCODE 
        } else {
            w !,"The element returned is ",c }
    }
}

DHC-APP>d ##class(PHA.TEST.SQLCommand).Li2()

The element returned is Blue

在以下嵌入式 SQL 示例中，subList 不是有效的列表参数，因为它是作为普通字符串返回的单个元素，而不是编码列表字符串。只有 $LIST 的三参数形式返回编码列表字符串。在这种情况下，会生成 SQLCODE -400 致命错误：

/// d ##class(PHA.TEST.SQLCommand).Li3()
ClassMethod Li3()
{
    s a = $lb("Red","Blue","Green")
    &sql(
        SELECT $LIST(:a,2)
        INTO :sublist 
    )
    if SQLCODE '= 0 {
        w !,"Error code ",SQLCODE 
    } else {
        &sql(
            SELECT $LIST(:sublist,1)
            INTO :c 
        )
        if SQLCODE '= 0 {
            w !,"Error code ",SQLCODE 
        } else {
            w !,"The sublist is"
            ZZDUMP c   ; Variable not set 
        }
    }
}

DHC-APP>d ##class(PHA.TEST.SQLCommand).Li3()

Error code -400