ibm enterprise modernization for system z:

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


Skill Level: Intermediate Reginaldo Barosa Executive IT Specialist – IBM Boston

April, 2010

© 2010 IBM Corporation 1


Abstract 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.6, 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. Before you start Learn what to expect from this tutorial and how to get the most out of it. Be sure that you have started the System z Sandbox and the IBM® Rational® Developer for System z is running under the Windows in the system z Sandbox.

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:

1. Prepare and load the local COBOL programs and copybooks. Create a local COBOL project, define the properties, and import the COBOL assets.

2. 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.

3. Work with the local debug tool. Use breakpoints, debug called programs, change variables, and so forth.

4. (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)

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, debugging called programs, change

variables, etc.

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


http://www.ibm.com/developerworks/downloads/emsandbox/systemz.html

http://www-01.ibm.com/software/awdtools/rdz/?S_TACT=105AGX28&S_CMP=EMSAND

http://www-01.ibm.com/software/awdtools/rdz/?S_TACT=105AGX28&S_CMP=EMSAND

http://www.ibm.com/developerworks/downloads/emsandbox/systemz/architecture/

http://www.ibm.com/developerworks/downloads/emsandbox/systemz/architecture/


Prepare the environment We are assuming that Rational Developer for System z is started and connected to our mainframe. Before starting working in the code, you may disconnect from the mainframe, since this exercise will be totally disconnected from the System z

1. Using the Remote System view, right click on dallas and select Disconnect as seen in Figure 1.

Figure 1. Disconnecting from the mainframe

Load the local COBOL programs and copybooks 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 2)

Figure 2. Import dialog in the z/OS Projects view

2. Click either the down-arrow button or the Browse button, and find the C:\RDZ7.6_POT\LAB1\LAB1_COBOL.zip file. If you used the Browse button, click Open.



3. Select LAB1_LOCAL_COBOL, and click Finish as seen in Figure 3. 4. By default when a project is loaded, Rational Developer for System z tries to build

the entire project and this fails here since you have not yet associated a property group to this project.

5. You will have an error (Errors during build) Click OK to dismiss the error dialog.

Figure 3. Import Project Interchange Contents dialog

Expand the + sign to see the assets shown in Figure 4 Some folders will be added to the workspace, and a LOCAL project will be created: Figure 4. 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 5 shows the table content. Figure 5. DB2 Table content



Local projects and properties When you first define your local project, you set values for properties, such as compiler options, copybook location, etc…. 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. The properties in local projects are similar to job control language (JCL) statements when using COBOL compilations, link and so. 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. PROPERTY GROUPS You can create property groups with property values that can be shared by z/OS projects, subprojects, and resources. A property group is a set of property values that you define for local COBOL and PL/I projects or specific remote systems. Once defined, the values in a property group can be applied to the z/OS projects, subprojects, and resources that you create on that system. Property groups provide a way to manage resource properties, share them easily across systems, projects, resources, and users, and maintain consistency in your development and build environment. You can, for example, define a property group with values required for debugging in your environment and apply that property group to your resources when you need to debug the programs in your project or subproject. If you need to change a specific property value, for example, the JCL job card and data set, you can change this property once in the property group and the change is propagated to all resources associated with that property group. System programmers can create property groups and default property values and make them available to users. When a connection is made to a system, Rational Developer for System z searches the system for system property group and default value files. If these files are found, then those property groups or default values are loaded and can be used. Assigning a property group to the projects and resources You must assign a property group as the current property group for a project. Assigning a property group to a project associates the property values in the group with the resource. This action is a good way to set or change the property values for a resource because it enables you to maintain consistency across your projects, subprojects, or data sets. If you decide a different set of properties is more suitable for your purposes, you can use this action to change the current property group for a resource

1. From the z/OS Projects view, right-click LAB1_LOCAL_COBOL and select Property Group > Associate Property Group… When the window opens select LAB1_LOCAL and click OK (Figure 6).

Figure 6. Associate Property Group to the project

Note: If this property is not there, it is because you are using a wrong workspace. You might continue, but will need to Import the property using the Property Group Manager view. Right click on Local > Import … > from C:\RDZ7.6_POT\LAB1\LAB1_property_group.xml



