DAP Magic — Modern Debugging Experience using VS Code & other IDEs
Changing user experiences across tools and platforms is frustrating and time consuming and this applies to troubleshooting and debugging which are two important diagnostic methods where wasted time can directly impact the business.
In this blog we describe next generation debug technology using the Debug Adapter Protocol [1] for mainframe code, therefore keeping the user experience the same across languages or platforms.
Debug Adapter Protocol (DAP)
In a previous blog we described the Language Support Protocol (LSP) which brings the magic of modern editing capabilities in modern IDEs for Mainframe Languages (COBOL, HLASM, REXX and JCL). To extend the consistent experience to debugging we need more magic— Debug Adapter Protocol. Before DAP was introduced, debugging support in dev-tools was provided for each language-debugger separately [see Figure-1]. DAP abstracts communication between the dev-tool’s debugging user experience and the language debuggers. To make this happen we need a Debugger Adapter [2], which adapts the debugger to the Debug Adapter Protocol. This means any dev-tool can connect with any number of different debuggers via debug adapters. Also, using the DAP approach, any dev-tool vendor can implement their debug adapters and publish them into the marketplace as freely available extensions. E.g. Installing the Debugger for Mainframe extension onto your VS Code editor enables you to debug COBOL programs there using all of the modern UI debugging capabilities of the IDE.
DAP Architecture
DAP defines the protocol to abstract the way of communication between a dev-tool and a debugger (or runtime). Any dev-tool (e.g. VSCode) implements a generic-debugger based on DAP which communicates with the debugger with the help of a dev-tool independent component — a Debug Adapter.
DAP Architecture offers flexibility, separating the user interfaces in the front-end and debugging functionality (breakpoints, log points, watch expressions, etc.) provided by the back-end. A debugger extension, installed onto the dev-tool, is a packaging container for the debug adapter. During debugging, the debug adapter provides (and also aggregates) some necessary information such as the list of languages supported by the debugger, the JSON schema for the debug configuration, and the default setup for the launcher. It can also modify, add or remove debug attributes, change debug type and more. The debugger UI uses this information for managing breakpoints for those languages, verifies the configuration and provides intellisense, and more.
When a client launches a new debug session, a new and separate process is created for the Debug Adapter, which communicates via stdin and stdout using the base protocol. The base protocol exchanges messages that consist of a header and a content. The client sends to the adapter an initialization message in order to get the initial information, then a normal sequence flow starts. When a debug session is terminated on the client, the sequence of events is slightly different based on whether the session has been initially “launched” or “attached”. See flow diagram below.
Broadcom’s Debugger Extension — Debugger for Mainframe
Based on the above DAP architecture, Broadcom provides such an adapter, the Debugger for Mainframe extension for VS Code and Eclipse Che. This is a next-generation debugger for COBOL applications running in CICS and a debugging interface to an interactive testing and debugging product for CICS applications, CA InterTest™ for CICS. This plugin offers a modern debugging experience for mainframe application developers with features like conditional and unconditional breakpoints and log points for COBOL programs with a file extension of .cob and .cbl.
Debugger for Mainframe can be downloaded for free from the VS Code Marketplace as a standalone extension, or as a part of the Code4z extension package. The Code4z package contains several extensions for developers working with z/OS applications, and also for system administrators and other users working with z/OS, and is suitable for all levels of mainframe experience. It is also available as a basic stack in Eclipse Che version 7.6.0 and above, with no installation needed.
Using Mainframe Debugger in VS Code Editor
In your VS Code extension tab, search for “Debugger for Mainframe” extension and install the extension. Or as an alternative, watch on youtube how to install and use this modern debug experience.
To start debugging, open your workspace and configure your connection to CA InterTest using the launch.json file with provided config-details.
Once the configuration is ready, start the debugger via the launcher, then provide your mainframe password to connect to CA InterTest on the mainframe. From your CICS region open a COBOL file you want to debug and put some breakpoints on it. Meanwhile, open an emulator session and start the CICS transaction in your CICS region. As you see, the debugger is already triggered in VS Code.
And now you are debugging your COBOL program in VS Code editor using that installed extension. You can see local variables, see error messages e.g. Variable TASKNUM has invalid data format.
Also, you can evaluate or update a variable’s value and resume execution of the program. Enjoy the modern debugging experience here.
Using Mainframe Debugger in Eclipse Theia Editor
Eclipse Theia is a cloud-native Web IDE, and the default editor for Eclipse Che [4]. Our Debugger for Mainframe extension is tailored to be used with the Theia Editor packaged via a Che devfile, which consists of all required plugins. Then using the Theia editor you can follow a similar set of debug steps as you did in VSCode, then start using the full power of the debugger-extension.
Summary
Applications developed using LSP (provides language intelligence) or DAP (provides debugging) ensures a common experience. If you provide software extensions (plugins, adapters …) using both LSP and DAP then your dev-tools (Eclipse Theia, VS Code, or other IDE) become familiar tools for any developer who wants to program in any language.
For further questions you may contact us on Slack: che4z.slack.com
References
[1] https://microsoft.github.io/debug-adapter-protocol/
[2] https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/
[3] https://code.visualstudio.com/blogs/2018/08/07/debug-adapter-protocol-website/
[4] https://www.eclipse.org/che/docs/che-7/eclipse-che4z/
Open Source repository: https://github.com/eclipse/che-che4z
