You are on page 1of 31

Local IBM z/OS application development with IBM Rational Developer for System z

Skill Level: Intermediate Reginaldo Barosa (rbarosa@us.ibm.com) Senior Certified IT Specialist IBM

01 Apr 2008 This tutorial will take you through the steps of using the IBM z/OS Application Development component of IBM Rational Developer for System z, Version 7.1, to work with local systems. It will familiarize you with the z/OS Application Development environment. You will be working with a sample COBOL program that accesses an IBM DB2 database and using the editing, compiling, and debugging capabilities of Rational Developer for System z. As an optional exercise, you can also experiment with the file comparison capability of Rational Developer for System z.

Section 1. Before you start


Learn what to expect from this tutorial and how to get the most out of it.

About this Series


Walk through this scenario and others online as part of the Enterprise Modernization Sandbox for System z.

About this tutorial


To complete this tutorial, you will perform these tasks:

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 1 of 31

developerWorks

ibm.com/developerWorks

1.

Prepare and load the local COBOL programs and copybooks. Create a local COBOL project, define the properties, and import the COBOL assets. Work with the local COBOL program. Use the Editor, Local history, Syntax checking, and Code Assist. Run a program that accesses a local IBM DB2 table. Work with the local debug tool. Use breakpoints, debug called programs, change variables, and so forth. (Optional) Compare files. Use IBM Rational Developer for System z to compare files and see possible differences.(we' call it simply Rational Developer hereafter, in this context only)

2.

3.

4.

Objectives
You will learn how to Work with COBOL programs without connecting to z/OS using Rational Developer for system z. Use the COBOL Editor, Use Local history, Syntax checking, and Code Assist. Run a program that accesses a local DB2 table. Work with local Debug using breakpoints, debuging called programs, change variables, etc.

System requirements
This tutorial assumes that Rational Developer for System z is already started and that you are ready to work with an empty workspace.

Local IBM z/OS application development with IBM Rational Developer for System z Page 2 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Section 2. Prepare and load the local COBOL programs and copybooks
Load the COBOL code
You will import and create a local project. As part of the import, you will load a sample COBOL program to work with for this tutorial. 1. From the z/OS Projects perspective, select File > Import. Scroll down to select Other > Project Interchange, and click Next:

Figure 1. Import dialog in the z/OS Projects view 2. Click either the down-arrow button or the Browse button, and find the C:\RDZ_POT_V7\LAB1\LAB1_COBOL.zip file. If you used the Browse button, click Open. Select LAB1_LOCAL_COBOL, and click Finish.

3.

Figure 2. Import Project Interchange Contents dialog The assets shown in Figure 3 will be added to the workspace, and a LOCAL project will be created: Figure 3. Assets added to workspace You have loaded a COBOL DB2 batch program named CUSBATCH, a COBOL subroutine named REGI0C, and two copybooks, named CUSMAP and CUSTRECD. You will use these assets in the next steps. What this COBOL code does
You will interact with the COBOL code that you through Display and Accept, and access a DB2 table (Figure 4). It has copybooks and an external call to another COBOL program. Based on the customer number that you have entered, the program will access a local DB2 table, retrieve the customer data, and display it. The values 999 or Q will stop the loop. The local DB2 table is already created and the data is loaded. Figure 4 shows the table content.

Figure 4. Content of the database table display

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 3 of 31

developerWorks

ibm.com/developerWorks

Import the project properties


Local projects and properties
Local projects are not associated with a system definition as Multiple Virtual Storage (MVS) projects are. When you first define your local project, you set values for properties, such as compiler options. Also, you can assign a property value at the level of a folder or file. The project properties can be exported to an XML file, and then other team members can quickly define other local projects by importing the values from that file. This is what you will do now. The properties in local projects are similar to job control language (JCL) statements when using COBOL compilations: link and so forth. For example, if a COBOL program has a copybook, its location must be indicated in the project properties, as well the COBOL compile options, link options, and so on. In the properties, you can also specify whether the generated code will be a DLL or *.EXE, and so forth.

You will import the local project properties to be able to do local compilations and build executables. 1. Right-click LAB1_LOCAL_COBOL and select Import Properties (Figure 5).

Figure 5. Use the drop-down menu to select Import Properties 2. Navigate to the file C:\RDZ_POT_V7\LAB1, select LAB1_properties.xml, and click Open (Figure 6).

Figure 6. The Open view 3. To verify that the properties were successfully imported, expand the cobol folder by clicking the plus (+) sign beside that folder (see Figure 7).

Figure 7. Expanded cobol folder What these build options mean


TEST: Use Test to produce object code that contains the symbol and statement information that enables the debugger to perform symbolic source-level debugging. ADATA: Use ADATA when you want the compiler to create a SYSADATA file, which contains records of additional compilation information. EXIT: This allows the compiler to accept user-supplied modules in

Local IBM z/OS application development with IBM Rational Developer for System z Page 4 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

place of SYSIN, SYSLIB (or copy library), and SYSPRINT: When ADEXIT is specified, the compiler loads the exit module during initialization. The exit module is called for each record written to the SYSADATA data set. LIB: If your program uses COPY, BASIS, or REPLACE statements, the LIB compiler option must be in effect. SQL: Use the SQL compiler option to enable the DB2 coprocessor capability and to specify DB2 sub-options. The DB2 sub-option string that you provide on the SQL compiler option is made available to the DB2 coprocessor. Only the DB2 coprocessor views the contents of the string. DATABASE: In this example, you will use the Database option that will specify the database named EOTZOS. This database could be located in the z/OS, and you would specify this using the connection to z/OS. SYSLIB: Specify paths to directories to be used in searching for COBOL copybooks when you do not specify an explicit library name n the COPY statement.

4.

Right-click the CUSBATCH.cbl file, and select Properties (Figure 8).

Figure 8. Use the drop-down menu to select Properties 5. Click Local COBOL Build Options and verify that it has the options that Figure 9 shows.

Figure 9. Properties for cobol view 6. Click Local Link Options. Notice that the option for Local Link is EXE. This means that when a COBOL program from this project is built, a name.exe file is generated rather than a name.dll file. Also notice that the options /de and db2api.lib were specified; /de means that the program will include debugging information and a db2api.lib file is a DB2 library.

Figure 10. Properties view What you have done so far


You created a Local MVS project, loaded a COBOL batch program named CUSBATCH, a COBOL subroutine named REGI0C, and two copybooks, named CUSMAP and CUSTRECD. Because this program accesses the local DB2, it was necessary to specify properties that specify where the DB2 table is located, the name of the database, and so forth. To make this definition easy,

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 5 of 31

developerWorks

ibm.com/developerWorks

you imported some predefined project properties so that, when you will compile the program, the compiler will find the DB2 table and the required COPBOOKS. Also notice that the properties will inform the linker that you will use the debugger and create an *.EXE file rather than a DLL file. At this point, you would be ready to compile, link, and debug the code, but first you will use Rational Developer for System z editing capabilities.

7.

Click Cancel, because you do not need to make any changes to the properties.

Section 3. Work with the local COBOL program


In this section, you will work with the local COBOL program that you have loaded. You will use the Rational Developer LPEX Editor, Local history, Syntax checking, and Code Assist, and then you will run the program that accesses a local DB2 table.

Editing a COBOL source file


1. Using the z/OS Projects perspective, expand the LAB1_LOCAL_COBOL project and the cobol folder. Double-click CUSBATCH.cbl. You should see something similar to Figure 11.

Figure 11. CUSBATCH.cbl expanded Note: Ignore the error (indicated by the red X icon ) if it appears. When you imported the COBOL program, the compiler checked the syntax and flagged many errors. This was before fixing the properties that point to the copybooks. 2. On the lower left, click the Outline tab to change focus to the Outline view (Figure 12).

Figure 12. Outline tab The Outline view displays a summary of a structured file that is currently open in the editor area, showing structural elements. The contents of the outline view are

Local IBM z/OS application development with IBM Rational Developer for System z Page 6 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

editor-specific. 3. Expand the plus signs and observe the COBOL structure (Figure 13).

Figure 13. Click the plus signs to expand the view Examples of icons that can help you save time Sort ascending, Show only divisions, Hide nested programs, Show DATA DIVISION only, and others 4. Click SEEYA (under PROCEDURE DIVISION). The editor will show th the SEEYA code (Figure 14).

Figure 14. SEEYA code

Adding bookmarks
Creating a bookmark within a file The Workbench allows you to create bookmarks in files that you edit so that you can quickly reopen those files from the Bookmarks view. You will create a bookmark in the SEEYA paragraph and, later, you will return to this point. You could create tasks in a similar way. 1. Right-click in the gray border at the left of the editor area (where the SEEYA paragraph is coded), and select Add Bookmark from the drop-down menu (Figure 15). Bookmark this paragraph for later changes.

Figure 15. Editor view 2. Accept 030-SEEYA as the bookmark name (Figure 16) by clicking OK.

Figure 16. Add Bookmark view with name filled in Notice that an icon for the bookmark now appears in the left border of the editor area (Figure 17). A line is also added to the Bookmarks view (you will see that later). Figure 17. Blue bookmark icon in border

Changing the profile editor


The default profile used by the editor is LPEX, which defines the key behavior. The editor can emulate most of the key behavior of other editors, such as ISPF and XEDIT. Most developers are used to using ISPF, so you can set the editor profile to
Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 7 of 31

developerWorks

ibm.com/developerWorks

ISPF, if you prefer. 1. To open the Preferences dialog, select Window > Preferences (Figure 18).

Figure 18. Open Preferences from the drop-down menu 2. In the left panel, click LPEX Editor, and then from the Editor Profile list (Figure 19), click ispf.

Figure 19. Preferences options 3. Click OK to close the Preferences dialog. Notice that the editor is now similar to the ISPF on z/OS (Figure 20).

Figure 21 shows some of the editor commands. Figure 20. New editor view ISPF profile editor commands
This editor enables you to enter commands in the prefix area (such as d to delete, m to move, r to duplicate, and so on) similar to the TSO/ISPF editor. You can also use key combinations for commands, for example: Ctrl + L for Locate, Ctrl + F for Find, Alt+Enter for newLine, and so forth (see Figure 21). Try some of the ISPF editor commands. To see all ISPF editor commands, select Help, and then Help contents and type: ispf or ispf base profile in the Search window. Caution! Do not save any changes that you make.

Figure 21. Partial display of ISPF keys that you can use the ISPF editor

Creating tabs for the editor


Because you are using COBOL, it is a good idea to create tabs for easy navigation in the editor. 1. 2. Select Windows > Preferences. Expand LPEX Editor, click Tabs, and enter 1, 7, and 8 as tab stops. Also change the tab increment to 4 (rather than 8). Each time the Tab key is

Local IBM z/OS application development with IBM Rational Developer for System z Page 8 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

pressed, the cursor will move to positions 1, 7, and 8. The increment 4 will also make stops at 12, 16, 20, 24, and so on. See Figure 22. 3. Click OK.

Figure 22. Setting Preferences in the editor 4. Close the file being edited by clicking the X in the title tab:

Working with bookmarks In some steps, before you have added a bookmark, the bookmark stays with the program, and you can even close the workspace to find it later. There is a view named Bookmarks that shows all of bookmarks that you have for a specific workspace. 1. To open this view (Figure 23) to find the bookmarks, select this sequence: Window > Show View > Bookmarks.

Figure 23. Find bookmarks set previously You can reopen the file for editing at any time by double-clicking the bookmark under the Bookmarks tab. 2. To see how this works, double-click 030-SEEYA to reopen the editor (Figure 24). The editor will open and move to the position that you have bookmarked. This is nice when you need to stop work and return later.

Figure 24. Bookmarks view 3. Press Enter to move the cursor to the line 103, and then use the Tab key to move the cursor and change the word from DISPLAY to DSPLAY (just delete the letter I) and press Enter.

Notice that, because you are using a smart editor and DSPLAY is not a valid COBOL statement, the color that was blue is changed to black. Using Shift + Tab moves the cursor back. Notice that the asterisk (*) at the left of the file name in the view tab indicates that the file has been changed. The asterisk will disappear when the file has been saved. Figure 25. Intentional error: DSPLAY

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 9 of 31

developerWorks

ibm.com/developerWorks

4. 5.

Press Ctrl + S to save the change. However, this is not flagged as an error, because the program must be compiled to find the errors. Resize the editor as you want during these exercises. Sometimes, you will need more space to see the whole program. The easiest way is just to double-click in the CUSBATCH.cbl title tab area (Figure 26).

Figure 26. CUSBATCH.cbl title tab 6. When you have finished, double-click again, and the window will return to its previous size. However, it is always better to work with the editor with a larger window size. Keep this editor with more space, because you will make changes in the COBOL code. Scroll down to line 120, type d (lowercase d, for delete) in the left column (gray area), and press Enter to delete the line, but do not save the file.

7.

Figure 27. Deleting a line 8. Scroll down to move the cursor to line 142, and press Ctrl + Enter to insert a new line. Use he Tab key and type a new paragraph name for column 8, such as ADDED in the example in Figure 28:

Figure 28. Adding a line 9. Now press Ctrl + S to save the file.

10. Because you probably resized or closed some views, you might want to return to the default view. Select Window > Reset Perspective, as shown in Figure 29, and then click OK. Figure 29. Reset Perspective default views Notice that the Bookmarks view also goes away, because it is not part of the default z/OS Projects perspective.

Using the Local History feature


About the Local History feature
The local history of a file is maintained when you create or modify a file. Each time that you edit and save a file, a copy of it is saved. This enables you to compare your current file state to a previous state or to replace the file with a previous state. Each state in the local history is identified by the date and time that the file was saved.

Local IBM z/OS application development with IBM Rational Developer for System z Page 10 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Local history is a handy feature. Imagine situations where you are editing a file in the z/OS and, by mistake, you deleted some lines and saved those changes. There is no way to recover, except to use a backup copy if you have one. By selecting Window > Preferences > General > Workspace > Local History, you can change the defaults. For example, if you type 300 in Days as the number of days to keep file, then the history will show saved states from the last 300 days.

Note: Neither projects nor folders have local histories; only files do. To replace a current version of Local History with the previous one, you can use this feature. For example: to recover the line that you deleted before: 1. Using the z/OS Projects view, right-click CUSBATCH.cbl and select Replace with > Local History (Figure 30).

Figure 30. Replace with Local History The Replace from Local History window opens. Notice the two small change bars shown to the right of the scrollbar on the right side. These mark where changes were made. (You will have different dates and time and less history than Figure 31 shows). 2. Click the blank bar (the second) to jump to the other change.

Figure 31. Change after clicking the second change bar Can you see the differences? The view on the left shows the current version in the editor (with the ELSE deleted and ADDED paragraph name), and the view on the right is the previous version. 3. Click the Replace button to replace the copy being edited and return to the previous version.

Figure 32. Replace the file with the previous one The previous version is restored (Figure 33). Figure 33. Previous version restored Note: Ignore the error . It will go away when you compile the program. 4. Close the editor by clicking the X beside the file name:

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 11 of 31

developerWorks

ibm.com/developerWorks

Check the COBOL source file syntax


Local COBOL or PL/1 syntax checking
When you develop COBOL or PL/I code, you can do a local or remote syntax check on a particular source file. A local syntax check uses a workstation-based compiler. You use a local syntax check to save processing time and to avoid the expense (if any) that is associated with added z/OS CPU cycles. To perform a local syntax check, the source file that you want to check, along with all of its dependencies, must be in a z/OS project.

' 1. Using the z/OS Projects view (Figure 34), right-click CUSBATCH.cbl and select Local Syntax Check from drop-down menu.

Figure 34. Select Local Syntax Check from the menu 2. Click the Remote Error List tab to see the list of compile warnings and errors (Figure 35).

Figure 35. List of compile warnings and errors Fixing syntax errors Because there are COBOL syntax errors, you need to fix them. 1. Double-click the red error icon , and it will bring you to the editor where the statement was flagged. You will see something similar to Figure 36.

Figure 36. Editor shows code with error 2. 3. Use the Tab key to move the cursor and change back from DSPLAY to DISPLAY. Save your changes (Ctrl + S) and perform another Local Syntax Check to ensure that the compilation is now clean (Figure 37).

Figure 37. Repeat the Local Syntax Check 4. The Return Code is 0 (zero). Click Remote Error List. You should see no errors in the Remote Error List view after re-running the Local Syntax Check.

Local IBM z/OS application development with IBM Rational Developer for System z Page 12 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Notice that the warnings are gone also, because they resulted from the error that you have fixed.

Using the COBOL Content Assist features


About the Content Assist features
COBOL and PL/I content assistance (Content Assist for short) is available for syntax elements of each language. For example, built-in functions and subroutine calls for the PL/I language are available as completion proposals, with the correct syntax. Where possible, user-defined labels and variables are included in the list of suggested options. You can customize available content assistance options by editing the *.sdf files located in the installation directory.

You are now going to add COBOL statements after the PROCEDURE DIVISION. 1. 2. Using the Outline view, click PROCEDURE DIVISION to position the cursor on that line. Then type the command i3 (insert 3) in the gray area for that line and press Enter. This will add three blank lines. (Alternative: You could use Ctrl + ENTER 3 times to add 3 empty lines.)

Figure 38. Adding 3 empty lines 3. Resize the editor so that you can see more: Double-click in the blue CUSBATCH.cbl title tab.

Figure 39. Select the title tab again 4. 5. 6. 7. Double-click the tab again to return the window to its previous size (but it is best to use the larger view of when editing). On Line 77, use the Tab key to move the cursor to Column 12 and press Ctrl + Space. You will see all possible COBOL statements. Type the letter D, and it will show all statements that start with D. Double-click DISPLAY. (See Figure 40.)

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 13 of 31

developerWorks

ibm.com/developerWorks

Figure 40. Double-click DISPLAY The entire line can be coded by using the Code Assist feature: 8. 9. Move the cursor after the DISPLAY command and type Enter name or Q to quit. Enter a space, press Ctrl + Space again, type a U (notice the list is shortened to anything beginning with the letter U), and then double-click UPON. (See Figure 41.)

Figure 41. Double-click the word UPON 10. Start typing console with just the first two letters, co, use Ctrl + Space again, and then double-click CONSOLE (see Figure 42). Figure 42. CONSOLE selected When Content Assist is especially useful
Using Ctrl + Space is very helpful when you need to use data names. For example, when using the ACCEPT command to move the data entered in the console to a data name, you will have a list of possible data names to receive that value. In a small program, this feature is not that important. But in a huge program, with lots of data names, this is can be very useful.

11. Click Enter to move to Line 78. In Column 12, type the ACCEPT statement plus a space, and then use Ctrl + Space to add the variable, Input-name (see Figure 43). Figure 43. Adding the Input-name variable The result will look like Figure 44. Figure 44. After the Input-name variable has been added 12. Click Enter to move to Line 79. In Column 12, type IF, press Ctrl + Space, and select IF - END-IF (the second on the list), as Figure 45 shows. Figure 45. Typing IF triggers two If statements to choose from 13. On Line 79, type this code (notice that you can use Ctrl + Space to help with the data name): IF Input-name = 'Q' STOP RUN

Local IBM z/OS application development with IBM Rational Developer for System z Page 14 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Figure 46. Code added on Line 79 Notice that, because the LPEX COBOL editor is a smart editor, some mistakes appear at coding time. 14. On Line 77, eliminate the second quotation mark (") from the DISPLAY statement, and then either press Enter or move the cursor to another line. You will get the error message shown in Figure 47. Figure 47. Error message: CBL005 Closing delimiter for literal not found 15. Fix the error, and save the changes by using Ctrl + S. Notice that the asterisk * on the left of the title tab disappears after it is saved: 16. Make the editor smaller by double-clicking on the title tab to resize it. 17. Right-click CUSBATCH.cbl, and select Local Syntax Check to check the syntax again (Figure 48). Figure 48. Run the Local Syntax Check again 18. Click in the Remote Error List view. There should be no errors listed in that view. If you have errors, correct them and check the syntax again. Figure 49. Remote Error List view Note: If you have errors but don't want to lose time fixing them, just load the code with the changes above from the Solution project folder for this tutorial ( C:\RDZ_POT_V7\LAB1\solution). Simply select File > Import > File system > Next, and select this file: CUSBATCH.cbl

Using the Help feature


Another nice feature when coding the program is the built-in Help capability: 1. Move the cursor to the DISPLAY statement on Line 77 and press F1. The Help screen will open, showing the selected statement. You can use this feature for any statement.

Figure 50. DISPLAY statement, Line 77 After a few moments (it can take a while the first time), the Help window will open and you will have what Figure 51 shows.

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 15 of 31

developerWorks

ibm.com/developerWorks

Figure 51. Help results 2. Click DISPLAY statement to get more information.

Figure 52. DISPLAY statement description Context-sensitive Help


If you are working through a task and encounter part of the interface that you do not understand, use the Help capabilities. Bring the focus to the interface widget in question by clicking it or using the Tab key, and then just press F1. You will get information about the interface and, if appropriate, links to more information.

3.

Close this Help window.

Figure 53. Click the X in the upper-right corner to close the window What you have done so far
You worked with some Rational Developer for System z editing capabilities, and now you have a COBOL program that has no syntax errors. You are ready to run this program by working with Display and Accept. You will also read some DB2 data.

Creating an executable COBOL program


Now that you have successfully checked the syntax of your COBOL program, you can run it locally. But before creating the executable program, delete the existing executable code so you will be sure that the executable code will be created again. 1. Right-click on the BuildOutput folder, and select Delete.

Figure 54. Delete the existing BuildOutput folder Note: The reason that you delete the BuildOutput folder for this tutorial is just to show you that it will be recreated. This is not really necessary. 2. When the Delete Confirmation dialog appears, click Delete.

To build the program and create an executable:

Local IBM z/OS application development with IBM Rational Developer for System z Page 16 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

3.

Using the z/OS Projects view, expand LAB1_LOCAL_COBOL, right-click on CUSBATCH.cbl, and select Nominate as Entry Point.

Tip: If you do not do that and you have multiple programs in the same project, one DLL will also be generated with the project name. Notice that Figure 55 does not show all of the actions that you can apply. Nominate as Entry Point is almost the last action. Figure 55. Partial view action options After the program has been nominated as the entry point, a red checkmark will appear in the icon for the program: 4. To build the program, right-click the LAB1_LOCAL_COBOL project, and select Rebuild Project (Figure 56). This action will invoke the COBOL Compiler and the linker, create the executables, and create the BuildOutput folder again.

Figure 56. z/OS Projects view options 5. Expand the BuildOutput folder (Figure 57).

Figure 57. Build Output folder, expanded Notice that CUSBATCH.exe was created; this is the executable that you will run soon. Also notice that REGI0C.OBJ has been created. This is the called COBOL program, compiled, that was included in the linker when the executable was created. Therefore, you have actually executed two COBOL compilations. One is for CUSTBATCH and the other is for REGI0C. However, you will check only one of these in the next step.

Check the local COBOL compilation and link edit


Before you run this program, it is a good procedure to verify that there are no errors or warnings. The COBOL compiler and the linker stores the output at the BuildOutput folder. To see the main COBOL program compile listing, just double-click on CUSBATCH.lst. (See Figure 58.) Figure 58. COBOL program compiler listing Notice that the compiler TEST option was used. This will enable you to use the
Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 17 of 31

developerWorks

ibm.com/developerWorks

DEBUG option later. Figure 59. Editor view showing TEST 1. Go to the end of the listing, and you see that there are no compilation errors. You can use the Ctrl + End key combination to go to the end.

Figure 60. End of the code listing 2. Close the CUSBATCH.lst editor.

You can also review the generated REGI0C.lst completion code. This is the cobol subroutine called by the CUSBATCH pro gram. The return code also must be zero. 3. Review the REGI0C.lst now by double-clicking to edit it and clicking CTRL + End.

Figure 61. REGI0C.lst expanded You can also review the generated TPF Toolkit Console for the link edit completion code. This file contains all of the compilation results. 4. Review the TPF Toolkit Console and scroll up and down until the end. The return code must be 0.

Figure 62. TPF Toolkit Console 5. Close all opened files. You can use CTRL + Shift + F4.

Creating a launch configuration and running the COBOL program


LaunchConfiguration is used to describe how a program should be launched. A launch configuration keeps a set of named attributes that can be used to store data specific for a particular kind of launcher. You interact with a launch configuration dialog to set up the parameters for different types of launches. Because you might want to run this program many times, it's a good idea to create a launch configuration. This makes running and debugging a specific program easier. To create a launch configuration that will load the compiled COBOL program, follow these steps:

Local IBM z/OS application development with IBM Rational Developer for System z Page 18 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

1.

Right-click on CUSBATCH.exe and select Run As > Run (not Run on Server).

Figure 63. Select Run As, then Run 2. Double-click Compiled Application. This will cause the launch configuration entry fields to display on the right-hand side of the dialog box (Figure 64).

Figure 64. Compiled Application and the Main tab 3. 4. In the Name field, enter a name, such as RunCUSBATCH. Use the second Browse button next to Program name to locate CUSBATCH.exe under the BuildOutput folder. Click Open to select it, and then click Apply.

Notice that your COBOL executable should be in this location: C:\Workspaces\RDZv7\LAB1_LOCAL_COBOL\BuildOutput\CUSBATCH.exe Figure 65. Run view and Main tab 5. 6. Select Run. The execution begins, and you will see the dialog shown in Figure 66. Type your first name and press Enter. See one example below:

Figure 66. "Reginaldo" typed as first name 7. Type 006 as the customer number and press Enter.

Figure 67. 006 added as customer number The results should be something like the screen shown in Figure 68. Figure 68. Data entered 8. Type 999 to stop the execution.

The console window will close, and you will be back to Rational Developer for System z. What you have done so far
You created an executable program (*.exe) with two COBOL programs and ran it.

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 19 of 31

developerWorks

ibm.com/developerWorks

The main program called a COBOL subprogram that displayed the name that you typed with a welcome phrase. After returning from the subroutine, the main program prompted for a customer number and accessed the DB2 data that was also displayed. When you typed 999 (or Q) the execution ended.

In the next section, you will debug these programs by using the local debug tool.

Section 4. Debug your local COBOL program


In this section, you will use the local debug tool. You will create breakpoints, debug the called program, change variables, and so forth.

Launch the debug tool


1. Because you have already created the launch configuration, just right-click on CUSBATCH.exe and select Debug As > Debug (Figure 69).

Figure 69. Selections for the debugging tool 2. When the Debug window opens, select RunCUSBATCH and then click Debug.

Figure 70. Debug button to start the process 3. The dialog shown in Figure 71 will ask if you want to switch to the Debugger perspective. Click Yes.

Figure 71. Confirm Perspective Switch dialog 4. The Debugger perspective is opened and the debugging process starts. Notice that Rational Developer for System z opened a new perspective named Debug (Figure 72).

Local IBM z/OS application development with IBM Rational Developer for System z Page 20 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Figure 72. Debug view 5. Using the Debug view, either click the Step Over icon or click F6 twice.

The COBOL execution starts, and it should stop just before the ACCEPT statement (Figure 73). Figure 73. Stopped at ACCEPT Input-name, Line 78

Add breakpoints
About breakpoints
Breakpoints are temporary markers that you place in your executable program to tell the debugger to stop your program at a given point. When a breakpoint is encountered, execution suspends at the breakpoint before the statement is executed, at which point you can see the stack for the thread and check the contents of variables, registers, and storage or memory. You can then step over (execute) the statement and see what effect it has on the argument. Depending on the debug engine that the debugger user interface is connected to, you can set one or more of the following types of breakpoints when you are debugging a compiled language application: Line breakpoints Function breakpoints or Entry breakpoints Address breakpoints Watch breakpoints Load breakpoints Statement breakpoints

Add a Line breakpoint 1. Add a breakpoint on the Line 81: DISPLAY "Program CUSTBATCH starting..." statement. Just move the mouse pointer into the left gray area on Line 81 and double-click (see Figure 74). A small, circular icon with a checkmark then indicates the location of the breakpoint.

Figure 74. Adding a line breakpoint 2. Scroll down and add another breakpoint (double-click) in Line 98, just before the subroutine CALL. Again, a small blue circle with a checkmark

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 21 of 31

developerWorks

ibm.com/developerWorks

marks the breakpoint. Figure 75. Pointer to break point icon A breakpoint causes the execution of a thread to suspend at the location where the breakpoint is set. Now, resume the execution of the program until the breakpoint is found: 3. 4. Click the Resume icon or press F8. The commands and icons are now disabled, because you need to go to the DOS window to type an answer. (The DOS window is hidden -- see the bottom of the display.) Restore the minimized windows, and look at the base of your screen. Click C:\Workspaces to restore the workspace. Type your first name (Figure 76), press Enter, and minimize (do not close) the DOS window to continue with the debug.

5. 6.

Figure 76. "Reginaldo" typed as first name 7. Return to the Debug view, where you will notice that the execution stops at Line 81 (Figure 77).

Figure 77. Process stops at Line 81 8. Scroll back so that you can see the PROCEDURE DIVISION statement (Figure 78).

Figure 78. Use the scroll bar on the right to go back to Line 77, PROCEDURE DIVISION statement 9. To evaluate variable contents, such as the Input-Name variable, just move the cursor to the data name and wait a few seconds for the content to appear (see Figure 79).

Notice that a variable's value is also shown in the Variables view (Figure 80), Figure 79. "Reginaldo" as first name now shows as the Input-Name variable 10. Click the Variables tab, find and expand PROGRAM-WORK-FIELDS, and change the contents of INPUT-NAME from your name to something else (this example uses Mr. Magoo). Just click the Value column of INPUT-NAME and change it as shown in Figure 80, and then press

Local IBM z/OS application development with IBM Rational Developer for System z Page 22 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

. Figure 80. Variables view 11. Click the Breakpoints tab (Figure 81) to see all breakpoints assigned to this program: Figure 81. Breakpoints tab Add a Watch breakpoint Watch breakpoints
A watch breakpoint is a type of breakpoint that is triggered whenever execution changes data at a specific address. A watch breakpoint halts program execution even if the new value being written is the same as the old value of the field. You can use the Frequency controls to tell the debugger when to stop on a breakpoint and when to skip it. The debugger keeps track of how many times each breakpoint is encountered. The fields in this section tell the debugger on which encounter of a breakpoint the debugger will first stop, how often it will stop, and on which encounter the debugger will no longer stop. You can also use Expression. The execution of the program stops at the breakpoint only if the condition specified In one specific variable test is True.

You will now add a Watch breakpoint. 1. Right-click in the Breakpoint view, and select Add Breakpoint > Watch.

Figure 82. Adding a Watch breakpoint 2. 3. Type BRANCHFLAG as the Address, and select 1 as the Number of bytes, because you want to stop at this field when it is modified. (See Figure 83.) Then click Next and Finish.

Figure 83. Add a Watch breakpoint, required information 4. Click the Resume icon or press F8.

You will get a message that tells you that storage was changed (Figure 84). This is because the MOVE 2 to BRANCHFLAG is executed, and this field has changed. Click OK.

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 23 of 31

developerWorks

ibm.com/developerWorks

Figure 84. Debug Engine Message The debugging will be stopped at Line 84 (Figure 85). Notice that the execution stopped immediately after the BRANCHFLAG field changed. Figure 85. Debug process stopped at Line 84 5. Click the Resume icon again or press F8. The execution will stop at the second breakpoint, on Line 98, where it was about to execute IF BRANCHFLAG > 1 (Figure 86), before the CALL command. Use the right scroll bar so that you can see what would be the next statement would be.

6.

Figure 86. Halted again at Line 98 7. Click the Step Into icon (or press F5 twice) so that you can debug the called program subroutine, REGI0C (Figure 87).

Figure 87. Use the Step Into icon or press F5 twice at Line 2 8. Keep pressing F6 (or the Step Over icon ) to see the logic. Remember that simply moving the mouse pointer to the variables allows you to see the variable contents (Figure 88).

Figure 88. Use the Step Over icon or F6 to see the contents 9. Keep pressing F6 or use the Step Over icon until the commands are disabled, because the window is displayed and the ACCEPT is waiting in the console (Statement: ACCEPT CUSTNOI FROM CONSOLE).

Tip: If you get some Assemble-like code during the debugging, you will get the normal COBOL code again if you click the Use Step Filter icon: 10. Bring back the window again (from the bottom of the display), type 006 as Customer number, press Enter, and minimize the console. 11. Keep pressing F6 and follow the DB2 database access. You can use the Variables view and check the SQLCODE, as Figure 89 shows on Line 209. Figure 89. Variables view 12. Press F6 until the ACCEPT command is in control again.

Local IBM z/OS application development with IBM Rational Developer for System z Page 24 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

13. Now, so that you can see the consequences, type an invalid customer number, such as 000, and then press Enter. 14. Minimize the DOS windows. Back in the debugger view, you will be stopped at the statement on Line 116 (Figure 90). Figure 90. Line 116 in the debugger view Jumping over sections of a program
You can jump to the position of the cursor or jump to a location that you have selected on the editor ruler. This will skip over sections of code, to avoid executing certain statements, or move to a position where certain statements can be executed again. Jumping moves the instruction pointer to the new jump-to location and does not execute any of the code in between. You also can run to a location, in that running to a location executes all statements between the current location and the run-to location.

15. Move your cursor to Line 112, right-click, and select Jump To Location. Figure 91. Select Jump to Location This will move the execution back to Line 112 (Figure 92). Figure 92. DISPLAY command, Line 112 16. Press F6 until the #ACCEPT statement is in control again. But now, type another valid customer number, such as 007, and press Enter. 17. Minimize the DOS windows, and go back to the debugger view, where you will be stopped in the statement on Line 116 (Figure 93). Figure 93. DISPLAY command, Line 116 Disable the breakpoints (you can re-enable them later): 18. Go to the Breakpoints view, select all breakpoints (hold down the Shift or Ctrl keys for multiple items), right-click, and select Disable from the drop-down menu. Figure 94. List of breakpoints in the Breakpoints view 19. Click the Resume icon or press F8.
Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 25 of 31

developerWorks

ibm.com/developerWorks

The commands are now disabled, because you need to go to the DOS window to type an answer. (The DOS window is hidden. See the bottom of the screen.) 20. Restore the minimized window by clicking the C:\Workspace button: <<>>. 21. Type 999 as the Customer number, press Enter to end the debugging, and click OK to dismiss this dialog. Figure 95. Debug Engine Message Animated Debug feature
This is a feature introduced in Version 7.1 that you can use for either local or remote debugging.

22. Restart the debug process by using the Debug icon, which looks like a bug: (also see Figure 96). Figure 96. Debug icon in the Debug view 23. Click the Use Step Filer icon to avoid the assembler debugging. Figure 97. Use Step Filter icon Tip: You can get the same debugging capability for batch, IBM CICS, IMS, or DB2 programs (all running on z/OS) by installing the interactive mainframe debugger on those platforms. 24. Click the Animated Step Into icon: (also see Figure 98). You will need to go to the Microsoft Windows black screen to answer the COBOL display statements. Ways to control Animated Step Into actions
When you issue this action, the debugger issues a Step Into action repeatedly. You can control the delay between each step by selecting the Animated Step Into icon down-arrow. You can set the current Step Into pace (or current Step Into delay) and the maximum pace (or maximum Step Into delay) of the Animated Step Into action. In addition, you can set the amount of time by which the pace increases or decreases when you select the Speed Up or Slow Down Animated Step Into actions in the Debug view. These are the default values of the fields in the Preference page:

Local IBM z/OS application development with IBM Rational Developer for System z Page 26 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Current pace (ms) field: 2 seconds or 2000 milliseconds Speed up/Slow down by (ms) field: 200 milliseconds Maximum pace (ms) field: 5 seconds or 5000 milliseconds.

Figure 98. Animated Step Into icon in the Debug view 25. Type 999 when you are finished, click OK, and then close the debug perspective by clicking Close from the drop-down menu, upper-right. Figure 99. Close the Debug view 26. If you have learned enough for now, close Rational Developer for System z. You have completed this tutorial. If you have extra time, you can do a bit more by completing the optional sections that follow.

Section 5. (Optional) How to compare two versions of the same file


There are situations where you have two files (COBOL, JCL, or others) that you want to compare. Here is an example of how you can do that quickly and easily: 1. Using the z/OS Projects view, make a copy of the CUSBATCH.cbl file, as shown Figure 100 shows: right-click and select Copy.

Figure 100. Make a copy of the CUSBATCH.cbl file 2. Right-click on the cobol folder, and select Paste (Figure 101).

Figure 101. Paste the copied file into the cobol folder 3. Because this file name already exists, there will be a conflict or "collision." Select Rename, change the name to NEWPROG.cbl, and click OK (Figure 102).

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 27 of 31

developerWorks

ibm.com/developerWorks

Figure 102. Duplicate Name Collision dialog The updated cobol directory tree view should appear (Figure 103). Figure 103. NEWPROG.cbl now shows in the cobol directory view Now you will make changes to the NEWPROG.cbl file. 4. To edit the file, double-click NEWPROG.cbl, and use I (lowercase letter I, for insert) to insert this comment line below Line 3: * This line has been added by XXXXXX

Figure 104. Comment line added 5. Add this new statement below PROCEDURE DIVISION: Display "RDz is helpful"

Figure 105. Statement added 6. Save the edited file (Ctrl + S) and close the editor, or just use CTRL + F4 and reply YES.

Now compare the two programs: 7. Select CUSBATCH.cbl and NEWPROG.cbl (Ctrl + click), right-click, and select Compare With > Each Other (see Figure 106).

Figure 106. Compare the two files You will see the contents of the two programs side-by-side, as Figure 107 shows. Figure 107. Side-by-side comparison in Text Compare view 8. Use the scroll bar at the right to see the next difference (shown in Figure 108).

Figure 108. Same view, different position Tip: You can use this feature with either local assets or assets that are located on z/OS. You can merge the files by using the yellow directional (arrow) icons at the top to choose which file you want to merge into which direction: 9. Click the first icon, which means Copy All from Left to Right (Figure 109).

Local IBM z/OS application development with IBM Rational Developer for System z Page 28 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Figure 109. Right-pointing arrow selected for merge 10. Use Ctrl + Shift + F4 to close all opened files, and click Yes to save the changes. 11. After merging the files, do the comparison again (Figure 110). Figure 110. Select both files, then Compare with, and Each other 12. You will get the message that Figure 111 shows, because there are no differences after the merge. Figure 111. Compare message Note: The program that you compare here, NEWPROG.cbl, can also be loaded from the Solution project folder for this tutorial: C:\RDZ_POT_V7\LAB1\solution\ When you are finished, close Rational Developer for System z.

Section 6. (Optional) How to import this tutorial project into your workspace
If you could not complete this tutorial (lab), or if you missed one step or typed an incorrect name, you will have problems. In that case, you can load the solution to your workspace: 1. In any perspective, import the Solution project by selecting File > Import > Other > Project Interchange and use the solution located here: C:\RDZ_POT_V7\LAB1\solution\lab1_solution.zip.

You will also need to import the project properties, because they do not remain at the Project Interchange. 2. 3. Right-click tutorial1 COBOL Sample > Import Properties > C:\RDZ_POT_V7\LAB1, and select LAB1_properties.xml. Next, right-click the CUSBATCH.cbl file, and select Nominate as Entry

Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 29 of 31

developerWorks

ibm.com/developerWorks

Point. Also, there is the Solution workspace (C:\Workspaces\RDZv7SOLUTION) in your VMWARE image. To start the workspace with the solution: 4. 5. Open the Solutions RDz POT folder: Double-click the RDz7 solutions icon:

Local IBM z/OS application development with IBM Rational Developer for System z Page 30 of 31 Copyright IBM Corporation 1994, 2008. All rights reserved.

ibm.com/developerWorks

developerWorks

Resources
Learn Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products. Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge. Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development. Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events. Browse the technology bookstore for books on these and other technical topics. Get products and technologies Download trial versions of IBM Rational software. Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2, Lotus, Tivoli, and WebSphere. Discuss Participate in the discussion forum for this content. Check out developerWorks blogs and get involved in the developerWorks community.

About the author


Reginaldo Barosa Reginaldo W. Barosa is an IBM Certified Application Development Specialist. He provides sales support, helping customers with enterprise transformation solutions and development tools, such as WebSphere Developer for System z. Before joining IBM US, Reginaldo worked for 27 years in IBM Brazil. He has co-authored IBM Redbooks and has written books, as well as other articles for IBM developerWorks. He holds a degree in Electrical Engineering from Instituto Mau de Tecnologia, Sao Paulo, Brazil.
Local IBM z/OS application development with IBM Rational Developer for System z Copyright IBM Corporation 1994, 2008. All rights reserved.

Page 31 of 31