COBOL Application, COBOL Attach to Process, and COBOL Wait for Application Attachment

Use COBOL Attach to Process to debug an application when it has been called by another application already running. Use COBOL Wait for Application Attachment to wait for a COBOL application to be run and attach to it when it is started. Any remote application must have been compiled for debugging.

General tab

The options common to the General tab in the Debug Configurations dialog box for these configurations are:

COBOL Project

The project that will be used while debugging.

Connection Properties

Enter values for these fields if you want to debug your project or the application when it is running on a remote machine.

Remote Host

The name or IP address of the remote machine.

Specify the port on which cobdebugremote process will listen on the remote host

When you are debugging an application on a remote machine, the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) needs to be running on that machine. ¹

If you are developing the application on the remote machine

If you are using Visual COBOL Development Hub, the IDE starts the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) automatically on the remote machine when you start debugging. You do not need to select a port as a random one is picked when the process starts, but if you select this option you can assign a specific port in the cobdebugremote port field. If you do specify a port, the process starts automatically on that port.

If you are developing the application on the local machine and debugging remotely

You must first start the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) from a command prompt.

The process takes the following options:

no options

Starts the process and opens a random port for remote connections. The port number is displayed in the console.

machine=name

Specify the machine that the process is running on. Only valid with the stop option.

port

port=nnnnn: Specify the port to use to listen for connection requests.
port=nnnnn-yyyyy: Specify the range of ports to use. If port nnnnn is in use, the next port is tried until a free port is found. If no free ports are found in the range, the utility returns an error.
Note: You must enter the same number you set as the port option in the cobdebugremote port field of your debug configuration.

repeat

After the debug session has been completed, start listening for another connection. If no option is specified, the process exits after the debug session has completed.

stop

Causes the process that is listening on the port to exit. Must be used with the port option. This is only valid when the process is waiting for a connection.

If you run the process with no options, you must enter the port number displayed in the console in the cobdebugremote port field.

Use X Server

For SSH-only connection types (Micro Focus DevHub SSH Only), you do not need to use an X Server implementation to echo the remote program output back to your local machine; for simple I/O programs, you can display the output in the Console view within the IDE. For more complex programs, you may still want to use an X Server implementation, for a better display experience.

To direct the program output to the Console view, ensure Use X Server is not selected. For other connection types, this option is unavailable, and an X Server implementation must be used.

X Server (DISPLAY)

If you are debugging an application on a remote UNIX machine using Visual COBOL Development Hub, enter the identifier for the X server that will display the remote program output on a local Windows machine. The default value is client machine name:0.0.

Before debugging, make sure that the X server is running and that the remote machine xhost configuration has the correct access permissions. You can use the xhost + command to add your host or username to the list of those permitted.

Debug Options

Use these options to further control the debugging process.

To ensure debugging works correctly, you must indicate when the application you are debugging is 64-bit or graphical.
Select Suspend at 'stop run' to keep debugging your program by suspending it, rather than terminating it, when a STOP RUN command is executed.
To specify that a program breakpoint causes execution to stop only when the Procedure Division entry point is called, check Program breakpoint on main entry point only. With this option unchecked, which is the default, a program breakpoint causes execution to stop on any entry point to the program and on return to the program from a call.
To allow you to move forwards and backwards through the execution path whilst debugging, select Enable reverse debugging.
Note: You can only select this option if you have selected a project/program located on a platform that supports reverse debugging - see Reverse Debug and Live Recording for a list of supported platforms.
The Require program symbols (.idy) to match the program option is selected by default, which only allows debugging of native COBOL programs if the symbols file matches the COBOL program (in that it was produced at the same time). To disable the check, clear this option.

The following settings are only applicable to COBOL Application debug configurations:

Main Program

Select the main executable in your project. If you have already selected this in a build configuration you only need enter the build configuration name, otherwise you can browse to the program's location in your project.

Start Options

Enter the arguments to pass to the program when it starts. You can also indicate the working directory of the application if the project doesn't explicitly specify its location.

Run Options

Check Pause after running the application to prevent the application terminal from automatically closing once it has completed running. This option gives you time to note any terminal output. Press Enter to close the terminal.

Debug Options

