z OS Initiation with USTBATCH

Overview

UPSTREAM backup and restore operations can be initiated in many different ways.

• From the Client (see the UPSTREAM Client guide for details)
  
  • Manually, through the Client panels.
    
  • Manually, through the Director Java interface
    
  • Automatically, through the Dispatcher scheduler
    
  • Automatically, through your own client-side scheduler.
    
• From the z/OS Storage Server
  
  • Manually, through the TSO/ISPF dialog (after building a USTBATCH job)
    
  • Manually, through a USTBATCH job (created outside of the ISPF dialog)
    
  • Automatically, initiating a USTBATCH job through the UPSTREAM scheduler
    
  • Automatically, initiating a USTBATCH job through your own scheduler.
    

As you can see, all of the z/OS Storage Server initiation methods listed involve the eventual submission of a batch job to execute the UPSTREAM utility program called USTBATCH, which then communicates with the main UPSTREAM started task to initiate the requested process.

Aside from initiating backup and restore operations, USTBATCH jobs can also be used to initiate other UPSTREAM functions described elsewhere in this manual. For example, you can use a USTBATCH job to invoke any of the following:

• The USTVAULT, USTMIGRT, and USTMERGE utilities (Copying Backups with USTVAULT, Migrating Backups from Disk to Tape, and Completing Deferred Merge Backups)
  
• The File Transfer utility (File Transfer)
  
• A “user process” on an Client (Running an UPSTREAM Client User Process)
  
• The USTMAINT utility and UPSTREAM console commands (UPSTREAM Operation)
  

Automation with USTBATCH

USTBATCH jobs can be submitted manually, or through an automated process, such as your own job scheduling system (if you have one), or through USTSCHED, the scheduling system provided within UPSTREAM (UPSTREAM Scheduler).

USTBATCH processing can be further automated by enabling the “WTOCOMP” facility in the UPSTREAM configuration (see Configure the MAIN Options). This will cause the UPSTREAM started task to issue WTO messages to the system log regarding the completion status of the requested function. These messages can be intercepted by your scheduling and automation systems to control subsequent initiations of additional USTBATCH driven processes, or any other process.

A similar result can be obtained using the CONV=WAIT and WTOCOMP options of USTBATCH itself (described later in this chapter), which cause USTBATCH to produce console messages detailing the progress of initiated tasks.

With careful planning and design, you can potentially automate your entire UPSTREAM workload using a combination of USTBATCH jobs and your job scheduling system or automation systems.

USTBATCH Work-Flow

The work-flow of USTBATCH varies slightly, depending on whether the requested process is “client-based” (e.g., you are running a backup) or “host-based” (e.g., running an UPSTREAM internal utility, such as USTVAULT, USTMERGE, or USTMIGRT).

Running a “Client-Based” Process

The following sequence of events occurs when USTBATCH is used to initiate an Client-based process, such as a backup, restore or file transfer.

• A USTBATCH job is submitted on the mainframe either manually or automatically, as previously described.
  
• USTBATCH allocates a VTAM APPC (LU 6.2) conversation to the UPSTREAM started task. Unless the CONV=WAIT option is specified (see below), the USTBATCH job does not need to run on the same z/OS system as UPSTREAM, so long as there is a VTAM connection between the z/OS images.
  
• USTBATCH then forwards the specified request (backup, restore, etc) to the UPSTREAM z/OS started task, including all of the supporting parameters that may have been provided within the USTBATCH job. As a minimum, this job contains details of the target Client on which the process is to run. It may optionally contain additional parameters to control how that process operates.
  
• PSTREAM stores the received request and parameters (for potential retry attempts) before initiating a conversation with the target Client. The actual request and specified parameters are then sent to the Client for action, together with a request for a “confirmation”. If no response is received from the target Client within three minutes, UPSTREAM times-out the request and logs an error (though this can be overridden by adding PARM='NOTIMER' to the USTBATCH EXEC statement).
  
• If the target Client is busy or not available when the request is sent, a retry process is started by the online initiator, as controlled by various “retry” parameters available to USTBATCH (APPLRETRY, TMAXRETRY, MAXRETRY - as described later).
  
• If the request is accepted by the Client, a “confirmed” response is returned to the requesting USTBATCH task, which in turn logs the confirmation. If CONV=KEEP or WAIT is specified, the “confirmed” response is not returned until the Client has validated and initiated the request.
  
• Once the request has been accepted and the initiation of the process is completed at the Client (either successfully, or the retries have been exhausted), the online initiator logs the final results of the initiation attempt to the online UPSTREAM log.
  
• Assuming the initiation attempt was successful, the target Client then starts a conversation with the UPSTREAM started task to begin the requested operation (e.g., the backup, restore). If CONV=KEEP or WAIT is specified, the Client uses the connection that was previously established for the initial request, otherwise it disconnects and establishes a new connection.
  
• If CONV=WAIT is not specified, USTBATCH terminates its connection as soon as the Client has accepted the initial request. It then continues to scan the job input to see if another Client operation has been requested within the same batch job. If so, that operation is initiated, as previously described. If no additional Client operations have been requested, the USTBATCH job terminates.
  
• If CONV=WAIT is specified, USTBATCH scans all of the input during initiation and builds a queue of requests. It then goes through the process described for each request in the queue, retaining the conversation with the UPSTREAM started task until the Client(s) complete the processing of the request(s). It then logs a final return code associated with each request in the USTBATCH log (and optionally to the system console if WTOCOMP is specified). If e-mail notification is enabled, and if the specified condition is met, an e-mail will be issued at the completion of each step. When working with a queue of requests in this way, USTBATCH attempts to concurrently initiate as many of the requests in its queue as possible (but controlled by the TASKLIM parameter).
  

Running an z/OS Storage Server-Based Process

When USTBATCH is used to initiate a “host-based” process, such as USTMERGE, USTMIGRT, USTVAULT (or perhaps a console command), no communication with an Client is required. All communication is between the USTBATCH job and the UPSTREAM started task.

The request or command is executed by UPSTREAM as if it was entered on the z/OS console. If CONV=WAIT is specified, USTBATCH waits for the end of the execution of the request or command. It then logs the success or failure of the request and displays any messages associated with it. If e-mail notification is enabled, and if the specified condition is met, an e-mail is issued at the completion of each step.

E-mail Notification

USTBATCH can issue a condition code dependent e-mail indicating the success or failure of the USTBATCH operation. This is invoked by an optional USTEMAIL DD statement in the USTBATCH job step. The DD statement references control statements defining the message and the recipients, This feature is supported for either “Client based” or “Host based” processes. The use of CONV=WAIT (described previously) and an e-mail server that supports SMTP (Simple Mail Transport Protocol) are also required.

Creating Your USTBATCH Jobs

USTBATCH jobs can be created in one of two ways, as follows:

Through the UPSTREAM TSO/ISPF Dialog

Many of the previous chapters in this manual include samples of the TSO/ISPF dialogs that can be used to create USTBATCH jobs. Some examples include:

• Running USTREORG (The UPSTREAM Repository)
  
• Performing a Backup
  
• Performing a Restore
  
• Copying Backups with USTVAULT
  
• Migrating Backups from Disk to Tape
  
• Completing Deferred Merge Backups
  
• Updating the Repository
  
• Running an UPSTREAM Client User Process
  

When using the TSO/ISPF dialogs, you do not have to be concerned about the USTBATCH parameter formats and coding rules (described later in this chapter), since all parameter generation is done for you.

Manual Job Creation

As an alternative, however, you can create USTBATCH job manually, without the use of the TSO/ISPF dialogs. The remainder of this chapter describes the parameters and settings available under USTBATCH.

Some example USTBATCH jobs are shown in USTBATCH Examples.

USTBATCH JCL Parameters

These are the JCL parameters required to execute USTBATCH.

