The WebFacing Tool, part of the Advanced edition of WebSphere Development Studio Client for iSeries (WDSCA), creates a browser interface to a 5250 application based on the display file DDS code. This first step in the Web-enabling process delivers e-business capabilities to your 5250 applications, such as remote access via the Web. Without customization, however, the new Web-enabled application lacks the appeal of typical Web applications. It simply looks like a 5250 application running in a browser.

As a starting point for the article, we show a sample 5250 screen, a Web interface created by the initial conversion using the WebFacing Tool, a Web interface customized by the tools that come with the basic version of the WebFacing Tool, and finally, a Web interface that has been leveraged and extended using the customization tools in the Advanced edition of WebSphere Development Studio.

The starting point: From 5250 to a Web interface

Figure 1 shows what the interface looks like before we start to Web-enable the application using the WebFacing Tool. When you run your display file DDS code through the initial conversion process, the WebFacing Tool generates an interface similar to that shown in Figure 2.

Figure 1. The initial 5250 green screen for order inquiry

Figure 2. The order inquiry screen after basic WebFacing

When typical green-screen users see this Web-enabled version of their application, some may be impressed with the appearance of the new interface. After all, it’s not green-on-black. Although this interface is functional, it would not be considered adequate for most organizations. Some basic changes are required to give it a more professional look:

• The company logo and colors should be integrated into the Web pages.
  
  

• The select-and-enter format of a typical green-screen application should be replaced by a mouse-click selection process.
  
  

• The screen needs the graphics and the calendar help typical of most Web applications.
  
  

Figure 3 is the same screen with some basic customizations for the Web. It has a customized style sheet with graphics added for the company logo.

Figure 4 shows the same screen, but on top of the company logo and colors, we have added calendar help for dates, graphics and pictures, and some Web extensions to the basic green-screen application. This has the look and feel of a typical Web application. Of course, in normal operation, all the pop-up windows wouldn’t be open at the same time, but this interface illustrates the customizations available with the Advanced edition of the tools.

Figure 3. The screen after customization with company style sheet and header logo

Figure 4. The screen after customization with Struts apps, calendar, and image pop-ups

Tools for customization

The before and after images of the interface demonstrate some of the potential that can be realized from the customization of your Web applications. The WebFacing Tool offers a number of customization capabilities, including:

• The ability to modify the appearance of the Web pages by using the cascading style sheets. A new style sheet can also be created with the layout model in PageBuilder to define command keys, the page header, and the application area. You can easily change the colors and integrate your company logo into the style sheet.
  
  

• The ability to customize the WebFaced with output with predefined enhancements to add hyperlinks, hide fields, add drop-down selection lists, include graphic images, and so on. You can also define enhancements, such as adding custom HTML or JavaScript. The Web settings are special comments stored in your DDS source members. You enter Web settings using the CODE Designer tool. Because these customizations are saved, when you regenerate your Web interface, the changes are automatically included.
  
  

• The ability to use Page Designer (or other Web development tools) to customize the generated JSP pages. If you reconvert your application, you need to manually add these customizations back to your generated JSP pages.
  
  

WDSCA for iSeries V5 includes the following additional new customization capabilities:

• The new Web Interaction wizard generates a Struts-based Web interface to your 5250 application. This new interface is architected so that it can be leveraged and extended with other Struts-based applications. These new Web applications can add new capabilities to your Web enabled application.
  
  

• A report service allows you to view spool files from within the Web interface.
  
  

• User-defined command keys allow you to leverage and extend the Web application with new custom services.
  
  

• Support for custom JSP tag libraries enhances the customization capabilities of the Web application. You also have the option to generate custom JSP tags.
  
  

Extend the Web-enabled application with Struts

The new WebFacing Tool wizard in WDSCA creates a Struts-based Web interface to a 5250 application built on top of the open-source Struts framework for Java Web applications from Apache (www.apache.org). This new Struts interface allows a Web-enabled application created by the WebFacing Tool to be enhanced substantially through the addition of another Web application. To understand the significance of this Struts interface, we need a quick review of Struts. For a more indepth treatment, please refer to the articles that were published in the July/August and September/October issues of iSeries 400 Experts Journal.

The Struts framework provides a service-oriented architecture for building Web applications. A Struts application that is Web-enabled with the WebFacing Tool can be extended in many ways, easily providing a strategic (as opposed to a tactical) Web application solution. The Struts platform delivers a number of benefits:

• Integration of new applications as services at deployment.
  
  
• Improved national language support.
  
  
• Less coding for a Web infrastructure.
  
  
• Support for adapting multiple client types (Web, wireless, B2B, and others).

The online help claims that Struts supports MVC2 architecture (Model – View – Controller), but Struts goes well beyond MVC2. MVC2 applications are engineered as three separate component layers:

• Model: The application model with corresponding data representation and business logic.
  
  

• View: Data presentation, providing views for user input.
  
  

• Controller: The component that dispatches requests and controls data flow using service handlers.
  
  

The Web page created by the WebFacing Tool is similar to a 5250 screen. It displays one or more record formats logically merged into a single page. For each display record format, the WebFacing Tool generates five objects used to create Web pages: Three XML beans for input data, output data, and the I/O feedback data for the display format and two JSP files for the HTML on the page and for the JavaScript embedded on the page.

The new wizard generates a simple Struts workflow with a limited number of Struts objects—the WFActionServlet servlet, ActionServlet subclasses, and Struts application controller. All requests pass through the WFActionServlet servlet and are handled by the appropriate action class. The normal flow is:

1. WebFacingAction
   
   
2. PageBuilder.jsp called as a forward from WebFacingAction
   
   
3. ScreenBuilderAction called through an include from PageBuilder.jsp
   
   
4. BuilderAction called to create the application area returned

Build the new lookup service for the Web-enabled application

To demonstrate the new capabilities, we will create a Struts service for looking up account numbers. We are making this enhancement to only the Web version of the application.

The Web tools in WDSCA make it productive to develop a Struts-based application. Some of the key Web tools used are detailed in “Boost Struts development with WDSC” in the September/October issue of iSeries 400 Experts Journal.

Here is the process to build a database account lookup service for a Web-enabled application:

1. Create a model bean to look up the account for a name.
   
   
2. Generate a Struts Web application with the Web Interaction wizard.
   
   
3. Set a command key to invoke the account lookup service.
   
   
4. Create a Web diagram to document the application.
   
   
5. Test the generated application in the WebSphere Application Server test environment.

Step 1: Create and test the model bean. As noted earlier, there are many ways to easily create Java beans that reflect entities in your business model (customer, item, etc.). You can turn databases, host programs, and XML documents into services as Java beans using the iSeries Studio tools:

• Use the Java class wizard to generate a new Java class and the editor to add the properties you want; then generate the “getter and setter” methods.
  
  

• Start with an XML document, generate an XML schema, and then generate a matching Java bean.
  
  

• Start with a DB2 table, run an XML query to generate an XML schema, and then generate a matching Java bean.
  
  

• Start with a host program (RPG, COBOL, etc.) and generate a program called bean using the Program Call wizard.
  
  

Check your Web application to be sure you have access to all the runtime libraries (JAR files) needed to execute your Java bean. The libraries can be stored on a classpath for your Web applica-tion server or within the application itself in the Web Content\Web-inf\lib folder.

In this example, we create a simple model bean— QueryCustomerAcctForName—to find the correct account number for a given customer name. There are many ways to implement this service (as shown above). Here, we just created a simple SQL query that returned the account number for a given name.

For QueryCustomerAcctForName, we need to add the following custom JAR files to the Web project:

• cj_base_03.jar, which includes simple tools for accessing stream files easily in Java.
  
  

• ebtQwqbBase.jar, which includes simple JDBC connection management tools.
  
  

It was easy to create a stand-alone test of the model bean using a Java scrapbook page added to our WebFacing project. This is shown in Figure 5. Highlighting the scrapbook code in Figure 5, we choose the run option to generate the test output in Figure 6.

ZPARA2.qwx.db.QueryCustomerAcctForName query = 
     new ZPARA2.qwx.db.QueryCustomerAcctForName();
 query.name = “B”;
 query.findAcctForName();	
 System.out.println(“QueryCustomerAcctForName - for name “ 
     + query.name + “  account nbr = “ + query.account)

connectDb connected to: demo 

    List - table: nacrms findAcctForName ran Thu Aug 28 10:37:55 
EDT 2003     on: Thu Aug 28 10:37:55 EDT 2003

NAME     ACCT	
 account = 026785 

QueryCustomerAcctForName - for name B  account nbr = 026785

Step 2: Generate a Struts Web application with the Web Interaction wizard. Using the Web Interaction wizard, we can create a simple Struts Web application to update a Registration bean from Web pages. The resulting bean can be saved to a relational database or an XML document.

