Debug the Application

This part of the CICS tutorial shows how to use the Java CodeWatch debugger to walk through an employee directory PL/I sample application. It explains pertinent parts of the application and debugger functionality.

Before you start debugging, connect to the enterprise server using a TN3270 emulator such as Micro Focus Rumba. Note that the instructions for setting up a connection or clearing the screen might be different if you are using an emulator other than Micro Focus Rumba.

If you installed Rumba as part of Enterprise Developer, you can also use the embedded Rumba mainframe display from within the IDE.

Starting the terminal emulator and configuring the connection

To open the embedded Rumba mainframe display:

  1. Right-click the CICS project in Solution Explorer, and click Enterprise Server > Mainframe TN3270 Display.

    This starts the Mainframe TN3270 Display window inside the IDE. You can reposition or resize the window, if needed.

    The display automatically connects to the STAFF enterprise server at the specified TN3270 port. You should see the Signon to CICS screen.

If you are using the standalone Rumba Desktop application, you need to connect it to the server as follows:

  1. Start Micro Focus Rumba and create a new mainframe display.
  2. Choose Connection > Configure. The Connection Configuration dialog box appears.
  3. In the General tab, select TN3270 in the Installed Interfaces list, then click the TN3270 tab.
  4. Click Insert to create a host destination name, then type your local machine IP address in the Destination Name/Address field and click OK.
    Note: In some configurations, localhost can also be used as the host destination name. On versions of Windows Vista and later, if you experience issues connecting to localhost, connect to 127.0.0.1 instead.
  5. Under Telnet Port, click the User Defined button and type 5150 as the port number. Click OK to save your changes.
  6. Choose Connection > Connect. The Signon to CICS screen appears in the mainframe display.

Logging in and starting the application in CodeWatch Debugger

  1. To log in, type a user ID and password. These would typically be SYSAD and SYSAD. Press the Tab key to move from the ID field to the Password field.
  2. Press Enter.
  3. Press Ctrl+Shift+Z to clear the screen if using Rumba. If using a different terminal emulator, follow instructions for that emulator to clear its screen.
  4. Type TTEA and press Enter to start the sample application.

    The CodeWatch debugger window appears. The debugger displays the STAFF02 program and moves to the initial line of the program code. A Java CodeWatch terminal log window also appears. Both windows might be minimized to the task bar.

  5. Click GUID-C4997AD0-7586-4F90-84E8-28CDB1DE9D17-low.jpg, or press Shift+F5 to exit CodeWatch and return to the Rumba mainframe display window. This exits the program to allow you to enter data to be used by the program.

    For this tutorial, you enter a last name for a staff customer to step through the use of that data in CodeWatch.

  6. In the Rumba Mainframe Display window, type WILLIAMS in the Name field and press Enter.
  7. The CodeWatch debugger window reappears - check the task bar as the window might be minimized. The debugger displays the STAFF02 program and moves to the initial line of the program code. The Java CodeWatch terminal log window and a Java execution window also reappear.

Stepping through the CICS mapset in the STAFF02 program

The code for the STAFF02 program receives data from the CICS mapset. This part of the tutorial steps through to where data is received from the mapset.

