Remote IBM z/OS application development with IBM Rational ...public.dhe.ibm.com/software/dw/rational/pdf/rdz_osappdev.pdf · Remote IBM z/OS application development with IBM Rational

Remote IBM z/OS application development with IBM Rational Developer for System z Speed the efficiency of traditional mainframe, Web, and

integrated mixed-workload development

By Reginaldo W. Barosa TechWorks Practice Lead for Enterprise Modernization

IBM Corporation

Level: Intermediate

March 2008

mailto:[email protected]

Remote IBM z/OS application development with Rational Developer for System z, Page 2 of 53

Copyright © 2008, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.

Contents

Overview of development tasks.................................................................................. 3

Connecting to the z/OS remote system.................................................................... 4

Section 1. Allocate z/OS data sets .............................................................................. 6

Modifying the JCL provided .................................................................................... 6

Submitting a JCL for z/OS execution........................................................................ 9

Importing the properties for the MVS files .............................................................. 13

Section 3. Send the COBOL program to the z/OS........................................................ 17

Copying the COBOL program to the z/OS system .................................................... 17

Section 4. Create a z/OS project and subproject......................................................... 20

Understanding how z/OS projects work.................................................................. 20

Creating a new z/OS project................................................................................. 21

Adding resources to the project ............................................................................ 26

Checking syntax by using the Show Dependencies feature........................................ 28

Section 5. Work with z/OS remote assets .................................................................. 29

Editing a remote COBOL program.......................................................................... 29

Modifying the COBOL Program.............................................................................. 31

Generate JCL to compile, link, and GO without the z/OS debugger............................. 39

Submit the JCL to run ......................................................................................... 42

Access the output listings .................................................................................... 42

Generating JCL for running the z/OS debug tool ...................................................... 45

Using the z/OS Remote Debug tool ....................................................................... 49

(Optional) Import the Solution project into your workspace.......................................... 50

Trademarks........................................................................................................... 52

Resources............................................................................................................. 52

About the author ................................................................................................... 53



This tutorial takes you through the steps of using the z/OS Application Development component of IBM® Rational® Developer for System z™ to work with remote systems. It will familiarize you with the IBM® z/OS® Application Development environment. If the connection to the mainframe is available, you will define a remote z/OS, set up a Multiple Virtual Storage (MVS) project, edit, compile, and debug a COBOL application. The process would be the same for a PL/1 program.

Overview of development tasks

To complete this tutorial, you will perform these six tasks: 1. Connect to a z/OS: Prepare your workspace to connect to the z/OS by defining a

Remote System and connecting to it.

2. Allocate z/OS data sets: Allocate and load assets required for this tutorial.

3. Set the z/OS properties: Configure the system data sets names, job names to be generated, and so forth.

4. Send the COBOL program to the z/OS: Copy a COBOL program from your workstation to the z/OS.

5. Create a z/OS project: Specify which data sets you will use in this tutorial, specify properties, and so on.

6. Work with z/OS remote assets: Edit, check syntax, submit, run, debug, and see the output.

If you get an error message This tutorial assumes that Rational Developer for System z is started, the z/OS is ready, and you have logged in with a z/OS ID. If you get an error message, it could be because the z/OS is not ready for you. Please use Feedback to let us know about this problem. When you start this tutorial, you will be logging in on the z/OS, and you will be in the z/OS Projects perspective of Rational Developer for System z.

The z/OS Projects perspective

Use the z/OS Projects perspective to define, connect, and work with remote systems, as well as to create, edit, and build projects, subprojects, and files on your remote systems. The Projects perspective contains the following views:

Remote Systems view (see next page*) z/OS Projects view, Properties view Outline view Remote Error List view z/OS File System Mapping view Remote System Details view

For each system to which you have established a connection, the Remote Systems view shows five nodes under the connection name:

1. JES (Job-Entry Subsystem) 2. MVS files (Multiple Virtual Storage) 3. TSO commands (Time-Sharing Options) 4. USS files (unformatted system service) 5. USS shells



MVS and USS files are file subsystems. TSO commands and USS shells are command subsystems. JES is the JES subsystem. *From the Remote Systems view, you can complete these tasks:

Add or remove remote system definitions Connect or disconnect remote systems Allocate partitioned data sets or sequential data sets on remote systems Launch an edit session for a specific file or PDS member Migrate, delete, or rename data sets Create PDS members within data sets Move, copy, delete, or rename PDS members Submit jobs to the remote system Edit data set name levels Add, modify, or remove mappings that associate workstation files with remote files.

Notice that a filter named My Data Sets is automatically created for you. This means, for example, that if you are logged on as EMFORZXX, you will see all data sets that start with EMPOTXX.*. In other words, EMFORZXX would be the High-Level Qualifier (HLQ), similar to when you use TSO. You could also create other filters, such as filters for these MVS files, among others:

HLQ.* HLQ.* COBOL HLQ.UTIL.* HLQ.* COB.*

However, a filter beginning with an asterisk (*) is not a legal filter.

Connecting to the z/OS remote system 1. If you successfully connect to the z/OS remote system, be sure that you have the

z/OS Projects Perspective available and that you can see the Remote Systems view on the right.

Remote Systems view

The Remote Systems view shows all existing connections to remote systems. Connections are persisted, containing the information needed to access a particular remote host. The view contains a prompt to create new connections, and pop-up menu actions to rename, copy, delete, and reorder existing connections. Connections contain attributes, or data, that is saved between sessions of using the workbench. These attributes are the connection name, the remote system's host name and system type, an optional description, and a user ID that is used by default by each subordinate subsystem at connection time. Underneath, all connections are stored as files in an Eclipse project named RemoteSystemsConnections, which you can enable to share connections with a team.



