第159章 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 (&) 变成 &
apostrophe (') 变成 '
quotation mark (") 变成 "
open angle bracket (<) 变成 <
close angle bracket (>) 变成 >
要在提供的文本字符串中表示撇号，请指定两个撇号，如下例所示：'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><Para>24</Para></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>