Quick Start Guide
Version 8.0.1
October, 2020
The objective of this guide is to help you deploy the ASG-JOB/SCAN REST services as quickly as possible. It provides step-by-step exercises that will guide you through the process of modifying an existing Liberty Profile server and deploying the latest ASG-JOB/SCAN REST services.
A Liberty Profile server is a Java application server runtime model offering a small footprint and significant z Integrated Information Processor (zIIP) offload. Unlike z/OSMF and z/OS Connect EE products, which embed a specialized Liberty Java server, ASG-JOB/SCAN REST services will operate as an application inside a separate Liberty Profile server.
First, you will modify an existing Liberty Profile server configuration to add or update JOB/SCAN.
Second, you will create or update the ASG-JOB/SCAN REST services configuration.
Third, you will upload and install the latest ASG-JOB/SCAN REST services downloaded from the ASG ACCESS Portal.
Fourth, you will update the ASG-JOB/SCAN base product installation to support ASG-JOB/SCAN REST services.
Last, you will customize the TSO logon procedure, depending on the JOB/SCAN features to be made available to JOB/SCAN REST services.
• An existing Liberty Profile server in which you will deploy the ASG-JOB/SCAN REST services.
• Appropriate access authority to the Installation and User directories.
• Familiar with z/OS UNIX shell applications and commands using Telnet protocol or via an OMVS session.
Make sure you have the following Liberty Profile server and JOB/SCAN Server configuration information:
Symbolic Name Description
WLP_INSTALL_DIR Path name of the Liberty Profile server Installation directory.
WLP_USER_DIR Path name of the Liberty Profile server User directory.
JAVA_HOME Path name of the 64-bit JAVA runtime directory.
SERVER_NAME User-defined server name for JOB/SCAN REST services.
INSTALL_HLQ The value represents the high level qualifiers under which your ASG-JOB/SCAN installation datasets are located.
Example: If you have specified INSTALL_HLQ as ASG.JJS800, this means JOB/SCAN's load library is located at
ASG.JJS800.SJJSLMOD.
z/OSMF_HOST Host URL needed to access z/OSMF REST services.
z/OSMF_PORT Port number needed to access the z/OSMF REST services.
TSO_LOGON TSO logon proc needed to start a TSO session.
Note:
This is the logon proc that is customized to support JOB/SCAN REST services. See “Step 5 - Configure the TSO logon procedure” on page 6, for more information.
Required Liberty Profile Server Configuration
Verify that the Liberty Profile server configuration file
"WLP_USER_DIR/servers/SERVER_NAME/server.xml" has the following settings:
Step 1- Add or update JOB/SCAN application to your Liberty Profile server
Use the ISPF Editor or the z/OS UNIX shell command edit; insert or update the following application definition to your Liberty Profile server configuration file
"WLP_USER_DIR/servers/SERVER_NAME/server.xml":
Element Value
server description="ASG-JOB/SCAN Liberty Profile server"
featureManager includes jsp-2.3, jaxrs-2.1, openapi-3.0, zosSecurity-1.0 and ssl-1.0.
classloading useJarUrls="true"
httpEndpoint host element definition IP address, domain name server (DNS) host name with domain name suffix, the DNS host name or “*” and unique listener ports for the Liberty Profile server for HHTP and HTTPS.
sslDefault specify passwords for the keyStore definitions including DefaultSSLSettings, CellDefaultKeyStore and
CellDefaultTrustStore.
<application id="JobScan"
location="jobscan.rest-8.0.1.<date-stamp>.war"
name="jobscan"
Step 2 - Create or update the ASG-JOB/SCAN REST services configuration
Use the ISPF Editor or the z/OS UNIX shell command edit; create the ASG-JOB/SCAN REST Services configuration member named jobscan.xml in the Liberty Profile server user directory “WLP_USER_DIR/servers/SERVER_NAME” and insert the following:
Replace the Symbolic Names with the site-specific values listed in “Prerequisites” on page 1.
The element <work-files> is used for temporary file allocations and consists of the following optional attributes:
Step 3 - Upload and deploy the ASG-JOB/SCAN REST services
Use the Windows FTP batch file and transfer the ASG-JOB/SCAN REST services WAR
<?xml version="1.0" encoding="UTF-8"?>
<jobscan description="ASG-JOB/SCAN REST Services">
<display-name>JobScan REST Services</display-name>
<installation-prefix> INSTALL_HLQ </installation-prefix>
<work-files storclas="sclass" dataclas="dclass" mgmtclas="mclass"
unit="SYSDA" qualifier="ASGJJS" extend="5"/>
<zosmf-details host="z/OSMF_HOST" port="z/OSMF_PORT"/>
<tso logon-proc="TSO_LOGON"/>
</jobscan>
storclas storage class used in work file allocation dataclas data class used in work file allocation
mgmtclas management class used in work file allocation unit type of unit used in work file allocation
qualifier the second level qualifier used in generating work file names extend quantity used in secondary extents in work file allocation
Windows FTP batch file deploy.bat
Batch file parameters
• Replace the <date-stamp> variable in the deploy.bat with the date of the WAR file (e.g. 20200608)
• Execute the Windows FTP batch file and transfer the ASG-JOB/SCAN REST services WAR file to the Liberty Profile Server application directory with the required parameters.
Example:deploy xxxxxx.asg.com userid password WLP_USER_DIR SERVER_NAME
• Verify that the ASG-JOB/SCAN REST services WAR file was transferred into the Liberty Profile Server application directory.
rem Deploy the ASG-JOB/SCAN Web Services Application Script rem Host: %1 User: %2 WLP_USER_DIR: %4 Server: %5
@echo off
echo open %1 > _ftpcmds.txt echo %2 >> _ftpcmds.txt echo %3 >> _ftpcmds.txt
echo cd %4/servers/%5/apps >> _ftpcmds.txt echo binary >> _ftpcmds.txt
echo put jobscan.rest-8.0.1.<date-stamp>.war >> _ftpcmds.txt echo quit >> _ftpcmds.txt
ftp -s:_ftpcmds.txt del _ftpcmds.txt
@echo on
%1 IP address, domain name server (DNS) host name with domain name suffix or the DNS host name for the z/OS system.
%2 User identifier with update authority to the Liberty Profile server User directory.
%3 Password for the user identifier.
%4 Path name of the Liberty Profile server User directory (WLP_USER_DIR).
%5 Server name for the Liberty Profile server (SERVER_NAME).
Note:
Before starting the following procedure, delete or rename
jobscan-hlq.SJJSLMOD.XMIT if it exists on your target z/OS system.
Steps to update JOB/SCAN base product installation:
1 Unzip the base product enablement package (jobscan.zos.<timestamp>.zip) from the RESTPKG directory into a working folder under Windows.
2 Open a Windows Command Prompt and switch to the working folder created in Step 1.
3 Enter the command: ftpJobScan host userid password jobscan-hlq where:
• host is the FTP address of the z/OS system
• userid is the user id of someone with authority to update the JOB/SCAN installation libraries
• password is the password of userid
• jobscan-hlq is the high level qualifier under which JOB/SCAN is installed
4 Logon to the target z/OS system and verify the following:
• jobscan-hlq.SJJSCLST contains the members JLCHK and JSSCAN
• jobscan-hlq.SJJSLMOD.XMIT has been created
5 Execute the TSO command: receive indsn('jobscan-hlq.SJJSLMOD.XMIT').
When prompted for restore parameters, enter: dataset('jobscan-hlq.SJJSLMOD').
6 Verify jobscan-hlq.SJJSLMOD contains the member RESTAPM.
Step 5 - Configure the TSO logon procedure
The TSO logon procedure is an essential part of JOB/SCAN REST services installation.
To support JOB/SCAN REST services, you must customize the TSO logon procedure on z/OS system. The procedure in this section describes how to set up a TSO logon
procedure, depending on the JOB/SCAN features to be made available to JOB/SCAN
However, it is crucial to meet the minimum resource requirements for running JOB/SCAN, e.g. sufficient region size, security authorization, latest z/OS maintenance, etc.
2 Save this procedure as your TSO logon procedure for JOB/SCAN REST services.
3 Verify the new logon procedure has the dataset allocations needed to execute REXX under TSO. Typically, this means the STEPLIB allocation should contain a DD statement for REXX.SEAGLPA or something similar.
4 If you want to use the Product Usage Facility in JOB/SCAN to track JOB/SCAN usage from the REST services, then add a DD allocation for JLLPUF and set its DSN to point to an existing JOB/SCAN product usage file. See ASG-JOB/SCAN and ASG-DOCU/TEXT Installation Guide for instructions on how to create this usage file.
5 If you want to use the Control-M scheduler interface, add the necessary dataset allocations for DAGLOBAL and DAPARM DDs. Refer to your existing JOB/SCAN installation to see what datasets are used for Control-M support.
6 Save this TSO logon procedure in your standard location for logon procedures.
7 Enter the name of this logon procedure for the attribute logon-procin jobscan.xml, the configuration file for JOB/SCAN REST services.