2. To verify the pre-defined properties for one resource: Expand cobol folder by clicking the plus (+), right-click on CUSBATCH.cbl and select Properties (see Figure 7) Figure 7. Verifying CUSTBATCH.cbl properties (1 of 4)

3. Click on Property Group, and note that this resource is associated with

LAB1_LOCAL (figure 8). Click OK to close this dialog.

Figure 8. Verifying CUSTBATCH.cbl properties (2 of 4)

4. To verify the properties, using the Property Group Manager view, double click on LAB1_LOCAL properties to edit it as shown in Figure 9.




5. Click on COBOL tab to see the defined settings for Local COBOL (Figure 10). No changes are needed


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 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.

6. Click Link tab. 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 11)



Figure 11. Local Link Options

7. Close the editor ( Ctrl + F4 ). You do not need to make any changes on the

properties. 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, you assigned a predefined property group to the project, so 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 few Rational Developer for System z editing capabilities.

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 12.

Figure 12. CUSBATCH.cbl edited



2. A nice feature part of the editor is the Outline. On the lower left, click the Outline tab to change focus to the Outline view (Figure 13).

Figure 13. 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 editor-specific, for example in COBOL we show the divisions, when editing Java we see the methods, etc...

3. Expand the plus signs and observe the COBOL structure (Figure 14). Figure 14. Click the plus signs to expand the view

In this view, some icons show operations to be done in this view like “Sort ascending”, “Show only divisions”, “Hide nested programs”, “Show DATA DIVISION only”, and others Examples of icons that can help you save time

4. Click 030-SEEYA (under PROCEDURE DIVISION). The editor will show the 030-SEEYA COBOL paragraph code (Figure 15).

Figure 15. 030-SEEYA COBOL paragraph 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 030-SEEYA paragraph is coded), and select Add Bookmark from the drop-down menu (Figure 16). To bookmark this paragraph for later changes.

Figure 16. Editor view

2. Accept 030-SEEYA as the bookmark name (Figure 17) by clicking OK. Figure 17. 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 18). A line is also added to the Bookmarks view (you will see that later). Figure 18. 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 ISPF, if you prefer you can change the editor appearance.. In this exercise we have already the option set to ISPF.

1. To open the Preferences dialog, select Window > Preferences (Figure 19). Figure 19. Open Preferences from the drop-down menu

2. In the left panel, click LPEX Editor, and then from the Editor Profile list (Figure

20), click ispf. It is already as ispf. But you could have other editor flavor Figure 20. LPEX Editor Preferences options



3. Do NOT close this dialog. You will make other changes in the preferences. 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 shows some of the editor commands. 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. Using the Preferences dialog ( Windows > Preferences.)

2. 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 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 Tabs Preferences for LPEX editor

Close the file being edited by clicking the X in the title tab (also can use Ctrl + F4): Figure 23. Close the editor

4.



Using the COBOL editor 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 24) to find the bookmarks, select this sequence: Window > Show View > Bookmarks.

Figure 24. Bookmarks view

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 25). 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 25. 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. And also a yellow mark is displayed on the left. The COBOL editor checks the syntax as you type it. Cool isn’t? You don’t need to compile to find COBOL syntax errors. (See Figure 26) Figure 26. Intentional error: DSPLAY



4. Move the mouse to the yellow mark and you will see what is the error: (Figure 27)

Figure 27. Understading the error cause

5. 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.

6. Press Ctrl+ S to save the change.

7. 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 28).

Figure 28. CUSBATCH.cbl title tab

8. 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. (Figure 29)

Figure 29. Deleting a line

9. Scroll down to move the cursor to line 142, and press Ctrl + Enter to insert a

new line. Use the Tab key and type a new paragraph name for column 8, such as ADDED in the example in Figure 30: Notice the yellow mark again. You can see what is wrong moving the mouse to the mark.

Figure 30. Adding a line



10. When you have finished, double-click the blue title 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.

11. Now press Ctrl + S to save the file.

12. 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 31, and then click OK.

Figure 31. Reset Perspective default views

Notice that the Bookmarks view also goes away, because it is not part of the default z/OS Projects perspective. Working with Margin lines using the editor The LPEX editor has a new feature that will help you when editing COBOL, PL/I or JCL.. Let’s see it.

1. Click on Window > Preferences

