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:
- 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:
- Start Micro Focus Rumba and create a new mainframe display.
- Choose
. The Connection Configuration dialog box appears.
- In the General tab, select TN3270 in the
Installed Interfaces list, then click the
TN3270 tab.
- 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.
- Under
Telnet Port, click the
User Defined button and type
5150 as the port number. Click
OK to save your changes.
- Choose
. The Signon to CICS screen appears in the mainframe display.
Logging in and starting the application in CodeWatch Debugger
- 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.
- Press
Enter.
- 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.
- 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.
- Click
, 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.
- In the Rumba Mainframe Display window, type
WILLIAMS in the
Name field and press
Enter.
- 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
.
- Click
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.
- 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.
- 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.
- 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.
- 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.
- Press
F10 several times until you step to the line that reads:
EXEC CICS XCTL PROGRAM ('STAFF03')
This line calls the program
STAFF03.
- 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
- 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.
- Click
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.
- 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.
- Press
F10 twice to step to the line that reads:
IF RC ^= DFHRESP(NORMAL) THEN
- 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.
- 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.
- 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.
- Press
or
F11 to step into
STAFF04.
- Scroll to line 282 that reads:
CALL PROCESS_DATA();
- Double-click in the left margin next to the line number to set a breakpoint at this line. Then click
to stop program execution at the line where you set the breakpoint.
-
Press
or
F11 to step into the
PROCESS_DATA procedure
- Press
or
F11 to step into the
READ RECORD procedure.
- 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
- In the CodeWatch window, click
File > Quit.
- Click
Yes to confirm and exit CodeWatch.