DesignBais Tip – Launching a URL – Part 1

I was asked by one of my clients to provide a button on a Customer Master Maintenance form which would launch a browser window to display a map showing directions from the home office to the customer being viewed. Oh boy, a challenge! This article provides info required for doing this.

As an example or what we want to accomplish, let’s say you’re flying into Chicago O’Hare International Airport, and the first thing you want to do is go listen to some real Chicago blues music at Kingston Mines. Just follow this link for directions. Now what if that was a button in your business app for your sales people, clients, truck drivers, etc (er, not to a blues club, but you get the idea. )

One might initially think that the PROCESS.STACK might launch a URL as well as a form, but there is a special variable just for launching a URL, DBCALLURL. All the documentation says is this:
DBCALLURL: Provides the ability to call a URL from any event.
Usage: DBCALLURL = "Urltocall;NewWindow"
Eg. DBCALLURL="http:\\www.google.com;newWindow"

Sure enough, just set the variable to a valid URL and RETURN back to the form, and your web page launches. That "newWindow" part isn’t even required, and if you’re having problems launching a URL it’s not (as I thought originally) because you got the casing wrong – I think that parameter isn’t used at all, so you can leave it off. More complex queries require putting more into the URL. For example, to find out what Google has to say about my company, I would type this into their text input box:

"Nebula R&D"

Note that quotes are required because the text includes a space. That results in the following query string being displayed in my browser address bar
http://www.google.com/search?hl=en&q=%22Nebula+R%26D%22&btnG=Google+Search
The information contained in there includes my preferred browser language (hl=en means english, try hl=xx-bork if you’re familiar with a popular swedish chef, or hl=xx-hacker if you’re a r34L g33K) and what button I hit to do the search (Google Search). Since the space character is not allowed in a URL, all spaces get converted to a plus sign (+). Similarly, the double-quote characters can’t be used though they are an important part of the query, so each of those is converted to a hexadecimal value preceded by a percent sign (%22). This encoding of characters is called URL Encoding, and all web servers parse query string requests in a similar manner. (More information on URL encoding is found on the "query string" page.) The ampersand character (&) separates name=value pairs. Since my query itself includes an ampersand, that character must be encoded to %26 so that it’s not confused with the other ampersands in the string.

To build a Google search query string, one needs to know exactly what parameters their server expects. Every web program is different but the name=value pairs separated by ampersands is consistent. For Google, figuring out the names is simply a matter of studying the address bar after making queries. (You can also get details from various web sites, or buy a neat book called Google Hacks.) We also then need to know how to URL-encode a query to avoid using those reserved characters. With the information found here and at many similar sites, we can find the encoded value for any ASCII character, and write a program to translate reserved characters into their %equivalents. (My code can be made available as part of a services engagement.) With a bit of parsing and concatenation in a program we are quickly able to create text strings that can be pasted into a browser to perform functions on many sites.

At this point in our quest to call a complex URL from DesignBais, we have a domain name, some name=value pairs separated by an ampersand (&), and data which has reserved characters encoded – including ampersands. But here’s a catch. A complex DBCALLURL like the following can’t be used:
DBCALLURL=
"http://www.google.com/search?hl=en&q=%22Nebula+R%26D%22"
This is because DesignBais is writing to a script in the browser, and the ampersand in the string is also a reserved character in HTML. Might the answer now be to just convert the whole string? That might result in a string like the following which most sites can’t process (though surprisingly to me, some can):
"%2Fsearch%3Fhl%3Den%26q%3D%22Nebula+R%26D%22"
So you can’t leave the ampersand in the string because DesignBais will error out, but you can’t convert the ampersand and other characters between name=value pairs to their URL encoded form either because the websites will reject the queries. What to do?

Since the problem is with HTML, we need to use a different encoding format for the ampersand and some other reserved characters in HTML. These codes may look familiar to some people : &   < > For others, here is one page of many out there with an exhaustive list of these and other codes.

So far only the un-encoded ampersand seems to be a problem, because the other characters generally aren’t used in URL’s anyway. (Don’t take that as an absolute statement, I’ll only continue to discuss the ampersand here but you may need to code for other characters. Remember that the result of a bad character in the stream is that the page the user is viewing will jump to a DesignBais error page – that’s not user-friendly.) To get around the problem I have code that works something like this:

URL="http://www.google.com/"
QUERY1 = "search?hl=en&q="
QUERY1 = SWAP( QUERY1 , \&\, \&\ )
QUERY2 = \"Nebula R&D"\
CALL URL.ENCODE(QUERY2)
DBCALLURL = URL:QUERY1:QUERY2

For our map function the solution required concatenation of FROM and TO addresses, URL encoding that data, building a simple set of other name=value pairs and converting the ampersands with HTML encoding, then putting all of that on the back end of "http://maps.google.com/". The result is a feature that’s sure to raise some eyebrows during the sales cycle for my client’s software – and I hope this tip does the same for you.

Next week I’ll post another short article (Part 2 of 2) showing how to send e-mail from the user’s PC using DBCALLURL. With the information provided in this article here, you may be able to figure that one out on your own. Go ahead and give it a shot and see if we have the same solution.

Thanks to Google for providing their free and useful mapping tools.