IBM IMS® Explorer for VS Code

IMS Explorer for VS Code provides modern development practices and simplifies complex IMS development tasks using Visual Studio Code.

Designed for application developers, database administrators, and system programmers, IMS Explorer for VS Code provides built-in features to access IMS inside Visual Studio Code IDE. By combining multiple activities into one environment, IMS Explorer for VS Code promotes modern development practices and simplifies complex IMS development tasks. IMS Explorer for VS Code 1.2.0 supports the following actions:

• Create and edit projects, driver definitions, and database connections.
• Connect to IMS Catalog and browse IMS databases.
• View PSB, DBD, DDL sources, segments and fields of your database.
• Visualize DBDs and PSBs for IMS database connections and IMS projects.
• Access IMS data with SQL queries.
• Execute IMS Type 1 and Type 2 commands and view command output and history.
• Edit, add, move, and delete DBD segment fields within IMS projects.
• Use a local IMS Explorer project as the metadata source for an IMS connection profile.
• Connect to IMS databases that use multi-factor authentication (MFA).
• Use advanced search to find referenced DBDs and PSBs from the table views.

See Capabilities below for more details.

View full documentation and additional information in the IMS Explorer Github repository. Engage in the community forum for announcements of latest updates, provide feedback, submit questions, polls or request for ideas.

Table of contents

• License
• Prerequisites
• Installing
• Extension settings
• Configuring IMS Workspaces
• Configuring Java
• Capabilities
• Support

License

• The license for the files managed in this repository, which may consist of files for issues, discussion items and education collaterals is in the file LICENSE.
• The license and notices files for the IMS Explorer for VS Code offering can be found in the product-licenses folder.

Prerequisites

Review the IMS Explorer for VS Code License Agreement and Third Party Notices before downloading.

The following software requirements must be met to run IMS Explorer for VS Code.

• Microsoft VS Code version 1.105.0 or later.

• Java SDK or JRE version 21 or later - 64 bit: The language servers included in this extension are implemented in Java, and require a 64-bit Java SDK or Runtime in order to start successfully. Examples of supported Java runtimes include the following:
  • Version 21 of IBM's Semeru Runtime that can be downloaded here.
  • Oracle Java 21.
  • OpenJDK.
  • Newer versions of Java should also work, but IMS Explorer for VS Code is developed on and tested for Java 21.

Installing

The following instructions describe how to install the IMS Explorer for VS Code extension.

1. Install Visual Studio Code

IMS Explorer for VS Code requires VS Code 1.105.0 or later. Download VS Code: https://code.visualstudio.com/

Tip: Microsoft’s Visual Studio Code for Java Installer can automatically install VS Code and a Java SDK.

2. Install the IMS Explorer for VS Code Extension

There are several ways to download and install IBM IMS Explorer for VS Code. You can install it directly from the VS Code Marketplace website or within the VS Code editor. Alternatively, you can download a ZIP of the extension from the IBM Mainframe downloads with provided code signing signature files that you can use to verify the integrity of the downloaded files.

Installing IBM IMS Explorer for VS Code from the VS Code marketplace

1. Open Visual Studio Code.
2. Go to the Extensions panel. You can do this by clicking View > Extensions.
3. Search for IMS Explorer for VS Code.
4. Select the page that features the IBM IMS Explorer for VS Code and click Install.

Installing IBM IMS Explorer for VS Code from a VSIX file

You can also download the IBM IMS Explorer for VS Code extension from the IBM Mainframe downloads website. Here, you can download the extension file directly. Use the following steps in VS Code to install the VSIX file manually.

1. Unzip the downloaded zip file.
2. Open the README.txt file in a text editor and follow the steps described there to verify the individual files with the provided code signing signatures.
3. To install the ims-explorer-for-vscode-<version>.vsix file in VS Code, click the Extensions icon in VS Code's activity bar to open the Extensions view.
4. Click the ... icon in the Extensions view's upper-right corner to reveal a drop-down menu of more actions.
5. In the drop-down menu that appears, click Install from VSIX.
6. Use the file picker that pops up to navigate to and select the VSIX file you downloaded, and then click Install.
7. The extension should be installed from the VSIX file.

Extension settings

Configurations can be made in VS Code Extension settings in order to specify the following:

• Specific Java installations used for IMS connections
• JVM arguments for the IMS Connection
• Additional JAR files for IMS connections
• Logging level for IMS Explorer logs
• Storage location for extension data

Configuring IMS workspaces

Before getting started with an IMS project, ensure that the desired workspace for your IMS projects has been specified using the IMS Workspace status bar option. This option determines the location for the ims.connections.json file, and can provide a common location for IMS project files to be shared in source control.

Connection configuration options

The ims.connections.json file supports additional configuration parameters for each connection:

Show IMS Catalog metadata

You can control the visibility of system-level IMS catalog DBDs and PSBs (those starting with the DFSC prefix) by setting the showIMSCatalogs parameter in your connection configuration in the ims.connections.json file.

Auto-commit behavior

SQL queries executed through IMS Explorer for VS Code use auto-commit mode by default. This means that each SQL statement is automatically committed immediately after execution.

Note: Auto-commit is always enabled and cannot be disabled. All SQL operations are committed automatically.

Configuring Java

The IMS Explorer for VS Code extension utilizes VS Code user settings to configure Java. These settings allow you to select the specific installation of Java to pick, in case you have several installations. Certain settings, such as how much memory you want the IMS Explorer for VS Code extension language servers to use, must be set at the JVM level.

Selecting the Java installation to use

