Creating a program debug session

A program debug session is started when a registered program is run. Create a program debug session in the Debug Session view.

About this task

The Debug Session view is a default view in the TPF Development perspective. If you close this view, click Window > Show View > Other > TPF > Debug Session to open this view again.

Procedure

  1. Take one of the following actions to open the Add Program Debug Session window:
    • In the Debug Session view, click the Add Debug Session Menu icon.
    • In the Debug Session view, expand the Add Debug Session Menu icon, and select Add Program Debug Session.
    • Right-click anywhere in the Debug Session view, and click Add Debug Session Menu > Add Program Debug Session.
  2. In the Session Name field, specify a name for the new debug session.
  3. Optional: To narrow the scope of debugging to a particular terminal, complete the following steps:
    1. Select the Filter by terminal checkbox.
      The Terminal field is enabled.
    2. In the Terminal field, specify the terminal by using one of the following terminal protocols:
      • IP address
      • Line number, interchange address, and terminal address (LNIATA)
    For more information about tracing by terminal, see Setting up LNIATAs.
  4. In the Program Name field, enter the name of a program that you want the z/TPF debugger to trace, and click Add to add the program to the program list.
    Notes:
    • You can specify multiple programs to be traced, but the debugger traps only the first program that is loaded. After a debug session is running, you can trap other programs in the list by setting load breakpoints to stop when each of those programs is loaded.
    • To remove a program from the list, select the program, and click Remove.
    • You can use an asterisk (*) at the end of the program name to specify a group of program names that start with the same string.
  5. Optional: To enable parent and child debugging, select the Trace created entries checkbox. If this checkbox is selected, when the traced ECB is about to create a child ECB by calling a supported macro or function, the z/TPF debugger stops the application program, and the ECB Create Event window is displayed for you to specify whether to trace the parent ECB, child ECB, or both.
  6. If the Trace created entries checkbox is selected, you can select or clear the Exclude common system services created ECBs checkbox:
    • If the Exclude common system services created ECBs checkbox is selected, which is the default setting, the z/TPF debugger does not stop the application program, and the ECB Create Event window is not displayed when a child ECB is created from a common system service call.
      Note: If Parent and child ECB debugging enhancement (APAR PJ46530) is not applied to your z/TPF system, the selection of the Exclude common system services created ECBs checkbox does not take effect.
    • If the Exclude common system services created ECBs checkbox is cleared, the z/TPF debugger stops the application program, and the ECB Create Event window is displayed even when a child ECB is created from a common system service call.
  7. If a user exit on the z/TPF system is required, enter a text string in the User token field to be passed to a custom z/TPF user exit program.

    If a user token is specified on the TPF Debug preference page, this field is filled with the user token string that is specified on the preference page. You can enter a different string to override the default value.

    For more information about the user exit, see Managing registration tasks on your production system.

  8. Optional: In the Advanced options area, modify the advanced options:
    Workstation name
    Specifies the name of the workstation for the debug session to be started on. If an asterisk (*) is specified, your current workstation is used to start the debug session.

    This field is filled with the same workstation name that is specified on the TPF Debug preference page. Although you can enter a different workstation name to override the default value, ensure that the workstation name is consistent with the TPF Debug preference page. The z/TPF registration monitor, if enabled, queries the z/TPF system debug registration tables by using the workstation name that is specified on the TPF Debug preference page. If a different workstation name is specified for the debug session, the monitor cannot find the debug session in the debug registration tables and will remove it from the TPF System view.

    Workstation address
    Start of changeSpecifies the IP address of the workstation for the debug session to be started on.

    Asterisks are supported in this field. You can specify a single asterisk, or an asterisk in any address octet such as 9.*.*.*. If you specify a single asterisk in this field, TPF Toolkit uses the first IPv4 address that is found.

    This field is enabled when one of the following conditions occurs on the TPF Debug preference page:
    • The z/TPF registration monitor is disabled.
    • The z/TPF registration monitor is enabled but the Automatically update workstation IP address checkbox is not selected.

    If you specify an IP address in this field, the workstation IP address in the registration entry on the z/TPF system remains static, which is useful in some scenarios.

    End of change
    Trace global variable initialization functions.
    By default, this checkbox is cleared. If you want to debug global variable initialization functions in your C/C++ modules on the z/TPF system, select this checkbox.
    Check time stamps when retrieving remote debug information
    This checkbox toggles whether time stamps are checked when automatic load support for remote debug information is used to retrieve debug information files from Linux® on IBM Z® to the z/TPF system:
    • If the checkbox is selected, which is the default setting, the debug information file to be retrieved must have the same time stamp as the shared object.
    • If the checkbox is cleared, the debug information file with the latest time stamp is retrieved.
  9. Optional: In the Conditional registration area, specify an additional condition to trap your programs for debugging:
    1. In the ECB field or register to compare field, enter the ECB field or the register that contains the content that you want to use for the condition, for example, EBW000 or R1.
    2. From the Condition list, select the operator that you want to use for comparison.
    3. In the Value to compare field, specify the value that you want to use for comparison.
      You can specify the value in the hexadecimal, decimal, or character format.
    4. If you do not want to use the entire content of the specified ECB field or register for comparison, complete the following steps to specify the number of bytes in the ECB field or register that you want to compare:
      1. Select the Limit comparison checkbox.
      2. In the Number of bytes to compare field, enter a number in the range of 1 - 255.

        You also can specify the number of bytes to compare. For example, EBW fields are 1 byte long. However, to compare EBW000 = 'D' and EBW001 = 'B, you must specify a length of 2 to compare both bytes, for example, EBW000 (limit comparison = 2) == c'DB'.

  10. Optional: If you want to register the debug session at this stage, complete the following steps:
    1. Click Next.
      All of the defined z/TPF systems are displayed in the Available systems list.
    2. Add one or more z/TPF systems to the Systems to register list.
  11. Click Finish.

Results

The new debug session is added to the Debug Session view.

If you performed step 10 and the registration is successful, the debug session is displayed under the selected z/TPF systems in the TPF System view, and the output is printed to the Console view.

What to do next

If you did not perform step 10, you can register the created debug session later. For more information, see Register the debug session with a z/TPF system.