2. Using the Remote Systems view, expand the dallas node to see all of your data sets, as Figure 1 shows.

Figure 1. Sample data sets

Notice that you do not have the same partitioned data sets (PDSs) that Figure 2 shows (under EMPOTXX.*), because this is just an example. You will probably have more data sets. Figure 2. Dallas node expanded

3. The example in Figure 3 shows EMPOT24. Important: Make a note of this user ID, because you will need it in the next section. Figure 3. EMPOT24 in My Data Sets



Section 1. Allocate z/OS data sets

You are connected to a z/OS remote system. Now you will modify a provided JCL (job control language) and submit it to z/OS to allocate data sets that are required for this tutorial. Notice that the JCL provided is on your workstation, not in the z/OS. You will modify this JCL and submit it for execution in the z/OS remote system.

Modifying the JCL provided We provided a simple JCL that will allocate data sets with your assigned z/OS ID instead of the sample ID provided (EMPOTXX). Therefore, you will edit the provided JCL and change where you find EMPOTXX to your assigned ID.

1. Using the Remote Systems view, left-click the plus (+) signs of Local (not the Local

under AIX), Local Files, and Drives and (see Figure 4), and look for this file: C:\RDz_POT_V7\LAB2\LAB2ALOC.jcl

Figure 4. Remote Systems view (second view after scrolling down)

Caution! Be sure that you are selecting the correct file. This JCL file will be used to allocate all of the PDSs necessary and to copy some members to use in this tutorial. This file is under the three that Figure 5 shows. You might have other assets under this folder.



Figure 5. Select the JCL file

2. Double-click the LAB2ALOC.jcl file to invoke the LPEX editor.

Figure 6. Launch the LPEX editor

3. Now you will change EMPOTXX to your assigned z/OS user ID: a. Use CTRL + F to search for EMPOTXX. b. Type EMPOTXX in the Find field and your user ID in the Replace field (which

shows EMPOT24 merely as an example), and then click Replace all. Important: The example in Figure 7 shows changing EMPOTXX to EMPOT24. Be sure that you are using your assigned user ID rather than EMPOT24 Figure 7. Type your z/OS user ID in the Find and Replace fields

4. Double click in the blue title tab to get a better view of this JCL, and be sure that you have changed everything correctly.



Figure 8. Title tab

5. Browse the file to verify the changes. The idea is to modify the existing EMPOTXX High-Level Qualifier to your ID. In this example, it would be something similar to what you see in Figure 9. Your change will be different, because instead of EMPOT01, you will use your user ID.

Figure 9. High-Level Qualifier changed to your ID (example only)

6. Save the changes by using Ctrl + S. Notice that the asterisk (*) that is beside the title goes away (Figure 10). Figure 10. Lab title tab

7. Press the Esc key to show the command line again.



Submitting a JCL for z/OS execution 1. Double-click again in the blue title tab (Figure 11) to resize the file windows back to

original size. Figure 11. Title tab

If you are still connected to the JES subsystem, you can submit this job to dallas for execution. (Sometimes a JES timeout occurs. If that happens, you will get an error when submitting, but we will explain how to fix it.)

2. Type submit to dallas, and press Enter. Figure 12. Type "submit to dallas"

You will see the JOB ID that was created for this execution (Figure 13). Figure 13. Job ID that was created previously is automatically added

3. Using the Remote Systems view, collapse the Local folder by left-clicking the hyphen (–), because you do not need that anymore.

Figure 14. Click to collapse the Local folder

4. Still using the Remote Systems view (Figure 15), left-click the plus signs to expand the JES node, the My Jobs filter, and EMPOTXX1.



Figure 15. Expand JES, My Jobs, and EMPOTXX1

5. Double-click in the JES Job Log (JES2:JESMSGLG) to make sure that the job has successfully run and that the return code is 4, 0, and 0, as Figure 16 shows. (It could be all zeros if you had data sets allocated already.)

The DELIST step may have 4 or 0. If the data set was already allocated, it will delete that and, in this case, it will be 0 rather than 4. Figure 16. Verify that the job has run and shows the correct return codes

Re

mote IBM z/OS application development with Rational Developer for System z, Page 11 of 53


What you have done so far

You just submitted a JOB that was executed in the z/OS and allocated data sets that you will need for this tutorial. You saw the execution output in Figure 16. Important! Do not continue until this task has been successful.

6. Close all opened editors (LAB2ALOC.jcl and the JES2 JOB LOG) either by using CTRL

+ Shift + F4 or clicking the close-window icon:

Alternative method to see the JES output

Another (better) way to see the JES output is by creating another view:

A. From the Remote Systems view, right-click My Jobs and select Show in Table (Figure 17).

Figure 17. Remote Systems view path to Show in Table

B. When the Remote System Details view opens (Figure 18), notice the column that shows the Return Code. Double-click that column header to open the output listing.

Figure 18. Remote Systems Details view

7. You will now purge the output of the jobs listed. If RACF allows you to do that:

a. Go to the Remote System or Remote System Details view. b. Right-click your Job and select Purge (see Figure 19).



Figure 19. Job Filter for My Jobs with job row selected and drop-down menu to select Purge

8. Using the Remote Systems view, expand My Data Sets by left-clicking the plus sign. You should now have allocated all of the data sets required for the next exercise (Figure 20). Figure 20. Data sets allocated under My Data Sets

