Chapter 3: Getting Started with PL/I Applications

This chapter comprises a tutorial-style session showing how you use PL/I Option to include a PL/I application in a Mainframe Express project.

---

You need to have read the chapter Start Here for the Tutorials in your Getting Started and worked through the first session, Using Mainframe Express, before you do this session.

You need to have installed PL/I Option to do this session. We assume you are familiar with PL/I on a mainframe.

You must be using Windows NT to use the PL/I debugger described in this chapter. The PL/I debugger will not dynamically attach to processes on Windows 95 or Windows 98, which prevents it being used with Mainframe Express on these operating systems. You can still do this tutorial if you omit the debugging sections.

---

3.1 Overview

This session takes you through maintaining and running a PL/I application on your PC.

The demo application used in this session is a simple PL/I application that you might have downloaded from a mainframe. In this session, you get it working on your PC. It copies records from one data set to another and, to illustrate program calls, it calls a subprogram which writes a message to the screen.

3.2 Preparation

If you have closed Mainframe Express, open it as before. If any project window or other windows are open, close them.

3.3 Sample Session

In this session you:

• Create a project
• Add files to the project
• Add a data set to the project
• Build the project
• Run the application
• Debug the application
• Step through the program
• Step into a subprogram
• Monitor data values
• Use breakpoints

3.3.1 Creating a Project

To create the project:

1. Click New on the File menu, then select Project on the New dialog box and click OK.

2. Enter plidemo as the name of the project and change the name of the Project Folder to x:\mfuser\projects\demo\plidemo, then click Next.

3. Ensure that Using this wizard is selected and click Next.

4. Leave the default folder for the catalog unchanged and click Next.

   You now get a page asking whether this project uses PL/I (and CICS, IMS or SQL if they are installed). It uses PL/I, but not the other three.

5. If they appear, click the CICS, IMS and SQL check boxes to delete their check marks, and click Next.

   Because you have said this project uses PL/I, you next get a page asking if the project uses only AMODE 31 load modules.

6. Leave the check box checked and click Next.

7. Click Finish.

3.3.2 Adding Files to the Project

To add your files to the project:

1. Click Add Files on the Project menu.

2. In the Add Files to Project dialog box, open the folder \mfuser\projects\demo\plidemo\source. Ensure the Files of Type field is set to Source Files.

3. Click Add All, then click Yes on the confirmation message.

   The files are added to the project.

4. Click Done.

3.3.3 Adding a Data Set to the Project

To add a data set to the project:

1. Right-click in the Catalog View and click Add Existing Dataset.

2. Enter the following information. Remember to use the ... button to put the full path \mfuser\projects\demo\plidemo\data\testdata.dat in the PC Filename field:

   DS Name	PC Filename	DSORG	RECFM	LRECL
   TESTDATA.INPUT.DATA	testdata.dat	PS	FB	400

3. Click OK.

3.3.4 Building the Project

The project contains two source files which need to be built to create two separate executable .dll files.

• PLIMAIN is the main program. When the project is built, this program is compiled and then automatically linked to create a .dll file.

• PLISUB is a subprogram which is called by PLIMAIN. When the project is built, this program is compiled but is not automatically linked unless you set the appropriate option. To do this:
  1. Right-click the plisub.pli file on the Files view

  2. Click Build Settings for PLISUB.PLI

  3. Click Link

  4. Check Automatically link module

  5. Click OK.

Also, before building these files, ensure that Create debug information is checked on the General page of the PL/I page of the Build Settings dialog box.

To build the project:

• Click Build on the Build menu.

  As you saw in the chapter Using Mainframe Express in your Getting Started, the correct compiler is automatically called for each source file - in this case, for the PL/I and JCL files.

  The build finishes with "Build finished with no errors".

3.3.5 Source Errors

There are no source errors in this application.

The method of handling source errors in a PL/I program is the same as in a COBOL program, as shown in the chapter Using Mainframe Express in your Getting Started. Error messages appear in the Output window, and you can click on a message to view the source program at the point of the error, and then edit, save and rebuild. All the same facilities, such as Compress and Expand, are available.

3.3.6 Running the Application

To run the application without debugging:

1. Select PLIDEMO.JCL in the right-hand pane and click Run on the Debug menu.

2. Ensure that Enable PL/I debugging is not checked.

3. Click the JCL tab if it is not already selected. The name of the file you selected is shown in the Job name field.

4. Click OK.

   The application runs. The Application Output window appears and shows the job starting and running to completion.

If you use Run again, it uses the same settings as the first time; you have no opportunity to change them. If you want to change the settings, click Start Debugging on the Debug menu, as described in the next section.

3.3.7 Debugging the Application

The PL/I debugger has an extensive set of debugging facilities which enable you, for example, to step through a PL/I application, set breakpoints, and monitor and change data values.

To debug the application:

1. Ensure PLIDEMO.JCL is still selected and click Start Debugging on the Debug menu.

2. Check Enable PL/I debugging. This causes the PL/I module to be debugged.

3. Click the JCL tab if it is not already selected.

4. Make sure that the PLIDEMO.JCL file is shown in the Job name field and click OK.

   The Application Output window appears and shows the job starting. When the PL/I program is loaded, the PL/I debugger is invoked. Its title window might be displayed for a few seconds.

   Then the Disassembly and Session Control windows are displayed. Close the Disassembly window as it is not needed. You can then see the Session Control window as shown in Figure 3-1.

   
   
   Figure 3-1: PL/I Debugger - Session Control Window

5. Ensure that Thread: 1 is selected in the left-hand pane.

6. On the right-hand pane, click the plus sign.

   This expands the list, as shown in figure 3-2.

   
   
   Figure 3-2: Expanded Session Control Window

