# DBE_XMLGEN
#### 接口介绍
DBE_XMLGEN系统包将SQL查询的结果转换为规范的XML格式，并将结果返回。支持的所有接口参见[表2]。
表1DBE_XMLGEN数据类型 
| 类型名称                   | 描述               |
|:---|:---|
| DBE_XMLGEN.CTXHANDLE | 用于存储XML输出状态的数据类型。 |
   
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
- 在同一个session中，context handle最多只允许存在65535个。关闭context handle并不会回收这个数量。
- 分布式中暂不支持connect by语句，因此不可构造newcontextfromhierarchy函数数据。
- 分布式中不允许cursor反向移动，因此restartquery功能不可使用。
- 输出的XML中表字段、类型与用户创建的表字段与类型大小写一致，如果需要大写字段与类型名需要在创建时使用双引号进行指定。
- NEWCONTEXTFROMHIERARCHY初始化时，能够调用SETNULLHANDLING、USENULLATTRIBUTEINDICATOR、SETCONVERTSPECIALCHARS方法设置，但不生效。
- 在不添加ORDER BY进行查询时，查询结果无序，会影响GETXML函数的返回结果。
- 使用EXECUTE DIRECT ON语法执行DBE_XMLGEN包中的函数时，如果GUC参数enable_udf_execute_direct的值为on，则可以执行；如果其值为off，则不可以执行。
 
 表2DBE_XMLGEN 
| 接口名称                                                              | 描述              |
|:---|:---|
| [DBE_XMLGEN.CONVERT]                       | 将输入的字符串进行XML编码或解码操作。                  |
| [DBE_XMLGEN.NEWCONTEXT]                  | 初始化普通context handle。                   |
| [DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY]          | 初始化带有递归元素的context handle。             |
| [DBE_XMLGEN.SETCONVERTSPECIALCHARS]       | 设置输出的XML是否需要进行XML编码。                  |
| [DBE_XMLGEN.SETNULLHANDLING]              | 设置XML中null值如何展示。                    |
| [DBE_XMLGEN.SETROWSETTAG]                | 设置XML根节点名称。                          |
| [DBE_XMLGEN.SETROWTAG]                    | 设置XML中每一行数据的tag名。                     |
| [DBE_XMLGEN.USENULLATTRIBUTEINDICATOR] | 对XML中的null值所在的元素添加xsi:nil="true"属性。 |
| [DBE_XMLGEN.USEITEMTAGSFORCOLL]          | 对数组类型变量所在的元素中添加_ITEM后缀。             |
| [DBE_XMLGEN.GETNUMROWSPROCESSED]            | 查看上一次GETXML或者GETXMLTYPE返回的数据行数。       |
| [DBE_XMLGEN.SETMAXROWS]                     | 设置GETXML操作最大的返回行数。                     |
| [DBE_XMLGEN.SETSKIPROWS]                  | 设置跳过SQL行数。                             |
| [DBE_XMLGEN.RESTARTQUERY]                 | 重启SQL。                               |
| [DBE_XMLGEN.GETXMLTYPE]                  | 返回XMLTYPE类型的XML文本。                    |
| [DBE_XMLGEN.GETXML]                    | 返回CLOB类型的XML文本。                     |
| [DBE_XMLGEN.CLOSECONTEXT]                | 关闭context handle。                     |
   
- DBE_XMLGEN.CONVERT
  将输入的字符串进行XML编码或解码操作。按照以下规则进行转换操作。
  表3XML编码规则 
  | 原始值 | 编码值     |
  |:---|:---|
  | \&   | \& |
  | \<   | \&lt;   |
  | \> | \&gt;   |
  | "      | \&quot;  |
  | '     | '      |
     
  DBE_XMLGEN.CONVERT函数原型：
  ```
  DBE_XMLGEN.CONVERT(XMLSTR IN VARCHAR2, FLAG IN NUMBER := 0) RETURNS VARCHAR2;
  DBE_XMLGEN.CONVERT(XMLCLOB IN CLOB, FLAG IN NUMBER := 0) RETURNS CLOB;
  ```
  表4DBE_XMLGEN.CONVERT接口参数说明 
  | **参数** | **描述**                                                                                                                 |
  |:---|:---|
  | XMLSTR   | 需要转换的XML字符串，VARCHAR2类型。                                                                                              |
  | XMLCLOB | 需要转换的XML字符串， CLOB类型。                                                                                                     |
  | FLAG    | 转码或解码字符串。 0：编码操作。 1：解码操作。 |
     
  示例：
  ```
  -- xml解码
  SELECT DBE_XMLGEN.CONVERT('<foo/>', 1);
   convert 
  ---------
   <foo/>
  (1 row)
  -- xml编码
  SELECT DBE_XMLGEN.CONVERT('<foo><qwe</foo>', 0);
              convert             
  --------------------------------
   &lt;foo&gt;&lt;qwe&lt;/foo&gt;
  (1 row)
  ```
  
