IBM WebSphere Development Studio Client for iSeries Tutorial: Building a Web user interface for an RPG application using iSeries Web Tools Version 5.1.2 Contents 1.0 Introduction to this tutorial 1.1 Learning objectives 1.2 Prerequisite knowledge 1.2.1 System Prerequisites 2.0 Introducing the Web customer inquiry application 2.1 Introducing iSeries Web Application Development 2.2 Introducing the Web customer inquiry application 2.3 Recap 3.0 Creating an RPG program 3.1 Exercise 2.1: Starting the Development Studio Client workbench 3.2 Exercise 2.2: Opening the Remote System Explorer perspective 3.3 Exercise 2.3: Creating a connection to the iSeries server 3.4 Exercise 2.4: Creating the IFS Directory for the Web project 3.5 Exercise 2.5: Finding an iSeries source member 3.6 Exercise 2.6: Editing a source member 3.7 Exercise 2.7: Reviewing Remote System LPEX Editor features 3.7.1 Highlighting specification fields 3.7.2 Displaying types of lines 3.7.3 Checking the syntax of a file 3.7.4 Keeping track of columns in a specification line 3.8 Exercise 2.8: Creating a *PGM object 3.8.1 Fixing errors 3.9 Recap 4.0 Creating the RPG service program for your Web application (optional) 4.1 Exercise 3.1: Starting the Development Studio Client workbench 4.2 Exercise 3.2: Opening the Remote System Explorer perspective 4.3 Exercise 3.3: Creating a connection to the iSeries server 4.4 Exercise 3.4: Creating the IFS Directory for the Web project 4.5 Exercise 3.5: Finding an iSeries source member 4.6 Exercise 3.6: Editing a source member 4.7 Exercise 3.7: Reviewing Remote System LPEX Editor features 4.7.1 Highlighting specification fields 4.7.2 Displaying types of lines 4.7.3 Checking the syntax of a file 4.7.4 Keeping track of columns in a specification line 4.8 Exercise 3.8: Creating a service program module 4.8.1 Adding RPG code 4.8.2 Creating the service program module 4.8.3 Fixing errors 4.8.4 Creating a service program 4.9 Recap 5.0 Creating a Web project 5.1 Exercise 4.1: Opening the Web perspective 5.1.1 Perspectives 5.2 Exercise 4.2: Creating a dynamic Web project 5.3 Exercise 4.3: Setting up the iSeries server information 5.4 Recap 6.0 Creating a Web application 6.1 Exercise 5.1: Invoking the Web Interaction wizard 6.2 Exercise 5.2: Specifying the input and output page 6.3 Exercise 5.3: Defining the iSeries GETDATA program invocation and parameters 6.3.1 Getting the program interface definitions 6.3.2 Specifying the input and output parameters 6.4 Exercise 5.4: Defining the iSeries GETDATAS service program invocation and parameters 6.4.1 Getting the program interface definitions 6.4.2 Specifying the input and output parameters 6.5 Exercise 5.5: Defining the input page content 6.5.1 Changing the heading 6.5.2 Changing a field label 6.6 Exercise 5.6: Defining the output page content 6.7 Exercise 5.7: Specifying error handling 6.8 Exercise 5.8: Enhancing the output page 6.9 Exercise 5.9: Ensuring the customer number field cannot be modified 6.10 Exercise 5.10: Visualizing the flow structure of your Web application 6.10.1 Struts 6.11 Recap 7.0 Running the Web application 7.1 Exercise 6.1: Opening the Web perspective 7.2 Exercise 6.2: Finding the Web application 7.3 Exercise 6.3: Selecting the run on server option 7.4 Recap 8.0 Debugging a Web application 8.1 Exercise 7.1: Introducing the iSeries Integrated Debugger 8.2 Exercise 7.2: Starting a Debug session using service entry points 8.3 Exercise 7.3: Adding and deleting breakpoints 8.4 Exercise 7.4: Displaying a variable 8.5 Exercise 7.5: Viewing the call stack 8.6 Exercise 7.6: Closing the debug session 8.7 Recap 9.0 Adding an error page 9.1 Exercise 8.1: Creating the flow control page 9.2 Exercise 8.2: Modifying your Web interaction 9.3 Exercise 8.3: Testing the new error page 9.4 Recap 10.0 Enhancing the input page using Web tools 10.1 Exercise 9.1: Opening Page Designer 10.2 Exercise 9.2: Working with page properties 10.3 Exercise 9.3: Linking a cascading style sheet to the Web page 10.4 Exercise 9.4: Designing and adding a logo 10.4.1 Starting the WebArt Designer 10.4.2 Creating the logo 10.4.3 Resizing the logo 10.4.4 Saving the object as a WebArt object 10.4.5 Saving the object for a Web page 10.4.6 Placing the logo on the Design page 10.5 Exercise 9.5: Adding a heading 1 tag to the page 10.6 Exercise 9.6: Adding a picture to the page 10.7 Exercise 9.7: Adding moving text to the page 10.8 Exercise 9.8: Changing the text color 10.9 Recap 11.0 Tutorial Summary Appendix. Notices A.1 Programming interface information A.2 Trademarks 1.0 Introduction to this tutorial iSeries(TM) Web development tools give you the ability to create new e-business applications that use a Web-based front end to communicate with the business logic in an ILE or non-ILE language program residing on an iSeries server. You can create the high-level design of your Web site and apply page templates using Web Site Designer. Then, you can create the individual pages with Page Designer, or generate input and output JSP files with the Web Interaction wizard. You can also add iSeries Web components to your pages, for example, Web equivalents of iSeries command keys, input fields that accept only particular types of data, or output fields such as subfile names. Tutorial purpose Before you begin, take a minute to read the learning objectives for the tutorial. Length of time This tutorial takes approximately 1.5 hours to complete. Chapters Work on the chapters in sequence. The pictures in the chapters show similar tasks. Some of the names and icons may be different from the environment you will be working with when you complete the chapters. Prerequisites You should also learn about the prerequisite knowledge for the tutorial before beginning. This section describes the type of knowledge you need to already have to fully benefit from this tutorial. 1.1 Learning objectives In order to successfully develop and test an e-business RPG application, you will need to understand many concepts. This tutorial is designed to help you learn about those concepts while working through the steps. In this tutorial, you will create a simple e-business customer inquiry application. While creating a browser user interface, you will learn how to use the iSeries wizards in Development Studio Client to create the servlets to invoke an RPG program that performs the business logic. You will then learn how to run the application in the WebSphere(R) Test Environment that is part of Development Studio Client. The tutorial is broken into eight chapters, each with their own specific learning objectives. You can choose to complete all chapters, or you can choose to complete only a few, depending on your own learning goals. Each chapter is composed of several exercises. These exercises must be completed in order to successfully achieve the chapter's goals. 2.0, "Introducing the Web customer inquiry application" shows you the completed customer inquiry application that you will build in this tutorial. You will also learn about the iSeries Web development tools that you will use to create this Web application. 3.0, "Creating an RPG program" helps you learn how to use the Remote System Explorer perspective to edit and compile an iSeries program or service program that will be invoked by the Web application to get data from the iSeries. 4.0, "Creating the RPG service program for your Web application (optional)" helps you learn how to use the Remote System Explorer perspective to edit and compile an iSeries program or service program that will be invoked by the Web application to get data from the iSeries. 5.0, "Creating a Web project" helps you learn about the Web perspective and the tools in this perspective to help you create a Web project to contain your Web application files and to supply the information which the iSeries server will use for serving business information for this Web application. 6.0, "Creating a Web application" helps you learn how to create a Web interaction to use an input and output page, and to create the servlet to invoke an RPG program to get data from the iSeries database. You will also learn how to visualize the flow structure of your Web application using the Web Diagram editor. 7.0, "Running the Web application" explains how to run the Web application in the WebSphere Test Environment. You also learn about the WebSphere Test Environment. 8.0, "Debugging a Web application" helps you learn how to create an informative error page for customers when an incorrect customer number is entered. 9.0, "Adding an error page" introduces you to the iSeries integrated debugger, helps you learn how to start a debug session using service entry breakpoints, and helps you learn how to add and delete breakpoints, display a variable, view the call stack, run, step and step into a program, set watch breakpoints and close the debug session. 10.0, "Enhancing the input page using Web tools" explains how to add color and some pictures to make the input page of the Web application more attractive. You will learn how to use the Page Designer tool and some other related Web tools. Be sure to read about the Prerequisite knowledge for the tutorial before beginning. This section describes the type of knowledge you need to already have to fully benefit from this tutorial. 1.2 Prerequisite knowledge In order to complete this tutorial end to end, you should already have working knowledge of the following: * Basic Microsoft(R) Windows(R) operations such as working with the desktop and basic mouse operations such as opening folders and performing drag-and-drop operations. * How Web applications work. * How to use a browser to navigate the Internet. It is also useful, but not necessary, for you to have basic knowledge of the following: * DDS * Servlets and Java(TM) Server Pages (to understand the generated output of the Web Interaction wizard) If you do not have current knowledge of these technologies and concepts, you might be interested in learning more about these after you complete this tutorial. You can find some additional information on these topics in the Help system that is part of WebSphere Development Studio Client for iSeries. There are also plenty of resources on the Internet at our product Web page http://ibm.com/software/awdtools/iseries. When you are ready to begin, start with 2.0, "Introducing the Web customer inquiry application". 1.2.1 System Prerequisites To run this tutorial you will need specific hardware and software. See the section key prerequisites in the Development Studio Client 5.1.2 announcement letter at http://ibm.com/software/awdtools/iseries. Finally you will need to restore the iSeries save file provided. Go to http://ibm.com/software/awdtools/wdt400/library to find the pdf and savefile for this tutorial. To restore the save file: 1. Create a save file named WSSLABXX in library QGPL or any other library you have access to on the iSeries by typing the following on an OS/400(R) command prompt: CRTSAVF QGPL/WSSLABXX 2. From a DOS Command Prompt window, go to the directory where you downloaded the save file and use FTP to send the WSSLABXX.savf file to the iSeries. (press enter after each statement) ftp iSeriesName user id password binary put wsslabxx.savf qgpl/wsslabxx quit 3. Restore the library on the iSeries by running the following command from an OS/400 command prompt: RSTLIB WSSLABXX DEV(*SAVF) SAVF(QGPL/WSSLABXX) The library has now been restored to the iSeries. 2.0 Introducing the Web customer inquiry application In this chapter, you will be introduced to the Web customer inquiry application that you will build in this tutorial. You will also learn about the iSeries Web tools included with Development Studio Client. In order to accomplish these learning objectives, there are several steps that are involved, including: * 2.1, "Introducing iSeries Web Application Development" * 2.2, "Introducing the Web customer inquiry application" The sections in this chapter must be completed in order. Start with 2.1, "Introducing iSeries Web Application Development" when you are ready to begin. Length of time: This chapter will take approximately 10 minutes to complete. 2.1 Introducing iSeries Web Application Development With Development Studio Client you can make your iSeries applications and data accessible beyond the green-screen interface. You can create a new Web interface that connects directly to your program's input and output parameters. You can create interactive Web pages using Web development tools. You use the Web Interaction wizard to define how your pages interact with one or more ILE or non-ILE applications. This wizard generates Java Action classes and JSP files for use with data from HTML forms. When the end user enters data in a form, the input becomes data to your ILE and non-ILE programs, and the output from the programs is formatted for the Web. Your ILE and non-ILE logic can be separated into different programs for each stage of input and output (known as a Web interaction), or can be a single service program with entry points to handle each Web interaction. The following diagram illustrates the Web development tools process: Web Development tools process You can easily customize your HTML and JSP files using the editing tools in Web development tools. You can use these tools to create and update input forms, change the appearance or placement of blocks of text, and add backgrounds and images to your pages. The iSeries-specific Web components help you create Web versions of your input and output pages with the same kinds of input validation, output formatting, and subfile controls that native DDS screens provide. You do not need a detailed knowledge of HTML or Java to accomplish these tasks. You have an easy test mechanism for your Web-enabled applications. You can easily run your program in the WebSphere test environment of the workbench, quickly make changes, and retest, rather than redeploy your application every time you want to verify functions. When you are finished, you can package and deploy your Web applications as J2EE-based Web archive (WAR) and Enterprise Archive (EAR) files, and then install them in a WebSphere Application Server. 2.2 Introducing the Web customer inquiry application By the end of this tutorial you will have created a simple e-business customer inquiry application that uses a Web-based front-end to communicate with RPG business logic residing on an iSeries server. You will first create the RPG program or service program for your Web application. You will then create a Web project and invoke the Web Interaction wizard to create the input and output pages and to create the servlet to invoke the RPG program or service program to get data from the iSeries database. Next, you will run the application in the local test environment on your workstation. You will also create an informative error page for when a customer enters an incorrect customer number. Here is what the finished e-business customer inquiry application looks like. After the WebSphere server has started, your Web application Customer Inquiry input page (inquiry.jsp) will display in the workbench browser: Workbench browser When you enter a customer number and click the Submit push button, the Customer Details output page (result.jsp) appears. Result page Next, you click the Back button Back button in the browser to return to the Customer Inquiry input page. Here you enter an incorrect customer number and click Submit. Incorrect input An error message appears. Error message You then add a new output error page to improve the message information so that if a wrong customer number is entered, Entering wrong customer number an error page opens instead of a message. Error Page 2.3 Recap Congratulations! You have completed 2.0, "Introducing the Web customer inquiry application". You should now understand: * What tools are available to iSeries programmers for iSeries Web application development * What the finished ebusiness customer inquiry application looks like +----------------------------------------------------------------------+ | Now that you have this introductory knowledge of Development Studio | | Client iSeries Web application development, you can continue with | | 3.0, "Creating an RPG program" if you want to work with an RPG | | program or 4.0, "Creating the RPG service program for your Web | | application (optional)" if you want to work with an RPG service | | program. | +----------------------------------------------------------------------+ 3.0 Creating an RPG program In this chapter, you will learn how to create the iSeries program that you will be using for your Web application using the Remote System Explorer perspective. Remote System Explorer provides a PDM like environment but with a GUI interface, and full integration with all iSeries programmer tools in the Development Studio Client workbench. +----------------------------------------------------------------------+ | If you want to work with a procedure in a service program instead, | | go to 4.0, "Creating the RPG service program for your Web | | application (optional)". | +----------------------------------------------------------------------+ If you haven't used the LPEX editor before, you may want to spend some time trying some LPEX editor features. In order to accomplish these learning objectives, there are several steps that are involved, including: * 3.1, "Exercise 2.1: Starting the Development Studio Client workbench" * 3.2, "Exercise 2.2: Opening the Remote System Explorer perspective" * 3.3, "Exercise 2.3: Creating a connection to the iSeries server" * 3.4, "Exercise 2.4: Creating the IFS Directory for the Web project" * 3.5, "Exercise 2.5: Finding an iSeries source member" * 3.6, "Exercise 2.6: Editing a source member" * 3.7, "Exercise 2.7: Reviewing Remote System LPEX Editor features" * 3.8, "Exercise 2.8: Creating a *PGM object" The exercises in this chapter must be completed in order. Start with 3.1, "Exercise 2.1: Starting the Development Studio Client workbench" when you are ready to begin. Length of time: This chapter will take approximately 15 minutes to complete. 3.1 Exercise 2.1: Starting the Development Studio Client workbench Now go ahead and start Development Studio Client. On your desktop taskbar: Starting the Development Studio Client 1. Click Start > All Programs > IBM(R) WebSphere Studio > Development Studio Client Advanced Edition for iSeries 5.1.2 A dialog for workspace selection will appear asking you for the workspace location, unless you used the Development Studio Client before and selected not to show this dialog again. Workspace selection The workspace contains all the information about your Development Studio projects. You can accept the default or store the work related to this tutorial, in a separate workspace. 2. To name the directory of the workspace as shown above, use the directory name WSSLABxx. 3. Click OK. After a few moments of loading, the workbench opens, and the initial window of Development Studio Client appears on your desktop. Initial window 3.2 Exercise 2.2: Opening the Remote System Explorer perspective Check if the window title bar says: Remote System Explorer. If it does you are all set. Skip the next steps and go directly to 3.3, "Exercise 2.3: Creating a connection to the iSeries server". To open the Remote System Explorer perspective: 1. In the workbench, check whether you have the Remote System Explorer perspective already open. Look for the icon in the left taskbar of the workbench. 2. If you see it click the RSE button RSE icon. RSE perspective icon 3. Otherwise, click Window > Open Perspective > Remote System Explorer on the workbench menu. The Remote System Explorer perspective opens. RSE Perspective 3.3 Exercise 2.3: Creating a connection to the iSeries server 1. Click the plus sign + beside iSeries under New Connection in the Remote Systems view. 2. Accept the default profile name. Default Profile 3. Click Next. Specifying the Connection name and Host name In this exercise s400a is used as the name for the iSeries server. You will need to use the name or IP address of your particular iSeries server. 4. Type a host name, for example, s400a in the Host name field. 5. The Connection name field will be filled automatically with the same entry. 6. Click Finish. Your new connection appears in the Remote Systems view and you are ready to work with objects on this iSeries system. 3.4 Exercise 2.4: Creating the IFS Directory for the Web project IFS Files allow you to explore folders and files in the Integrated File System of the remote iSeries system. You will now create a directory in the IFS that will be used when you compile your iSeries source member. Locate the newly created iSeries connection. 1. Expand your iSeries connections. Drilling down the IFS Files > File systems > root > QIBM 2. Expand the IFS Files by clicking the plus sign + beside it. 3. Expand the File systems. 4. If prompted, type your User ID and Password. Enter the User ID and Password 5. Select the Save user ID check box. 6. Select the Save password check box. 7. Expand the / Root node. 8. Select QIBM. Right-click QIBM and click New > Folder on the pop-up menu. Creating a new folder under QIBM 9. Enter WSSLABxx in the Folder name field. Enter the Folder name: WSSLABxx 10. Click Finish. Checking that the new folder has been created You should see the new WSSLABxx directory under QIBM. 3.5 Exercise 2.5: Finding an iSeries source member You will see a list of servers in the Remote Systems view. Now you locate the source you want to edit. To find an iSeries source member: List of servers in Remote Systems View 1. Expand your iSeries connections. 2. Expand iSeries Objects by clicking the plus sign + beside it. 3. Expand Library List. 4. Expand the library WSSLABxx. You will see all objects in this library. 5. Expand the source file QRPGLESRC. List of servers in Remote Systems View 6. Scroll down to the source members in the expanded list. 3.6 Exercise 2.6: Editing a source member A shell source member is provided for you to use. To edit a source member: 1. Right-click member GETDATA. 2. Click Open with > Remote Systems LPEX Editor on the pop-up menu. Open with Remote Systems LPEX Editor The Editor window opens and you are ready to write your program. Note: You can also double-click on a member to open the Remote Systems LPEX editor. Now you can work with the RPG program source. +----------------------------------------------------------------------+ | Before you work with the RPG program source, if you have not worked | | with the Remote Systems LPEX editor, go to 3.7, "Exercise 2.7: | | Reviewing Remote System LPEX Editor features". | +----------------------------------------------------------------------+ | If you already know the LPEX editor, then you are ready to write the | | RPG program; go to 3.8, "Exercise 2.8: Creating a *PGM object". | +----------------------------------------------------------------------+ 3.7 Exercise 2.7: Reviewing Remote System LPEX Editor features Before you start, here are some useful tips on using the LPEX editor. Let's look at some of the features of the LPEX editor, so you can later easily find your way around and use them: * ALT+L marks a line * ALT+U unmarks selection * ALT+D deletes a selected text * ALT+C copies selected text * ALT+M moves selected text * Enter inserts a new line 3.7.1 Highlighting specification fields The LPEX editor highlights the Tokens (specification fields) of your RPG program source, providing a separate color for each, improving readability. When you make changes to a line, the token colors get updated only after you move your cursor off the line. To see how token highlighting works: 1. Move the cursor to a Calculation statement. 2. Position the cursor to column 7 (right next to the C). 3. Type an asterisk (*). 4. Move the cursor off the line and watch what happens. The line where you typed the asterisk (*) becomes a comment line and its color changes accordingly. Token Highlighting 5. Move the cursor back to column 7 and remove the asterisk (*). 6. Move the cursor off that line of code and the statement is tokenized. The token highlighting changes to reflect that this is a non-commented C specification. 3.7.2 Displaying types of lines Using the LPEX editor, it is possible to have only particular types of source lines displayed at a time. To display types of lines: 1. Right-click anywhere in the Editor window. 2. Click Filter view on the pop-up menu. The menu items list the types of line selections that can be made. 3. Click Comments. The Editor window now contains only those RPG statements that are comments. Show comments only 4. Right-click anywhere in the Editor window. 5. Click Show all on the pop-up menu. Show all All statements types are displayed. In addition, the choices in the pop-up menu can be used to include only control specifications, user subroutines, and procedures and others. The Filter Selection option under the Selected option in the Edit menu allows the selection of only those lines containing a particular selected character string. 3.7.3 Checking the syntax of a file Syntax checking is available for RPG code, and by default will be active. The syntax of RPG code is checked automatically when a change is made to a line, and the cursor is moved off the line. When errors are found, they are displayed following the statement with the error. 3.7.4 Keeping track of columns in a specification line The format line is at the top of the Editor window, just above the first statement. A format line is used to help keep track of the columns in a particular specification line. The content of the format line can vary to reflect the particular type of specification being keyed such as F specs, C specs, D specs and so on. To display a format line: 1. Click a line or use the arrow keys and click the left mouse button to make a line active. The format line gets updated as a line gets focus. You can move the cursor right or left with the arrow keys to go from character to character, or with the Tab key to go from field to field. An indicator on the format line moves with the cursor to show in which column the cursor is positioned. Indicator moves with the cursor You can select a format line for any specification you want. 2. Click Source from the Editor menu. 3. Click Select Format Line on the pop-up menu. The Format Line Selection window opens. Format Line Selection window Now you can start and create the RPG program. 4. Click OK. 3.8 Exercise 2.8: Creating a *PGM object To make it easier for you, most of the RPG source is already prepared for you. You have already opened the correct source member GETDATA in the previous exercise using the Remote Systems view. Read through the source. It contains an F spec to access file CUSTOML3, which contains the customer data keyed by customer number. The D specs define the data structure CSTRUC that you pass back to your Web page and the CUSTNOI variable that gets passed from the Web page to this program. As well the Feedback variable is defined as a 20 length character field. The Entry parameter list is defined as: * CUSTNOI field (this is the input parameter). * CSTRUC structure (this the data structure for the customer output data). * Feedback field to indicate no success for file access. The code you have to write here, fetches a customer record by chaining to the file with the CUSTNOI that gets passed into the program. To create a *PGM object with RPG: 1. Add the code to get the customer record and check whether the chain was successful. CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq C CUSTNOI CHAIN CUSTOML3 5050 C C If *IN50 C EVAL FEEDBACK='CUS0001 ' + CUSTNOI C ELSE C EVAL FEEDBACK='0' C ENDIF Your coding is complete, so let's create the program. 2. Click the Save Save button icon on the workbench toolbar to save the member. 3. Click the X in the Editor window title bar to close the member. Close member Be careful not to click the X on the workbench window title bar. Compile 4. In the Remote Systems view, right-click the GETDATA member in source file QRPGLESRC and click Compile (Prompt) > CRTBNDRPG on the pop-up menu. The Create Bound RPG Program (CRTBNDRPG) dialog opens. CRTBNDRPG prompt 5. In the Debugging views list, select *ALL You need to specify two more parameters, these parameters are used to tell the compiler to generate the program interface description in a language called Program Call Markup Language (PCML). Later on you can use this description in the Web Interaction wizard. 6. Check the All Parameters check box at the bottom of the dialog. 7. Scroll down in the dialog until you see the Generate program interface field. 8. Select the *PCML value from the list. Generate the program interface. 9. Enter /qibm/wsslabxx/getdata.pcml for the Program interface stream file field. 10. Click OK to start to compile. After compile, the iSeries Error List view is shown, listing all compile errors. You may see only information and warning messages which means your compile was completed and the program object was created. iSeries command log 11. Click the iSeries Commands Log tab to check that the compile was successful. This log shows the Remote System Explorer job messages. If you get a message that there are errors in your program, go through the edit compile fix cycle. 3.8.1 Fixing errors In the error list view, check the errors: 1. Double-click the error. This positions the cursor in the Editor window on the statement that is wrong. 2. Fix all errors. 3. Save the source member. 4. Go back to the Remote Systems view. 5. Right-click the member to run the CRTBNDRPG command. 6. Continue this cycle until you get a clean compile. 3.9 Recap Congratulations! You have completed 3.0, "Creating an RPG program". You should now understand: * How to start the workbench * LPEX editor features * How to open the Remote System Explorer perspective * How to find an iSeries source member * How to edit an iSeries source member * How to compile a program object * How to create a PCML program interface description Now that you have created the RPG program, you can continue to 5.0, "Creating a Web project". +----------------------------------------------------------------------+ | Skip 4.0, "Creating the RPG service program for your Web application | | (optional)" as you don't need to do this set of exercises. | +----------------------------------------------------------------------+ 4.0 Creating the RPG service program for your Web application (optional) +----------------------------------------------------------------------+ | You do not need to do this chapter if you have done 3.0, "Creating | | an RPG program". | +----------------------------------------------------------------------+ In this chapter, you will learn how to add the iSeries service program to your Web application using the Remote System Explorer perspective. Remote System Explorer provides a PDM like environment but with a GUI interface, and full integration with all iSeries programmer tools in the Development Studio Client workbench. If you haven't used the LPEX editor before, you may want to spend some time trying some LPEX editor features. In order to accomplish these learning objectives, there are several steps that are involved, including: * 4.1, "Exercise 3.1: Starting the Development Studio Client workbench" * 4.2, "Exercise 3.2: Opening the Remote System Explorer perspective" * 4.3, "Exercise 3.3: Creating a connection to the iSeries server" * 4.4, "Exercise 3.4: Creating the IFS Directory for the Web project" * 4.5, "Exercise 3.5: Finding an iSeries source member" * 4.6, "Exercise 3.6: Editing a source member" * 4.8, "Exercise 3.8: Creating a service program module" The exercises in this chapter must be completed in order. Start with 4.1, "Exercise 3.1: Starting the Development Studio Client workbench" when you are ready to begin. Length of time: This chapter will take approximately 15 minutes to complete. 4.1 Exercise 3.1: Starting the Development Studio Client workbench Now go ahead and start Development Studio Client. On your desktop taskbar: Starting the Development Studio Client 1. Click Start > All Programs > IBM WebSphere Studio > Development Studio Client Advanced Edition for iSeries 5.1.2 A dialog for workspace selection will appear asking you for the workspace location, unless you used the Development Studio Client before and selected not to show this dialog again. Workspace selection The workspace contains all the information about your Development Studio projects. You can accept the default or store the work related to this tutorial, in a separate workspace. 2. To name the directory of the workspace as shown above, use the directory name WSSLABxx. 3. Click OK. After a few moments of loading, the workbench opens, and the initial window of Development Studio Client appears on your desktop. Initial window 4.2 Exercise 3.2: Opening the Remote System Explorer perspective Check if the window title bar says: Remote Systems Explorer. If it does you are all set. Skip the next steps and go directly to 4.3, "Exercise 3.3: Creating a connection to the iSeries server". To open the Remote System Explorer perspective: 1. In the workbench, check whether you have the Remote System Explorer perspective already open. Look for the icon in the left taskbar of the workbench. 2. If you see it, click the RSE button RSE icon. RSE perspective icon 3. Otherwise, click Window > Open Perspective > Remote System Explorer on the workbench menu. The Remote System Explorer perspective opens. RSE Perspective 4.3 Exercise 3.3: Creating a connection to the iSeries server To create a connection: 1. Click the plus sign + beside iSeries under New Connection in the Remote Systems view. 2. Accept the default profile name. Accepting the Default Profile name 3. Click Next. Enter the Connection name and Host name In this exercise s400a is used as the name for the iSeries server, you will need to use the name or IP address of your particular iSeries server. 4. Type a host name, for example, s400a in the Host name field. 5. The Connection name field will be filled automatically with the same entry. 6. Click Finish. Your new connection appears in the Remote Systems view and you are ready to work with objects on this iSeries system. 4.4 Exercise 3.4: Creating the IFS Directory for the Web project IFS Files allow you to explore folders and files in the Integrated File System of the remote iSeries system. You will now create a directory in the IFS that will be used when you compile your iSeries source member. Locate the newly created iSeries connection. 1. Expand your iSeries connections. Drill down the IFS Files > File system > root > QIBM 2. Expand the IFS Files by clicking the plus sign + beside it. 3. Expand the File systems. 4. If prompted, type your User ID and Password. Enter the User ID and Password 5. Select the Save user ID check box. 6. Select the Save password check box. 7. Expand the / Root node. 8. Select QIBM. Right-click QIBM and click New > Folder. Creating a new fold under QIBM 9. Enter WSSLABxx in the Folder namefield. Enter WSSLABxx as the folder name 10. Click Finish. Checking that the new folder has been created You should see the new WSSLABxx directory under QIBM. 4.5 Exercise 3.5: Finding an iSeries source member You will see a list of servers in the Remote Systems view. Now you locate the source you want to edit. To find an iSeries source member: List of servers in Remote Systems View 1. Expand your iSeries server. Use the same server that you have used to specify the reference fields in the data structure. 2. Expand iSeries Objects by clicking the plus sign + beside it. 3. Expand Library List. 4. Expand the library WSSLABxx. You will see all objects in this library. 5. Expand the source file QRPGLESRC. 6. Scroll down to the source members in the expanded list. 4.6 Exercise 3.6: Editing a source member One shell source member is provided for you to use. To edit the source member: 1. Right-click member GETDATAS. 2. Click Open with > Remote Systems LPEX Editor on the pop-up menu. Open with Remote Systems LPEX Editor The Editor window opens and you are ready to write your program. Tip: You can also double-click on a member to open the Remote Systems LPEX editor. +----------------------------------------------------------------------+ | Now before you edit the member, if you have not worked with the | | Remote Systems LPEX editor, go to 4.7, "Exercise 3.7: Reviewing | | Remote System LPEX Editor features". | +----------------------------------------------------------------------+ | If you already know the LPEX editor, you are ready to write your | | service program, go 4.8, "Exercise 3.8: Creating a service program | | module". | +----------------------------------------------------------------------+ 4.7 Exercise 3.7: Reviewing Remote System LPEX Editor features Before you start, here are some useful tips on using the LPEX editor. Let's look at some of the features of the LPEX editor, so you can later easily find your way around and use them: * ALT+L marks a line * ALT+U unmarks selection * ALT+D deletes a selected text * ALT+C copies selected text * ALT+M moves selected text * Enter inserts a new line 4.7.1 Highlighting specification fields The LPEX editor highlights the Tokens (specification fields) of your RPG program source, providing a separate color for each, improving readability. When you make changes to a line, the token colors get updated only after you move your cursor off the line. To see how token highlighting works: 1. Move the cursor to a Calculation statement. 2. Position the cursor to column 7 (right next to the C). 3. Type an asterisk (*). 4. Move the cursor off the line and watch what happens. The line where you typed the asterisk (*) becomes a comment line and its color changes accordingly. Token Highlighting 5. Move the cursor back to column 7 and remove the asterisk (*). 6. Move the cursor off that line of code and the statement is tokenized. The token highlighting changes to reflect that this is a non-commented C specification. 4.7.2 Displaying types of lines Using the LPEX editor, it is possible to have only particular types of source lines displayed at a time. To display types of lines: 1. Right-click anywhere in the Editor window. 2. Click Filter view on the pop-up menu. The menu items list the types of line selections that can be made. 3. Click Comments. The Editor window now contains only those RPG statements that are comments. Show comments only 4. Right-click anywhere in the editor window. 5. Click Show all on the pop-up menu. Show all All statements types are displayed. In addition, the choices in the pop-up menu can be used to include only control specifications, user subroutines, procedures and others. The Filter Selection option under the Selected option in the Edit menu allows the selection of only those lines containing a particular selected character string. 4.7.3 Checking the syntax of a file Syntax checking is available for RPG code, and by default will be active. The syntax of RPG code is checked automatically when a change is made to a line, and the cursor is moved off the line. When errors are found, they are displayed following the statement with the error. 4.7.4 Keeping track of columns in a specification line The format line is at the top of the Editor window, just above the first statement. A format line is used to help keep track of the columns in a particular specification line. The content of the format line can vary to reflect the particular type of specification being keyed such as F specs, C specs, D specs and so on. To display a format line: 1. Click a line or use the arrow keys and click the left mouse button to make a line active. The format line gets updated as a line gets focus. You can move the cursor right or left with the arrow keys to go from character to character, or with the Tab key to go from field to field. An indicator on the format line moves with the cursor to show in which column the cursor is positioned. Indicator moves with the cursor You can select a format line for any specification you want. 2. Click Source from the Editor menu. 3. Click Select Format Line on the pop-up menu. The Format Line Selection window opens. Format Line Selection window Now you can start and create the service program. 4. Click OK. 4.8 Exercise 3.8: Creating a service program module To make it easier for you most of the RPG source is already prepared for you. You have already opened the correct source member GETDATAS in the previous exercise using the Remote Systems view. Read through the source. It contains an F spec to access file CUSTOML3 which contains the customer data keyed by customer number. The D specs define the data structure CSTRUC that gets passed back to your Web page and the CUSTNOI variable that gets passed from the Web page to this program. Also variable FEEDBACK is defined as 20 characters, to return message id and customer number in case the customer record was not found. The prototype for procedure getrecord with the parameters is defined as the: * CUSTNOI field (this is the input parameter) * CSTRUC structure (this is the data structure for customer data) * FEEDBACK field (returns error or success) Note: The external name is case sensitive. It has to match exactly what you specified in the Web Interaction wizard. The procedure interface defines the parameters in the same way as the prototype. Inside the procedure after the procedure interface you need to add the RPG code. 4.8.1 Adding RPG code To add the RPG code: 1. CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq C CUSTNOI CHAIN CUSTOML3 5050 C C If not *IN50 C EVAL cust1=cstruc C EVAL FEEDBACK='0' C ELSE C EVAL FEEDBACK='CUS0001 '+ CUSTNOI C ENDIF 2. You do a CHAIN to the database and move the database fields to the local procedure structure. If the database access fails, move the MSGID and Customer number to the FEEDBACK variable. Your coding is complete, so let's create the service program module. 4.8.2 Creating the service program module To create the service program module: 1. Click the Save Save icon icon on the workbench toolbar to save the member. 2. Click X in the Editor window title bar to close the member. Close the member Be careful, don't click the X on the workbench window title bar. 3. In the Remote Systems view, right-click GETDATAS member in QRPGLESRC and select Compile (Prompt) > CRTRPGMOD on the pop-up menu. Compile The Create RPG Module (CRTRPGMOD) dialog opens. CRTRPGMOD prompt 4. In the Debugging views list, select *ALL You need to specify two more parameters, these parameters are used to tell the compiler to generate the program interface description in a language called Program Call Markup Language (PCML). Later on you can use this description in the Web Interaction wizard. 5. Select the All Parameters check box at the bottom of the dialog. 6. Scroll down in the dialog until you see the Generate program interface field. 7. Select the *PCML value from the list. Specify to generate the program interface 8. Enter/qibm/wsslabxx/getdatas.pcml for the Program interface stream file field. 9. Click OK to submit the command. After the compile the iSeries Error List view is shown, listing all compile errors. You may only see information and warning messages that means your compile was completed and the program module was created. iSeries Command log 10. Click the iSeries Commands Log tab to check if the compile was successful. This log shows the Remote System Explorer job messages. If you get a message that there have been errors found in your program, go through the edit compile fix cycle. 4.8.3 Fixing errors In the iSeries Error List view, check the errors: 1. Double-click on the error. This positions the cursor in the Editor window on the statement that is wrong. 2. Fix all errors. 3. Save the source member. 4. Go back to the Remote Systems view. 5. Right-click the member to run the CRTRPGMOD command. 6. Continue this cycle until you get a clean compile. 4.8.4 Creating a service program To create a service program: 1. In the Remote Systems view find the GETDATAS module in library WSSLABxx. Remote Systems view Note: If you don't see the module, right-click library WSSLABxx and click Refresh on the pop-up menu. 2. Right-click GETDATAS and click Create > Service Program on the pop-up menu. The Create Service Program (CRTSRVPGM) dialog opens. CRTSRVPGM prompt 3. In the Export list, select *ALL. 4. Click OK. Check the command log to see that the Service program was created. 5. Click the iSeries Commands Log tab at the bottom of the workbench. You should see a message that the Service program was created. iSeries Command Log 4.9 Recap Congratulations! You have completed 4.0, "Creating the RPG service program for your Web application (optional)". You should now understand: * How to start the workbench * LPEX editor features * How to open the Remote System Explorer perspective * How to find an iSeries source member * How to edit an iSeries source member * How to create a module and a service program object * How to create a PCML program interface description Now that you have created a RPG service program, you can continue to 5.0, "Creating a Web project". 5.0 Creating a Web project In this chapter, you will learn how to create a Web project and then supply the information which the iSeries server will use for serving the business information for this Web application. You will also learn about perspectives, J2EE settings, Web projects, and the iSeries Web Tools Run-Time Configuration wizard. In order to accomplish these learning objectives, there are several steps that are involved, including: * 5.1, "Exercise 4.1: Opening the Web perspective" * 5.2, "Exercise 4.2: Creating a dynamic Web project" * 5.3, "Exercise 4.3: Setting up the iSeries server information" The exercises in this chapter must be completed in order. Start with 5.1, "Exercise 4.1: Opening the Web perspective" when you are ready to begin. Length of time: This chapter will take approximately 5 minutes to complete. 5.1 Exercise 4.1: Opening the Web perspective In this exercise you will use the Web perspective. This allows you to access tools and views specifically related to Web application development. However, you are still in the Remote System Explorer (RSE) perspective which gives you the tools to do your iSeries programming tasks as you have discovered in the previous chapter. 5.1.1 Perspectives Before we go further, let's review perspectives. Perspectives are a collection of views and tools assembled to help different kinds of users to do their job when they use the workbench. These workbench users will have different jobs (roles), for example, one user needs to work with iSeries objects related to RPG/COBOL, another user is dealing with Java programs, and another user with Web page development. Each of these different user types will need different views of the files/objects they are working with and they need different tools. The perspectives present the user with a selection of specific views/tools geared towards the different roles the users have. The workbench has many predefined perspectives, like the: * Web perspective for Web developers. * Remote System Explorer perspective for iSeries programmers. You can also create your own perspective by using the Save Perspective as option under the Window menu in the workbench, after you have modified a perspective. Now that you know what a perspective is we can go ahead with our exercise. You are a Web developer in this tutorial and that is the reason you will select the Web perspective. The Web environment provides its own perspective since it needs to give its users access to unique views and tools targeted towards Web tasks. You create a Web project in the Web perspective. To open the Web perspective: Open perspective 1. Click Window > Open Perspective on the workbench menu. 2. Then click Other on the pop-up menu. The Select Perspective dialog opens. Select perspective 3. Select Web from the list. 4. Click OK. The workbench will now show the Web perspective with the Project Navigator view open on the left hand side. Web Projects view 5.2 Exercise 4.2: Creating a dynamic Web project Web projects hold all of the Web resources that are created and used when developing your Web application. The first step to creating or importing a Web application is to create either a static or a dynamic Web project. Static Web projects are meant to contain only simple Web site resources, such as HTML files. Dynamic Web projects are used to structure Web applications that will use more complicated, dynamic Web technologies, such as JavaServer Page files, and possibly data access resources. To create a dynamic Web project: 1. Click File > New on the workbench menu. 2. Then click Dynamic Web Project on the pop-up menu. Dynamic Web Project This starts the Dynamic Web Project wizard. The initial page of the wizard opens. Project name 3. Accept the default value in the Project location field. This is where your project is stored in your file system. 4. In the Project name field, type WSSLABxx. 5. Select the Configure advanced options check box to specify or customize the project options, such as adding Struts support to your Web project. 6. Click Next. The J2EE Settings page opens. This page allows you to specify the J2EE level for the Web project. If you plan to use the WebSphere Application Server Version 5 only, then you select J2EE level 1.3. If you are using previous versions of WebSphere Application Server in your environment and are planning to deploy the Web application to these versions then you use J2EE level 1.2 since these earlier versions of WebSphere Application Server don't support the J2EE level 1.3. In this exercise you use the Web application in the WebSphere Test Environment, which is Version 5, so you use J2EE level 1.3 which is the default. Page to select JSP level 7. In the EAR project field, type WSSLABxxEAR. A new or existing Enterprise Application project must be associated with your new Web project for purposes of deployment. The Enterprise Application project is new, so you typed the name of the new project. When your Web project is created at the end of the wizard, the new Enterprise Application project (EAR file) is also created. The default is an Enterprise Application project named DefaultEAR located in the same directory as your new Web project. 8. Leave the default value for the Context root field. The default value for the context root is the name you provided for your Web project. The context root is the Web application root, the top-level directory of your application when it is deployed to a Web server. The context root can also be used by the links builder to ensure that your links remain ready to publish as you move and rename files inside your project. 9. Leave the default value in the J2EE level list. By default, the Web project's J2EE level is set to the Workbench's J2EE level. Any new servlets and JSP files that you create should adhere to the latest specification level available; previous specification levels are offered to accommodate any legacy dynamic elements that you expect to import into the project. 10. Click Next. The Features Page opens. Features page 11. Leave the Default style sheet (CSS) check box selected to create a default CSS file (called Master.css) for any HTML and JSP files included in the project. 12. Select the Add Struts support check box as you want to create a project that uses Struts technology. 13. Select the iSeries Web Components Tag Library check box as you want to add iSeries fields and controls to the Web pages of your Web application. 14. Click Next to go to the Struts Settings page and ensure that Create a Resource Bundle for the Struts Project is selected. If not, select the Override default settings check box and then select Create a Resource Bundle for the Struts Project. 15. Click Finish to create the Web project. Now you are back in the workbench and your new project and project files appear in the Project Navigator. J2EE Navigator view with your project files 5.3 Exercise 4.3: Setting up the iSeries server information Before you can start creating your application, you will need to define where the RPG program you will connect to later on in this tutorial is located. You need to specify the iSeries server name and the user-ID and password to be used when starting the job on the iSeries to run your program. To set up the iSeries server: 1. In the Web perspective, right-click the WSSLABxx project in the Project Navigator. Setup iSeries information 2. Click Specify iSeries Web Tools Run-Time Configuration on the pop-up menu. Tip: You could also use the Configure iSeries button button from the workbench toolbar to open the Run-Time Configuration wizard. The iSeries Web Tools Run-Time Configuration wizard opens. Wizard to specify your iSeries server information You use this wizard to specify how Web interactions that perform program calls to an iSeries host should be connected and authenticated. 3. In the Host name field, type the name of the iSeries host where your program is located, for example s400a. 4. Enter your user ID and password for the iSeries host in the appropriate fields. You need to ensure that your User ID has been set up in a way that it contains the correct library list. If not, you will have to use this table to add a library to the library list when the job gets started to run your program. 5. Enable password-encoding is selected by default. This option ensures that the password appears in encoded format in the web.xml file. If you clear the check box for this option, the password appears as plain text in the web.xml file. 6. Click Next. 7. Select the Display detailed run-time errors check box to see the details for any errors that occur during the runtime of your Web application. This is useful for tracing and debugging development errors that may occur. Configure Run Time 8. Select the Use iSeries message file check box to retrieve error messages from the iSeries host. 9. Click Browse to specify the iSeries message file. 10. Click the plug sign + beside s400a. 11. Click the plus sign + beside *LIBL. Locating the message file 12. Drill down to WSSLABXX > MYMSGF.*msgf. Locating the iSeries message file 13. Click OK. 14. Click Finish to define authentication and run-time values for your host program or procedure call to be made by your Web interaction in the Web project. 5.4 Recap Congratulations! You have completed 5.0, "Creating a Web project". You should now understand: * The concepts of perspectives, the Web perspective, static Web projects, dynamic Web projects and J2EE settings * The importance of creating a Web project * The importance of setting up iSeries run-time configuration information * How to open the Web perspective * How to create a Dynamic Web project * How to set up iSeries server information Now that you have created a Web project, you can continue to 6.0, "Creating a Web application". 6.0 Creating a Web application In this chapter, you will learn how to create the interaction to use an input and output page, and to create the servlet to invoke an RPG program to get data from the iSeries database. You will also learn about interactions, Web input and output pages and Program Call Markup Language (PCML). Finally you will learn how to see the flow structure of your Web application. In order to accomplish these learning objectives, there are several steps that are involved, including: * 6.1, "Exercise 5.1: Invoking the Web Interaction wizard" * 6.2, "Exercise 5.2: Specifying the input and output page" * 6.3, "Exercise 5.3: Defining the iSeries GETDATA program invocation and parameters" * 6.4, "Exercise 5.4: Defining the iSeries GETDATAS service program invocation and parameters" * 6.5, "Exercise 5.5: Defining the input page content" * 6.6, "Exercise 5.6: Defining the output page content" * 6.7, "Exercise 5.7: Specifying error handling" * 6.8, "Exercise 5.8: Enhancing the output page" * 6.9, "Exercise 5.9: Ensuring the customer number field cannot be modified" * 6.10, "Exercise 5.10: Visualizing the flow structure of your Web application" The exercises in this chapter must be completed in order. Start with the 6.1, "Exercise 5.1: Invoking the Web Interaction wizard" when you are ready to begin. Length of time: This chapter will take approximately 20 minutes to complete. 6.1 Exercise 5.1: Invoking the Web Interaction wizard During this exercise you will use the Web Interaction wizard to create the interface description for parameters to be passed to an iSeries program. You will also generate a Web page based on the parameters definition used by the program. Some of the parameters will be defined based on existing iSeries database field definitions. To invoke the Web Interaction wizard: Web Diagram popup menu 1. Right-click WSSLABxx in the Project Navigator. 2. Click New > Other on the pop-up menu. 3. Select Web from the left pane. Creating a new Web Interaction 4. Select Web Interaction from the right pane. 5. Click Next. An interaction is the span between the submit of a request from the current Web page to the post of a new Web page. An interaction could be a simple request to the HTTP server to load another page. In this environment an interaction will be made up of a call to an iSeries program, waiting for the return of the program with data and then invoking a JSP to show the next Web page containing the data returned from the program. First you have to give the interaction a name so you can reference it later on. The Specify a Name and Location for your Web Interaction page opens. Specify Name and Location 6. Type custInquiry in the Web Interaction name field. 7. Click Next in the Web Interaction wizard. The Specify the Input and Output Pages for your Web Interaction page opens. 6.2 Exercise 5.2: Specifying the input and output page The next page of the Interaction wizard asks for information about the Web pages that are involved in this interaction. You have an input page that invokes the interaction and an output page that displays the results of interaction. The output page shows in the browser at the end of the interaction. The wizard generates both Web pages for you. Specify input and output page 1. Click Generate input page radio button. 2. Click Generate output page radio button. 3. Select custInquiryInput.jsp and click Rename. Renaming the input page 4. Enter inquiry.jsp as the new input JSP file name. 5. Click OK. 6. Select custInquiryResults.jsp and click Rename. 7. Enter result.jsp as the new output JSP file name. 8. Click OK. 9. Click Next. The Specify the Input and Output Parameters for your iSeries Host Program page opens. +----------------------------------------------------------------------+ | To define the iSeries GETDATA program invocation and parameters go | | to 6.3, "Exercise 5.3: Defining the iSeries GETDATA program | | invocation and parameters". | +----------------------------------------------------------------------+ | To define the iSeries GETDATAS service program invocation and | | parameters go to 6.4, "Exercise 5.4: Defining the iSeries GETDATAS | | service program invocation and parameters". | +----------------------------------------------------------------------+ 6.3 Exercise 5.3: Defining the iSeries GETDATA program invocation and parameters The next page asks you to define the parameters you want to pass between the Web pages and the iSeries program that processes the requests. Here you will re-use the PCML program interface definition that was created when you compiled your source member. Importing PCML 6.3.1 Getting the program interface definitions To get the program interface definitions that you want to call on the iSeries: 1. Click Import PCML The Import PCML dialog opens. Selecting Remote File System 2. Click the arrow on the Select PCML file from field 3. Select Remote File System from the list. The Browse For File dialog opens. Locating the PCML file 4. Expand the tree view of the IFS drive to the directory where you stored the PCML file generated by the RPG compiler: Since you followed the instructions and used a program call, it should be in QIBM/WSSLABxx/getdata.pcml Selecting getdata.pcml under QIBM > WSSLABxx 5. Select the correct file. 6. Click OK. 7. The Import PCML dialog appears with a list of the program interface constructs contained in the PCML file. Select All * A data structure * A call interface 8. Click Select All. 9. Click OK. 6.3.2 Specifying the input and output parameters The Specify the Input and Output Parameters for your iSeries Host Program page opens again, now containing the program description you just imported. Updating the behavior of the CUSTNOI parameter 1. Expand GETDATA in the left pane under Program call definitions. The information from the PCML file gets included in the right pane and the parameters defined for this program appear. 2. Select the first parameter CUSTNOI. 3. In the right pane, change the Usage field from Input/Output to Input to indicate that this parameter is used to pass a value from the Web page to the program. 4. Click OK Updating the behavior of CSTRUC parameter 5. In the left pane select the CSTRUC parameter. 6. In the right pane, change the Usage field from Input/Output to Output, indicating that this parameter is used to pass a value from the program to the result Web page. 7. Click OK. 8. Do the same for the FEEDBACK parameter. Associate GETDATA with this interaction 9. Now select GETDATA in the left pane under Program call definitions. This will fill the right pane with the program information. 10. In right pane, select the check box Associate this program with the interaction. 11. Click OK. 12. Click Next. +----------------------------------------------------------------------+ | Skip the next exercise and continue with 6.5, "Exercise 5.5: | | Defining the input page content". | +----------------------------------------------------------------------+ 6.4 Exercise 5.4: Defining the iSeries GETDATAS service program invocation and parameters The next page asks you to define the parameters you want to pass between the Web pages and the iSeries service program that processes the requests. Here you will re-use the PCML program interface definition that was created when you compiled your source member. Importing PCML 6.4.1 Getting the program interface definitions To get the program interface definitions that you want to call on the iSeries: 1. Click Import PCML The Import PCML dialog opens. Selecting Remote File System 2. Click the arrow on the Select PCML file from field 3. Select Remote File System from the list. The Browse For File dialog opens. Locating the PCML file 4. Expand the tree view of the IFS drive to the directory where you stored the PCML file generated by the RPG compiler: Since you used a service program, it should be in QIBM/WSSLABxx/getdatas.pcml. Selecting getdatas.pcml under QIBM > WSSLABxx 5. Select the correct file. 6. Click OK. 7. The Import PCML dialog appears with a list of the program interface constructs contained in the PCML file. Select All * A data structure * A call interface 8. Click Select All. 9. Click OK. 6.4.2 Specifying the input and output parameters The Specify the Input and Output Parameters for your iSeries Host Program page opens again, now containing the program description you just imported. Updating the behavior of the CUSTNOI parameter 1. Expand GETRECORD in the left pane under Program call definitions. The information from the PCML file gets included in the right pane and the parameters defined for this program appear. 2. Select the first parameter CUSTNOI. 3. In the right pane, change the Usage field from Input/Output to Input to indicate that this parameter is used to pass a value from the Web page to the program. 4. Click OK Updating the behavior of CUST1 parameter 5. In the left pane select the CUST1 parameter. 6. In the right pane, change the Usage field from Input/Output to Output, indicating that this parameter is used to pass a value from the program to the result Web page. 7. Click OK. 8. Do the same for the FEEDBACK parameter. Associate GETDATAS with this interaction 9. Now select GETRECORD in the left pane under Program call definitions. This will fill the right pane with the program information. 10. Change the name of the service program to GETDATAS. 11. Select the Program type *SRVPGM. 12. In right pane, select the check box Associate this program with the interaction. 13. Click OK. 14. Click Next. 6.5 Exercise 5.5: Defining the input page content Now you need to specify which of the input parameters you want to see on the input page for this interaction that gets generated by the wizard. This is easy in this application since you only have the customer number input field to handle. You also have the capability to enhance the page layout by changing colors of the page background and changing the heading. The Design the Input Form page contains a properties table that shows all input capable parameters, and a sample of the Web page that will be created. Input form 6.5.1 Changing the heading To change the heading: 1. Click the field beside the Page Title property in the Property table and type Customer Inquiry. 2. Press Enter to apply this change to the sample page. Now you want to change the customer number field properties. 3. Click the Fields tab on the Properties table. This opens the field properties for the selected field in the list. 6.5.2 Changing a field label To change a field label: Properties list 1. In the left pane of the Design the Input Form page, select CUSTNOI. 2. Click the field beside the Label property, and type Enter customer number. 3. Press Enter. 4. Click Next to advance to the next wizard page. 6.6 Exercise 5.6: Defining the output page content Now you can specify what data should be displayed on the Output Web page generated for you. In the right pane of the wizard you see a sample of the page that will be generated. First, change the Input style of the output parameter CSTRUC.CUSTNO. This will enable you to use customer number as an input parameter to future features of your Web project. To define the output page: Output parameter 1. Select CSTRUC.CUSTNO. 2. Click the Fields tab. 3. From the Input Style list, select Text Entry. By default all output parameters will be added to the Web page, but you don't want the data in the FEEDBACK parameter to be displayed. Let's go through the steps to erase the FEEDBACK parameter from the output page. The output parameter 4. In the left pane of the Design the Result Form, clear the FEEDBACK check box. This will remove it from the Web page. You will stay on this page to specify the error handling. 6.7 Exercise 5.7: Specifying error handling Now you can specify what should happen in case a customer number didn't match the customer numbers in your database. 1. In the left pane of the Design the Result Form, select the FEEDBACK parameter. You will see the properties for this variable in the Properties table. Properties Table 2. Locate the Message Controller heading in this Properties table. Change the message controller to true 3. Click the field beside the Message Controller and set it to true. 4. Click New. 5. Set the Parameter Value to *OTHER from the list. Change Message ID to *Select 6. Set the Message ID to *SELECT from the list. This opens a Message Selection Window. 7. Drill-down to s400a > WSSLABXX/MYMSGF > MYMSGF > CUS0001 Select CUS0001 as the message file 8. Click OK. 9. Leave the default value of the Web Component. 10. Click New. 11. Enter 0 as the Parameter Value. Completed Message Control Specification 12. Press Enter. 13. Set Message ID to *NONE using the list. 14. Set Web Component to result.jsp-DEFAULT using the list. 15. Click OK. Here is what you just did: * If the return value of the FEEDBACK parameter is 0, display the customer details in the result.jsp Web page. * Any other return value in the FEEDBACK parameter, use the message ID CUS0001 in the specified message file, place the Customer number input in the message substitution variable, and display the Web page inquiry.jsp with the error message CUS0001. The message handling is defined. 6.8 Exercise 5.8: Enhancing the output page Next you enhance the look of the Web page. To enhance the output page: 1. Click the Page tab in the Properties table. Customize the output 2. Click the field beside the Page title and type Customer Details. 3. Click the field beside the Background Color and click the selection button on the right side of the field. The Color palette opens. 4. Select a light yellow from the Color palette. Color selection 5. Click OK on the Color palette. 6. Click the field beside the Title Color and click the selection button on the right side of the field. 7. Select Blue from the Color palette. 8. Click OK on the Color palette. You notice the sample page gets updated as you choose different properties. If you don't like the suggested color choices, go ahead and create your own design. You need to modify the labels of the fields that show up on the output JSP. 9. Click the Fields tab. 10. Select each field in the top left, and for each one, change the Label value to the values described in the table below. Changing the parameter labels +----------------------------------+----------------------------------+ | CUSTNO | Customer Number | +----------------------------------+----------------------------------+ | CUSTNA | Customer Name | +----------------------------------+----------------------------------+ | REPNO | Representative Number | +----------------------------------+----------------------------------+ | CONTAC | Contact | +----------------------------------+----------------------------------+ | CPHONE | Phone Number | +----------------------------------+----------------------------------+ | CFAX | Fax Number | +----------------------------------+----------------------------------+ | CADDR | Address | +----------------------------------+----------------------------------+ | CCITY | City | +----------------------------------+----------------------------------+ | CCOUNT | Country | +----------------------------------+----------------------------------+ | CZIP | Zip | +----------------------------------+----------------------------------+ 11. In the left pane of the Design the Result Form page, clear the struc.CZIPLO check box. You don't need to display this variable. 12. Click Finish on the Design the Result Form page. The Interaction wizard creates the necessary files for your application: * The file custInquiry.wit is created in the project. This file reflects the data you entered on the pages of the Web Interaction wizard for the interaction you identified as cust. To modify these settings, double-click on the file to open the Web Interaction wizard. * The default package under the Java Source folder contains the .java files generated by the wizard. * The classes folder under Web Content/WEB-INF contains the .class files generated from the .java files that were created by the wizard. Note: If you encounter the following error message in your Tasks list: Error shown under Tasks view 1. Click the Server tab to access the Server view. 2. Right-click the test server and select Stop on the pop-up menu. Stop server 3. Switch to your Project Navigator and right-click your project folder. 4. Click Refresh on the pop-up menu. Refresh project 5. Right-click again your project folder and click Rebuild Project. Rebuild Project This should remove the error message in your Task view. 6.9 Exercise 5.9: Ensuring the customer number field cannot be modified Let's make sure that the Customer Number field on your results.jsp page cannot be modified. To ensure the customer number field cannot be modified: 1. In the Project Navigator, expand WebContent and locate result.jsp. Project Navigator 2. Right-click result.jsp. To open result.jsp 3. Click Open on the pop-up menu. This opens the result.jsp page on the Page Designer. Changing attributes of Customer Number 4. Select the Text Entry field of Customer Number in Page Designer. Notice the Attributes view of that Text field appears. 5. Select the Read-only check box. This prevents any modifications to the Customer Number. 6. Save your changes and close result.jsp. 6.10 Exercise 5.10: Visualizing the flow structure of your Web application A Web diagram is a view that helps you visualize the flow structure of a Struts-Based Web Application. Because of the indirectness involved with a Struts application, being able to visually see the application's flow can help you to better understand the application. 6.10.1 Struts Before you create a Web diagram, let's first look at what Struts is all about. First, Struts is a set of Java classes and JSP tag libraries that provide a conceptual framework for developing Web applications. The Struts technology is open source and was developed as part of the Apache Software Foundation's Jakarta project. Second, Struts provides numerous, custom JSP tags that are simple to use but are powerful in the sense that they hide information. The Page Designer does not need to know much about form beans, for example, beyond the bean names and the names of each field in a given bean. Third, you can use the diagram editor to show all or part of a Struts application. For example, suppose you have a three-part Struts application. One part handles the login process, one part handles product inquiries, and a third part handles product updates. In this case you could draw three diagrams to represent this system, or you could draw the entire system in a single diagram. Because one diagram can be included inside another, it would probably make more sense to represent this Struts application using a set of three diagrams. Now, that you know what Struts is, you can go ahead with this exercise. You will now create a Web diagram that will show you the visual components of the Web application you just created. An empty Web diagram (diagram.gph) should have been generated for you during project creation. To create a Web diagram: 1. If you don't see it (diagram.gph) in the editor, in the Project Navigator view, expand WSSLABxx. Locate diagram.gph under WSSLABxx in Project Navigator view 2. Locate and double-click diagram.gph. You will now see diagram.gph in the editor. Web Diagram Now, let's populate the Web diagram: 1. Locate inquiry.jsp under WSSLABxx and then WebContent in the Project Navigator. 2. Click inquiry.jsp and drag it to diagram.gph. You will notice the cursor change from Drag and drop to Drag and drop. 3. In the Web diagram, right click inquiry.jsp. inquiry.jsp: Draw > Draw All From 4. Click Draw > Draw All From on the pop-up menu. You will now see the custInquiry interaction. 5. Right-click custInquiry and click Draw > Draw Selected From. 6. Select the result.jsp check box result.jsp checkbox 7. Click OK. You should now see the graphical representation of the Web interaction that you've created in a previous exercise. 8. Save and close diagram.gph. 6.11 Recap Congratulations! You have completed 6.0, "Creating a Web application". You should know understand: * The purpose of an interaction. * How to invoke a Web interaction. * How to specify input and output pages. * How to define a program invocation and parameters. * How to invoke a service program. * How to define the program structure. * How to add reference fields from DB2/400 to the program structure. * How to add a structure as a parameter. * How to add a feedback parameter. * How to define the input page content. * How to define the output page content. * How to specify error handling. * How to enhance the output page. * How to ensure the customer number field cannot be modified. * The purpose of Struts. * The purpose of a Web diagram. * How to create a Web diagram from an existing Web Interaction. You are ready to run your Web application. Continue to 7.0, "Running the Web application". 7.0 Running the Web application In this chapter you learn how to test the Web application locally without deploying the files in the Web project to the host server. Testing your Web application locally includes using the iSeries Web Tools Run-time Configuration wizard to specify the authentication and run-time values for every host program or procedure call made by any Web interaction in the Web project. This is something you have already done in 3.0, "Creating an RPG program" or 4.0, "Creating the RPG service program for your Web application (optional)". In order to accomplish these learning objectives, there are several steps that are involved, including: * 7.1, "Exercise 6.1: Opening the Web perspective" * 7.2, "Exercise 6.2: Finding the Web application" * 7.3, "Exercise 6.3: Selecting the run on server option" The exercises in this chapter must be completed in order. Start with the 7.1, "Exercise 6.1: Opening the Web perspective" when you are ready to begin. Length of time: This chapter will take approximately 5 minutes to complete. 7.1 Exercise 6.1: Opening the Web perspective To open the Web perspective: 1. Click the Web perspective icon, on the left taskbar of the workbench. Web perspective icon 2. If there is no Web perspective icon, select Window > Open Perspective > Web from the workbench menu. 7.2 Exercise 6.2: Finding the Web application To find the Web application: 1. In the Project Navigator, expand your project WSSLABxx. 2. Expand the WebContent folder. 7.3 Exercise 6.3: Selecting the run on server option To test your application locally using the WebSphere test environment: 1. Right-click inquiry.jsp and click Run on Server on the pop-up menu. Project Navigation You will see a message to select the Server to run in the Test Environment. Server selection 2. Make sure Test Environment is selected in the Server type list. 3. Select the Set server as project default (do not prompt) check box. 4. Click Finish to configure and launch the server. After the WebSphere server has started, your Web application input page will display in the workbench browser. Workbench browser 5. Type 0010100 as the Customer Number. 6. Click Submit. This launches the generated output or result page. a. If you see a Page not found error, go to the Servers view. Restart server b. Restart the server instance. Then go back and try the Run on Server option again; the Server sometimes needs to be restarted to pick up the changes. You will see the Result page with customer data appearing in the workbench browser. Result page Next, test the message handling. 7. Click the Back button Back button in the browser to get back to the first page. 8. Enter a wrong customer number, for example, 9999. Incorrect input 9. Click Submit. An error message appears. Error message This capability is generated by the Web Interaction wizard. Remember that you specified something for the feedback field; you specified the message file to be accessed if the feedback field contains a non 0 value; in this case the feedback parameter will contain the message ID to be used for the error message. 7.4 Recap Congratulations! You have completed 7.0, "Running the Web application". You should now understand: * How to open the Web perspective * How to find the Web application * How to run the Web application Now that you have run your Web application you learn how to debug your Web application. Continue to 8.0, "Debugging a Web application". 8.0 Debugging a Web application In this chapter, you will learn how to debug a Web application. You will learn how to set up the debug environment, use a service entry point, add and remove breakpoints, display a variable, and view the call stack. You will debug a Web application that invokes the iSeries GETDATA program. In order to accomplish these learning objectives, there are several steps that are involved, including: * 8.1, "Exercise 7.1: Introducing the iSeries Integrated Debugger" * 8.2, "Exercise 7.2: Starting a Debug session using service entry points" * 8.3, "Exercise 7.3: Adding and deleting breakpoints" * 8.4, "Exercise 7.4: Displaying a variable" * 8.5, "Exercise 7.5: Viewing the call stack" * 8.6, "Exercise 7.6: Closing the debug session" The exercises in this chapter must be completed in order. Start with the 8.1, "Exercise 7.1: Introducing the iSeries Integrated Debugger" when you are ready to begin. Length of time: This chapter will take approximately 20 minutes to complete. 8.1 Exercise 7.1: Introducing the iSeries Integrated Debugger The Integrated Debugger is a source-level debugger that enables you to debug and test an application that is running on an iSeries system. It provides a functionally rich interactive graphical interface that allows you to: * View source code or compiler listings, while the program is running on the iSeries system. * Set, change, delete, enable and disable line breakpoints in the application program. You can easily manage all your breakpoints using the Breakpoints view. * Set watch breakpoints to make the program stop whenever a specified variable changes. * View the call stack of your program in the Debug view. As you debug, the call stack gets updated dynamically. You can view the source of any debug program by clicking on its call stack entry. * Step through your code one line at a time. * Step into or step over program calls and ILE procedure calls. * Display a variable and its value in the Monitors view. The value can easily be changed to see the effect on the program's execution. * Locate procedure calls in a large program quickly and easily using the Modules/Programs view. * Debug multithreaded applications, maintaining separate stacks for each thread with the ability to enable and disable any individual thread. * Load source from the workstation instead of the iSeries - useful if you don't want the source code on a production machine. * Debug client/server and distributed applications. The Debugger supports RPG/400(R) and ILE RPG, COBOL and ILE COBOL, C, C++ and CL. In the following exercise you will be given the opportunity to learn about some of the basic features of the Debugger. 8.2 Exercise 7.2: Starting a Debug session using service entry points In this exercise you will use service entry points to debug a Web application. The service entry point feature is designed to allow easy debugging of Web applications that invoke business logic written in RPG, COBOL, CL, or even C or C++. The service entry point is a special kind of entry breakpoint that can be set directly from the Remote System Explorer. It is triggered when the first line of a specified procedure is executed in a job that is not under debug. Service entry points allow you to gain control of your job at that point. A new debug session gets started and execution is stopped at that location. To start a debug session: 1. In the Remote System Explorer perspective, expand the iSeries server icon (s400a) 2. Expand iSeries Objects 3. Expand the Library List. If prompted, type your User-ID and password. 4. Expand the library WSSLABxx. You will see all objects in this library. Now you will start the debug session and set a service entry point. 5. Right-click GETDATA.*pgm.rpgle 6. Click Service Entry Point > Set on the pop-up menu. 7. Click the Web Browser tab to switch back to the Web browser. 8. Type 0010100 in the Enter customer number field. 9. Click the Submit button, which will invoke GETDATA*pgm.rpgle on the iSeries host. At this point, the Service Entry point is hit and the debug session is started. Debug Perspective Notice that it also opens an instance of the GETDATA source code in the debug editor. You now have the access to debug this source. Let's look at some more debug features. 8.3 Exercise 7.3: Adding and deleting breakpoints Breakpoints are markers you place in your program to tell the debugger to stop your program whenever execution reaches that point. For example, if you suspect that a particular statement in your program is causing problems, you could set a line breakpoint on the line containing the statement, then run your program. Execution stops at the breakpoint before the statement is executed. You can then check the contents of variables and view the call stack, and execute the statement to see how the problem arises. You can only set breakpoints at executable lines. All executable lines are displayed in blue. The easiest way to set a breakpoint is to right-click on the line in the Source view. To set a breakpoint: 1. Click anywhere on line 8. 2. Right-click and click Add breakpoint on the popup menu. A dot with a check mark in the prefix area indicates that a breakpoint has been set for that line. The prefix area is the small grey margin to the left of the source lines. Debug icon on line 8 3. Click on line 31. 4. Right-click and click Add breakpoint on the pop-up menu. 5. Click the Breakpoints tab in the upper right pane of the workbench. 6. In the Breakpoints view right-click the breakpoint for line 8. Here you can manage your breakpoints. You can disable, or remove breakpoints accordingly. Breakpoints view 8.4 Exercise 7.4: Displaying a variable You can monitor variables in the Monitors view. Now you will monitor the variable CUSTNOI. To monitor a variable: 1. In the Source view double-click the variable CUSTNOI on line 22. 2. Right-click CUSTNOI. 3. Click Monitor Expression on the pop-up menu. The variable appears in the Monitors view. If you quickly want to see the value of a variable without adding it to the Monitor, you can place the cursor on a variable to see its value in a pop-up window. This works well for scalars, but not for arrays or data structures. 8.5 Exercise 7.5: Viewing the call stack The Debug view in the upper left pane, lists all call stack entries. It contains a tree view for each thread. The thread can be expanded to show every program, module, procedure and method that is on the stack at the current execution point. If you double-click a stack entry that has debug data, the corresponding source will show up. Otherwise the message No Debug data available appears in the debug editor. In the Debug view, expand the stack entry of Thread:1 if it is not expanded already, by clicking the plus sign + in front of it. Viewing the call stack 8.6 Exercise 7.6: Closing the debug session To close a debug session: 1. Click Resume on the Debug toolbar. The session will stop at the first breakpoint on line 8. 2. Click Resume again. The session will stop at the breakpoint on line 31. 3. Click Resume again. 4. Click OK on the Program Terminated window. Next, close the Debug perspective. 5. Right-click the Debug icon on the left taskbar of the workbench. 6. Click Close on the pop-up menu. Close Debug perspective 7. Switch to the Remote System Explorer perspective to remove the Service Entry Point on GETDATA.*pgm.rpg. 8. Drill down to s400a > iSeries Objects > Library List > WSSLABXX > GETDATA.*pgm.rpg 9. Right-click on GETDATA.*pgm.rpg 10. Click Service Entry Point > Remove on the pop-up menu. 8.7 Recap Congratulations! You have completed this 8.0, "Debugging a Web application". You should now understand: * Debugger features * How to start a debug session using service entry breakpoints * Add and delete breakpoints * Display a variable * View the call stack * Close the debug session While the original service entry point design was meant to assist with debugging Web applications, using the feature is also beneficial when debugging applications in an environment where the job name is not known ahead of time. Some sample scenarios include: Debugging WebFacing applications Typically you would want to debug your RPG/COBOL code that is driven by the JSP that is executing in the application server. You do not know the name of the job in which your RPG/COBOL program will run, ahead of time, so the use of service entry points is an ideal solution for this scenario. Debugging any application that uses the Toolbox program or service program calls When a program or service program is called and the code where the service entry point is set is about to execute, the debugger can take control of the application. With this technique, you can put the program or service program invoked by the Toolbox under debug although you do not know which job it will be running in. Debugging applications running in a multi-job environment If your application runs in a multi-job environment, service entry points will significantly simplify your life while debugging. You would set a service entry point in the program that is about to be spawned in a new job. When the program is spawned and the line where the service entry point is set is about to execute, the debugger will be able to gain control of the program and stop at that line. Next you want to add an informative error page to your Web application. Continue to 9.0, "Adding an error page". 9.0 Adding an error page In this chapter, you will learn how to create an informative error page using Page Designer for when a customer enters an incorrect customer number. This way, the customer won't just be given an error message, but will have a more informative and helpful response from the Web Application, which is easy to customize. You will also learn how to add the error page to your existing Web application using the Web Interaction wizard and to use the RSE perspective to modify the program or service program to call the error page. In order to accomplish these learning objectives, there are several steps that are involved, including: * 9.1, "Exercise 8.1: Creating the flow control page" * 9.2, "Exercise 8.2: Modifying your Web interaction" * 9.3, "Exercise 8.3: Testing the new error page" The exercises in this chapter must be completed in order. Start with 9.1, "Exercise 8.1: Creating the flow control page" when you are ready to begin. Length of time: This chapter will take approximately 15 minutes to complete. 9.1 Exercise 8.1: Creating the flow control page First we need to create the error page using Page Designer. To create the error page: 1. In the Web Perspective, expand your project and drill down to the Web Content folder. Project Navigator 2. Right-click the Web Content folder and click New > JSP on the pop-up menu. The New JSP File page opens. JSP page 3. In the File Name field, type RecordNotFound. 4. Click Finish. The Page Designer automatically opens. Your window will look like this. Page Designer 5. Click on the words Place content here. and change it to something like Sorry, there is no record for that customer number. 6. Press Enter. 7. Type Please check the number and try again. 8. Highlight the words try again and right-click. 9. Select Insert Link on the pop-up menu. The Insert Link window opens. 10. Click Browse next to the URL field. 11. Click File on the pop-up menu. The File Selection window opens. File Selection 12. Select inquiry.jsp. 13. Click OK. 14. Click OK in the Insert Link dialog. You have completed creating the flow control page. 15. Save and close the file. You could spend more time customizing this page, but for the purpose of this exercise you will leave the page as is. 9.2 Exercise 8.2: Modifying your Web interaction To modify the Web interaction: 1. Expand your project WSSLABxx if not already expanded. 2. Right-click custInquiry.wit and click Open With > Web Interaction Wizard on the pop-up menu. Open with Web Interaction Wizard The Web Interaction wizard opens. The name and location of your Web interaction are already specified. 3. Click Next to add a new output page. Specify input/output JSP's 4. Next to the result.jsp section, click Add. The Output JSP window opens. Output JSP 5. Expand Web Content. 6. Select RecordNotFound.jsp. 7. Click OK to add the new output page. Adding RecordNotFound.jsp as one of the output pages 8. Click Next in the Web Interaction wizard. You will re-use the Feedback parameter to control which page the Web Interaction will send next after it performs its action; the result.jsp or the RecordNotFound.jsp. So you don't have to add another parameter or change the parameters, you just change the values the feedback parameter returns depending on whether a customer record was found or not found. 9. Click Next since you don't need to define the program interface. This opens the Input Parameters page. 10. Click Next again since you don't need to change any input parameters. This opens the Output Parameters page. Output parameters page 11. Select feedback under the Output Parameters list. 12. Change the Message Controller property to false. 13. Select feedback under the Output Parameters list again. Now a Flow controller property is added to the Properties table. Flow Controller added to the Property Table 14. Change the Flow Controller property to true. The Flow Control Specification dialog opens. Flow Control Specification 15. The value *OTHER is already in the Value field for the /error.jsp. 16. Click the /error.jsp field to change the Output JSP page. 17. Select RecordNotFound.jsp from the list. 18. Click New. This creates a new flow condition. The default page is result.jsp. 19. The value 0 is already in the Value field with result.jsp in the Output JSP field. 20. Click OK. This will set the flow control such that if the value of Feedback is 0, then the program will output the customer information to the result.jsp page and display it. However, if the customer number doesn't exist in the database, the Feedback value will be something else other than 0, and instead of displaying a message near the input field, it will show the user the RecordNotFound.jsp page for a more helpful response. 21. Click Finish on the Output Parameters page to apply your changes to the Web Interaction. Click Finish to apply the changes Note: If you encounter the following error message in your Tasks list: Error shown under Tasks view 1. Click the Server tab to access the Server view. 2. Right-click the test server and select Stop on the pop-up menu. Stop server 3. Switch to your Project Navigator and right-click your project folder. 4. Click Refresh on the pop-up menu. Refresh project 5. Right-click again your project folder and click Rebuild Project. Rebuild Project This should remove the error message in your Task view. 9.3 Exercise 8.3: Testing the new error page Now that the flow control is in place, if you enter a wrong customer number, Entering wrong customer number you will get the error page instead of a message. Error Page Now follow the instructions below to run the modified project on the WebSphere Test Environment to see the result of adding flow control to your Web application. The server should still be running from the last time you ran the Web application. Every time you make a change to the Web application, you need to restart the server to pick up the changes. To restart the server: Restart server instance 1. Click the Servers tab to open the Servers view. 2. Select the server instance. Right-click and click Restart on the pop-up menu. The server instance should restart. 3. In the Web perspective Project Navigator locate the Web Content folder, and right-click inquiry.jsp. Run on server 4. Click Run on Server on the pop-up menu. 9.4 Recap Congratulations! You have completed 9.0, "Adding an error page". You should now understand how to: * Use Page Designer to add a new error page. * Use the Web interaction wizard to add the error page. * Use the RSE perspective to modify the program or service program to call the error page. * Create a program or service program object. Now that you have added an error page to your Web application to handle incorrect customer numbers, you can learn how to customize your input page. Continue to 10.0, "Enhancing the input page using Web tools". 10.0 Enhancing the input page using Web tools In this chapter, you will learn how to use the Web tools in the Development Studio Client workbench to update the input page of your customer inquiry Web application. The input page named inquiry.jsp is one of the files created by the Interaction wizard. This page is very plain. You will learn how to use Page Designer and some related Web tools in the workbench to add some color to the input page, as well as add some pictures to make it a more interesting Web page. In order to accomplish these learning objectives, there are several steps that are involved, including: * 10.1, "Exercise 9.1: Opening Page Designer" * 10.2, "Exercise 9.2: Working with page properties" * 10.3, "Exercise 9.3: Linking a cascading style sheet to the Web page" * 10.4, "Exercise 9.4: Designing and adding a logo" * 10.5, "Exercise 9.5: Adding a heading 1 tag to the page" * 10.6, "Exercise 9.6: Adding a picture to the page" * 10.7, "Exercise 9.7: Adding moving text to the page" * 10.8, "Exercise 9.8: Changing the text color" The exercises in this chapter must be completed in order. Start with 10.1, "Exercise 9.1: Opening Page Designer" when you are ready to begin. Length of time: This chapter will take approximately 15 minutes to complete. 10.1 Exercise 9.1: Opening Page Designer The first step is to locate the inquiry.jsp file and to start Page Designer. In Page Designer you will link the page to a cascading style sheet that comes as a sample with the workbench. To open the Web perspective: 1. In the workbench, open the Web perspective: You should now have the Project Navigator in your workbench. Web project with input.jsp file 2. Expand the WSSLABxx web project. 3. Expand the Web Content folder. 4. Right-click inquiry.jsp and click Open on the pop-up menu. Page Designer showing the Design page The Page Designer appears in the upper right pane of the workbench and shows the inquiry.jsp page as the Web Interaction wizard created it. Make sure that you are on the Design page in Page Designer. 5. Click the Design tab. 10.2 Exercise 9.2: Working with page properties Next you move the form down. To work with page properties: 1. Click underneath the heading Customer Inquiry. Add some space in the upper half of the input.jsp page 2. Press Enter number of times as shown above. 3. To change the page properties, right-click the background of the inquiry.jsp page in Page Designer. Page properties 4. Click Page Properties on the pop-up menu. The Page Properties window opens. Page properties dialog This window allows you to change some of the page properties. For example you could change the title. When this page is shown in a browser, the Window title bar of the browser will display Customer Inquiry. 10.3 Exercise 9.3: Linking a cascading style sheet to the Web page Now you will add a style to the Web page. You can use a style that is used in your company or you can use one of the sample style sheets that are provided in Development Studio Client. To link a style sheet to a Web page: Page Designer, linking a style to the Web page 1. Click the Gallery tab, if the Gallery view isn't already displayed. 2. Click the Style Sheet icon in the Gallery list. 3. Click the Thumbnail tab in the left bottom stacked view in the workbench. You should see thumbnail icons of all the styles available as shown above. 4. In the thumbnail view, scroll down to the bottom, until you see style sheet denim001.css in the list, or select a style sheet that you like best. 5. Click the thumbnail picture of denim001.css. 6. Hold the left mouse button down and drag the mouse cursor to the Page Designer window. The cursor will change from this shape , to this shape. When the latter cursor shape appears in the Page Designer window then, let go of the mouse left button. After a short while the Style sheet properties will be applied. 7. Click the Preview tab. You will see the colors in the page have changed to the style sheet definitions. Index.html page with style properties applied 8. Click the Design tab to get back to the Design page. 10.4 Exercise 9.4: Designing and adding a logo Now that you have the overall Web page look specified you will use the WebArt Designer to create a Logo that you then will add to this page. 10.4.1 Starting the WebArt Designer To start the WebArt Designer: Tools menu with WebArt Designer 1. Make sure the Page Designer is in focus. 2. Click Tools > WebArt Designer in the workbench menu. The WebArt designer opens. WebArt Designer dialog The WebArt Designer shows the Template Gallery on the left, where you find samples of logos, buttons, rollovers, images and more. The large white area in middle of the dialog is the canvas that is used to work with objects that you want to create or change. Now you will create a logo from scratch. You could also select one from the template gallery as the base for your own logo. 10.4.2 Creating the logo To create the logo: 1. Click the Create Logo button above the canvas or click Object > Create Logo. The Logo Wizard opens. Logo wizard dialog 2. In the Text field, type your company name and in the next line in the Text field, type wflabxx. 3. In the Font name list, select Comic Sans MS. 4. In the Font size list, select 46. 5. Under Alignment, select the Center radio button. Notice in the upper right corner of the dialog, a sample of the logo as specified is displayed. 6. Click Next to go to the next page of the wizard. The Select Color page opens. Logo wizard with Select Color page 7. Select the gradation type button; the middle one of the three type push buttons. Tip: The other buttons select color types: solid and textured. 8. Select beer from the colors available, or any other color you like best, just scroll through the list to find a gradation you like. Tip: You can change the colors by clicking the Others button on this dialog and create you own gradation. 9. Click Next to go to the next page of the wizard. The Select Outline page opens. Logo wizard with Select Outline page 10. Select the Seal outline from the list, or any outline you like best. 11. Click Next. The Select Text Effect page opens. Logo wizard with Select Text Effect page 12. Select the Emboss text effect, or one that you like best. 13. Click Finish. You return to the WebArt designer window. WebArt designer with new logo object 10.4.3 Resizing the logo To resize the logo object on the canvas: 1. Click the logo object to select it. 2. Move the cursor to the rectangle at the right bottom corner of the object; watch the cursor changing shape. 3. Drag the rectangle up and to the left so the object becomes smaller. 10.4.4 Saving the object as a WebArt object Now you need to save this object. First save it as a WebArt object. This allows you later on to work with the object again in WebArt Designer, but you can't use that format for your Web page. To save this object: 1. Click File > Save Canvas As on the WebArt Designer menu. The Save Canvas As window opens. WebArt Designer save dialog 2. In the File name field, type mylogo. 3. Click Save. Now you need to save the object in a form that can be displayed on a Web page. 10.4.5 Saving the object for a Web page To save the logo for a Web page: 1. Click File > Save wizard for Web from the WebArt Designer menu. The Save Wizard opens. Save wizard with Specific Objects page 2. Click the Save the selected object radio button. 3. Click Next. The Select File Format page opens. Save wizard with Select File Format page 4. Click the GIF radio button. 5. Click Next. The GIF Format page opens. Save wizard with GIF Format page 6. Click Finish. The Save As window opens. Save dialog Make sure the directory is pointing to the Web Content directory in the workspace where your Web project is located. 7. In the File name field, type mylogo. 8. Click Save. Close the WebArt designer. 9. Select File > Exit from the menu. You return to the workbench in the Web perspective and see the Project Navigator. 10.4.6 Placing the logo on the Design page To place the logo on the Design page: 1. Make sure you switch from the Gallery view to the Project Navigator. 2. Expand the WSSLABxx Web project. 3. Expand the Web Content folder. View of WebContent directory with mylogo.gif The mylogo.gif file should appear in the list as shown below. If it doesn't appear, the list might need to be refreshed. 4. Right-click the Web Project WSSLABxx folder icon. 5. Select Refresh. Hopefully you can see the file now in the Web Content folder, if not, go to Windows Explorer and search for the mylogo.gif on your hard drive. Move it to the Web Content folder in the Development Studio Client workspace. If you didn't use the default location as shown above, do a search for the workspace and the WSSLABxx directory in it. Move the mylogo.gif file into the Web Content sub directory under the WSSLABxx directory. Now you can take the logo and put it on your Web page that is still open in Page Designer. If Page Designer has been closed just open the inquiry.jsp file. Note: Make sure your are on the Design page, not the Preview page. 6. In the Project Navigator view select the mylogo.gif file. 7. Hold the left mouse button down. 8. Drag the file to the upper left side in the Page Designer window. 9. Release the mouse button. The logo is placed on the Design page. Dragging the mylogo.gif file onto the Design page 10.5 Exercise 9.5: Adding a heading 1 tag to the page Now you want to insert a heading below the logo. To add a heading 1 tag: 1. Position the cursor just below the logo at the first BR tag. Heading 1 2. Click Insert from the workbench menu. 3. Click Paragraph > Heading 1 from the pop-up menu. A frame appears that allows you to enter text. 4. Enter your company name. Enter your company name Now you want to use one of the sample pictures that comes with Development Studio Client and place this picture on the page. 10.6 Exercise 9.6: Adding a picture to the page To add a picture to the page: 1. In the Project Navigator, click the Gallery tab. Adding an image 2. Expand the Image folder. 3. Select the Illustration folder. 4. On the Design page beside the Gallery view select one of the sample illustrations, for example, use file u013cut.gif. 5. Drag the picture onto the Design page beside the logo. The Design page now contains a picture. Preview page with image You are almost done. Next you add moving text to the page. 10.7 Exercise 9.7: Adding moving text to the page To add moving text: 1. Back to the Design page, position the cursor underneath your company name. 2. Click Insert from the workbench menu. 3. Click Paragraph > Heading 3 on the pop-up menu. Heading 3 4. Leave the cursor positioned inside the heading 3 frame. 5. Click Insert from the workbench menu. Insert Marquee 6. Click Others > Marquee on the pop-up menu The Insert Marquee window opens. Insert Marquee window 7. Enter into the Text field Please enter customer number and press Submit button to start application. 8. Select Slide from the Movement list. 9. Select Finite from the Repetition list. 10. Select 1 from the Count list. The two last selections just avoid the text sliding in forever and not standing still. If you want more movement on the page, you can change these settings. 11. Select Lime in the Background color list. 12. Click OK. The Design page should look like: To save some space, you can remove some of the line break tags. 13. Position the cursor on the BR tag. Remove BR 14. Press the Delete key until the entry field and push buttons appear on your page: Next you view the page as it would appear in a browser. 15. Click the Preview tab at the bottom of the Design page. You will notice that your heading 3 text is sliding in. Preview page -- text sliding in 10.8 Exercise 9.8: Changing the text color Sometimes you want to change the text color. There is an easy way to apply another color to certain areas of text. To do that you return to the Design page. To change the text color: 1. Click the Design tab. Change text color 2. Select the company text (IBM) you want to change color on, by swiping the text area with the mouse cursor. Below the Page Designer window there are several tabs. 3. Click the Colors tab. 4. Select a color from the Color palette. 5. Click Text color from the Color menu. 6. Click Set as Text Color on the pop-up menu. You are done; now the selected text will be displayed with the color you selected for it. 7. Click the Preview tab to view your completed page. 8. Save the file inquiry.jsp. Preview with text color changed 9. Exit Page Designer. 10. In the Project Navigator expand the WSSLABxx folder. 11. Expand the Web content folder. 12. Right-click inquiry.jsp. 13. Click Run on server on the pop-up menu. Your new designed input page opens and you can run your Web application. Run on Server 10.9 Recap Congratulations! You have completed 10.0, "Enhancing the input page using Web tools". You should know understand: * The purpose of Page Designer. * How to open Page Designer. * How to add a style sheet to a Web page. * How to work with Web page properties. * How to design and add a logo to a Web page * How to add a heading 1 tag to a Web page * How to add a picture to a Web page. * How to create a logo with WebArt designer. * How to add moving text to a Web page. * How to change the text color in a Web page. 11.0 Tutorial Summary As you can see, the intent of the iSeries extensions to the Web Development Tools is to enable you to be immediately productive creating Web user interfaces on top of RPG business logic, leveraging your existing skills and potentially even existing code, and delaying the need to learn HTML, JavaScript(TM) and Java. These extensions include a palette of iSeries-unique JSP custom tags within the Web Page Designer, which offer attributes for formatting, validation and field referencing that you are accustomed to from your green screen development. These attributes include data type, length, decimals, formatting and validation. From these attributes, client-side JavaScript is generated. These palette parts defer the need to learn HTML and JavaScript. The Web tools extensions also include a Web Interaction wizard, that given the signature information for an iSeries executable or entry point, will generate not only the Java bean wrapper to call it, but also a Struts action that uses it, and optionally input and output JavaServer Pages and form beans to prompt for the input parameters and display the output parameters. A Web application that uses RPG for business logic, can be created by creating and stringing together Web interactions, where the output page from one interaction is the input page to the next interaction. When the JSPs are created first, the Web Interaction wizard allows mapping of input fields to input parameters and output fields to output parameters. This interaction wizard defers the need to learn Java, JSPs and Servlets, especially if combined with the Web Site Designer for creating page templates, preferably by someone else skilled in Web design. Note: For more information on Development Studio Client and the iSeries Web Tools, see http://ibm.com/software/adwtools/iseries. Appendix. Notices Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: Lab Director IBM Canada Ltd. Laboratory 8200 Warden Avenue Markham, Ontario Canada L6G 1C7 Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: (C) (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. (C) Copyright IBM Corp. 1992, 2004. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear. A.1 Programming interface information Programming interface information is intended to help you create application software using this program. General-use programming interfaces allow you to write application software that obtain the services of this program's tools. However, this information may also contain diagnosis, modification, and tuning information. Diagnosis, modification and tuning information is provided to help you debug your application software. Warning: Do not use this diagnosis, modification, and tuning information as a programming interface because it is subject to change. A.2 Trademarks IBM iSeries OS/400 RPG/400 VisualAge WebSphere Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. ActiveX, Microsoft, SourceSafe, Visual C++, Visual SourceSafe, Windows, Windows NT(R), Win32, Win32s and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX(R) is a registered trademark of The Open Group. Other company, product, and service names may be trademarks or service marks of others.