7. Double-click PLIMAIN.OBJ.

   The source file for PLIMAIN is displayed in the Source window, as shown in Figure 3-3.

   
   
   Figure 3-3: Source Window for the First Part of PLIMAIN

   The window that you see might be smaller or larger than this, but you can resize it in the usual way by dragging its borders. All the debugging operations described in the following sections start from the Source window.

   The program PLIMAIN has not been invoked at this point, so the debugging operations that are available are limited. Notice that the number of line 1 is highlighted.

   We will now invoke the program.

8. Click Run to location on the Run menu, or press L.

   The program is run to the highlighted line number. In this case, line 1 had been automatically selected as the location by the debugger, but you can select any line by single-clicking its line number. This is a convenient way to run to any line that is in the future execution path of the program.

   You will see that the whole of line 1 is now highlighted. This is how the debugger shows the line about to be executed.

3.3.8 Stepping Through the Program

To step through the program:

1. Click Step over on the Run menu, or click on the toolbar, or press O. The debugger executes the current statement and stops at the next executable statement, on line 9.

2. Repeat step 1. The debugger executes the current statement and stops at the next executable statement, on line 16.

3. Repeat step 1. The debugger executes the current statement and stops at line 17. If you look at the Application Output window you will see that START OF PLIMAIN has been written to the screen, as requested by line 16.

3.3.9 Stepping Into a Subprogram

To step into a subprogram:

1. Click line number 22 to select it.

2. Click Run to location on the Run menu or press L.

   The program stops at line 22, which calls the subprogram PLISUB. When the FETCH statement on line 21 is executed, an entry for the PLISUB.DLL component is added to the Session Control window, as shown in Figure 3-4.

   
   
   Figure 3-4: Session Control Window with PLISUB Added

   At this point, you could expand the PLISUB.DLL component and double-click PLISUB.OBJ to display its source code and set up debugging controls, but we will see the source anyway when we step into the subprogram in the next step.

3. Click Step into on the Run menu, or click on the toolbar, or press I.

   The Source window changes to show PLISUB with line 1 highlighted, as shown in Figure 3-5.

   
   
   Figure 3-5: Source Window for PLISUB

   You can now perform debugging operations on the subprogram. We will just run the subprogram and return to the main program.

4. Click Step return on the Run menu, or click on the toolbar, or press T.

   The Source window changes to show the main program PLIMAIN again, as shown in Figure 3-6. The current line might still be shown as 22, but that line has now been executed.

   
   
   Figure 3-6: Source Window for the Second Part of PLIMAIN

   If you had used Step over instead of Step into in the previous step, execution would have continued to line 23 without stopping in the subprogram.

3.3.10 Monitoring Data Values

To monitor the value of the variable LINECNT, which is a count of the number of lines read from the input file:

1. Click any instance of the variable LINECNT, such as on line 30.

2. Click Monitor expression on the Monitors menu.

   The Monitor Expression window is displayed, as shown in Figure 3-7. The Expression field is already set to LINECNT.

   
   
   Figure 3-7: Monitor Expression Window

3. Click the Popup monitor radio button.

4. Click OK.

   A Popup Monitor window is displayed, as shown in Figure 3-8.

   
   
   Figure 3-8: Popup Monitor Window

   It shows that the current value of LINECNT is 0. This window will be displayed with the Source window until we close it. We will use it to monitor how the value of this variable changes as the program proceeds.

   Another way to monitor variables is as follows.

5. Double-click a variable-name, such as LINECNT in line 30.

   The Program Monitor window is displayed, as shown in Figure 3-9.

   
   
   Figure 3-9: Program Monitor Window for One Variable

   You can monitor several variables on the Program Monitor window, whereas each Popup Monitor window is for a single variable.

6. To illustrate this, double-click the variable EOD_DATA on line 27.

   The window now contains EOD_DATA, as shown in Figure 3-10.

   
   
   Figure 3-10: Program Monitor Window for Two Variables

3.3.11 Using Breakpoints

To set a breakpoint:

1. Double-click line number 31.

   This sets a line breakpoint on this line. The line number is highlighted in red.

   Alternatively, you could use the Breakpoints menu to set this or any other type of breakpoint, or to specify conditions to control the use of the breakpoint.

2. Click Run on the Run menu, or click on the toolbar, or press R.

   The program runs to the breakpoint on line 31. On the Popup Monitor window that you setup earlier you will see that the value of LINECNT has changed from 0 to 1.

3. Again, click Run on the Run menu, or click on the toolbar, or press R.

   Nothing changes on the Source window but the program has executed one iteration of the DO WHILE loop and the value of LINECNT is now 2.

4. Again, click Run on the Run menu, or click on the toolbar, or press R.

   The value of LINECNT increases to 3.

   Next we want to run to the point where we exit from the loop.

5. Double-click line number 31 to delete the breakpoint.

   The line number reverts to normal color.

6. Click line number 42 to select it.

7. Click Run to location on the Run menu or press L.

   When the program stops on line 42, the value of LINECNT is now 50, showing that 50 lines have been read from the SYSUT1 file. You can also see in the Program Monitor window that the value of EOD_DATA is now '1', indicating that end-of-file has been reached.

   Now to complete the execution of the program:

8. Click Run on the Run menu, or click on the toolbar, or press R.

   All the debugger windows close and you can see the job ending in the Application Output window.

3.4 Before Continuing

Hide the Application Output window and close the project.

If you want to take a break before going on to the next session, you can close Mainframe Express.

Return to the Tutorials Map in the chapter Start Here for the Tutorials in your Getting Started and choose which session to go on to next, depending on your interests.