The Web Interaction wizard provides two potential starting points to build a Web interaction: A host RPG or COBOL program or a Java bean. The bean you select will fill one or both of the following roles:

• A Java bean modeling a business entity (customer, item, and so on).
  
  

• A Java client bean operating as a command interface accepting input, running a command, and returning output.
  
  

If you’re not calling a host program, always select the Java bean option. In other cases, however, using the command bean is usually the better option because it could have a reference to the entity bean class to create instances of the entity bean, as well as run the Find, Create, Update, Delete, View, or Edit commands.

Here we use the entity model for our Registration bean. For a real application, we would use the command bean that supports all the added behavior we need and manages the set of entity beans. The definition process for the Web interaction wizard follows:

1. Name the interaction.
   
   
2. Select the interaction type: Program or Java bean.
   
   
3. Select the properties or methods to update or invoke.
   
   
4. Define an existing or new input JSP file.
   
   
5. Define an existing or new out put JSP file.
   
   
6. Click Finish to generate the Web interaction application code.

Step 3: Set a command key to invoke the account lookup service. To define a command key to invoke the Customer Account for Name service, follow these steps:

1. In the WebFacing Projects view, open the properties page for the project.
   
   
2. Select Command Key Actions -> Add.
   
   
3. Select an available command key.
   
   
4. For an internal URI (in the project), enter the name of the Struts action to invoke and the URI is filled in automatically. For an external URI (out-side the project), enter the name of the Struts action to invoke and the absolute URI to invoke.
   
   
5. Specify whether to open the invoked page in a new frame or the same frame.
   
   
6. Set a label for the service to display on the command key button.
   
   
7. Republish your application to the server.
   
   
8. Restart the application on the server.

Figure 7 shows the Command Key Actions window where you define each command key.

Figure 7. Set a command key action

Step 4: Create a Web diagram to document the application. Al-though this step is optional, it can be useful to create a visual representation of your application. This is not required to create the Struts service in a WebFacing application.

IBM has included a visual diagram editor for Struts applications in the iSeries Studio tools. It shows pictorially the information that’s in the Struts-config.xml file. In fact, when you change either the file or the diagram, the other is dynamically updated in WDSC to reflect the changes.

What’s the value of the diagram editor? You can define the diagram first as a road map for what the application will do and then invoke the wizards to create any unrealized parts (parts that don’t yet exist in the application). Or you can create the diagram after building the Struts application to produce a graphical view of the workflow.

While developers new to Struts might find it valuable to create the diagram as a road map for what to build, experienced Struts developers probably prefer to use the Struts configuration file editor to define the same road map.

In Figure 8, we used the diagram in the second approach to document the Struts application we created. It takes only two steps to draw the diagram with an existing Struts application:

Figure 8. A Struts Web diagram for the CustomerAccountForName inquiry

1. Add the starting Web page (here CustomerAcctForNameInput.jsp) to the Free Form Surface (FFS) of the editor.
   
   
2. Select the JSP file and Draw All from the menu.
   

Step 5: Test the generated application in the WebSphere Application Server test environment. The WebSphere Test Environment provides a one-click way to test your application:

1. In the WebFacing project view, select the index.html file that was generated.
   
   
2. Click Run on Server.
   
   
3. Watch your Web-enabled application run.
   

This option automatically:

• Configures a Web application server
  
  

• Creates a Web application server instance
  
  

• Publishes your application to the server
  
  

• Starts the Web application server
  
  

• Runs your WebFacing application
  

So far, this example shows how to extend the Strut-based interface created by the new WebFacing wizard with a new Web application and how to integrate a new Web application with a command key in an existing Web-enabled application. We have also reviewed some of the new Struts Web development tools that are now included in WDSC for iSeries.

To complete the review of the customization enhancements in the Advanced edition, the rest of this article discusses how you can use the report service to view spool files and how you can use the support for custom JSP tag libraries.

Add the report service to a Web-enabled application

Adding the report service to your Advanced WebFacing application is easy. To define a command key to invoke the Report service from your WebFacing application:

1. In the WebFacing Projects view, open the properties page for the project.
   
   
2. Select Command Key Actions -> Add.
   
   
3. Select an available command key.
   
   
4. Enter the name of the Struts action to invoke (Report Service) and the URI is filled in automatically.
   
   
5. Specify whether to open the invoked page in a new frame or the same frame.
   
   
6. Set a label for the service to display on the command key button.
   
   
7. Republish your application to the server.
   
   
8. Restart the application on the server.
   
   

Use a custom JSP tag library to display the current date

