IBM Developer for z/OS 16.0 (IDz) is now available!  This release offers a long list of exciting features.  One of the features is the introduction of the Java SDK for Remote Systems Explorer API (RSE API).  

RSE API is a collection of REST APIs that allow a client to work with various components on the z/OS host system, including MVS data sets, z/OS UNIX files and commands, JES jobs, TSO commands, and more.  The SDK makes it easy to create a Java client that work with these APIs.

IBM Developer for z/OS (IDz)  is an extensible development environment.  Custom tools can be developed using one of the following methods:

• Write an Eclipse plugin that extends from RSE extension points
• Write an application that works with the RSE API server via HTTP/HTTPS protocol

These methods have advantages and challenges:

• With an Eclipse plugin, the custom tool requires runtime dependencies from RSE and Eclipse.  It cannot be run without the IDz runtime.
• Working with RSE API server, requires clients to build a HTTP/HTTPS communication layer with the RSE API server.  Clients are also required to understand how to build requests to invoke various functions.  In addition, clients need to understand the expected responses and their JSON schema.  This can be a considerable amount of development effort, before clients can even begin building their custom tools.

The Java SDK for RSE API is created to address these challenges.  The goal of the SDK is to speed up custom tools development.  Clients do not need to spend effort in building foundational code.  

In this article, we are going to show how you can write a Java application that remotely works with the UNIX file system from z/OS.  This Java application will:

1. Create a script file onto the remote UNIX file system.
2. Add executable bits to the script file.
3. Execute the script remotely.

Let's begin by setting up a new Java project.

Setting up Java Project

IDz provides a set of tools (content assist, code templates, etc.) for working with the Java SDK for RSE API.  The tools are enabled if the SDK is part of the project's class path.  Otherwise, the tools are not available.

To create a Java project and include the IBM RSE API SDK Toolkit Library in its classpath: 

1. Create a Java project. (File -> New... -> Project…)
2. Select Java Project
3. You may be prompted to enable the Java Development capability. Select OK and enable the capability.
4. In the New Java Project dialog, make sure that the “Create module-info.java file" option is unchecked.

5. For this example, the project name is com.ibm.zexplorer.examples.
   
6. Click Next and select the “Library” tab. 
7. Select "Classpath" and click on the “Add Library…” button.
8. Select "IBM RSE API SDK Toolkit Library".
9. Click Next and accept the default version.
10. Click OK.

11. The "IBM RSE API SDK Toolkit Library" is added to the project's class path.
12. Click Finish.

Next, create a Java class with a main method:

1. Create a new class with the main method generated. File -> New Class…
2. Enter the package and name of the class. In this example, the classname is UnixExample.
3. Check the option to generate the public static void main(…) method.
4. Click "Finish"

Content Assist

Content assist helps a developer to write code faster and more efficiently.  Based on the current code context in the Java Editor,  IDz provides a list of code proposals in the editor.  Selecting a proposal will insert the code into the editor.  Content assist can be assessed from the Java Editor via the CTRL + Space shortcut or by Edit -> Content Assist -> Java Proposals menu item.

For example, you can see the proposals for the RSEAPI class by following these steps:

1. In the Java Editor, type “RSEAPI.”
2. Type CTRL + Space
3. This will bring up the content assist hover:

Keep typing, and keep invoking CTRL+Space, and you can see the list of proposals being narrowed down.  For example, you can see more details about the authenticateService.login(…) function:

RSE API Code Templates

 
You can write almost the entire application using just content assist and code completion.  To make things even simpler, IDz provides a set of code templates for some of the most common tasks.  Code templates can be accessed the same way as content assist.  Instead of just inserting a single line of code, code template function inserts a snippet of code that performs some of the common tasks.  For example, if you type “log in” and invoke content assist, you will see the following template.  The code template function inserts the code to log in to a z/OS server and all the required imports. 

