sp_xml_preparedocument (Transact-SQL)

Считывает входной XML-текст, проводит его синтаксический анализ при помощи средства синтаксического анализатора MSXML (Msxmlsql.dll) и выдает проанализированный документ, готовый к потреблению. Проанализированный документ является древовидным представлением различных узлов в XML-документе: элементов, атрибутов, текста, комментариев и т. д.

Процедура sp_xml_preparedocument возвращает дескриптор, по которому можно обратиться к вновь созданному внутреннему представлению XML-документа. Дескриптор действует только в течение сеанса либо до тех пор, пока не будет аннулирован путем выполнения процедуры sp_xml_removedocument.

Примечание

Проанализированный документ хранится во внутреннем кэше SQL Server.Средство синтаксического анализа MSXML использует одну восьмую всей памяти, доступной SQL Server.Во избежание проблем с недостатком памяти освободите память с помощью процедуры sp_xml_removedocument.

Примечание

В целях обратной совместимости процедура sp_xml_preparedocument удаляет символы возврата каретки (char(13)) и перевода строки (char(10)) из атрибутов, даже если эти символы существенны.

Примечание

Средство синтаксического анализа XML, вызываемое процедурой sp_xml_preparedocument, позволяет анализировать внутренние DTD и объявления сущностей.Так как злонамеренно созданные DTD и объявления сущностей могут быть использованы для проведения атак отказа в обслуживании (DoS), настоятельно рекомендуется не передавать напрямую XML-документы из сомнительных источников в процедуру sp_xml_preparedocument.

Для избежания атак методом расширения рекурсивных сущностей, процедура sp_xml_preparedocument ограничивает до 10 000 число сущностей, которые можно поместить в корневую сущность документа.Это ограничение не применяется к символьным и числовым сущностям.Ограничение позволяет хранить документы с большим количеством ссылок на сущности, но предотвращает рекурсивное расширение отдельной сущности в цепочку длиннее 10 000 расширений.

Примечание

Процедура sp_xml_preparedocument устанавливает ограничение в 256 одновременно открываемых элементов.

Применимо для следующих объектов: SQL Server (начиная с SQL Server 2008 до текущей версии).

Значок ссылки на раздел Cинтаксические обозначения в Transact-SQL

Синтаксис

sp_xml_preparedocument 
hdoc  
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ]

Аргументы

hdoc
Дескриптор только что созданного документа. hdoc является целым числом.
[ xmltext ]
Исходный XML-документ. Средство синтаксического анализа MSXML анализирует этот XML-документ. Аргумент xmltext является текстовым параметром: char, nchar, varchar, nvarchar, text, ntext или xml. Значение по умолчанию равно NULL. В этом случае создается внутреннее представление пустого XML-документа.

Примечание

Процедура sp_xml_preparedocument может обрабатывать только текст или нетипизированный XML.Если значение экземпляра, передающееся в качестве входного параметра, уже является типизированным XML, его сначала необходимо привести к новому нетипизированному экземпляру XML или к строке, после чего его можно передавать в качестве входного параметра.Дополнительные сведения см. в разделе Сравнение типизированного и нетипизированного XML.
[ xpath_namespaces ]
Указывает объявления пространств имен, которые используются в выражениях XPath строк и столбцов в OPENXML. Аргумент xpath_namespaces является текстовым параметром: char, nchar, varchar, nvarchar, text, ntext или xml.

Значение по умолчанию равно <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. Аргумент xpath_namespaces предоставляет URI пространств имен для префиксов, используемых в выражениях XPath в OPENXML посредством XML-документа правильного формата. Аргумент xpath_namespaces объявляет префикс, который должен использоваться для обращения к пространству имен urn:schemas-microsoft-com:xml-metaprop; таким образом предоставляются метаданные о проанализированных элементах XML. Хотя с помощью данного приема можно переопределить префикс пространства имен для пространства имен метасвойства, это пространство имен не будет потеряно. Префикс mp все еще действителен для urn:schemas-microsoft-com:xml-metaprop, даже если аргумент xpath_namespaces не содержит такого объявления.

Значения кода возврата

0 (успешное завершение) или >0 (неуспешное завершение)

Разрешения

Необходимо быть членом роли public.

Примеры

А.Подготовка внутреннего представления для XML-документа правильного формата

В следующем примере возвращается дескриптор вновь созданного внутреннего представления XML-документа, который передается как входной аргумент. При вызове процедуры sp_xml_preparedocument используется сопоставление префикса пространства имен по умолчанию.

DECLARE @hdoc int;
DECLARE @doc varchar(1000);
SET @doc ='
<ROOT>
<Customer CustomerID="VINET" ContactName="Paul Henriot">
   <Order CustomerID="VINET" EmployeeID="5" OrderDate="1996-07-04T00:00:00">
      <OrderDetail OrderID="10248" ProductID="11" Quantity="12"/>
      <OrderDetail OrderID="10248" ProductID="42" Quantity="10"/>
   </Order>
</Customer>
<Customer CustomerID="LILAS" ContactName="Carlos Gonzlez">
   <Order CustomerID="LILAS" EmployeeID="3" OrderDate="1996-08-16T00:00:00">
      <OrderDetail OrderID="10283" ProductID="72" Quantity="3"/>
   </Order>
</Customer>
</ROOT>';
--Create an internal representation of the XML document.
EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc;
-- Remove the internal representation.
exec sp_xml_removedocument @hdoc;

Б.Подготовка внутреннего представления для XML-документа правильного формата с DTD

В следующем примере возвращается дескриптор вновь созданного внутреннего представления XML-документа, который передается как входной аргумент. Хранимая процедура проверяет корректность загруженного документа с помощью DTD, включенного в документ. При вызове процедуры sp_xml_preparedocument используется сопоставление префикса пространства имен по умолчанию.

DECLARE @hdoc int;
DECLARE @doc varchar(2000);
SET @doc = '
<?xml version="1.0" encoding="UTF-8" ?> 
<!DOCTYPE root 
[<!ELEMENT root (Customers)*>
<!ELEMENT Customers EMPTY>
<!ATTLIST Customers CustomerID CDATA #IMPLIED ContactName CDATA #IMPLIED>]>
<root>
<Customers CustomerID="ALFKI" ContactName="Maria Anders"/>
</root>';

EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc;

В.Указание URI пространства имен

В следующем примере возвращается дескриптор вновь созданного внутреннего представления XML-документа, который передается как входной аргумент. При вызове процедуры sp_xml_preparedocument сохраняется префикс mp в сопоставлении пространства имен метасвойства и добавляется префикс сопоставления xyz к пространству имен urn:MyNamespace.

DECLARE @hdoc int;
DECLARE @doc varchar(1000);
SET @doc ='
<ROOT>
<Customer CustomerID="VINET" ContactName="Paul Henriot">
   <Order CustomerID="VINET" EmployeeID="5" 
           OrderDate="1996-07-04T00:00:00">
      <OrderDetail OrderID="10248" ProductID="11" Quantity="12"/>
      <OrderDetail OrderID="10248" ProductID="42" Quantity="10"/>
   </Order>
</Customer>
<Customer CustomerID="LILAS" ContactName="Carlos Gonzlez">
   <Order CustomerID="LILAS" EmployeeID="3" 
           OrderDate="1996-08-16T00:00:00">
      <OrderDetail OrderID="10283" ProductID="72" Quantity="3"/>
   </Order>
</Customer>
</ROOT>'
--Create an internal representation of the XML document.
EXEC sp_xml_preparedocument @hdoc OUTPUT, @doc, '<ROOT xmlns:xyz="urn:MyNamespace"/>';