In this example, we created a custom JSP tag library to do something very simple—display the current date. While this is overkill for the purpose of displaying a date string, it demonstrates how to use JSP tags in a WebFacing application.

To add a custom JSP tag to a WebFacing Web page:

1. Create a custom JSP tag library.
   
   
2. Define a tag library descriptor file.
   
   
3. Modify the JSP file for the menu page. In this case, the taglib directive and the JSP tag for the date were added.
   
   
4. Cut code from the JSP file for the date string and insert it as HTML in CODE Designer Web settings after the OEM100 Menu text string.
   
   
5. Reconvert your Web page.
   
   
6. Republish the application to the test server.
   
   
7. Restart the application on the test server.
   
   
8. Test the Web page.

Figure 9 shows the resulting date string displayed on the menu page.

Figure 9. The main menu page showing the result of the JSP custom tag to display date

Separate the Web from the green-screen interface

We have reviewed the key customization capabilities delivered in WDSC for iSeries for applications that have been Web-enabled with the WebFacing Tool. These updates substantially enhance the capability of the Web version of the application while leaving the green-screen application intact. Because the 5250 and Web versions of the application have diverged, it is important to be able to access them differently even though they have the same base.

You have three choices to change the workflow or logic of your host application so that it runs differently for a Web user:

1. Add a parameter to the start- up call of your application identifying whether it is run- ning for a Web or host user.
   
2. Use the QQFENV API in OS/400 to determine if the job is running for a Web user or host user.
   
3. Create a Web version of your host application and modify it differently for Web users.

The simplest option is just to pass a parameter with the CL program invocation that indicates the job is running for a Web user; Call mylib/myprogram (‘webmode’).

The only negative to this approach is having to pass the parameter through all the calls you make to the program that needs to use this information. If you don’t have the ability to do this, you can create a data area in QTEMP to pass the information to the target program or you can use the QQFENV API.

The QQFENV API, part of OS/400, indicates whether a job is running for a Web or a 5250 client device. Using the returned flag (1 = WebFacing environment, 0 = 5250 environment), you can condition the logic of your host application differently for the Web user.

You’ll need to create a simple RPG ILE program similar to the WFENV program, shown in Figure 10, that invokes the QQFENV API. You can:

• Copy the source code below to a source member in QRPGSRC with the RPGLE type (here it is WFENV).
  
  

• Use CRTPGMOD to create a program module from the source member.
  
  

• Use CRTPGM to create the program with keyword BNDSVCPGM specifying QSYS/QQFENV.
  
  

Figure 11 shows an example of using WFENV from a parent program to condition its workflow based on whether the user is a Web (WebFacing user) or a host (5250 terminal user).

 
CALL     PGM(WFENV) PARM(&MODE) /* get mode = web or +
             host from qqfenv */
       CHGVAR     VAR(&MSGDTA) VALUE(‘STRWFJ mode = ‘ *CAT &MODE)
       SNDPGMMSG  MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA(&MSGDTA)

       IF         COND(&MODE = ‘web’) THEN(DO)
       CALL       PGM(QCMDEXC) PARM(&WEBJOB)
       ENDDO
       ELSE CMD(DO)
       CALL       PGM(QCMDEXC) PARM(&HOSTJOB)
       ENDDO

  
DQQFENV         PR        10I 0 Extproc(‘QqfEnvironment’)
 Drc        S        10I 0
 C  *entry     plist
 C          parm             mode           10
 C          Eval      rc = QQFENV
 C          If        rc = 1
 C          Eval      mode = ‘web’
 C          Else
 C          Eval      mode = ‘host’
 C          EndIf
 C          Eval      *inlr = *on

Note: The complete source is available at www.iseries400experts.com and www.ebt-now.com.

Advanced edition brings WebFacing to a new level

In this guided tour of the customization capabilities of WDSCA for iSeries, we have demonstrated how to use the four key enhancements to the WebFacing Tool:

1. The WebFacing Tool wizard to generate a Struts-based Web interface.

2. Support for user-defined command keys to extend Web-enabled applications.

3. A report service for viewing spool files.

4. Support for custom JSP tag libraries.

We also reviewed how to access the unique capabilities in the Web version of the host application.

The enhancements available in the Advanced edition allow the developer to substantially leverage and extend the capabilities of the Struts-based Web-enabled application created with the WebFacing Tool. With these enhancements, the base 5250 applications can serve as the starting point for a brand-new suite of Web applications.

View this article online at www.iseries400experts.com