Dynamic Runtime Tracing

You can create a diagnostics report that traces the behavior of a runtime environment. You can enable this tracing dynamically on any of your existing programs; however, certain details can only be traced if your programs are compiled with the debugging options -Gs and -Gl before they are executed.

Use the following steps to produce a runtime diagnostics report from a command prompt:

1. If required, compile your program for debugging; the minimum requirements are the -Gs and -Gl compiler options:

   ccbl -Gs -Gl my-prog.cbl

2. Run the program with the --analyze switch.

   runcbl --analyze my-prog.acu 

3. Locate the process ID of your runtime process, and then create a configuration file named analyze.process-ID.cfg.
   Note: The configuration file should be located in the current directory, or in the %PUBLIC%\etc (Windows), or /etc (UNIX) directory.
4. Populate the configuration file with the required runtime options; see Configuration Variables for Dynamic Runtime Tracing.
5. Turn tracing on using the -analyze option to cblutil:

   cblutil -analyze process-ID

   You can specify more than one process ID to enable tracing for multiple processes.
   CAUTION:
   For UNIX users - cblutil is unable to determine if the specified process is a runtime that has been started with the --analyze switch. An error is only returned if you specify a non-existent process ID, or when you do not have sufficient permissions to send a signal to the process. An alternative method to turn on tracing is to send a SIGUSR2 signal to the runtime, using the kill command; refer to your operating system documentation for specific details.
6. Use your program as you would normally; the actions set to be traced are written to the report file specified by OUTPUT_FILENAME_PATTERN.
7. To stop tracing, run the command at step 5 again, or terminate the program.

   The report file is created in the directory from which the program was run.

8. View the tracing output from the report file.