Debugging Using a Core Dump

Important:
  • The following applies to native code only.
  • On Windows, the core files created by this product are Microsoft minidump files. If you have a mixed-language application, you can use the minidump file to debug the other languages involved.

When an application crashes or when you programmatically invoke a core dump (using the CBL_CREATE_CORE library routine), you can arrange for its state to be saved to disk, in a core file. The contents of this file can indicate where the error occurred in the source code; it also contains the contents of memory at the time of the error or invocation, and the values of any variables and expressions set at the time. You can then use the core file to help debug any problems.

Core dump debugging is useful when you have a failing application in a production environment, and you don't have the COBOL development system installed. As long as you have access to the application's source files elsewhere, you can produce a core file and debug it.

To accurately debug using a core file, in your development environment, you must use the original source and .idy files used to create the executable in question, or failing that, you must ensure that the sources are in the same state (directive settings, optimization, etc..) as they were during the initial build. Also, as this process will most likely result in you moving from a production environment on one machine, to a development environment on another, any supporting files used by the application must be installed along the same path in both environments.

If you do not have the required .idy file, the IDE indicates that no source is available.

Produce a core file

You can produce a core file in one of the following ways:

  • Use cblcored.exe from a command prompt:
    1. Copy the file cblcored.exe from the bin subfolder in the product installation directory to the same directory as your application's main executable file.
    2. At the command line, go to the directory containing cblcored.exe and type:
      cblcored
      Note: cblcored.exe requires write permission to the current user’s HKEY_CURRENT_USER key in the Windows registry. Ensure that the utility has the required permission in order for any changes to the Core Dump settings to persist.
    3. From the Core Dump list, select one of the following then click OK:
      • Enabled with prompt if you want a message box displayed when a core dump is about to be created.
      • Enabled with no prompt if you do not want a message box displayed when a core dump is about to be created.
      • Disabled if you do not require a core dump.

      If you have selected one of the enabled options, the next time you run the application and an error occurs, the state of the application at the time of the error is saved in the file cblcore. This file is saved in the same folder as the application.

    4. Run the application. When the application crashes, a core dump is produced if you selected either of the Enabled... options.
  • Use run-time tunables to perform a core dump for any run-time errors:
    1. Create a run-time tunable configuration file and add to it the core_on_error tunable.

      The default name of the core file to be produced is cblcore. To specify a different file name, add the core_filename tunable to the run-time tunable configuration file.

    2. Run the application. When the application crashes, a core dump is produced.
  • Use the CBL_CREATE_CORE library routine to programmatically invoke a core dump; see CBL_CREATE_CORE for more details.

Debug using a core file

To debug a core file using a native COBOL project:

Note: Ensure that the project and the sources it compiles have not changed since the original executable was created; otherwise, any discrepancies in the .idy file used to debug and the one originally created (when the executable was built) will cause unexpected results during debugging.
  1. In the IDE, click Project > MyProject Properties and navigate to the Debug tab.
  2. Click Start external program and specify the name of the Micro Focus core file.
    If the project is a native COBOL mainframe project:
    • On the Debug tab in the project's properties, set Active Settings to Core Dump.
    • Under Core Dump Settings, specify the name of the Micro Focus core file.
  3. Start debugging.
Note:
  • It is not possible to enable both Just-In-Time Debugging and Core Dump concurrently.
  • To debug a 64-bit core dump you must first create a 64-bit project configuration or select x64 as the Platform target on the COBOL tab in the project's properties.
  • cblcored.exe is one of the Enterprise Server files, which is provided for on-site debugging. You are authorized to redistribute this file to your customers providing you have the appropriate license.
  • To create a core dump for an application running under IIS, the application must be run in the same user account as that being used when enabling the core dump feature. For example, a core dump will not be produced for a CGI or ISAPI application running under the default anonymous logon account.