How to Build a WSDL and What to Do With It
WSDLs provide technical documentation for a Web service much like an RPG prototype documents a subprocedure.
When I started learning about Web services, I thought WSDLs were just a lot of overhead. But now I see they provide a nice level of technical documentation for a Web service—much like how an RPG prototype documents a subprocedure. Most people have probably heard of a WSDL but wouldn’t know where to start if they were tasked with creating one from scratch or, even more importantly, know what the XML data in WSDL documents looks like. This article guides you through building a WSDL from scratch and generating XML instances for the request and response.
Before getting too much further, let’s declare the scenarios for the two basic approaches to Web services: Either you need to connect to a Web service created by someone else or you’re being asked to create one to which others can connect. For our purposes, I’ll explain the latter to provide the RPG programmer with the best approach for how to offer a Web service on the IBM i platform. I’ll also share free software you can use to fully describe your Web service to the outside world.
Let’s say you’ve just been asked to provide an XML Web service for .NET programmers on your staff that will let them look up prices. In this scenario, all of the item information resides on the IBM i and your goal is to use RPG to offer up the Web service.
Your first step is no different from when you create a service program with exported subprocedures for another RPG programmer to call: Determine your input and output data. This can be trickier when your I/O is communicating with non-IBM i native languages because a string variable in .NET is potentially much different from the same string variable on i. For example, the input for our Web service is going to be itemId and custNbr. We could say the itemId is just a string, but in reality it’s a string with a set length—let’s say 15. This detail needs to be accounted for when specifying the I/O in the WSDL and XML schema definition (XSD).
The following RPG prototype exemplifies the concept of data we want to pass in and out:
D Item_calcPrice pr
D pCustNbr 10i 0 value
D pItemId 15a value
D pUnitPrice 7p 2
D pError 100a
Because VALUE is specified on the pCustNbr and pItemId, the data is obviously inbound only, and because VALUE is left off pUnitPrice and pError, we know those are output-capable parameters. If you were to hand this to .NET programmers, they most likely wouldn’t have the slightest idea of how to proceed because you aren’t speaking their language, and that’s where a WSDL comes into play.
Creating a WSDL From Scratch
A WSDL has text content that describes various things, including input and output parameters, similar to what the aforementioned Item_calcPrice prototype declares. In my opinion, a WSDL doesn’t really make sense until you develop one yourself. The content of a WSDL file is very complex compared with an RPG prototype, and that’s why I recommend downloading the Eclipse Integrated Development Environment (IDE), as it has a graphical drag-and-drop interface to help create a WSDL.
Download “Eclipse IDE for Java* EE Developers” from the Eclipse Downloads Web page (www.eclipse.org/downloads). We need this version as it includes the XML-, WSDL- and XSD-related editors. You could download the base Eclipse and install the Web Standard Tools plugin to get what you need, but simplicity rules and that’s why I recommend the Java EE version even though we’ll be doing zero Java coding.
Describing how to successfully create a WSDL with a GUI tool using words is like trying to convince a police officer that your mug contains only coffee after he pulled you over for “crossing the white line multiple times.” (Don’t ask.) Instead, I’ll give a high-level overview and provide you with to a video tutorial (http://tinyurl.com/52j7e2) that details it more fluently. The general steps in creating a WSDL in Eclipse are: