Tutorial: Debugging COBOL Applications Remotely

Overview

This tutorial uses the COBOL Snake game from the Samples to show how to build a native COBOL application on a local machine, copy the application files to a remote machine and debug the application from the local machine.

The process of building the application through to debugging it remotely is as follows:

Build the native COBOL sample on your local Windows machine.
Copy the application and the symbols file to a remote Windows machine.
On the remote machine, start a cobdebugremote or cobdebugremote64 process at a specified port.
Configure the Firewall to allow the Micro Focus Debugger Proxy V2.
In your Visual Studio project, specify properties for remote debugging and configure the symbols paths.
Debug the remote application on the local machine

Prerequisites

To complete this tutorial, you need two machines with the following software installed:

On the local machine - Windows OS and Visual COBOL.
On the remote machine - Windows OS and either Visual COBOL or COBOL Server.

Note: See Product Information for details about the system and software requirements for Visual COBOL and COBOL Server.

Build the Source Code on the Local Machine

Build the COBOL Snake sample on the local machine as follows:

Start the Visual COBOL Samples Browser. If you need instructions, see To start the Samples Browser.
Click Games in the list in the left-side pane.
Select COBOL Snake and click Open Sample in Visual Studio.
In Solution Explorer, right-click the project and select Properties.
Click the COBOL tab.
Ensure Configuration is set to Active (Debug).
Click Build > Build Solution.

Copy the Application to the Remote Machine

From your local machine copy the contents of the debug subfolder in your project directory and any data files used by the application to the remote machine as follows

In Solution Explorer, right-click the project and choose Open Folder in Windows Explorer.
Navigate to the \bin\x86\debug subfolder in the project directory.
Copy COBOLSnake.exe and COBOLSnake.idy.
On the remote machine, create a folder for storing the demonstration files such as c:\tutorials\remotedebug.
Copy the files to the new folder on the remote machine.

Note: Make sure you synchronize any changes you make to the application locally with the remote machine by uploading an up-to-date version of the .exe and the .idy files.

Open a Port for Remote Connection

To do this, you need to start a cobdebugremote or cobdebugremote64 process at a specified port as follows:

On the remote machine, start a COBOL command environment by clicking Start > All Programs > Micro Focus Visual COBOL> Tools > Product Name Command Prompt (32-bit) or Start > All Programs > Micro Focus COBOL Server 2017 > Tools > Product Name Command Prompt (32-bit).
Start the cobdebugremote or cobdebugremote64 process by typing one of the following commands at the prompt:
32-bit:
```
cobdebugremote port=nnnn repeat
```
64-bit:
```
cobdebugremote64 port=nnnn repeat
```
where nnnn is the port number on which the daemon will listen for connection requests. It is recommended that you use a port number greater than 1024 as numbers below this one are for system use. For example, you can use a port number such as 56789.

The console displays a message that the remote machine waits for a connection at the specified port.
Note:
- Note that cobdebugremote uses the repeat option. This keeps the cobdebugremote process running and listening for another connection after you have stopped debugging. If you do not specify this option, the process exits after the debug session has completed.
- You can start the cobdebugremote or cobdebugremote64 process without specifying a port number by entering only cobdebugremote or cobdebugremote64 at the command line. This opens a random port for remote connections. Check the console to see which number has been assigned for the connection.
- Normally, after the debug session has been completed, cobdebugremote or cobdebugremote64 stops and closes the remote connection. The process would have to be started again to allow a new debug session. The repeat option helps avoid doing this manually and when the debug session has been completed, the cobdebugremote or cobdebugremote64 process starts listening for another connection.

Configure the Firewall on the Remote Machine

Ensure the Firewall on the remote machine allows the Micro Focus Debugger Proxy V2.
Alternatively, you can open a TCP port in the Firewall for communications. The port number you add should be the one you specified on the command line.

Prepare for Remote Debugging on the Local Machine

Specify properties for remote debugging:
1. In Solution Explorer, right-click the Properties folder of the project and click Open.
2. Click the Debug tag.
3. Click Start external program.
4. In the adjacent field, enter the path to the application executable on the remote machine and the filename: c:\tutorials\remotedebug\cobolsnake.exe.
5. On the same page, check Use remote machine.
6. Type the name or the IP address of the remote machine in the adjacent field.
7. Specify the port number in the respective field.
8. Click File > Save All.
Configure the Symbols Paths:
1. Click Debug > Options.
2. In the left-hand pane, click Debugging > Symbols.
3. Click and enter the path to the symbols (.idy) file on the remote machine: c:\tutorials\remotedebug.
  Note: If your program includes more than one COBOL programs (and .idy files respectively), you need to configure the Symbols Paths for each .idy file on the remote machine.
4. Click OK.

Debug the Application

On your local machine, click Debug > Start Debugging or Debug > Step Into.
Visual Studio on your local machine enters a debug session. On the remote machine, the cobdebugremote or cobdebugremote64 process displays a message in the console that a connection with your local machine has been established. The application on the remote machine starts running.
On your local machine, click Debug > Windows > Modules in the IDE.
The Modules window displays the .dll and .exe files that are used by the application. This can help you see whether the symbols are loaded for debugging or if the program is using the files you expect.
Debug the application in the usual way.

Stop Debugging

On your local machine, click Debug > Stop Debugging in the IDE.
On the remote machine, if you wish to close the cobdebugremote or cobdebugremote64 process and the port, type Q in the cobdebugremote console.
Before you can debug again, you need to restart the cobdebugremote or cobdebugremote64 process on the remote machine.