590 SQL Server 2000 Stored Procedure Programming Model varchar(25) ' /@Model', comment ntext '@mp:xmltext') EXEC sp_xml_removedocument @intDoc return @intErrorCode Figure 12-10 demonstrates the use of the stored procedure. A long XML document was created by copying and pasting the same set of nodes into the string (XML document) over and over. Publishing Database Information Using XML SQL Server 2000 has an external set of components that allow users to access database information in the form of an XML document Figure 12-10. Use of a text input parameter Chapter 12: XML Support in SQL Server 2000 591 through the HTTP protocol. It is important to understand that these components are external. The most important of these is the ISAPI filter that works within IIS (Internet Information Server—a Web server), rather than within SQL Server (see Figure 12-11). It retrieves database information through a SQL Server 2000 OLE DB provider (SQLOLEDB). The OLE DB provider itself has been modified to use a new SQLXML.dll component and to support retuning of the result in the form of a stream. Figure 12-11 illustrates the transfer of information from a client computer to the server and back. Configuring Database Access Through HTTP One new component delivered with SQL Server 2000 is an MMC snap-in called IIS Virtual Directory Management for SQL Server. This snap-in provides a graphical user interface for configuring database access through HTTP. Behind the scenes, it operates using the IIS Virtual Directory Management for SQL Server Object Model. Figure 12-11. Accessing database information using XML 592 SQL Server 2000 Stored Procedure Programming This tool can operate on any edition of Windows NT or Windows 2000. Computers with Windows NT must also have IIS 4.0 or higher (or Peer Web Services 4.0 or higher on Windows NT Workstation) and MMC 1.2 or higher. The configuration of database access requires only one operation— the administrator needs to create a virtual directory. Apart from the usual information (such as name and path), this virtual directory must contain information for accessing the database (login, password, database, server name, database name, and the type of access allowed through the URL and virtual names). Before we explain what a virtual name is, let’s first say that there are three types of access that end users can accomplish through IIS: ▼ dbobject Users can issue a Select statement as a part of an HTTP request and access a database object (such as a table or a view). ■ template Users can specify a template that is a valid XML document and contains one or more Transact-SQL statements. SQL Server will execute, and the information will be included in the result. ▲ schema The URL can be specified to execute an XPath query against the annotated mapping schema file. A virtual name is a part of a URL that specifies and executes a dbobject, a template, or a schema. Let’s now demonstrate how you can configure IIS to provide access to SQL Server: 1. Launch IIS Virtual Directory Management for SQL Server: Start | Programs | Microsoft SQL Server | Configure SQL XML Support in IIS. 2. When the application appears on the screen, expand the server to display the Default Web Site. Select it and then select Action | New | Virtual Directory. The application displays the New Virtual Directory Properties dialog box. 3. Set the name and the physical path of the virtual directory (see Figure 12-12). Chapter 12: XML Support in SQL Server 2000 593 4. Select the Security tab and define the authentication method that the user will use to connect to the database: Figure 12-12. Configuring a new virtual directory 594 SQL Server 2000 Stored Procedure Programming 5. Select the Data Source tab to define the server and the database containing the source information: 6. Select the Settings tab to specify the type of access to allow through the virtual directory. For training purposes, let’s allow them all (although on a production server you will probably allow only templates or XPath). Chapter 12: XML Support in SQL Server 2000 595 7. Select the Virtual Names tab to associate a specific type of access and optional directory to a virtual name: 8. Click the New button. The application displays the Virtual Name Configuration dialog box. Type a new name, specify a type, select an existing path that will store files, and then click Save: 9. Repeat step 8 to create virtual names for other types, and then click OK in the New Virtual Directory Properties dialog box. The application creates a virtual directory (see Figure 12-13). 596 SQL Server 2000 Stored Procedure Programming Accessing Database Information Using a URL After the virtual directory is created, an end user can use a browser such as Internet Explorer 5.0 to query the database using HTTP GET and POST methods. The simplest syntax for making such queries would be: http:// server / virtual_directory / virtual_name ?sql= tsql_statement Unfortunately, characters such as “ “ (space), “?”, “/”, “%”, “#”, and “&” have special meanings in URL syntax. Therefore, they must be encoded using their hexadecimal value in the form “%xx”. For example, the space character can be replaced using “%20” or “+”. Therefore, to query the Inventory table, a user can issue the following statement: Figure 12-13. A new virtual directory Chapter 12: XML Support in SQL Server 2000 597 http://MyServer/Asset?sql=select%20top%201%20*%20 from%20Inventory%20for%20xml%20auto The query returns an XML document that contains just one node (see Figure 12-14). If you leave the clause top 1 out of the query, http://MyServer/Asset?sql=select%20*%20 from%20Inventory%20for%20xml%20auto the parser will not be able to process the result. The Inventory element in the result string is repeated for each record and there is, therefore, no unique top element (see Figure 12-15). Figure 12-14. An XML document as a result of the database query 598 SQL Server 2000 Stored Procedure Programming There are two solutions to this problem. You can add a root parameter to the HTTP GET method, and the server will add a root node to the result: &root= root_node In this case, the previous query would be http://dejan/asset?sql=select%20*%20 from%20Inventory%20for%20xml%20auto&root=ROOT The other alternative is to write the Transact-SQL statement so that it returns a missing root element. In the following example, two additional Select statements were added: http://dejan/Asset?sql=SELECT%20'<Root>'; %20SELECT%20*%20FROM%20Inventory%20FOR%20XML%20AUTO; %20select%20'</Root>' The results of both methods are identical (see Figure 12-16). Figure 12-15. The problem with no unique top element Unfortunately, many things can go wrong when you connect all these components and try to make them work together. Internet Explorer and the XML parser are not ideal debugging tools, which is understandable considering the number of layers created and the transformations that occurred. Using a Stored Procedure Through HTTP SQL Server 2000 and the ISAPI driver do not force you to use only the Select statement to get information via HTTP. Naturally, you can also use stored procedures. The following stored procedure contains a simple Select statement with a For XML clause: CREATE PROCEDURE prListEquipment_xml AS select * Chapter 12: XML Support in SQL Server 2000 599 Figure 12-16. The result as an XML document with root element [...]...600 SQL Server 2000 Stored Procedure Programming from Equipment for xml auto The stored procedure can be called through HTTP: http://dejan/asset ?sql= execute%20prListEquipment_xml&root=ROOT In the following example, we demonstrate two things First, a list of parameters can be included as a part of the Transact -SQL statement that executes the stored procedure Second, the root element... database information Template files have the following syntax: default_value< /sql: param> tsql_statements < /sql: query> XPath_query < /sql: XPath-query> The root element of the template file has one mandatory... value is not specified: default_value< /sql: param> The following example contains a simple template file with two parameters: Toshiba< /sql: param> Portege 7020CT< /sql: param> < /sql: header> exec prGetEquipment2_xml @Make, @Model < /sql: query> Let’s... type="PartNum" sql: field="EquipmentId"/> 6 19 620 SQL Server 2000 Stored Procedure Programming Part < /sql: xpath-query> The schema is identified using the sql: id attribute and described using the sql: is-mapping-schema attribute of the element The identifier... HTML page 6 09 610 SQL Server 2000 Stored Procedure Programming To get a proper mapping schema in this case, you need to extract the schema into a separate file and to add another namespace to it (xmlns :sql= “urn:schemas-microsoft-com:xml -sql ): Part < /sql: xpath-query> The result is shown in Figure 12-23 613 614 SQL Server 2000 Stored Procedure Programming Figure 12-23 The result of the annotated schema sql: field annotations can be applied to elements as well The following... 618 SQL Server 2000 Stored Procedure Programming It can be used through the following template: Contact < /sql: xpath-query> The result is shown in Figure 12-25 Naturally, you can join more than one table Other Annotations There are other annotations that you can also use in mapping schemas: sql: is-constant=“1”... the urn:schemas-microsoft-com:xml -sql namespace Therefore, all template files must have an xmlns :sql= “urn:schemas-microsoft-com:xml -sql attribute The xsl attribute is optional It is used to specify the name of the XSL transformation file 601 602 SQL Server 2000 Stored Procedure Programming Using Query The element is used to specify one or more Transact -SQL statements The following template... (Equipment.xsl): exec prListEquipment2_xml < /sql: query> If you execute just the stored procedure (for example, from Query Analyzer), you can see the simple XML document it produces: Chapter 12: XML Support in SQL Server 2000 . IIS Virtual Directory Management for SQL Server Object Model. Figure 12-11. Accessing database information using XML 592 SQL Server 2000 Stored Procedure Programming This tool can operate on. document with root element 600 SQL Server 2000 Stored Procedure Programming from Equipment for xml auto The stored procedure can be called through HTTP: http://dejan/asset ?sql= execute%20prListEquipment_xml&root=ROOT In. the database query 598 SQL Server 2000 Stored Procedure Programming There are two solutions to this problem. You can add a root parameter to the HTTP GET method, and the server will add a root node