Section 2. Set the z/OS system properties You have the data sets required on the z/OS, and you will define the settings required to work with the z/OS assets, such as specifying the correct COBOL libraries, CICS and DB2 settings, and so forth. Usually, this is done only once for each workspace.

MVS Files properties page

You can use the MVS Files properties page to edit the properties of an MVS Files subsystem. This page contains a list of property sets. Select a set to display its properties, such as Assembler Settings , BMS Settings, C/C++ Settings, COBOL Settings, Code Pages, Application Entry Point, JCL Job Card, Link Options, MFS Settings, PL/I Settings, Runtime Options, Server Connection Security, Server Launcher Settings, and Subsystem.



Rational Developer for System z assigns a set of default properties for the set of system properties. If you plan to develop COBOL applications in the workbench, you may wish to set properties on the Compiler Options tab of this page and override the JCL Procedures that would otherwise be used for compile, link, and execution requests. Note that the string <HLQ> is automatically replaced with the high level qualifier you select when you create a project from this system definition. Depending on your use of CICS, DB2, and IMS, you may need to set additional properties on the remaining tabs of this page.

Importing the properties for the MVS files Because you perform this task once per installation, import the already-defined properties for your environment:

1. Using the Remote Systems view, expand dallas, select MVS Files, right-click and select Import Properties.

Figure 21. Remote Systems view for importing properties

2. Navigate to C:\RDz_POT_V7\LAB2\LAB2_MVS_Files_Properties.xml and click Open to accept the file. The required properties for the MVS Files will be imported.

Figure 22. Import the properties for the MVS files

You will see the imported properties in the next steps. Usually, those properties are shared among developers.

3. Select MVS Files again, right-click and select Properties (Figure 23, which follows).



Figure 23. Remote Systems view to select properties

4. You need to change the JCL card: a. In Properties, select JCL Job Card and change the xxx to your z/OS ID

number. Example: If your user ID is EMPOT24, change it to GEN024. b. DO NOT click OK.

Figure 24. JCL Job Card view

5. Still in the Properties window, click COBOL Settings in the directory on the left. 6. Click the + signs at the left of ELAXFCOP, ELAXFCOT, and ELAXFCOC. 7. Select COBOL, and then click Edit step.

This is the default COBOL procedure when the COBOL syntax checking is used. Note: You could enable and disable the procedures that must be executed before the COBOL compilation if necessary. These are the default procedures supplied (but disabled):

ELAXFCOP. Invoke DB2 pre-compiler ELAXFCOT. Invoke CICS translator ELAXFCOC. Invoke COBOL compiler



Figure 25. Selecting and editing COBOL settings

The COBOL Compile Step Options dialog will open. You could change these properties, such as Compile Options, data set names, and so on. For instance, when JCL is generated for Compile, it will use the options specified here. Later, the <HLQ> will be replaced with your logon user ID when JCL is generated or when you create a z/OS project, as we will discuss here later.

8. In this case, do not make any changes. Your screen must be exactly as shown in Figure 26, which follows, so simply click OK to close the COBOL Compile Step Options window.

(continued next page)



Figure 26. COBOL Compile Step Options view

9. Also click OK to close the Properties window. No changes were made here either. Figure 27. Close-up of the OK button


You have connected to z/OS and have submitted a job to allocate and copy some of the members required to complete this tutorial. You also imported the XML file that defined the configuration properties of the MVS files. Now, if you ask for JCL generation, for instance, the data set names will be correct. Next, you will copy a COBOL program to z/OS and play with it.



Section 3. Send the COBOL program to the z/OS

You have the data sets and copy book members required for this tutorial, but you still need a COBOL program to play with. In this section, you will copy a COBOL program from the workstation and move it to your PDS member. Later, you will work with this program. You could do that with the JCL that you had submitted before, but we want to show you that one way to move data sets is to copy and paste files from your workstation to the z/OS. This capability will also work between different z/OS systems.

Copying the COBOL program to the z/OS system The data sets that you created submitting the JCL consist solely of the COBOL Copybooks and two COBOL subroutines. You will now copy the main COBOL program that is in your Microsoft® Windows® directory to the z/OS system.

1. Using the Remote Systems view (Figure 28), left-click in the plus sign (+) of the nodes Local, Local Files, Drives, and C:\, and look for this folder: C:\RDz_POT_V7\LAB2

Figure 28. Folders and locations expanded in the Remote Systems view

2. Right-click CUSVSAM.cbl (Figure 29), and select Copy.



Figure 29. Copy option in the drop-down menu after selecting CUSVSAM.cbl

3. Still using the Remote Systems view, scroll down, expand MVS Files and My Data Sets until you find the EMPOTxx.POT.COBOL data set (where EMPOTxx is your user ID).

4. Right-click EMPOTXX.POT.COBOL and select Paste, as Figure 30 shows. Figure 30. Select Paste

The programs will be moved from your workstation to the z/OS. A progress indicator will appear, as Figure 31 shows.



Figure 31. Progress Information screen

5. If necessary, expand the data set EMPOTXX.POT.COBOL by clicking the plus sign next to the DTPOT24.POT.COBOL folder. You will see the COBOL program loaded in the z/OS and also mapped to cbl (COBOL).

Notice that the other programs were already there. Also, you could have done this just as you copy files in your workstation, dragging them from the Windows Explorer or the Local Files folder. Figure 32. The CUSVSAM COBOL data set