EXEC Statement

Must specify PGM=USTBATCH.

The EXEC statement should specify REGION=0M to make the maximum region available.

It may optionally contain a PARM= operand to pass options to the USTBATCH program. For example, “PARM=NOTIMER” overrides the 3-minute timer that the UPSTREAM started task uses to determine if an Client is not responding (although this is not generally recommended).

Any PARM= data passed to the USTBATCH program is interpreted as control statement input. Multiple commands specified via this method must be separated by a slash “/” character.

JOBLIB or STEPLIB DD Statement

If UPSTREAM has not been placed into the system linklist, this DD statement is required to point to the UPSTREAM load library. This must be an APF authorized library.

SYSTCPD DD Statement

This is an optional data set for use when a TCP/IP Domain Name Server (DNS) is not defined in the TCP/IP PROFILE data set. In the absence of a Domain Name Server to handle the name resolution requests, the SYSTCPD DD statement is used to point to a valid TCPDATA data set or member.

SYSUDUMP DD Statement

Recommended in all USTBATCH jobs in order to diagnose more easily error conditions that make USTBATCH abend.

USTEMAIL DD

This data set is a PDS with one or more members that specify input control statements, defining the message and the recipients, for the USTBATCH e-mail facility. If present, USTBATCH can issue an e-mail indicating the success or failure of the USTBATCH operation. The data set must have the characteristics RECFM=FB and LRECL=80.

USTLOG DD Statement

This is the USTBATCH log file, which contains informational and error messages. It is usually a SYSOUT data set with the characteristics RECFM=V, LRECL=134, and BLKSIZE=138.

USTPARM DD

This data set contains the USTBATCH input parameters. It may be a SYSIN data set, or it can point to a parameter file. It must have the characteristics RECFM=FB and LRECL=80.

17.6 USTBATCH Input Parameters

Input parameters to USTBATCH are fixed-length 80-byte records. The rules for coding the USTBATCH input parameter records are as follows:

• All parameters must start in the first position (column 1) of the record.
  
• All keyword parameters must be followed by at least one blank. All Client override parameters, since they may contain embedded blanks, must be followed by at least 2 blanks. Blanks are not required if the parameters extend to the end of the record (column 71). Parameters can be continued to another record, following these rules:
  
  • Enter the parameter text in columns 1 to 71 of the current record. The text must continue through column 71. No comments are permitted.
    
  • Place any non-blank character in column 72.
    
  • Start the continuing text in column 1 of the next record. It will be concatenated with the text from the previous statement.
    
  • A statement can be continued multiple times, for a maximum parameter length of 261 characters, including blanks.
    
• Data beyond a terminating blank is considered as a comment. Entire comment records may also be included anywhere in the input parameter file. They are indicated by the presence of a “*” in the first position of the record.
  
• Only one parameter is permitted per input record, except that the WSPARM= operand can also appear after a TCPTARG or TARGLU= parameter.
  
• Certain parameters apply to the entire USTBATCH step. They can appear only once in the input and must be placed at the beginning of the input. These parameters are documented in "Single Use” Input Parameters.
  
• Other parameters apply to a target Client that will be contacted by this execution of USTBATCH. If requests are to be sent to multiple Clients, these parameters can appear many times in the USTBATCH input. These parameters are documented in "Multiple Use” Input Parameters .
  
• The operation to be performed may be fully described in a “parameter file” stored on the target Client. If that is the case, the USTBATCH input parameters need only to provide the name of the target Client (via TCPTARG, TARGNAME, DNSNAME or TARGLU,) and the name and location of the Client's parameter file. However, USTBATCH input parameters can also be used to modify or override some/all of the client-side parameters. These parameters are documented in USTBATCH “UPSTREAM Client Override” Parameters.
  
• If any optional parameters that have a default value are omitted, a warning message is logged and the USTBATCH step will end with return code 4, even if the request is successfully processed.
  
• The end of a set of Client parameters is assumed when another TCPTARG, TARGNAME, DNSNAME, or TARGLU parameter is found, or the end of the USTBATCH input is encountered.
  

USTBATCH Input Parameters

USTBATCH Input Parameters

“Single Use” Input Parameters#

The following “single use” input parameters may appear only once and must be placed before any of the “Multiple Use” Input Parameters (except for LOGMODE=).

ALLOWDUP=#

Controls the ability to have multiple requests for the same target Client running simultaneously and initiated by a single USTBATCH job step. This parameter, when used in conjunction with TASKLIM, allows for a reduction in the number of separate USTBATCH jobs required to initiate a given workload.

YES - multiple requests for the same target Client running simultaneously is allowed.

NO - multiple requests for the same target Client running simultaneously is disabled.

Default: NO.

APPLPREF=#

Specifies the five-character prefix that USTBATCH uses to build its own VTAM APPLID value. It appends a character-numeric value (beginning at “001”) to the specified APPLPREF and use the resulting name to attempt to open a VTAM ACB (with the generated name as the APPLID). If that APPLID is already in use, the appended value is incremented until a free APPLID is found.

Default: UPSTR.

APPLRETRY=#

Used only if USTBATCH cannot find a free VTAM application ID (see APPLPREF=). USTBATCH waits 5 seconds and tries again, repeating this until a free application ID is found or the APPLRETRY limit is reached.

Default: 240, which causes USTBATCH to retry every 5 seconds for about 20 minutes.

CONV=#

As described in USTBATCH Work-Flow, USTBATCH always establishes an APPC connection to the UPSTREAM started task for each requested operation specified in its input stream. It then transmits details of the target Client and (optionally) parameters relating to the requested operation. The UPSTREAM started task then initiates a conversation with the target Client and forwards the request. The CONV= parameter controls what happens next:

NONE - causes the Client to disconnect as soon as the request has been accepted. The UPSTREAM started task informs USTBATCH that the request has been accepted (or not), and USTBATCH disconnects and goes on to process its next request, or terminates if there are no more requests. The Client then reconnects to the UPSTREAM started task to perform the requested function.

KEEP - causes the UPSTREAM started task to use the same conversation with the Client for processing the request as was used to send the initial request - i.e., it keeps that connection open to process the request. USTBATCH is notified as soon as the Client begins processing the request, at which point it disconnects and processes its next request, as with CONV=NONE.

WAIT - includes the effect of CONV=KEEP. In addition, USTBATCH remains connected to the UPSTREAM started task until the Client completes the requested operation, at which time USTBATCH logs the final return code and UPSTREAM messages associated with the operation. This allows the success or failure of the operation to be determined from the USTBATCH log. If WTOCOMP is also specified, the return code is logged on the system console as well as in the USTBATCH log.
CONV=WAIT causes USTBATCH to maintain two internal queues of requests. All the requests in the USTBATCH input are parsed and added to a “wait” queue, ready for initiation. USTBATCH attempts to initiate concurrent requests to multiple Clients, keeping as many Clients busy as possible (controlled by TASKLIM). Once a request has been successfully initiated, it is transferred to an “active” queue to await notification of its completion. CONV=WAIT also enables USTBATCH to accept console commands which can be used to display USTBATCH status and modify its operation, as described in Controlling USTBATCH.

Default: WAIT.

EMAILOK=#

EMAILWRN=#

EMAILERR=#

Used when the USTBATCH e-mail notification facility is invoked by the presence of the USTEMAIL DD statement in the USTBATCH JCL. These optional parameters each specify a unique member of the PDS referenced by the USTEMAIL DD statement. This member specifies input control statements, defining the message and the recipients of the e-mail, that is issued if the return code result indicated in message UST747[E]* of the UPSTREAM process is met. (This should not be confused with the Job condition code.)

EMAILOK=member_name

invoked upon a return code of 0.

EMAILWRN=member_name

invoked upon a return code of 4.

EMAILERR=member_name

invoked upon a return code greater than 4.

