07/11/12 www.ibmsy stemsmag.com/CMSTemplates/IBMSy stemsMag/Print.aspx?

path=/ibmi/dev eloper/gener
www.ibmsy stemsmag.com/CMSTemplates/IBMSy stemsMag/Print.aspx?path=/ibmi/dev eloper/gener
close window
Print
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.
December 2008 | by Aaron Bartell
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
servicemuch like how an RPG prototype documents a subprocedure. Most people have
probably heard of a WSDL but wouldnt 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, lets 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 youre being asked to create one to which others can connect. For our purposes, Ill
explain the latter to provide the RPG programmer with the best approach for how to
offer a Web service on the IBM i platform. Ill also share free software you can use to
fully describe your Web service to the outside world.
Lets say youve 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 its a string with a set
lengthlets 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:
07/11/12 www.ibmsy stemsmag.com/CMSTemplates/IBMSy stemsMag/Print.aspx?path=/ibmi/dev eloper/gener
2/5 www.ibmsy stemsmag.com/CMSTemplates/IBMSy stemsMag/Print.aspx?path=/ibmi/dev eloper/gener
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
wouldnt have the slightest idea of how to proceed because you arent speaking their
language, and thats 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 doesnt really make sense until you develop one yourself. The
content of a WSDL file is very complex compared with an RPG prototype, and thats 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 thats why I recommend the
Java EE version even though well 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. (Dont ask.) Instead, Ill 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:


1 . Unzip the Eclipse download and double-click eclipse.exe in the unzipped folder.
2. Create a project named My FirstWSDL.
3. Create a file named calcprice.wsdl.
4. Double-click to open calcprice.wsdl.
5. Right-click in white space to add a port ty pe named CalcPricePortTy pe.
Rename the operation in CalcPricePortTy pe to be CalcPriceOperation.
Add the input parameters and name them itemId and custNbr.
Add the output parameters and name them unitPrice and error.
6. Right-click in white space to add a serv ice named CalcPriceServ ice.
Rename the port CalcPricePort.
07/11/12 www.ibmsy stemsmag.com/CMSTemplates/IBMSy stemsMag/Print.aspx?path=/ibmi/dev eloper/gener
3/5 www.ibmsy stemsmag.com/CMSTemplates/IBMSy stemsMag/Print.aspx?path=/ibmi/dev eloper/gener
Specify the URL of where the RPG program will reside on the IBM i.
7 . Create a new binding v ia the drop-down box in the Properties tab named
CalcPriceBinding.
In the binding tab, select the PortTy pe of CalcPricePortTy pe to bind to.
Select the Generate Binding Content button and specify that this is a SOAP-based
Web serv ice.
8. Done! The WSDL is complete and can be uploaded to a folder on the IBM i that Apache is
serv ing up to the browser.
These steps are fairly straightforward, but whats actually happening needs some
explanation. The first thing we did was create a port type with an operation and
input/output parameters. Think of this as similar to our RPG prototype for Item_calcPrice.
Think of the port type as analogous to the service program, the operation as analogous
to the subprocedure name, and the input/output parameters as analogous to the D-
spec parameters list on our prototype. All of step 5 boils down to conveying the same
thing we have in the RPG environment, just using a different syntax.
Step 6 details the location of the Web service. When dealing with Web services, the
location is denoted with a URL. This could be thought of as analogous to how to specify
the exact location of an RPG service program with the library/object notation.
Step 7 doesnt necessarily relate to the RPG environment because its declaring the
enveloping method and transport to use for this Web service. In this case, the
enveloping method is SOAP and the transport is HTTP. It should be stated that most
Web services that involve a WSDL use SOAP as the enveloping mechanism and HTTP for
transport, so you dont have to worry about deciding what should be used in the
binding portion. A little further into this article, Ill provide a generalization of SOAP to
show why it adds unnecessary bloat and complexity. The other purpose of the binding is
to connect the service (i.e., CalcPriceService) and port type (i.e., CalcPricePortType).
The last step was to publish the WSDL file so other programmers (i.e., .NET personnel)
could access it. One of the most common approaches to publishing a WSDL is to place it
on an HTTP server as in this example, but its also acceptable to e-mail it as an
attachment. The developer on the other end would then save the attachment to the
hard drive and work with the WSDL from there. One of the first things most .NET/Java
developers will ask you is, Where is your WSDL? Now you know how to create one
and where to put it so they can access it.


I Have a WSDL. Now What?
The next major part of this article has to do with learning what a WSDL does for you
once its created. More importantly, RPG programmers want to know exactly what datas
coming into our program and what data needs to go out. In the case of Web services,
we need to know the structure of the input XML so we know how to parse it, and we
need to know the structure of the outbound XML so we know how to compose it. Once
youve created a WSDL, a tool called soapUI can generate an example input and output
XML document for RPG programming purposes.
The non-professional version of the soapUI tool (www.soapui.org) is free and open
source. To date, its served all of my needs so I havent done an in-depth review of the
professional version. I use soapUI mainly to create XML instances and invoke my SOAP-
based RPG programs for testing purposes.
Again, the goal of this section is to get an instance of an inbound and outbound XML
document so we know how to parse and compose the XML respectively, and what
better way to see that happen with a graphical tool than with another video tutorial
(http://tinyurl.com/3tn9qn) and the following high-level points describing it:
1 . Download and install soapUI.
2. Start soapUI and create a project, ensuring that y ou specify the URL of the calcprice.wsdl
residing on y our IBM i. If y ou didnt want to publish it to y our i y ou can browse for it on
y our local hard driv e.
3. Open the generated request XML instance.
4. Manually generate a response XML instance.
In steps 3 and 4, you effectively have the raw XML thats being passed into and out of
your yet-to-be-created RPG Web service. Its in these steps that we can see the SOAP
envelope. In the end, SOAP adds more bloat than anything for most Web services. For
example, heres the entire SOAP request:
< soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:cal="http://www.example.org/calcprice/" >
< soapenv:Header/ >
< soapenv:Body >
< cal:CalcPriceOperation >
< itemId > HAT123 < /itemId >
< custNbr > 115523 < /custNbr >
< /cal:CalcPriceOperation >
< /soapenv:Body >
< /soapenv:Envelope >

And heres what we could whittle the XML request down to if we chose not to go with
SOAP:

< CalcPriceOperation >
< itemId > HAT123 < /itemId >
< custNbr > 115523 < /custNbr >
< /CalcPriceOperation >
SOAP has many features other than just acting as an enveloping mechanism, but
adoption of those other features has been so minimal that it hardly warrants the extra
07/11/12 www.ibmsy stemsmag.com/CMSTemplates/IBMSy stemsMag/Print.aspx?path=/ibmi/dev eloper/gener
5/5
processing SOAP incurs on the client and server sides.
Once you complete all of these steps, you can start coding your RPG to receive in the
XML from an HTTP POST, parse the XML to learn what data was sent, make any
necessary business-logic calls or file accesses to validate the data, and finally compose
the XML response. You can solve these steps by writing your own code, making use of
free tools like CGIDEV2 (for XML composing), using IBMs tools (i.e., XML parsing as of
IBM i 5.4 and now in 6.1) or purchasing a commercial product.
Kick Start
I hope this article has given you a nice kick-start in learning how WSDLs and their
corresponding generated XML can be more easily disseminated. Feel free to drop me a
line with questions or suggestions on topics youd like addressed further.

I BM Systems Magazine is a trademark of I nternational Business Machines Corporation. The editorial content of
I BM Systems Magazine is placed on this website by MSP TechMedia under license from I nternational Business
Machines Corporation.
2012 MSP Communications, I nc. A ll rights reserved.