Select Allow debugging of all COBOL target types in order to debug any executable compiled with COBOL code. If you do not select this option, only .int code will be debugged. If you choose this type of debugging, you cannot debug non-COBOL projects that have both COBOL and non-COBOL programs calling each other.
All Windows programs run in multi-threaded run-time systems. For UNIX programs, select Use multi-thread run-time system to do the same, otherwise the single-threaded system is used.

The following settings are only applicable to COBOL Wait for Application Attachment debug configurations:

Matching Options

Specifies which programs the debugger attaches to when the program starts:

Any - the debugger attaches to any process that is enabled for debugging. For instance, using the environment variable COBSW=+A or by a call to CBL_DEBUG_START.
Note: This option is only available when debugging applications running on Windows.
Program identifier - specify the identifier of the program the debugger should attach to. The matching program identifier value should be passed as a parameter to the CBL_DEBUG_START library routine called by the application to be debugged - see CBL_DEBUG_START.
Executables stored in directory:
- On Windows platforms, specify the directory which contains the main executable used to start the process.
- On UNIX platforms, specify the current directory of the process.

Return to waiting state when debugger disconnects

If you select this the debugger will wait until a debuggable program attaches to it again. If you do not select it, debugging terminates when it disconnects from the program.

Source tab

The options common to the Source tab in the Debug Configurations dialog box for these configurations are:

Source Lookup Path

Enables you to specify the locations and order in which the debugger looks for source files.

Click Add to add locations:

COBOL Project: Click this to choose the projects to search. Any folders and dependent projects specified on the Micro Focus > Build Path tab in the projects' properties is also searched.
Environment Variable: Click this to select one or more variables that include the folders that must be searched.
File System Directory: Click this to specify a specific file system folder to be searched that may exist outside the workspace.
Paths From Debugger Information Files: Click this to enable the debugger to locate the source file using the path specified in the .idy file, this is the path stored when the program was compiled. The source file can be outside of the workspace and means that the project containing the source file does not need to be added to the source lookup.
Project: Click this to enable folders in a specific project to be searched.
Remote File System Directory: Note: This option is only available when debugging remote projects.
Click this to specify source files from a remote file system folder located on a remote host. Use the Connection name field to select an existing connection to a remote host, or click New Connection and create a new connection, and then use the Remote path field to select the location of the source files on the host. Select Search subfolders if you want to search recursively through subfolders for required source files.
Working Set: Click this to add the source lookup path for all the visible projects defined in a working set, see Working Sets.
Workspace: Click this to search all folders within the current workspace.
Workspace Folder: Click this to enable you to specify a specific folder within your workspace as a source lookup path.

Debug Symbols tab

The options available in the Debug Symbols tab in the Debug Configurations dialog box for these configurations are:

Debug Symbols Lookup Path

Enables you to specify the locations and order in which the debugger looks for debug symbols containers and files.

Click Add to add locations:

Environment Variable: Click this to select one or more variables that include the folders that must be searched.
File System Directory: Click this to specify a specific file system folder to be searched that may exist outside the workspace.
Project: Click this to enable folders in a specific project to be searched.
Remote File System Directory: Note: This option is only available when debugging remote projects.
Click this to specify debug symbol files from a remote file system folder located on a remote host. Use the Connection name field to select an existing connection to a remote host, or click New Connection and create a new connection, and then use the Remote path field to select the location of the symbol files on the host. Select Search subfolders if you want to search recursively through subfolders for required symbol files.
Workspace Folder: Click this to enable you to specify a specific folder within your workspace as a debug symbols lookup path.

Note: Debug symbols containers length must not exceed 32,725 characters.

CTF

This tab enables you to configure the Consolidated Tracing Facility (CTF) to produce diagnostic information for your program:

Enable CTF

Check this to displays any CTF configuration files that you have in your workspace in the Available configurations list.

Note: CTF configuration files must have a .mfctfcfg suffix.

Use selected configuration: Click this to use the selected configuration file. This populates the Chosen configuration area with the configuration items contained in the selected configuration file. You can modify the configuration items, and then click Apply.
Note: Modifying the configuration in the Chosen configuration area does not modify the source configuration file.
Export: Click this to export your modified configuration to a file on your local filesystem or a remote location.
Import: Click this to import a configuration from a file on your local filesystem outside your workspace or from a remote location.

See The Consolidated Tracing Facility for more information on CTF configuration files.