Easytrieve Language Support Extension

Easytrieve language support empowers developers with modern, shift-left capabilities that eliminate repetitive, manual tasks and fuel productivity. The modern day developer, relatively new to the mainframe can now work with mainframe applications with familiar, open-source tooling.

The extension leverages the language server protocol to provide features such as autocomplete, syntax coloring, hover, Go to definition, as well as diagnostic features for Easytrieve code and its macros. The Easytrieve VS Code extension connects to the mainframe using the Zowe z/OSMF profile to perform a number of operations such as JCL submission, retrieving the macros used in an Easytrieve program and storing them locally on your PC.

The extension also has the capability to generate JCLs to wrap around your Easytrieve program to execute on Mainframe.

There are other VS Code extensions from Broadcom and the Open Mainframe project which complement and complete the Easytrieve extension. Broadcom extensions include Explorer for Endevor, Bridge for Git, and JCL Language Support. You can also leverage the Zowe Explorer extension available from the Open Mainframe Project. It may be necessary to install and configure one or more of these extensions depending on the other applications you are running and the setup. For example, to use Endevor as your source code management in sync with GitHub requires the Bridge for Git extension. To access code directly from Endevor requires Explorer for Endevor. For more information about other extensions that can be used with the Easytrieve Language Support Extension, see Broadcom Support.

Easytrieve Language Support recognizes files with the extension .ezt as Easytrieve files, .mac for Easytrieve macros and .def for option table definition.

For a high level overview of the Easytrieve Visual Studio Code Extension as well as instructional videos about how to use many functionalities of the extension, see Broadcom’s Educate YouTube channel.

Features

The following features are available through the Easytrieve Language Support Extension:

Source code validation

Code in .ezt files is validated by the modified Easytrieve compiler. As such, error and warning messages are the same as when the source code is compiled under the same conditions. These conditions may include a specified options table, or database connection used by the Easytrieve compiler.
Syntax coloring

An Easytrieve program developed using this extension is syntax colored. The coloring schema uses VScode standards.
Hover

The Hover functionality provides additional information to symbols (fields and filenames). Use the hover function by placing the cursor over the field name or file name. Information may be limited if the symbol is not defined in the edited file (i.e. symbol is defined in a macro).
Go to definition

The Go to definition feature makes it possible to jump to a specific location where a symbol (field or filename) is defined. This function is limited to a currently edited file. This feature is not available for symbols defined in a macro.
Autocompletion (context-specific)

Autocompletion can be used only when a colon : is used after a filename. Enter ctrl + space to see a list of all fields defined for the file.
Options table editing

This feature makes it possible to perform error checking of the options table. Following any change in the options table, all the opened and validated .ezt files are revalidated.
Local build and run task

When using the Windows version, the code created using VS Code can be executed directly from VS Code on a local PC and the output can be viewed using VS Code.
Mainframe communication tools

Mainframe communication tools make it possible to execute an Easytrieve program on the mainframe. The created Eastrieve program can be uploaded to the mainframe by using the Upload EZT to mainframes feature. The dataset reference is subsequently used in the generated JCL.
Easytrieve Language Support - Generate JCL

This feature makes it possible to execute an Easytrieve program on the mainframe.

Installing

After installing the extension through the Visual Studio Code Marketplace, basic extension functionality is available.

To activate the extension, open a file with the.ezt extension. Alternatively, you can activate the extension by selecting the Easytrieve language.

For full functionality, the installation and configuration of other tools or extensions may be required.

Other tools which can work in combination with the extension include the following:

Zowe CLI
Zowe Explorer (Open Mainframe Project extension)
JCL Language support (Broadcom VS Code extension)
DB2 (client, connect, server)
Easytrieve for Windows
SSH client for VS Code (or one of the available from the list of VS Code extensions from VS Code marketplace, that would allow you to communicate with the Linux server itself) in order to compile and run an Easytrieve program on a remote Linux system

Note: Currently, the Easytrieve Language Support Extension is only available on Windows 10, and only supports ODBC and DB2 databases. The extended printer definition is not supported on the current version of the Easytrieve Language Support Extension.

