# DBE_XMLPARSER
#### 接口介绍
DBE_XMLPARSER用于将xml字符串反序列化，将存储xml文档的字符串转换为document节点。高级包DBE_XMLPARSER支持的所有接口请参见[表1]。
XMLPARSER数据类型可以被用来存储XMLPARSER数据，存储Xmlparser的数量上限为16777215。XMLPARSER数据类型能够根据输入的字符串解析建立domdocument节点，高级包还提供相应的set、get型接口，对解析过程的约束属性进行操作。
DBE_XMLPARSER高级包在字符集设置为SQL_ASCII的数据库内使用的情况下，传入超出ASCII范围的字符，会导致报错。
DBE_XMLPARSER高级包只支持O兼容模式。
表1DBE_XMLPARSER接口参数说明
| 接口名称 | 描述 |
|:---|:---|
| [DBE_XMLPARSER.FREEPARSER] | 释放PARSER。 |
| [DBE_XMLPARSER.GETDOCUMENT] | 获取解析的document节点。 |
| [DBE_XMLPARSER.GETVALIDATIONMODE] | 获取validate属性。 |
| [DBE_XMLPARSER.NEWPARSER] | 新建PARSER实例。 |
| [DBE_XMLPARSER.PARSEBUFFER] | 解析VARCHAR字符串。 |
| [DBE_XMLPARSER.PARSECLOB] | 解析CLOB字符串。 |
| [DBE_XMLPARSER.SETVALIDATIONMODE] | 设置validate属性。 |
- DBE_XMLPARSER.FREEPARSER
释放给定的PARSER对象。
DBE_XMLPARSER.FREEPARSER的存储过程原型为：
```
DBE_XMLPARSER.FREEPARSER (
p IN parser);
```
表2DBE_XMLPARSER.FREEPARSER接口参数说明
| **参数** | **描述** |
|:---|:---|
| p | 指定的parser类型对象。 |
示例：
```
-- 新建parser ，随后释放。
DECLARE
l_parser dbe_xmlparser.parser;
BEGIN
l_parser := dbe_xmlparser.newparser;
-- 直接释放l_parser实例
dbe_xmlparser.freeparser(l_parser);
END;
/
```
执行结果：执行成功
- DBE_XMLPARSER.GETDOCUMENT
GETDOCUMENT返回PARSER构建的DOM树文档的根节点。只有在解析文档后，才能调用此函数。
DBE_XMLPARSER.GETDOCUMENT的函数原型为：
```
DBE_XMLPARSER.GETDOCUMENT (
p IN parser)
RETURN DOMDocument;
```
表3DBE_XMLPARSER.GETDOCUMENT接口参数说明
| **参数** | **描述** |
|:---|:---|
| p | 指定的parser类型对象。 |
- GETDOCUMENT函数无传入参数，报错。
- GETDOCUMENT函数参数parser传入为空，返回null。
- GETDOCUMENT函数传入的parser还没有解析文档，返回null。
示例：
```
-- 新建parser解析字符串，GETDOCUMENT获取文档打印出来。
DECLARE
l_parser dbe_xmlparser.parser;
l_doc dbe_xmldom.domdocument;
buffer varchar2 :=
'
Tove
Jani
Reminder
Donot forget me this weekend!
';
buffer2 varchar2;
BEGIN
l_parser := dbe_xmlparser.newparser;
dbe_xmlparser.PARSEBUFFER(l_parser, buffer);
l_doc := dbe_xmlparser.getdocument(l_parser);
-- l_parser解析字符串，通过GETDOCUMENT获取domdocument节点
dbe_xmldom.writetobuffer(l_doc, buffer2);
RAISE NOTICE '%', buffer2;
--将l_doc中的内容打印出来
dbe_xmlparser.freeparser(l_parser);
dbe_xmldom.freedocument(l_doc);
END;
/
```
执行结果：
```
NOTICE:
Tove
Jani
Reminder
Donot forget me this weekend!
```
- DBE_XMLPARSER.GETVALIDATIONMODE
获取给定Parser的解析验证模式。如果DTD验证开启返回TRUE，否则返回FALSE。
DBE_XMLPARSER.GETVALIDATIONMODE的函数原型为：
```
DBE_XMLPARSER.GETVALIDATIONMODE (
p IN parser)
RETURN BOOLEAN;
```
表4DBE_XMLPARSER.GETVALIDATIONMODE接口参数说明
| **参数** | **描述** |
|:---|:---|
| p | 指定的parser类型对象。 |
示例：
```
-- 新建parser,通过GETVALIDATIONMODE获取parser解析验证模式是否打开。
DECLARE
l_parser dbe_xmlparser.parser;
BEGIN
l_parser := dbe_xmlparser.newparser();
if (dbe_xmlparser.GETVALIDATIONMODE(l_parser) = true) then
RAISE NOTICE 'validation';
else
RAISE NOTICE 'no validation';
end if;
dbe_xmlparser.freeparser(l_parser);
END;
/
```
执行结果：
```
NOTICE: validation
```
- DBE_XMLPARSER.NEWPARSER
新建Parser对象，返回一个新的解析器实例。
DBE_XMLPARSER.NEWPARSER的函数原型为：
```
DBE_XMLPARSER.NEWPARSER
RETURN Parser;
```
示例：
```
-- 新建parser 解析字符串，随后释放。
DECLARE
-- Create a parser.
l_parser dbe_xmlparser.parser;
l_doc dbe_xmldom.domdocument;
buffer varchar2(1000) :=
'
Tove
Jani
Reminder
Donot forget me this weekend!
';
buffer2 varchar2(1000);
BEGIN
l_parser := dbe_xmlparser.newparser;
-- Parse the document and create a new DOM document.
dbe_xmlparser.PARSEBUFFER(l_parser, buffer);
dbe_xmlparser.freeparser(l_parser);
END;
/
```
执行结果：执行成功
- DBE_XMLPARSER.PARSEBUFFER
PARSEBFER解析存储在字符串中的XML文档。
DBE_XMLPARSER.PARSEBUFFER的存储过程原型为：
```
DBE_XMLPARSER.PARSEBUFFER (
p IN parser,
doc IN VARCHAR2);
```
表5DBE_XMLPARSER.PARSEBUFFER接口参数说明
| **参数** | **描述** |
|:---|:---|
| p | 指定的parser类型对象。 |
| doc | 存储XML文档的字符串。 |
- PARSEBUFFER函数能够解析的字符串最大长度为32767，超过最大长度解析报错。
- 与A数据库差异：字符串encoding只支持UTF-8；version字段只支持1.0，1.0-1.9解析警告但正常执行，1.9以上报错。
- 与A数据库DTD校验差异：
- !ATTLIST to type (CHECK\|check\|Check) "Ch..."将报错，因默认值"Ch..."不属于括号中枚举值，而A数据库不报错。
- \...... \&Baidu;\&writer将报错，因区分字母大小写，Baidu无法与baidu对应，而A数据库不报错。
- 与A数据库命名空间校验差异：解析未声明的命名空间标签正常执行，而A数据库会报错。
- 与A数据库xml预定义实体解析差异：'\"会被解析转译为字符'"，而A数据库中预定义实体统一都没有转译为字符。
示例：
```
-- 新建parser，PARSEBUFFER解析字符串，获取文档打印出来。
DECLARE
l_parser dbe_xmlparser.parser;
l_doc dbe_xmldom.domdocument;
buffer varchar2 :=
'
Tove
Jani
Reminder
Donot forget me this weekend!
';
buffer2 varchar2;
BEGIN
l_parser := dbe_xmlparser.newparser;
dbe_xmlparser.PARSEBUFFER(l_parser, buffer);
l_doc := dbe_xmlparser.getdocument(l_parser);
dbe_xmldom.writetobuffer(l_doc, buffer2);
RAISE NOTICE '%', buffer2;
dbe_xmlparser.freeparser(l_parser);
dbe_xmldom.freedocument(l_doc);
END;
/
```
执行结果：
```
NOTICE:
Tove
Jani
Reminder
Donot forget me this weekend!
```
- DBE_XMLPARSER.PARSECLOB
PARSECLOB解析存储在Clob中的XML文档。
DBE_XMLPARSER.PARSECLOB的存储过程原型为：
```
DBE_XMLPARSER.PARSECLOB (
p IN parser,
doc IN CLOB);
```
表6DBE_XMLPARSER.PARSECLOB接口参数说明
| **参数** | **描述** |
|:---|:---|
| p | 指定的parser类型对象 |
| doc | 存储XML文档的clob字符串 |
- PARSECLOB不支持解析大于等于2GB的clob。
- 与A数据库差异：字符串encoding只支持UTF-8；version字段只支持1.0，1.0-1.9解析警告但正常执行，1.9以上报错。
- 与A数据库DTD校验差异：
- !ATTLIST to type (CHECK\|check\|Check) "Ch..."将报错，因默认值"Ch..."不属于括号中枚举值，而A数据库不报错。
- \...... \&Baidu;\&writer将报错，因区分字母大小写，Baidu无法与baidu对应，而A数据库不报错。
- 与A数据库命名空间校验差异：解析未声明的命名空间标签正常执行，而A数据库会报错。
- 与A数据库xml预定义实体解析差异：'\"会被解析转译为字符'"，而A数据库中预定义实体统一都没有转译为字符。
示例：
```
-- 新建parser，parseclob解析字符串，获取文档打印出来。
DECLARE
l_clob clob :=
'
Tove
Jani
Reminder
this weekend!
';
-- Create a parser.
l_parser dbe_xmlparser.parser;
l_doc dbe_xmldom.domdocument;
buffer varchar2(1000);
BEGIN
l_parser := dbe_xmlparser.newparser;
-- Parse the document and create a new DOM document.
dbe_xmlparser.parseclob(l_parser, l_clob);
l_doc := dbe_xmlparser.getdocument(l_parser);
dbe_xmldom.writetobuffer(l_doc, buffer);
RAISE NOTICE '%',buffer;
dbe_xmlparser.freeparser(l_parser);
dbe_xmldom.freedocument(l_doc);
END;
/
```
执行结果：
```
NOTICE:
Tove
Jani
Reminder
this weekend!
```
- DBE_XMLPARSER.SETVALIDATIONMODE
设置给定Parser的解析验证模式。
DBE_XMLPARSER.SETVALIDATIONMODE的存储过程原型为：
```
DBE_XMLPARSER.SETVALIDATIONMODE(
p IN parser)
yes IN BOOLEAN);
```
表7DBE_XMLPARSER.SETVALIDATIONMODE接口参数说明
| **参数** | **描述** |
|:---|:---|
| p | 指定的parser类型对象。 |
| yes | 要设置的模式： - TRUE：开启DTD验证。 - FALSE：不开启验证 |
- SETVALIDATIONMODE函数yes传入为空，不改变parser的解析验证模式。
- parser初始化默认为开启DTD验证模式。
示例1：
```
-- 新建parser，设置的待解析xml字符串同DTD格式不匹配。
-- setValidationMode设置为false可以正常解析,设置为true后解析报错。
DECLARE
l_clob clob :=
'
]>
African Coffee Table
80
120
';
l_parser dbe_xmlparser.parser;
l_doc dbe_xmldom.domdocument;
buffer varchar2(1000);
BEGIN
l_parser := dbe_xmlparser.newparser;
-- 设为 false，去解析
dbe_xmlparser.setValidationMode(l_parser, false);
dbe_xmlparser.parseclob(l_parser, l_clob);
l_doc := dbe_xmlparser.getdocument(l_parser);
dbe_xmldom.writetobuffer(l_doc, buffer);
RAISE NOTICE '%', buffer;
dbe_xmlparser.freeparser(l_parser);
dbe_xmldom.freedocument(l_doc);
END;
/
```
执行结果：
```
NOTICE:
]>
African Coffee Table
80
120
```
示例2：
```
-- 新建parser，设置的待解析xml字符串同DTD格式不匹配。
-- setValidationMode设置为true后解析报错。
DECLARE
l_clob clob :=
'
]>
African Coffee Table
80
120
';
l_parser dbe_xmlparser.parser;
l_doc dbe_xmldom.domdocument;
buffer varchar2(1000);
BEGIN
l_parser := dbe_xmlparser.newparser;
-- 设为 true，去解析。
--xml字符串不符合DTD格式，预期将报错
dbe_xmlparser.setValidationMode(l_parser, true);
dbe_xmlparser.parseclob(l_parser, l_clob);
l_doc := dbe_xmlparser.getdocument(l_parser);
dbe_xmldom.writetobuffer(l_doc, buffer);
dbe_xmlparser.freeparser(l_parser);
dbe_xmldom.freedocument(l_doc);
END;
/
```
执行结果：
```
xmlparser解析报错
ERROR: invalid XML document
```