Troubleshooting Code Debug Debugging

Basic Eclipse Code Debug TSO Concepts

Programs that are to be debugged using Code Debug TSO (via Code Debug) must be designated as having the intent to debug. This is done through Code Debug in conjunction with a Code Debug TSO feature called the Multi-Batch Facility, which was introduced in Code Debug 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 Code Debug 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, Code Debug TSO checks if this program was intended to be debugged by searching the Multi-Batch requests. If a match is found, Code Debug TSO takes control and allocates Code Debug TSO files needed for execution as specified in the other tabs of the launch configuration (Scripting, Load Libraries, DDIO, Log, and Work Files).

note_icon.gifNote: 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 Code Debug session..." message.

Once the program was successfully intercepted by Code Debug TSO for debugging. Code Debug 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 Code Debug 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 Code Debug TSO, allowing the facilities of the debugger to interrogate the execution of the program. At the end of program execution, a Code Debug TSO log of the debugging session is optionally produced. The application program output is available using the Host Explorer plug-in.

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

Note

Many of the issues discussed below for batch Code Debug TSO debugging also apply to IMS MPP and DB2 SP testing because in all these cases JCL is being submitted to initiate testing and requires Code Debug 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 Code Debug TSO Batch debugging

  • The job ended before being intercepted by Code Debug. This can happen for multiple reasons with the most common listed first. The way to determine if Code Debug 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 Code Debug TSO if the job step is intercepted to be debugged by Code Debug 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 the 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 Code Debug 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 Code Debug TSO or Code Debug 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 a Code Debug 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 error 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 job Action: Determine what caused the job to fail to be executed.
      • The job is submitted in a JES class that does not get executed immediately Action: Determine what caused the job to fail to be executed.

Basic Eclipse Code Debug CICS Concepts

Debugging CICS programs via Eclipse requires less input from the user than Code Debug 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 a Code Debug 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 the 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 Code Debug CICS automatically sets a breakpoint at the entry of the program the execution of the program is interrupted by Code Debug 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 Code Debug CICS session should be terminated by highlighting the “Code Debug CICS Debug Session” thread in the Debug view and clicking the terminate icon.

Troubleshoot Code Debug CICS debugging

Defining the sockets listener errors: The majority of errors, when attempting to connect to Code Debug CICS in a CICS region, will be the result of the socket listener not being defined as described in the BMC Mainframe 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.










 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*