Your application has just crashed. How do you figure out why and where it’s gone wrong? This session will walk you through some of the tips and tricks used by Micro Focus SupportLine and developers to diagnose application problems. We’ll cover a variety of debugging techniques, tracing, profiling and more. These techniques should be invaluable to COBOL developer using Net Express, Server Express or Visual COBOL.
UNIFIED ENDPOINT MANAGEMENT. WHAT IT IS AND WHY IT’S IMPORTANT
Debugging and Diagnostics with Visual COBOL
1. Debugging & Diagnostics with
Visual COBOL
Chris Glazier – SupportLine
Scot Nielsen – Product Management
2. This Session…
• …is for developers
• Something in here you can use next week
– or when you get really stuck
• Want to fit in as many different approaches to ‘finding the
problem’ as we can in 45 minutes
• We’ll use Visual Studio and Eclipse
– Just about everything you can do in Net Express/Server Express
• Back of this deck are all the things we’ve covered (and
potentially those things we didn’t get to!)
2
3. 3 areas we’re looking at today
1. Report generation tools
– What did my program do?
2. Tracing tools
– Where did it all go wrong?
3. Interactive debugging
– Taking the bull by the horns
Use these for testing as well as debug
Production and development
3
4. Start with a little humor…(very little)
There are 10 types of
people in the world…
Those who understand
binary and those who
don’t…
4
6. Report Generation Tools –
MFSupportinfo
• When to use it?
– Opening an incident with SupportLine
– Need to know what Micro Focus products are
installed
– Available in Dev and Production products
• How does it work?
– creates Mfsupportinfo_machinename_timestamp.log
– log file contains everything about your workstation configuration
– Can be found in Visual COBOLbin folder starting with Visual COBOL 2.0
6
7. Report Generation Tools –
Profiler (Performance Analysis)
• When would it be used?
– Diagnose Performance issues
– Requires a development product
• What information does it provide?
– Gives the total execution time
– By section and paragraph
7
8. Report Generation Tools –
Test Coverage
• When would it be used?
– Find out which lines of code have been executed
– Useful for Code Coverage Testing
– Requires the Development product
• What information does it provide?
– Shows which statements have been executed
– Identifies untested portions of the program
– Accumulates results over multiple runs
• How does it work?
– Program must be compiled with TESTCOVER directive
– TCReport utility creates HTML or text report
8
9. Report Generation Tools –
Fault Finder
• When would it be used?
– For Production or Development debugging
– Does not require the development product
• What information does it provide?
– Snapshot of the application at the time of failure
– Open files, file buffers, loaded programs, environment settings, call stack, program memory
data, working-storage and local storage
• How does it work?
– Triggered by abnormal program termination
– configured using run-time tunables
– Creates report on application state
9
11. Tracing Tools -
Paragraph tracing using TRACE directive
• When to Use
– Shows execution flow of paragraphs & sections
– Typically for batch applications
– Usually a developer product
• How to use
– Compile using TRACE directive
– READY TRACE statement turns on trace
– RESET TRACE statement turns off trace
– TRACE is displayed to screen as sections executed
– OUTDD”filename” directive can redirect a file.
12. Tracing Tools -
Database / OpenESQL
• ODBC Driver Statement Trace
– Traces statements executed by the ODBC driver itself
– Can be used in Development or production
– Use precompiler directive SQL(ODBCTRACE=ALWAYS)
– Run application to create file MFSQLTRACE.LOG
• OpenESQL Summary Trace
– Creates pseudo-code summary of statements executed by OpenESQL.
– Can be used in Development and Production.
– Use precompiler directive SQL(TRACELEVEL=4)
– Run application to create file OpenESQLTrace.processID.log.
12
13. Tracing Tool –
Consolidated Tracing Facility (CTF)
• What is it?
– Highly extendable application tracing engine
– Integrated with the components of Visual COBOL, Net Express and Server Express
– Provides tracing for applications deployed under COBOL Runtime2010, Application Server and
Enterprise Server environments
• Why is it so important?
– For any customer production issue, application tracing can be turned on by simply setting an
environment variable
– CTF is always enabled by default and deployed in an application; no special requirements such
as compiler directives or development environment IDE is required
– Provides a consistent interface for tracing across all products and environments
– Customers can CTF-enable their own application components allowing them to
configure and generate trace output along with MF component trace information
13
14. Architecture Diagram
Config
File Output
Destinations
TEXTFILE
Emitter File
Config
APIs
BINFILE BINFILE
Engine
Emitter CTFViewer
Tracer
Application
Tracing
IDEDBG
APIs
Visual Studio
Emitter IDE
Event Log Windows
UNIX Syslog
Consolidated Emitters Event or
Emitter Unix Syslog
Tracing Facility
15. Tracing Tools –
XFHTRACE (File Handling)
• XFHTRACE – binary trace of file I-O
– Traces all file I-O statements to binary format
– Often requested in cases of file corruption
– Can be used in development or production
– Save copy of current file that you wish to trace
– Set option TRACE=ON in EXTFH.CFG
– Set environment variable EXTFH to point to extfh.cfg
– Run application to create binary file XFHTRACE.XFH
• COBFHREPRO3 – Create readable text trace file report
– run COBFHREPRO3
– Example:
C:>cobfhrepro3 /gXFHTRACE.XFH /a /d /ntestfile.dat
– Creates report output file xfhrepro.log
• COBFHPRINT – Abnormal File Conditions
– Prints contents of XFHLOG file
– Abnormal file conditions are stored in XFHLOG
15
16. Tracing Tools –
Fileshare Tracing
• Fileshare Server Configuration File – Add option “/tr f”
– Trace message written to screen
– Trace messages written to file fsscreen.lst
– Can severely impact performance so use only when debugging
– F2 key used to toggle trace on and off
16
17. Tracing Tools –
Fileshare Tracing
• FSView utility
– Command line tool or callable API
– FSVIEW lets you:
• view statistics produced by Fileshare
• manage Fileshare servers remotely
17
18. Tracing Tool – 3rd Party Tools from SysInternals
Process Monitor – PROCMON
• Process Monitor can be downloaded for free from:
http://technet.microsoft.com/en-us/sysinternals/bb896645
19. Tracing Tool – 3rd Party Tools from SysInternals
Process Explorer – PROCEXPL
• Process Explorer can be downloaded for free from:
http://technet.microsoft.com/en-us/sysinternals/bb896653
20. The Debugger
How many ways can you debug?
• Dynamic debugging
• Wait for animatable attachment
• Attach to Process
• Core Dump
• Watch Points
Different approaches for different situations
20
Notes de l'éditeur
Visual COBOL includes many different types of tools that can aid the developer in tracking down and solving problem issues in areas such as performance, file handling, database and just plain old bugs in general.Many of you Net Express and Server Express users may recognize some of these tools as they have also been available in those products for years. But I know from experience in talking with Net Express and Server Express users that a large number of them are either not aware of the existence of these tools or they don’t really understand their purpose.We will try to clarify this for you today.Visual COBOL includes report generation tools like Profiler and Fault Finder as well as tracing tools such as the Consolidated Tracing Facility or CTF.The third section of this presentation will cover interactive debugging using the Visual Studio IDE itself .This includes many different methods of starting the debugger.The second section of this presentation will focus on the tracing tools that are available within Visual COBOL and this first section will cover the report generation tools.Let’s get started.
Visual COBOL includes many different types of tools that can aid the developer in tracking down and solving problem issues in areas such as performance, file handling, database and just plain old bugs in general.Many of you Net Express and Server Express users may recognize some of these tools as they have also been available in those products for years. But I know from experience in talking with Net Express and Server Express users that a large number of them are either not aware of the existence of these tools or they don’t really understand their purpose.We will try to clarify this for you today.Visual COBOL includes report generation tools like Profiler and Fault Finder as well as tracing tools such as the Consolidated Tracing Facility or CTF.The third section of this presentation will cover interactive debugging using the Visual Studio IDE itself .This includes many different methods of starting the debugger.The second section of this presentation will focus on the tracing tools that are available within Visual COBOL and this first section will cover the report generation tools.Let’s get started.
Starting with Visual COBOL 2.0 the mfsupportinfo utility can be found in the bin folder of the Visual COBOL installation folder.It was also included as part of Net Express in V5.0 and higher.This utility creates a report containing detailed information about the environment of the computer on which it is run.Thisincludes a list of all Micro Focus products installed, operating system and file system details and general information about the computers environment and licensing.This is routinely one of the first items that Customer Care engineers will ask you for.If you run this utility and attach the generated .log file to a support incident it will give us the critical information that we need in order to move forward with the problem at hand.This utility is also used to compare environments between computers on which your application works and on those on which it fails.It also lets us compare the version of your development product (Visual COBOL) with the version of your production product (COBOL 2010 Runtime) to ensure that they do not differ.There is a similar utility in our Unix products MFPOLL.Lets take a quick look at what a typical mfsupportinfo log file contains. <click link>
The Profiler Tool will create a report which gives you information about where your application is spending most of its time. The report generated is in a formatted text file and gives you total execution time of your program and then breaks it down in milliseconds for program sections and paragraphs.This is a good way to spot possible bottleneck areas of your program that you can then fine tune to adjust performance.To create a Profiler report you must compile your program with the profile directive.The Visual COBOL development product must also be installed on the machine where the application to be profiled will be run.When the application compiled with the profile directive is run it will create one .IPF file for each of the programs called.You can create a readable profiler report by running the profiler command from a Visual COBOL command prompt specifying the names of all of the .IPF files that you wish to include along with any directives to control the output of the generated report.This will create a report with the name of the first program specified with the extension .PRF.
The Test Coverage tool aids developers or development teams during an applications testing phase. Programs to be tested need to be compiled with the TESTCOVER directive.Multiple application program tests can be cumulative so you can test using different paths of execution or test data and the Test Coverage tool will merge the output of the multiple runs.You can then generate a report in either text or HTML format which will show the source code of your program along with per source line counts of the number of times an individual statement has been executed.After all your testing is complete, if a test coverage report still shows that certain statements or paragraphs within the application have not yet been executed, then perhaps you need to expand your test runs or perhaps you have dead code in your program which is unreachable from any path of execution. This dead code could then be removed if it is truly not required anymore.
The next report generation tool that we will talk about is Fault Finder.This tool is used to generate a detailed report containing a snapshot of your computer and application programs environment at the moment an error occurs.The generated report contains information such as program memory, open files, call stack, loaded programs and other useful information to help you track down program errors.Fault Finder is useful for production debugging as it does not require a development environment on the computer running the application.The application does need to be compiled with the FaultFind directive and some additional report generation information can be set as runtime tunables in a cobconfig.cfg configuration file.These options can control the type of information which will be included in the report such as whether or not to include the contents of a programs Working Storage in the report.
In this next section we will cover the various tools that provide for application tracing capability.Depending on the tool used, trace output can be anything from a simple textfile showing you paragraphs that are being executed to a complex report detailing all of the memory allocation requests that are occurring in the run-time system.That being said, it is important to note that some of these tracing tools provide information that may seem completely useless to you as an application developer but this same information can be extremely important to both Micro Focus Customer Care and Development teams.
The Database tracing tools are important in tracking down the source of a problem when using embedded SQL statements in your applications.In addition to the tracing which is provided by each database vendor, Visual COBOL also provides its own powerful tracing through the use of two precompiler directives.The first directive SQL(ODBCTRACE=ALWAYS) provides for an ODBC trace of all SQL statements executed. This information is output by the ODBC driver itself and really requires a certain level of knowledge of ODBC APIs in order for these to be useful. They are extremely useful to development however in tracking down potential bugs in our product or within the ODBC driver itself.Here is a typical trace file which is generated by setting this directive. <click link>The second directive that can be used is SQL(TRACELEVEL=4) which causes the application to generate trace information containing a summary of executed statements in theOpenESQL run-time itself.Here is a sample of what a typical OpenESQL summary looks like.<click link>
So far I have shown you a number of different tools for producing reports and trace information for specific components.The problem with these various tools is that they all use different configuration and reporting techniques.There is no consistency and that causes confusion.In order to try and remedy this situation, we came up with a new tool called the Consolidated Tracing Facility.CTF provides a consistent interface across all product platforms and environments and its generated tracing information is configurable and controlled by the user of the tool.One of the most powerful features of CTF is that you don’t have to recompile your programs with any special directive in order to use it.CTF enabled components are always ready to start tracing.All you need to do is to set the MFTRACE_CONFIG environment variable to point to a ctf configuration file containing information about which components you wish to trace.This means it can be turned on in a production environment just as easily as in development.
XFHTRACE is the name for the Micro Focus External File Handler trace facility.It provides a means to output trace information for all file I-O within an application or limit the trace to specific files for which a problem is occurring.It is turned on by adding the option TRACE=ON to the extfh.cfg file.You can also specify TRACEFILENAME= and TRACEFILEEXTEND to provide a name for your trace file and tell it whether or not the trace file will be extending or erased each time the application is started.Here is a sample extfh configuration file which contains the trace option. <click link>The output file that is created is by default called XFHTRACE.XFH and contains binary information which cannot be viewed.In order to generate a text readable file the utility program COBFHREPRO3 needs to be run against the binary file.This program can also be used by development to replay all file I-O against a supplied original copy of a file in order to track down possible file corruption issues.This is what the command line looks like to generate a text file named xfhrepro.log.And this is what that file might contain: <click link>
Fileshare is the Micro Focus remote file handler server.It can run as a standalone application or as a Windows service on a remote server machine on which your files reside.Applications configured to run with fileshare have their file I-O redirected to a fileshare server which handles the I-O and passes any resulting data back.You can turn on Fileshare Tracing on the server by adding the /tf f option to the fileshare configuration file.Trace records will be output to the screen if fileshare was started from command line, and also to a file called fsscreen.lst.You can also add tracing information for CCI (Common Communications Interface) which is the program handling all of the underlying communications between the client and the server by adding the option /trcci to the same configuration file.
Another tool that can be quite useful in both managing fileshare operations as well as troubleshooting is the FSView program.This can be started as a command line utility or it is available as a callable API so that you can write your own interface to its functions.You can see here some of the commands that are available with this utility.You can get a list of locks on a particular file, get server information, get a list of open files per user and many other useful commands.
This last section is a hands-on presentation to demonstrate how the Visual Studio 2010 IDE can be used in a number of different ways to help diagnose and debug application problems.
This last section is a hands-on presentation to demonstrate how the Visual Studio 2010 IDE can be used in a number of different ways to help diagnose and debug application problems.
The Profiler Tool will create a report which gives you information about where your application is spending most of its time. The report generated is in a formatted text file and gives you total execution time of your program and then breaks it down in milliseconds for program sections and paragraphs.This is a good way to spot possible bottleneck areas of your program that you can then fine tune to adjust performance.To create a Profiler report you must compile your program with the profile directive.The Visual COBOL development product must also be installed on the machine where the application to be profiled will be run.When the application compiled with the profile directive is run it will create one .IPF file for each of the programs called.You can create a readable profiler report by running the profiler command from a Visual COBOL command prompt specifying the names of all of the .IPF files that you wish to include along with any directives to control the output of the generated report.This will create a report with the name of the first program specified with the extension .PRF.
Lets take a look at what this profiler report looks like:
In order to generate a test coverage report you need to set the compiler directive TESTCOVER in any program that you wish to include or set it at the project level in Visual COBOL to include all programs within the project.You then create a testcover configuration file and set the environment variable TESTCOVER to point to the location of this file.There is a default configuration file in the location specified here and you can use it as is or modify it to fit your needs.When you run your application it will create a binary file with the name of your first program and the extension .TCZ.You can then create a readable report in html or text format by running the tool tcreport against this .TCZ file.Here is an example of what such a command line would look like.
Lets take a look at what a typical html test coverage report looks like.
The next report generation tool that we will talk about is Fault Finder.This tool is used to generate a detailed report containing a snapshot of your computer and application programs environment at the moment an error occurs.The generated report contains information such as program memory, open files, call stack, loaded programs and other useful information to help you track down program errors.Fault Finder is useful for production debugging as it does not require a development environment on the computer running the application.The application does need to be compiled with the FaultFind directive and some additional report generation information can be set as runtime tunables in a cobconfig.cfg configuration file.These options can control the type of information which will be included in the report such as whether or not to include the contents of a programs Working Storage in the report.
You create a readable report by setting the faultfind directive in the program that is reporting an error such as an RTS error 114.Set the applicable faultfindtunables in your cobconfig.cfg file.Here is a sample of what this file might contain: <click link>Set the environment variable COBCONFIG to point to the location of the configuration file and then run the application outside of the IDE.You must run it outside of the IDE or else the debugger will be launched when the error occurs.It is really more useful on a production computer on which the IDE is not available.Although faultfinder can be quite useful, better tools are now available by using remote debugging or generating and debugging a core dump using the Visual Studio debugger.We will cover these options a little later on.Lets take a quick look at what type of information is written to the faultfind.log file. <click link>
CTF Text Files are currently generated on a per process basis so if your application creates new processes or you are running under Enterprise Server then your application trace may generate more than one trace file with the process ID being used as part of the file name.For Multi-threaded applications that run within a single process, trace records from all threads will be output to the same process file and they can be recognized by the thread-id field within a trace record.The format of these trace records is configurable by the user by an entry in the configuration file so the actual information and order of the fields within the trace record is controlled by the user.You can see that in a textfile some of the information output such as the event ID is only output with a component name and a number that you would then look up within the Visual COBOL documentation.
You can see that when you use a BINFILE emitter and the CTFViewer along with special annotation files you can receive a much more verbose report where detailed textual descriptions would replace the Event ID number. These CTFViewer component annotation files are located by default in the etc\\mftrace\\annotations folder of the Visual COBOL product installation folder.These annotation files are in XML format and contain detailed information about the events supported within a component. This allows the CTFViewer to apply the descriptive information to the event records so that instead of displaying an event ID that you would need to look up in the product documentation you will get more meaningful text such as “RTS Initialization” or “Library Load”.The CTFViewer also provides advanced find and bookmarking options that make trace analyzing a much easier task. You can choose to find and view only records that meet a certain criteria or you could search for only records that pertained to an error that was occurring.
In this next section we will cover the various tools that provide for application tracing capability.Depending on the tool used, trace output can be anything from a simple textfile showing you paragraphs that are being executed to a complex report detailing all of the memory allocation requests that are occurring in the run-time system.That being said, it is important to note that some of these tracing tools provide information that may seem completely useless to you as an application developer but this same information can be extremely important to both Micro Focus Customer Care and Development teams.
This last section is a hands-on presentation to demonstrate how the Visual Studio 2010 IDE can be used in a number of different ways to help diagnose and debug application problems.