IBM RSE API SDK 101

 Before diving into writing code, let’s discuss the basics of the SDK.  The entry point to access the z/OS system is through the com.ibm.zexplorer.rseapi.sdk.services.RSEAPI class. 

This class provides the following methods:

• authenticateService() – returns the authenticate service to log in and log out of the system.
• unixFilesService() –returns the UNIX file service to work with files that reside in the UNIX file system. Clients may use this service invoke operations like create, edit, and delete files.
• mvsDatasetService() – returns the MVS dataset service to work with MVS datasets. Clients may use this service to create, edit, delete or retrieve information about partitioned and sequential datasets.
• jobsService() – returns the jobs service to work with jobs on z/OS. Clients may submit, cancel, purge jobs from the system.  Clients may also use this service to get job files and address space information.
• unixCommandService() – returns the UNIX command service. Clients may use this service to run UNIX commands on z/OS.
• tsoCommandService() – returns the TSO command service. Clients may use this service to run TSO commands on z/OS.
• scanService() – returns the scan service. Clients may use this service to scan for language information of source files on z/OS.
• commonPropertiesService() – returns the common properties service. Clients may use this service to access, read, write, and delete of common properties.
• infoService() – returns the information service. Clients may use this service to gather information like server version, z/OS versions about the servers that the Java application is connected to.

The APIs from these services require an ISession object.  This object contains a valid security token needed to run the services.  Obtain this object by using the authenticate service to log onto the system:

RSEAPI.setAcceptAllCertificates(true);		// optional to disable certificate validation during authentication
ISession session = RSEAPI.authenticateService().login("https://rseapi.ibm.com:6800/rseapi", "userid", "passwd");

 
The authenticate service builds the HTTP request for log in.  It then parses the response from the RSE API server, retrieve the security token, and save it in the session object.  By default, the authenticate service is set up to log in via HTTPS.  To successfully login, it is required that the runtime JVM has a valid SSL certificate from the remote host.  A valid certificate may not be available if the application is running in a test environment.  Certificate validation can be disabled using RSEAPI.setAcceptAllCertificates(true) function.  
 
Next, use the session object to use other services.  For example, to list all the files from the /tmp directory, use this code snippet:

List<IUnixFile> unixFiles = RSEAPI.unixFilesService().list(session, "/tmp");

Under the covers, the SDK creates the HTTP GET request to list all the files from the “/tmp” directory.  The SDK parses the response from the RSE API server and then creates Plain Old Java Objects (POJO) that represent files on the UNIX file system.  Clients can focus on building tools using the POJO objects.  There is no need to worry about the underlying HTTP requests and responses.  This approach is used throughout the SDK.

Sample Application

Let’s create the application now. 

Replace the content of UnixExample.java with the following code:

package com.ibm.zexplorer.examples;

import com.ibm.zexplorer.rseapi.sdk.model.ICommandOutput;
import com.ibm.zexplorer.rseapi.sdk.model.ISession;
import com.ibm.zexplorer.rseapi.sdk.services.IUnixFilesService;
import com.ibm.zexplorer.rseapi.sdk.services.RSEAPI;

/**
 * 
 * This example demonstrates the use of the RSEAPI SDK:
 *     - authenticate service
 *     - unix files service
 *     - unix command service
 * The application logs in to a remote z/OS system via the RSE API server. It creates
 * a new directory and script file. The application adds execution permission on the file,
 * and invokes the script. Finally, the application removes the newly created
 * script file and directory.
 *
 */
public class UnixExample {

