Running an UPSTREAM Client User Process


Introduction

Performing a Backup and Performing a Restore show how to run backups and restores from/to an UPSTREAM Client. UPSTREAM also provides a facility for a “user process” to be initiated on a Client machine.

The “user process” can be any program, batch file, or script that can execute on a Client machine. Generally, although not always, this process is used to control some aspect of an UPSTREAM operation, such as a backup or a restore.

As an example, a script might be run prior to backing up a database. This script could inform users of a pending backup before going on to close down the database and prepare it for the backup to begin. Similarly, a matching script could be run after the backup has completed to re-start the database and inform the users of the resumption of normal service.

Utilizing the USTBATCH process (z/OS Initiation with USTBATCH), the before/after scripts and the backup itself can all be automated into an z/OS batch-driven procedure, optionally controlled by your z/OS job scheduling system or the UPSTREAM scheduler USTSCHED (UPSTREAM Scheduler).

Building the USTBATCH Job

This section shows how to use the UPSTREAM TSO/ISPF dialogs to build a USTBATCH batch job to initiate a user process on a Client machine. USTBATCH JCL can also be constructed manually (although this is not recommended) as described in z/OS Initiation with USTBATCH.

Step #1 - Select USTBATCH - z/OS Storage Server Initiated Services

Enter the UPSTREAM TSO/ISPF dialog via your installation defined method (see Make the UPSTREAM ISPF Dialogs Easily Available). From the main menu, specify option number 1, “USTBATCH”, and press ENTER.

~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- UPSTREAM ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
 COMMAND ===> (% class="Red" %)1(%%)
**1** **USTBATCH** **- Host Initiated Services
** **2** (% class="Red" %)STATUS(%%) - Current Status Information
 **3** (% class="Red" %)DEFINE(%%) - Define Control Files
 **4** (% class="Red" %)CONFIGURE(%%) - Main Options
 **5** (% class="Red" %)PROFILE(%%) - Client Profile Names
 **6** (% class="Red" %)OPER(%%) - Operator Commands
 **7** (% class="Red" %)REPORT(%%) - Report
 **8** (% class="Red" %)REGISTRY(%%) - Name Registry
 **10** (% class="Red" %)SCHEDULE(%%) - Command Scheduler
 **11** (% class="Red" %)MANAGEMENT(%%) - Backup Management
 **12** (% class="Red" style="font-weight: Bold;" %)USTCRYPT(%%) - USTCRYPT Options
\\ 11 Active Jobs:
\\Sel Jobname System #ACT TCP/IP Address PORT VTAM APL
~-~-- ~-~-~-~-~-~-~-~- ~-~-~-~-~-~-~-~- ~-~-~-~- ~-~-~-~-~-~-~-~-~-~-~-~-~-~-- ~-~-~-~- ~-~-~-~-~-~-~-~-
 S USTPRODA CPUA 1 192.168.0.1 2001 USTSAAPL
 USTPRODP CPUA VERSION < 3.9.1
 UI CPUB 192.168.0.2 1972 NONE
 USTEURO CPUE INACTIVE\\

Step #2 - USTBATCH Specification

The next menu to appear allows for the specification of the USTBATCH parameters required to initiate the Client user process. The parameters of most interest are explained below. Note that we are selecting an Action of 3 “Run A PC Job”, instead of the usual Action 1 (backup) or Action 2 (restore).

-------------------------- FDR/UPSTREAM - USTBATCH ------- * ------------------
COMMAND ===> 3 SCROLL ===> CSR

Gen - Generate statements Read/Save/Delete parameter set

1 - Backup 6 - Restart Restore
2 - Restore & Inquiry 7 - Kill Restart Backup
3 - Run a PC Job 8 - Kill Restart Restore
4 - File Transfer 12 - Operator Commands
5 - Restart Backup 13 - Performance Tests

Communication parameters between USTBATCH and the UPSTREAM Storage Server
HOSTIP ===> HOSTPORT ===> 1972
HOSTDNS ===> YOUR.LPAR.DNS.NAME
APPLPREF ===> QUEUE ===> MAXRETRY ===>
USAPPL ===> CONV ===> TMAXRETRY ===>
TPNAME ===> WTOCOMP ===> APPLRETRY ===>
LOGMODE ===> RESTART ===> TASKLIM ===>

Communication parameters between UPSTREAM Storage Server & Client Target System
 TARGNAME ===> TARGNAME
or DNSname ===>
or TCP/IP addr ===> TCP/IP port ===>
IPADAPTER addr ===>
. ERRWTO . WTOR=>

Remote Parameter File:
WSPARM ===>
USERID ===> | PASSWORD ===> MIXED ===> NO

Login Parameters:
Client Login Name ===>
Client Password ===>

USTBATCH / UPSTREAM Client User Process Parameters

The key parameters used in the preceding example are explained here. For a full description of all USTBATCH parameters, see z/OS Initiation with USTBATCH.

Supply values to the fields you wish to change and then press the ENTER key to proceed to the next menu.

The parameters specified in the panel above are explained here. For a full description of all parameters, see z/OS Initiation with USTBATCH.

Beginning with UPSTREAM z/OS 3.9.1, the UPSTREAM started task and USTBATCH may now use TCP/IP to initiate requests. The SNA parameters described further below are no longer required but may still be used. They are required for users of UPSTREAM z/OS 3.9.0 and earlier and are listed here for their reference.

USTBATCH to Started Task TCP/IP Parameters (Preferred):

  • HOSTDNS
    The DNS name of the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTIP parameter.
  • HOSTIP
    The IP address of the TCP/IP stack on the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTDNS parameter.
  • HOSTPORT
    The IP port number of the UPSTREAM started task. If omitted, the default is 1972. This parameter may be used with either the HOSTDNS or HOSTIP parameters.

USTBATCH to Started Task VTAM SNA Parameters (UPSTREAM version 3.9.0 and prior):

  • APPLPREF
    The 5 character prefix of the VTAM APPLID to be used by USTBATCH for its communications with the UPSTREAM started task.
  • USAPPL
    The VTAM APPLID of the UPSTREAM started task.
  • TPNAME
    The Transaction Program Name to be used during LU 6.2 communications.

  • LOGMODE
    The VTAM LOGMODE to be used for communicating with the UPSTREAM started task.

Additional Parameters. (These parameters are used with any version of UPSTREAM and may be used with either TCP/IP or SNA USTBATCH to Started Task communication.):

  • CONV
    This controls whether or not the USTBATCH job should wait for the completion of the request submitted to the started task, or end immediately after the request is accepted.
  • WTOCOMP
    Allows a WTO completion message to be issued to the z/OS system operator when the request finishes.

Started Task to Client Target System Parameters:

  • TCP/IP ADDR

    The IP address of the Client on which you wish to initiate the user process. Note that this parameter is mutually exclusive with the TARGNAME, DNSNAME, and TARGLU keywords.

  • TCP/IP PORT
    The TCP port number of the Client on which you wish to initiate the user process.
  • ACTION
    Controls which UPSTREAM function is to be performed by this set of generated statements. In our preceding example, ACTION=3 specifies the running of a Client process or “PC Job”.

Step #3 - User Process Specification

The next menu to appear allows you to specify the location (on the Client) and the filename of the user process that you want to execute. This is done on the “Command Line” field, as shown below, where we are going to execute a program or script called “setupdb” that resides in the “/u/user01” directory or folder on the Client. We are also controlling the return code mapping sent back to the originating USTBATCH job (see the UPSTREAM Client Guide for more details).

-------------------------- UPSTREAM - USTBATCH Run a PC Job ---------------
COMMAND ===> SCROLL ===> CSR


Command Line....( /u/user01/setupdb )

Return Code Map ( 0:0 ?:8 )

-------------------------------------------------------------------------------
| ( ) Do not run job, terminate UPSTREAM immediately |
| |
| ( X ) Run job from UPSTREAM and: |
| |
| < > Wait for job completion |
| |
| < > Terminate UPSTREAM after job start/completion |
| |
| < > Log STDOUT and STDERR |
| |
| < > Kill job after wait time limit |
| |
| Wait Time Limit: ( )
Milliseconds |
|------------------------------------------------------------------------------

OK <enter> Prior panel <PF3>

Step #4 - Generate the USTBATCH JCL

On completion of the preceding menu, press the ENTER key, then press the PF3 key to return to the USTBATCH Specification menu. We can now generate the z/OS JCL that is used to invoke the USTBATCH utility program that submits the request to the UPSTREAM started task for processing. You do this by specifying “GEN” on the command line and pressing the ENTER key.

-------------------------- UPSTREAM - USTBATCH ------- * ------------------
COMMAND ===> 3 SCROLL ===> CSR

Gen - Generate statements Read/Save/Delete parameter set

