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
ProfileUtilsandProfileSessionhelper classes to load credentials from an existingzowe.config.jsoninstead 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. BecausegetRseStatus()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:
| Module | Key exports |
|---|---|
methods | AuthLogin, AuthLogout, CheckStatus, List, GetJobs, Download, DownloadJobs, Upload, SubmitJobs, MonitorJobs, Create, Delete, Copy, Move, Rename, Search, IssueCommand, Admin, Lock, HMigrate, HRecall, Archives, ClassificationScan, StreamContent, … |
constants | RseApiCapability, RseApiCapabilityMap, MINIMUM_SUPPORTED_RSE_API_VERSION, JOB_STATUS, JobsConstants, … |
interfaces | IJob, IJobFile, ISpoolFile, IRestApiResponse, ITokenInfo, IUnixFileContentResponse, … |
profiles | ProfileSession, ProfileUtils, ZoweExplorerRseApi |
rest | RseRestClient (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.