	public static void main(String[] args) {

		// TODO:  Update to your home directory
		String home = "/u/myuserid";
		
		String dir = home + "/tmp";
		String script = dir + "/listTmp.sh";
		String scriptContent = "echo \"### Running Script -> List Home Directory ###\" \n ls -la" + home;
		
		// TODO:  Update to your RSEAPI Host
		String rseapiHost = "https://rse_api_host:port/";
		
		// TODO:  Update to your user id
		String userid = "myuserid";
		
		// TODO:  Update to your password
		String passwd = "passwd";

		// accept all certificates
		RSEAPI.setAcceptAllCertificates(true);

		// log in to the remote server and get the session object
		ISession session = RSEAPI.authenticateService().login(rseapiHost, userid, passwd);

		// create a temporary folder
		RSEAPI.unixFilesService().createFile(session, dir, IUnixFilesService.TYPE_DIR, "drwxrwxr-x");

		// create a new file in the UNIX file system
		RSEAPI.unixFilesService().createFile(session, script, IUnixFilesService.TYPE_FILE, "-rw-rw-rw-");

		// update the script file content. The script file will list all files from the
		// user's home directory
		RSEAPI.unixFilesService().changeContent(session, script, true, null, scriptContent);

		// change permission on script file to allow execution
		ICommandOutput output = RSEAPI.unixCommandService().run(session, dir, "chmod a+x " + script, true);

		System.out.println(output.getStdOut());

		// run the script
		output = RSEAPI.unixCommandService().run(session, dir, script, false);

		System.out.println(output.getStdOut());

		// clean up the script file and dir
		RSEAPI.unixFilesService().delete(session, script);
		RSEAPI.unixFilesService().delete(session, dir);

		// log out from the system
		RSEAPI.authenticateService().logout(session);

	}

}


​

Running the Example in IBM Developer for z/OS

To run this example:

1. Update the HOME directory, RSE API url, user id and password in the application.
2. Save the file.
3. Right click from the Java Editor
4. Run As -> Java Application
   

You will see an output similar to the follwing in the Console view:

[]
### Running Script -> List Home Directory ###
total 400
drwxr-xr-x   11 USER1    SYSPROG     8192 Oct 18 10:43 .
dr-xr-xr-x  526 ROOT     TTY            0 Oct  5 15:16 ..
drwxrwxrwx   10 USER1    SYSPROG     8192 Sep 29 12:03 .rseapi
-rw-------    1 USER1    SYSPROG      719 Oct 17 14:45 .sh_history
drwxrwxrwx    4 USER1    SYSPROG     8192 Jul 21 10:58 F2
-rw-r--r--    1 USER1    SYSPROG     1913 Jun 30 14:06 anagram2
drwxrwxrwx    3 USER1    SYSPROG     8192 Nov  1  2021 blabla
drwxrwxrwx    2 USER1    SYSPROG     8192 Aug 29 15:43 hello
-rwxrw-r--    1 USER1    SYSPROG       39 Jun 30 12:39 hellofriend.txt
-rwxrw-rw-    1 USER1    SYSPROG       39 Aug 25 18:08 hellofriend2.txt
-rw-r--r--    1 USER1    SYSPROG    25342 Aug  2 15:53 myapp.war
drwxrwxr-x    2 USER1    SYSPROG     8192 Oct 18 10:43 tmp​

Running the Example as Stand-alone Application

It is not required to run the application in IDz.  The application can run independently outside of IDz by exporting it as a runnable jar:

1. Select the Java project from the Package Explorer
2. Right click -> Export 
3. Select Java -> Runnable JAR file
4. In the Runnable JAR File Export dialog, select the launch configuration and export destination.
5. Select Package required libraries into generated JAR - This will package the IBM RSE API SDK JAR, and its dependencies into the exported jar.

Use the following command to run the application in a terminal:

java -jar unixexample.jar

Conclusion

This article is an introduction of the Java SDK for RSE API.  The SDK has made development of custom tooling for z/OS easy.  Clients can focus on business logic, and not the underlying communication protocols between the client and the server.  With the help of toolings provided by IDz, clients can get started using the SDK quickly.  We have shown you a very simple example of working with the Unix file system.  This is just the beginning.  The SDK can be used to work with many different services from z/OS.  There are many other use cases and possibilities of using the SDK for custom tools developer.

References

IBM Remote System Explorer API References
IBM Java SDK for RSE API Overview