Artigo
09/28/2010

sp_xml_preparedocument (Transact-SQL)

Lê o texto XML fornecido como entrada, analisa o texto usando o analisador MSXML (Msxmlsql.dll) e fornece o documento analisado em um estado pronto para consumo. Esse documento analisado é uma representação em árvore dos vários nós no documento XML: elementos, atributos, texto, comentários e assim por diante.

sp_xml_preparedocument retorna um identificador que pode ser usado para acessar a representação interna recentemente criada do documento XML. Esse identificador é válido para a duração da sessão ou até que ele seja invalidado executando-se sp_xml_removedocument.

Observação
Um documento analisado é armazenado no cache interno do SQL Server. O analisador MSXML usa um oitavo da memória total disponível para o SQL Server. Para evitar ficar sem memória, execute sp_xml_removedocument para liberar a memória.

Observação
Para compatibilidade com versões anteriores, sp_xml_preparedocument recolhe os caracteres CR (char(13)) e LF (char(10)) em atributos mesmo se esses caracteres tiverem entidade.

Observação
O analisador XML invocado por sp_xml_preparedocument pode analisar DTDs internos e declarações de entidade. Como DTDs e declarações de entidade construídos com má intenção podem ser usados para executar uma negação de ataque de serviço, é altamente recomendável que os usuários não passem documentos XML diretamente de fontes não confiáveis para sp_xml_preparedocument. Para minimizar os ataques de expansão de entidade, sp_xml_preparedocument limita a 10.000 o número de entidades que podem ser expandidas em uma única entidade no nível superior de um documento. O limite não se aplica a entidades numéricas ou caractere. Esse limite permite que documentos com muitas referências de entidade sejam armazenados, mas impede que qualquer entidade seja recursivamente expandida em uma cadeia com mais de 10.000 expansões.

O analisador XML invocado por sp_xml_preparedocument pode analisar DTDs internos e declarações de entidade. Como DTDs e declarações de entidade construídos com má intenção podem ser usados para executar uma negação de ataque de serviço, é altamente recomendável que os usuários não passem documentos XML diretamente de fontes não confiáveis para sp_xml_preparedocument.

Para minimizar os ataques de expansão de entidade, sp_xml_preparedocument limita a 10.000 o número de entidades que podem ser expandidas em uma única entidade no nível superior de um documento. O limite não se aplica a entidades numéricas ou caractere. Esse limite permite que documentos com muitas referências de entidade sejam armazenados, mas impede que qualquer entidade seja recursivamente expandida em uma cadeia com mais de 10.000 expansões.

Observação
sp_xml_preparedocument limita o número de elementos que podem ser abertos de uma só vez a 256.

Ícone de vínculo de tópico Convenções de sintaxe Transact-SQL

Sintaxe

sp_xml_preparedocument
hdoc 
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ]

Argumentos

hdoc
É o identificador do documento recentemente criado. hdoc é um inteiro.

[ xmltext ]
É o documento XML original. O analisador MSXML analisa esse documento XML. xmltext é um parâmetro de texto: char, nchar, varchar, nvarchar, text, ntext ou xml. O valor padrão é NULL; nesse caso é criada uma representação interna de um documento XML vazio.

Observação
sp_xml_preparedocument podem processar somente XML de texto não digitado. Se um valor de instância a ser usado como entrada já é XML digitado, primeiro converta-o em uma nova instância XML digitada ou uma cadeia de caracteres e, em seguida, passe esse valor como entrada. Para obter mais informações, consulte XML digitado comparado com XML não digitado.

[ xpath_namespaces ]
Especifica as declarações de namespace usadas em expressões XPATH de linha e coluna em OPENXML. xpath_namespaces é um parâmetro de texto: char, nchar, varchar, nvarchar, text, ntext ou xml.

O valor padrão é <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces fornece namespace URIs para os prefixos usados em expressões XPATH em OPENXML por meio de um documento XML bem-formado. xpath_namespaces declara o prefixo que deve ser usado para se referir ao namespace urn:schemas-microsoft-com:xml-metaprop; isso fornece metadados sobre os elementos XML analisados. Embora você possa redefinir o prefixo de namespace para o namespace metaproperty usando essa técnica, esse namespace não será perdido. O prefixo mp ainda será válido para urn:schemas-microsoft-com:xml-metaprop mesmo se xpath_namespaces não tiver tal declaração.

Valores de código de retorno

0 (êxito) ou >0 (falha)

Permissões

Requer associação na função public.

Exemplos

A. Preparando uma representação interna para um documento XML bem-formado

O exemplo a seguir retorna um identificador para a representação interna criada recentemente do documento XML que é fornecido como entrada. Na chamada para sp_xml_preparedocument, é usado um mapeamento de prefixo de namespace padrão.

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

B. Preparando uma representação interna para um documento XML bem-formado com um DTD

O exemplo a seguir retorna um identificador para a representação interna criada recentemente do documento XML que é fornecido como entrada. O procedimento armazenado valida o documento carregado contra o DTD incluído no documento. Na chamada para sp_xml_preparedocument, é usado um mapeamento de prefixo de namespace padrão.

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

C. Especificando um namespace URI

O exemplo a seguir retorna um identificador para a representação interna criada recentemente do documento XML que é fornecido como entrada. A chamada para sp_xml_preparedocument preserva o prefixo mp para o mapeamento de namespace metaproperty e adiciona o prefixo de mapeamento xyz ao namespace 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"/>'