- DBE_XMLGEN.NEWCONTEXT
  初始化普通context handle，该context handle只能在一个事务中使用，否则使用[DBE_XMLGEN.RESTARTQUERY]和[DBE_XMLGEN.CLOSECONTEXT]关闭对应context handle时会报错。
  DBE_XMLGEN.NEWCONTEXT函数原型：
  ```
  DBE_XMLGEN.NEWCONTEXT(QUERYSTRING IN VARCHAR2) RETURNS DBE_XMLGEN.CTXHANDLE;
  DBE_XMLGEN.NEWCONTEXT(QUERYSTRING IN SYS_REFCURSOR) RETURNS DBE_XMLGEN.CTXHANDLE;
  ```
  表5DBE_XMLGEN.NEWCONTEXT接口参数说明 
  | **参数**    | **描述**                           |
  |:---|:---|
  | QUERYSTRING | 用于生成XML的查询SQL语句或SYS_REFCURSOR。 |
     
  
- DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY
  初始化带有递归元素的context handle。数据格式要求为两列，第一列为NUMERIC类型，第二列为XML或XMLTYPE类型。通常情况下由connect by语句生成，第一列指定生成level。由于分布式不支持connect by语句，因此该函数用例无法构造。
  ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  生成的xml层级嵌套不允许超过5000万层。
  DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY函数原型：
  ```
  DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY(QUERYSTRING IN VARCHAR2);
  ```
  表6DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY接口参数说明 
  | **参数**   | **描述**                |
  |:---|:---|
  | QUERYSTRING | 需要转换的XML字符串，VARCHAR2类型。 |
     
  
- DBE_XMLGEN.SETCONVERTSPECIALCHARS
  设置输出的XML是否需要进行XML编码。取消xml编码可能会存在xml注入问题，如果出于性能考虑且可以保证xml是安全的情况下可以不进行xml编码。
  DBE_XMLGEN.SETCONVERTSPECIALCHARS函数原型：
  ```
  DBE_XMLGEN.SETCONVERTSPECIALCHARS(CTX IN DBE_XMLGEN.CTXHANDLE, CONV IN BOOLEAN);
  ```
  表7DBE_XMLGEN.SETCONVERTSPECIALCHARS接口参数说明 
  | **参数** | **描述**                                                                                                                                                                                                                                                                                                 |
  |:---|:---|
  | CTX   | context handle。                                                                                                                                                                                                                                                                                        |
  | CONV | 是否需要对输出的XML进行XML编码。 - true：进行XML编码。  - false：不进行XML编码。   |
     
  
- DBE_XMLGEN.SETNULLHANDLING
  设置XML中null值如何展示。
  DBE_XMLGEN.SETNULLHANDLING函数原型：
  ```
  DBE_XMLGEN.SETNULLHANDLING(CTX IN DBE_XMLGEN.CTXHANDLE, FLAG IN NUMBER := 0);
  ```
  表8DBE_XMLGEN.SETNULLHANDLING接口参数说明 
  | **参数** | **描述**                                                                                                                                                                                                                                                                                                                                                                                                          |
  |:---|:---|
  | CTX   | context handle。                                                                                                                                                                                                                                                                                                                                                                                                    |
  | FLAG  | NULL值展示格式。 - 0：不展示元素。  - 1：元素上添加 xsi:nil="true" 属性。  - 2：展示自闭合元素。   |
     
  
- DBE_XMLGEN.SETROWSETTAG
  设置XML根节点名称。
  DBE_XMLGEN.SETROWSETTAG函数原型：
  ```
  DBE_XMLGEN.SETROWSETTAG(CTX IN DBE_XMLGEN.CTXHANDLE, ROWSETTAGNAME IN VARCHAR2);
  ```
  表9DBE_XMLGEN.SETROWSETTAG接口参数说明 
  | **参数**         | **描述**        |
  |:---|:---|
  | CTX            | context handle。 |
  | ROWSETTAGNAME | XML根节点名称。    |
     
  
