RPG-XML Suite (RXS) is an incredibly flexible toolkit, allowing developers to create and consume web services on the IBM i using 100% native RPG.
In this article, we demonstrate how to utilize a real-world web service to accomplish a common business task – address validation using FedEx provided web service APIs and RXS. At the end of the article, links to the source code for the service program, the copybook, display file, and program can be found, along with a ZIP file containing the source code and instructions for how to get up and running.
Often we have applications where we need to enter an address for customer or supplier. However, what we have on file might be incomplete or might not be a correctly formatted address as far as shipping companies are concerned. Using this ‘incorrect ‘ address can lead to shipping delays or even packages being lost. So we went ahead and fixed this problem for you!
Basically we wrote a service program around the “FedEx Ship Manager API/Direct Address Verification XML Transaction”. Despite its long name, this is simply a web service provided by FedEx which you can use to verify an address. The web service returns a list of up to 10 addresses which match the address or partial address you supply. These addresses are in the correct format for FedEx (and for the United States Postal Service), including full 5+4 zip codes, standardized abbreviations (Rd, St, Apt etc.), capitalization etc. This service program is called FDXSV and has a single exported procedure — FDX_verifyAddress().
We also created a separate interactive green-screen program called FDXAVTR which you can use to call FDX_verifyAddress() from a command line. When you call it, this program displays an entry screen where you type in as much address information as you have, calls FDX_verifyAddress() and then displays a subfile of matching addresses. You can also integrate this program into your existing applications easily, passing an ‘address’ structure directly to it and returning a selected address. No longer will you worry about customer addresses being incorrect! This web service works for any US address, including Puerto Rico, to which FedEx delivers (so it doesn’t include P.O. boxes).
In fact, you can simply use this program to update or check your customer addresses, even if you’re not sending packages out. As an example, let’s suppose the following conversation:
Your boss: “Where’s Krengel Tech’s office? I need to send them a gift basket.”
You: “Um… Er… It’s ‘600 shady’ something — Road, Avenue, Street… Oh, and the city is called Hutchinson. Or maybe it’s Hutchenson. Or maybe it’s Hutchingson … I know it’s in Minnesota…”
Your boss: “That’s not good enough. Get me the answer, now!”
Now of course, you could go to the Contact page on www.rpg-xml.com and get it from there (it’s 600 Shady Ridge Road, Hutchinson, MN 55350, by the way). Alternatively, you could call FDXAVTR and enter only the information you know – “600 shady, hutch, mn”.
Pressing Enter calls the FDX_verifyAddress() procedure which calls the FedEx web service, which returns a list of matching addresses, which FDXAVTR displays in a nice subfile:
In this case, there’s only a single matching entry. Taking subfile option 5 against the returned entry displays the detail screen with any messages related to the address match:
In this case, the FedEx web service didn’t just verify the address you entered — it modified it (i.e. the data it returned isn’t the same as the data you entered – the web service has completed the street address using the USPS standard “Rd” abbreviation for “Road”, added the “NW”, determined that the city is, in fact, Hutchinson and supplied the 5+4 zip code. Pretty nifty, eh?
The FedEx web service can actually return up to 10 results. If we enter a more generic address, such as “120 park, san fran, CA”, this is the subfile that is displayed:
As you can see, the FedEx web service has been more ‘generous’ when it comes to returning results. Since ‘san fran’ doesn’t directly match a city name, it’s returned a list of cities that have similar names. The same goes for the street address. Since there isn’t a street called ‘park’, it’s returned a number of matches which it thinks might fit. Some of the records are displayed in red because they have warnings associated with them. If I select the 6th record (“120 Parker Avenue”) for display, you can see that the warning is about the fact that an apartment number is required:
We’re providing the source to both the FDXSV service program and the FDXAVTR interactive program. Note that we might be updating the FDXSV service program in the future to provide more functionality with other FedEx web services, so consider this an initial version. They are pretty simple and compile using the instructions below. Obviously using the FDXSV service program relies on you having the RPG-XML Suite already loaded.
Download the source code and README to get up and running, or view the source code below.
One Response