IBM WebSphere(R) Development Studio Client for iSeries Tutorial: Maintaining an iSeries project-based RPG or COBOL application Version 6.0 Contents 1.0 Introduction to this tutorial 1.1 Learning objectives 1.2 Prerequisite knowledge 2.0 Setting up an iSeries Project and enabling the merged view 2.1 Creating an iSeries Project 2.2 Populating the project with members 2.3 Enabling the merged view 2.4 Modifying the view 2.5 Recap 3.0 Building the iSeries Project 3.1 Selecting the build style 3.2 Submitting a build 3.2.1 Submitting a single member compile 3.2.2 Submitting a full project build 3.3 Running the PAYROLL or PAYROLLC2 program 3.4 Recap 4.0 Module checkpoint answers Appendix. Notices A.1 Programming interface information A.2 Trademarks 1.0 Introduction to this tutorial The development cycle behind iSeries Projects involves creating and populating an iSeries Project with source members. These members are then edited locally and verified for syntax errors. Next, the members are pushed to the iSeries host and a build is issued against them, depending on the Build Style associated with the project. The errors from the compiles can be retrieved and viewed locally, and the members can be modified accordingly. Finally, once all members compile error free, they can be checked into a team server for source management, if team development is required. The team server can be specified by associating the project with a Team provider. The rest of this tutorial walks you through each of these development steps, and applies them in the context of updating an existing payroll application. In this tutorial you will follow the typical iSeries(TM) application development life cycle tasks using a payroll application written in RPG or COBOL. You will work through a series of exercises that will teach you about iSeries project based application development. 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. Modules: Work on the modules in sequence. The pictures in the modules show similar tasks. Some of the names and icons may be different from the environment you will be working with when you complete the modules. 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 this tutorial, you will learn how to perform some typical iSeries native development tasks. You will walk through a development cycle using iSeries Projects where you are given the task of updating an existing payroll application and re-pushing it back to the iSeries host. The development cycle involves creating and populating an iSeries project with the existing code for the payroll application. It then involves editing and verifying the code locally, and pushing it back to the iSeries host. Finally, a build has to be submitted to the iSeries host to compile your new and improved native application. This tutorial is broken into ten modules, each with their own specific learning objectives. Each module is composed of several exercises. These exercises must be completed in order to successfully achieve the module's goals. The first module, Reviewing the 5250 payroll application, helps you learn about the 5250 payroll application before you use the new iSeries Development tools to maintain it. The second module, Starting Development Studio Client helps you learn about the workbench and workspace. You will then learn how to start Development Studio Client. The third module, Opening a perspective helps you learn about a perspective, and specifically the iSeries Projects perspective. You will then learn how to open the iSeries Projects perspective. The fourth module, Configuring a connection to an iSeries system and connecting to an iSeries, explains how to create a connection to an iSeries server. You will learn the steps to configure and create a connection. The fifth module, Setting up an iSeries Project and enabling a merged view describes how to create an iSeries project and to populate it with members. It also explains how to show remote objects or local objects or both. The sixth module, Editing source, helps you learn about some of the language features available in the Remote Systems LPEX Editor while you edit ILE RPG source or ILE COBOL source. The seventh module, Verifying source, explains how to verify ILE RPG source or ILE COBOL source in the Remote Systems LPEX Editor. You learn how to find and fix errors identified in the iSeries Error list. The eighth module, Building the iSeries Project, helps you learn how to select a build style, submit a build and run the application. The ninth module, Designing screens, helps you learn about the various aspects of the CODE Designer while modifying a display file to add a screen. The tenth module, Debugging a program, explains the Debug perspective and how to start the debugger, set breakpoints, monitor variables, run and step into a program, view the call stack in the Debug view, remove a breakpoint, add a storage monitor, and set watch breakpoints. 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. It is also useful, but not necessary, for you to have basic knowledge of the following: * ILE RPG or ILE COBOL * DDS When you are ready to begin, start with the first module. 2.0 Setting up an iSeries Project and enabling the merged view In this module, you will learn how to create an iSeries Project and import the source you have just located for the green-screen application into that project. You will also learn how to manage local and remote objects. In order to create an iSeries Project and manage local and remote objects, there are several steps you will need to learn about and follow: * Describe iSeries Projects * Create the iSeries Project * Select the build style * Populate the iSeries Project * Show only local objects * Show only remote objects * Show both local and remote objects * Recognize local and remote objects by their icons In order to accomplish these learning objectives there are several steps involved, including: * Creating an iSeries Project * Populating the iSeries Project * Enabling the merged view * Modifying the view to show local objects, remote objects or both The exercises within this module must be completed in order. Start with the first exercise when you are ready to begin. Length of time: This module will take approximately 10 minutes to complete. 2.1 Creating an iSeries Project iSeries Projects are projects that are dedicated for holding iSeries source members destined to be pushed and compiled on an iSeries machine. They follow the Workbench paradigm in that they have a special perspective, the iSeries Projects Perspective, dedicated to showing and working with these projects. When a new iSeries project is created three properties need to be associated with it. These are an iSeries Connection, an Associated Library, and a Build Style. Tip: Only iSeries projects can hold source physical files and members. Since you can create various types of projects with the Development Studio Client for iSeries, each project type is identified by a distinct icon. Specifically, iSeries projects are distinguished by blue on the top right corner of the project icon. Now that you have located the source code, you need to import it into an iSeries project for editing. You can create a new iSeries project from scratch by using the New iSeries Project Wizard. To create an iSeries project: 1. In the iSeries Project Navigator, right-click and click New > iSeries Project on the pop-up menu. creating a new iSeries Project The iSeries Project page opens. 2. In the Project name field, type MyProject. Type MyProject in the Project name field 3. Click Next. 4. Select your connection from the Connection list, for example, s400a. The property iSeries connection allows for remote access to the iSeries host machine, and handles various aspects, including user ID and password authentication to the remote host. It also provides the initial environment for builds, including the base library list. 5. In the Associated library field, type RSELABxx The associated library is a "scratch" library on the remote iSeries system that an iSeries project maps to. It is used for pushing code changes made locally to the remote host and for performing builds on that remote host. It is expected that this library is a "personal" library and the goal is that there should not be any need for any source in it to be edited directly on the host. It is meant to be a sandbox in which a single developer can perform tasks. 6. Click Next. 7. Under Active build style, select CL Program. The property build style determines how a given iSeries Project is built. It determines how source physical files and members are pushed to the remote host, and how these members are compiled there. 8. Click Finish. This will create an empty iSeries project that you have to populate. This is useful when you are creating new iSeries members from scratch and you don't have them already on a host. 2.2 Populating the project with members You have an existing green screen application that you need to import into an iSeries project. There are several ways of importing members into an iSeries project, but the quickest way is to use the Make Available Offline action. The Make Available Offline action downloads the selected files or members locally to their corresponding iSeries project. The corresponding iSeries project has the same host and the same library properties as the host name and the library of the selected source physical files or members. If such an iSeries project is not found, one will automatically be created. In your case, this action created a new iSeries Project with the name being connectionName_libraryName. If there was one or more existing iSeries projects which had the same connection and mapped to the same library as the Associated Library, then this action would have prompted you to select one of these existing projects. To populate the project with members: 1. In the iSeries Projects perspective look for the Remote Systems view. It is located under the iSeries Project Navigator. 2. In the Remote Systems View Library filter, right-click the QDDSSRC, QRPGLESRC and QCBLLESRC source physical files and click Make Available Offline on the pop-up menu. Make Available Offline A dialog opens asking you to confirm the download of files to your project. Confirm download 3. Click Yes. The files will be added to your project: Newly added files 2.3 Enabling the merged view Once the iSeries project has been created and populated with source files and members, you can display the remote objects that exist in the associated library of the project by selecting the Show Remote Objects action from the project pop-up menu. This action displays the "bleed-through" view that merges all the local resources with all the remote resources that exist in the remote library. Now you want to display the "bleed-through" view that merges all the local resources with all the remote resources that exist in the remote library. To enable the merged view: 1. Right-click your project. 2. Click Show Remote Objects on the pop-up menu. Show Remote Objects 3. Your iSeries Project Navigator will now look like this: iSeries Project navigator with Local and Remote files Notice how some members are flagged with the yellow arrow. This shows that there are objects that are local and remote. 2.4 Modifying the view Next you modify the view to filter out remote objects. To modify the view: 1. Go to the iSeries Project Navigator toolbar. 2. Click the drop down arrow. 3. Click Show > Remote Objects on the pop-up menu. Filter view This removes all objects that are only remote from the view. Filtered view 2.5 Recap Congratulations! You have completed this module. You should know understand: * The concept of an iSeries Project * How to create an iSeries Project * How to populate the iSeries Project with members * The concept of a merged view * How to enable a merged view * How to view remote objects, local objects or both Now that you have created an iSeries Project, populated it with members and enabled the merged view continue to the next module. 3.0 Building the iSeries Project So now that the code has been edited locally and verified against any syntax errors, you are ready to perform a build (or compile) on the source members under a given iSeries project. Associated with each iSeries project is a Build Style which basically determines how source members under that project will be pushed and compiled on the host. A build style is a set of actions that provide push and build operations for a given iSeries Project. In this module, you will learn how to select a build style, compile a single file or compile an entire iSeries Project. You will also learn how to update files on your local machine and on the server automatically. In order to build the iSeries Project, there are several steps you will need to learn about and follow: * Describe the build styles * Select the build style * Compile a single file * Compile an iSeries Project In order to accomplish these learning objectives, there are several steps that are involved, including: * Selecting the build style * Submitting a build * Running the program The exercises within this module must be completed in order. Start with the first exercise when you are ready to begin. Length of time: This module will take approximately 10 minutes to complete. 3.1 Selecting the build style There are three IBM-supplied build styles: *NONE This build style contributes no actions and is useful if you want to disable the menu items associated with a build style. This style will always be available. Command This build style runs a single command in batch to compile all the members of the project. The command can be configured through the build style's configuration page. This build style contributes the following three actions to the Remote Actions menu found in the iSeries Projects Navigator view: * Push Changes -- Pushes any new or changed resources found in the selected project. An item is changed if it has been updated locally since the last time it was pushed, either by Push Selected or Push Changes. The first time it is done, all resources are uploaded to the associated library. Each subsequent upload is incremental. * Push Selected -- This action uploads all selected resources and their children to their corresponding iSeries source files and members in the associated library. It creates any resources that do not exist. It will overwrite any changes that have been made on the host system only if confirmed by the user. Use this action to force the contents of the associated library to match the workspace. Submit Build Command Submits the command found in this build style configuration to the host. CL Program This build style uploads the COMPILE.CLLE and BIND.CLLE members from the source file that you designated in the build style configuration for this project. It then compiles and runs them to build this project on the host system. This build style contributes the following actions to the Remote Actions menu: * Push Changes and Push Selected -- These two actions are identical in behavior to the above build style. * Submit Build -- Submits a job to compile and run the iSeries Project on the host using the COMPILE and BIND programs from the source file you specify. Each iSeries Project can have only one active build style. This can be configured through the properties page for that project (right click on the iSeries project and select Properties). By default, when a new iSeries project is created it has the CL Program build style associated with it. This can be changed by going to Window > Preferences > iSeries Projects > iSeries Build Styles. Once submitted, a build can be monitored through the iSeries Build Status View. This view can be set to update at regular intervals and monitors all iSeries Project build jobs that you have submitted. Also compile errors can be retrieved from that view by right clicking on the submitted build and selecting the Retrieve Errors action. 3.2 Submitting a build There are two ways by which you can compile your code changes. You can do a single member compile on an individual member basis. Or you can compile the full project. Compiling the full project depends on the Build Style associated with the project. Note: Choose to do a single member compile or a full project build but not both. 3.2.1 Submitting a single member compile To do a single member compile: 1. Push the member to the host: in the iSeries Project Navigator, right-click on the member and click Remote Actions > Push Selected on the pop-up menu. 2. Right-click on the member and select Show in Remote Systems View. Show Remote Objects The Show in Remote Systems View menu option is enabled only if you have already selected to show remote objects for the iSeries Project. Show Remote Objects 3. In the Remote Systems view, right-click the selected member and select Compile to compile your member. . Compile PAYROLLC2.cblle Compile PAYROLL.rpgle This will compile your member and any errors will appear in the iSeries Error List. Make sure you refresh your view to see the generated objects. Tip: When you connect the host using a Remote System Explorer connection, the Library List is gathered from your profile at the host. You can override this and modify the library list of a specific connection. Right-click the connection in the Remote Systems view and click Properties > Subsystems > iSeries Commands. 3.2.2 Submitting a full project build You can compile the project in full. The actual compile behavior depends on the Build Style associated with the project. The default build style for iSeries Projects is the CL Program Build Style. This build style will generate a COMPILE.CLLE member in a QCLSRC file that will contain a compile entry for each source member in the iSeries project. You can verify or change the configuration of a build style. You can specify the name of the source file to hold the COMPILE.CLLE member and whether or not you want to automatically push changes and re-generate the COMPILE.CLLE member before a push. For this exercise, all you have to do is simply submit the build. To compile a project in full: 1. Right-click any object in the iSeries Project and click Remote Actions > Submit Build. SUBMIT BUILD This action, with the default configuration, will perform all of the following: a. Generate the following COMPILE.CLLE member: COMPILE.CLLE b. Display a Build Job entry in the iSeries Build Job Status View indicating that a build has been submitted. The entry will look like this: iSeries Build Job Status c. Push all project changes to the host, including the newly created COMPILE.CLLE member. d. Compile COMPILE.CLLE into a program in the QTEMP library. e. Run it against the source in the RSELABxx library. This will generate the program. You can refresh your library view and now you should see an RPG program object or a COBOL program object: PAYROLL.*pgm.rpgle 2. If there where any errors during the submitted build, after the job completes, refresh the iSeries Build Job Status View, then right-click on the entry in the iSeries Build Job Status View, and select Retrieve Errors. This will open the iSeries Error list and you will be able to double-click the error to open the corresponding member. 3.3 Running the PAYROLL or PAYROLLC2 program Communication between the iSeries and your workstation can be configured for: 1. The Remote System Explorer server job, the one that you are using currently. 2. A batch job. 3. An interactive job to test 5250 applications. You will need an interactive communication link to the iSeries server and therefore you will need a 5250 emulator to start the interactive job on the iSeries. The communication link will be established through the emulation session by using an OS/400 command to initiate the session to your workstation. To set up an interactive connection: 1. Start a 5250-emulation session. 2. Sign-on to the iSeries with a User ID and Password. Note: Instead of the Enter key, you may have to use the Ctrl key in your 5250-emulation session. 3. Type STRRSESVR NAME (s400a) RMTLOCNAME(*RESOLVE) in the command line. Start Remote System Explorer interactive connection The *RESOLVE keyword will get the IP address of your workstation and with this information the Remote System Explorer server will communicate with the Remote System Explorer daemon that runs on your workstation. You should see a screen as shown: RSE connection screen Note: This screen will stay this way. Don't wait for it to finish, this session is the interactive session for interactive commands started from the Remote Systems view. Next you will run the program that you just compiled earlier. Select the program object in the iSeries Projects Navigator, right-click to see the pop-up menu and then click Show in Remote Systems View. In the Remote Systems view, in the RSELABxx library: Run program interactive 1. Locate the PAYROLL program or PAYROLLC2 program that you created. 2. Right-click the PAYROLL program icon or PAYROLLC2 program icon in the Remote Systems view. 3. Click Run > Interactive on the pop-up menu. 4. Switch to your 5250-emulation session. You will see the Start Menu of the payroll program. Payroll Start Menu 5. Place an x beside Employee Master Maintenance. 6. Press the Enter key. 7. Type 456 for the Employee Number. 8. Type A for the Action Code to add employee 456. 9. Press the Enter key. 10. Type any information you like about the employee. 11. Press the Enter key. 12. Play in the application as much as you like. 13. Press F3 to end the program. 3.4 Recap Congratulations! You have completed this module. You should now understand: * The concept of build styles * How to select a build style * The difference between a single member build and a full project build * How to submit a build * How to run an interactive application Now that you have built your iSeries project, you can move on to designing screens. Continue to the next module. 4.0 Module checkpoint answers +---------+----------+---------+---------+---------+----------+-------+ | 2 | 3 | 4 | 6 | 7 | 9 | 10 | +---------+----------+---------+---------+---------+----------+-------+ | 1d | 1b | 1c | 1d | 1d | 1b | 1c | +---------+----------+---------+---------+---------+----------+-------+ | 2e | 2aa,bd,c | 2e | 2T | 2d | 2aa,bb,c | 2T | | | b, ee | | | | d,dc | | +---------+----------+---------+---------+---------+----------+-------+ | | | 3f | 3a | 3g | 3e | 3e | +---------+----------+---------+---------+---------+----------+-------+ | | | 4c | 4T | 4T | 4h | 4c | +---------+----------+---------+---------+---------+----------+-------+ | | | 5T | 5d | | 5T | 5c | +---------+----------+---------+---------+---------+----------+-------+ | | | 6e | 6c | | 6T | 6T | +---------+----------+---------+---------+---------+----------+-------+ | | | 7e | 7b | | 7T | 7e | +---------+----------+---------+---------+---------+----------+-------+ | | | | 8c | | 8T | 8T | +---------+----------+---------+---------+---------+----------+-------+ | | | | 9c | | 9T | 9a | +---------+----------+---------+---------+---------+----------+-------+ | | | | 10a | | | 10a | +---------+----------+---------+---------+---------+----------+-------+ | | | | 11d | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 12c | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 13F | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 14d | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 15e | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 16d | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 17d | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 18b | | | | +---------+----------+---------+---------+---------+----------+-------+ | | | | 19T | | | | +---------+----------+---------+---------+---------+----------+-------+ Appendix. Notices Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM(R) 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, Win32, Win32s and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group. Other company, product, and service names may be trademarks or service marks of others.