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