Note: By default the CodeWatch debugger shows the line numbers - see View > Show Line Numbers.
  1. Click GUID-D033A7CA-2983-4C21-A28E-32ED88BC3423-low.jpg or press F10 several times until you step to the line that shows the following:
    EXEC CICS RECEIVE MAPSET('OCMCS')

    This line indicates that the program receives data from the CICS mapset.

  2. Press F10. The debugger steps to this line.
    IF RC ^= DFHRESP(NORMAL) THEN

    Right-click the text RC and choose View contents of 'RC'. RC=0{fixed binary(31)} displays in a message box, indicating the mapset was successfully retrieved. Click Ok to close the message box.

  3. Press F10 several times until you step to the line that reads:
    IF NAMEDI = (45) '00'x THEN

    Right-click the text NAMEDI and choose View contents of 'NAMEDI'. The text S0934I.NAMEDI = WILLIAMS '{character (45)} displays in a message box. This indicates that the name that you entered was successfully retrieved. Click Ok to close the message box.

  4. Press F10 several times until you reach the line that reads:
    EXEC CICS WRITEQ

    This line writes the processed input data (WILLIAMS) to CICS temporary storage.

  5. Press F10 to step to the next line that reads:
    IF RC ^= DFHRESP(NORMAL) THEN

    Right-click the text RC and choose View contents of 'RC'. RC=0{fixed binary(31)} displays in a message box, which in this instance indicates that the program has successfully written the processed input data to a CICS temporary data queue. Click Ok to close the message box.

  6. Press F10 several times until you step to the line that reads:
    EXEC CICS XCTL PROGRAM ('STAFF03')

    This line calls the program STAFF03.

  7. Press F10 a few more times to step into STAFF03. The CodeWatch debugger window closes down when STAFF02 ends and then, when STAFF03 starts, it reappears and highlights the initial line of STAFF03. You might need to select the window from the task bar.

Stepping through the CICS mapset in the STAFF03 program

  1. Press F10 several times until you step from the start of the program to the line that reads:
    CALL READ_QUEUE;
    This line calls a PL/I subroutine which then reads the temporary queue.
  2. Click GUID-197CB38E-E980-41B5-BA93-254BAC623686-low.gif or press F11 to step into the procedure. This steps to the line that reads:
    READ_QUEUE: PROC;

    This line starts a procedure to read the queue where the processed input data (WILLIAMS) is stored.

  3. While still on this line, right-click the text DDP_STRUCA five lines below the current line and choose View contents of 'DDP_STRUCA'. Notice in the message box that DPP_STRUCA.MENU_DATA.NAME.LAST_NAME entry does not contain WILLIAMS. Click Ok to close the message box.
  4. Press F10 twice to step to the line that reads:
    IF RC ^= DFHRESP(NORMAL) THEN
  5. Right-click the text RC and choose View contents of 'RC'. The message box displays: RC=0{fixed binary(31)}. Click Ok to close the message box.
  6. A few lines above the current line is a line that reads:
    Into (DPP_STRUCA)

    Move the cursor back over and right-click the text DDP_STRUCA on that line and choose View contents of 'DDP_STRUCA'. The record in the tooltip now contains WILLIAMS in the DPP_STRUCA.MENU_DATA.NAME.LAST_NAME entry. Click OK to close the message box.

  7. Press F10 to continue stepping until you return from the procedure and are on the line that calls the STAFF04 program:
    CALL STAFF04(DFHEIPTR, Q_NAME);

    This line reads the file to determine if WILLIAMS is present.

  8. Press GUID-197CB38E-E980-41B5-BA93-254BAC623686-low.gif or F11 to step into STAFF04.
  9. Scroll to line 282 that reads:
    CALL PROCESS_DATA();
  10. Double-click in the left margin next to the line number to set a breakpoint at this line. Then click GUID-C4997AD0-7586-4F90-84E8-28CDB1DE9D17-low.jpg to stop program execution at the line where you set the breakpoint.
  11. Press GUID-197CB38E-E980-41B5-BA93-254BAC623686-low.gif or F11 to step into the PROCESS_DATA procedure

  12. Press GUID-197CB38E-E980-41B5-BA93-254BAC623686-low.gif or F11 to step into the READ RECORD procedure.
  13. If you continue stepping, you will see that as you keep reading records, none of them match on WILLIAMS.

You can repeat the steps above using a different last name. You can type for example CH in the last name field and you will see valid records being found in the PROCESS_DATA procedure.

You can also use the debugger's Go to line function to skip the code matching on the last name and thus make it behave as though it found a matching record and cause it to be displayed. You can access the Go to line function from the context menu when you right-click the line you want.

Stop debugging the application

  1. In the CodeWatch window, click File > Quit.
  2. Click Yes to confirm and exit CodeWatch.