金仓数据库KingbaseES 兼容Oracle包dbms_xmlgen的使用(二)
关键字：
KingbaseES、xml、dbms_xmlgen、行标签、根标签、人大金仓、KingbaseES、
一、功能描述
1.1 行标签设置功能
在Kingbase中，兼容Oracle包dbms_xmlgen在生成XML文档的过程中，还提供了设置行标签的功能，实现该功能的语法为：
procedure setRowTag(ctx in ctxHandle, tag in varchar2);
由于该功能为生成XML文档的中间过程，因此，通过一个存储过程实现。设置标签的结果可以通过dbms_xmlgen包中的GETXML或GETXMLTYPE函数返回XML的文档显示。SetRowTag过程的输入参数为上下文句柄ctx和需要设置行标签tag，其中，上下文句柄为sys_refcursor类型，由dbms_xmlgen包中的NEWCONTEXT函数返回。NEWCONTEXT函数的语法为：
function newContext(query in varchar2) return ctxHandle;
function newContext(queryString in sys_refcursor) return ctxHandle;
该函数的功能为通过查询字符串或查询字符串引用游标来创建上下文句柄，该上下文句柄可以用于后续生成XML文档，其间，可以进行行标签等句柄属性的设置，生成个性化的XML文档。SetRowTag过程的另外一个输入参数tag有两种设置方式：NULL和varchar2类型的非NULL值。当输入为NULL值时，行标签不存在；当输入为非NULL值时，行标签设置为该非NULL值。XML标签的命名规则为：
- 标签可以含字母、数字以及其他字符
- 标签不能以标点符号或者数字开始。
- 标签不能包含空格。
1.2 根标签设置功能
在Kingbase中，兼容Oracle包dbms_xmlgen在生成XML文档的过程中，同样提供了设置根标签的功能，实现该功能的语法为：
procedure setRowsetTag(ctx in ctxHandle, tag in varchar2);
和设置行标签的功能同理，设置根标签的功能使用一个存储过程实现，可以通过GETXML或GETXMLTYPE函数显示设置结果。它的输入参数同样为上下文句柄和标签。标签的设置有两种情况：NULL和varchar2类型的非NULL值。当输入NULL值时，根标签不存在；当输入非NULL值时，根标签设置为该非NULL值。标签的设置规则与行标签相同。
1.3 行标签与根标签功能的关联
（1）当通过dbms_xmlgen包中的GETXMLTYPE函数生成XML文档时：
- 如果行标签和根标签均不设置，行标签的默认值为row，根标签的默认值为rowset。
- 如果行标签和根标签均设置为非NULL值，则行标签和根标签设置为该非NULL值。
- 如果行标签设置为NULL值,根标签设置为非NULL值，则行标签不存在，根标签设置为该非NULL值。
- 如果行标签设置为非NULL值,根标签设置为NULL值，则行标签设置为该非NULL值，根标签不存在。
- 如果行标签和根标签均设置为NULL值，则行标签和根标签均不存在。
以上情况的XML文档均可以正常输出。
（2）当通过dbms_xmlgen包中的GETXML函数生成XML文档时：
- 对于通过GETXMLTYPE函数生成XML文档的前三种情况，GETXML函数同理，均可以正常输出XML文档，并且行标签和根标签的设置与其相同。
- 如果行标签设置为非NULL值,根标签设置为NULL值时，分为两种情况：
- 输出的XML文档结果为一行，则根标签不存在，行标签设置为非NULL值，可以正常输出XML文档。
- 输出的XML文档结果多于一行，则输出报错，错误信息显示根标签不存在，无法输出XML文档。
- 如果行标签和根标签均设置为NULL值，同样输出报错，错误信息显示根标签不存在，无法输出XML文档。
（3）在结果显示上，GETXML函数和GETXMLTYPE函数的区别为：GETXML函数输出的XML文档比GETXMLTYPE函数多一个XML版本信息：
<?xml version = "1.0"?>。
二、使用实例
由于使用GETXMLTYPE函数可以展示行标签和根标签设置的多种不同情况，因此，以GETXMLTYPE函数为例，提供一些根标签和行标签设置的典型实例。
（1）首先创建dbms_xmlgen包依赖的kdb_xmltype插件，然后创建dbms_xmlgen插件，接着创建用于查询的表格test1，该表格的结果将通过dbms_xmlgen包转化为XML文档，最后创建用于存放XML文档结果的表格xml_test。
create extension kdb_xmltype;
create extension dbms_xmlgen;
create table test1 (id int, name text);
insert into test1 values(1, 'aaa'), (2, 'bbb'), (3, NULL);
create table xml_test (result xmltype);
（2）当行标签和根标签均设置为非NULL值，则行标签和根标签设置为该非NULL值。
set serveroutput on;
\set SQLTERM /
DECLARE
qryCtx dbms_xmlgen.ctxHandle;
result xmltype;
BEGIN
qryCtx := dbms_xmlgen.newContext('select * from test1');
-- Set the rowset header to be EMPLOYEE
dbms_xmlgen.setRowSetTag(qryCtx, 'Head');
-- Set the row header to be EMPLOYEE
dbms_xmlgen.setRowTag(qryCtx, 'test');
-- Get the result
result := dbms_xmlgen.getXMLtype(qryCtx);
INSERT INTO xml_test VALUES(result);
--Close context
dbms_xmlgen.closeContext(qryCtx);
END;
/
select * from xml_test;
/
输出结果：
result
---------------------------
<Head> +
<test> +
<id>1</id> +
<name>aaa</name>+
</test> +
<test> +
<id>2</id> +
<name>bbb</name>+
</test> +
<test> +
<id>3</id> +
</test> +
</Head> +
(1 row)
（3）当行标签设置为NULL值,根标签设置为非NULL值，则行标签不存在，根标签设置为该非NULL值。
set serveroutput on;
\set SQLTERM /
DECLARE
qryCtx dbms_xmlgen.ctxHandle;
result xmltype;
BEGIN
qryCtx := dbms_xmlgen.newContext('select * from test1');
-- Set the rowset header to be EMPLOYEE
dbms_xmlgen.setRowSetTag(qryCtx, 'Head');
-- Set the row header to be EMPLOYEE
dbms_xmlgen.setRowTag(qryCtx, NULL);
-- Get the result
result := dbms_xmlgen.getXMLtype(qryCtx);
INSERT INTO xml_test VALUES(result);
--Close context
dbms_xmlgen.closeContext(qryCtx);
END;
/
select * from xml_test;
/
输出结果：
result
----------------------------
<Head> +
<id>1</id> +
<name>aaa</name>+
<id>2</id> +
<name>bbb</name>+
<id>3</id> +
</Head> +
(1 row)
（4）当行标签设置为非NULL值,根标签设置为NULL值，则行标签设置为该非NULL值，根标签不存在。
set serveroutput on;
\set SQLTERM /
DECLARE
qryCtx dbms_xmlgen.ctxHandle;
result xmltype;
BEGIN
qryCtx := dbms_xmlgen.newContext('select * from test1');
-- Set the rowset header to be EMPLOYEE
dbms_xmlgen.setRowSetTag(qryCtx, NULL);
-- Set the row header to be EMPLOYEE
dbms_xmlgen.setRowTag(qryCtx, 'test');
-- Get the result
result := dbms_xmlgen.getXMLtype(qryCtx);
INSERT INTO xml_test VALUES(result);
--Close context
dbms_xmlgen.closeContext(qryCtx);
END;
/
select * from xml_test;
/
输出结果：
result
----------------------------
<test> +
<id>1</id> +
<name>aaa</name>+
</test> +
+
<test> +
<id>2</id> +
<name>bbb</name>+
</test> +
+
<test> +
<id>3</id> +
</test> +
+
(1 row)
（5）当行标签和根标签均设置为NULL值，则行标签和根标签均不存在。
set serveroutput on;
\set SQLTERM /
DECLARE
qryCtx dbms_xmlgen.ctxHandle;
result xmltype;
BEGIN
qryCtx := dbms_xmlgen.newContext('select * from test1');
-- Set the rowset header to be EMPLOYEE
dbms_xmlgen.setRowSetTag(qryCtx, NULL);
-- Set the row header to be EMPLOYEE
dbms_xmlgen.setRowTag(qryCtx, NULL);
-- Get the result
result := dbms_xmlgen.getXMLtype(qryCtx);
INSERT INTO xml_test VALUES(result);
--Close context
dbms_xmlgen.closeContext(qryCtx);
END;
/
select * from xml_test;
/
输出结果：
result
-----------------------------
<id>1</id> +
<name>aaa</name> +
<id>2</id> +
<name>bbb</name>+
<id>3</id> +
(1 row)