As previously mentioned, there should be a member in the PDS referenced by the USTEMAIL DD statement, for each of the preceding three parameters. Those members specify:

TCPNAME

name of the TCP/IP started task.

MAILSERVER

the SMTP mail server IP address or DNS name.

FROM

e-mail address of the sender.

TO

one or more recipient e-mail addresses.

SUBJECT

subject line that may contain substitution variables (see below).

The body of the e-mail is defined on the line following the SUBJECT line and is one or more lines of text that may contain substitution variables (see below).
The substitution variables used for the Subject line and the e-mail body text are:

&JOBNAME

replaced by the batch jobname.

&STEPNAME

replaced by the name of the batch JCL step.

&EMAILDATE

replaced by the current date in the form MM/DD/YYYY.

&EMAILEDAT

replaced by the current date in the form DD/MM/YYYY.

&EMAILTIME

replaced by the time of day in the form HH.MM.SS.

&SYSTEM

replaced by the z/OS System ID the started task is running on.

The UST747[E]* message text is included at the end of the specified e-mail text as the last message line.

Please see Example 4: E-mail Notification.

ERRWTO=#

n the event of a failure of a USTBATCH-initiated process, this parameter specifies up to 60-characters of text to include in a UST731E message written to the system console and system log. Three variables may be embedded within the text to allow for customization of the message:

&JOBNAME

include the z/OS job name in the message text (8 characters).

&STEPNAM

include the z/OS step name in the message text (8 characters).

&NAME

include the target Client name in the message text (20 characters).

A reason code is also provided with the following meanings:

4– USTBATCH cannot establish or maintain communications with the UPSTREAM started task.

 8– the UPSTREAM started task cannot establish or maintain communications between itself and the target Client.

 12– this reason code occurs if any other error is encountered on the connection.

If specified, this keyword must follow TCPTARG, TARGNAME, or DNSNAME.

ERRWTOR=#

See ERRWTO=for full details. Using ERRWTOR instead of ERRWTO causes USTBATCH to wait for a reply from the system operator or an automated operations console product.

If specified, this keyword must follow TCPTARG, TARGNAME, or DNSNAME.

HOSTDNS=#

aaaaaaaaa or aaa.aaa.aaa

The DNS name of the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTIP parameter. If a Domain Name Server is not pre-configured in the TCP/IP PROFILE data set, the USTBATCH JCL must contain a SYSTCPD DD statement pointing to a valid TCPDATA file or member.

The value may be up to 64 characters.

HOSTIP=#

nnn.nnn.nnn.nnn - The IP address of the TCP/IP stack on the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTDNS parameter.

The IP address is specified in dotted-decimal form, e.g., HOSTIP=192.175.000.000. Optionally, the HOSTPORT may be specified following the HOSTIP by separating the values with “..” or a comma e.g., HOSTIP=192.175.000.000..1972 or HOSTIP=192.175.000.000,1972

The value may be up to 21 characters.

HOSTPORT=#

nnnnn - The IP port number of the UPSTREAM started task. This parameter may be used with either the HOSTDNS or HOSTIP parameters.

Default: 1972

The value can range from 1 to 65535.

IPADAPTER=#

nnn.nnn.nnn.nnn - Specifies the IP address of an IP stack to which the UPSTREAM started task should bind to make the connection to the Client when CONV=WAIT or KEEP is specified. It is required only if the z/OS Storage Server has multiple TCP/IPs running. The IP address is specified in dotted-decimal form, e.g., IPADAPTER=192.175.000.000.

LOGMODE=#

For connections to VTAM SNA Clients only. It specifies the VTAM logon mode entry name that is used by the UPSTREAM started task to establish a session with the SNA Client. It is also used by the Client when it establishes its session back to UPSTREAM to perform the requested function. (See Define Optional VTAM System Resources for a discussion of the mode tables used by UPSTREAM).

Default: #INTER.

MAXRETRY=

nnn - Used only if the UPSTREAM sub-task fails its initial attempt to initiate a conversation with the Client. This parameter specifies the maximum number of retry attempts allowed. If the MAXRETRY value is non-zero and the initial attempt fails, USTBATCH retries the initiation with the Client every 10 minutes, decreasing the retry count until it reaches 0. At that time, an “LU NOT AVAILABLE” indication is sent to USTBATCH and subsequently logged. Any value from 0 to 255 is allowed.

If a RESTART count is also specified, and the MAXRETRY value is lower than the RESTART count value, MAXRETRY value is set to the RESTART count value.

Default: MAXRETRY=5,10.

QUEUE=#

In the event that the target Client cannot process a request immediately, this parameter instructs the Client to queue the request, if possible. Otherwise, requests are not queued.

RESTART=

nn,nn - Controls automatic restart of backups (if they are defined as restartable) and restores if a communication failure occurs and if CONV=WAIT is also specified. It has two values (e.g., RESTART=3,2). The first value is the number of times to attempt a restart of an interrupted operation. The second value is the number of minutes to wait between restart attempts. When a communication error occurs and a wait to restart is begun, a message is issued to the z/OS operator in case some type of manual intervention is required to correct the communications problem.

Default: RESTART=5,10.

TASKLIM=#

nnnn - A 4-digit numeric value specifying the maximum number of concurrent tasks a USTBATCH utility job will dispatch. Once this value is reached, USTBATCH does not initiate another request until one or more of active tasks ends.

Only valid if CONV=WAIT is specified.

Default: 1.

TIMEOUT=#

nnnn - If CONV=WAIT was specified, this specifies the number of minutes (1 to 1440) to wait for the request to complete. If the request does not complete within the time limit, it is terminated.

Default: 10.

TMAXRETRY=

Used only if USTBATCH connects to UPSTREAM but is informed that the started task is already at its maximum permitted sub-task limit, as defined by the MAXTASKS configuration parameter (see Configure the MAIN Options). USTBATCH retries the operation every 10 minutes until it is accepted, or until the specified TMAXRETRY limit is reached.

Default: 0 (no retries), the recommended value.

USAPPL=#

cccccccc - Specifies the VTAM APPLID of the UPSTREAM started task. USTBATCH uses this value to allocate an LU 6.2 conversation with UPSTREAM to request the remote initiation of the requested function. The USAPPL value must match the value specified for APPLID= in the UPSTREAM configuration (see Configure the MAIN Options).

Default: UPSTREAM.

VERIFY=#

Controls the verification of the spelling of input parameters (i.e., not the syntax or values, just the spelling). All valid input parameters to USTBATCH are shown in this chapter of the manual.

YES - Specifies that the spelling of these parameters will be verified.

NO - Requests that the parameters are not verified.

Default: NO.

WSPARM=#

This optional parameter specifies the name and location of a parameter file on the target Client that is used to control the requested operation (e.g., backup, restore). See full documentation of WSPARM under the “Multiple Use” Input Parameters for more details. The value may be up to 255 characters.

WTOCOMP=#

If CONV=WAIT is specified, WTOCOMP causes USTBATCH to issue a UST747[E]* message on the system console indicating the success or failure of each Client request. This may be used for visual confirmation by the operator, or for use with automation products.

“Multiple Use” Input Parameters#

The “multiple use” input parameters described below can appear one or more times in the USTBATCH input. The parameters may be repeated to invoke multiple UPSTREAM operations or console commands.

For “host-based” operations, each individual set of parameters will begin with COMMAND.

For “client-based” operations, each individual set of parameters must start with one of the following to identify the target Client: TCPTARG, TARGNAME, DNSNAME, or TARGLU. These “Client identifying” parameters can then be optionally followed by “Client override” parameters, which can be used to specify or modify the operation to be performed at the Client.

COMMAND=

CMD=