- DBE_XMLGEN.SETROWTAG
  设置XML中每一行数据的tag名。
  DBE_XMLGEN.SETROWTAG函数原型：
  ```
  DBE_XMLGEN.SETROWTAG(CTX IN DBE_XMLGEN.CTXHANDLE, ROWTAGNAME IN VARCHAR2);
  ```
  表10DBE_XMLGEN.SETROWTAG接口参数说明 
  | **参数**   | **描述**            |
  |:---|:---|
  | CTX       | context handle。 |
  | ROWTAGNAME | 每一行数据的tag名。       |
     
  
- DBE_XMLGEN.USENULLATTRIBUTEINDICATOR
  对XML中的null值所在的元素添加xsi:nil="true"属性。
  DBE_XMLGEN.USENULLATTRIBUTEINDICATOR函数原型：
  ```
  DBE_XMLGEN.USENULLATTRIBUTEINDICATOR(CTX IN DBE_XMLGEN.CTXHANDLE, ATTRIND IN BOOLEAN);
  ```
  表11DBE_XMLGEN.USENULLATTRIBUTEINDICATOR接口参数说明 
  | **参数**   | **描述**            |
  |:---|:---|
  | CTX      | context handle。 |
  | ATTRIND | 无意义。              |
     
  
- DBE_XMLGEN.USEITEMTAGSFORCOLL
  对数组类型变量所在的元素中添加_ITEM后缀。
  DBE_XMLGEN.USEITEMTAGSFORCOLL函数原型：
  ```
  DBE_XMLGEN.USEITEMTAGSFORCOLL(CTX IN DBE_XMLGEN.CTXHANDLE);
  ```
  表12DBE_XMLGEN.USEITEMTAGSFORCOLL接口参数说明 
  | **参数** | **描述**        |
  |:---|:---|
  | CTX     | context handle。 |
     
  示例：
  ```
  -- 预置数据
  CREATE TABLE test_for_array(idd number, id INT[]);
  INSERT INTO test_for_array VALUES(1, ARRAY[1,2,3]);
  SELECT DBE_XMLGEN.GETXML('SELECT * from test_for_array');
  -- 数组类型添加_ITEM后缀
  DECLARE
  qryctx DBE_XMLGEN.CTXHANDLE;
  result CLOB;
  BEGIN
  qryctx := DBE_XMLGEN.NEWCONTEXT('SELECT id from test_for_array');
  DBE_XMLGEN.useItemTagsForColl(qryctx);
  result:=DBE_XMLGEN.GETXML(qryctx);
  DBE_XMLGEN.CLOSECONTEXT(qryctx);
  DBE_OUTPUT.PUT_LINE(result);
  END;
  /
  <?xml version="1.0"?>
  <ROWSET>
  <ROW>
    <id>
      <int4_ITEM>1</int4_ITEM>
      <int4_ITEM>2</int4_ITEM>
      <int4_ITEM>3</int4_ITEM>
    </id>
  </ROW>
  </ROWSET>
  ANONYMOUS BLOCK EXECUTE
  DROP TABLE test_for_array;
  ```
  
- DBE_XMLGEN.GETNUMROWSPROCESSED
  查看上一次GETXML或者GETXMLTYPE返回的数据行数。
  DBE_XMLGEN.GETNUMROWSPROCESSED函数原型：
  ```
  DBE_XMLGEN.GETNUMROWSPROCESSED(CTX IN DBE_XMLGEN.CTXHANDLE);
  ```
  表13DBE_XMLGEN.GETNUMROWSPROCESSED接口参数说明 
  | **参数** | **描述**        |
  |:---|:---|
  | CTX       | context handle。 |
     
  
- DBE_XMLGEN.SETMAXROWS
  设置每一次GETXML最大的返回行数。
  DBE_XMLGEN.SETMAXROWS函数原型：
  ```
  DBE_XMLGEN.SETMAXROWS(CTX IN DBE_XMLGEN.CTXHANDLE, MAXROWS IN NUMBER);
  ```
  表14DBE_XMLGEN.SETMAXROWS接口参数说明 
  | **参数** | **描述**            |
  |:---|:---|
  | CTX   | context handle。    |
  | MAXROWS | 每一次GETXML最大的返回行数。 |
     
  
- DBE_XMLGEN.SETSKIPROWS
  设置跳过SQL行数。
  DBE_XMLGEN.SETSKIPROWS函数原型：
  ```
  DBE_XMLGEN.SETSKIPROWS(CTX IN DBE_XMLGEN.CTXHANDLE, SKIPROWS IN NUMBER);
  ```
  表15DBE_XMLGEN.SETSKIPROWS接口参数说明 
  | **参数**      | **描述**          |
  |:---|:---|
  | CTX         | context handle。 |
  | SKIPROWS | 跳过SQL的头部行数。   |
     
  