6. Using the Remote Systems view, scroll back and collapse the Local folder by clicking the icon (Figure 33), because you don’t need it anymore.

Figure 33. Local folder icon


You have connected to z/OS and have submitted a job to allocate and copy the members required to complete this tutorial. You also imported an XML file that defined the configuration properties of the MVS files. In this last section, you copied a COBOL program from your local workstation to a z/OS data set. You are ready to start working on this asset now.



Section 4. Create a z/OS project and subproject

After you define a z/OS-based system, you can define a z/OS project under that system, but you can define the z/OS project only when you are connected to the system.

Understanding how z/OS projects work Rational Developer for System z assigns a set of default properties from the set of system properties. However, changes that you make to system properties do not affect the definition of an existing project. If you change your system properties to reference a new compiler release, for example, the reference affects only those projects that are defined after the change. This isolation of system data from existing projects is beneficial because it lets you develop your code without disruption. You can introduce changes to the project definition when you choose.

States of a z/OS project

A z/OS project is in either of these two states:

Online. The project is connected to the system to which the project refers. You can directly change the data sets that are stored on that system.

Offline. The project can access only workstation-based files, which may be new or may be copies of mainframe resources.

When you disconnect from z/OS, you can specify the data sets and members to be transferred to the workstation. When you switch back to the online state, the specified files are automatically uploaded to the mainframe, with a confirmation message that keeps you from unintentionally overwriting resources. Before creating a new MVS subproject

MVS subprojects contain the development resources that reside on an MVS system. You can create multiple subprojects in a z/OS project. Before you create an MVS subproject, you need to have completed these tasks:

Connecting to a remote system Creating a z/OS project

To make your job easier, you will group all of the assets that you will work with together. This is a new development concept for TSO users, because TSO does not have this capability. To accomplish this task, you will create a z/OS project, and then select which assets will be part of the project.

What's new in Rational Developer for System z V7 related to z/OS projects

A host-based project is one that has been defined on a z/OS system and can be downloaded to the workstation when you connect to the remote system. Host-based projects enable an installation to define and automatically propagate projects on client workspaces from a central location. When you disconnect from a remote system, the host-based projects are removed from your z/OS Projects view. Host-based projects are associated with specific user IDs and downloaded automatically when those user IDs connect to the z/OS system.



Creating a new z/OS project The advantage of creating a z/OS Project is that we just focus on those data sets and members that are being constructed or updated, instead of having all of the dozens of mainframe data sets or members. At anytime if you need to see a data set not added to the project, just go to the z/OS Systems view and add it. Also, at any time, you can remove from your project the data sets no longer being used.

1. Using the z/OS Projects view (on the left), right-click the blank area and select New > z/OS Project.

Figure 34. Starting a new z/OS project

2. For the Project name, type POTCOB, and then select Create an MVS subproject and click Finish.

Figure 35. Naming and creating the project

3. Type LAB2_COBOL as the Subproject Name and click Next.



Figure 36. MVS Subproject Name and Location view

The High-Level Qualifier will be your user ID. In the example in Figure 37, that is EMPOT24, because that is the user ID of the person who is logged in.

4. In the JCL Job Card and Data Set dialog (Figure 37), change the JCL Data Set field entry from EMPOTXX.GENERTED.JCL to EMPOTXX.POT.JCL (where EMPOTXX is your z/OS user ID).

Figure 37. The JCL Job Card and Data Set dialog



5. Click Next 4 times to continue, until you see the COBOL Settings panel. For now, only COBOL is relevant.

6. Expand the ELAXFCOC procedure (click the plus sign +), select COBOL, select Edit Step.

Figure 38. COBOL Settings view

7. Review the COBOL Compile settings (Figure 38, which follows). Notice that the values were inherited from the dallas system properties that you had imported previously. Also notice that the <HLQ> has been automatically changed to your z/OS logon user ID. This example shows EMPOT24, but your panel should be something different, such as EMPOTXX, where XX is your assigned number.

8. No changes are required here, so click OK to close this window. Figure 39. COBOL Compile settings



Note: If your properties do not show your z/OS user ID, it is because you missed the steps where you imported the properties. You will need to delete the project (but not the data sets), import the properties again, and recreate the project.

9. Click Next until you are in the Linkage Editor Name Choice panel. 10. Expand the + beside ELAXFLNK, click LINK, and then click Edit Step.

Figure 40. Linkage Editor Name Choice view

11. No changes are required here, so just click OK to close this window (Figure 41). Figure 41. Link Step Options view, which includes the Link Libraries field



Tip: The Link Libraries (Figure 41) include more than one data set, because this is how we concatenate data sets. Just add as many as you want with a space between each.

12. Click Next 2 times until you get to the Run Options panel (Figure 42). 13. Expand ELAXFGO, select RUN, and then select Edit Step.

Figure 42. Run Options view

This is the panel that will specify the properties for the GO step in the Compile-Link-GO job. Because you must access a VSAM data set at this step, you need the JCL card to be specified here. This was already done for you for this example (see Figure 43) and was also part of the imported properties inherited from the dallas system. Run in batch was also specified, because we do not want to use the debugger during the first execution. Notice the DDNAME POTVSAM in the additional JCL field. This is the DDNAME that will point to the AM data set in the z/OS, which is required for the batch run. When the JCL is generated, this DDNAME will be added.

14. Click OK to close this window. No changes are required here. Figure 43. Runtime Step Options view



Remote debugging

With remote debugging, you could run the COBOL program on the z/OS and control it from your workstation. You will not use the debugging option at this point, but if you were using it, you would follow these steps:

A. On the Application Entry Point page, make sure that COBOL is selected. B. Ensure that you specify the TEST compile option in your COBOL settings, Compile

Options page, or in the procedure that compiles the COBOL (default setting). C. Select Run in batch with debugger on the Runtime page, rather than Run in

batch, as you did for this example.

15. Click Finish to create the z/OS project. You should see a z/OS Project named POTCOB in your z/OS Projects view.

16. Using the z/OS Projects view (Figure 44), left-click the + sign to expand the POTCOB project. You'll see that is empty, but it was defined.

Figure 44. z/OS Projects tab

Adding resources to the project To make the data sets available to your remote project named POTCOB, you will need to add them. For this tutorial, you need to add only three data sets, but you could add specific members or the whole data set.

1. Using the Remote Systems view on your right (Figure 45, which follows), expand MVS Files and My Data Sets under dallas until you see the data sets that you allocated before.

2. Select EMPOTXX.POT.COBOL, EMPOTXX.POT.COPYLIB, and EMPOTXX.POT.JCL (hold the Ctrl key down for multiple selections), right-click and select Add to Subproject. (See Figure 45, which follows.)



Figure 45. Path to add subproject in Remote Systems view

3. In the Add Resources panel (Figure 46), select the z/OS POTCOB project from the drop-down menu and LAB2_COBOL from the subproject drop-down menu.

4. Click Finish.

Figure 46. Add Resources view

5. Switch to the z/OS Projects view and expand LAB2_COBOL. You will now see that EMPOTXX.POT.COBOL, EMPOTXX.POT.COPYLIB, and EMPOTXX.POT.JCL are defined to the POTCOB project.

6. Also expand EMPOTXX.POT.COBOL, EMPOTXX.POT.COPYLIB, and EMPOTXX.POT.JCL. The z/OS Projects view should look like Figure 47.



Figure 47. z/OS Projects view

Checking syntax by using the Show Dependencies feature In this example, we have added the COPYBOOKS in the project; however, this is not necessary. Rational Developer for System z provides a feature called Show Dependencies. You can automatically add the dependencies of a COBOL or PL/I program to your MVS subproject. You must first have added your COBOL or PL/I program to an MVS subproject, and your program must not contain any syntax errors. Note: If your program depends on a file that cannot be found, an error message is returned and the file is skipped. To ensure that files are not skipped, you may first run a local syntax check on your program. If the syntax check does not produce any errors, it means that all of the dependencies can be located and no files will be skipped.

1. Right-click the COBOL or PL/I program in the z/OS Projects view. 2. Select Show Dependencies in the drop-down menu. A job will be submitted to

z/OS and, if the system is able to process your job, a window will open that lists the dependencies for the selected program. This operation could take minutes, depending on the z/OS availability.

3. Select the dependencies from the list that you want to add to your subproject. 4. Select the Add selected to subproject check box. 5. Click Finish.

The selected dependencies are added to your MVS subproject.




At this point, you have connected to z/OS and have submitted a job that allocated and copied the members required for this tutorial. You have also imported an XML file that defined the configuration properties for the MVS files. In Section 3, you copied the CUSVSAM COBOL program from your local workstation to a z/OS data set. In Section 4, you created a z/OS project and added two data sets to this project. You are ready to proceed. If you disconnect now and connect later, you can go the z/OS projects. You will find that the code that you are working on is all grouped there. This is to make your work here easier, so that you don’t need to start looking for all of your components when you resume work on this tutorial.

Section 5. Work with z/OS remote assets

You will work with a z/OS member using the editor. You already explored some of these capabilities in Section 1, but now you will be working with the assets located on the z/OS remote system. You have copied a COBOL program named CUSVSAM from your workstation to a PDS member. This is a batch program that reads a VSAM data set and displays it contents. Also, this program issues a dynamic call and a static call to two other COBOL programs, named REGI0B and REGI0C. Figure 48 shows this program architecture.

Figure 48. CUSVSAM program architecture

Editing a remote COBOL program 1. Using the z/OS Projects perspective and the z/OS Projects view, expand

EMPOTXX.POT.COBOL in the PotCob project.

2. Double-click CUSVSAM.cbl to open the file by using the editor. You should see something similar to what Figure 49 shows.



Figure 49. CUSVSAM.cbl file contents

Tips: You can click to expand the editor area to see more lines of the COBOL program.

Remember that when double-clicking in the title (CUSVSAM.CBL), you can either expand it to a full screen (Figure 50) or return it to the original size.

Also, selecting Window > Reset Perspective restores the default (in that case, you may need to rearrange the Remote Systems and Team views on top of z/OS projects view again).

Figure 50. Click the title tab to expand to full-screen view

3. Click in the Outline tab to see the outline view.

4. Using the editor, browse the program, and notice that the contents of the Outline view are synchronized with the COBOL source code, and vice versa.

5. Click PROCEDURE DIVISION (Figure 51).

Figure 51. Click an item on the left to see the code view for that item on the right

6. You will now make a small change in the DISPLAY statement: Locate line 44, and two characters to the DISPLAY statement (Figure 52), which could be your initials.



Figure 52. Changing the Display statement

7. Save the change by using Ctrl + S. The asterisk (*) beside the title will disappear, as Figure 53 shows.

8. Do not close the editor.

Figure 53. Asterisk no longer shows on the title tab

Note: When you are editing a PDS member, this resource is locked to prevent multiple updates.