2. Expand LPEX Editor > System z LPEX Editor and click COBOL Parser. Notice that that the Margin R at column 73 is selected (Figure 32).

Figure 32. Enabling Margins on Editor for COBOL (1 of 2)



3. Select Enable Margin A line at column 8 and Enable Margin B at column 12 and click OK (Figure 33)

Figure 33. Enabling Margins on Editor for COBOL (2 of 2)

You will see that a line will show Margin A and Margin B. This is cool since it helps when working with COBOL, note also that you can always use Tab key also. This helps you for quickly column alignments in COBOL (Figure 34).

Figure 34. Result after enabling Margins on Editor

4. To return as it was before:. Click on Window > Preferences, expand LPEX Editor > System z LPEX Editor and click on COBOL Parser. Clear Enable Margin A line at column 8 and Enable Margin B at column 12 and click OK

You will see that the lines on columns 8 and 12 will disappear..

What have you done so far? You imported a COBOL program, created a book mark and did small code changes. Note that this program has lots of errors. All variables defined in the copybooks were not resolved since the properties that tells where is the copybook was assigned to the project only after its compilation when loaded. We will fix that soon. 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 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.



Using the Local History feature 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 35).

Figure 35. Replace with Local History

The Replace from Local History window opens.

2. Double click in the first date Notice the two small change bars shown to the right of the scrollbar on the right side. These mark where changes were made

3. Click the blank bar (the second mark) to jump to the other change. (Figure 36)

Figure 36. Comparing two file versions

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. You see the ADDED as a new paragraph name.



4. Click the Replace button to replace the copy being edited and return to the previous version. (Figure 37)

Figure 37. Replace the file with the previous one

The previous version is restored (Figure 38) and ADDED paragraph is not there anymore Figure 38. Previous version restored

5. Close the editor by clicking the X beside the file name:

Or use Ctrl + Shift + F4 (close all files being edited)

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.



Check the COBOL source file syntax

1. Using the z/OS Projects view, right-click CUSBATCH.cbl and select Show Dependencies… (Figure 39)

Figure 39. Selecting Show Dependencies

It shows all dependent components that are required for a correct compilation of this COBOL program. See the results on Figure 40. Figure 40. Dependencies for CUSTBATCH.cbl

2. Click OK to dismiss this dialog. 3. Using the z/OS Projects view (Figure 41), right-click CUSBATCH.cbl and select

Local Syntax Check from drop-down menu.

Figure 41. Select Local Syntax Check from the menu



4. Click the Remote Error List tab to see the list of compile warnings and errors (Figure 42). Notice that all errors were gone, and now you have only the error that you introduced. Note that the order of errors and warnings might be different that shown in the Figure below.

Figure 42 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 43.

Figure 43. Editor shows code with error

2. Change back from DSPLAY to DISPLAY.

3. Save your changes (Ctrl + S) and perform another Local Syntax Check to ensure that the compilation is now clean (Figure 44).



Figure 44. Repeat the Local Syntax Check

4. Click Remote Error List. You should see no errors in the Remote Error List view after re-running the Local Syntax Check.

Notice that the warnings are gone also, because they resulted from the error that you have fixed. 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.

Using the COBOL Content Assist features You are now going to add COBOL statements after the PROCEDURE DIVISION.

1. Using the Outline view, click PROCEDURE DIVISION to position the cursor on that line.

2. Then type the command i3 (insert 3) in the gray area for that line and press Enter. This will add three blank lines as shown in Figure 45.. (Alternative: You could use Ctrl + ENTER 3 times to add 3 empty lines.)

Figure 45. Adding 3 empty lines



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

Figure 46. Double click the title tab again

4. On Line 77, use the Tab key to move the cursor to Column 12. Note: You MUST be in column 12 or higher, otherwise the Content assist will not work.

5. Type DI, and press Ctrl + Space. The dialog will show all statements that start with DI.

6. Double-click DISPLAY. (See Figure 47.) or press Enter since this is the selected option.

Figure 47. Content assist feature

The entire line can be coded by using the Code Assist feature:

7. Move the cursor after the DISPLAY command and type “Enter name or Q to quit” (must type the “ also) .

8. 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 48.)

Figure 48. Double-click the word UPON



