第159章 SQL函数 XMLELEMENT

文章目录

• ​​第159章 SQL函数 XMLELEMENT​​
• ​​大纲​​
• ​​参数​​
• ​​描述​​
• ​​XMLATTRIBUTES 函数​​
• ​​XMLELEMENT 和 XMLFOREST 比较​​
• ​​标点符号值​​
• ​​示例​​

第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 (&) 变成​​&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><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>