Configure PL/I Debugging

Note:
  • This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.

A launch.json file is used to configure the PL/I debugger. Visual Studio Code generates a launch.json under the .vscode folder in your workspace. The generated file contains two sections: one that configures debugging for launching scenarios and another that configures debugging for attach to process.

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:
id
Waits for and then attaches to the next PL/I program which calls PLITEST with the identifier you specify in the ID field as an argument.
enterpriseServer (required)
The Enterprise Server application debugging options. The value consists of servername and serverAddress plus 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
  • 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 (.stb) 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.
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": 0
}
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"
}

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

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
  • is64Bit
  • cwd
  • pathMappings
  • sourceFileMap
  • useConsole
Parent topic: Debugging