更新时间:2024-06-03 GMT+08:00

DBE_XMLGEN

接口介绍

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

表1 DBE_XMLGEN数据类型

类型名称

描述

DBE_XMLGEN.CTXHANDLE

用于存储XML输出状态的数据类型。

  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函数的返回结果。
表2 DBE_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编码或解码操作。按照以下规则进行转换操作。

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