We are pleased to mark the one-year anniversary of IBM Remote System Explorer API with the release of RSE API 1.0.5. There have been a variety of updates and enhancements since its inaugural release. Some of these have been described in previous blog entries such as this one, which focused on 1.0.2. In this article, we'll highlight key features that have been introduced since then.

Jobs

Display Active

You can now use RSE API to get at z/OS address space information via the following REST APIs: When using GET /jobs/displayactive/all, you get information about all the address spaces on the system:

Record-Ranges

When querying job spool content, you can now specify an optional record range, allowing you to get at the records you're interested in rather than the entire spool. There are a couple ways to specify record range using the optional header:

• SSS-EEE lets you indicate the starting record followed by the ending record. For example, you can specify 0-10 to get the first 10 records of a spool. If you leave the ending record blank (e.g. 41000-) then you get all the records from the starting record on.
• SSS,NNN lets you indicate the starting record followed by the number of records desired. For example, you can specify 20000,5 to get 5 records starting at record 20000. If you leave the number of records blank (e.g. 41000,) then you get all the records from the starting record on.

MVS Data Sets

Record-Ranges

Just like you can specify a record range to get a subset of job spool records, you can make use of this option when getting MVS file content.

Raw Content

Prior to the rawContent APIs, you could only download and upload data set content via the GET /datasets/{dsn}/content and PUT /datasets/{dsn}/content APIs using JSON objects. For small to medium text-based content this works well but if you want to work with large or binary resources and be able to download and upload in a streaming fashion, you'll want to take advantage of the rawContent APIs. We've also added HEAD APIs for both the rawContent and content APIs. These provide an Etag in the response header that contains the content checksum so you can quickly know whether or not a previously downloaded file has changed on the host since you last checked.

Allocate Like

You can now use POST /datasets/{copydsn}/allocateLike to allocate a new data set like an existing one.

Mappings

The z/OS File System Mappings view in the IBM Explorer for z/OS client lets you map data sets to transfer types, host encodings and content types and also specifies the default host encoding to use. RSE API provides this same kind of functionality using a JSON format host configuration that is shared by each client. A default mapping file is generated out of the box but this can be customized by modifying the $RSEAPI_CFG/mvsMappings.json file or by specifying a different path in rseapi.env using the RSEAPI_MVS_MAPPING_FILE environment variable. You can use GET ​/datasets​/mappings to see the current mappings.


When downloading and uploading MVS resources, these mappings are used to determine the host encoding to convert to/from. If a given data set has no mapping, then RSE API falls back to the default. If you don't want to use the default, you can override that by passing in a hostEncoding header with your request.

Locking

RSE API now provides support for locking MVS resources. Using these APIs, the lock owner for an MVS resource can be obtained and files can be locked and unlocked. Note that when an RSE API user session ends (either explicitly or via idle timeout), any locks obtained during the session by that user are automatically released. This feature is not enabled by default but, if locking support is desired, the host can be configured as described here.

UNIX Files

Archives

APIs are now available to work with UNIX archive files (i.e. zip, jar, tar, pax, tgz & war files). If you need to browse, open, export from, import into or modify the files of an archive, these new APIs make it easy for you.

Raw Content

Similar to the MVS raw content APIs, the UNIX raw content APIs allow you to transfer large files to and from the mainframe using streaming. Like MVS ones, the UNIX files HEAD APIs can be used to get the checksum (Etag) of a file for comparison purposes.

UNIX Commands

Streaming Shell Commands

The PUT /unixcommands API allows you to run simple UNIX commands that run to completion and then provide results in JSON format. But if you need to run a long running shell command that uses your profile, you'll want to make use of the new PUT ​/unixcommands​/shellcommand API. Unlike the basic commands API, the shellcommand API lets you consume the raw command output as it becomes available so that you don't have to wait until completion to see the results.

CORS: (Cross-Origin Resource Sharing)

Applications running in a browser outside of the server's domain are usually not allowed to access the server without being granted permission. A browser will send a preflight request to determine whether some operation is permitted from its origin. A CORS filter is used to configure what origins are permitted. In RSE API, the permitted origins can now be specified in the rseapi.env file by setting the CORS_ALLOWED_ORIGINS environment variable.

If you want to write a browser-based application that talks to RSE API, you need to use this option. For example, to allow the following cloud application to access RSE API from a brower, we needed to add CORS_ALLOWED_ORIGINS=https://rseapishellcommands.us-south.cf.appdomain.cloud to the rseapi.env file:

Zowe Conformance

If you use the Zowe Mediation Layer, you can onboard RSE API to be able to take advantage of a variety of Zowe Gateway capabilities and other features in a single-signon environment. Learn more about that here.

Autoscaling

The new autoscaling feature makes it easy to scale RSE API in support of large numbers of concurrent users. Learn more about that here.

IBM RSE API Plug-in for Zowe CLI

Most folks who are reading this blog aren't about to go write a brand new RSE API client. That's fine, there already is one available for your use: the IBM RSE API Plug-in for Zowe CLI which is provided as part of IBM Z Open Editor. This lets you interact with z/OS from your client using a command line interface.




Installing Z Open Editor will extend Zowe Explorer to include these RSE capabilities.



Learn more about the RSE API Plugin-in for Zowe CLI here.
To see how this is used in IBM Wazi for Red Hat CodeReady Workspaces check this out.

Conclusion

RSE has long been an integral part of Aqua products like IBM Developer for z/OS, providing the means of accessing the mainframe. RSE API builds on that history to make it easy for any client to leverage its functionality using modern tooling, and with this first anniversary release, clients now have an expansive set of capabilities to work with.