of the source code. LIMITATION OF LIABILITY AND DISCLAIMER OF WARRANTY No representation is made that any of the programs, computer source code, commands, or configurations described and depicted in this manual and in the computer source code accompanying this manual are error-free and suitable for any application that you may develop. Aaron Bartell (author) and Rochester Initiative (publisher) make no warranty of any kind, expressed or implied, including the warranties of merchantability or fitness for a particular purpose, with regard to the information, examples, and computer source code presented in this manual and on the accompanying distribution media.<br><br> Everything provided in this manual and on the accompanying distribution media is provided cas is d. Author and Publisher shall not be liable in any event for incidental or consequential damages or any other claims, pursuant to your use of any of the techniques presented in this manual, or your use of the computer source code in programs that you develop, even if Author and/or Publisher have been advised of the possibility of such damages. i Table of Contents Chapter 1 - Introduction To XML Web Services .......................................................................1 1.1 Painting The Picture...................................................................................................1 1.2 Two Scenarios For Web Services..................................................................................1 Chapter 2 - XML................................................................................................................<br><br> ..4 2.1 Why XML?.................................................................................................................4 2.2 XML Labels Data........................................................................................................4 2.3 Mixed Content...........................................................................................................8 2.4 XML Whitespace ........................................................................................................9 2.5 XML Comments .......................................................................................................10 2.6 Lab: cWell formed d XML............................................................................................11 2.7 It Pays To Be Popular...............................................................................................15 2.8 Lab: XML tooling in Eclipse........................................................................................16 2.9 XML Namespaces.....................................................................................................19 2.9.1 Why Namespaces? ............................................................................................19 2.9.2 Namespaces In Action .......................................................................................20 2.10 XPath...................................................................................................................21 2.10.1 Namespaces and XPath....................................................................................23 2.11 What To Use 3 Elements or Attributes?.....................................................................23 2.12 Parsing XML ..........................................................................................................25 2.13 Lab: Parsing XML...................................................................................................32 2.14 Composing XML.....................................................................................................33 2.15 Lab: Composing XML..............................................................................................36 Chapter 3 - XML Schema Definitions....................................................................................38 3.1 Why XSD? ..............................................................................................................38 3.2 XSD Syntax ............................................................................................................38 3.3 Modular XSD's.........................................................................................................42 3.4 Externalizing XSD Files.............................................................................................44 3.5 Using XSD Restrictions.............................................................................................46 3.6 Generating An XML Instance .....................................................................................50 3.7 XSD vs.<br><br> DTD (Document Type Definition) ...................................................................52 3.8 Lab: Creating an XSD using Eclipse............................................................................54 Chapter 4 - HTTP 3 Transferring XML Data ...........................................................................60 4.1 What Is HTTP? ........................................................................................................60 4.2 Why HTTP? .............................................................................................................60 4.3 How Does HTTP Work?.............................................................................................60 4.4 Lab: Calling a remote web service .............................................................................63 4.5 Lab: Setup Apache for Web Services..........................................................................65 Chapter 5 - Publishing and Documenting a Web Service.........................................................71 5.1 Why WSDL?............................................................................................................71 5.2 Relating WSDL's To The RPG Environment ..................................................................71 5.3 SOAP (Simple Object Access Protocol)........................................................................76 5.4 SOAP Body content that is escaped............................................................................78 5.5 Lab: Creating an XML instance from a WSDL (manual approach) ...................................80 5.6 Lab: Creating an XML instance from a WSDL (generated approach) ...............................82 5.6.1 SOAPUI Approach .............................................................................................82 5.6.2 Eclipse Approach...............................................................................................84 5.7 Lab: Parsing XML with namespaces............................................................................88 ii 5.8 Composing SOAP XML ..............................................................................................91 5.9 Publish WSDL On Your System i ................................................................................92 Chapter 6 - Offering A Web Service.....................................................................................93 6.1 Web Service Purchase Order Add...............................................................................94 6.2 Using the Web Service Tester....................................................................................98 6.2.1 Lab: Program Doesn't Exist..............................................................................100 6.2.2 Lab: Apache Instance Not Started.....................................................................101 6.3 Lab: Using IFS files for XML ....................................................................................102 6.4 Lab: Accessing Physical Files In Other Libraries .........................................................105 6.5 LAB: Offering a SOAP based web service ..................................................................107 6.5.1 Responding With Correct HTTP Headers.............................................................111 6.5.2 Flushing The Buffer .........................................................................................111 6.5.3 IFS Template Authorities..................................................................................111 6.5.4 Sending IFS To Standard Output After Composing It ...........................................112 Chapter 7 - Calling a Web Service.....................................................................................113 7.1 Client Program Purchase Order Add .........................................................................114 7.2 Lab: Emulating a remote web service for testing........................................................118 7.3 Lab: Remote Web Service Not Available ...................................................................119 7.3.1 Lab Part 1: What happens when a web service program name changes .................119 7.3.2 Lab Part 2: What happens when a higher level domain change is made .................120 7.4 Lab: Dealing with Timeouts.....................................................................................121 7.5 Lab: Using IFS files for XML ....................................................................................123 7.6 Lab: Calling a SOAP web service..............................................................................126 Chapter 8 - Security........................................................................................................133 8.1 SSL......................................................................................................................13 3 8.2 Lab: Initial SSL setup.............................................................................................133 8.3 Lab: Installing a certificate for a Certificate Authority.................................................140 8.4 Lab: United Parcel Service and SSL..........................................................................151 8.5 HTTP Basic Authentication ......................................................................................154 8.6 Lab: Setting Up HTTP Basic Authentication................................................................155 8.7 Lab: HTTP Basic Authentication from RPG.................................................................160 Chapter 9 - A Web Service Project.....................................................................................162 9.1 Consuming A Web Service ......................................................................................162 9.2 Offering A Web Service...........................................................................................163 Chapter 10 - Appendix A 3 Debugging Web Services ...........................................................165 10.1 When offering a web service..................................................................................165 10.2 When consuming a web service .............................................................................169 10.3 Logs...................................................................................................................172 10.3.1 QTMHHTTP Spool Files and Job Logs................................................................172 10.3.2 Apache Error Log Files ...................................................................................173 10.4 Wireshark ...........................................................................................................175 Chapter 11 - Appendix B 3 Obtaining and Installing Software ...............................................178 11.1 Java Runtime ......................................................................................................178 11.2 Eclipse IDE (Integrated Development Environment) .................................................178 11.3 SOAPUI ..............................................................................................................180 11.4 RPG-XML Suite ....................................................................................................181 11.5 Web Service Tester ..............................................................................................182 11.6 WDSC (Websphere Development Studio Client) .......................................................183 11.7 TextPad..............................................................................................................184 11.8 Wireshark ...........................................................................................................185 iii 11.9 Java web service examples ...................................................................................185 Chapter 12 - Appendix C - Green Screen Stream File Maintenance ........................................186 12.1 Creating Stream Files...........................................................................................186 12.2 Editing Stream Files .............................................................................................186 12.3 Working With Stream Files....................................................................................186 12.4 Displaying Stream Files ........................................................................................187 12.5 Template File Authority.........................................................................................187 Chapter 13 - Appendix D - RPG Related XML Tools ..............................................................188 13.1 IBM XML Toolkit for iSeries....................................................................................188 13.2 IBM 9s V5R4 support for XML..................................................................................188 13.3 HTTPAPI .............................................................................................................189 13.4 CGIDEV2 ............................................................................................................189 Chapter 14 - Appendix E - Why Web Services?<br><br> ...................................................................190 14.1 When Are Web Services Right?..............................................................................190 14.2 Traditional Communication....................................................................................190 14.3 When Not To Use Web Services .............................................................................192 Chapter 15 - Appendix F - Author Biography.......................................................................194 iv Preface This training manual is my effort to find the best way to approach the subject given the typical environment an RPG programmers lives in on a day to day basis. I have lived through the trial and error research of XML web services and documented the ensuing best practices for you here so, you don't have to. This training manual is not meant to exhaust every possible definition found in the XML web services space.<br><br> Instead it will give you a roughly three day approach to learning everything an RPG programmer on the System i needs to know to successfully implement web services. I have formulated it down to such a small amount of time based on my experiences with, hundreds of organizations, programmers and projects relating to XML web services over the past six years. I have found there is an ceasy d path to web services by putting all of the right pieces in the right places.<br><br> That's the intent of this manual 3 explain in more common RPG terminology what is required to communicate via XML with a variety of applications around the world. Prerequisites and Things to Note Programming Knowledge To benefit from this System i training course the reader must have a general understanding of the RPG language and how to call RPG sub-procedures, including language features up to V5R1. Workstation Requirements 2 A Windows PC 2 Internet Explorer 5.5 or greater, or FireFox 1.5 or greater.<br><br> 2 A 5250 emulator of your choice. My preferred is TN5250j which is a free download at http://tn5250j.sourceforge.net . System i Requirements The RPG web service API's included with this manual (see next section) were compiled down to V5R1 which is the lowest OS level you will need to execute the labs and implement web services on your System i.<br><br> Note : The terms cIBM i d, cSystem i d, ciSeries d, cAS/400 d are synonymous with each other. RPG-XML Suite The labs in this text use a tool known as RPG-XML Suite, that runs natively on the System i . RPG-XML Suite is referenced in this training manual to create an abstracted environment that allows you to focus on what 9s important to easily meet real-world business requirements without the need for low-level coding.<br><br> It is a very usable set of tools that was developed over time from real-world business needs. Because I am a primary developer of RPG-XML Suite, you will find that the toolsets available in the solution follow the same paradigm as this training module. As a purchaser of this training manual you are entitled to an evaluation version of this product for your company 9s exclusive use as you learn about XML web services from RPG.<br><br> If, after you master web v services, you choose not to utilize the toolset available in RPG-XML Suite there are several alternatives that can be pieced together with additional low-level coding on your part to provide similar results. Those alternatives can be found in Appendix D at the end of this manual. Contact The Author Do you have questions or comments you would like to relay to me (Aaron Bartell)?<br><br> You can contact me at aaronbartell@mowyourlawn.com. Please put the word XML4RPG in the subject line. You can also visit my website at www.mowyourlawn.com.<br><br>

less