IBM Z® Open Editor
Docs
News and Blogs
IBM Downloads
VS Code Marketplace
GitHub
Docs
News and Blogs
IBM Downloads
VS Code Marketplace
GitHub
  • Overview

    • Introduction
    • Updates and user feedback
  • Getting Started

    • Getting started with IBM Z Open Editor
    • Setting up integrations to interact with z/OS
    • Getting started with Zowe 3.0
  • Configuration

    • Setting preferences
    • Configuring your applications with ZAPP files
    • Setting property groups
    • Setting compiler options
    • Setting file associations
    • Setting language-specific tab stops and rulers
    • Enabling and disabling problems in IBM Z Open Editor
    • Enabling and disabling unreachable COBOL code warnings
    • Customizing the Outline view
    • Setting language-specific maximum line length
    • EBCDIC code pages and mappings files
    • Experimental: Formatting COBOL source code
  • Tutorials

    • Tutorial overview
    • Exploring the user interface
    • Exploring the sample files
    • COBOL editing tutorial
    • COBOL, PL/I Preprocessor tutorial
    • HLASM editing tutorial
    • REXX editing tutorial
    • Managing z/OS resources with IBM RSE API Plug-in for Zowe CLI tutorial
    • Submitting JCL to compile, link, and run jobs tutorial
  • Editing program files

    • Language References
    • Making COBOL and PL/I code changes
    • PL/I macro preprocessor
    • Making High Level Assembler code changes
    • Making REXX code changes
    • Making JCL code changes
    • Using and managing code snippets
    • Using the integrated Git
    • Searching for COBOL, PL/I, HLASM, and REXX components
  • Interacting with z/OS using Zowe

    • Interacting with z/OS
    • Creating a configuration profile in Zowe Explorer v3.0.0
    • Migrating Zowe profiles
    • Supported methods of authentication for z/OS using Zowe
    • Sharing team configuration files
    • Connecting to z/OS with Zowe Explorer walk through
    • Using the Zowe Explorer views
    • Using Zowe profiles in Z Open Editor
    • Connecting to z/OS using Zowe CLI walk through
    • Using command line to interact with z/OS
    • Interact with RSE Common Properties
  • Advanced Capabilities

    • Overview
    • Activating advanced capabilities
    • Launching a 3270 emulator from Zowe Explorer
    • z/OS Resources Table
    • Data Elements View
    • Program Control Flow Browser
    • Data Flow Browser
    • Line Hex Editor
    • Preprocessor support
    • Custom Macros for HLASM
    • Language Detection
    • Linting with IBM ZCodeScan
    • User build with IBM Dependency Based Build (DBB)
    • User build with customizable tasks
    • Agent Mode (Model Context Protocol)
    • IBM Bob™ Premium Package for Z integration
  • Cloud-based Editing

    • Overview to using Cloud and Browser-based platforms
    • Try Z Open Editor in the Red Hat Developer Sandbox
    • Configuring Red Hat OpenShift Dev Spaces
    • Managing Developer Workspaces
    • Managing secrets
    • Create and use custom images
    • Migrating from IBM Wazi for Dev Spaces
    • Using Z Open Editor on GitHub Codespaces
    • Using Z® Open Editor with Dev Containers
  • Troubleshooting

    • Known issues and limitations
    • Troubleshooting using log files
    • Troubleshooting for User Build
    • Uninstalling CLI plugins and VS Code extensions
  • Reference

    • PL/I Compiler Options Support Reference
    • IBM RSE API Plug-in for Zowe CLI commands
    • IBM RSE API Plug-in for Zowe CLI as a Node.js SDK
    • IBM RSE API Plug-in for Zowe CLI as nodejs SDK reference
    • Using MFA and Zowe team configuration profiles with the RSE API Node.js SDK
    • Example Zowe configuration setups
    • IBM Z Open Editor MCP Tools
    • GRUB Scripts - Git remote user build
    • Accessibility and Keyboard Shortcuts
    • settings.json properties
    • Message ID Reference
    • Other Visual Studio Code extensions
  • Legal information

    • Notices
    • Trademarks
    • Privacy policy considerations

IBM RSE API Plug-in for Zowe CLI as a Node.js SDK

IBM® RSE API Plug-in for Zowe™ CLI (@ibm/rse-api-for-zowe-cli) is an npm package that can also be used as a fully featured Node.js SDK to build automations, tools, and integrations that communicate with z/OS® through IBM Remote System Explorer (RSE) REST APIs. The package exposes its core functionality through public TypeScript classes, making the same capabilities that power the CLI available directly from your code, including access to data sets, z/OS UNIX System Services files, jobs, TSO and shell commands over HTTPS, and JWT-based authentication. Projects that use the RSE API plug-in as an SDK must also declare @zowe/imperative as a peer dependency. For more information about the Zowe SDK, see zowe.org.


Setting up your project

Install the package and its peer dependency:

npm install @ibm/rse-api-for-zowe-cli @zowe/imperative

Every SDK call requires an imperative.Session. Pass your connection details directly:

import * as imperative from "@zowe/imperative";

const session = new imperative.Session({
  hostname: "myzos.example.com",
  port: 6800,
  user: "<RSE_USERID>",
  password: "<RSE_PASSWORD>",
  protocol: "https",
  type: "basic"
});

Using Zowe team configuration profiles or MFA: Use the ProfileUtils and ProfileSession helper classes to load credentials from an existing zowe.config.json instead of constructing a session manually. See Using MFA and Zowe team configuration profiles with the RSE API Node.js SDK for details.


Checking server status and capability gating

Before you make API calls, verify that the server is reachable and determine which capabilities the target RSE API version supports. The CheckStatus class provides both capabilities.

import { CheckStatus, RseApiCapability } from "@ibm/rse-api-for-zowe-cli";

// Get server version and status information (the result is cached for 20 minutes)
const status = await CheckStatus.getRseStatus(session);
console.log(status);

// Guard a code path based on a specific capability
const supportsJobNotifications = await CheckStatus.isCapabilitySupported(
  session,
  RseApiCapability.JOB_NOTIFICATION
);

if (supportsJobNotifications) {
  // ... use job notification APIs
}

// Or throw an error if the server does not support a required capability
await CheckStatus.requireCapability(
  session,
  RseApiCapability.VSAM_CREATION,
  "createVsam"
);

The RseApiCapability enum maps capabilities to the RSE API versions that introduce them. Using requireCapability() instead of explicit version checks makes the code self-documenting by indicating why a minimum version is required.

Capability-aware code

For more complex applications, use getAllCapabilitiesForVersion() to compute the complete capability set locally from the version string returned by CheckStatus.getRseStatus(). This approach avoids repeated network calls. A single check at startup can support all capability-based branching logic:

import * as imperative from "@zowe/imperative";
import {
  CheckStatus,
  RseApiCapability,
  getAllCapabilitiesForVersion
} from "@ibm/rse-api-for-zowe-cli";

async function buildCapabilitySet(
  session: imperative.Session
): Promise<Set<RseApiCapability>> {
  const status: any = await CheckStatus.getRseStatus(session);
  const version: string = status.rseapi_version; // e.g. "1.2.4"
  return new Set(getAllCapabilitiesForVersion(version));
}

// One network call at startup; no per-capability polling needed
const capabilities = await buildCapabilitySet(session);

if (capabilities.has(RseApiCapability.COMBINED_SPOOL_DOWNLOAD)) {
  // Use single-call combined spool download (RSE API 1.2.4+)
} else {
  // Fall back to per-spool-file download
}

Note: This pre-check supports application-specific branching logic but does not bypass the SDK's internal capability checks. Individual SDK methods perform their own CheckStatus.apiVersionCheck() call before execution. Because getRseStatus() caches the response for 20 minutes, these checks incur minimal overhead after the initial call.


RSE API plug-in SDK Examples

List data set members

import { List } from "@ibm/rse-api-for-zowe-cli";

const response = await List.allMembers(session, "MY.PDS");
const memberNames: string[] = response.apiResponse.items.map(
  (item: any) => item.memberName
);
console.log(memberNames.join("\n"));

List UNIX System Services files

import { List } from "@ibm/rse-api-for-zowe-cli";

const listing = await List.fileList(session, "/u/myuser/myproject");
console.log(listing.apiResponse);

Download a data set member

import { Download } from "@ibm/rse-api-for-zowe-cli";

await Download.dataSet(session, "MY.PDS(MYMEMBER)", {
  file: "./local-output/MYMEMBER.cbl"
});

Upload a local file to a data set

import { Upload } from "@ibm/rse-api-for-zowe-cli";

await Upload.fileToDataset(session, "./local/MYMEMBER.cbl", "MY.PDS(MYMEMBER)");

The Upload class automatically detects binary files and switches to binary transfer mode when required.

Submit a job and wait for output

import { SubmitJobs, MonitorJobs } from "@ibm/rse-api-for-zowe-cli";

// Submit a job from a data set member
const job = await SubmitJobs.submitJob(session, {
  jobDataSet: "MY.JCL(COMPILE)"
});
console.log(`Submitted ${job.jobid} (${job.jobname})`);

// Wait for the job to complete and retrieve the return code
const completedJob = await MonitorJobs.waitForJobOutputStatus(session, job);
console.log(`Job ended with: ${completedJob.retcode}`);

In RSE API 1.2.2 and later, the JOB_NOTIFICATION capability enables a notification-based model that reduces polling overhead for long-running jobs. Support for this capability can be verified using CheckStatus.isCapabilitySupported().

Run TSO and shell commands

import { IssueCommand } from "@ibm/rse-api-for-zowe-cli";