Modifying the COBOL Program About the CUSVSAM program

This is a batch program that reads all records from a VSAM KSDS file and prints them, using DISPLAY. Also, this program calls two other COBOL programs (REGI0B and REGI0C) by using dynamic and static calls. The subroutine that is called dynamically does a division by zero that will cause an abnormal end of task (abend) error with System Completion Code=0CB. By using the z/OS debug feature, you can intercept the abend error, modify the value to be other than zero, go back to the division statement, and rerun the division, thus avoiding the abend problem.

1. Using the Outline view, navigate to the first Procedure Division statement by clicking it (see Figure 54, which follows).



Figure 54. Navigate to the first Procedure Division statement

You are going to execute this code, but before submitting a job to the z/OS system to compile the COBOL source file, you can check the syntax to ensure a clean compilation. To see how this works, you will deliberately introduce an error that demonstrates the error feedback capability.

2. Using the Outline view on the left, find and click PROCEDURE DIVISION, and then go to line 44 of the CUSVSAM.cbl code display on the right (or, you could use CTRL + L and type 44).

3. Now, introduce a small error: Use Tab key to find column 16, press the Insert key to enter Replace mode, and overtype DISPLAY with DSPLAY (spelled incorrectly) to force an error.

Tip: Notice that, at the top (Figure 55), the word Replace indicates that the cursor is now in Replace mode. Pressing Insert again returns the cursor to Insert mode. Figure 55. Replace mode

4. Still using the Outline view, click the paragraph 0200-LOGIC and change the IF statement (line 75).



Figure 56. Line 74, 0200-LOGIC

5. Change from LAB2 to NODYNAM Figure 57).

Figure 57. Change the IF statement in line 75 to NODYNAM

Using local syntax checking You will compile the COBOL program by using the local compiler, because this will save CPU resources in the z/OS system. But first, you need to save the changes. There is one option that performs both actions.

1. Right-click and select Save and Syntax Check > Local (Figure 58). Figure 58. Save changes and check syntax

2. Select Syntax check only, and click OK, because there were no changes in the copybooks.

Important: Do not use the default selection (Refresh dependencies), because this might take a while. If you did by accident, be patient. This will submit a JOB to the z/OS.



Figure 59. Check syntax only; do not refresh dependencies

Messages will be displayed in the TPF Toolkit Console view (this is the local compiler console). The return code should be 12 (syntax errors), as Figure 60 shows. Figure 60. TPF Toolkit Console view shows message output

3. Click the Remote Error List tab (in the bottom pane, shown in Figure 61) to check syntax errors.

Figure 61. Remote Error List tab

4. Double-click the error message (Figure 62). This should bring you to the editor, positioned at line 44.



Figure 62. Error message for line 44

Using Replace with Local History You will fix that error by returning to the old version that had the correct Display statement. A nice feature of Rational Developer for System z is the ability to recover previous versions (even remote code) by using the local workstation. This is very useful when you delete and save components on the z/OS, where Undo is not possible after you have saved the changes.

1. Click CTRL + Shift + F4 to close any opened editor.

2. Right click CUSVSAM.cbl and select Replace With > Local History (Figure 63).

Figure 63. Select the CUSVSAM.cbl file, then Replace With and Local History

This operation can take a while, because it goes to the z/OS. It will show all of the previous versions (although you have just one).

3. Use the scroll bar on the far right (see the little hand in Figure 64) to see the next change.



Figure 64. Scroll to see the next change

If you need to change workspace preferences

If you get a different result than the one that Figure 64 shows, you could change the Preferences on your workspace. Also, be aware that you are not using the suggested workspace for the tutorials, so you might have future problems. You can continue for now, but in the next tutorial, switch to the correct workspace. To change the preferences:

A. Select Windows > Preferences. B. Expand General and click Compare/Patch. C. Select Ignore white space. D. Click OK.

4. Click the down-arrow icon to see the change (Figure 65).

Figure 65. Down-arrow icon



As Figure 66 shows, you can see exactly where the difference is. Figure 66. Side-by-side comparison

5. To return to the previous version (the original without changes), click Replace (Figure 67). The version without changes will return to the z/OS system.

Note: All operations are running at the z/OS level. Depending on your network, this could be slower if it is using the local copy.

Figure 67. The Replace button

6. Perform another Local Syntax Check:

a. Right-click CUSVSAM.cbl and select Syntax Check > Local.

Figure 68. Syntax check run on local

b. Again, select Syntax check only and click OK (Figure 69).



Figure 69. Check dependencies? dialog

The TPF Toolkit Console tab (Figure 70) should show the Return Code as 0 (zero). There should not be any syntax errors in your remote COBOL program at this point, so you should see this result at the end: Return Code: 0 Figure 70. TPF Toolkit Console view

7. Click in the Remote Error List view, and notice that there is now a warning in the Remote Error List. The error message from the last time is gone.

8. Double-click in the warning and you will be positioned at the location of the warning. Warnings are fine.

Figure 71. Code content of line with warning message



9. Close all editors that are still open (CTRL + Shift + F4).

Generate JCL to compile, link, and GO without the z/OS debugger Now that you have a successful syntax check of your COBOL program, you can generate the JCL (Job Control Language) that will be used to create the executable file on your z/OS system.

1. Using the z/OS Projects view, right-click the CUSVSAM.cbl file, and select Generate JCL > For Compile Link Go (Figure 72).

Figure 72. z/OS Projects tab

2. In the JCL Data Set and Member Name window, notice that JCL Data Set Name is set to the value that you specified for your project settings.

