Unfortunately the z/TPF debugger, Performance Analyzer, Code Coverage Tool and so on cannot find and solve your code bugs. However, the z/TPF debugger and associated tools can help you locate and identify your code bugs. The key is to understand what features are available and to creatively use them together to diagnose your code bugs. How do you learn about the features of the debugger and associated tools?
Documentation is available at http://www-01.ibm.com/software/htp/tpf/. See the Fast links section on the lower left side for the following information:
TPFUG presentations – A debugger and TPF Toolkit update is often provided at each TPFUG to announce new features, provide education and so on. These presentations are usually given in the TPF Toolkit Task Force or the Development Tools Subcommittee.
Tools -> z/TPF Debugger ->Debugger for z/TPF Demo Movie – This demo movie was created several years ago to highlight the function that was available at that time. Even though this movie is out of date, the education delivered in this format has been found to be very useful and the core function described continues to exist today.
TPF Family Libraries -> Open Current Information Center -> z/TPF PUT -> Library -> Debugger User’s Guide – The Debugger User's Guide describes the essence of using the debugger and is a good source for what function is currently available.
Tools -> z/TPF Debugger ->z/TPF Redbook - z/TPF Application Modernization using Standard and Open Middleware Redbook. See appendices A-D for an in depth step by step discussion for using the TPF Toolkit, Debugger, Code Coverage Tool, and so on. This may be a good resource if you are new to the toolset.
Tools -> z/TPF Debugger - The practical education articles, of which this article is part, provide explanations of how to use various debugger features to address debugging situations.
Tools -> z/TPF Debugger - The developerworks Custom Communications Packages article provides an explanation of how to administer customer communication packages to address debugging situations.
The TPF Toolkit help that is found in the Help menu also provides information regarding the features that are available. Select the Help menu -> Help contents. Then select Debugging TPF Applications, Analyzing Code Coverage of TPF Applications, or Analyzing Performance of TPF Applications.
This set of documentation.
Experimentation – Experimenting with the tool is one of the best ways to understand how the tool works.
Ask IBM – You can open a PMR to ask your question or send an email to firstname.lastname@example.org with your question. If your question is involved enough or you have a large number of questions, ask to have conference call with the experts to get your questions answered.
The purpose of this documentation is to augment the information currently available in the Debugger User's Guide and TPF Toolkit help documents by describing the ways in which the debugger and associated tools can be used to solve problems. The approach of this documentation is to examine different situations and come up with ideas about how to use different features of the debugger to diagnose the problem.
User Defined Debugger Summary view / TPF Debugger File view / ECB trace / In Debug Console ECBHeap section, added reference to Trace Log
Hints and Tips
This article discusses some hints, tips, and little known features in a situational format. That is, why, when and how would you use these hints and tips. We will explore the following:
Compiler and assembler options
Program attribute table (PAT) debug setting
Custom ECB summary view / User defined debugger summary view
TPF Debugger File View
Changing condition codes and seeing instruction details
Seeing stack contents
ZDBUG ACCESS command
Debugger dumps and what to do
Compiler and assembler options
The z/TPF debugger can be used to debug optimized or non-optimized code. Debugging non-optimized code will provide the best debugging experience as variables will not be optimized out, loops will not be unrolled, instructions will not be intermixed for pipelining and so on. Many of these optimizations cause the debugger to jump around sporadically from source line to source line when you are stepping. To build your code in non-optimized, use the compile options:
CFLAGS_USER := -O0
CXXFLAGS_USER := -O0
However, you may want to start out debugging your application optimized. For example, suppose your application is composed of 100 C shared objects (CSOs). Building and loading the application might be a significant undertaking. Instead, use the trace log tool, code coverage tool or debugger to understand the path of your application as described in the Determining code path article. Once you have narrowed down where the problem is, rebuild a subset of modules non-optimized and debug in greater depth.
The High Level Assembler (HLASM) built basic assembler language shared objects (BSOs) must be built with the ADATA option to have debug information available. The assembler debug information tells the debugger how to interpret DSECTs, macros and so on. To build your code with debug information for assembler use the assembler option.
ASMFLAGS_USER := ADATA
The GCC compiler provides multiple leves of debug information. By default, the maketpf utility uses the -g2 level of debug information. However, there might be cases where you need to debug C/C++ macros. In these instances, use the -g3 compile option for more debug information. The trade off is that the size of your shared object will be significantly larger. To build your code with debug information for GCC use the compiler option.
CFLAGS_USER := -g3
CXXFLAGS_USER := -g3
It is advisable to always build your application with the debug information options regardless of optimization or other levels. The debug information can be stripped out by loadtpf options, the debug load card, ZOLDR LOAD NODEBUG option, ZTPLD NODEBUG option, and so on. In this way, the code loaded to the system will not have debug information and won't require the additional disk space on the z/TPF system. However, when you need to debug at a later time, the module with debug information will be available to load or FTP to the system. See debug information section below.
The final compiler and assembler option that is available is the XMLGEN option. This option will generate XML files for the assembler macros, C/C++ structs, and C/C++ class objects. These XML files can be used in the memory view to map the content of memory and provide a formatted view your data. To use the XMLGEN option, simply specify it
ASMFLAGS_USER := ADATA XMLGEN
CFLAGS_USER := -O0 XMLGEN
CXXFLAGS_USER := -O0 XMLGEN
The XML files will be placed in the base/xml directory of your build root directory. Do the following to use an XML file against your application data:
Open the memory view at the address you want to map. NOTE: A tip in the memory view is to click the green plus sign and then click OK without filling in an expression. The address opened will be the address of the entry control block (ECB) that you are debugging.
Click new rendering
Figure : Adding a rendering in the memory view
Double click map
Select an XML file from the base/xml directory. A tree view will be displayed formatting your data:
Figure : Viewing an XML rendering in the memory view
Lastly, you can run the tpfxmlgen tool directly on your assembler or C/C++ object and request a map of a specific DSECT, struct or class.
What compile options were used to build the application that you are debugging?
The debug view shows you the C/C++ compile options used for each object in the stack frame. Assembler options are not shown because they do not affect the content of what is being debugged or provide a level of debug information. Also notice that the loadset name is shown on the far right of the display.
Figure : Compile options in the stack frame
Debug information is a description of how the debugger can locate variables, line numbers, source files, and so on provided by the compiler or assembler.
If debug information is not loaded to your system, the debugger will show you a disassembled view of the code and will not provide you variable evaluations from your code. However, you can still use many features of the debugger such as trace log, stop on all function, load breakpoints and so on.
To build your application with debug information and ensure the debug information is loaded to the system, see the debug information subtopic in the compiler topic above.
Is debug information available for my module?
On the z/TPF system, use the ZDDBG DISPLAY DBGINFO-prog command to see what debug information is available on the system for a specific module. The loadset name is provided so you can ensure that your code has debug information.
Figure : ZDDBG DISPLAY DBGINFO-QDB0 sample output
The .so file at load time is named with the module timestamp as the name of the file.
Also, you can see the compile options used on an object by object basis as shown in the What compile options were used to build the application that you are debugging? subsection in the compile options section above.
Automatically load debug information
The remote debug information feature can be used to automatically load the debug information from a remote location. This can be especially handy if you don't know the path your application will take through many modules and you've built all modules with debug information. Remote debug information locators can be set up from the preference pages or from debugger registration entries.
Figure : Selecting the TPF Remote Debug Information Locators from a registration entry
Click the use debug information locators checkbox. Use the Add/modify option to specify the entries to point to the system, user ID and password, and directories where you .so files exist. The .so files include debug information built into the executable and linking format (elf) sections of the module. Notice that the Only use debug information with matching timestamp is selected by default. It is recommended that you always use this option to avoid using the incorrect debug information. If you uncheck this option, you can override the debug information used on the system for all users.
Figure : Selecting the Use debug information locators and Add/Modify
Figure : Creating a debug information locators with the system name, ID, password, directory and so on.
Figure : Selecting the debug information locators to use
Then register or re-register your debugger session. Debug information will automatically be loaded while you are debugging. Watch the Debug console for more information regarding which debug information is being used while you are debugging.
Figure : Debug Console view showing the remote debug information locator FTP status
Here is a final tip on remote debug information locators. The system administrator can define the locators in the TPF Toolkit for all of your systems and roll the definitions out to all users. In this way, the end user can easily select the debug information for the system they are working on without having to know all of the search paths to enter.
PAT debug setting
The ZAPAT NODBUG setting prevents a module from being debugged. This was implemented because the debugger cannot be used to debug certain modules on the system or deadlocks can occur (such as TCP/IP code, file system code, debugger code and so on). However, you can make use of this feature to speed up your debugging experience.
Suppose your application has a set of library modules that are very mature and you are debugging a new feature that uses these mature libraries. You can use the ZAPAT command to mark these library modules as NODBUG in the PAT slot. In this way, you can debug your application without ever stopping in the mature libraries in any way. Use the ZDPAT command to see what the DBUG setting is. If you want to make this change permanently, you can modify your maketpf cntl files to specify NODBUG for your modules, build and load the IPAT.
Another feature is available to accomplish a similar task. It is called step debug. This feature allows you to set up a list of modules you want to debug and then pressing the step into button will cause the debugger to only stop in the modules in the step debug list. More information for the step debug feature is available in the Determining Code Path article.
The z/TPF debugger has several TPF specific views available.
The ECB view can be used to inspect the contents of the ECB in a familiar format using the dump tags to delineate where ECB fields are located. An EBCDIC translation rendering is also provided as well as a tree view of the dump tags. In the tree view is the EB0EB tab which is a tree view of all available fields in the ECB. Right click in the EB0EB tab and choose find field to use a fuzzy search of the available fields.
Figure : ECB View
The data level view shows the contents of all data levels in the ECB. The DECB view shows all data levels in the DECB structure. The DETAC view shows all ECB data levels and DECBs that have been detached. The Record hold view shows you all of the file address that are currently held by the ECB being debugged. These views can be used to investigate the contents of the data levels. Right click on a core block address and choose go to address to view the contents in the memory view. Add an XML map rendering to see the data formatted.
The SW00SR view allows you to see the TPFDF state of your application. Click on a SW00SR in the summary pane and other panes populate. The SW00SR tab is a tree view of all available fields in the SW00SR. Right click in the SW00SR tab and choose find field to use a fuzzy search of the available fields. The core block pane shows a list of all core blocks in memory, all of the logical records (LRECs) in a selected core block and all of the fields in a selected LREC in XML format. The XML map is automatically expanded to the correct key.
Figure : SW00SR view
The TPF malloc view was introduced in the Problem Diagnosis article. This view also provides filters to allow you to filter out only the malloc entries that you are interested in seeing. You can filter based on nearly all of the fields that can be displayed in the TPF malloc view. To set up a filter, do the following:
1) Choose the Configure the filter dropdown option
Figure : TPF Malloc view configure filter
2) Set the conditions to filter on:
Figure : TPF Malloc view setting up the filter
3) Filters are automatically turned on (shown by green light).
Figure : TPF Malloc view malloc filters activated
4) Toggle the filter button off to see all malloc entries:
Figure : TPF Malloc view malloc filters deactivated
The ALASC view shows all ALASC blocks as well as a hexadecimal and EBCDIC rendering of the data. The final view discussed is the ECB Summary view. The ECB summary view combines several views into a concise display of ECB relevant information such as the work area, data levels and so on. The instruction detail pane is discussed in the next topic.
Most of the TPF views are formatted by using XML files. The content and layout of these files can be customized by modifying the XML files. These files are located in your Toolkit install directory for example C:\Program Files\IBM\TPF Toolkit V40\Config\TPFSHARE\map files.
Custom ECB Summary view / User Defined Debugger Summary view
The z/TPF debugger provides you the ability to map binary data with an XML map. This XML mapping feature gives helpful context and meaning to an otherwise difficult to interpret view of memory as hexadecimal data. The User Defined Summary view allows you to apply these XML maps to memory in a prescriptive manner thereby simplifying the process of applying XML maps significantly. You can define rules - such as applying a particular XML map to any data level that contains a record with a given ID - which are automatically applied with a single click when viewing the contents of a data level.
To create a new TPF Custom Memory Monitor, from the Custom ECB Summary view, select the plus sign:
Specify the information for the program that this memory monitor will apply to. In this example, when module QDB2 comes up, this Memory Monitor will display in the Custom ECB Summary View. Optionally, specify a memory map file to parse the ECB memory block defined by the memory monitor
Specify the data that you wish to display. The Data level contents by RID option allows you to specify the record ID (RID) of a data level or DECB in hexadecimal format. The ECB location by field option allows you to specify a named field in ECB memory, such as CE1CR4. The ECB location by offset option allows you to specify a hexadecimal offset in ECB memory.
Here, we will specify that the data is located at ECB location CE1CR1.
We have also specified that the memory map file is idecb.xml. The first time you use this, the display initially shows the raw data, and not the XML that was specified.
For this, it is necessary to point to the XML using the Map Locator Properties. From the Toolbar, select Map Locator Properties.
Click on Add to specify the directory where the XML files are located. This is similar to the Edit Source Lookup.
Now you will see the XML mapping for this.
From the Toolbar, you can also change the Rule File Properties.
Rule File Properties shows the custom memory monitors defined in the current rule file. You can select another rule file for this debug session from the Rule file dropdown list, or change its defined monitors from the context menu on the properties page.
Say that I have a monitor for Record ID E7C9, but I have specified that I only want to see it when I am working with QT19. I can go to the Rule File Properties, and select to edit this monitor.
I will change the Module from QT19 to be asterisk (*).
Now I will see this monitor in my existing program.
NOTE: This was made available in IBM TPF Toolkit, Version 4.2
TPF Debugger File view
z/TPF applications frequently access file records with z/TPFDF APIs, FIND/FILE macros, and so on. The commands ZDCOR and ZACOR can be used from the TPF terminal to view and alter the contents of these TPF files. The TPF Debugger File view lets you view and alter the contents of TPF files through a graphical user interface within TPF Toolkit. The debugger shows the contents of these TPF files in a memory-like view with the ability to render the contents in a variety of ways including applying XML maps to the data. You can use the TPF File view to monitor a TPF file in system or ECB context.
There are a few ways you can create a file monitor.
From the TPF File View, You can choose to manually type in a file address. You can also specify to view the file data at a certain offset. The Monitor TPF File action is available on the context menu in many debug views; it allows you to easily monitor a TPF file during debugging. When a file address is available in the view or pane, the action yields the Monitor TPF File dialog, and picks up the file address from the selected item. In this example, from the DECB view, select a file address, and choose to monitor the TPF file.
When you select this option, you will be given the choice to view this from the System context or the ECB context. If you choose the System context, this is equivalent to issuing a ZDFIL for this file address. The ECB context is useful if your application is in a commit scope. In this case, the ECBs view of the data at this file address will be different from the data viewed by issuing ZDFIL.
Once you have the file monitor, you can choose to view the data on file starting at a given offset into the file. To do this, click on the file and select “Show Offset.” In the example below, we have a monitor for file address 1003EF30. There are three offsets for this monitor, offset 0x20, 0x40 and 0xA0. This would be useful in the case when I have an XML mapping that applies at offset 0x20 into the file. I can show the offset, and then select a New Rendering, and apply the XML map.
Right clicking on the monitors pane will allow you to choose to organize columns. Here you can select additional columns to display, in order to provide additional properties for this file.
Another nice feature here is the ability to compare the system view of the data with the ECB view of the data. Say that you are altering the data on file and you are in a commit scope, you can see the difference between the file view and the ECB view of the data before your application issues the tx_commit, as the next diagram illustrates. The comparison feature is available in TPF Toolkit 4.2.
To edit the file, right click on the file and select Edit File.
The entire contents of the file will appear in a pop up window. Then edit the file just like you would with the memory view. Your changes will not go into effect until you hit the OK button.
Then the changes will appear in red.
The Instruction Detail Pane is a component of the ECB summary view. The instruction detail pane in the ECB Summary view shows the
Current assembler instruction
Operands for the current assembler instruction
A fixed amount of data at the locations of the operand values.
Branch indicator (YES or NO based on branch instruction conditions, condition code, and so on)
The instruction detail pane also gives you the ability to alter the program status word (PSW) condition code.
Figure : ECB Summary view altering the PSW condition code
You can debug without the editor view by doing the following
Minimize the editor view
Move debug view somewhere visible
Use the global execute keys (F5 step into, F6 step over, F7 step return, F8 run)
In this way you can simply watch the instructions in the instruction detail pane and state of the application. This can be a handy way of debugging if you set up a macro group breakpoint such as ALLSVC or DFALL, stop on all functions, load breakpoints or so on to quickly walk through the code while focusing on the state of the ECB rather than the code that is getting executed.
Figure : ECB Summary view with no editor view visible
The Debug console view allows you to enter commands to the debugger. These commands can be very helpful in diagnosing conditions or setting the state of your application such that you can debug a specific situation. The following commands are available:
help – shows a list of all supported commands
help – shows more information on a given command.
z/TPF macro support allows you to issue GETCC, RELCC, FLIPC, ATTAC, and DETAC on your application through the debugger debug console.
tpfmemfill command allows you to copy chunks of data from one address or data level to another. It also allows you to fill a data level or address with data from a file (similar to the ECB Launcher).
stepdebug is a feature that allows you to only debug programs entered in the step debug list. More information for the step debug feature is available in the Determining Code Path article.
xcptrap allows you to manage which exceptions will cause the debugger to stop the application sort of like an exception specific breakpoint.
ECBTrace shows you the current state of the ECB trace (function and macro trace). More information is available in the Determining Code Path article.
TRLOG allows you to turn on the trace log feature without making any changes to you application. More information is available in the Determining Code Path article.
ECBHEap allows you to see details regarding the heap usage of your application in a manner than facilitates diagnosing memory leaks, using excessive amount of memory and other issues with malloc. More information is available in the Diagnosing Problems article. Also see the Determining Code Path article for information on how to view heap blocks through the trace log “Log size” tab.
TPFSEarchmem allows you to search memory. This feature is available in GUI form in any memory based view by right clicking and choosing Search Memory. The GUI usage is also able to maintain the highlighting of matches to the search.
Figure : Searching in the memory view
TPFDUmpdata command allows you to retrieve data requested by the dump capture user exit (cdbaux.cpp). The dump capture user exit allows you to capture additional segments of memory for the dump viewer to display. For example, suppose your application uses a special control block of system heap or other shared memory; you can use the dump capture user exit to capture this data at dump time, learn the address with the TPFDUmpdata command in the dump viewer, and view the contents in the memory view in the dump viewer.
Seeing stack contents
Sometimes it is necessary to view the contents of the stack frame to diagnose an issue. Generally speaking, register 15 (R15) is used as the current stack frame address. You can examine the contents of R15 in the Registers view or the ECB summary view in case your application has corrupted R15. Or possibly, your application corrupted the stack and when the stack frame was popped, R15 was restored to a value that is not valid.
The stack is shown in the Debug view. Generally speaking, depending upon compiler optimization level, local C/C++ variables are stored in the stack. Clicking through the different stack frames and viewing the variables might give you an idea if the stack frame of your application has been corrupted. Also from the Debug view, you can right click on any stack frame and choose map memory element to see that stack frame in the memory view with an XML map of the stack as described in the Diagnosing Problems article.
If debug information and C/C++ source file or assembler listing are available, the debugger will preferentially show this view to you. However, you can choose to switch to view the disassembly code to understand what instructions implement the code you are debugging. You can switch back and forth.
Figure : Switching to the disassembly view of the code.
From this menu, you can select a variety of action such as searching the source file for a specific piece of test, adding a breakpoint, monitoring an expression, monitoring memory, changing the source lookup path, and changing the source file used, or so on. In the editor on the far left grey bar, you can double click to create breakpoints at that location.
In the editor view, you can also perform expression evaluation by highlighting an expression (such as R15, i, or so on) and hovering over that expression. However, sometimes hover expression evaluation is very expensive and slow (possibly due to a slow network connection). You can turn hover expression evaluation off from the preference option Window menu->Preferences->Run/Debug->Compiled Debug->Allow hover evaluation checkbox.
Figure : Hover expression evaluation
One key to editing the source lookup path is to ensure that the Default -> Debug engine always appears at the bottom of the list. This enables assembler listings to automatically be sent from the z/TPF system to the debugger when you are debugging BSOs with debug information loaded to the system.
Figure : Source lookup path
Some users prefer if the debugger always centers the next line to be executed in the editor view. This behavior can be set from the preference option Window menu->Preferences->Run/Debug->Compiled Debug->Center view on execution line
Figure : Center on execution line preference page
Most breakpoint types allow you to specify a frequency or an expression to evaluate that must be met for the debugger to stop the execution of the application for that breakpoint. After adding the breakpoint, click the next button.
Figure : Creating a line breakpoint
Figure : Breakpoint parameters.
Ensure this button is always depressed such that the breakpoints view only shows you the breakpoints for the ECB you are currently debugging. Otherwise, you may think you have breakpoints set up that are not for the ECB you are debugging.
Figure : Selected target breakpoint setting
If you do not want the debugger to catch system errors or exceptions, you can turn it off by using this button:
Figure : Event breakpoint setting
The Modules view is also a good location to set breakpoints from. You can click the green plus sign and add a module that the debugger is not aware of yet. The debug information for that module will be loaded and you can add entry breakpoints by right clicking on a function. Also, you can double click on a function or file to open the source file and then double click in the file to add a breakpoint.
Figure : Creating an entry breakpoint from the Modules view.
Other breakpoints and uses of breakpoints are described in the Determining Code Path article.
The access control feature allows your administrator to control what functionality can be executed on a test or production system. For example, you can disable the performance analyzer, debugger, dump viewer, ECB monitor, ECB Launcher, web services, and some functionality in the debugger. Unlike the ZDDBG command, the ZDBUG command requires computer room agent set (CRAS) authority so you can limit who can issue this command.
The zdbug access disp command displays current access control settings.
Figure : ZDBUG ACCESS DISP
Here is an example of turning off the ability to register the debugger with the ZDBUG ACCESS ALTER NODBUG command to disable the ability to register the debugger.
Figure : ZDBUG ACCESS ALTER NODBUG
After altering access to a feature, enter ZDBUG CLEAR to remove any existing debugger registration entries (note that your end users might be confused as to why their debugger sessions inexplicably exit). Any attempt to register the debugger will result in an error message being returned to the user.
Figure : ZDBUG ACCESS restricted error message in the remote console
However, there is additional flexibility in the CDBPUX user exit. You can do online determination as to who can do what. For example,
You can prevent a particular user from doing anything at all despite the access control rules
You can set it so the balance of users follow the access control rules.
You can have super users who can do what you allow them regardless of the rules.
It is recommended that the debugger should never be allowed to run on a production system. The use of PER will dramatically slow down the system response and if the user stops the application while holding certain system resources, the system could come down or grind your production traffic to a stop. The performance analyzer probably would not have as much impact but is still not recommended for running on a production system. The dump capture, dump viewer, and ECB monitor can be run on a production system but you might want to limit who has the authority to do so to minimize the system impact.
Debugger has the following timeouts available that can make for a better experience over slow networks or on slow z/TPF systems.
The amount of time that passes before an ADB01 timeout occurs can be set by the user in the preference pages. An ADB01 dump indicates a communications failure of some sort and is often seen by users when they register a bad workstation IP address. An ADB01 dump can also appear when the network is slow and it takes longer to establish a connection. This timeout setting determines how long the z/TPF system will wait before causing an ADB01 dump.
Figure : z/TPF connect timeout
The engine response timeout determines how long the TPF Toolkit will wait for a response to come back from the z/TPF system after submitting a request. If the network is slow, you might need to increase this timeout to avoid seeing error messages from the Toolkit that the communications link was lost.
Figure : TPF Toolkit request timeout
The z/TPF debugger should perform better than TPF 4.1 debugger.
Better z/TPF debugger performance depends upon individual usage. We do not produce any benchmarks of anticipated performance due the fact that there are an infinite number of ways to use the debugger and using the debugger in some ways can drastically impact performance. Hints for using the debugger such that is performs better will follow this section. The following statements can be made about why the z/TPF debugger should perform better than the TPF 4.1 debugger.
The z/TPF debugger takes advantage of system hooks to make better use of the PER hardware facility. The TPF 4.1 debugger and z/TPF debugger use the PER hardware facility to implement breakpoints and stepping. The TPF 4.1 debugger simply set the PER range based upon the breakpoints that the user had set. If the breakpoints are in different modules or encompass a large portion of the application space, there could be a dramatic performance impact running from breakpoint to breakpoint as the PER facility must examine each instruction in that range. On the z/TPF system, the PER range is limited to the breakpoints that exist in the currently executing module. If there are no breakpoints in the module, PER is turned off completely and the application is allowed to run through that module code as fast as possible. When the application enters a module that has breakpoints set in it, the PER facility is turned back on inside that module only. This allows the z/TPF debugger to perform better than the TPF 4.1 debugger.
The C/C++ expression evaluator was completely replaced on the z/TPF system. The design of the new expression evaluator is substantially better that the expression evaluator that existed in TPF 4.1 system.
Usage hints for better debugger performance.
Edit Source Lookup can be set so that the debugger performance can be dramatically impacted. For example, some users set the edit source lookup to point to a couple root directories and allow the debugger to locate the source. The debugger must search each subdirectory of every root to find the first occurrence of the specified file name. If a root directory has thousands of subdirectories to traverse before locating the file, it can take a substantial amount of time to perform the search (on the order of minutes). Here are some tips to follow when setting the source lookup path:
Choose TPF project or Remote folder since they are known to perform better:
Figure : Selecting source lookup types
Do not specify root directories (such as /ztpf/)
Specify directories as close to source as possible (such as /ztpf/my_project/base/my_src_file/)
Specify as few paths as possible.
Do not search for multiple matches unless it is absolutely needed. This feature will search all directories and sub-directories on all paths for the matching file name and present a list of all matches to the user. This can have an obvious performance impact.
Figure : Search for duplicates
Do not search subfolders. Select the folders where your source exists explicitly.
Use the Up and Down buttons to order your directories such that most source files will be found on the first path. As mentioned above, ensure the default always exists in the list and appears last.
If network performance is a drastic issue, copy source code to a local location on the hard drive, remove all network paths and set the path to this single local location. This will give the best performance in locating files but introduces source file synchronization issues.
If using TPF project, limit the definition of project filters to a small set of files (especially in the case of large projects or project filters that specify root directories and wildcards).
Open fewer debugger views. Each debugger view requires data to be retrieved from the back end. Some views can automatically populate with changes such as the variables and monitors views. However, other views (like views that show memory – ECB view, memory, data level, and so on) require a request and response be sent to and from the z/TPF system. If the network is slow, gathering the information can take a significant amount of time. Often the time sending and receiving requests over the network is where the debugger performance is most impacted. By hiding the views you are not using or showing views that are more static (breakpoints, modules, debug console, and so on) fewer requests are sent to z/TPF and the debugger might perform better.
Hide complex or costly views. This is similar to the previous item except that specific views require multiple requests or are costly to populate.
Variables view – if your variables view is populated with more than 20 (or even over 100) C/C++ variables, the debugger time required to evaluate these variables can become considerable. Expression evaluation is a costly exercise and a heavily loaded system may exacerbate this processing time such that a user may experience a debugger performance issue. Hide the variables view and monitor the expressions you are interested in watching in the monitors view or use the hover expression evaluation selectively.
SW00SR view – this view requires sending multiple requests to the z/TPF system to gather the information to be displayed to the user. Since multiple requests are sent to the z/TPF system, a slow network with this view open can result in poor debugger performance. Also, using the XML files in the core block panes might require some time for rendering. Open this view when you need to investigate some detail and then hide this view again.
ECB Summary – this view requires sending multiple requests to the z/TPF system to gather the information to be displayed to the user. Since multiple requests are sent to the z/TPF system, a slow network with this view open can result in poor debugger performance. Open this view when you need to investigate some detail and then hide this view again.
TPF Malloc view – depending upon the number of malloc entries multiple requests might need to be made to the z/TPF system to gather the information to be displayed to the user. Because multiple requests are sent to the z/TPF system, a slow network with this view open can result in poor debugger performance. If corruption detection is being done, a slow performing z/TPF system can impact debugger performance since corruption detection requires a significant amount of processing. Open this view when you need to investigate some detail and then hide this view again. Using the malloc filtering feature will reduce the amount of data to be sent over the network. Change the refresh setting to only refresh upon user request.
Limit the use of labor intensive features such as perform heapcheck on stop.
Define remote debug information directories well. This is similar to the edit source lookup advice except that with remote debug information locators you must specify the exact location of the debug information files (.so files). Here are a few tips:
Specify as few paths as possible. Three is a good general guideline with the thinking of one for the user, one for the project, and one for the system. However this might be over simplified.
Specify a small timeout value. If FTP must timeout on each system and path and the timeout value is set significantly high, the user may need to wait a long time for the timeout to occur for each system and path (accumulating to a long wait time). For example, suppose there are three paths with an FTP time out of 10 seconds. If a system is unreachable and the user has to wait the full time out on each path, the user will wait 30 seconds for the debugger to respond after entering each new module that does not have debug information loaded to the system.
If the network is performing poorly, load debug information by way of the loaders instead of relying on the remote debug information feature. Or use debugging techniques that do not require debug information to be loaded similar to what was described for debugging production level code (see Determining Code Path article).
Debugger Dumps and what to do
There are three debugger dumps that generally don’t need to be sent to IBM. Here is an explanation for each of these.
ADB01 dumps indicate that a communications problem has occurred. The dump message is enough to indicate what kind of problem has occurred. Usually, this dump is the result of the user registering the wrong workstation IP address. But it can also occur under other circumstances such as a poorly performing network. Some ADB01 dumps have been replaced with WTOPC messages that attempt to explain exactly what the user needs to do to address the problem.
ADB06 dumps occur for the application when the debugger dumps. These dumps do not indicate any problem exists in the application. The ADB06 dump simply ensures that the application ECB is cleaned up the most complete way possible. These dumps can be ignored at all times.
ADB13 dumps indicate that the debugger has run out of memory. Usually this is the result of loading debug information. First try increasing MAXXMMES with the ZCTKA command, ZRIPL and retry your case. Modules have been debugged that required MAXXMMES to be set as high as 500-800. This dump may also be an indication that your system (VPARS, or so on) requires more memory allocated to it. Generally, debugging less than 10 CSOs with debug information at –O0 should not be a problem. However, if your CSO is extremely large (such as CMQS) or coded in such a way that global (file scope variables) appear in each object, or so on, greater amounts of the debug information need to be loaded. Again, try increasing MAXXMMES. Otherwise, please send this dump to IBM.
The ECB Launcher allows you to create an ECB on a test system and enter any given 4 character program name. You can enter a driver segment that sets up the ECB for an application or enter the application directly. The ECB launcher allows you to enter a text string into the ECB work area and create a data level and fill it with predefined data. The predefined data can be specified as an ASCII, EBCDIC, binary, or hexadecimal file which is a text file with data copied from a dump or so on.
Suppose I have some dump data from a data level and I want to restart my application with that given information.
Figure : Text file with hex data in it
1) Use the files subsystem to copy the file to the z/TPF file system. You can drag and drop files from a system onto the z/TPF system or use copy and paste.
Figure : Files subsystem showing the textual hexadecimal file contents on the z/TPF system.
2) Create a new ECB launcher entry specifying the program name, ECB work area text, data level, core block size, and file on the z/TPF system to populate the file from.
Figure : Create a new ECB launcher
3) To launch a new ECB right click on the launcher and choose launch ECB
Figure : Launch ECB
An ECB will be created and set up as requested.
The ECB launcher is independent from debugger. You can use the ECB laucher to start any traffic on the system you choose. To debug a launched ECB, register the debugger as normal (use * for the terminal since the ECB is created by way of CREMC). Notice the EBW00 work area contents are as registered and the data level contains a block as specified with the contents from our file.
In this article we have discussed the not so obvious features of the z/TPF debugger.