If, as an RPG programmer, you happen to dabble with any sort of Web interface, you’ve most likely heard of Asynchronous JavaScript and Extensible Markup Language (XML), better known as AJAX. At the moment, there’s quite a buzz about AJAX, with opinions varying from “another flash in the pan” to “the greatest thing since sliced bread.” As usual, the truth probably falls somewhere in between. But AJAX does have plenty to offer RPG programmers who write programs for the Web.

This article (the first of two) provides an overview of AJAX and its background, and it shows how to use AJAX in conjunction with RPG Common Gateway Interface (CGI) programs. When used in conjunction with CGI programs, AJAX uses asynchronous calls to “update” the page while the user is working. So there is no delay or “white page” while the user waits for a response from the server.

This article compares the AJAX technique with the traditional process for calling a CGI program. Part II will discuss more practical uses of AJAX as well as ways to make the technology even easier to use.

What is AJAX?

AJAX is not a programming language. It is primarily a collection of techniques that enable a program to communicate with a server from within a Web page. These techniques make use of standard JavaScript objects to asynchronously retrieve data from a server, so you must become familiar with JavaScript code to use AJAX. The data is retrieved from the server as XML, Hypertext Markup Language (HTML), or plain text (it is easier to start with plain text and HTML).

AJAX allows programmers to dynamically update the existing Web page, which means that the server updates the current Web page rather than load a new page. It also allows the Web page to transmit small amounts of information to and from the server as opposed to full pages.

For AJAX to work, JavaScript must be enabled in the browser. This is probably the largest hindrance to using AJAX, especially if you are deploying AJAX-enabled applications in an Internet environment where you cannot specify the client’s browser configuration.

All of the JavaScript objects required for AJAX are part of the browser. Additional plug-ins or downloads are not required, but there are many useful JavaScript functions (known as frameworks) available for AJAX that you’ll probably want to take advantage of (more about frameworks in the next article).

How was AJAX born?

In Web terms, the techniques used with AJAX are “old”; they have been around since the late 1990s. They are a result of a progression of techniques used in Hidden Frames, IFrames, Dynamic HTML (DHTML), and XMLHTTP.

Most of these techniques were pioneered by projects at Google Labs. For example, Google Suggest uses AJAX to provide a list of search suggestions as you type into the search box, and Google Maps uses AJAX to allow you to scroll through a map (parts of the map are retrieved as you scroll) or it uses AJAX to show details of an item on a map as a pop-up.

But where did the term AJAX come from? In February 2005, Jesse James Garrett of Adaptive Path, LLC published “Ajax: A New Approach to Web Applications,” in which he coined the term AJAX. According to Garrett:

Google Suggest and Google Maps are two examples of a new approach to Web applications that we at Adaptive Path have been calling AJAX. The name is shorthand for Asynchronous JavaScript + XML, and it represents a fundamental shift in what’s possible on the Web.

The article led to a wave of articles, code samples, and debates about AJAX. Suddenly, everyone was talking about AJAX.

The other main contributor to the success and rapid adoption of AJAX was the increase of broadband usage. Google Maps would not have succeeded on dial-up alone!

Why is AJAX so popular?

The popularity of AJAX cannot be attributed to a catchy turn of phrase in an article. Naming the techniques may have provided a focus, but that in itself is not enough to make programmers use it.

The following are some of the components that led to the success of AJAX:

• All of the required objects are part of the browser (nothing to buy or install).
  
  
• AJAX provides capabilities formerly available only through server-side scripting (e.g., JavaServer Pages), Java applets, or ActiveX controls.
  
  
• PCs are now more powerful; faster processors and more memory allow programs to run faster.
  
  
• Broadband provides the communications speed and satisfies any volume requirements.
  
  
• There is no longer a myriad of browsers. The industry seems to have standardized on Internet Explorer (IE), Firefox, and Opera (or at least requirements are defined by these three browsers).
  
  
• There are numerous frameworks available that simplify AJAX implementation and use.
  
  
• The Web is full of examples of AJAX in action.

Requirements for working with AJAX

What are the skill requirements for the RPG programmer working with AJAX?

On the server side (i5, iSeries, AS/400), you must know CGI programming. The easiest way to integrate CGI with RPG is to use IBM’s CGIDEV2 toolkit, which is what the following examples use. If you’re unfamiliar with CGIDEV2, please see the “References” section at the end of the article.

On the PC side, you must have the following requirements:

