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.
- 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.
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
- Click this to specify a specific remote file system folder located on the remote project's host. This option is only available if you have set up a remote project and selected it in the
COBOL Project field on the
General tab.
- 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.