IMS Explorer for VS Code extension scans the following locations, in the order specified, for the first Java installation that is at least Version 21 and 64-Bit to be used. If the target Java fails to meet requirements, the remaining target locations will be scanned:

1. The ims.explorer.connection.property.javaHome VS Code user setting.
2. The java.jdt.ls.java.home VS Code user setting.
3. The JAVA_HOME environment variable.
4. The PATH defined for the environment in which IMS Explorer for VS Code runs (i.e. your default Windows or macOS path)
5. A typical platform-specific location. For example, on MacOS it will execute the /usr/libexec/java_home -V and on Windows the where java.exe commands to locate a valid Java installation.

Note that the methods at the end of the list require a significant amount of time as they are executing programs on your system. To improve startup times you should consider user settings as they provide the best startup performance.

If Java cannot be located check the VS Code Output view's IMS Explorer for VS Code tab for any error and try to fix the problem by either setting the JAVA_HOME environment variable or create an entry in your VS Code user settings.

To define a user setting use the Preferences > Settings menu and either locate the setting in the graphical editor under IMS Explorer for VS Code or edit the setting json file directly by adding an entry as follows using an absolute path name to the Java installation directory.

On Mac:

"ims.explorer.connection.property.javaHome": "/Library/Java/JavaVirtualMachines/jdk21/Contents/Home"

On Windows:

"ims.explorer.connection.property.javaHome": "C:\\Program Files\\Java\\jdk21"

Configuring JVM arguments

JVM arguments are used for configuring connections to IMS. Use the following VS Code Setting example to configure JVM arguments such as memory heap allocation for IMS connections.

"ims.explorer.connection.property.jvmArgs": "-Xms2g -Xmx4g -Denv=prod -Djavax.net.debug=ssl,handshake,trustmanager"

Configuring additional JARs

Use the following VS Code Setting to specify additional JAR files required for IMS connections, such as a customized UDB driver or other dependencies. Separate multiple JAR paths with a semicolon (;). Do not use quotation marks around the paths.

"ims.explorer.connection.property.additionalJars": "/Users/username/Downloads/udb-15.1.31.jar;/Users/username/Downloads/typeconvertars.jar"

Configuring log level

The default Java logging level is info. Use the following VS Code Setting to change the value.

"ims.explorer.logging.level": "INFO"

The logs appear in the IBM IMS Explorer for VS Code output channel.

Configuring IMS Workspace

Use the following VS Code Setting to change the default directory of the IMS Workspace location to store associated extension files.

On macOS: Default directory is the user home directory.

"ims.explorer.property.ImsWorkspace": "/Users/<username>/.vscode/ims-workspace"

On Windows: The default directory is the current user profile directory.

"ims.explorer.property.ImsWorkspace": "C:\\Users\\%USERNAME%\\.vscode\\ims-workspace"

Capabilities

The following sections offer a preview of the features available with the IMS Explorer for VS Code.

Welcome page

A Welcome page is displayed when IMS Explorer for VS Code is first opened, helping users get started quickly with guided steps and links to key features.

IMS connection profiles

Create connections to IMS databases using the IMS connections view. IMS connections can be organized into folders and expanded or collapsed. Two connection profile types are supported:

• IMS Database — connects to an IMS database via the IMS Catalog or a local IMS project as the metadata source.
• IMS Command — connects to IMS to execute Type 1 and Type 2 commands.

Create IMS database connection

Create IMS command connection

IMS connections tree and table views

You can add multiple IMS database connections in a tree view. Browse DBDs, PSBs, and PCBs for IMS databases using the IMS Connections tree view. You can use this view to:

• Add IMS catalog and database connections
• Expand and collapse database connection contents to view DBDs, PSBs, and PCBs
• Select an individual DBD, PSB, or PCB and right-click to view segments and source code

In addition to segments and fields, IMS database DBDs, PSBs, and PCBs can also be viewed in a table with extended columns for DBDs, PSBs, Segments, and Fields. This allows simple click navigation between related PSBs and PCBs to find associated segments and fields.

You can verify connections to IMS databases or select another connection using the IMS Connection option in the status bar.

IMS Projects

Create IMS projects to edit and organize SQL queries and IMS commands to execute on IMS databases.

Create IMS project for PSB, DBD and SQL

Create IMS project for IMS commands

Edit and execute SQL

Edit and execute SQL from an IMS project file against an IMS database using a specified database connection. DDL statements can also be run directly in the SQL editor. A results window is provided with a table containing the resulting query information. You can sort and filter results within the table.

Each result set from SQL queries are stored in a query history view. You can download SQL result sets as a CSV file.

Execute IMS commands

Execute IMS Type 1 and Type 2 commands from a Command folder within an IMS project. Command results are displayed in a JSON Output view and a Command Output view, with execution status shown inline. Previously executed commands are available in the Command History.

Import DBDs and PSBs from the IMS catalog

Select an IMS database connection from the IMS Connections View to import DBDs and PSBs from. Use advanced search to filter by name and choose to import referenced DBDs, referencing PSBs, or all instances directly into a project.

Import from catalog

Advanced Search and import reference DBDs and PSBs

Edit DBD segment fields

Add, edit, move, and delete segment fields within DBDs in an IMS project. Changes are reflected in the source code and DDL views within the project.

Add Fields

Edit and Delete Fields

Visualize DBDs and PSBs

View DBDs and PSBs in an interactive hierarchical visualization, allowing visual navigation of segments and view of segment fields by expanding their contents. Swap between source, DDL, tables, or visualization as needed using tabs or context menus.

Support

To report issues or submit feedback about this extension, you can contact IBM support or open an issue in our GitHub repository. GitHub issues may also be used to submit requests for future enhancements.