• Knowledge of HTML
  
  
• Knowledge of JavaScript or VBScript
  
  Note: The Web provides lots of material (books and articles) and samples for working with these languages. They are not the easiest of languages and can be very frustrating — especially when you are debugging code. Also, when it comes to debugging JavaScript, I find the JavaScript console in Firefox to be more useful than the one in IE.
  
  
• Knowledge of how the JavaScript objects for AJAX work
  
• JavaScript-enabled browsers
  
  Note: Such browsers are a major consideration if you are developing for the Web in an area where you do not depend on the method clients use to configure their browsers. In these circumstances, your application must take into account that AJAX may not be working (e.g., if you’re using AJAX to validate data as users enter it, you should still perform full validation when a form is submitted).

You may also want to become familiar with XML, but only if you plan to make full use of AJAX. It definitely is not a requirement, especially in the beginning.

Programmers working with AJAX must master JavaScript. The use of AJAX techniques will either make very little difference to the RPG side or greatly simplify the programs you write.

Traditional CGI process

Before looking at AJAX, let’s examine the traditional process for calling a CGI program:

1. A user enters data in a Web page displayed in a browser.
   
   
2. The user clicks a Submit button (or hyperlink), and the data is sent to the server.
   
   
3. The Web page is now locked as it waits for a response.
   
   
4. The server calls a script — in this case, an RPG IV CGIDEV2 program.
   
   
5. The program performs whichever process it was designed for (validation, business logic, database access, etc.). This will usually be a small program or procedure designed to perform a simple task.
   
   
6. The program generates an HTML document and writes it to the server.
   
   
7. The server sends the Web page to the browser.
   
   
8. The browser displays a new Web page.

CGI and AJAX process

The CGI process with AJAX is as follows:

1. A user enters data in a Web page displayed in a browser.
   
   
2. An AJAX routine asynchronously sends data to the server.
   
   
3. The Web page is not locked, and the user keeps on working.
   
   
4. The server calls a script — again, an RPG IV CGIDEV2 program.
   
   
5. The program performs whichever process it was designed for (validation, business logic, database access, etc.).
   
   
6. The program generates data (text, HTML, or XML) and sends it to the server. This time the program generates only “data” and not a complete document.
   
   
7. The server sends the data to the browser.
   
   
8. The AJAX routine in the browser receives the returned data, processes it, and displays the results to the user.

The user’s Web page may be updated dynamically. Not only may data be inserted in the page, but the received data also may be used to determine if items should be enabled, disabled, displayed, and so on.

AJAX and RPG programming: The XMLHttpRequest object

AJAX is implemented through JavaScript’s XMLHttpRequest object, which provides a set of methods (functions) and variables that allow a Web page to send data to and receive data from a server. To enable an AJAX conversation between the browser and the server, your Web page must first instantiate an XMLHttpRequest object. This is where you hit the first problem with AJAX. The exact object used depends on which browser is being used. The XMLHttpRequest object is supported by all current browsers, but in releases of IE prior to version 7, support is through a Microsoft proprietary interface (ActiveX objects); luckily, that interface is 100% compatible with XMLHttpRequest.

You use the XMLHttpRequest object’s open() and send() methods to “call” an RPG program, making the request in the same format as any CGI request on a hyperlink or in a form.

The XMLHttpRequest object’s onreadystatechange, readyState, status, and responseText variables are used to determine the data received from the server, and you code a function to process it.

This complete process of issuing the call and receiving and processing the returned data is asynchronous.

The RPG program is like any other CGI program except in the format and content of the data returned. But you will find yourself writing programs in a different way for multiple AJAX calls (e.g., the same program may be called multiple times, performing a different field validation on each call).

Example of AJAX at work

Let’s look at a very simple example that uses AJAX to retrieve the description for an entered product code. Figure 1 shows the Web page initially displayed to the user, and it also shows the contents of the page after the user has entered a product code and the server has retrieved a description. The purpose of this example is to show you the basic mechanics of the AJAX process. In Part II of this article, you’ll see more practical applications of the process. To follow along with the present example, install the download files now. You can download these files at www.iseries400experts.com/aej/downloads.jsp. Refer to the sidebar “Installing the AJAX examples” for instructions.

Figure 1	A simple example of AJAX at work

In a nutshell, the example has two RPG CGI programs: AJAX1 sends the Web page to the browser, and AJAX2 processes the request. It also has two HTML pages: ajax1.html is the requesting HTML document, and ajax2.html is the response document that returns to the ajax1.html requesting document. This simple example contains many bits and pieces, so let’s review the process step by step before diving into it:

1. A user enters a product code in a Web page (ajax1.html) and moves the cursor off the field.
   
   
2. A JavaScript function to call a server is automatically invoked.
   
   
3. A second JavaScript function to instantiate an XMLHttpRequest object is invoked.
   
   
4. An open() method identifies the CGI program to call (AJAX2) along with the parameter to pass.
   
   
5. The complete value (the contents of ajax2.html) returned from the CGI program is placed in the div section in the ajax1.html document.
   
   
6. The server updates the Web page currently displayed rather than a new page.

Let’s now look at the HTML and JavaScript portions of the requesting document, the RPG program that processes the request, and the HTML data the program returns.

The HTML portion of the requesting document

Figure 2 shows the source code for the requesting HTML document (ajax1.html). The important points to note are as follows (refer to the corresponding numbers in Figure 2):

1. An RPG CGIDEV2 program (AJAX1 shown in Figure 3) sends the page to the browser — hence the $top$ and Content-type at the start of the page.
   
   
2. The JavaScript functions — createXMLHttp() and callServer() — have been removed for clarity (more in a moment).
   
   
3. The definition of the prodcd entry in the form specifies that the callServer() function should run when the contents of the field change. This means that the callServer() function is called when a user enters a value and moves the cursor out of the field (using the keyboard or the mouse).
   
   
4. The contents of the div delimiters (id=“prods”) are updated with the value returned from the AJAX call to the server.

<!-- $top$ --> (1) Content-type: text/html <script TYPE="text/JavaScript"> (2) <!-- Definition of JavaScript functions createXMLHttp() & callServer() here --> </script> <html> <head> <title>Simple example of AJAX at Work</title> </head> <body> <a href="/ajax/ajax0">Menu</a> <center><h1>Ajax at Work!</h1> <h2>Simple example of AJAX at Work</h2></center> <p>Enter a valid product code (0000001) and the description is displayed </p> <table border=0> <tr><td>Product Code: <input type="text" id = prodcd name=prodcd size=7 maxlength=7 onChange="callServer()"></td> (3) <td><div id="prodds" ></div></td> (4) </tr> </table> </body> </html>

Figure 2

The source code for an AJAX-enabled HTML page (ajax1.html)

Figure 3 shows the source code of the AJAX1 RPG program that simply loads and writes the ajax1.html document shown in Figure 2. You don’t have to write the page from a CGI program; it could just as easily be a static Web page, but it is included here to highlight some of the standard CGIDEV2 features (refer to the corresponding numbers in Figure 3):

1. The binding directory ALLBNDDIR contains entries for the Hypertext Transfer Protocol (HTTP) service program QZHBCGI (containing the CGI APIs) and the CGIDEV2 service program CGISRVPGM2 (containing the CGIDEV2 subprocedures).
   
   
2. Copy directives include the PROTOTYPEB and USEC members required to use CGIDEV2 procedures.
   
   
3. When the server loads the external HTML document, the default delimiters for the sections in the document are changed to '<!-- $' and '$ -->' and the default delimiters for variables are changed to '<!-- %' and '% -->'.

H Option(*SrcStmt:*NoDebugIO) (1) H DftActGrp(*No) ActGrp('AGCGI') BndDir('ALLBNDDIR') (2) /Copy PROTOTYPEB /Copy USEC /Free (3) gethtmlIFS('/ajaxdocs/ajax1.html':'<!-- $':'$ -->': '<!-- %':'% -->'); wrtSection('top *fini'); Return; /End-Free
Figure 3	The source code for the RPG program (AJAX1) that writes ajax1.html

The JavaScript portion of the requesting document

Next, let’s look at the two JavaScript functions that will do all of the work: createXMLHttp() and callServer(). These are the two JavaScript functions coded between the script tags at the start of the ajax1.html document shown in Figure 2.

The createXMLHttp() function

Figure 4 shows an example of a JavaScript function used to instantiate an XMLHttpRequest object. The createXMLHttp() function returns an XMLHttp-Request object, but it must first determine which type of object is supported by the browser. The function checks if an XMLHttpRequest object is available. If an object is not available, the function loops through the list of proprietary ActiveX objects.

