Debugging ISPF applications

Debugging ISPF applications presents some challenges to the user because of the way ISPF application programs are invoked. The two main challenges are as follows:
  • Providing TEST runtime options to the application.
  • Choosing a display device for your z/OS® Debugger session.
You need to provide TEST runtime options. This can be done in one of the following ways:
  • Edit the exec or panel that invokes the application and change the parameter string that is passed to the program to add the TEST runtime options.
  • Allocate a CEEOPTS DD that contains the TEST runtime options.
  • Edit the application source code to add a call to CEETEST.

    This method provides the simplest way to debug only the ISPF application subroutine that you want to debug.

You need to select a display device for your z/OS Debugger session. This can be done in one of the following ways:
  • Specify a display device by using the TEST runtime options.
    • Use the same 3270 terminal as ISPF is using. When you run your program, specify the MFI suboption of the TEST runtime option. The MFI suboption requires no additional values if you are going to use the same 3270 terminal as ISPF is using.
       TEST(ALL,*,PROMPT,MFI:*)

      PA2 refreshes the ISPF application panel and removes residual z/OS Debugger output from the emulator session. However, if z/OS Debugger sends output to the emulator session between displays of the ISPF application panels, you need to press PA2 after each ISPF panel displays.

      When you debug ISPF applications or applications that use line mode input and output, issue the SET REFRESH ON command. This command is executed and is displayed in the log output area of the Command/Log window.

    • Use a separate 3270 terminal using full-screen mode using the Terminal Interface Manager (TIM).
      When you run your program, specify the VTAM suboption of the TEST runtime option. The VTAM suboption requires that you specify your user ID, as in the following example:
      TEST(ALL,*,PROMPT,VTAM%user_id:*)
    • Use a separate 3270 terminal using full-screen mode using a dedicated terminal without Terminal Interface Manager.
      When you run your program, specify the MFI suboption of the TEST runtime option. The MFI suboption requires that you specify the VTAM® LU name of the separate terminal that you started, as in the following example:
      TEST(ALL,*,PROMPT,MFI%terminal_id:*)
    • Use remote debug mode and a remote IDE.
      When you run your program, specify the TCPIP suboption of the TEST runtime option. The TCPIP suboption requires that you specify the TCP/IP address of your workstation, as in the following example:
       TEST(ALL,*,PROMPT,TCPIP&tcpip_id%8001:*)

      The 2nd, 3rd, and 4th options above support debugging a batch ISPF program.

  • Specify a display device via a call to CEETEST.
    The 1st parameter to CEETEST test is a 'command string' where the first command in the string can be one of the following ones:
    • A null command. In this case, z/OS Debugger will use the same display as ISPF is using.
       ;
    • A parameter that indicates you want to use full-screen mode using the Terminal Interface Manager (TIM) and the ID you logged on to TIM with.
      VTAM%USERIBM:*;
    • A parameter that indicates that you want to use remote debug mode and provides the TCP/IP address of the workstation.
      TCPIP&9.51.66.92%8001:*;

    The 2nd and 3rd options above support debugging a batch ISPF program.

Here is an example of using CEETEST in a COBOL program to provide both the TEST runtime options and the display device information.

This declaration in the DATA DIVISION indicates using the same 3270 terminal that ISPF is using.

01 COMMAND-STRING.
      05 AA PIC 99 Value 1 USAGE IS COMPUTATIONAL.
      05 BB PIC x(60) Value ';'.

This declaration in the DATA DIVISION indicates using full-screen mode using the Terminal Interface Manager.

01 COMMAND-STRING.
      05 AA PIC 99 Value 14 USAGE IS COMPUTATIONAL.
      05 BB PIC x(60) Value 'VTAM%USERIBM:*;'.

This declaration in the DATA DIVISION indicates using remote debug mode.

 01 COMMAND-STRING.
      05 AA PIC 99 Value 24 USAGE IS COMPUTATIONAL.
      05 BB PIC x(60) Value 'TCPIP&9.51.66.92%8001:*;'.

The 2nd and 3rd options above are needed if you are debugging a batch ISPF program.

These are the declarations needed in the DATA DIVISION for the 2nd parameter to CEETEST.

01 FC.
      02 CONDITION-TOKEN-VALUE.
         COPY CEEIGZCT.
             03 CASE-1-CONDITION-ID.
                04 SEVERITY PIC S9(4) BINARY.
                04 MSG-NO PIC S9(4) BINARY.
             03 CASE-2-CONDITION-ID
                      REDEFINES CASE-1-CONDITION-ID.
                04 CLASS-CODE PIC S9(4) BINARY.
                04 CAUSE-CODE PIC S9(4) BINARY.
             03 CASE-SEV-CTL PIC X.
             03 FACILITY-ID PIC XXX.
      02 I-S-INFO PIC S9(9) BINARY.

Here is the call to CEETEST that goes in the PROCEDURE DIVISION.

 CALL "CEETEST" USING COMMAND-STRING FC.