Specifies an z/OS console command to be issued to the UPSTREAM started task, such as a request to initiate “host-based” operations like USTVAULT, USTMIGRT or USTMERGE. See UPSTREAM Operation for full details on the z/OS console commands that can be issued to control UPSTREAM, either through USTBATCH or through the USTCMD dialog. The USTBATCH COMMAND parameter does not include the “F UPSTREAM” portion of the z/OS command. It cannot be continued beyond column 71. For example:

    COMMAND=STATUS    CMD=VAULT01 PROFILE=PAYROLL

DNSNAME=#

This allows you to identify the target Client using a TCP/IP Domain Name Server (DNS) name (up to 64 characters). If a Domain Name Server is not pre-configured in the TCP/IP PROFILE data set, the USTBATCH JCL must contain a SYSTCPD DD statement pointing to a valid TCPDATA file or member.

TARGLU=

(For VTAM/SNA Clients.) Specifies the network LU name of the target Client.

TARGNAME=

Specifies the UPSTREAM registered name of the target Client. As described in Registered Name Service, the UPSTREAM registered name service allows you to identify a target Client using a descriptive name that is independent of its current network address and connection type.

TCPPORT=#

(For TCP/IP Clients.) Specifies the TCP/IP port number on which the Client is configured to listen for z/OS Storage Server requests, as configured within the Client software. The TCPPORT= value can be optionally specified after TCPTARG= or DNSNAME=.

Default: 1972.

TCPTARG=

(For TCP/IP Clients.) Specifies the IP address of the target Client, specified in “dotted decimal” form. The TCP/IP port number (see “TCPPORT=” in Section) can optionally be appended to the address as 2 more periods (or a comma) and the decimal port. Examples:

Or:

TPNAME=

cccccccc - (For VTAM/SNA Clients only.) Specifies the Transaction Program Name (TPName) used to communicate to the Client. Used only following TARGLU= (or TARGNAME, when the connection is SNA) TPNAME= allows multiple simultaneous mainframe initiated conversations to SNA Clients.

Default: UPSTREAM.

WSPARM=

This optional parameter specifies the name and location of a parameter file on the target Client, which is used to control the requested operation (e.g., backup, restore). One or more of the parameters contained in that Client parameter file can, however, be overridden from within the USTBATCH job itself, as described in “Non-Repeated” Client Override Parameters.

The WSPARM value is passed to the target Client during the initiation request from the UPSTREAM started task. It appears as a sub-parameter on the TCPTARG= parameter:

Although, strictly speaking, WSPARM is regarded as a “multiple use” parameter, it can operate as a global “Single Use” Input Parameters. This, however, assumes that the name and the location of the Client parameter file is consistent across all target Clients. For example, the following WSPARM could be coded as a global “single use” parameter in USTBATCH, negating the need to code it for every target Client:

The WSPARM value may be up to 255 characters.

USTBATCH “UPSTREAM Client Override” Parameters

In addition to the “single use” and “multiple use” USTBATCH parameters previously described, the USTBATCH job may also include parameters that are specific to the UPSTREAM Client request, and which control or override the behavior of that request.

Client override parameters apply only to the Client request defined by the preceding TCPTARG, TARGNAME, DNSNAME, or TARGLU in the USTBATCH input stream. They can be either “non-repeated” (single use) or “repeated” (multiple use).

Full details of all these parameters can be found in the UPSTREAM Client Guide.

The examples section includes an example (Example 2: “BATPARM”) of a USTBATCH job that uses some of these parameters.

“Non-Repeated” Client Override Parameters#

This section describes all “non-repeated” Client override parameters. These parameters can be specified only once per each target Client.

Required Parameters

ACTION=

The function to be performed.

0 - Restore (or “Client receive” file transfer)

1 - Backup (or “Client send” file transfer)

2 - As of … Restore

3 - Wait for remove initiate

4 - Restart backup only

5 - Run a Client process

6 - Kill last restartable backup

7 - Run z/OS Storage Server report

8 - Restart restore only

9 - Kill last restartable restore

10 - Submit a z/OS Storage Server job

12 - Inquire versions

13 - Performance test

14 - Physical disk restore

15 - Physical disk backup

16 - Delete backup

17 - Register target name

18 - Inquire file

Default: 1.

Optional Parameters

ASCTOEBC=

filename - The name of a Client file containing a user-supplied ASCII to EBCDIC translation table. This table is used for this and all subsequent operations on the Client until UPSTREAM is terminated and restarted. If not specified on a Client, a default US English translation table is used.

Default: USATOE.TAB.

ATTENDED=

Y - It is assumed that there is a user present to make prompted decisions.

N - Unattended mode. It is recommended that you also specify MESSAGETIMELIMIT as well.

Default: Y.

BACKUPPROFILE=

cccccccc - The backup profile name. You can specify up to 8 characters.

Default: NONE.

BACKUPVERIFY=

Y - UPSTREAM reads and compresses the data, but does not sent it to the z/OS Storage Server. A checksum of the data is compared against a checksum on the z/OS Storage Server. If a mismatch occurs, the file is transmitted. As it degrades performance, this option should be used on slow lines only when you wish to verify non-file data.

Default: N.

BLANKTRUNC=

If the LINEBLOCK parameter is set to Y, this parameter controls truncation of trailing blanks.

Y - Trailing blanks are removed from records being transmitted.

N - Trailing blanks are not removed.

Default: Y.

CALCDASDSIZE=

N - If you are performing a sequential disk backup the amount of space allocated on z/OS for the backup depends on the amount of file data found.

Y - If you are performing a sequential disk backup the amount of space allocated on z/OS depends on the amount of file and non-file data found.

Default: N.

COMPRESSLEVEL=

Selects the level of compression to be performed on the backup data by the client before that data is transmitted to the z/OS host.

0 - No compression

1 - Fast compression

2 - High compression 1

3 - High compression 2

4 - High compression 3

Default: 1.

DASDOVERRIDE=

Allows you to override the amount of space (bytes) requested on a sequential disk backup. There are four forms:

+n…n - Add the given number of bytes to the total calculated.

-n…n - Subtract the given number of bytes from the total calculated.

nnn% - Use the given percentage to calculate the total.

n…n - Use the given number to override any calculated value.

Default: 100%.

DISPLAY=

Y - Backup or restore status information continually updated.

N - No status display during the backup or restore.

Default: Y.

EBCTOASC=

The name of a Client file containing a user-supplied EBCDIC to ASCII translation table. This table is used for this and all subsequent operations on the Client until UPSTREAM is terminated and restarted. If not specified on an Client, a default US English translation table is used.

Default: USETOA.TAB.

EXCLUDELISTNAME=

Specifies the name of a Client exclude list file.

FAILJOB

If specified, this job is run if the current function fails and UPSTREAM is running in unattended or z/OS Storage Server initiated mode.

FILETRANSFER=

Controls the file transfer facility (the ACTION parameter controls whether it is a send or receive).

Y - This is a file transfer operation.

N - This is a backup or restore.

Default: N.

HOLDTAPE=

Y - UPSTREAM keeps the tape volume mounted for an additional 2-3 minutes after this backup request completes so that any additional requests for this tape volume by the same profile can be satisfied without causing it to be remounted. This feature is used primarily by the database interfaces.

N - Tape volumes are immediately de-allocated at the end of the request.

Default: N.

HOSTFILENAME=

If specified, the name of the z/OS Storage Server file. If not specified, UPSTREAM generates a name for Client sends, or uses the latest recorded file transfer for Client receives.

HOSTRECORD=

For client-to-host transfers only.

Y - Details of files transferred to the z/OS Storage Server are to be recorded in the UPSTREAM CATALOG repository file for reporting purposes.

N - Transferred files are not recorded in the UPSTREAM CATALOG repository.

Default: Y.

HOSTSORT

Y - Use the z/OS Storage Server sort utility.

N - Do not use the z/OS Storage Server sort utility.

Default: N.

