sp_xml_preparedocument (Transact-SQL)

Mis à jour : 14 avril 2006

Lit le texte XML fourni en entrée, l'analyse à l'aide de l'analyseur MSXML (Msxmlsql.dll), puis fournit le document analysé dans un état exploitable. Ce document analysé est une représentation arborescente des différents nœuds du document XML : éléments, attributs, textes, commentaires, etc.

sp_xml_preparedocument retourne un descripteur qui peut être utilisé pour accéder à la représentation interne du document XML nouvellement créée. Ce descripteur est valide pour toute la session ou jusqu'à ce qu'il soit invalidé par l'exécution de sp_xml_removedocument.

Remarque :
Un document analysé est stocké dans le cache interne de SQL Server 2005. L'analyseur MSXML utilise un huitième de la mémoire totale disponible pour SQL Server. Pour éviter de manquer de mémoire, exécutez sp_xml_removedocument pour en libérer.

Remarque :
Pour des raisons de compatibilité descendante, sp_xml_preparedocument réduit les caractères CR (char(13)) et LF (char(10)) en attributs, même si ces caractères sont convertis en entités.

Remarque :

L'analyseur XML appelé par sp_xml_preparedocument peut analyser des DTD et des déclarations d'entité internes. Dans la mesure où des DTD et des déclarations d'entité construits dans une optique nuisible peuvent être utilisés pour réaliser une attaque par déni de service, il est fortement recommandé de ne pas passer de documents XML directement depuis des sources non approuvées à sp_xml_preparedocument. Pour limiter les risques d'attaques d'extension d'entité récursive, sp_xml_preparedocument limite à 10 000 le nombre d'entités qui peuvent être étendues sous une même entité au niveau supérieur du document. Cette limite ne s'applique pas aux entités numériques ou de caractères. Elle permet de stocker des documents contenant de nombreuses références d'entités, mais elle empêche une entité d'être étendue de manière récursive dans une chaîne supérieure à 10 000 extensions.

Remarque :
sp_xml_preparedocument limite à 256 le nombre d'éléments qui peuvent être ouverts simultanément.

Conventions de la syntaxe de Transact-SQL

Syntaxe

sp_xml_preparedocument
hdoc 
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ] 

Arguments

• hdoc
  Descripteur du document nouvellement créé. hdoc est un entier.

• [ xmltext ]
  Document XML initial. L'analyseur MSXML analyse ce document XML. xmltext est un paramètre de texte : char, nchar, varchar, nvarchar, text, ntext ou xml. Lorsque la valeur est NULL (valeur par défaut), une représentation interne d'un document XML vide est créée.

  Remarque :
  sp_xml_preparedocument ne peut traiter que du texte ou du XML non typé. Si une valeur d'instance à utiliser en entrée est déjà du XML typé, commencez par la convertir en une nouvelle instance XML non typée ou en une chaîne, puis passez cette valeur en entrée. Pour plus d'informations, consultez XML typé et non typé.

• [ xpath_namespaces ]
  Spécifie les déclarations d'espaces de noms utilisées dans les expressions XPath de ligne et de colonne sous OPENXML. xpath_namespaces est un paramètre de texte : char, nchar, varchar, nvarchar, text, ntext ou xml.

  La valeur par défaut est <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces fournit les URI d'espaces de noms des préfixes utilisés dans les expressions XPath sous OPENXML par le biais d'un document XML correctement mis en forme. xpath_namespaces déclare le préfixe à utiliser pour faire référence à l'espace de noms urn:schemas-microsoft-com:xml-metaprop, qui fournit les métadonnées sur les éléments XML analysés. Bien que cette technique vous permette de redéfinir le préfixe de l'espace de noms des métapropriétés, cet espace de noms n'est pas perdu. Le préfixe mp est toujours valide pour urn:schemas-microsoft-com:xml-metaprop, même si xpath_namespaces ne contient pas une telle déclaration.

Autorisations

Il faut être membre du rôle public.

Valeurs des codes renvoyés

0 (succès) ou >0 (échec)

Exemples

A. Préparation d'une représentation interne pour un document XML correctement mis en forme

L'exemple suivant retourne un descripteur pour la représentation interne nouvellement créée du document XML fourni en entrée. L'appel à sp_xml_preparedocument contient un mappage de préfixes d'espaces de noms par défaut.

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. Préparation d'une représentation interne pour un document XML correctement mis en forme avec un schéma DTD

L'exemple suivant retourne un descripteur pour la représentation interne nouvellement créée du document XML fourni en entrée. La procédure stockée valide le document chargé sur le schéma DTD inclus dans le document. L'appel à sp_xml_preparedocument contient un mappage de préfixes d'espaces de noms par défaut.

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. Spécification d'un URI d'espace de noms

L'exemple suivant retourne un descripteur pour la représentation interne nouvellement créée du document XML fourni en entrée. L'appel à sp_xml_preparedocument préserve le préfixe mp associé au mappage d'espaces de noms des métapropriétés et ajoute le préfixe de mappage xyz à l'espace de noms 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"/>'

Voir aussi

Référence

Procédures stockées XML (Transact-SQL)
Procédures stockées système (Transact-SQL)
sp_xml_removedocument (Transact-SQL)
OPENXML (Transact-SQL)

Aide et Informations

Assistance sur SQL Server 2005

Historique des modifications