Creating a function debug session

A function debug session is started when a function that is listed in the session is called. You can create debug sessions only for external functions. Create a function debug session in the Debug Session view.

1. Take one of the following actions to open the Add Function Debug Session window:
   • In the Debug Session view, expand the Add Debug Session Menu icon, and select Add Function Debug Session.
   • Right-click anywhere in the Debug Session view, and click Add Debug Session Menu > Add Function 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 Function Name field, enter the name of the function that you want the z/TPF debugger to trace.
   You also can use a class name to locate a class member function, with two colons (::) between the class name and the function name:

   classname::functionname

   Notes:

   • You can use an asterisk (*) at the end of the function name to specify a group of function names that start with the same string. If you want to match single overloaded function names, you must specify the complete mangled name.
   • You can use asterisks (*) to specify class member functions, for example:
     • You can register all class member functions for a group of classes by specifying IVA*::*.
     • You can register all of the get functions, such as the getpid and getenv functions, for a group of classes by specifying IVA*::get*.
   • You can specify mangled names with or without using an asterisk (*).
   • You can specify demangled names with or without an asterisk (*). However, parameters cannot be specified.
   • The debugger does not capture functions that are defined by using the TMSPC and PRLGC general macros if the functions are built with fast linkage. If a function is built with fast linkage, it is built without function hooks.
   • Real-time assembler entry point names are not valid. To capture real-time basic assemble language (BAL) programs, create a program 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. But the asterisk in the module name might impact performance or even cause a 000010 system error.
6. Optional: In the Object Name field, enter the name of the object.
   Notes:

   • 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.
   • If the function that you specified at step 4 exists in the compiler generated portion of a module, do not specify the object name, or specify an asterisk (*) for the object name. A typical example is when the function is declared and defined in a header file.
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: 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'.

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