COBOL Language Support enhances the COBOL programming experience on your IDE. The extension leverages the language server protocol to provide autocomplete, syntax highlighting and coloring, and diagnostic features for COBOL code and copybooks. The COBOL Language Support extension can also connect to a mainframe using the Zowe Explorer extension to automatically retrieve copybooks used in your programs and store them in your workspace. COBOL Language Support also supports COBOL programs which interact with Datacom, CICS, and DB2 SQL. An add-on extension which adds support for the IDMS dialect is available on the VS Code Marketplace.
COBOL Language Support recognizes files with the extensions .cob
, .cbl
and .cobol
as COBOL files.
How can we improve COBOL Language Support? Let us know on our Git repository
This extension is a part of the Che4z open-source project. Feel free to contribute right here.
COBOL Language Support is also part of Code4z, an all-round VS Code extension package that offers a modern experience for mainframe application developers, including tools for language support, data editing, testing, and source code management. For an interactive overview of Code4z, see the Code4z Developer Cockpit.
There are no client or server-side prerequisites for COBOL Language Support.
The COBOL Language Support extension is supported on Visual Studio Code and Github Codespaces.
This extension is not compatible with other extensions that provide COBOL support except COBOL Control Flow and the dialect add-ons published by Broadcom. We recommend that you disable all other COBOL-related extensions to ensure that COBOL Language Support functions correctly.
The COBOL Language Support extension only supports IBM Enterprise COBOL. Other versions of COBOL are not supported.
Integrating COBOL Language Support with the Zowe Explorer and Explorer for Endevor extensions let you:
Both Zowe Explorer and Explorer for Endevor are available as part of the Code4z extension pack. A Zowe Explorer zosmf
or zftp
profile with credentials and a connection URL is also required to retrieve copybooks from mainframe data sets.
COBOL Language Support provides the following COBOL syntax awareness features:
Autocomplete speeds up the coding process by intuitively suggesting the most likely variables or paragraphs to follow existing code. The extension provides live suggestions while you type for:
The autocomplete feature is only available in the main COBOL file, not in copybooks.
This feature checks for mistakes and errors in COBOL code. The syntax check feature reviews the whole content of the code and suggests fixes, through syntax and semantic analysis which returns diagnostics on the entire context of the code, not just keywords.
This feature is also enabled for Datacom, CICS, and DB2 SQL keywords and variables.
The extension enables syntax highlighting for COBOL code.
Contrasting colors are used in displayed code for ease of identifying and distinguishing keywords, variables, paragraphs and sections.
The extension enables outline view and breadcrumb view, which show the structure of elements within the program and allow easy navigation between them.
Before you write your COBOL code from scratch, search the snippet library for useful templates.
F1
to open the command palette.You can also insert a code snippet by typing the name of the snippet in your code and clicking on the autocomplete text.
The COBOL Language Support extension also supports user snippets. Add your custom snippets to the COBOL.json
file in your user snippets folder.
Configure the smart tab function in your settings.json
file to set tab stops at specific columns in the editor window. The cursor stops at these columns when you use Tab and Shift+Tab to move forwards and backwards in the code. You can specify custom tab stops, and use regular expressions to set conditional tab settings for different sections and divisions of the code.
To configure the smart tab feature, open your settings.json
file and change the "cobol-lsp-smart-tab":
parameter.
Tip: You can open your settings.json
file directly from the COBOL Language Support extension settings. Under Cobol-lsp: Smart-tab, click Edit in settings.json.
false
to use the default tab settings for Visual Studio Code.true
to use the default tab settings for COBOL Language Support. This adds extra tab stops for the margins at columns 8, 12 and 73.[0, 7, 20]
sets tab stops at columns 1, 8 and 21 and nowhere else."default":
and "anchors":
.
"anchors":
, specify a JSON element containing any number of parameters of the format "ANCHOR": tab stops
.
ANCHOR
can be a regular expression and corresponds to a string that occurs in the code. tab stops
are an array of integers that specify tab stops. These tab stop settings apply to all lines in the code below the string specified in the anchor until another condition is met."default":
, specify an array of integers that specify tab stops when no condition is met.DATA DIVISION
, after columns 3, 5 and 70 after the line PROCEDURE DIVISION
and after columns 5, 10 and 15 elsewhere.
"cobol-lsp.smart-tab": {
"default": [5, 10, 15],
"anchors": {
"DATA +DIVISION": [1 ,2, 3, 4],
"PROCEDURE +DIVISION": [3, 5, 70]
}
}
Many companies have their own COBOL preprocessors which complement or modify standard IBM enterprise COBOL with custom statements and keywords. In our documentation, we refer to these preprocessors as "dialects".
Dialect add-ons are available to add support for specific language analysis in your COBOL files. Currently an add-on for the IDMS dialect is available on the Visual Studio Code Marketplace.
Dialect add-ons must be enabled in the COBOL Language Support extension settings. To enable dialect add-ons that you install, complete the following tasks:
preprocessor
parameter in a processor group. For more information, see Processor Groups.COBOL Language Support processes dialects in the order you list them in the Cobol-lsp: dialects setting or within the preprocessor
parameter of a processor group. If you list dialects in the wrong order, some pieces of code might be incorrectly processed using the wrong dialect parser and marked as errors.
Set the SQL backend server as either DB2 or Datacom to ensure you use the correct version of the implicit SQLCA
and SQLDA
copybooks. To set the SQL backend server, go to VS Code Settings > User > Extensions > COBOL Language Support > Cobol-lsp: Target-sql-backend. The default setting is DB2.
The COBOL Language Support extension supports subroutines specified in CALL statements if the called program is stored in a local folder in your workspace. The Go To Definition and Find All References functionalities, as well as autocomplete, are extended to work for names of subroutines.
To enable subroutine support, specify the paths of folders containing subroutine files in your workspace extension settings.
If you specify your subroutine folders using absolute paths or paths containing ../
or ./
, the subroutine folders are not watched for changes. You might need to resolve names of recently added files in your code manually.
The COBOL Language Support extension supports copybooks used in your source code that are stored in a local folder in your workspace. If you have copybooks stored in mainframe data sets or USS directories, you can use a Zowe Explorer profile to automatically download them from the mainframe to your workspace.
To enable copybook support, you specify the folders and data sets that contain copybooks used in your project in the workspace settings. When a copybook is used in the program, the folders and data sets are searched in the order they are listed for files and members that match the name of the copybook. If a copybook with the same file name is located in both a local folder and a remote location, the one in the local folder is used.
Copybook support features are disabled for files stored in the folder .c4z/.extsrcs in your workspace. If you also use the Debugger for Mainframe extension to debug your COBOL programs, you might have some files stored in this folder.
Configuring copybook support on COBOL Language Support also enables copybook support features of the COBOL Control Flow extension.
COBOL Language Support supports the following copybook types:
COPY
statement.COPY
statement. Datacom copybooks must be extracted to a mainframe data set or local folder for use in COBOL Language Support. For more information, see the Datacom documentation.You can store your copybooks locally in folders in your workspace and specify those folder paths in your workspace extension settings.
searches all subfolders named "copybooks" in subfolders of your workspace root, while the path
copybooks/*searches all subfolders one level below the
copybooks` folder in the workspace root. For more information on available wildcards, see the Glob Primer.cpy
and .copy
.If you specify your copybook folders using absolute paths or paths containing ../
or ./
, the copybook folders are not watched for changes. You might need to resolve names of recently added copybooks in your code manually.
To resolve copybook names manually, hover over the copybook name with the error underline, select Quick Fix... and Resolve copybook.
You can also set up automatic copybook retrieval from the mainframe to download copybooks from mainframe data sets and USS directories to your workspace.
.cpy
and .copy
.Copybooks that you retrieve from mainframe data sets are stored in your VS Code global storage folder.
We recommend that you refresh your copybooks from time to time. To refresh your copybooks, press F1 and run the command Clear downloaded copybooks. This command clears the global storage folder so that copybooks are downloaded again from the mainframe.
When you open a COBOL file using Explorer for Endevor, COBOL copybooks that are specified in the Endevor element processor group are automatically downloaded to your VS Code global storage folder.
The extension setting Cpy-manager: Endevor-dependencies determines how copybooks are retrieved from the mainframe when you open a COBOL file in Explorer for Endevor. This setting has the following options:
The extension includes the following copybook support features:
Syntax and semantic analysis are enabled for keywords, variables, and paragraphs across all copybooks used in the COBOL file, to ensure and maintain compatibility of copybooks called in code.
The semantic analysis feature takes into account COPY REPLACING
statements which alter the content of copybooks when checking for errors.
Syntax coloring is automatically enabled for copybook files with the extension .cpy
and .copy
, as long as they are used in the main COBOL file. You can also select the COBOL Copybook language mode to enable syntax coloring for copybook files.
The Find All References and Go To Definition functionalities are extended to work for occurrences of copybook names, variables and paragraphs in the main COBOL file.
Use processor groups to link programs with specific dialects, SQL backend settings, copybook extensions, compiler options, and local folders containing copybooks. You define processor groups in a proc_grps.json
file and associate processor groups with programs in a pgm_conf.json
file. Create both of these files in a /.cobolplugin
folder in your workspace root.
The proc_grps.json
file is formatted as an array of JSON elements, with one JSON per processor group. Each processor group can contain the following elements:
Specify preprocessors to enable specific dialects and SQL backend settings for the programs linked to a processor group. You can also specify libraries that contain copybooks that use a specific dialect.
Each preprocessor is formatted as a JSON element containing a name, which identifies the type of preprocessor, and other parameters which specify the configuration. As the preprocessor
element of the proc_grps.json
file is an array, you can specify more than one preprocessor per processor group.
The SQL backend preprocessor is used to override the SQL server that you specify in the extension settings. This preprocessor has the following parameters:
A dialect preprocessor can be used to enable a COBOL dialect for a particular processor group and specify libraries which contain copybooks written in that dialect. Dialects that you enable in processor groups take priority over those that you specify in the extension settings. A dialect preprocessor has the following parameters:
The program configuration file, pgm_conf.json
, links programs to processor groups. The program configuration file has the following format:
{
"pgms": [
{ "program": "PROGRAM1", "pgroup": "GROUP1" },
{ "program": "PROGRAM2", "pgroup": "GROUP2" },
]
}
Each element contains the following parameters:
proc_grps.json
.Using the example pgm_conf.json
file above, the following proc_grps.json
example enables the following:
{
"pgroups": [
{
"name": "GROUP1",
"libs": [
"LIB1", "LIB2"
],
"copybook-extensions": [
".cpy", ".copy"
],
"compiler-options": [
"QUALIFY(EXTEND)", "XMLPARSE(COMPAT)"
]
},
{
"name": "GROUP2",
"preprocessor": [
{
"name": "IDMS",
"libs": [
"LIB3", "LIB4"
]
},
{
"name": "SQL",
"target-sql-backend": "DB2_SERVER"
}
],
"libs": [
"LIB5", "LIB6"
]
}
]
}
To enable troubleshooting logs for the LSP server, specify a value for the parameter cobol-lsp.logging.level.root in the extension settings. Specify one of the following values:
These values are ordered from returning the least information ("ERROR"; errors only) to the most information ("ALL"; all details).
To view troubleshooting logs, open the output panel and select COBOL Language Support from the drop-down menu.
The COBOL Language Support extension is made available to customers on the Visual Studio Code Marketplace in accordance with the terms and conditions contained in the provided End-User License Agreement (EULA).
If you are on active support for Brightside, you get technical assistance and support in accordance with the terms, guidelines, details, and parameters that are located within the Broadcom Working with Support guide.
This support generally includes:
Note: To receive technical assistance and support, you must remain compliant with “Working with Support”, be current on all applicable licensing and maintenance requirements, and maintain an environment in which all computer hardware, operating systems, and third party software associated with the affected Broadcom software are on the releases and version levels from the manufacturer that Broadcom designates as compatible with the software. Changes you elect to make to your operating environment could detrimentally affect the performance of Broadcom software and Broadcom shall not be responsible for these effects or any resulting degradation in performance of the Broadcom software. Severity 1 cases must be opened via telephone and elevations of lower severity incidents to Severity 1 status must be requested via telephone.
The extensions for Visual Studio Code developed by Broadcom Inc., including its corporate affiliates and subsidiaries, ("Broadcom") are provided free of charge, but in order to better understand and meet its users’ needs, Broadcom may collect, use, analyze and retain anonymous users’ metadata and interaction data, (collectively, “Usage Data”) and aggregate such Usage Data with similar Usage Data of other Broadcom customers. Please find more detailed information in License and Service Terms & Repository.
This data collection uses built-in Microsoft VS Code Telemetry, which can be disabled, at your sole discretion, if you do not want to send Usage Data.
The current release of COBOL Language Support collects anonymous data for the following events:
Each such event is logged with the following information: