Using the Incoming Remote Debug Session configuration

Debug configurations are used for saving the settings that are used when a debug session launches. The Incoming Remote Debug Session configuration saves the launch settings that are used when an incoming application connects to the debugger user interface through the debug daemon. The Incoming Remote Debug Session configuration cannot be used for directly launching debug sessions from the debugger user interface.

About this task

Settings, such as breakpoints, are saved upon termination of a debug session. However, these settings are not saved by launch configuration. Therefore, if you create more than one launch configuration for the same application, settings such as breakpoints will be the same for each launch configuration. The advantage to creating more than one launch configuration for the same application, is that you can set different arguments as parameters to the program in the launch configurations and you can have different sets of Debug Console commands when launching debug sessions.

When you connect to the debugger user interface by launching a JCL that connects to the user interface debug daemon, an Incoming Remote Debug Session configuration is automatically created for the program that you are debugging. Subsequent launches of the same program will reuse this configuration. You can create multiple configurations for the same program - for example, you can copy a configuration and then modify the copy. If you have multiple configurations for the same program and you launch that program for debug, you will be prompted by a dialog box to choose the configuration that you want to use for launching the debug session.

To create a Incoming Remote Debug Session configuration, complete these steps:

Procedure

  1. In a workbench perspective that offers the set of debug-related action (such as the Debug perspective), perform one of the following tasks:
    • Select Run > Debug from the workbench menu bar to open the Debug launch configurations dialog box.
    • Click the down arrow next to the workbench toolbar Debug push button and choose Debug from the list. This will open the Debug launch configurations dialog box.
  2. In the Debug launch configurations dialog box, perform one of the following tasks:
    • Right-click the Incoming Remote Debug Session node and select New from the pop-up menu.
    • Double-click the Compiled Application node.
  3. This will cause the launch configuration tabs and entry fields to display on the right-hand side of the dialog box.
  4. In the Name field, enter a name of your choice for the configuration that you are creating.
  5. Select the Program tab to bring it to the foreground.
  6. Enter the name of the program that you want to debug in the Program name field. Completion of this field is mandatory.
  7. Select the Debug initialization check box to debug code that executes before the main program entry point is called. You might want to do this if you are debugging C++ code and you need to debug the constructors for your globally-declared C++ class objects (because such objects are constructed before main is entered). If the check box is cleared, the program will run to the main entry point.
  8. To set the Source Lookup Path, select the Source tab and perform any of these tasks:
    • To add a source location, click Add. This will invoke the Add Source dialog box, in which you can select the type of source location to add. From the selection list in the Add Source dialog box:
      • Choosing Workspace will cause all projects in your workspace to be added to the source location list.
      • Choosing File System Directory will add a local file system directory to the source location list. If desired, subdirectories of this directory will be recursively searched if you select the Search subfolders check box.
      • Choosing Project open a dialog which allows you to select a project in your workspace. From the list of projects, you can choose one or more projects to add to the source location list.
      • Choosing Debug engine will cause the debug engine to be added to the source location list.
      • Choosing Debug engine path will cause the path specified on the debug engine to be added to the source location list. When specifying multiple paths, the path separator varies by platform (on IBM Z®, use a semi-colon (;) as the path separator).
        Note: Changes to the Debug engine path setting will take effect in subsequent debug sessions.
      Additional source container types may be available, depending on the product that you are using.
    • To remove an existing entry, select a source location and click Remove.
    • To set the order of existing entries, select a source location and click Up or Down to alter that location's placement.
      Note: In some cases, changing the placement of a location might not take effect until the next time the program is launched.

    If you want to search for all instances of the source file name in the source search path, select the Search for duplicate source files on the path check box. If you select this check box and the debugger finds multiple instances of the file name, you will be prompted by a dialog box to choose the correct source file.

  9. Select the Debug Console Commands tab to bring it to the foreground. This tab is used for adding commands to be issued to the debug engine when the debug session starts. You can add, remove, and modify these commands using the push buttons in the page - or you can import commands from a command list text file. Command list files contain lists of commands that are separated by new line (carriage return/line feed). Command list files can contain comments which will not be imported into the command list. Comment lines begin with a # character.
  10. Select the Common tab to bring it to the foreground. You can perform any of these tasks in the Common page:
    • If you want the launch configuration to be stored locally and available for a single user, ensure that the Local radio button is selected. If the launch configuration is to be stored as a file in the workspace and shared in a repository for team use, select the Shared file radio button and enter the project location where you want the launch configuration to be stored in the text field next to Shared file. Alternatively, you can browse for the project.
    • If you want the launch configuration to be displayed as a favorite debug configuration in the Debug push button favorites menu or the Debug menu Debug History list, select the Debug check box.
  11. If all information mandatory to the launch configuration has been provided, the Debug and Apply push buttons will be enabled. Clicking Apply will save the launch configuration, at which point you can choose to close the dialog box without launching the debug session or you can click Debug to launch a debug session using the new launch configuration. If you click Debug, any changes to the launch configuration will be saved and a debug session will be launched.

    After you have saved a debug launch configuration, you can edit it. For further information about editing debug launch configurations, see the related task.

    Tip: If you have not yet saved launch configuration settings and if you have made entries in the launch configuration settings that you want to remove or change, clicking Revert will remove all changes that you have made.
  12. If information mandatory to the launch configuration has not been provided or if there are errors in the information that you have provided, messages at the top of the dialog box will indicate what is missing.
  13. If you did not use the dialog box to launch a debug session (for example, you used it instead to create and save a launch configuration), click Close to exit the dialog box when you are finished working in it.

Results