1 - Backup 6 - Restart Restore
2 - Restore & Inquiry 7 - Kill Restart Backup
3 - Run a PC Job 8 - Kill Restart Restore
4 - File Transfer 12 - Operator Commands
5 - Restart Backup 13 - Performance Tests

Communication parameters between USTBATCH and the UPSTREAM Storage Server
HOSTIP ===> HOSTPORT ===> 1972
HOSTDNS ===> YOUR.LPAR.DNS.NAME
APPLPREF ===> QUEUE ===> MAXRETRY ===>
USAPPL ===> CONV ===> TMAXRETRY ===>
TPNAME ===> WTOCOMP ===> APPLRETRY ===>
LOGMODE ===> RESTART ===> TASKLIM ===>

Communication parameters between UPSTREAM Storage Server & Client Target System
 TARGNAME ===> TARGNAME
or DNSname ===>
or TCP/IP addr ===> TCP/IP port ===>
IPADAPTER addr ===>
. ERRWTO . WTOR=>

Remote Parameter File:
WSPARM ===>
USERID ===> | PASSWORD ===> MIXED ===> NO

Login Parameters:
Client Login Name ===>
Client Password ===>

Step #5 - Adding a JOBCARD and STEPLIB

The menu below then allows you to tailor the USTBATCH JCL to match your installation's requirements. As a minimum, you should alter the JCL to provide a valid mainframe JOBCARD. You also need to include a STEPLIB to point to the UPSTREAM load library if it is not in the Linklist. If you use the DNSNAME= option to address the Client, you may also need a SYSTCPD DD statement.

-------------------------- UPSTREAM - USTBATCH -------------------------
 COMMAND ===> 2

 Please select one of the following options or press the END key to cancel

 1 - Browse the generated JCL stream
 2 - Edit the generated JCL stream
 3 - Submit the generated JCL stream
 4 - Save the generated JCL in a data set
 5 - Run the generated USTBATCH statements in the TSO foreground

 JCL statements:
 ( //jobname JOB (job acct data),'job id data',NOTIFY=userid )
 ( //* )
 ( //* )
 ( //* )
 ( //USTBATCH EXEC PGM=USTBATCH )
 ( //STEPLIB DD DISP=SHR,DSN=your.upstream.loadlib )
 ( //SYSUDUMP DD SYSOUT=* )
 ( //USTLOG DD SYSOUT=* )

Step #6 - Editing the USTBATCH Job

Select option 2 on the command line of the preceding menu (then press ENTER) to review and optionally edit the generated USTBATCH JCL and parameters via a standard ISPF Edit screen.

File Edit Confirm Menu Utilities Compilers Test Help
‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹‹
EDIT------ USER01.SPFTEMP1.CNTL--------------------------- Columns 00001 00072
Command ===> Scroll ===> CSR
****** ***************************** Top of Data *****************************
000001 //jobname JOB (accounting,information),'job id data',
000002 // NOTIFY=userid
000003 //*
000004 //*
000005 //BACKUP EXEC PGM=USTBATCH
000006 //STEPLIB DD DISP=SHR,DSN=your.upstream.loadlib
000007 //SYSUDUMP DD SYSOUT=*
000008 //USTLOG DD SYSOUT=*
000009 //USTPARM DD *
000010 HOSTDNS=YOUR.LPAR.DNS.NAME
000011 HOSTPORT=1972 *default
000012 LOGMODE=#INTER
000013 CONV=WAIT
000014 *
000015 TARGNAME=ZVMINST1
000016 *
000017 ACTION=5
000017 SPECNUMBER=1
000018 FILES=/u/user01/*
000019 *
000020 ENDPARM
000021 /*

The above example assumes the user is using UPSTREAM 3.9.1 or later. If using UPSTREAM 3.9.0 or earlier, replace the TCP/IP USTBATCH to Started Task communications parameters HOSTDNS & HOSTPORT with APPLPREF=UPSTR (VTAM APPL Prefix), USAPPL=UPSTREAM (Name of UPSTREAM Started TASK VTAM APPL), & LOGMODE=#INTER (VTAM LOGMODE to use from USTBATCH to STC) for APPC USTBATCH to Started Task communications.

Step #7 - Submitting and Monitoring the USTBATCH Job

The USTBATCH job can then be submitted for batch processing, either immediately, or it can be saved to a member in a PDS for later submission (manually, or through a job scheduling system).

Once it has been initiated, the executing request can then be monitored via the UPSTREAM ISPF STATUS panel (Option #2), or via the UPSTREAM STATUS operator command (UPSTREAM Operation).


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*