INQOPTIONS=

A bit map of options used during inquiry and restore

0 - Inquiries and restores only show normal files and the highlighted backup (VERSIONDATE)

1 - Inquiries show migrated files as well as normal files

2 - Inquiries and restores use “Highlighted back to full”.

4 - Inquiries and restores operate from the currently highlighted backup to the first version (“Highlighted back to oldest”).

8 - (not used)

16 - Only display migrated files in an inquiry

32 - Reserved

64 - Expiration date is displayed for migrated files.

128 - Old style file inquiries work as for list and restore.

Default: 2.

JOBOPTIONS=

A bit map of options used when a job is requested and started.

0 - Start job and immediately terminate UPSTREAM.

1 - Start job and do not terminate UPSTREAM.

2 - Wait for job to be terminated.

4 - Kill the job if it runs longer than the JOBWAITTIMELIMIT number of milliseconds or when UPSTREAM terminates. Also sets value 2.

8 - No job, terminate the current UPSTREAM program. Terminates the parent as well if running in automatic attach manager mode.

16 - (UNIX) Run the job using exec() (Internal use only).

32 - Write the STDOUT and STDERR output from the job to the UPSTREAM log and back to the Storage Server (if CONV=WAIT and value 1 is specified). Implicitly sets value 2.

Default: 0.

Recommendation: 35 (32+2+1).

JOBRETURNCODEMAP=

For CONV=WAIT jobs, a mapping between the Client return code and the z/OS Storage Server job return code. You can specify multiple mappings (including Client return code ranges). The “?” is used for all unassigned Client return codes.

Default: 0:0 ?:8.

KEEPALIVE=

nn - This parameter allows you to tune how often (in seconds) “Keep Alives” are transmitted to the z/OS Storage Server. Keep Alives are used to tell the z/OS Storage Server how much data the Client has written and allows the z/OS Storage Server to read the data from the disk as the Client is writing it.

Default: 2.

LATESTVERSION=

Y - Restore the latest version available for the backup profile.

N - Use a specific version date.

Default: Y.

LINEBLOCK=

Y - Records are separated by a CR/LF (LF only on Unix) for Client sends; CR/LF (LF only on Unix) is added to the end of each record for Client receives.

N - All records are separated by the record size (Client sends).

Default: Y.

LINETRUNC=

Used only if LINEBLOCK=Y for Client sends).

Y - Data exceeding the record size is truncated

N - Data exceeding the record size is sent as a separate record.

Default: Y.

LOCALBACKUP=

0 - Host storage is used exclusively for backups and restores.

1 - During a backup, files should be stored locally as well as at the host. During a restore, files should be taken from local storage whenever possible.

2 - Local backups are stored on shared EMC or IBM FDRSOS Local Backup disks.

Default: 0.

LOCALBACKUPDIR=

If local backups are enabled to:

1 - Disk (LOCALBACKUP=1) the name of the directory where the local backup files are stored.

2 - FDRSOS (LOCALBACKUP=2) the internal UPSTREAM name of the disk where the data is stored.

Default: None.

LOCALBACKUPMAX=

n - The number of local backups to keep. When a new local backup is created in the location specified by LOCALBACKUPDIR and there are already “n” or more such backups in that location, the older ones are deleted.

Default: 3.

LOCALBACKUPMAXFILESIZE=

nnnnn - The maximum size of a file to be placed in local backup, in bytes. Files greater than this size are not backed up locally.

Default: 10MB.

LOCALBACKUPMAXSIZE=

