Статья
04/01/2012

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.

Проанализированный документ хранится во внутреннем кэше 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 расширений.

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

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

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

Значок ссылки на раздел Синтаксические обозначения в 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.

Процедура 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"/>'