9. Start typing console with just the first three letters, con, use Ctrl + Space again, and then double-click CONSOLE (see Figure 49).

Figure 49. 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.

10. 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 50).

Figure 50. Adding the Input-name variable

The result will look like Figure 51. Figure 51. After the Input-name variable has been added

11. 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 52 shows.

Figure 52. Few If statements to choose from

12. 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



Figure 53. Code added on Line 79

Notice that, because the LPEX COBOL editor is a smart editor, some mistakes appear at coding time.

13. 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 a warning > Move the mouse there and you will see the error message shown in Figure 54.

Figure 54. Error message: MissingLiteralCompletion”

14. Fix the error, adding the “ after the quit and save the changes by using Ctrl + S. Notice that the asterisk * on the left of the title tab disappears after it is saved:

15. Make the editor smaller by double-clicking on the title tab to resize it.

16. Right-click CUSBATCH.cbl, and select Local Syntax Check to check the syntax

again (Figure 55). Figure 55. Run the Local Syntax Check again

17. 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 56. 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:\RDZ7.6_POT\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. After a while, the Help screen will open, showing the selected statement. You can use this feature for any statement.

Figure 57 . Pressing F1 to get help on DISPLAY statement

After a few moments (it can take a while the first time), the Help window will open and you will have what Figure 58 shows. If does not open as another window, use Figure 58. Help results

2. Click DISPLAY statement to get more information. (Figure 59)



Figure 59. DISPLAY statement description

3. Close this Help window. (Figure 60) Figure 60 . Click the X in the upper-right corner to close the window

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. 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 61. 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:

3. Using the z/OS Projects view, expand LAB1_LOCAL_COBOL, and cobol folder, right-click on CUSBATCH.cbl, and select Nominate as Entry Point. (Figure 62) Notice that Figure 62 does not show all of the actions that you can apply. Nominate as Entry Point is almost the last action.

Figure 62. Nominating the CUSBATCH.cbl program as Entry Point

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 63). This action will invoke the COBOL Compiler and the linker, create the executables, and create the BuildOutput folder again.



Figure 63. Rebuilding the project

5. Expand the BuildOutput folder (Figure 64).

Figure 64. 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 results 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 store the output at the BuildOutput folder. To see the main COBOL program compile listing:

1. Double-click on CUSBATCH.lst. (Figure 65.) Figure 65. COBOL program compiler listing being edited



Notice that the compiler TEST option was used. This will enable you to use the DEBUG option later. Figure 66. Editor view showing TEST

2. 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 67. End of the code listing

3. Close the CUSBATCH.lst editor (Ctrl + F4). 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.

4. Review the REGI0C.lst now by double-clicking to edit it and clicking CTRL + End.

Figure 68. REGI0C.lst eited

5. Close all opened files. You can use CTRL + Shift + F4.



Creating a launch configuration and running the COBOL program Launch Configuration 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:

1. Right-click on CUSBATCH.exe and select RunAs > Run Configurations… (not Run on Server).

Figure 69. Select Run As, then Run Configurations…

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 70).

Figure 70. Creating a debug configuration

3. In the Name field, enter a name, such as RunCUSBATCH.

4. 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:\Workspaces7.6\SANDBOX\LAB1_LOCAL_COBOL\BuildOutput\CUSBATCH.exe



Figure 71. Run view and Main tab

5. Click the button Run. The execution begins, and you will see the dialog shown in

Figure 72. 6. Type your first name and press Enter. See one example below:

Figure 72. "Reginaldo" typed as first name

7. Type 006 as the customer number and press Enter.

Figure 73. 006 typed as customer number

The results should be something like the screen shown in Figure 74. Figure 74. Data displayed



8. Type 999 to stop the execution. The console window will close, and you will be back to Rational Developer for System z. In the next section, you will debug these programs by using the local debug tool. What you have done so far

• You created an executable program (*.exe) with two COBOL programs and ran it. • 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.

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 With Configuration > RunCUSBATCH (Figure 75).

Figure 75. Selections for the debugging

2. The dialog shown in Figure 76 will ask if you want to switch to the Debugger perspective. Click Yes.

Figure 76. Confirm Perspective Switch dialog



The Debugger perspective is opened and the debugging process starts. Notice that Rational Developer for System z opened a new perspective named Debug (Figure 77). Figure 77. Debug Perspective