Important: Be sure that the data set name is EMPOTXX.POT.JCL (where EMPOTXX is your use ID). If it is not, change it to that data set name.

3. Click OK. Figure 73. JCL Data Set and Member Name view



You should see the message that Figure 74 shows. Figure 74. JCL Generation Message notice

4. Click OK.

5. Go to your z/OS Projects view, and expand EMPOTXX.POT.JCL. You will see that CUSVSAM.jcl was generated (Figure 75).

Figure 75. z/OS Projects tab view

6. Double-click the JCL file to open in, and make sure that the job name is GENXXX (where xxx is the last 3 characters of your user ID, for example: EMPOT24 should be GEN024).

The first 14 lines should look something like the screen output in Figure 76. Figure 76. CUSVSAM.jcl file content



Notice that LPEX editor recognizes JCL, and you can navigate through your job in the Outline view.

7. Click the //GO step (line) in the left pane, and notice that the cursor will be at that location in the right pane.

Figure 77. z/OS Projects tab and CUSVMSAM.jcl tab

8. Add a JCL error. For example if you delete the comma in the end of the line 32 (after CUSVSAM) and press Enter will get the error shown in Figure 78. Notice, also, that some keywords are recognized and displayed in blue text.

Figure 78. Error on line 33: LOADDSN=EMPOT24.POT.LOAD

9. Fix the line 32 by adding a comma after CUSVSAM, and then pressing Enter. Figure 79. Comma added at the end of line 32

10. Take a look in the JCL generated: Using the Outline view, click in the //GO step. Notice the JCL card POTVSAM that is generated. This card was defined in the project properties previously.

The program CUSVSAM calls two other COBOL programs: REGI0B and REGI0C. For this tutorial, those programs were already compiled and are in the data sets EMPOTXX.POT.OBJ and EMPOTXX.POT.LOAD, because they need to be included by the linkage editor.



Figure 80. POTVSAM

11. Save the changes (Ctrl + S), but do not close the editor.

Submit the JCL to run Now you can submit the job to be run on the z/OS system. You can use the command editor or the context menu actions. Notice that the JES subsystem must be connected; otherwise, a message will indicate that submission was not accepted.

1. Using the command editor, type submit (or sub), and then press Enter as shown in Figure 81 (you could use TSO/ISPF, instead).

Figure 81. "submit" typed in the editor

A message with your JOBID number will indicate that the job was accepted (Figure 82).

Figure 82. JOBID number added, which indicates that the job was accepted

2. Close the JCL editor by clicking the X.

Access the output listings You can check the job-generated output listings:

1. Using the Remote Systems view, locate the dallas node, and expand JES node.



2. Right-click My Jobs and select Refresh (Figure 83).

Figure 83. Remote Systems view

3. Expand GENxxx JOBxxxx, and you will see the job that you had submitted (Figure 84, which follows, shows an example).

Figure 84. My Jobs with jobs submitted listed

4. Right-click My Jobs and select Show in Table. This is a good way to see the listing, because you get more details, such as the return code, the dates, and so forth (see Figure 85, which follows).



Figure 85. Remote Systems view

5. As expected, there is an abnormal end of task error (abend), as Figure 86 shows, and the return code is S0CB (division by zero)

Figure 86. Abnormal end of task error in Return Info and S0CB for Return Code

6. Using the Remote System Details view, double-click the job that you submitted

(JOB01101).

Figure 87. Job tab



Because the abend error was after the display of the VSAM records, you can see the records displayed.

7. Double-click the GO SYSOUT step to see the results of this step. Each record was read from the VSAM and displayed to the listing. You can also see the decimal-divide exception that caused the 0CB.

Figure 88. Decimal-divide exception

8. Close all of the editors (CTRL +Shift + F4).

9. Using Remote System Details view, select the jobs to be purged (use the CTRL key to select more than one), right-click, and select Purge. The job listings will be purged if you have authorization allowing you to do so.

Figure 89. Selecting the job to purge

Generating JCL for running the z/OS debug tool Change the project runtime for the JCL to be generated with the debug options.

1. Right-click LAB2_COBOL and select Properties (Figure 90). Figure 90. Select the Lab2 COBOL properties



2. Click Run-time Options, expand ELAXGO, select RUN, and click Edit step.

Figure 91. Properties tab for LAB2 COBOL

3. Change the option to Run in batch with debugger and be sure that Program Parameters/Run-time Options is selected, and then click OK and OK to close the properties (Figure 92).

Figure 92. Run-time Step Options view

Note: The reason that we specified Program Parameters/Runtime Options is that we want that the JCL generated in the form of PARM.RUN=('/TEST(,,,TCPIP&&24.60.11.120%8001:*)') to be used by the z/OS Debug. If you specify Run-time Options/Program Parameters, the JCL generated will be in the form of PARM.RUN=('TEST(,,,TCPIP&&24.60.11.120%8001:*)/'), and the z/OS debug will not work this way.

4. Right-click CUSVSAM.cbl and select Generate JCL > For Compile Link Go.



Figure 93. z/OS Projects tab with drop-down menus displayed for further selections

5. In the JCL Data Set and Member Name window, notice that the JCL Data Set Name is set to the value that you specified for your project settings.

6. Click OK. Figure 94. JCL Data Set and Member Name view

7. This is the second time to generate the JCL; therefore, click Yes to replace the existing member. Figure 95. Member Already Exists dialog

8. You should see the message shown in Figure 96. Click OK. Figure 96. JCL Generation Message