function createXMLHttp() { if (typeof XMLHttpRequest != "undefined") { return new XMLHttpRequest(); } else if (window.ActiveXObject) { var aVersions = ["MSXML2.XmlHttp.5.0","MSXML2.XmlHttp.4.0", "MSXML2.XmlHttp.3.0","MSXML2.XmlHttp", "Microsoft.XmlHttp"]; for (var i = 0; i < aVersions.length; i++) { try { var oXmlHttp = new ActiveXObject(aVersions[i]); return oXmlHttp; } catch (oError) { } alert("Could not connect"); } } throw new Error ("Could not create an XMLHttp object"); }

Figure 4

The createXMLHttp() function creating an XMLHttpRequest object

Even though you have to write this function only once (it is the same in all documents using AJAX), the good news is that somebody else has already done the work, so there’s no point in reinventing the wheel. In the next article, we’ll discuss using some of these freely available routines, but for the sake of demonstration, let’s stick with the createXMLHttp() function shown in Figure 4.

The createXMLHttp() function will be called from the callServer() function, which is described next.

The callServer() function

The callServer() function shown in Figure 5 does all of the AJAX work. This function sends the entered product code to the AJAX2 program and puts the response in the div section identified by the prods id. The important points to note are as follows (refer to the corresponding numbers in Figure 5):

1. The value of the variable prodcd is set to the value entered for the field in the form.
   
   
2. The value of the variable URL identifies the CGI program to call. The URL is constructed the same as any CGI call — this example calls the program AJAX2 and passes a parameter for the product code and the value entered. Values for parameters must be encoded, which does not happen automatically as it does on a normal CGI call from a hyperlink or a form, so you must use the escape() or the encodeURI Component() function to encode the values (both are standard, with escape() being the older of the two).
   
   
3. The xmlHttp variable is the XMLHttpRequest object that is instantiated through use of the createXML-Http() function. The methods and variables of this object will perform the AJAX communication.
   
   
4. The open() method takes three parameters: the method for sending the request (GET or POST), the URL, and an indicator that is true for asynchronous and false for synchronous. The open() method does not actually send the request; it simply identifies the connection (much like opening a file in a program).
   
   
5. The onreadystatechange attribute identifies the function to run when the server sends a reply.
   
   
6. When the readyState is completed (value of 4) and the status is success (value of 200), then the code sets the contents of the div section (identified by the id of prods) equal to the responseText value returned from the server.
   
   
7. The send() method sends the request. There is no delay in the browser — the request runs in the background. The onreadystatechange function runs automatically when the server returns data.

<code>function callServer() { (1) var prodcd = document.getElementById("prodcd").value; (2) var url = "/ajax/AJAX2?prodcd=" + escape(prodcd); (3) var xmlHttp = createXMLHttp(); (4) xmlHttp.open("GET", url, true); (5) xmlHttp.onreadystatechange = function() { (6) if (xmlHttp.readyState == 4) { if (xmlHttp.status == 200) { document.getElementById("prodds").innerHTML = xmlHttp.responseText; } else { alert("An error occurred trying to contact the server."); } } } (7) xmlHttp.send(null); }</code>

Figure 5

The createXMLHttp() function creating an XMLHttpRequest object

Obviously, the real work is done in step 6 when the data returned from the server is processed (in this case, the data is simply some HTML text).

The readyState may have a value of 0=Un-initialized, 1=Loading, 2=Finished Loading, 3=Retrieving Data, or 4=Completed.

The status may be one of the standard server status codes: 404=Not Found, 501=Not Authorized, and so on.

The called program

Figure 6 shows the RPG CGI program (AJAX2) that processes the AJAX request. It is a very simple program that performs the following (refer to the corresponding numbers in Figure 6):

1. Loads the external HTML document
   
   
2. Retrieves the product coded passed on the query string
   
   
3. Retrieves the requested record from the product file
   
   
4. Applies an error message to the description if the product was not found
   
   
5. Sets the value of the description in the Web page
   
   
6. Writes the document

<code>H Option(*SrcStmt:*NoDebugIO) H DftActGrp(*No) ActGrp('AGCGI') BndDir('ALLBNDDIR') FProduct1 IF E K Disk ExtFile('AJAXLIB/PRODUCT1') /Copy PROTOTYPEB /Copy USEC D SavedQryStr S 2000A Varying /Free (1) gethtmlIFS('/ajaxdocs/ajax2.html':'<!-- $':'$ -->': '<!-- %':'% -->'); wrtsection('top'); If ZhbGetInput(SavedQryStr: QUSEC) > 0; (2) ProdCd = ZhbGetVar('prodcd'); (3) Chain ProdCd Product1; If Not %Found(Product1); (4) ProdDs = '*** Product Not Found ***'; EndIf; (5) updHTMLvar('prodds':prodds); wrtsection('datarow'); EndIf; (6) wrtSection('end *fini'); Return; /End-Free</code>

