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.1.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.

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 consists 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
• 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 will scanned 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. you 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 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 defult 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: Default directory is current the 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.

IMS connection profiles

Create connections to IMS databases using the IMS connections view. IMS connections can be organized into folders and expanded or collapsed.

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 DDL, segments, and source code

In addition to segments and fields, IMS database DBDs, PSBs, and PCBs can also be viewed in a table. 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 to execute on IMS databases.

Edit and execute SQL

Edit and execute SQL from an IMS project file against an IMS database using a specified database connection. 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.

Import DBDs and PSBs from the IMS catalog

Select an IMS database connection from the IMS Connections View to import DBDs and PSBs from. Filter and select which DBDs and PSBs to import into an IMS project. Optionally, you can choose to import any referenced DBDs.

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 support or open an issue in our GitHub repository. GitHub issues may also be used to submit requests for future enhancements