Introduction

z/OS Management Facility

IBM z/OS Management Facility (z/OSMF) provides a framework for managing various
aspects of a z/OS system through a Web browser interface.
z/OSMF provides you with a single point of control for:
Viewing, defining, and updating policies that affect system behavior.
Monitoring the performance of the systems in your enterprise.
Managing your z/OS software.
Performing problem data management tasks.
Consolidating your z/OS management tools.
z/OSMF allows you to communicate with the z/OS system through a Web browser, so you
can access and manage your z/OS system from anywhere.

z/OS jobs REST Interface

z/OS jobs REST interface is an application programming interface (API) implemented
through industry standard Representational State Transfer (REST) services. This
interface allows a client application to perform operations with batch jobs on a
z/OS system.
With the z/OS jobs REST interface, an application can use REST services to perform a
variety of operations on batch jobs. The supported operations by the REST services
include
Obtain the status of a job
List the jobs for an owner, prefix, or job ID
List the spool files for a job
Retrieve the contents of a job spool file
Submit a job to run on z/OS
Cancel a job
Change the job class of a job
Cancel a job and purge its output.

Scope of the document

Scope of this document is limited to How To on establishing of connection to ZOSMF
REST interface from your java client application.

Software Requirements
Using the z/OS jobs REST interface requires one of the following minimum levels of
JES on your z/OS system: JES2 V1R13 or JES3 V1R13.

Processing overview
The z/OS jobs REST interface services can be invoked by any HTTP client application,
running on the z/OS local system or a remote system.
The program (the client) initiates an HTTP request to the z/OS jobs REST interface.
If the interface determines that the request is valid, it performs the requested
service. After performing the service, the z/OS jobs REST interface creates an HTTP
response. If the request is successful, this response takes the form of an HTTP 2nn
response and, if applicable, a result set that is passed back to the program.
Depending on which service was requested, the result set might be returned in a
format that requires parsing by the program, for example, a JSON object. In other
cases, results might be returned in another format, such as plain text or binary
data. If the request is not successful, the response consists of a non-OK HTTP
response code with details of the error provided in the form of a JSON object.

Connecting to zOSMF REST Interface from JAVA

1. Connecting to ZOSMF

1.1. Server connection URL https://www.zosmfserver.com/zosmf/

1.2. Open connection with HTTP header property Authorization set to value Base64
encoded byte string of userid:password prefixed with Basic (Word Basic
followed by a space).
For example, consider your ZOSMF user id is ZMFUSER, password is ZMFPASS and
Base64 encoded value of the string ZMFUSER:ZMFPASS is ENCRYPTED_CREDENTIALS.
The request header property value combination will look like
Authorization:Basic ENCRYPTED_CREDENTIALS

Sample Code
// Apache Commons Codec is used for Base64 encoding
import org.apache.commons.codec.binary.Base64;
public String openConnection()
{
String host = "https://www.zosmfserver.com/zosmf/";
String encoding =
Base64.encodeBase64String("ZMFUSER:ZMFPASS".getBytes());
try
{
URL url = new URL(host);
HttpsURLConnection httpsConnection =
(HttpsURLConnection) url.openConnection();
httpsConnection.setRequestMethod("POST");
httpsConnection.setDoOutput(true);
httpsConnection.setRequestProperty("Authorization", "Basic "
+ encoding);
httpsConnection.connect();
}
catch (Exception ex)
{
// Exception handling
}
}
1.3. Upon successful connection, Server would return a response code of 200.
1.4. The response header will also have a LTPA token which should be used for
every subsequent request. The LTPA token is embedded in the response header
property Set-Cookie. This value need to be send to server for as value to
the property Cookie.

Sample Code: Extract LTPA token from response header

String LTPA_Token;
int responseCode = httpsConnection.getResponseCode();
if(responseCode == HttpsURLConnection.HTTP_OK)
{
Map<String, List<String>> headerFields =
httpsConnection.getHeaderFields();
List<String> tempCookie = headerFields.get("Set-Cookie");
for(String value : tempCookie)
{
if(value.contains("LtpaToken2"))
{
LTPA_Token = (value.split(";"))[0]+";";
break;
}
}
}

Sample Code: Connecting to REST interface to fetch Job details

String host = "https://www.zosmfserver.com/zosmf/";
URL url = new URL(host+"restjobs/jobs/");
HttpsURLConnection httpsConnection =
(HttpsURLConnection) url.openConnection();
httpsConnection.setRequestMethod("GET");
httpsConnection.setDoOutput(true);
httpsConnection.setRequestProperty("Cookie",LTPA_Token);
httpsConnection.connect();

Sample Code: Connecting to REST interface to fetch Dataset details

String host = "https://www.zosmfserver.com/zosmf/";
URL url = new URL(host+"restfiles/ds/");
HttpsURLConnection httpsConnection = (HttpsURLConnection) url
.openConnection();
httpsConnection.setRequestMethod("GET");
httpsConnection.setDoOutput(true);
httpsConnection.setRequestProperty("Cookie",LTPA_Token);
httpsConnection.connect();

2. Known issues while connecting to ZOSMF server

2.1. javax.net.ssl.SSLHandshakeException:
java.security.cert.CertificateException: No subject alternative names
present.
Cause: There is no domain name registered in DNS for the IP address. This
may encounter in test system. This problem is least expected in production
system as production system expected to have a domain name.
Solution: Write your own host name verifier class. This is not advised for
production code.
String host = "https://www.zosmfserver.com/zosmf/";
URL url = new URL(host);
HttpsURLConnection httpsConnection = (HttpsURLConnection) url
.openConnection();
httpsConnection.setHostnameVerifier(
new HostnameVerifier() // Anonymous class
{
@Override
public boolean verify(String hostname, SSLSession session)
{
return true;
}
});

2.2. sun.security.provider.certpath.SunCertPathBuilderException: unable to

find valid certification path to requested target.
Solution: Import the websites certificate to keystore using keytools.
Keytools is a free tool provided along with JRE.
To import the certificate follow the below steps.
2.2.1 If you dont have the certificate file, got to your browser and export
the certificate in to a local folder. Example: zomf.cer.
2.2.2 Open command prompt and enter the following command
2.2.3 keytool -import -alias ZOMF_CERT -file zosmf.cer -keystore
javapath\lib\security\cacerts
where javapath where your jre installation resides.
Ex:- C:\Program Files\Java\jre8

2.2.4

You will be prompted for a password. Enter the password and the answer
the questions then appear on screen. The default password to the
keystore javapath\lib\security\cacerts is changeit.