3. 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 78). Figure 78. Stopped at ACCEPT Input-name, Line 78

Note: If you get some Assembler code instead of COBOL, click the icon (step filter) as seen in Figure 79 Figure 79. Be sure that step filter is in effect

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



Adding 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 80).

Figure 80. Adding a line breakpoint

2. Using the Outline view (on right), expand the PROCEDURE DIVISION and click on paragraph 020-LOGIC Using the editor, scroll down a few lines and add another breakpoint (double click on left gray area) in the line 98, just before the subroutine CALL. A small circle indicates the breakpoint (Figure 81)

Figure 81. Adding a second line breakpoint

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. Click the Resume icon or press F8.

4. 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 PC screen, where Windows show the running programs.

5. Restore the minimized windows, and look at the base of your screen.

Click C:\Workspaces7.6\SANDBOX to restore the workspace.



6. Click in this window and type your first name (Figure 82), press Enter, the window will be minimized again . If not, just minimize (do not close) the DOS window to continue with the debug.

Figure 82. "Reginaldo" typed as first name

7. You will be returning to the Debug perspective, where you will notice that the execution is at Line 81 (Figure 83).

Figure 83. Process stops at Line 81

8. Using the Outline view click on PROCEDURE DIVISION statement (Figure 84)

Figure 84. Go to 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 85).

Notice that a variable's value is also shown in the Variables view (Figure 85), Figure 85. "Reginaldo" 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 86, and then press Enter.

Figure 86. Variables view

11. Click the Breakpoints tab (Figure 87) to see all breakpoints assigned to this program:

Figure 87. Breakpoints tab



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.

Adding a Watch breakpoint You will now add a Watch breakpoint.

1. Right-click in the Breakpoint view, and select Add Breakpoint > Watch. Figure 88. Adding a Watch breakpoint

2. 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 89.)

3. Then click Next and Finish. Figure 89. 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 90). This is because the MOVE 2 to BRANCHFLAG is executed, and this field has changed. Click OK. Figure 90. Debug Engine Message



The debugging will be stopped at Line 84 (Figure 91). Notice that the execution stopped immediately after the BRANCHFLAG field changed. Figure 85. Debug process stopped at Line 91

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 92), before the CALL command.

Figure 92. Halted again at Line 98

6. Click the Step Into icon (or press F5 ) three times so that you can debug the called program subroutine, REGI0C (Figure 93). Note: May take a while to display REGI0C.

Figure 93. program REGI0C being debugged



7. 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 94).

Figure 94. Debugging program REGI0C

8. 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:

9. Bring back the window again clicking on (from the bottom of the display), and type 006 as Customer number, press Enter, and minimize the console.

10. Click on Variables tab and keep pressing F6 and follow the DB2 database access. You can use the Variables view and check the SQLCODE, as Figure 95 shows on Line 209.

Figure 95 Variables view



11. Keep pressing F6 (do not press F8 ) until the COBOL ACCEPT command is in control again. And the icons are disabled. Also notice in the right the outline view, the paragraphs being shown are displayed there.

12. Now, so that you can see the consequences, type an invalid customer number, such as 000, and then press Enter. The DOS windows should minimize, if not, just minimize it.

Back in the debugger view, you will be stopped at the statement on Line 116 (Figure 96). Figure 96. 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.

13. Using the Outline view, click Start-Again. Move your mouse to the line 112 and click it, right-click and select Jump To Location. (Figure 97).

Figure 97. Select Jump to Location

This will move the execution back to Line 112 (Figure 98).



Figure 98. DISPLAY command, Line 112

14. Press F6 until the #ACCEPT statement is in control again. Restore the DOS window and type another valid customer number, such as 007, and press Enter.

15. You will be back to the debugger view, where you will be stopped in the statement on Line 116 (Figure 99).

Figure 99. DISPLAY command, Line 116

Disable the breakpoints (you can re-enable them later):

16. 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 100. List of breakpoints in the Breakpoints view

17. Click the Resume icon or press F8. 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.)

18. Restore the minimized window by clicking the C:\Workspaces7.6\SANDBOX

icon



19. Type 999 as the Customer number, press Enter to end the debugging, and click OK to dismiss this dialog.

