Troubleshooting Xpediter/Eclipse Debugging

Basic Eclipse Xpediter/TSO Concepts

Programs that are to be debugged using Xpediter/TSO (via Xpediter/Eclipse) must be designated as having the intent to debug. This is done through Xpediter/Eclipse in conjunction with an Xpediter/TSO feature called the Multi-Batch Facility, which was introduced in Xpediter/TSO release 7.6.

In the case of a batch job, the job name, job step, and program name of the program must be specified in order to debug. These fields are indicated in the Matching Criteria section of the Target tab of the Xpediter/Eclipse launch configuration. When the user clicks the Debug icon on the specific launch configuration, a Multi-Batch request is automatically written to the mainframe Multi-Batch staging file. If the record is written successfully, then the JCL specified in the Batch Job Location of the launch configuration is submitted to the mainframe. Thus, once the job begins execution, Xpediter/TSO checks if this program was intended to be debugged by searching the Multi-Batch requests. If a match is found, Xpediter/TSO takes control and allocates Xpediter/TSO files needed for execution as specified in the other tabs of the launch configuration (Scripting, Load Libraries, DDIO, Log, and Work Files).

Note: If there is a multi-batch request from ISPF in the file that matches the specified user ID, job name, step name, and program name, the multi-batch request from ISPF takes precedence. An example indication of this condition is a repetitive "Waiting for Xpediter debug session..." message.

Once the program was successfully intercepted by Xpediter/TSO for debugging. Xpediter/TSO displays the program source (if available) from the Source Listing File(s) specified in the DDIO tab of the launch configuration and gives control to the application program. Because Xpediter/TSO automatically sets a breakpoint at the entry of the program, and optionally at the exit of the program, the execution of the program is interrupted by Xpediter/TSO, allowing the facilities of the debugger to interrogate the execution of the program. At the end of program execution, an Xpediter/TSO log of the debugging session is optionally produced. The application program output is available using the Compuware Host Explorer plug-in.

The following are some reasons the debugging session may not be successful. These issues are discussed separately for Xpediter/TSO batch debugging and Xpediter/TSO foreground debugging.

Note

Many of the issues discussed below for batch Xpediter/TSO debugging also apply to IMS MPP and DB2 SP testing because in all these cases JCL is being submitted to initiate testing and require Xpediter/TSO to intercept the JCL. In the sections below for IMS MPP and DB2 SP only unique issues to these environments are discussed. Issues such as JCL errors are not discussed redundantly.

Troubleshoot Xpediter/TSO Batch debugging

The job ended before being intercepted by Xpediter. This can happen for multiple reasons with the most common listed first. The way to determine if Xpediter/TSO intercepted the JCL is to scan the job SYSOUT looking for the presence of an XTASKLIB DD statement. This statement is dynamically inserted in the job by Xpediter/TSO if the job step is intercepted to be debugged by Xpediter/TSO. If this DD statement is not present than the job step was not intercepted and it could be for one of the following reasons:
- - The filter masks specified in the Eclipse launch configuration do not match jobname, step name, and program name in the submitted JC These launch configuration masks indicate what job name, job step, and program name should be intercepted by Xpediter/TSO. If they are not correct, the job step will not be intercepted and the above message will be displayed. Action: Please validate that the “Matching Criteria” as specified in the Target tab of the launch configuration matches the JCL you submitted.
  - When running Xpediter/TSO or Xpediter/CICS prior to release 3, the job ran on another LPAR than the Multi-Batch record was written to. This can happen if multiple LPARs are sharing JES queues and the submitted JCL was routed to an LPAR that did not contain an Xpediter/TSO intercept record for this job. Action: Please verify that the job ran in the MVS LPAR that contains the Multi-Batch staging file. You can tell what z/OS system (LPAR) the Multi-Batch request was written to by looking at the “z/OS System” field of the “Target System” of the launch configuration. You can then look at your job output (SYSOUT) and look at the $HASP373 message (JES2). This message indicates what LPAR the job ran on and it must match the system specified in the “z/OS System” field of the “Target System” of the launch configuration.
  - JCL erro The submitted JCL contains a JCL error. Action: Correct the JCL error and resubmit the JCL.
The submitted JCL program is not executing. This situation may arise do to any of the following conditions:
- - The job is waiting behind one or more jobs in the JES queu Action: Determine what caused the job to fail to be executed.
  - The JES initiator is not active for the job class specified for this jo Action: Determine what caused the job to fail to be executed.
  - The job is submitted in a JES class that does not get executed immediatel Action: Determine what caused the job to fail to be executed.

Basic Eclipse Xpediter/CICS Concepts

Debugging CICS programs via Eclipse requires less input from the user than Xpediter/TSO debugging. This is because all the files required by CICS application programs must be pre-defined in the CICS region. To begin, the Eclipse user creates an Xpediter/CICS Debug Session launch configuration giving it a name of their choosing. The only required fields are the Load Module name in the Program to Debug section (CSECT defaults to load module name if not supplied) and the HCI Connection and CICS Region in the Target Region section. The user then clicks on the Debug icon and Eclipse attempts to connect to the requested CICS region and retrieve the source for the program indicated in the Load Module and CSECT fields. Once source is displayed execution of the program begins when the user enters the CICS transaction ID that corresponds to the program being tested. The transaction may be entered at a 3270 terminal or any other CICS supported input device external to Eclipse. Because Xpediter/CICS automatically sets a breakpoint at the entry of the program the execution of the program is interrupted by Xpediter/CICS and the user is able to use the facilities of the debugger to interrogate the execution of the program. The transaction may be run as many times as necessary to debug the program without re-launching the configuration. When the user has completed testing, the Xpediter/CICS session should be terminated by highlighting the “Xpediter/CICS Debug Session” thread in the Debug view and clicking the terminate icon.

Troubleshoot Xpediter/CICS debugging

Defining the sockets listener errors: The majority of errors, when attempting to connect to Xpediter/CICS in a CICS region, will be the result of the sockets listener not being defined as described in the Compuware Mainframe Eclipse Installation Guide. Every attempt has been made to provide specific diagnostic runtime messages so in the event of a connection error detailed information will be available to correct the error in a timely manner. Action: These errors will require the system installer to make corrections to the sockets listener definition and then stop/start the listener in the CICS region.