// Issue a TSO command
const tsoResult = await IssueCommand.tsoCommand(session, "LISTUSER MYUSERID");
console.log(tsoResult);

// Issue a UNIX System Services shell command
const shellResult = await IssueCommand.unixShellCommand(
  session,
  "ls -la /u/myuser"
);
console.log(shellResult);

Search data sets and UNIX System Services files

import { Search } from "@ibm/rse-api-for-zowe-cli";

// Search for a string across PDS members
const mvsResults = await Search.performSearch(session, {
  pattern: "MY.PDS.*",
  searchString: "DISPLAY",
  regex: false
});

// Search UNIX System Services files by content
const ussResults = await Search.uss(session, "/u/myuser/src", "*", {
  text: "TODO"
});

What's exported from the package

The top-level @ibm/rse-api-for-zowe-cli package re-exports functionality from the following modules:

ModuleKey exports
methodsAuthLogin, AuthLogout, CheckStatus, List, GetJobs, Download, DownloadJobs, Upload, SubmitJobs, MonitorJobs, Create, Delete, Copy, Move, Rename, Search, IssueCommand, Admin, Lock, HMigrate, HRecall, Archives, ClassificationScan, StreamContent, …
constantsRseApiCapability, RseApiCapabilityMap, MINIMUM_SUPPORTED_RSE_API_VERSION, JOB_STATUS, JobsConstants, …
interfacesIJob, IJobFile, ISpoolFile, IRestApiResponse, ITokenInfo, IUnixFileContentResponse, …
profilesProfileSession, ProfileUtils, ZoweExplorerRseApi
restRseRestClient (low-level HTTP client for advanced use cases)

The complete API reference is available at RSE API SDK TypeScript reference.


RSE API plug-in SDK used with Zowe Explorer

Zowe Explorer offers an API package that can be used by extenders to register new protocols, extend menu options, and more. RSE type profiles are available in Zowe Explorer via IBM Z Open Editor using these extender APIs to register the protocol and adopting available APIs for file manipulation and other z/OS actions that are supported for that protocol.

Registering a protocol with Zowe Explorer

import * as rest from '@ibm/rse-api-for-zowe-cli';
import { MainframeInteraction, ZoweVsCodeExtension } from '@zowe/zowe-explorer-api';
// Retrieve the Zowe Explorer API object from the currently running instance.
// Choose the version of Zowe Explorer to support, i.e.. v2 or v3.
const zoweExplorerApi = ZoweVsCodeExtension.getZoweExplorerApi("3.0.0");
if (zoweExplorerApi) {
  // register with the Zowe Explorer tree views
  rest.RseRestUssApi.registerApi(importedApi);
  rest.RseRestMvsApi.registerApi(importedApi);
  rest.RseRestJesApi.registerApi(importedApi);
  rest.RseRestCommandApi.registerApi(importedApi);
  // Initialized the users ~/.zowe directory with the metadata for new protocol's profiles in case
  const meta = await rest.ProfileUtils.getProfileMeta();;
  await zoweExplorerApi.getExplorerExtenderApi().initForZowe("rse", meta);
  await zoweExplorerApi.getExplorerExtenderApi().reloadProfiles();

  // Get the IApiExplorerExtender instance from the API that extenders can used
  // to interact with Zowe Explorer such as accessing all the loaded profiles
  const profilesCache = zoweExplorerApi.getExplorerExtenderApi().getProfilesCache();

  // Example for iterating over the profiles loaded by Zowe Explorer by type
  const allProfileTypes = profilesCache.getAllTypes();
  let message = "Found the following available profiles: ";
  if (!allProfileTypes) {
    message += "none.";
  } else {
    for (const profileType of allProfileTypes) {
      const profileNames = await profilesCache.getNamesForType(profileType);
      message += `${profileType}: ${JSON.stringify(profileNames)} `;
    }
  }
  void vscode.window.showInformationMessage(message);

  // Example of listing data sets using Zowe Explorer APIs
  const loadedProfile = profilesCache.loadNamedProfile(profileName, optionalProfileType);
  const mvsApi: MainframeInteraction.IMvs = ZoweSettings.getZoweExplorerApi().getMvsApi(loadedProfile);
  const response = await mvsApi.dataSet(dsFilter, listOptions);
  //display returned list items
  console.log(response.apiResponse.items)
}

More information about extending Zowe Explorer and using the extension APIs can be found in Zowe Explorer's Wiki for Extending Zowe Explorer.


Related documentation

  • Using MFA and Zowe team configuration profiles with the RSE API Node.js SDK
  • RSE API SDK TypeScript reference
  • Setting up integrations to interact with z/OS
  • Example Zowe configuration setups
  • Zowe SDK documentation
Last Updated: 10/26/26, 5:32 AM
Contributors: Billie Simmons, Esther M, phaumer
Prev
IBM RSE API Plug-in for Zowe CLI commands
Next
IBM RSE API Plug-in for Zowe CLI as nodejs SDK reference