Figure 101. Debug Engine Message

20. Restart the debug process by using the Debug icon, which looks like a bug:

(also see Figure 102). Figure 102. Debug icon in the Debug view

21. Click the Use Step Filer icon to avoid the assembler debugging. Figure 103. 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.

22. Click the Animated Step Into icon: (also see Figure 104). Bring back the

window again clicking on (from the bottom of the display) to answer the COBOL display statements. Type valid values and observe the debug in action.

Tip: If you get blank data on the debug. Close the debug perspective and start the debug again as shown in the step 20. Figure 104. Animated Step Into icon in the Debug view



Ways to control Animated Step Into actions When you choose this, 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: 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.

23. Type 999 when you are finished, click OK, and then close the debug perspective by clicking Close from the drop-down menu, upper-right.

24. If you have learned enough for now, close Rational Developer for System z.

Figure 105. Close the Debug view

You have completed this tutorial. If you have extra time, you can do a bit more by completing the optional sections that follow.

(Optional) Refactoring COBOL code

Use a nice feature to refactor variables and paragraph. We allow refactoring of data items and paragraph names within a single file, also we allow the removal of optional “noise words” (unnecessary words from the COBOL source). Note that this is only available if the COBOL parsing succeeds.

1. Using the z/OS Projects view double click on REGI0C.cbl to edit., as shown Figure 106 shows.

Figure 106. Editing program REGI0C



2. You want to change all data-names definitions and occurrences from “In-Len” to “LENGTH-IN” . Double click on In-Len to select it, then right click and select Refactor > Rename . (Figure 107).

Figure 107. Starting the Refactoring to rename a cobol name variable.

3. Type LENGTH-IN (the new name), select Force preview and click Preview (Figure 108).

Figure 108. Renaming to LENGTH-IN

4. You will see that four references were found for this variable, Click Continue (Figure 109).

Figur9 109. Rename found 4 references



5. The refactoring is performed. Click on the icon to see the next differences (Figure 110)

Figure 110. Rename in action

6. When you saw all click OK The file will the changes is showed (Figure 111).. Figure 111. Statement refactored

7. Click Ctrl + Shift + F4 to close the editors.



SOLUTION: 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:\RDZ7.6_POT\LAB1\solution\lab1_solution.zip. (Figure 112)

Figure 112. Importing the provided solution.

2. You will have many errors on the Remote Error List view and this is because the

Project properties were missing. Depending on which workspace you are using, you may also need to import the property group and associate with this project since they do not ‘stick’ at the Project interchange exporting. Click on Property Group Manager tab, right click on LOCAL and select import (figure 113)

Figure 113. Importing the property group

3. Navigate to C:\RDZ7.6_POT\LAB1|LAB1_property_group.xml and click OK. 4. From the z/OS Projects view, right-click on LAB1_LOCAL_COBOL and select

Property Group > Associate Property Group. When the window opens select LAB1_LOCAL and click OK.

Figure 114. Associate the project with the property group.

. 5. Right-click the CUSBATCH.cbl file, and select Nominate as Entry Point.

Also, there is the Solution workspace (C:\Workspaces7.6\RDZSOLUTION) in your VMWARE image. To start the workspace with the solution:




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 W. Barosa is an IBM Executive IT Specialist. He provides sales support, helping customers with enterprise modernization solutions and development tools, such as Rational Developer for System z. Before joining IBM U.S. more than nine years ago, Reginaldo worked 27 years for IBM Brazil. He has co-authored IBM Redbooks and has written two books, as well as other articles and tutorials for IBM developerWorks. He holds a degree in electrical engineering from Instituto Maua de Tecnologia, Sao Paulo, Brazil

http://www.ibm.com/developerworks/rational

http://www.ibm.com/training/us/catalog/rational

http://www.ibm.com/developerworks/rational/rationaledge/

https://www.ibm.com/developerworks/newsletter/

http://www.ibm.com/developerworks/apps/SendTo?bookstore=safari

http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX01&S_CMP=ART

http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX01&S_CMP=ART

http://www.ibm.com/developerworks/forums/dw_forum.jsp?forum=375&cat=5

http://www.ibm.com/developerworks/blogs/

ibm enterprise modernization for system z:

Documents