DBE_XMLGEN

接口介绍

DBE_XMLGEN系统包将SQL查询的结果转换为规范的XML格式，并将结果返回。支持的所有接口参见表2 DBE_XMLGEN。

1. 在同一个session中，context handle最多只允许存在65535个。关闭context handle并不会回收这个数量。
2. 分布式中暂不支持connect by语句，因此不可构造newcontextfromhierarchy函数数据。
3. 分布式中不允许cursor反向移动，因此restartquery功能不可使用。
4. 输出的XML中表字段、类型与用户创建的表字段与类型大小写一致，如果需要大写字段与类型名需要在创建时使用双引号进行指定。
5. NEWCONTEXTFROMHIERARCHY初始化时，使用SETNULLHANDLING、USENULLATTRIBUTEINDICATOR、SETCONVERTSPECIALCHARS方法设置但不生效。
6. 在不添加ORDER BY进行查询时，查询结果无序，会影响GETXML函数的返回结果。

• DBE_XMLGEN.CONVERT

  将输入的字符串进行XML编码或解码操作。按照以下规则进行转换操作。

  表3 XML编码规则

  原始值	编码值
  &	&
  <	&lt;
  >	&gt;
  "	&quot;
  '	&apos;

  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;

  表4 DBE_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。

  DBE_XMLGEN.NEWCONTEXT函数原型：

  DBE_XMLGEN.NEWCONTEXT(QUERYSTRING IN VARCHAR2) RETURNS DBE_XMLGEN.CTXHANDLE;
  DBE_XMLGEN.NEWCONTEXT(QUERYSTRING IN SYS_REFCURSOR) RETURNS DBE_XMLGEN.CTXHANDLE;

  表5 DBE_XMLGEN.NEWCONTEXT接口参数说明

  参数	描述
  QUERYSTRING	用于生成XML的查询SQL语句或SYS_REFCURSOR。

• DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY

  初始化带有递归元素的context handle。数据格式要求为两列，第一列为NUMERIC类型，第二列为XML或XMLTYPE类型。通常情况下由connect by语句生成，第一列指定生成level。由于分布式不支持connect by语句，因此该函数用例无法构造。

  

  生成的xml层级嵌套不允许超过5000万层。

  DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY函数原型：

  DBE_XMLGEN.NEWCONTEXTFROMHIERARCHY(QUERYSTRING IN VARCHAR2);

  表6 DBE_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);

  表7 DBE_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);

  表8 DBE_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);

  表9 DBE_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);

  表10 DBE_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);

  表11 DBE_XMLGEN.USENULLATTRIBUTEINDICATOR接口参数说明

  参数	描述
  CTX	context handle。
  ATTRIND	无意义。

• DBE_XMLGEN.USEITEMTAGSFORCOLL

  对数组类型变量所在的元素中添加_item后缀。

  DBE_XMLGEN.USEITEMTAGSFORCOLL函数原型：

  DBE_XMLGEN.USEITEMTAGSFORCOLL(CTX IN DBE_XMLGEN.CTXHANDLE);

  表12 DBE_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>

• DBE_XMLGEN.GETNUMROWSPROCESSED

  查看上一次GETXML或者GETXMLTYPE返回的数据行数。

  DBE_XMLGEN.GETNUMROWSPROCESSED函数原型：

  DBE_XMLGEN.GETNUMROWSPROCESSED(CTX IN DBE_XMLGEN.CTXHANDLE);

  表13 DBE_XMLGEN.GETNUMROWSPROCESSED接口参数说明

  参数	描述
  CTX	context handle。

• DBE_XMLGEN.SETMAXROWS

  设置每一次GETXML最大的返回行数。

  DBE_XMLGEN.SETMAXROWS函数原型：

  DBE_XMLGEN.SETMAXROWS(CTX IN DBE_XMLGEN.CTXHANDLE, MAXROWS IN NUMBER);

  表14 DBE_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);

  表15 DBE_XMLGEN.SETSKIPROWS接口参数说明

  参数	描述
  CTX	context handle。
  SKIPROWS	跳过SQL的头部行数。

• DBE_XMLGEN.RESTARTQUERY

  重启SQL。分布式不支持该接口。

  DBE_XMLGEN.RESTARTQUERY函数原型：

  DBE_XMLGEN.RESTARTQUERY(CTX IN DBE_XMLGEN.CTXHANDLE);

  表16 DBE_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;

  表17 DBE_XMLGEN.GETXMLTYP接口参数说明

  参数	描述
  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);

  表18 DBE_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);

  表19 DBE_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>