Debug Launch Configurations (Native COBOL)

Note:
  • This functionality requires a licensed version of a Rocket Visual COBOL or Rocket Enterprise Developer product on the same machine. See Installation for details.
  • The following information applies to native COBOL code.

You can create additional launch configurations for various debugging scenarios in the launch.json file:

Set or change the following options to control Visual Studio Code's behavior during debugging.

Launch options

program (required)
The full path to the executable the debugger will launch.
or
waitForAttachment (required)
The debugger waits for the program to start in a separate process before attempting to attach to it. The value is an object containing:
directory
Waits for and then attaches to the next COBOL program that is launched with its working directory set to either the folder specified or a subfolder of it.
returnToWait (optional)
Return the debugger to a waiting state when the program being debugged exits.
or
id
Waits for and then attaches to the next COBOL program which calls CBL_DEBUG_START with the identifier you specify in the ID field as an argument.
or
any
Waits for and then attaches to the next COBOL program which calls CBL_DEBUGBREAK, or is launched with the COBSW environment variable set to +A (Windows only).
returnToWait (optional)
Return the debugger to a waiting state when the program being debugged exits.

or

enterpriseServer (required)
The Enterprise Server application debugging options. The value consists of serverName and serverAddress plus optional additional values to control the debugger.
serverName (required)
The name of the server.
serverAddress (required)
The debug listener address for the server to be debugged.
debugType (optional)
The type of application to debug. It must be one of the following:
  • jcl
  • web
  • any
options (optional)
Any of the following:
  • web

    where the Web Services options are:

    clientIP
    Leave this field empty to enable debugging from any IP address. Specify an IP address to allow debugging only from it.
    serviceName
    Specify the address of the web service to debug. Enter the address and any specific operation that is part of the web service in the format http://namespace/ServiceName#OperationName.
stopOnEntry
Automatically pause the program after launching.
console
Select the launch target for debugging from one of the following values:
  • externalConsole - this is the default value.
  • integratedTerminal
  • externalTerminal
Note: To use this option, you must have a licensed Visual COBOL or Enterprise Developer product, version 10.0 or later, installed on your machine.
trace
Enable logging of the Debug Adapter Protocol.
cwd
The working directory of the program. Default is the current workspace root.
args
Command line arguments passed to the program. The value can be either a single string or an array of strings.
symbolSearchPaths
Paths to search for program symbol (.idy) files.
env
Environment variables passed to the program. The value can either be an array of name and value objects: 
"env": [
{"name": "VAR1", "value": "value1"},
{"name": "VAR2", "value": "value2"}, 
]
or a list of environment variable names and values 
"env": {
"VAR1": "value1",
"VAR2": "value2"
}
envFile
Absolute path to a file containing environment variable definitions. This file has key value pairs separated by an equals sign per line, for example KEY=VALUE.
stopAtStopRun
Suspend debugger at stop run.
stepOverIgnoreInline
Step into inline PERFORM statements when using Step Over.
programBreakpointMainEntryOnly
Program breakpoint on main entry point only.
remoteDebug
When present, this tells the debugger to connect to a remote computer. The value consists of the remote machine name or IP address and the port number that is used by the cobdebugremote or cobdebugremote64 process. 
            "remoteDebug": {
                "machine": "machine name or IP",
                "port": nn
            }
is64Bit
Indicates whether the debugger is a 64-bit application. Defaults to false on Windows and true on Linux.
useConsole
Use a console for screen input/output.
Note: This option is deprecated. Use the console option instead.
pathMappings
When remote debugging, file names provided by the debugger will contain paths on the remote file system which may not exist on the local file system. Adding one or more pathMappings value maps paths from the remote file system to paths on the local file system allowing the source files to be opened. 
            "pathMappings": [
              {
                    "remote": "remote-path",
                    "local": "local-path"}
            ],
sourceFileMap
Alternative to the 'pathMappings' entry consisting of a list of path mapping values. 
            "sourceFileMap": [
              {
                    "remote-path": "local-path",
            ]
symbolsMustMatchProgram
Require program symbols (.idy) to exactly match the program.

Platform-specific configurations

The above options can be used within predefined platforms.
windows
Include options that are specific to debugging on Windows platforms. For example, to set the program to be run when debugging on Windows: 
            "windows": {
                "program": "${workspaceFolder}/Program.exe"
            }
linux
Include options that are specific to debugging on Linux platforms. For example, to set the program to be run when debugging on Linux: 
            "linux": {
                "program": "${workspaceFolder}/Program"
            }

Attach options

Set or change the following options to control Visual Studio Code's behavior during debugging:

processId (required)
The process ID to attach to. If processId used, do not use processName.
or
processName (required)
The process name to attach to. If this is used processId should not be used.
Some additional options you can specify are as follows:
  • trace
  • symbolSearchPaths
  • stepOverIgnoreInline
  • programBreakpointMainEntryOnly
  • is64bit
  • cwd
  • pathMappings
  • sourceFileMap
  • symbolsMustMatchProgram

Example - enable CTF tracing

In order to enable CTF tracing for the COBOL program being run, you need to add the following setting: 
"env": [ {"name": "MFTRACE_CONFIG", "value": "d:\\trace.cfg" }]

This does not, on its own, result in CTF output in the DEBUG CONSOLE.

If, however, the CTF configuration file has the idedbg emitter set then CTF output will be displayed in the DEBUG CONSOLE. The idedbg emitter is only available on Windows and therefore the output will only be displayed in the DEBUG CONSOLE on Windows.

As an alternative, on Linux platforms the content of the textfile emitter can be viewed in Visual Studio Code as it is written by opening the Terminal and running the tail command using: 

 tail -f <path-to-emitter-file>

For more about CTF Tracing, see the product Help of Visual COBOL or Enterprise Developer.

Parent topic: Debugging