Figure 6

The source code for the RPG program (AJAX2) that processes the AJAX request

Data returned

The CGI program (AJAX2) that the AJAX process calls returns an HTML document. Figure 7 shows the external HTML document (ajax2.html) that loads in the browser (shown in Figure 6). Even though it is not a new page that displays, the Content-type is still required at the start of the page. The CGI program will place a product description in the area identified by <!-- %prodds% -->.

<!-- $top$ --> Content-type: text/html <table border=0> <!-- $datarow$ --> <tr><td><!-- %prodds% --></td></tr> <!-- $end$ --> </table>
Figure 7	The HTML returned by the AJAX2 CGI program

The server returns this complete document to the ajax1.html document in the browser and places it between the prodcd div delimiters.

Conclusion

Now you know what AJAX is, how to code it in an HTML document, and how to take care of the request on the server side using an RPG program and CGIDEV2.

In Part II of this article, you’ll see how to make AJAX processing even easier to code in the HTML document, learn a little about frameworks, and consider a more practical implementation of AJAX.

Installing the AJAX examples To install the AJAX examples, follow these steps: Install CGIDEV2 on your system (if it’s not already installed). Create two save files: AJAXLIB and AJAXDOCS in QGPL. FTP the download files ajaxlib.savf and ajaxdocs.savf to the corresponding save files created in step 2. Restore the AJAXLIB library: RSTLIB SAVLIB(AJAXLIB) DEV(*SAVF) SAVF(QGPL/AJAXLIB) Create the AJAXDOCS directory in the root file system: MD DIR('/ajaxdocs') Restore the AJAXDOCS directory: RST DEV('/QSYS.LIB/QGPL.LIB/AJAXDOCS.FILE') OBJ(('/ajaxdocs/*')) Duplicate the required CGIDEV2 objects to AJAXLIB: CRTDUPOBJ OBJ(CGISRVPGM2) FROMLIB(CGIDEV2) OBJTYPE(*SRVPGM) TOLIB(AJAXLIB) CRTDUPOBJ OBJ(CGIDEBUG*) FROMLIB(CGIDEV2) OBJTYPE(*ALL) TOLIB(AJAXLIB) DATA(*YES) Change the current library to AJAXLIB. Compile the programs AJAX0, AJAX1, and AJAX2 in QRPGLESRC. Ensure that the profiles QTMHHTP1 and QTMHHTTP have authority to AJAXLIB and all objects in it. Ensure that the profiles QTMHHTP1 and QTMHHTTP have authority (*RWX) to AJAXDOCS and everything in it. Configure an HTTP server or change an existing configuration to match CGI requests for the AJAX examples, similar to the following: ScriptAliasMatch ^/ajax/(.*) /QSYS.LIB/AJAXLIB.LIB/$1.PGM <Directory /QSYS.LIB/AJAXLIB.LIB> Order Allow,Deny Allow From all </Directory> Run the examples by entering the URL to run AJAX0; for example: http://yourserver/ajax/ajax0

References Articles Jesse James Garrett, “Ajax: A New Approach to Web Applications” http://adaptivepath.com/publications/essays/archives/000385.php Bradley V. Stone, “Easy Web programming with CGIDEV2” www.iseries400experts.com/aej/article.jsp?queryString=cgidev2&article_id=33025 Bradley V. Stone, “The nine lives of CGIDEV2” www.iseries400experts.com/aej/article.jsp?queryString=cgidev2&article_id=44522 Web resources Google Maps http://maps.google.com CGIDEV2 download www-03.ibm.com/servers/eserver/services/assets/ebus_cgisrv.html Everything you need to know about CGIDEV2 www.easy400.net

Paul Tuohy CEO ComCon

Paul Tuohy has worked in application development on IBM midrange systems for more than 20 years. He was the IT Manager of Kodak Ireland and Technical Director of Precision Software. He is currently the CEO of ComCon, a System i consulting company. For 17 years, Paul has worked with IBM to deliver courses in pro-gramming and application develop ment. Paul is the author of “Re-Engineering RPG Legacy Applications,” is quoted in “Who Knew You Could Do That with RPG IV?,” and is an award-winning speaker at COMMON. Paul can be reached at tuohyp@attglobal.net.