sp_xml_preparedocument (Transact-SQL)

Data aggiornamento: 14 aprile 2006

Legge il testo in formato XML specificato come input, ne esegue l'analisi mediante il parser MSXML (Msxmlsql.dll) e restituisce il documento analizzato in un formato pronto per l'uso. Il documento analizzato corrisponde a una rappresentazione strutturata dei vari nodi (elementi, attributi, testo, commenti e così via) del documento XML.

La stored procedure sp_xml_preparedocument restituisce un handle utilizzabile per l'accesso alla nuova rappresentazione interna del documento XML. L'handle è valido per l'intera durata della sessione oppure finché l'handle non viene invalidato tramite l'esecuzione della stored procedure sp_xml_removedocument.

[!NOTA] Un documento analizzato viene archiviato nella cache interna di SQL Server 2005. Il parser MSXML utilizza un ottavo della memoria totale disponibile per SQL Server. Per evitare possibili problemi di memoria insufficiente, eseguire sp_xml_removedocument in modo da liberare memoria aggiuntiva.

[!NOTA] Per compatibilità con le versioni precedenti, sp_xml_preparedocument comprime i caratteri CR (char(13)) e LF (char(10)) negli attributi anche quando tali caratteri sono sostituiti con entità.

[!NOTA] Il parser XML richiamato da sp_xml_preparedocument consente l'analisi di dichiarazioni di entità e definizioni DTD interne. Poiché tramite definizioni DTD e dichiarazioni di entità appositamente create è possibile eseguire attacchi Denial of Service, è consigliabile che documenti XML di fonti non attendibili non vengano passati direttamente dagli utenti a sp_xml_preparedocument. Per ridurre il rischio di attacchi di espansione ricorsiva di entità, sp_xml_preparedocument limita a 10.000 il numero delle entità espandibili sotto una singola entità di primo livello di un documento. Tale limite non viene applicato a entità carattere o numeriche e consente di archiviare documenti con numerosi riferimenti a entità impedendo tuttavia l'espansione ricorsiva di qualsiasi entità in una catena di lunghezza superiore a 10.000 espansioni.

[!NOTA] sp_xml_preparedocument limita a 256 il numero di elementi che è possibile aprire contemporaneamente.

Convenzioni della sintassi Transact-SQL

Sintassi

sp_xml_preparedocument
hdoc 
OUTPUT
[ , xmltext ]
[ , xpath_namespaces ] 

Argomenti

• hdoc
  Handle del nuovo documento. hdoc è di tipo integer.

• [ xmltext ]
  Documento XML originale. Il parser MSXML analizza il documento XML. xmltext è un parametro di testo di tipo char, nchar, varchar, nvarchar, text, ntext o xml. Il valore predefinito è NULL, con cui viene creata una rappresentazione interna di un documento XML vuoto.

  [!NOTA] La stored procedure sp_xml_preparedocument può elaborare solo testo e XML non tipizzato. Se un valore istanza da utilizzare come input è già XML tipizzato, eseguire innanzitutto il cast di tale valore in una nuova istanza XML non tipizzata oppure come stringa, quindi passare il valore come input. Per ulteriori informazioni, vedere Codice XML tipizzato e non tipizzato.

• [ xpath_namespaces ]
  Specifica le dichiarazioni degli spazi dei nomi utilizzate nelle espressioni XPath di riga e colonna in OPENXML. xpath_namespaces è un parametro di testo di tipo char, nchar, varchar, nvarchar, text, ntext o xml.

  Il valore predefinito è <root xmlns:mp="urn:schemas-microsoft-com:xml-metaprop">. xpath_namespaces fornisce l'URI degli spazi dei nomi per i prefissi utilizzati in espressioni XPath in OPENXML tramite un documento XML corretto. In xpath_namespaces viene dichiarato il prefisso da utilizzare nei riferimenti allo spazio dei nomi urn:schemas-microsoft-com:xml-metaprop, che fornisce i metadati sugli elementi XML analizzati. Questa tecnica consente di ridefinire il prefisso dello spazio dei nomi di metaproprietà conservando allo stesso tempo lo spazio dei nomi. Il prefisso mp è tuttora valido per urn:schemas-microsoft-com:xml-metaprop anche se xpath_namespaces non contiene tale dichiarazione.

Autorizzazioni

È richiesta l'appartenenza al ruolo public.

Valori restituiti

0 (esito positivo) o >0 (esito negativo)

Cronologia delle modifiche

Esempi

A. Preparazione di una rappresentazione interna di un documento XML

Nell'esempio seguente viene restituito un handle per la nuova rappresentazione interna del documento XML specificato come input. Nella chiamata a sp_xml_preparedocument viene utilizzato il mapping predefinito per i prefissi degli spazi dei nomi.

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. Preparazione di una rappresentazione interna di un documento XML con DTD

Nell'esempio seguente viene restituito un handle per la nuova rappresentazione interna del documento XML specificato come input. Il documento caricato viene convalidato in base al valore DTD incluso nel documento. Nella chiamata a sp_xml_preparedocument viene utilizzato il mapping predefinito per i prefissi degli spazi dei nomi.

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. Specificazione di URI di spazi dei nomi

Nell'esempio seguente viene restituito un handle per la nuova rappresentazione interna del documento XML specificato come input. Nella chiamata a sp_xml_preparedocument il prefisso mp del mapping dello spazio dei nomi di metaproprietà viene conservato e viene aggiunto il prefisso di mapping xyz allo spazio dei nomi 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"/>'

Vedere anche

Riferimento

Stored procedure XML (Transact-SQL)
Stored procedure di sistema (Transact-SQL)
sp_xml_removedocument (Transact-SQL)
OPENXML (Transact-SQL)

Guida in linea e informazioni

Assistenza su SQL Server 2005