The RPG-XML Suite developers at Krengel Tech have been at it again! This month's idea came from thinking about another real-world use for web services — sending packages via carriers like FedEx and UPS.
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
The steps are as follows:
Download the fdx_av_req.tpl template file
- 1. Download the source for the FDXAV module, the source for the FDXCP copybook,the FDXAVTR program and the FDXAVTD display file. You can copy them to any source file, but for the purposes of these instructions, I'm assuming you're copying them into the default source files - QRPGLESRC and QDDSSRC.
- 2. Ensure that you have the RPG-XML Suite installed and licensed and that the RXSSV service program is in a binding directory, so it can be referenced during the compilations — I have a binding directory called RXSBND which contains an entry for the RXSSV service program
- 3. Compile the FDXAV module and create the FDXSV service program using the following commands:
CRTRPGMOD MODULE(library-name/FDXAV) SRCFILE(library-name/QRPGLESRC) DBGVIEW(*ALL)
CRTSRVPGM SRVPGM(library-name/FDXSV) MODULE(library-name/FDXAV) EXPORT(*ALL) BNDDIR(RXSBND QC2LE) ACTGRP(*CALLER)
After the FDXSV service program has been created, the FDXAV module can be deleted. Note that FDXSV also needs to be added to the RXSBND binding directory so it can be resolved at compile time. To add FDXSV simply type WRKBNDDIRE RXSBND and add it.
- 4. Compile the FDXAVTD display file using the following command:
CRTDSPF FILE(library-name/FDXAVTD) SRCFILE(library-name/QDDSSRC) RSTDSP(*YES)
- 5. Compile the FDXAVTR program using the following command:
CRTBNDRPG PGM(library-name/FDXAVTR) SRCFILE(library-name/QRPGLESRC) DBGVIEW(*ALL) OPTION(*NODEBUGIO) DFTACTGRP(*NO) BNDDIR(RXSBND QC2LE) ACTGRP(*CALLER)
into the IFS (for a typical RPG-XML Suite installation, this will be into the '/www/myrxs/templates/' directory).
That's all there is to it! Now you can call FDXAVTR interactively or you can write your own programs to use the FDX_verifyAddress() procedure. Stay tuned in the coming months for many more examples of how you can continue to utilize XML within your business!