9. Open the JCL file double-clicking it. Tip: If you get a message that says "An internal error occurred," just click OK (see Figure 97). This is a known issue in the current version and will be fixed soon, probably by the time you read this.

Figure 97. Error message

10. Using the Outline view, click //GO, where you will see that a PARM.RUN parameter was generated.

Notice that the TCP/IP address of your machine is also generated (and will be something other than the one that Figure 98 shows, of course). Your workstation will be listening at the port 8001 (default). The debug tool running on the z/OS will communicate to you by using this IP address (that is the why this section of the tutorial will work only in networks that are known by the z/OS in Dallas). Figure 98. z/OS communicates with the IP address

11. Close the editor (Ctrl + F4). Important! Do not submit this job.



What you have done so far At this point, you are still connected to the z/OS.

In Section 5, you edited a COBOL program located in Dallas (Texas, U.S.A.), made small changes to it and. after the changes were committed on the z/OS, you returned to the previous version by using the local history. This Rational Developer for System z feature can be very helpful. You added an error in the program, checked the syntax, and corrected the errors. You generated the JCL necessary to run the batch program, and submitted it for execution. You have also seen how the z/OS debug tool would communicate back to your workstation by using the TCP/IP address automatically generated in the JCL card.

Using the z/OS Remote Debug tool

Attention! The z/OS Remote Debug tool will work only if the z/OS Dallas system is able to recognize your workstation IP address. This is not the case in this tutorial. When the COBOL program is running under z/OS Remote Debug, it must be able to communicate back using the TCP/IP address that is known in the z/OS network. If you are behind a router or without an external physical TCP/IP address, the debug tool will not work. Usually, this means that you must be inside the same network as the z/OS server. But at least you have been able to generate the JCL and understand how the debug will work.

Also, you can watch the Flash movie that shows the z/OS debug tool in action.

You will need to be using the Enterprise Modernization Sandbox VMWare image to see the Flash demo. Start the Microsoft® Internet Explorer® browser, and click Favorites to run the demo (see Figure 99).

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



Figure 99. Debug tool Flash demo

In case you do not find this in the Favorites menu, use the Internet Explorer Browser execute the sequence: Click File > Open… > Browse… > and navigate to the HTML file: C:\RDZ_POT_V7\HTML\VIEWLETS\LAB2_DEBUG_with_Callouts\LAB2_DEBUG_with_Callouts.html Tip: Press F11 for more screen space. This movie will last a little longer than 5 minutes. You can play, pause, and stop the movie by using the icons (in that order) that the bar in Figure 100 shows. Figure 100. Flash movie control buttons

When the movie ends, close the Internet Explorer browser and continue to the last section (optional). You have completed this tutorial. (Optional) Import the Solution project into your workspace

If you could not complete the tutorial, or if you missed one step or typed an incorrect name, you would have problems. In that case, you can use the solution workspace: C:\Workspaces\RDZv7SOLUTION. To start the workspace with the Solution project, either

open the POT folder and double-click the RDz7 solutions icon: or use the drop-down menu by the Workspace field to specify this workspace (Figure 101) when Rational Developer for System z starts: C:\Workspaces\RDZv7SOLUTION



Figure 101. Workspace Launcher



Trademarks IBM, the IBM logo, and Rational are trademarks of IBM Corporation in the United States, other countries, or both. Microsoft, Internet Explorer, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. Share this article

Digg this story

Post to del.icio.us

Slashdot it!

Resources

Learn

IBM Enterprise Modernization solutions Try it now with Sandbox for System z Product overview: IBM Rational Developer for System z Demo: Rational Developer for System z Podcast: Building next generation mainframe applications with IBM Rational

Developer for System z and Rational Business Developer White paper: Unleash the power of mainframe assets into SOA See the Get products and technologies section that follows for a trial download

Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.

Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.

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

Get the trial download of Rational Developer for System z

Download trial versions of other IBM Rational software.

Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.

Discuss

Check out developerWorks blogs and get involved in the developerWorks community.

http://digg.com/submit?phase=2&url=http://www.ibm.com/developerworks/linux/library/l-linuxboot/�

http://del.icio.us/post�

javascript:location.href='http://slashdot.org/bookmark.pl?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)�

http://digg.com/submit?phase=2&url=http://www.ibm.com/developerworks/linux/library/l-linuxboot/

http://del.icio.us/post

javascript:location.href='http://slashdot.org/bookmark.pl?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)

http://www.ibm.com/software/info/developer/solutions/em/index.jsp

http://www.ibm.com/developerworks/downloads/emsandbox/systemz.html?S_TACT=105AGX28&S_CMP=EMSAND

http://www-306.ibm.com/software/awdtools/rdz/

http://rational.dfw.ibm.com/atdemo/atdemo_rdz.html

http://www-306.ibm.com/software/rational/podcasts/

http://www-306.ibm.com/software/rational/podcasts/

https://www14.software.ibm.com/webapp/iwm/web/pick.do?lang=en_US&source=swg-systemzsoa11&S_TACT=&S_PKG=SOAE11NOV07GEN1

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

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

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/r/rdz/

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/blogs/

http://www.ibm.com/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 seven years ago, Reginaldo worked for IBM Brazil for 27 years. 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 Mauá de Tecnologia, São Paulo, Brazil.

Documents

Remote IBM z/OS application development with IBM Rational ...public.dhe.ibm.com/software/dw/rational/pdf/rdz_osappdev.pdf · Remote IBM z/OS application development with IBM Rational