- DBE_XMLGEN.RESTARTQUERY
  重启SQL。分布式不支持该接口。
  DBE_XMLGEN.RESTARTQUERY函数原型：
  ```
  DBE_XMLGEN.RESTARTQUERY(CTX IN DBE_XMLGEN.CTXHANDLE);
  ```
  表16DBE_XMLGEN.RESTARTQUERY接口参数说明 
  | **参数** | **描述**         |
  |:---|:---|
  | CTX      | context handle。 |
     
  
- DBE_XMLGEN.GETXMLTYPE
  返回XMLTYPE类型的XML文本。
  DBE_XMLGEN.GETXMLTYPE函数原型：
  ```
  DBE_XMLGEN.GETXMLTYPE(SQLQUERY IN VARCHAR2, DTDORSCHEMA IN NUMBER := 0) RETURNS XMLTYPE;
  DBE_XMLGEN.GETXMLTYPE(CTX IN DBE_XMLGEN.CTXHANDLE, DTDORSCHEMA IN NUMBER := 0) RETURNS XMLTYPE;
  ```
  表17DBE_XMLGEN.GETXMLTYPE接口参数说明 
  | **参数**        | **描述**          |
  |:---|:---|
  | SQLQUERY       | 需要转换成XML的查询SQL。 |
  | DTDORSCHEMA | 无意义            |
  | CTX           | context handle。    |
     
  
- DBE_XMLGEN.GETXML
  返回CLOB类型的XML文本。
  DBE_XMLGEN.GETXML函数原型：
  ```
  DBE_XMLGEN.GETXML(SQLQUERY IN VARCHAR2, DTDORSCHEMA IN NUMBER := 0) RETURNS CLOB;
  DBE_XMLGEN.GETXML(CTX IN DBE_XMLGEN.CTXHANDLE, DTDORSCHEMA IN NUMBER := 0) RETURNS CLOB;
  DBE_XMLGEN.GETXML(CTX IN DBE_XMLGEN.CTXHANDLE, TMPCLOB INOUT CLOB, DTDORSCHEMA IN NUMBER := 0);
  ```
  表18DBE_XMLGEN.GETXML接口参数说明 
  | **参数**   | **描述**           |
  |:---|:---|
  | SQLQUERY    | 需要转换成XML的查询SQL。    |
  | DTDORSCHEMA | 无意义                |
  | CTX        | context handle。    |
  | TMPCLOB     | 用于保存输出的XML的CLOB变量。 |
     
  
- DBE_XMLGEN.CLOSECONTEXT
  关闭context handle。
  DBE_XMLGEN.CLOSECONTEXT函数原型：
  ```
  DBE_XMLGEN.CLOSECONTEXT(CTX IN DBE_XMLGEN.CTXHANDLE);
  ```
  表19DBE_XMLGEN.CLOSECONTEXT接口参数说明 
  | **参数** | **描述**          |
  |:---|:---|
  | CTX  | context handle。 |
     
  示例：
  ```
  CREATE TABLE IF NOT EXISTS department(department_id NUMBER, department_name VARCHAR2(30), manager NUMBER, location NUMBER);
  INSERT INTO department VALUES(10, 'administrator', 200, 1700);
  INSERT INTO department VALUES(11, 'aaa', 200, 1700);
  INSERT INTO department VALUES(12, 'bbb', 300, 1600);
  INSERT INTO department VALUES(13, 'ccc', 400, 1600);
  INSERT INTO department VALUES(14, 'aaa</row><a>asd</a><row>', 400, 1600);
  INSERT INTO department VALUES(15, NULL, 500,1600);
  INSERT INTO department VALUES(16, '!@#$%^&*()+-=<>/\"a3_啊', 400, 1600);
  -- 关闭context
  DECLARE
      qryctx DBE_XMLGEN.CTXHANDLE;
      result CLOB;
  BEGIN
  qryctx := DBE_XMLGEN.NEWCONTEXT('SELECT * from department where department_id=14');
  DBE_XMLGEN.SETCONVERTSPECIALCHARS(qryctx, false);
  result:=DBE_XMLGEN.GETXML(qryctx);
  DBE_XMLGEN.CLOSECONTEXT(qryctx);
  DBE_OUTPUT.PUT_LINE(result);
  END;
  /
  <?xml version="1.0"?>
  <ROWSET>
  <ROW>
    <department_id>14</department_id>
    <department_name>aaa</row><a>asd</a><row></department_name>
    <manager>400</manager>
    <location>1600</location>
  </ROW>
  </ROWSET>
  ANONYMOUS BLOCK EXECUTE
  DROP TABLE department;
  ```