sp_xml_preparedocument (Transact-SQL)

Artículo
12/15/2008

Actualizado: 14 de abril de 2006

Lee el texto de XML proporcionado como entrada, analiza el texto con el analizador MSXML (Msxmlsql.dll) y proporciona el documento analizado en un estado apto para su uso. Este documento analizado es una representación en árbol de varios nodos en el documento XML: elementos, atributos, texto, comentarios, etc.

sp_xml_preparedocument devuelve un identificador que se puede utilizar para obtener acceso a la representación interna que se acaba de crear del documento XML. Este identificador es válido mientras dura la sesión o hasta que el identificador se invalida ejecutando sp_xml_removedocument.

[!NOTA] Un documento analizado se almacena en la caché interna de SQL Server 2005. El analizador MSXML usa un octavo de la memoria total disponible para SQL Server. Para no quedarse sin memoria, ejecute sp_xml_removedocument para liberar memoria.

[!NOTA] Para mantener la compatibilidad con versiones anteriores, sp_xml_preparedocument contrae los caracteres CR (char(13)) y LF (char(10)) en atributos incluso si se crean entidades de estos atributos.

[!NOTA] El analizador XML invocado por sp_xml_preparedocument puede analizar DTD y declaraciones de entidades internos. Puesto que se pueden utilizar DTD y declaraciones de entidades creadas de forma malintencionada para realizar ataques de denegación de servicio, se recomienda encarecidamente que los usuarios no pasen directamente documentos XML de orígenes que no sean de confianza a sp_xml_preparedocument. Para mitigar ataques de expansión de entidades recursivos, sp_xml_preparedocument limita a 10.000 el número de entidades que pueden expandirse debajo de una sola entidad en el nivel superior de un documento. Este límite no se aplica a los caracteres o entidades numéricas. Este límite permite almacenar documentos con muchas entidades, pero evita que cualquier entidad se expanda de forma recursiva en una cadena con más de 10.000 expansiones.

[!NOTA] sp_xml_preparedocument limita el número de elementos que pueden estar abiertos a la vez a 256.

Icono de vínculo a temas Convenciones de sintaxis de Transact-SQL

Sintaxis

sp_xml_preparedocument
hdoc 
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ]

Argumentos

hdoc
Es el identificador del documento recién creado. hdoc es un número entero.

[ xmltext ]
Es el documento XML original. El analizador MSXML analiza este documento XML. xmltext es un parámetro de texto: char, nchar, varchar, nvarchar, text, ntext o xml. El valor predeterminado es NULL, en cuyo caso se crea una representación interna de un documento XML vacío.

[!NOTA] sp_xml_preparedocument sólo puede procesar texto o XML sin tipo. Si el valor de instancia que se va a utilizar como entrada ya es XML con tipo, primero conviértalo a una nueva instancia XML sin tipo o a una cadena y, a continuación, pase ese valor como entrada. Para obtener más información, vea XML con tipo y sin tipo.

[ xpath_namespaces ]
Especifica las declaraciones de espacio de nombres que se utilizan en las expresiones XPath de fila y columna de OPENXML. xpath_namespaces es un parámetro de texto: char, nchar, varchar, nvarchar, text, ntext o xml.

El valor predeterminado es <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces proporciona los URI del espacio de nombres para los prefijos utilizados en las expresiones XPath de OPENXML mediante un documento XML bien formado. xpath_namespaces declara el prefijo que se debe utilizar para hacer referencia al espacio de nombres urn:schemas-microsoft-com:xml-metaprop, que proporciona metadatos sobre los elementos XML analizados. Aunque puede redefinir el prefijo del espacio de nombres para el espacio de nombres de metapropiedad mediante esta técnica, este espacio de nombres no se pierde. El prefijo mp es válido para urn:schemas-microsoft-com:xml-metaprop aunque xpath_namespaces no contenga esa declaración.

Permisos

Debe pertenecer a la función public.

Valores de código de retorno

0 (correcto) o >0 (error)

Ejemplos

A. Preparar una representación interna para un documento XML bien construido

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada. En la llamada a sp_xml_preparedocument se utiliza la asignación predeterminada del prefijo de espacio de nombres.

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. Preparar una representación interna de un documento XML bien construido con un DTD

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada. El procedimiento almacenado valida el documento cargado contra el DTD incluido en el documento. En la llamada a sp_xml_preparedocument se utiliza la asignación predeterminada del prefijo de espacio de nombres.

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. Especificar un URI de espacio de nombres

En el siguiente ejemplo se devuelve un identificador para la representación interna que se acaba de crear del documento XML proporcionado como entrada. La llamada a sp_xml_preparedocument conserva el prefijo mp de la asignación de espacio de nombres de metapropiedad y agrega el prefijo de asignación xyz al espacio de nombres 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"/>'

Vea también

Referencia

Procedimientos almacenados de XML (Transact-SQL)
Procedimientos almacenados del sistema (Transact-SQL)
sp_xml_removedocument (Transact-SQL)
OPENXML (Transact-SQL)

Ayuda e información

Obtener ayuda sobre SQL Server 2005

Historial de cambios

Versión	Historial
14 de abril de 2006	Contenido nuevo: Se describió el nuevo límite de expansión de entidades incluido en el Service Pack 1. Se describió el nuevo límite de elementos incluido en el Service Pack 1.