Build a pureXML application in DB2 for z/OS, Part 2: Web enablement through Universal Services

In this tutorial, set up Web access to your pureXML data through simple insert, update, delete, select, and query operations known as the Universal Services. Use the included download bundle with ready-to-install services to explore the concepts of this tutorial, and learn how to quickly build application prototypes with the Universal Services.

Share:

Kirsten A. Larsen (kila@dk.ibm.com), Senior IT specialist, IBM

Kirsten A. LarsenKirsten Ann Larsen is a senior IT specialist and technical lead with IT Delivery in IBM Nordics. She has more than 10 years of experience with DB2 for z/OS and has co-authored a Redbook on DB2 security. She has worked with XML since pureXML support was included with the release of DB2 9 in 2007.



Susan Malaika, Senior Technical Staff Member, IBM

Susan Malaika photoSusan Malaika works in IBM's Information Management Group. She specializes in XML and Web technologies, including Grid computing. She has published articles and co-edited a book on the Web. She is a member of the IBM Academy of Technology.



04 June 2009

Also available in Chinese

Before you start

About this tutorial

This is the second installment in a series on how to get started with XML in IBM® DB2® for z/OS®. This series provides different approaches for creating simple applications that manipulate XML data. The objective is to provide some familiarity with the technology and demonstrate the ease with which XML applications can be developed, but the downloadable material may also serve as a starting point for prototyping.

This tutorial describes how to set up Web access to your pureXML data in DB2 for z/OS in a few easy steps, supplying a download bundle complete with instructions for you to install.

The operations supplied are insert, update, delete, select, and query. The query operation supplies the functionality of applying any XPath expression entered through the Web page to your XML document in DB2, thus providing an environment for experimenting with XPath as well as a starting point for creating more specific queries.

This tutorial also provides instructions on how to import the Universal Services into Data Studio as a project for further development.

The content in this tutorial is based on the article "Universal Services for pureXML using Data Web Services" (developerWorks, August 2008). However, it has been adopted to target DB2 for z/OS, whereas the original article works with DB2 for Linux®, UNIX®, and Windows®.

Prerequisites

In order to install and run Universal Services, the following software needs to be available:

  • DB2 9 for z/OS
  • JRE 1.5 or later on z/OS
  • JDK 1.5 or later on the Windows server
  • DB2 Connect, Version 8 or later
    • This tutorial uses a type 4 JDBC driver, so DB2 Connect does not actually need to be installed, but the license must be available.
  • One of the following Web servers:
    • IBM WebSphere® Application Server, Version 7 or later
    • WebSphere Application Server Community Edition, Version 2.1 or later
    • Apache Tomcat, version 5.5 or later

You can download both WebSphere Application Server Community Edition and Tomcat free of charge (see Resources).


The architecture of Universal Services

The architecture of this small application is three-tier, as shown in Figure 1. At the back end, DB2 for z/OS acts as a database server. The application layer in this case is a Web server running on Windows. The presentation layer or user interface is the Web page itself.

Neither layer is very complex. This tutorial discusses them briefly to give a basic understanding of the different elements and how they work together, although it is not strictly necessary to understand the inner workings of the Web services to set up the Universal Services.

Database layer

In DB2, there is a single table with three columns: ID, which has type INT; COMMENT, which has type VARCHAR; and XMLDATA, which is an XML column. This table is used to store all the XML data for the application, which is just a collection of individual XML documents, each identified by an ID key and with an optional comment field.

There is also a user-defined function that takes an XPath expression and an XML document as input and returns the result of applying this XPath expression to the XML document.

Web server

This tutorial uses either WebSphere Application Server, WebSphere Application Server Community Edition, or Tomcat running on Windows (for example, your own laptop) as the Web server. The actual Web service is a set of operations built from simple SQL scripts for select, insert, update, and delete, as well as a script calling the user-defined function defined in DB2 with an XPath expression received through the Web page.

The individual Web service operations are invoked through a Java Servlet, which is supplied together with some necessary libraries.

Together with a few files containing definitions and mappings between different elements, these files comprise the application layer.

Presentation layer

The user interface is written in XHTML with XSL stylesheets to format the output from two of the operations of the Web service, namely getXMLDocumentByKey (the select operation) and runxpathXML (the query operation).

Figure 1 illustrates the architecture of Universal Services:

Figure 1. Architecture of Universal Services
Diagram illustrating the architecture of Universal Services using boxes, lines, and cylinders

For WebSphere Application Server Community Edition and Tomcat, this tutorial uses the REST protocol, which is really just a fancy way of saying that you send XML over HTTP. For WebSphere Application Server, this tutorial uses SOAP, where (among other things) the messages are wrapped in XML envelopes containing various metadata.

This tutorial accesses DB2 on z/OS from Windows using a JDBC type 4 driver.

The application layer and the presentation layer are packed together in a .war file, which is deployed to the Web server. The .war file is an archive that contains the following:

  • JAR files containing the Java Servlets that interpret the Web service operations and some library classes needed by the servlets
  • WSDL file containing a definition of the Web service (in other words, the operations, their arguments, their protocol binding, and their physical location)
  • XML files containing relationships between the different components: web.xml mapping URLs to servlets, config.xml mapping operations to SQL statements, and other platform-specific XML files
  • XHTML file containing the definition of the Web page
  • XSL files containing stylesheets for formatting the results from two of the five operations of the Web service (the remaining three are so simple, they don't need them)

Figure 2 illustrates the folder structure of the .war file:

Figure 2. .war file structure
Screenshot of the .war file structure

Installing Universal Services

The DDL files in the included download bundle create the necessary objects in DB2, and the script create the .war file, which you can then deploy to the Web server.

The contents of the download bundle are shown in Figure 3:

Figure 3. Universal Services download bundle
Screenshot showing the file structure of the Universal Services download bundle

The only necessary configuration parameter is the location name of your DB2. You also, however, have the option to change the names of the DB2 objects creator, table, and columns as command line arguments.

The only .war component affected by customization is the config.xml file, which holds the SQL statements or operations supplied by the Web service, and for Tomcat, the context.xml file, which holds the data source definition. All the other files are included in the download bundle and added to the .war file unaltered.

The steps required for installation therefore include:

  • Create table and UDF in DB2
  • Configure script with table names and connection properties
  • Run script to generate .war file
  • Deploy .war file to Web server

Create objects in DB2

You need a table with the following columns:

Listing 1. Columns of table DB2ADMIN.SAMPLETABLE
ID              INTEGER GENERATED ALWAYS AS IDENTITY
COMMENT         VARCHAR(1000)
XMLDATA         XML

The names of the table and the columns are immaterial as long as the format is correct. Also, the table can contain additional columns; they just won't be referenced by Universal Services. If you do not have a table of your own that you want to use, the DDL for the table above is in the file createTable.txt.

The user-defined function is written in Java language. It takes as input an XPath expression, an ID, a table name, and column names, and returns the result of applying the XPath expression to an XML document, namely the one in the row of the table with the supplied ID.

A Java UDF consists of a Java load module and the DDL definition. The Java load module can either be installed into the DB2 catalog or into the Java directories in Unix System Services. This tutorial follows the recommended praxis of installing it into the DB2 catalog. To this end, this tutorial supplies a small Java technology program that calls the stored procedure SQLJ.DB2_INSTALL_JAR. You could also call the stored procedure from Data Studio.

To install the UDF, perform the following tasks:

  1. Modify supplied Java technology program uploadJar.java with the following information:
    • <hostname>, <port no>, and <location name> of the DB2 subsystem. This is the usual connection information needed when connecting to a DB2 subsystem.
    • <userid> and <password> for a user with the privileges needed to install a JAR into the DB2 catalog.
    • The path to the JAR file if Universal Services was not installed in the root directory of the C: drive.
  2. Compile and run the program:
    1. Start a command line in Windows.
    2. Navigate to the directory UniversalServicesZ.
    3. Enter the command javac uploadJar.java to compile.
    4. Enter the command java uploadJar to run.
  3. Create the user-defined function DB2ADMIN.XPATHXML:
    • Modify XPathDDL.txt. You must provide the name for the WLM environment used for Java routines in your environment. In the supplied DDL, it has the value DSN9WLMJ.
    • Run DDL in XPathDDL.txt, in, for example, SPUFI.

Configure and generate .war file

You perform both the configuration and the generation by the script configure for zOS.bat. You perform the configuration by calling a Java program with the values for:

  • Table creator, table name, column names (these will be used in the SQL scripts for insert, update, delete, select, and query)
  • DB2 location name (this is used to define a connection if the Web server used is Tomcat)

The Java program generates the files config.xml and context.xml.

Afterwards, the Web archive is created by jar'ing these files with the other supplied files. The result is the file UniversalServices.war.

Deploy to the Web server

The actual steps needed for deployment depends on which Web server is used. In each case, you need to:

  • Configure the data source (in other words, the connection to the DB2 subsystem where the data reside)
  • Deploy UniversalServices.war to the runtime environment of the Web server

Table 1 summarizes the information needed to configure the data source—regardless of which Web server is used. This information is needed whenever a remote connection is made to DB2 through DB2 Connect or a type 4 JDBC driver.

For illustration purposes, let's use the (non-existent) values DSN9 for <db2 name>, 9.123.45.678 for <host name>, 446 for <port no>, and db2admin for <userid>. You must supply your own values for your subsystem.

Table 1. Data source definition information
ElementDescription
<db2 name>The location name of your DB2 subsystem
<host name>The name of your z/OS system (could be a logical name or an IP-address)
<port no>Port number of the DB2 subsystem
<username>User id used for the connection
<pwd>Pwd for user id used for connection

The next section provides a detailed description of deployment with each of the Web servers.


Deploying to Web servers

This section contains instructions for deployment for each of the Web servers supported by the Universal Services: WebSphere Application Server, WebSphere Application Server Community Edition, and Tomcat. This tutorial does not go through the actual installation process, but assume that the software has been installed. WebSphere Application Server Community Edition and Tomcat are both available for download free of charge (see the Resources section for further information).

Deployment using WebSphere Application Server

Let's go through three steps you need to follow to deploy the Universal Services application to WebSphere Application Server:

  • Configure a JDBC provider
  • Define a data source (in other words, the DB2 subsystem)
  • Deploy the .war file

You perform all three steps from the administrative console, which is run through a Web browser. The full screen of the WebSphere Application Server administrative console is shown in Figure 4, but subsequent screen shots only show the actual console.

  1. Log on with the username and password provided at installation time:
    Figure 4. WebSphere Application Server administrative console
    Screenshot of the Websphere Application Server administrative console
  2. From the menu on the left, choose Resources > JDBC > JDBC Providers:
    Figure 5. JDBC Providers
    Screenshot showing how to select JDBC Providers
  3. Click on New:
    Figure 6. Create new JDBC provider
    Screenshot showing how to create a new JDBC provider
  4. Select DB2 for Database Type, DB2 Universal Driver Provider for Provider type, and XA data source for Implementation type, then click on Next:
    Figure 7. Create JDBC provider, step 1
    Screenshot showing how to create a new JDBC provider, step 1
  5. Enter the location of the jar files containing the JDBC driver and the DB2 Connect license. For a standard installation, this will be C:\Program Files\IBM\SQLLIB\java. Then click on Next:
    Figure 8. Create JDBC provider, step 2
    Screenshot showing how to create a new JDBC provider, step 2
  6. You get a summary page with the definitions made. Click on Finish:
    Figure 9. Create JDBC provider, step 3
    Screenshot showing how to create a new JDBC provider, step 3
  7. Finally, to save the changes to the master configuration click on Save:
    Figure 10. Create JDBC provider, step 4
    Screenshot showing how to create a new JDBC provider, step 4

The new JDBC provider is now available for use:

Figure 11. The new JDBC provider is created
Screenshot showing the new JDBC provider is created

The second task is to configure the data source:

  1. Choose Resources > JDBC > Data Sources from the menu on the left, then click on New:
    Figure 12. Create new data source
    Screenshot showing how to create new data source
  2. Click on Create a new J2C authentication alias (this is the definition of the user used to connect to the DB2 subsystem):
    Figure 13. Create J2C authentication alias, step 1
    Screenshot showing how to create J2C authentication alias, step 1
  3. Click on New:
    Figure 14. Create J2C authentication alias, step 2
    Screenshot showing how to create J2C authentication alias, step 2
  4. Enter a name for the alias (for example, "UnivServUser"), userid (for example, "db2admin"), and password for the account that is to be used for the connection to DB2, and click on OK:
    Figure 15. Create J2C authentication alias, step 3
    Screenshot showing how to create J2C authentication alias, step 3
  5. Click on Save directly to the master configuration:
    Figure 16. Create J2C authentication alias, step 4
    Screenshot showing how to create J2C authentication alias, step 4

Now you must configure the data source:

  1. Choose Resources > JDBC > Data Sources, and click on New:
    Figure 17. Create data source, step 1
    Screenshot showing how to create data source, step 1
  2. Enter Universal Services for the data source name and jdbc/<location name> (fill in appropriate value) for the JNDI name, then select UnivServUser from the drop-down menu and click on Next:
    Figure 18. Create data source, step 2
    Screenshot showing how to create data source, step 2
  3. Select Select an existing JDBC provider, and choose DB2 Universal Driver Provider XA from the drop-down menu, then click Next:
    Figure 19. Create data source, step 3
    Screenshot showing how to create data source, step 3
  4. Enter your own values in the "Database name", "Server name", and "Port number" fields for the DB2 subsystem, and click on Next:
    Figure 20. Create data source, step 4
    Screenshot showing how to create data source, step 4
  5. Click on Finish on the summary page, then click on Save directly to master configuration:
    Figure 21. Create data source, step 5
    Screenshot showing how to create data source, step 5
  6. The Universal Services data source is now available in the list. To test the connection, select the check box next to the data source, and click on the Test connection button:
    Figure 22. Create data source, step 6
    Screenshot showing how to create data source, step 6

    The following receipt shows that the test was successful:

    Figure 23. Create data source, step 7
    Screenshot showing how to create data source, step 7

You are now ready to deploy the .war file.

  1. Select Application > Install New Applications from the menu on the left.
  2. Fill in the path to the .war file or use the browse function to locate it.
  3. Enter UniversalServices (no spaces) for the "Context root" field, and click on Next:
    Figure 24. Deploy WAR file, step 1
    Screenshot showing how to deploy WAR file, step 1
  4. Accept the default values, scroll down to the bottom, and click on Next:
    Figure 25. Deploy WAR file, step 2
    Screenshot showing how to deploy WAR file, step 2
  5. Accept the default values, and click on Next":
    Figure 26. Deploy WAR file, step 3
    Screenshot showing how to deploy WAR file, step 3
  6. Browse to the bottom of the page and select the Universal Services check box.
  7. Choose a Target Resource JNDI name by clicking the browse button and selecting the data source previously configured—with name "jdbc/<location name>"—then click on Next:
    Figure 27. Deploy WAR file, step 4
    Screenshot showing how to deploy WAR file, step 4
  8. Click on Next:
    Figure 28. Deploy WAR file, step 5
    Screenshot showing how to deploy WAR file, step 5
  9. Click on Finish on the summary screen, scroll down to the bottom of the following screen, and click on Save directly to the master configuration:
    Figure 29. Deploy WAR file, step 6
    Screenshot showing how to deploy WAR file, step 6
  10. Finally, click on Applications > Enterprise Applications in the menu on the left.
  11. You get a list of applications installed. Universal Services is marked as stopped. To start it, select the check box next to Universal Services and click on the Start button:
    Figure 30. Deploy WAR file, step 7
    Screenshot showing how to deploy WAR file, step 7

You should get a receipt that the application has been started successfully and you are then ready to start testing.

Deployment using WebSphere Application Server Community Edition

Let's go through three steps you need to follow to deploy the Universal Services application to WebSphere Application Server Community Edition:

  • Make the DB2 Connect license available as a resource
  • Define a data source (in other words, the DB2 subsystem)
  • Deploy the .war file

All three steps are performed from the administrative console, which is run through a Web browser. The full screen is shown in Figure 31, but subsequent screen shots only show the actual console.

  1. Log on with username and password provided at installation time:
    Figure 31. WebSphere Application Server Community Edition administrative console
    Screenshot showing the Websphere Application Server Community Edition administrative console
  2. Select Services > Repository from the menu on the left:
    Figure 32. Adding DB2 Connect license to the repository, step 1
    Screenshot showing how to add DB2 Connect license to the repository, step 1
  3. Enter the location of the DB2 Connect license or use browse to find it. It will often be found in C:\Program Files\IBM\SQLLIB\java. The name of the jar file is db2jcc_license_cisuz.jar.
  4. Fill in the Group, Artifact, Version, and Type fields as follows (shown in Figure 33), then click on Install:
    • Group: com.ibm.db2
    • Artifact: db2jcc_license_cisuz
    • Version: 9.1
    • Type: jar
    Figure 33. Adding DB2 Connect license to the repository, step 2
    Screenshot showing how to add DB2 Connect license to the repository, step 2
  5. Having added the license, it is now possible to configure the data source. Select Services > Database Pools from the left to obtain the Database Pools window.
  6. Select Using the Geronimo database pool wizard:
    Figure 34. Create database pool, step 1
    Create database pool, step 1
  7. Enter jdbc/UniversalServices as the name for the database pool, choose DB2 XA as the database type, and click on Next:
    Figure 35. Create database pool, step 2
    Create database pool, step 2
  8. Fill in the connection information. You need to choose driver and license jar files, and enter your own values for the Port Number, User Name, Server Name, Password, and Database Name fields. Leave everything else to default.
    Figure 36. Create database pool, step 3
    Screenshot showing how to add DB2 Connect license to the repository, step 3
  9. Scroll down to the bottom, and click on Deploy.

    You can now see the database pool in the list:

    Figure 37. Create database pool, step 4
    Screenshot showing how to add DB2 Connect license to the repository, step 4
  10. To test the connection, scroll down to "Run SQL".
  11. Select the database pool jdbc/UniversalServices from the drop-down menu, enter an SQL statement, and click on the Run SQL button. The result of the query is returned at the bottom of the page:
    Figure 38. Test database pool
    Screenshot showing how to test database pool

Now you are ready to deploy the .war file.

  1. Choose Deploy New from the Application area of the menu on the left:
    Figure 39. Deploy WAR file, step 1
    Screenshot showing how to deploy WAR file, step 1
  2. Enter the location of the .war file or use the browse function to find it. It is located in Universal Services/war/wasce.
  3. Click on Install.
    Figure 40. Deploy WAR file, step 2
    Screenshot showing how to deploy WAR file, step 2

When you get the receipt saying the .war file has been installed, you are ready to start testing:

Figure 41. Deploy WAR file, step 3
Screenshot showing how to deploy WAR file, step 3

Deployment using Apache Tomcat

Let's go through three steps you need to follow to deploy the Universal Services application to Apache Tomcat:

  • Install the JDBC driver and license for DB2 Connect
  • Define a data source (in other words, the DB2 subsystem)
  • Deploy the .war file

To install the JDBC driver and license, you copy the files db2jcc.jar and db2jcc_license_cisuz.jar to the lib directory of the Tomcat installation. For a standard DB2 Connect installation, these will be found in C:\Program Files\IBM\SQLLIB\Java. The location of the lib directory varies with the version of Tomcat. With Version 5.5, it is located in \Tomcat 5.5\common\, whereas with Version 6, it is in the Tomcat root directory.

Figure 42. Tomcat 5.5 directories
Screenshot of Tomcat 5.5 directories

You can most easily configure the data source by manually editing the file server.xml, which is located in the conf directory directly under Tomcat's root directory.

Add the following entry (Listing 2) to the file. The entry should be placed within <GlobalNamingResources>.

Listing 2. Connection entry in server.xml
<Resource name="jdbc/DSN9"
 type="javax.sql.DataSource"
   url="jdbc:db2://9.123.45.678:446/DSN9"
   driverClassName="com.ibm.db2.jcc.DB2Driver"
   password="*******"
   maxActive="4"
   maxWait="5000"
   maxIdle="2"
   username="db2admin"/>

Note: In Listing 2, "DSN9" is the location name, "9.123.45.678" is the host name, "446" is the port number, "db2admin" is the userid, and "*******" is the password for the DB2 connection. You must supply your own values for these parameters.

To deploy the .war file:

  1. Start Tomcat and open the Tomcat Manager. You normally do this through a browser pointing at http://localhost:8080/manager/html, depending on the port number of your Tomcat server. The full screen of the Tomcat manager is shown in Figure 43, but subsequent screen shots only show the actual console (note that this tutorial uses port no 8888). Log on with username/password provided at installation time.
    Figure 43. Apache Tomcat Manager start page
    Screenshot showing the Apache Tomcat Manager start page
  2. Scroll down to the bottom of the page to the "Select WAR file to upload" field.
  3. Enter the path to the .war file or use the browse function to find it, then click on the Deploy button:
    Figure 44. Deployment of .war file
    Screenshot showing the deployment of .war file

"Universal Services" is now listed under "Applications":

Figure 45. Universal Services added to Applications
Screenshot showing that the Universal Services is added to Applications

The application has been started successfully, and you are ready to start testing.


Testing Universal Services

Testing Universal Services

The Web service is accessed through the supplied test page.

The URL of the test page is http://localhost:8080/UniversalServices/testServices.html, depending on the port number of your Web server.

Figure 46 shows the test page (note that the port number 8888 is used here):

Figure 46. Universal Services test page
Screenshot showing the Universal Services test page

The operation getPrimaryKeys returns a list of all the IDs of rows in the table. These can subsequently be used in the other operations supplied, like delete, update, or query.

How to use the query operation

The query operation can be used for practice with XPath expressions, or as a starting point for creating your own dedicated XPath queries. You enter a native XPath expression (in other words, without any DB2-specific keywords) in the text box. The operation then wraps it in the necessary DB2 syntax before it is sent to DB2 for processing. (This makes it easier to focus on the actual XPath expression.)

The Universal Services are for use with any XML schema. This tutorial therefore cannot supply many non-trivial examples that will work in all cases. One that will work is '.', which just returns the context node; that is, the whole XML document. Another is '//text()', which prints all text values in the document.

An example of an XPath expression for a UBL 2.0 Invoice document, which simply selects the whole invoice, is shown in Listing 3:

Listing 3. XPath expression UBL 2.0 Invoice
declare default element namespace
 "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2";
  /Invoice

For further information about and for the syntax of XPath, refer to the tutorial "Get Started with XPath" (developerWorks, May 2004).

Industry Bundles

If you are interested in a specific XML format, or if you just need some data for test purposes that have the quality of real-life data, you may want to take a look at the Industry Bundles that are available for download (see Resources > "Industry Formats and Services with pureXML").

There are Industry Bundles for a number of different XML formats, such as UNIFI, UBL 2.0, IRS1120, and more.

The bundles contain DDL for a table that matches the one this tutorial uses for Universal Services. They also contain the XML schemas that document the XML format and some sample XML documents adhering to this schema. These can be used with Universal Services to test the application.


Developing Universal Services

If you want to modify the Universal Services, the easiest way of doing so is through IBM Data Studio Developer. Maybe you want to add a parameter or create additional operations like dedicated XPath queries. Included as part of the tutorial download is a zip file containing the Web service that can be imported into Data Studio for modification.

IBM Data Studio Developer is an integrated Eclipse-based development environment for creating and testing database applications with most functions available for download free of charge, including data Web services. (See Resources for a link to download Data Studio Developer.)

This section includes detailed instructions on how to import and configure the Data Studio project. For more information on developing Web services using Data Studio, refer to some of the articles listed in the Resources section.

Import Universal Services project to Data Studio

This tutorial assumes that Data Studio has been installed and that it has been started using the data perspective.

  1. Right-click on the space in the Data Project Explorer, and select Import:
    Figure 47. Import project into Data Studio, step 1
    Screenshot showing how to import project into Data Studio, step 1
  2. Select Existing Projects into Workspace, and click on Next:
    Figure 48. Import project into Data Studio, step 2
    Screenshot showing how to import project into Data Studio, step 2
  3. Enter the destination of the file or browse to find it, and click on Finish:
    Figure 49. Import project into Data Studio, step 3
    Screenshot showing how to import project into Data Studio, step 3
  4. The project will appear in the Data Project Explorer. Click on the project. You will be asked if you want to edit the connection profile. Click on Edit now:
    Figure 50. Configure database connection, step 1
    Screenshot showing how to configure database connection, step 1
  5. You then get a list of connections to choose from. Select Universal Services Database Connection1, and click on Edit:
    Figure 51. Configure database connection, step 2
    Screenshot showing how to configure database connection, step 2
  6. In the "Properties for Universal Database Connection1" window, select Driver Properties from menu on the left:
    Figure 52. Configure database connection, step 3
    Screenshot showing how to configure database connection, step 3
  7. Enter your own values for the Database (DB2 location name), Host, Port number, User name, and Password fields, then click on Test Connection:
    Figure 53. Configure database connection, step 4
    Screenshot showing how to configure database connection, step 4
  8. Click OK to the receipt.
  9. Click OK in the "Universal Services Database Connection1 Properties" window.
  10. Click on Finish in the Connection window.
  11. Expand the project folder, and in your "Data Project Explorer", you should see the following contents: A folder structure with main folders SQL Scripts, Stored Procedures, User-Defined Functions, Web Services, and XML. The Web Services folder contains a subfolder named Universal Services, containing the services you are going to modify. The XML folder contains subfolders WSDL, XML Documents, XML Schema, and XSLT.
    Figure 54. Universal Services project contents
    Screenshot showing the Universal Services project contents

At this point you are ready to modify the Web services. You might want to change one of the existing operations, for example, by adding a parameter or adding operations to the Web service. For more information on how to use Data Studio to develop Web services, see Resources.

When you have made your modification (or even without modifications), you can deploy your Web service.

  1. Right-click on the Web services folder, and select Build and Deploy:
    Figure 55. Deploy Web service, step 1
    Screenshot showing how to deploy Web service, step 1
  2. In the "Deploy Web Service" window, choose which Web server to use from the drop-down menu.
  3. Choose whether to deploy to the Web server or just build the .war file. Here, just build the .war file, as the other option requires some configuration of the Web server in Data Studio.
  4. Make sure the location name is correct, then click on Finish:
    Figure 56. Deploy Web service, step 2
    Screenshot showing how to deploy Web service, step 2

A message in the Workspace log shows that the Web service has been deployed together with the destination of the .war file:

Figure 57. Deploy Web service, step 3
Screenshot showing how to deploy Web service, step 3

Finally, you have to deploy the .war file to the chosen Web server. (Refer to the "Deploying the Web servers" section.)

In the Universal Services bundle, an XHTML document defines a full Web page, providing a user interface for invoking the Web service operations. When modifying the operations through Data Studio, this XHTML document may no longer be applicable, but it can be updated manually to cater for the changes.

The XHTML document contains forms that collect arguments and generate HTTP POST requests to the Web server. As an example, the form for the getXMLDocumentByKey operation is shown in Listing 4:

Listing 4. XHTML for invoking operation getXMLDocumentByKey
<form name="testServices_getXMLDocumentByKey"  
      action="rest/UniversalServices/getXMLDocumentByKey"   
      method="post">
  <tr class="row-dark" >
    <td>getXMLDocumentByKey</td>
    <td align="right">ID:</td>
    <td align="center">
       <input type="text" name="p1" size="40" />
    </td>
    <td align="center">
      <input type="submit" value="Invoke" />
    </td>
  </tr>
</form>

You can see that the name of the operation is part of the action URL and that the form field for the single argument is named p1 (and p2, p3, and so on for subsequent arguments).

Alternatively, the individual operations of the Web service can be invoked directly through the HTTP GET method. Listing 5 shows example of URLs for each of the supplied operations. Note that parameters are passed as p1, p2, and so on, and separated by an ampersand (&).

Listing 5. URLs for GET methods of Universal Services
http://localhost:8888/servicesUniversalServices/rest/UniversalServices/getPrimaryKeys?

http://localhost:8888/servicesUniversalServices/rest/UniversalServices
    /getXMLDocumentByKey?p1=1

http://localhost:8888/servicesUniversalServices/rest/UniversalServices/deleteDocument?p1=3

http://localhost:8888/servicesUniversalServices/rest/UniversalServices
    /update?p1=<document4>updated document</document4>&p2=4

http://localhost:8888/servicesUniversalServices/rest/UniversalServices
    /insertXML?p1=A comment&p2=<document5>new doc</document5>

http://localhost:8888/servicesUniversalServices/rest/UniversalServices
    /runxpathXML?p1=.&p2=2

Conclusion

This tutorial showed how to set up the Universal Services to access pureXML data on DB2 z/OS, making it easier and quicker to build application prototypes that include pureXML. Various articles in the Resources section describe prototypes built on pureXML based on the Universal Services.

Acknowledgement

Thank you to Michael Schenker and Nuno Job for their contributions to this article and download.


Download

DescriptionNameSize
Universal Services for z/OSUniversalServices.zip2781KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management, XML, SOA and web services
ArticleID=394485
ArticleTitle=Build a pureXML application in DB2 for z/OS, Part 2: Web enablement through Universal Services
publish-date=06042009