Debug Launch Configurations (Native COBOL)

Note:

This functionality requires a licensed version of a Micro Focus 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:

With launch.json opened in Visual Studio Code, click Run > Add Configuration.
You can add one of the following configurations - COBOL (native): Launch, COBOL (native): Launch - remote, COBOL (native): Launch - Remote-SSH, COBOL (native): Launch - 64-bit, COBOL (native): Attach to process, COBOL (native): Enterprise Server, COBOL (native): Wait for attachment.

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.

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.

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:

cics (default)
ims
jcl
web
any

options (optional)

Any of the following:

jcl
where the JCL options are:

jobName

The name of the job.

jobNumber

The number of the job in the held queue.

stepName

The step that you want to debug.

topLevelProgram

The start program to be used when debugging the application.
cics
where the CICS options are:

user

The CICS user ID that was used to start the application.

terminal

The CICS terminal ID that was used to start the application.

transaction

The CICS transaction for the application.

linkLevelProgram

The CICS invoked program at which to start to debugging.
ims
where the IMS options are:

user

The user ID that was used to when debugging the application.

terminal

The logical terminal ID to be used when debugging the application.

transaction

The transaction to be used when debugging the application.

topLevelProgram

The start program to be used when debugging the application.
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.

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.

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
useConsole
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 Micro Focus Enterprise Developer.