nnnnnn - The maximum size of the local backup file, in bytes. Once this many bytes have been placed in the local backup file, no more files are backup up locally (but they are still sent to the z/OS Storage Server.

Default: 100MB.

LOCALPASSWORD=

The password of the remote user who wishes to logon to this system.

LOCALUSER=

The local user name of the remote user who wishes to logon to this system. For Windows NT, you can specify domain/user.

LOGNONFATAL=

0 (or N) - Non-fatal errors during a backup are not logged, displayed or transmitted to the z/OS Storage Server.

1 (or Y) - Non-fatal errors during a backup are logged and displayed.

2 - Only messages during a backup which result in a skipped file are transmitted to the z/OS Storage Server.

Default: N.

MAXBACKUPTIME=

nn - The number of minutes before a backup will terminate due to excessive time.

0 - No termination.

Default: 0.

MAXKFILESIZE=

nnnn - Exclude files that are larger than the specified size (in 1024 byte increments).

0 - No file size exclusion.

Default: 0.

MAXRESTORETIME=

nnnn - The number of minutes before a restore will terminate due to excessive time.

0 - No termination.

Default: 0.

MERGE=

The backup type:

0 - No merge used

1 - Full merge

2 - Incremental merge

3 - First-time merge backup

Default: 0.

MINIMIZE=

Y - Allows UPSTREAM, when running unattended, to start minimized.

N - Do not start minimized.

Default: N.

MODIFYFILE=

Y - Incremental backup eligibility is determined by the last date/time UPSTREAM was run (stored in the modification file).

N - Incremental backup eligibility is determined by the archive bit.

Default: Y (for UNIX); N (for other environments).

NOVELLPROFILE=

The profile name, set in SETNOV.EXE, referencing the server, user name, and drive mappings to be mapped to your Novell file server.

Default: NONE.

NOVELLRECALL=

Y - This backup profile could be used to backup a Novell server that uses the UPSTREAM auto-recall facility.

N - This backup profile is never used to backup a Novell server that uses the UPSTREAM auto-recall facility.

Default: Y.

NTREGRESTORE=

Windows NT registry restore options:

0 - “Legacy.” Replace the registry with no additional prompting.

1 - “Keep.” Keep existing registry entries, but prompt allowing user interaction if attended.

2 - “Replace.” Replace registry entries, but prompt allowing user interaction if attended.

Default: 0.

PACKFLUSHAFTERFILE=

Y - Forces a packed record in a backup to be transmitted after each file.

N - Records are fully packed.

Default: N.

PACKRECSIZE=

No longer used and replaced by USBACKUPPACKRECSIZE and USRESTOREPACKRECSIZE.

PASSWORD=

cccccccc - The password associated with the security userid. Usually required if USERID is required. However, it can be omitted if the security userid is the same as the userid under which the USTBATCH job is being run.

PERFORMBITMAP=

If ACTION=13, specifies a bit map of the performance tests you wish to run.

8 - Backup, no I/O test

16 - VSAM performance test

32 - Raw communications test, PC send

64 - Raw communications test, z/OS send

128 - Backup - no communications

For additional details, please see the UPSTREAM Client Guide, Performance, Chapter 8.

Default: 96 (64+32).

PERFORMNUMRECORDS=

nnnnnnn - The number of records sent/received on raw communications performance tests.

Default: 5000. Maximum is 1048570.

PERFORMRECORDSIZE=

nnnnnnn - The size of records sent/received on raw communications performance tests.

Default: 32700. Maximum is 1048570.

POSTJOB=

cc…cc - If defined, this is the name of a program, batch file, or script file that is run after the unattended UPSTREAM function.

PREJOB=

cc…cc - If defined, this is the name of a program, batch file, or script file, that is run before the unattended UPSTREAM function.

PRTYCLASS=

The priority class for the requested action:

1 - Idle-time.

2 - Regular.

3 - Time-critical (Very Dangerous).

4 - Fixed-high.

Default: 4.

PRTYLEVEL=

nn - A number from 0 to 31 (OS/2) or 0 to 8 (32-bit Windows, where 0 and 1 are resolved as 8) modifying the priority class.

Default: 1 (OS/2) and 6 (32-bit Windows).

RECALLCLEANUP=

Y - UPSTREAM examines Novell auto-recall stub files to determine if any have expired and, if so, they are deleted.

N - Auto-recall stub files are not deleted.

Default: N.

RECORDSIZE=

No longer used and replaced by USERECORDSIZE.

REPORTNAME=

cc…cc - The name of the file to write reporting information to.

Default: UPSTREAM RPT.

REPORTOPTIONS=

A bit map describing any of the report features you wish to enable, add the required options and enter the sum:

1 - Files backed up/restored

2 - Files skipped during the backup

4 - Files automatically deleted

8 - Inquire versions

16 - Inquire files

32 - Specified parameters

Default: 0.

RESTARTTYPE=

Specifies the action to be performed at a restart point (usually the next time UPSTREAM is run) if there is a restartable error:

0 - Never restart.

1 - Restart failed files and incomplete backups.

2 - Restart only incomplete backups.

Default: 0.

RESTOREARCHIVEBIT=

Y - Archive bits are set for files that are restored.

N - Archive bits are not set for files that are restored.

Default: N.

RESTORECHECKPOINT=

nnnn - The number of seconds between automatic checkpoints when performing a restartable restore.

Default: 120.

RESTOREFILEDAIL=

Allows you to specify what to do if a file is locked when you attempt to restore it.

0 - Fail the file.

1 - Restore the file to a generated name.

2 - Restore the file to a generated name and rename the file to its original name after a reboot.

Default: 0.

SENDHOSTDETAILS=

N - Only the first line of an error is sent to the z/OS Storage Server.

Y - All message lines of a message are sent except additional description lines from the message file.

Default: N.

SKIP=

For restores using “List and Restore”, a set of options of how to process existing files:

0 - Restore all files regardless of whether there are existing files

1 - Restore only files where there is no existing file of the same name

2 - Restore only files where the existing file's modification date/time and size are not the same.

Default: 0.

SKIPBACKUPSCAN=

Y - UPSTREAM does pre-scan the disk for files to backup but performs the scan while the backup is running. Only recommended in certain cases due to the lack of a size estimate. For disk backups, must also specify DASDOVERRIDE.

Default: N.

SORTBACKUP=

Y - Sorts the backup in the same order as the z/OS Storage Server uses. May result in slightly reduced FILEINFO overhead.

N - Do not sort the backup in the order that the z/OS Storage Server uses.

Default: N.

STORAGETYPE=

Specifies how the data is stored on the mainframe.

2 - Sequential disk. Stored directly to mainframe disk.

3 - Sequential tape. Stored directly to mainframe tape.

Default: 3.

TIMEOVERRIDE=

(Win32) overrides the time settings for a given backup specified in the Configurator parameter TIMECONVERSION.

0 - Local time.

1 - Standard time.

2 - Daylight savings time.

3 - Greenwich Mean Time.

Default: 0.

TRANSLATE=

Y - ASCII-to-EBCDIC translation is performed on all data (assumes text).

N - No translation of the data (assumes binary).

Default: Y.

USBACKUPPACKRECSIZE=

nnnnn - The maximum number of bytes transmitted to the z/OS Storage Server. If less than the value for USERECORDSIZE, the value for USERECORDSIZE is used. Specify a value from 0 to 65400 inclusive.

0 - Disable record packing (send the record as is.)

Default: 65400.

USERECORDSIZE=

nnnn - The data blocking size. This is a memory and performance tool. Disk backups of files of sizes between 10,000 and 50,000 bytes are set to use record sizes of 8192. Specify a value up to the maximum of 32700.

For file transfers to z/OS, this is the largest record that can be transmitted and USERECORDSIZE+4 is the LRECL of the output z/OS data set.

Default: DASD backups - 27968 (optimized for half-track blocking)
TAPE backups - 32695

USERID=

cccccccccccccccccccccccccccccccc

Your security identifier, up to 32 characters. This may be required by some z/OS systems (see your system Administrator). There is a special format of this parameter (USERID &JOB) that requests that the security userid under which the USTBATCH job is executing (usually specified on the JOB statement) is to be used. This format can be specified only in USTBATCH input.

USRESTOREPACKRECSIZE=

nnnnn - The maximum number of bytes received from the z/OS Storage Server. Specify a value from 0 to 65400 (inclusive).

0 - Disable record packing (receive the record as is.)

Default: 65400

UTF8=

Y - UTF-8 unicode encoding.

N - UPSTREAM Unicode encoding.

Default: N.

VERSIONDATE=

nnnnnnnnnnnn - For a restore, if you specified LATESTVERSION=N, then you are required to specify a complete version date. This is usually used with an inquire versions command. The version date is exactly 12 numeric characters.

XFERRECORDSIZE=

nnnn - The record blocking size for file transfers. Users often use 80 for text files as well.

Default: 8192.

“Repeated” UPSTREAM Client Override Parameters

This section describes all “repeated” Client override parameters, which may be specified in groups to define the Client files to be processed.

Required Parameters

FILES=

filespec - The Client file specification to be processed by this request. This can include wild-cards, but note that UPSTREAM can only support Client filenames up to 255 characters in length.

For physical disk/backup restores, specify <\location\*.* where location is the internal UPSTREAM physical disk form.

For FDRSOS restores, specify />_FDRSOS_BACKUP if the source is a UNIX disk or >\*.* if the source is a PC disk.

SPECNUMBER=

nnnn - The header to this file set. Each file set begins with SPECNUMBER definition with an ascending number starting at 1.

Optional Parameters

ARCHIVEBIT=

Y - The archive bit is reset for all files successfully backed up.

N - The archive bit is not reset.

Default: Y.

DELETEPROMPTS=

0 - No prompts; delete the files without waiting (unattended).

1 - Prompt for each file before deleting.

2 - Prompt for the files in each directory before deleting.

Default: 0.

DESTINATION=

cc…cc - This parameter allows files to be restored to a different file or path name from which they were originally backed up. The wild-card specifications must match the wild-card specifications in the FILES parameter. You can specify up to 128 characters.

DIRDELETE=

Y - If automatically deleting files, remove directories from which all files have been deleted.

N - Leave the directories that were just emptied.

Default: Y.

DIRSONLY=

Specifies whether only directories and no files should be restored:

Y - Restore only directories (no files).

N - Restore files and directories.

Default: N.

DRIVEALIAS=

c - If specified, the drive letter transmitted to the z/OS Storage Server in lieu of the specified one. Allows you to move drive mappings without affecting merge backups. Specify a single letter (no trailing colon).

FILEDELETE=

Y - Delete the files that were successfully backed up.

N - Do not delete the files that were successfully backed up.

Default: N.

FILESOPENFORUPDAT=

Y - Win32 and OS/2 backups use the DENY_WRITE file open attribute. For AIX, files open for update are not included at all.

Default: N.

HARDLINKS=

Y - Enables hard link support for backups or restores.

N - Disables hard link support for backups or restores.

Default: Y (Unix), N (Win).

HIDDENFILES=

Specifies whether hidden files should be backed up or restored as well as normal files.

Y - Backup and restore hidden files.

N - Do not backup and restore hidden files.

Default: Y.

INCREMENTAL=

Y - Only those files with the archive bit set (files that have changed) are backed up.

N - All files specified will be backed up.

Default: N.

MIGRBITS=

Specifies how migrated files should be treated in a restore:

0 - Do not include migrate files in the restore.

1 - Include migrated files in the restore

2 - Include only migrated files (no regular files) in the restore.

Default: 0.

MOUNTPOINTS=

Y - Include a mount point and all of its files in a backup.

N - Exclude the mount point and all of its files in a backup.

Default: N.

NOVELLMIGRATE=

Y - Leave a Novell migration sub instead of deleting the file after the file has been successfully backed up.

N - Delete the file after it has been successfully backed up.

Default: N.

NOVELLMIGRATEADDEXT=

Y - With NOVELLMIGRATE=Y, this option adds the extension “.UPSTREAM_MIGRATED” to all migrated stub files to keep Windows Explorer from recalling files in directory listings.

N - Do not add the extension to migrated stub files.

Default: N.

NTFSADDPERMISSION=

Y - If an UPSTREAM directory or file access fails for security on an NTFS volume, the user that UPSTREAM is running as is added to the ACLS for that directory or file.

N - The user tis not added to the ACLS for that directory or file.

Default: Y.

PLUGIN=

filespec - Allows you to specify the name of a DLL or shared library, which can be used to extend UPSTREAM functionality. PLUGINs must be in the \plugin subdirectory, directly beneath the UPSTREAM directory.

PLUGINPARAMETERS=

Parameters specific to a plugin.

RESTOREMOUNTPOINT=

Whether or how Windows 2000 mount points are restored:

0 - Do not restore.

1 - Verify before restoring.

2 - Recreate if necessary.

3 - Restore without verification.

Default: 0.

ROOTENTRY=

Y - A dummy file: <Volume Information> is created for Windows NT and NLM backups containing non-file data for the volume itself.

N - This file is not created.

Default: Y.

SKIPOLD=

Y - Only those files that have a newer version on the backup than that contained on the Client are restored.

N - All files are restored.

Default: Y.

SOSDISK

The source for backups and the destination for physical disk/FDRSOS restores, using the internal UPSTREAM physical disk format.

SOSTIMESTAMP=

Y - Create an FDRSOS Timestamp file during the backup, which is used at restore time to determine if an FDRSOS restore has been done if the “Highlighted back to FDRSOS” restore option is selected.

N - Do not create an FDRSOS Timestamp file.

Default: N.

SOSTIMESTAMPPATH=

filespc - If SOSTIMESTAMP=Y, this is the path where the FDRSOS timestamp file is written (for backups) or read from (for restores). If not specified the file is written/read in the specified backup directory.

SPECTYPE=

0 - File specification is for files to be included in the backup or restore.

1 - File specification is for files to be excluded from the backup or restore.

2 - File specification is for files to be migrated during the backup.

Default: 0.

SUBDIRECTORIES

Y - All subdirectories under the current one are checked for files that match the file specification.

N - Only those files in the specified or default directory that match the file specification are transferred.

Default: Y.

USTBATCH Examples

This section provides several examples of USTBATCH jobs.

Example 1: “BATCHJCL”

The following example is found in the BATCHJCL member of the UPSTREAM Installation Control Library (ICL). It shows a fairly simple jobstream in which a Client-based operation is requested.

Initiate a backup against the target Client currently located at TCP/IP address 192.168.000.000. The backup is controlled entirely by the client-side parameters stored in the “BKUP.DAT” parameter file in “/opt/fdrupstream” on the Client.

In this example execution, no Client override parameters are being used.

• UPSTREAM 3.9.1 and later using USTBATCH to Started Task TCP/IP Parameters:
  

  //MAINT EXEC PGM=USTBATCH
  //STEPLIB DD DISP=SHR,DSN=your.upstream.loadlib
  //SYSUDUMP DD SYSOUT=*
  //USTLOG DD SYSOUT=*
  //USTPARM DD *
  *
  CONV=WAIT * WAIT for Backup to complete before ending
  *
  * THIS IS AN EXAMPLE OF USING USTBATCH TO INITIATE OPERATIONS
  * ON A FDR/UPSTREAM CLIENT USING A PARAMETER FILE ON THE
  * FDR/UPSTREAM CLIENT TO DEFINE THE OPERATION
  *
  HOSTDNS=YOUR.LPAR.DNS.NAME
  HOSTPORT=1972 *default
  MAXRETRY=1 RETRY COUNT
  *
  * INITIATE A BACKUP ON A TCP/IP FDR/UPSTREAM CLIENT
  *
  TCPTARG=192.168.000.000..1972,WSPARM=/opt/fdrupstream/bkup.dat
  /*

• UPSTREAM 3.9.0 and prior using USTBATCH to Started Task APPC Parameters:
  

  //RUNBAT   EXEC PGM=USTBATCH
  //STEPLIB  DD DISP=SHR,DSN=your.upstream.loadlib
  //SYSUDUMP DD SYSOUT=*
  //USTLOG   DD SYSOUT=*
  //USTPARM  DD *
  *
  * THIS IS AN EXAMPLE OF USING USTBATCH TO INITIATE OPERATIONS
  * ON A UPSTREAM CLIENT USING A PARAMETER FILE ON THE
  * UPSTREAM CLIENT TO DEFINE THE OPERATION
  *
  APPLPREF=UPSTRAPPL NAME PREFIX
  USAPPL=UPSTREAMONLINE UPSTREAM APPLID
  LOGMODE=USTMODEMODE NAME FOR SESSION
  MAXRETRY=1 RETRY COUNT
  QUEUE QUEUE REQUEST IF UPSTREAM CLIENT BUSY
  *
  * INITIATE A BACKUP ON A TCP/IP UPSTREAM CLIENT
  *
  TCPTARG=192.168.000.000..1972,WSPARM=/opt/fdrupstream/bkup.dat
  /*

Example 2: “BATPARM”#

The following example is found in the BATPARM member of the UPSTREAM Installation Control Library (ICL). It shows a more complex jobstream in which various Client-based operations are being requested.

• Task 1 is an incremental backup against the Client currently on TCP/IP address 192.168.000.000. The file spec used for the backup is being overridden by the USTBATCH job.
  
• Task 2 is the execution of an UPSTREAM process described entirely in the “DAILY.DAT” parameter file on the target Client currently registered to UPSTREAM as “MKTNG1”.
  

• Task 3 is a restore of some application files to the Client currently at TCP/IP address 192.168.000.000. The entire restore process is being controlled by Client override parameters in the USTBATCH job.
  

  //RUNBAT   EXEC PGM=USTBATCH
  //STEPLIB  DD DISP=SHR,DSN=your.upstream.loadlib
  //USTLOG   DD SYSOUT=*
  //USTPARM  DD *
  ***************************************************************
  * THIS IS AN EXAMPLE OF USTBATCH INPUT TO INITIATE OPERATIONS
  * AT 3 UPSTREAM CLIENTS
  ***************************************************************
  HOSTDNS=YOUR.LPAR.DNS.NAME
  HOSTPORT=1972    *default
  MAXRETRY=3 RETRY 3 TIMES (EVERY 10 MINUTES)
  CONV=WAIT WAIT FOR RESULTS FROM UPSTREAM CLIENT
  ***************************************************************
  * TASK 1. INITIATE AN INCREMENTAL BACKUP, USING THE
  *         MERGBKUP.DATA PARAMETER FILE AT THE UPSTREAM CLIENT,
  *         BUT OVERRIDING THE FILESPEC.
  ***************************************************************
  TCPTARG=192.168.000.000..1972,WSPARM=/opt/fdrupstream/mergbkup.dat
  ACTION 1 RUN A BACKUP
  STORAGETYPE 2TO SEQUENTIAL DISK
  MERGE 2 BACKUP IS AN INCREMENTAL MERGE
  SPECNUMBER 11st (and only) FILE SPEC
  FILES /usr/*BACKUP THE /usr DIRECTORY
  ***************************************************************
  * TASK 2. INITIATE AN OPERATION DEFINED ENTIRELY BY THE
  *         PARAMETER FILE AT THE UPSTREAM CLIENT
  ***************************************************************
  TARGNAME=MKTNG1,WSPARM=/opt/fdrupstream/daily.dat
  ***************************************************************
  * TASK 3. INITIATE A RESTORE OPERATION DEFINED ENTIRELY BY
  *         UPSTREAM CLIENT OVERRIDES
  ***************************************************************
  TCPTARG=192.168.000.000..1972
  ACTION 0 RUN A RESTORE
  USERID USER37MAINFRAME USERID
  PASSWORD MYPASSMAINFRAME PASSWORD
  BACKUPPROFILE SERVER2 UPSTREAM CLIENT PROFILE NAME
  LATESTVERSION YRESTORE LATEST VERSION OF ALL FILES
  SPECNUMBER 11st FILE SPEC -
  FILES /usr/*RESTORE ALL FILES FROM /usr/*
  SPECNUMBER 22nd FILE SPEC -
  FILES /opt/*RESTORE ALL FILES FROM /opt/*
  SUBDIRECTORIES NDO NOT RESTORE FILES IN SUBDIRECTORIES
  SKIPOLD N RESTORE EVEN IF RESTORED FILES ARE OLDER
  /*

  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.

Example 3: Running an UPSTREAM Client Process

This example demonstrates a multi-step USTBATCH job being used to run a Client process (Running an UPSTREAM Client User Process).

• Step 1 executes a script on the target Client to close and export databases.
  
• Step 2 performs a backup up of the databases.
  
• Step 3 then re-enables the databases for user access.
  

Example 4: E-mail Notification

Please refer to “Single Use” Input Parameters for further details.

The three PDS members below define the parameters and substitution variables used to enable e-mail notification for a given condition code. The members are optional and are located in the PDS referenced in the USTEMAIL DD statement in the USTBATCH JCL of the backup or utility job. The member names need not be as listed below and may be of your choosing.

• The MAILSERVER parameter may reference either the DNS name of the mail server (as in member EMAIL0), or the TCP address (as in members EMAIL4 and EMAIL8),
  
• The e-mail SUBJECT text may be up to 71 characters inclusive.
  
• The e-mail BODY text is defined on the line following the SUBJECT. The substitution variables listed in the SUBJECT and BODY are optional.
  

Sample JCL listing the USTEMAIL and SYSTCPD DD statements and the EMAILOK, EMAILWRN, and EMAILERR parameters are listed on the following page. These samples can also be found in the Installation Control Library (ICL) that was created as part of the installation of UPSTREAM.

• Member “EMAIL0” in data set “YOUR.EMAIL.PDS” contains:

  TCPNAME ENSRV001
  ** MAILSERVER YOUR.MAILSERVER.DNS *EITHER IP ADDR OR DNS ACCEPTED
  MAILSERVER 192.168.X.X
  FROM:<CPUA@YOURCOMPANY.COM>
  ***** MULTIPLE ADDRESSES ACCEPTED
  TO:<SUPPORT@YOURCOMPANY.COM>
  TO:<SYSPROG@YOURCOMPANY.COM>
  SUBJECT: UPSTREAM JOB &JOBNAME ZERO RETURN CODE
  JOB &JOBNAME STEP &STEPNAME ZERO RETURN CODE ON SYSTEM &SYSTEM

• Member “EMAIL4” in data set “YOUR.EMAIL.PDS” contains:

  TCPNAME ENSRV001
  MAILSERVER YOUR.MAILSERVER.DNS *EITHER IP ADDR OR DNS ACCEPTED
  FROM:<CPUA@YOURCOMPANY.COM>
  TO:<SUPPORT@YOURCOMPANY.COM>
  SUBJECT: UPSTREAM JOB &JOBNAME WARNING &EMAILDATE &EMAILTIME
  JOB &JOBNAME STEP &STEPNAME WARNING RETURN CODE ON SYSTEM &SYSTEM

• Member “EMAIL8” in data set “YOUR.EMAIL.PDS” contains:

  TCPNAME ENSRV001
  MAILSERVER 192.168.X.X
  FROM:<CPUA@YOURCOMPANY.COM>
  TO:<SUPPORT@YOURCOMPANY.COM>
  SUBJECT: UPSTREAM JOB &JOBNAME ERROR &EMAILDATE AT &EMAILTIME
  JOB &JOBNAME STEP &STEPNAME ERROR RETURN CODE

Sample USTBATCH JCL illustrating use of the USTEMAIL and SYSTCPD DD statements and the EMAILOK, EMAILWRN, and EMAILERR parameters.

• The USTEMAIL DD statement is required for e-mail notification, but is otherwise optional. It references a PDS that contains the members referenced in the EMAILOK, EMAILWRN, and EMAILERR parameters.
  

• The SYSTCPD DD statement may be used when a TCP/IP Domain Name Server (DNS) is not defined in the TCP/IP PROFILE data set. It is otherwise optional.
  

  //BACKUP   EXEC PGM=USTBATCH
  //STEPLIB  DD DISP=SHR,DSN=your.upstream.loadlib
  //USTEMAIL DD DISP=SHR,DSN=your.email.pds
  //*        USTEMAIL ONLY REQUIRED FOR E-MAIL NOTIFICATION
  //SYSTCPD  DD DISP=SHR,DSN=your.tcpdata.dataset
  //*        SYSTCPD NEEDED IF NO DNS IN TCP/IP PROF
  //SYSUDUMP DD SYSOUT=*
  //USTLOG   DD SYSOUT=*
  //SYSPRINT DD SYSOUT=*
  //*
  //USTPARM  DD *
  HOSTDNS=YOUR.LPAR.DNS.NAME
  HOSTPORT=1972 *default
  LOGMODE=#INTER
  CONV=WAIT
  MAXRETRY=0
  WTOCOMP
  EMAILOK=EMAIL0  *DEFINE FOR NOTIFICATION IF STEP CONDITION CODE=0
  EMAILWRN=EMAIL4 *DEFINE FOR NOTIFICATION IF STEP CONDITION CODE=4
  EMAILERR=EMAIL8 *DEFINE FOR NOTIFICATION IF STEP CONDITION CODE=8
  RESTART=3,5
  *
  TARGNAME=ZVMINST1
  ACTION 1        *1=BACKUP
  .
  .
  .
  (remainder of backup job follows)

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.

Controlling USTBATCH

If CONV=WAIT is specified within the USTBATCH input parameters, USTBATCH can accept z/OS console commands in order to monitor and modify its operation. In the examples shown below, “jobname” is the name of the USTBATCH job.

Status Display

This causes USTBATCH to display multiple UST749 messages, one for each Client request that is either pending or active. The messages contain the following information:

• An internal 4-digit task ID
  
• The target Client name or address
  
• The status of the request (see below)
  
• The time that the request was confirmed by the Client
  

The possible status values are:

WAIT

The request is still in the wait queue and has not yet been initiated.

CNFRM

The request has been sent to the UPSTREAM started task and USTBATCH is waiting for confirmation from the target Client that it has been accepted.

ACTIV

The request has been initiated and confirmed by the target Client and has been moved to the “active” queue awaiting completion notification.

FAILD

The request has failed. UPSTREAM will shortly issue a failure notification and remove the request from the queue.

Task Termination

This console command requests that USTBATCH terminate a request (identified by its ID number “nnnn”, as obtained from the status display). This has two possible effects, depending on the current status of the request.

• If the request is in WAIT status, it is deleted from the queue.
  
• If the request is in ACTIV or CNFRM status, it continues to be processed since it has already been sent to the UPSTREAM started task. However, USTBATCH removes it from its queues and no longer waits for completion of that request (essentially converting it to CONV=NONE processing). Depending on the status of other requests, this allows USTBATCH to terminate while the requested operations are still running.
  

Immediate Stop

This cause USTBATCH to clear all of its queues and terminate as soon as possible. Any requests that have not yet been initiated (i.e., they are in WAIT status) are discarded. All requests that have been initiated (i.e., in ACTIV or CNFRM status) continue to execute, but USTBATCH no longer waits for them.

Flush Log

This causes USTBATCH to close and reopen its log file (DD USTLOG). This allows the most recent USTBATCH messages to be available for viewing so that you can check on the status or results of requests while some requests are still executing.

USTBATCH Security

Please refer to USTBATCH Security Checking for the security implications of using USTBATCH.