Creating a system error debug session

A system error debug session is started when the specified system error occurs. Create a system error debug session in the Debug Session view.

1. Take one of the following actions to open the Add Error Number Debug Session window:
   • In the Debug Session view, expand the Add Debug Session Menu icon, and select Add Error Debug Session.
   • Right-click anywhere in the Debug Session view, and click Add Debug Session Menu > Add Error 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 System Error Number field, enter the 6-character hexadecimal system error number that you want the z/TPF debugger to trace.
   If you specify a string that has fewer than six hexadecimal characters, the string is automatically padded with zeros to the left side.

   Notes:

   • You can specify only one system error number for each debug session.
   • Only the system error number is needed. The system error prefix is not valid.
   • You cannot use an asterisk (*) to specify a system error number.
   • Memory dumps that occur from a debugger ECB or a debugged application ECB do not start a system error debug session.
5. Optional: In the Module Name field, enter the name of the module.
   Note: You can use an asterisk (*) at the end of the module name to specify a group of module names that start with the same string.
6. Optional: In the Object Name field, enter the name of the object.
   Note: You can use an asterisk (*) at the end of the object name to specify a group of object names that start with the same string.
7. 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.
8. 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.
9. 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.

10. 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

    Specifies 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.

    

    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.

11. 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.
12. Click Finish.