Configuring

The extension UI provides several fields in which you can specify your configuration settings. For more information about how to configure settings, see Visual Studio Code User and Workspace Settings.

The following settings are available through the Easytrieve Language Support Extension:

Language Server Settings

The following Language Server Settings can be customized using the extension:

Options Table

Specify where to store options as an input for the compiler. If the value is a relative path, this value is evaluated against the first root of the workspace. Update this field when other values other than default values are applied in the options table for validating and parsing the code by the extension.

The default is empty. This results in a W703 warning (missing options table).

In the Options Table field, enter the path to the file containing the options table definitions in text format. Use the .def extension.

Important: A .def file that uses CRLF at the end of the line of characters can prevent the Language Server from running properly. To prevent this problem from occurring, ensure that the end of the line sequence in *.def is set to Unix style (LF).

Notes:

Use the same format as is used as input for etopload. For more information, see Updating the Table.
Ensure to include an empty line at the end.

Macros

In the Macros field, provide a list of directories (absolute path) or DSN with macros separated by semicolon. An absolute path is treated as a local directory. Other values other than absolute paths are treated as a dataset name.

The default value is empty.

Click refresh macros in the status bar to download macros from datasets.

Alternatively, you can execute the following line in the command pallet:

Easytrieve Language Support - refresh macros

For more information, see the Macro Search Directory Parameter in the Easytrieve documentation.

eztsql

Configuring eztsql configures your database connection type. To setup the database itself, follow the documentation specific to your database. This specification ensures that the database connection is used during validating and parsing of the Easytrieve code. This value controls the type of database connection (EZTSQL)

Possible values for this field are the following databases:

ODBC
DB2

The default database connection is ODBC.

Notes:

The meaning of the EZTSQL field is the same as the meaning of the EZSQL environment variable used in Easytrieve itself.
After changing this value, be sure to restart the language server by restarting VS Code.

Db Name Override

ODBC Datasource name or Database name for SSID PARM Override overrides the database name (e.g. SSID) specified in the source code. This override is useful when the local database used by the language server name differs from the one used on the target system (used during execution).

The default of this setting is empty.

Note: After changing this value, the language server requires a restart of VS Code.

Zowe Profile

Specifying this profile enables communication between VS Code and the mainframe. This profile is used for the following executions on the mainframe:

Upload of generated JCLs
Easytrieve program upload
macro upload/download

To use the default profile, leave this field empty.

For more information, see Zowe Explorer Profiles.

For more information on creating a z/OSMF profile, see Creating a zosmf profile.

Jcl settings

The Jcl generate functionality makes it possible to create JCLs required to execute the Easytrieve program on the mainframe. These JCLs are built using the JCL settings present in the Easytrieve Language Support Extension settings.

The following options apply to the Jcl generate functionality. To generate a JCL for the Easytrieve code, specify the following:

jobcard

A freeflow Jobcard field for the Easytrieve execution JCL. This could be any freeflow jobcard as specified by the programmer.

//JOB01EZT JOB (123456789),'EZTPRGMR' is the default setting.

This jobcard is inserted in the beginning of the generated JCL.
cbaaload

Specifies the Step libraries for Options table creation and Easytrieve execution. Multiple libraries must be delimited by semicolons. The specified libraries are used in the options table creation step as well as the Easytrieve compile and go step of the generated JCL.
ezoptbl

Specifies the existing options table dataset residing on the mainframe. This is an options table for the generated JCL for Easytrieve execution. Specify a valid pre-created/compiled options table.
- When ezoptbl is present, the JCL generate feature generates only a compile and go step of the Easytrieve program.
- When ezoptbl is not present, theJCL generate feature also adds an options file creation step to the generated JCL.
The options for the options table are recovered from the Windows options file if ezoptbl is present. If the Windows options file is not specified, the Easytrieve default options are used.
jobparm

Specifies the Jobparm for the Easytrieve execution JCL.

Example:

/*JOBPARM SYSAF=*

The default is set to empty.
eztdsn

Specifies an existing dataset where to upload the created Easytrieve programs. Specify DSN for Easytrieve programs (*.EZT files) to be uploaded to the mainframe. Specify this value to upload Easytrieve code to a separate mainframe dataset and to refer the dataset in the generated JCL. When eztdsn is not specified, the Easytrieve program is placed in-line with the generated JCL.

The default is set to empty.
jcldsn

Specifies an existing dataset where to upload the generated JCL. Specify JCLDSN for the generated JCL (generated *.JCL files) to be uploaded to the mainframe from VS Code.

The default is set to empty.

Configuring Eastrieve Report Generator for Windows (Optional)

To execute the Easytrieve code locally on Windows, see Install Easytrieve for Windows.

Note: Configuring Easytrieve Report Generator for Windows is required for the local-build and run task.

Execute your Easytrieve Program on the Mainframe

To Execute the Easytrieve program on the mainframe, generate a JCL using the JCL generate feature. Supporting DD statements like Input Output (IO) files and JCL comments which are specified in JCL format can be added to the generated JCL in one of three ways:

Specify IO files, JCL comments and/or DD statements in the <Easytrieve_program_name>.dsn file within the workspace

Example:

For the Easytrieve program employee.ezt, the input file salary is specified in JCL format in the employee.dsn file.
```
//THIS IS JUST A COMMENT
//SALARY    DD DSN=SITEID.DATE.SALARY,DISP=SHR
```
Specify the IO files, JCL comments and other DD statements in the user prompt which is displayed after the Easytrieve Language Support - Generate JCL contextual option. To use this option, right-click on the *.ezt file display. (This option overrides the first option.)

Note: Leave the User Prompt empty and press Enter to continue generating the JCL with the IO files specified on the <Easytrieve_program_name>.dsn file.
Specify common DD statements and JCL comments to the default.dsn file. These statements and comments are applied to every JCL generated within the workspace.

Upload Easytrieve Programs to the Mainframe

After generating the JCL, if the Eztdsn setting is specified with a valid dataset name, the dataset name is referenced for the Easytrieve source in the generated JCL. To have a valid reference to the dataset and program member, it is necessary to upload the Easytrieve program to the specified dataset in the mainframe.

To upload the Easytrieve program to the mainframe, select the contextual option Easytrieve Language Support - Upload EZT to mainframes.

If a dataset name is specified in the Jcldsn setting, the generated JCL is uploaded to the mainframe.

Note: Ensure that Zowe profile is configured to upload EZT and the JCL to the mainframe.

Options for Use with Easytrieve on Distributed Platforms

The following options control the syntax check of SQL statements of the Easytrieve Report Generator application program. These options are used to set the level of the syntax check for Easytrieve programs.

Note: These options are new compiler options for the Language Server and are currently only available in the extension.

MFEXEC {Y|N}

Specifies the syntax check for SQL statements to execute on z/OS. This option is only applicable for distributed platforms.

Setting MFEXEC to Y allows SQL statement syntax check specifically to z/OS execution.

Setting MFEXEC to N does not perform an SQL statement syntax check specific to z/OS execution.

The default value for MFEXEC is set to Y.
SQLCHK {Y|N}

Specifies the syntax check of SQL statements. This option is only applicable for distributed platforms.

Setting SQLCHK to Y allows the SQL statement syntax check at compile time for DB2, and reports errors if any.

Setting SQLCHK to N does not perform any SQL statement syntax check at compile time for DB2.

The default value for SQLCHK is set to Y.

For more information, see Create or Modify an Options Table in the Easytrieve documentation.

Technical Assistance and Support for Easytrieve Language Support Extension

The Easytrieve 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 Easytrieve Report Generator, 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:

Telephone and online access to technical support
Ability to submit new incidents 24x7x365
24x7x365 continuous support for Severity 1 incidents
24x7x365 access to Broadcom Support Online
Interactive remote diagnostic support

Technical support cases must be submitted to Broadcom support in accordance with guidance provided in “Working with Support”.

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.

Tip: To post, vote, and comment on enhancement requests, visit Broadcom Ideas