SQL函数 XMLELEMENT

SQL函数 XMLELEMENT

一种格式化 XML 标记标记以包含一个或多个表达式值的函数。

大纲

XMLELEMENT([NAME] tag,expression[,expression])

XMLELEMENT([NAME] tag,XMLATTRIBUTES(expression [AS alias]),expression[,expression])

参数

• NAME tag - XML标记的名称。NAME关键字是可选的。该参数有三种语法形式: NAME "tag", "tag"和NAME。前两者在功能上是相同的。如果指定，标记必须用双引号括起来。标签中的字母大小写保持不变。

XMLELEMENT不执行标记值的验证。然而，XML标准要求有效的标记名不能包含任何字符 !"#$%&'()*+,/;<=>?@[\]^``{|}~，并且不能以"-", "."或数字开头。

如果指定没有标记值的 NAME 关键字， 将提供默认标记值：<Name> ... </Name>。 NAME 关键字不区分大小写；结果标签初始大写。

• expression - 任何有效的表达式。通常是包含要标记的数据值的列的名称。可以指定以逗号分隔的列列表或其他表达式，所有这些都将包含在同一标记中。第一个以逗号分隔的元素可以是 XMLATTRIBUTES 函数。只能指定一个 XMLATTRIBUTES 元素。

描述

XMLELEMENT 函数返回用标记中指定的 XML（或 HTML）标记开始标记和结束标记标记的表达式的值。例如，XMLELEMENT(NAME "Para",Home_City) 返回如下值：<Para>Chicago</Para>。 XMLELEMENT 不能用于生成空元素标记。

XMLELEMENT 可用于引用表或视图的 SELECT 查询或子查询。 XMLELEMENT 可以与普通字段值一起出现在 SELECT 列表中。

tag 参数使用双引号将文字字符串括起来。在几乎所有其他上下文中，SQL 使用单引号将文字字符串括起来；它使用双引号来指定分隔标识符。因此，必须启用分隔标识符支持才能使用此功能；默认情况下启用分隔标识符。

当 SQL代码被指定为用双引号分隔的字符串时，例如在动态 SQL %Prepare() 方法中，必须通过指定两个双引号来转义标记双引号，如下所示：

/// d ##class(PHA.TEST.SQLFunction).XmlElement()
ClassMethod XmlElement()
{
    s myquery = "SELECT XMLELEMENT(""Para"",Name) FROM Sample.Person"
    s tStatement = ##class(%SQL.Statement).%New()
    s qStatus = tStatement.%Prepare(myquery)
}

通常，表达式是查询返回的多行中的字段名称（或包含一个或多个字段名称的表达式）。表达式可以是任何类型的字段。返回指定的表达式值，由开始标记和结束标记括起来，格式如下：

<tag>value</tag>

如果要标记的值是空字符串 ('') 值或 NULL，则返回以下内容：

<tag></tag>

如果表达式包含多个逗号分隔的元素，则将结果连接起来，如下格式所示：

<tag>value1value2</tag>

如果表达式是数据流字段，则使用 <![CDATA[...]]> 在生成的 XML 值中转义流值：

<tag><![CDATA[value]]></tag>

XMLELEMENT 函数可以嵌套。 XMLELEMENT 和 XMLFOREST 函数可以任意组合嵌套。可以使用 XMLCONCAT 连接 XMLELEMENT 函数。但是，XMLELEMENT 不会对整个表达式进行 XML 类型解析。例如，XMLELEMENT 不能在 CASE 语句的子句中执行字符转换（参见下面的示例）。

XMLATTRIBUTES 函数

XMLATTRIBUTES 函数只能在 XMLELEMENT 函数中使用。如果 expression 的元素是 XMLATTRIBUTES 函数，则指定的表达式成为标记的属性，格式如下：

<tag ID='63' >value</tag>

只能在 XMLELEMENT 函数中指定一个 XMLATTRIBUTES 函数。按照惯例，它是第一个表达式元素，尽管它可以是表达式中的任何元素。 用单引号将属性值括起来，并在属性值和标记的右尖括号 (>) 之间插入一个空格。

XMLELEMENT 和 XMLFOREST 比较

• XMLELEMENT 将其表达式列表的值连接到单个标记中。 XMLFOREST 为每个表达式项分配一个单独的标记。
• XMLELEMENT 要求指定标记值。 XMLFOREST 允许采用默认标记值或指定单个标记值。
• XMLELEMENT 允许使用 XMLATTRIBUTES 指定标记属性。 XMLFOREST 不允许指定标记属性。
• XMLELEMENT 返回 NULL 的标记字符串。 XMLFOREST 不返回 NULL 的标记字符串。

标点符号值

如果数据值包含 XML/HTML 可能解释为标记或其他编码的标点字符，则 XMLELEMENT 和 XMLFOREST将此字符转换为相应的编码形式：

• ampersand (&) 变成 &amp;
• apostrophe (') 变成 &apos;
• quotation mark (") 变成 &quot;
• open angle bracket (<) 变成 &lt;
• close angle bracket (>) 变成 &gt;

要在提供的文本字符串中表示撇号，请指定两个撇号，如下例所示：'can''t'。列数据不需要加倍撇号。

示例

以下示例将 Sample.Person 中每个人的 Name 字段值作为普通数据和 xml 标记数据返回：

SELECT Name,
       XMLELEMENT("Para",Name) AS ExportName
     FROM Sample.Person

返回的数据示例行如下所示：

Name                    ExportName
Emerson,Molly N.   <Para>Emerson,Molly N.</Para>

以下示例将 Sample.Person 中每个不同的 Home_City 和 Home_State 对值返回为带有标签 <Address> ... </Address> 的 xml 标记数据。指定一个空格表达式以防止城市名称和州名称的连接：

SELECT DISTINCT 
   XMLELEMENT(NAME "Address",Home_City,' ',Home_State) AS CityState
   FROM Sample.Person
   ORDER BY Home_City

请注意，在上面的示例中，提供了可选的 NAME 关键字。在下一个示例中，提供的 NAME 关键字没有标记值：

SELECT DISTINCT 
   XMLELEMENT(NAME,Home_City,' ',Home_State) AS CityState
   FROM Sample.Person
   ORDER BY Home_City

在这种情况下，将返回相同的数据，但使用默认标记进行标记：<Name> ... </Name>。

以下示例返回字符流数据：

SELECT XMLELEMENT("Para",Name) AS XMLNotes,XMLELEMENT("Para",Notes) AS XMLText
     FROM Sample.Employee

返回的数据示例行如下所示：

XMLName                         XMLText
<Para>Emerson,Molly N.</Para>   <Para><![CDATA[Molly worked at DynaMatix Holdings Inc. as a Marketing Manager]]></Para>

以下示例显示 XMLELEMENT 函数可以嵌套：

SELECT XMLELEMENT("Para",Home_State,
                 XMLELEMENT("Emphasis",Name),Age)
FROM Sample.Person

返回的数据示例行如下所示：

<Para>CA<Emphasis>Emerson,Molly N.</Emphasis>24</Para>

以下示例显示了使用子查询值的 XMLELEMENT 函数：

SELECT XMLELEMENT("Para",Name,DOB, XMLELEMENT("Emphasis",%ID),Age,
   (SELECT XMLELEMENT("NameSub",Name) FROM Sample.Person WHERE %ID=2)) AS ExportName
FROM Sample.Person WHERE %ID=1

返回的数据示例行如下所示：

<Para>Zucherro,Rob F.38405<Emphasis>1</Emphasis>71<NameSub>Quixote,Mark N.</NameSub></Para>

以下示例显示 XMLELEMENT 不能标记 CASE 语句子句中的值：

SELECT XMLELEMENT("Para",Home_State,
    XMLELEMENT("Para",Name),
    CASE WHEN Age < 21 THEN NULL
      ELSE XMLELEMENT("Para",Age) END )
FROM Sample.Person

返回的数据示例行如下所示：

<Para>CA<Para>Emerson,Molly N.</Para>&lt;Para&gt;24&lt;/Para&gt;</Para>

以下查询将 Sample.Person 中的 Name 字段值作为标记中的 XML 标记数据返回，该标记使用 ID 字段作为标记属性：

SELECT XMLELEMENT("Para",XMLATTRIBUTES(%ID),Name) AS ExportName
     FROM Sample.Person

返回的数据示例行如下所示：

ExportName
<Para ID='101' >Emerson,Molly N.</Para>

可以为属性指定别名，如以下示例所示：

SELECT XMLELEMENT("Para",XMLATTRIBUTES(%ID AS ItemKey),Name)
     FROM Sample.Person

<Para ItemKey='101' >Emerson,Molly N.</Para>