Installation and Configuration

Overview

This section contains the instructions for installing the UPSTREAM z/OS product on your system.

The installation of UPSTREAM requires TSO with ISPF.

Installation Checklist

The installation of UPSTREAM z/OS involves several steps as outlined in the following table that you can use as a checklist as you work through the installation process.

• Install Type “ALL” must be done by all users (i.e., new and existing customers).
• Install Type “NEW” is ordinarily only done by new users.

Installation Checklist

Upgrading to a New Version

The following section describes configuring a test UPSTREAM to run in parallel with your production environment for testing, If you do not wish to configure a new test UPSTREAM and prefer to use an existing test UPSTREAM or your production UPSTREAM, please skip to Upgrading UPSTREAM to a Newer Versionbelow.

Testing and Implementing a New Production Version

A new production version of UPSTREAM can be tested while an existing version continues to be used for full production. To insure that the two instances of UPSTREAM do not interfere with each other:

• Load the new UPSTREAM libraries from the distribution media (APF Authorize the UPSTREAM Load Library and Installation ISPF Dialog) being sure to specify library names different from those used in production.
  
• Create a new configuration data set and repository data sets for testing:
  
  • Define the “CONFIG” Configuration File
  • Define the “CATALOG” Repository Data Set
  • Define the “FILEINFO” Repository Data Set
•  Define the VTAM application major node (Define Optional VTAM System Resources)
• Assign a TCP/IP port number different from the one used by production (Define an OMVS Segment for the UPSTREAM Started Task Userid).
• Copy the UPSTREAM startup PROC to your procedure library under a different name (e.g., USTTEST) updating it to point to the test data sets. Your existing startup options may be used (if any). If using the UPSTREAM Scheduler, change the reference from your production to your test UPSTREAM.
  
• Configure the MAIN options, ISPF panel 4, Configure the MAIN Optionsupdating the SUBSYS and TCPPORT parameters.
  
• While testing the new ISPF dialogs, the USTALLOC procedure shown at the beginning of (Start the UPSTREAM ISPF Interface) can be used to invoke them.
  
• Set the required parameters in the test configuration (see UPSTREAM-Profiles). The test backup profiles should have names different from those used for production and should create different backup data set names (DASDPREF= and TAPEPREF=).
  

Upgrading UPSTREAM to a Newer Version

After unloading the distribution libraries, creating the new UPSTREAM installation data sets and testing of a new version is complete, it can be easily placed into full production and set up to use the existing configuration and repository data sets:

1. If the Started Task PROC distributed with the new release is not changed from the old, make a new copy of your Started Task PROC and edit the STEPLIB reflecting the new UPSTREAM program library name/loadlib. You can, and should, use you existing control files. The old library (and PROC) should be saved for a quick and easy fall-back, if required.
   
2. Either take a current USTREORG of each of the control files and note the backup file created as part of the USTREORG, or take a DUMPX (the backup portion of the USTREORG), saving the backup files created.
   
3. Bring down the old UPSTREAM and using the new started task PROC created above, bring up UPSTREAM with the new loadlib.
   
4. Once UPSTREAM is started using the new loadlib, browse the started task logs (JESMSGLG and USTLOG DD statements) for any errors starting up. If you wish, performing a USTREORG or DUMPX for each of the control files verifies the integrity of the control files that have been migrated from the prior version. Performing a backup (writes to the control files and the backup data set), restore (reads from the control files and the backup data set) and any other UPSTREAM functions you use regularly will exercise the product.
   
5. Once you are satisfied that the new UPSTREAM is performing as expected, rename your production started task PROC to a save version and rename the PROC created in step 1 to your production name.
   
6. Change the STEPLIB in any USTBATCH job streams and other UPSTREAM batch jobs to refer to the new UPSTREAM program library.
   
7. The ISPF dialogs can be updated by renaming the new libraries to match the names of the existing production UPSTREAM ISPF libraries (saving the original libraries under another name for any potential fall-back). Alternatively, update your TSO logon procs to reflect the new ISPF panels, clist, messages, skeleton, and tables data sets.
   
8. Once the new version has been running successfully for a time, the libraries from the old version can be deleted.
   

3.4 APF Authorize the UPSTREAM Load Library

While not needed to receive and unload the UPSTREAM libraries, the UPSTREAM load library must be defined to z/OS as an APF authorized library before accessing the UPSTREAM ISPF panels used to customize and run the product. You specify the data set name in Screen1 of the ISPF installation dialog. See Electronic Installation - Data Set Name Selectionof this manual for further details. If the load library is not already defined as authorized, you (or your z/OS system programmer) must do so by one of the following methods:

• If your installation uses the PROGxx member in PARMLIB to define authorized libraries, you can update the PROGxx member and activate the updated list with the following z/OS console command:
  SET PROG=xx
• If your installation has specified that the authorized program list is in dynamic format, you can also temporarily authorize the UPSTREAM load library with the following z/OS console command:
  SETPROG APF,ADD,DSNAME=upstream.loadlib,VOL=volser

3.5 Authorize UPSTREAM ISPF Programs to TSO/E

Some of the functions available in the UPSTREAM ISPF dialog require that several program names be added to the TSO/E list of authorized programs (see Electronic Installation – IDP Product Install):

• USTATUS - for status displays (ISPF option 2 - required)
  
• USTBATCH - for ISPF panel generation of USTBATCH jobs
  
• USTCMD - for issuing commands to UPSTREAM (ISPF option 6)
  
• USTRPORT - for generating dynamic reports (ISPF option 7)
  
• USTMONA - for the UPSTREAM Debugging Facility
  

If you do not intend to give TSO users access to one or more of the preceding facilities, you can omit the associated program name from the TSO/E list of authorized programs. In TSO/E V2R4 and higher, you can authorize programs by modifying member IKJTSOxx in SYS1.PARMLIB. The program names must be added to both the AUTHPGM and AUTHTSF lists in that member. If you have the proper authority, you may issue the following TSO command to activate the updated IKJTSOxx member immediately, otherwise it is activated after the next IPL:

3.6 Electronic Installation

The UPSTREAM z/OS software is available via our Electronic Distribution service. Please login to the BMC Support Central to download the install package.

Order Acknowledgment E-mail

With the electronic installation, instructions are sent via e-mail for installing the libraries. The e-mail looks similar to:

Order Acknowledgment E-mail

Follow the instructions as directed in the INSJCL.TXT file included in the acknowledgment e-mail to retrieve the product package from the UPSTREAM FTP site.

Follow the “Remaining Product Installation Instructions” that is presented at the end of the file transfer.

Receiving Installation Files on z/OS

Expanding the product distribution file on your z/OS host is a two-step process. If you are using ISPF, issue the following TSO commands from ISPF Option 6 (TSO Commands). You can also exit ISPF and issue them from the TSO “READY” prompt. This TSO session must have access to an ISPF environment because the z/OS install process expects to employ ISPF panels to complete the installation. The steps described below assume TSO PROFILE NOPREFIX is NOT used.

1. Enter:
     RECEIVE INDATASET(UST.BIN)

   Where the INDATASET(…) value is the name that you created during the file transfer to z/OS.

   This creates a partitioned data set containing two load modules. After the RECEIVE is complete, the name of the PDS is ‘user id.IDPREC.LOAD’. If you want a different name, then at the prompt:

   Data set FDRSYS.IDPREC.LOAD from USTCFG on JESCPUA
   Enter restore parameters or 'DELETE' or 'END' +

   Enter:
     DSN(desired.name)

   Or take the default by pressing “ENTER.”
   A confirmation message is posted:

   Restore successful to dataset 'userid.IDPREC.LOAD'
   ***

   Important

   This library is only used to unload the distribution files. It is not the UPSTREAM program library that is unloaded as part of this installation.

2. Enter:
        CALL 'userid.IDPREC.LOAD(IDPREC)'

   or, if you gave the PDS a different name:

        CALL 'dsname(IDPREC)'

   A welcome message is displayed. Enter appropriate responses to name and SYSOUT class prompts.

   You are also prompted to enter the 16-digit IDPREC PASSWORD supplied in the Order Acknowledgment e-mail

   A sample dialogue follows:

   *--------*
   * Welcome to Innovation's - PRODUCTION install of the UPSTREAM PRODUCT
   * A default pds 'userid.UST.SHIPPDS' will be deleted, allocated and loaded
   * Enter a new name or press enter to use default
   
   * A default TSO receive sysout class of X will be used
   * Enter a new sysout class value or press enter to use default
   
   * After the transmission file is unpacked and the TSO receive is finished
   * an ISPF menu will be displayed with a menu titled:
   * IDP PRODUCT INSTALL (SCREEN1) - (This will take about a minute)
   
   * This dialog has Help containing additional information about the
   * install process
   *--------*
   Please enter IDPREC Password to load install file or QUIT to end

   Follow the instructions on the ISPF panel to complete the installation of the distribution files.

3.7 Installation ISPF Dialog

Electronic Installation - Data Set Name Selection

This screen allows you to specify the data set names that are used for the data sets you are unloading from the install package. These may be existing data sets to be updated, or they may be new data sets that are allocated and cataloged (new data sets are recommended).

Figure 3.2: IDP Product Install - Screen 1

The names shown above are the default names provided by the IDPREC Install program (your TSO userid is used for the HLQ). You may change these names in one of two ways:

1. To change the High or 2nd Level qualifiers for all data sets, change the values in the corresponding field for the Output DSN section.
   
2. To change an individual Low Level qualifier, change desired Low Level Qualifier for the data set(s) that you want to change.
   

The resulting data set names that are used are displayed at the bottom area of the panel.

You can also specify the SMS attributes (if they are to be SMS-managed) or VOLUME/UNIT information on this panel to allocate these data sets when creating them as NEW.

The “USS File System Directory Name” prompt allows specification of the location to unload the UPSTREAM client installation files for z/OS UNIX Systems Services (USS). These are used to backup USS file systems. This is an optional selection and would be used if you are licensed for z/OS UNIX Systems Services (USS). If you are not licensed for USS, please ignore the prompt. By default, the installation does not unload the USS installation files. If you wish to unload and then receive the files, remove the ******** at the “Do file system load by clearing” prompt. The name shown above is the default name provided by the IDPREC install program and may be changed as appropriate. Verify the installation path name entered at the “USS File System Directory Name” prompt. This specification may be for an existing HFS or z/FS subdirectory. The path name will be listed as the HFSDIR at the bottom of the screen.

The TSO id of the user performing the installation must have write privileges to the directory specified. For further information, please see the UPSTREAM z/OS UNIX Systems Services manual. Once you are satisfied with the selections, press ENTER and then END (PF3.)

Electronic Installation – IDP Product Install#

This screen documents the process that is used to create the product libraries. When you press “ENTER” to continue, it shows you the status of each of the data sets being created.

IDP Product Install - Screen 2

Figure 3.4: Completion Message

Electronic Installation - Data Sets Have Been Received

• 
  
  • ===

This screen documents that all the product libraries have been created and received and goes to the Primary Options Menu to continue the installation process and customize the product. You can exit the menu at this time as all the necessary libraries have been loaded.

IDP Product Install - Screen 3

Start the UPSTREAM ISPF Interface

With the UPSTREAM libraries loaded from the prior step, the UPSTREAM load library APF authorized (Section3.4 “APF Authorize the UPSTREAM Load Library”) and the UPSTREAM program names added to the TSO/E list of authorized programs, you can now invoke the USTALLOC dialog to continue the installation process. From ISPF Option 6 (TSO COMMANDS), issue the following command to display the UPSTREAM Main Menu:

EXEC 'upstream.clist.library(USTALLOC)'This panel is displayed:

UPSTREAM - Main ISPF Panel

If you are not performing a full z/OS installation as described in Electronic Installation and only wish to install the UPSTREAM USS client, the client can also be downloaded via FTP. Instructions for downloading the client and extracting the client files are provided in a distribution email containing a link to download a tar file.

For your reference, the instructions are listed below.

1. Copy the link supplied in the distribution email and paste into your browser to download the file to your PC. (If using Firefox, double clicking on the file may not work.)
   
2. Open a DOS window/command prompt and navigate to the directory where you downloaded the file.
   
3. Using the Windows FTP client (in DOS) FTP, in Binary, the file to your z/OS lpar where the USS client will run.
   
4. Under OMVS, navigate to your USS installation dir.
   
5. Extract the client files from the tar archive. You may need to “su” to reset your UID to 0 (super user.)
     tar -xvfp /<USS_directory_containing_the_FTP_file>/client-4.0.00-uss.tar.tz
6. Update (if necessary) the upstream.cfg file and if you are using one, the script file that will be used to start the USS Process.
   

3.10 Define the UPSTREAM System Data Sets

If you are upgrading from an earlier version of UPSTREAM and plan to use the existing system data sets, you can skip the UPSTREAM DEFINE steps. If you want to re-size any of those data sets, specify the filename of the existing data set at the bottom of the DEFINE screen, and a REPRO step is generated to copy the existing data.

Option 3 (“DEFINE”) from the UPSTREAM Main Menu takes you to a sub-menu (below) where you can define the data sets used by the UPSTREAM system. These data sets include the main configuration data set and the three repository data sets (The UPSTREAM Repository).

Figure 3.7: UPSTREAM - Define Panel

Once you have selected all the desired data sets, UPSTREAM - Generate the JCLshows you how to generate (and optionally modify) the JCL required to create those data sets.

Define the “CONFIG” Configuration File#

The UPSTREAM configuration data set contains options describing and controlling the various processes that can run with UPSTREAM (backups, restores, utility functions, etc) as well as options controlling the behavior of the UPSTREAM system itself. See UPSTREAM Configurator for a full description of the UPSTREAM Configuration File.

The configuration data set is a sequential or partitioned data set (PDS is recommended) and it must have the following DCB characteristics: RECFM=FB, LRECL=120, and a blocksize that is a multiple of 120.

Selecting option 1 (“CONFIG”) from the define menu takes you to the panel shown below, where you define the parameters for the allocation of the configuration data set.

UPSTREAM - Define the Configuration File

When you are satisfied with the values displayed, press PF3/END to return to the main DEFINE menu.

Define the “CATALOG” Repository Data Set#

The CATALOG repository data set contains information about all the backups currently recorded by UPSTREAM and (optionally) history records detailing recent operations.

Selecting option 2 (“CATALOG”) from the define menu displays the panel shown below, where the parameters for the allocation of the CATALOG repository data set are defined.

UPSTREAM - Define the Catalog Cluster

UPSTREAM can estimate the required size of the CATALOG data set by entering an estimate of the number of backups for all Clients that are recorded by UPSTREAM at any one time. Alternatively, specify a data set size in cylinders. Filling in either value and pressing ENTER causes UPSTREAM to display a calculated value for the other value.

For example, to backup 10 Clients and each Client retains (on average) 10 weekly full merge backups and 5 incremental merge backups between each full, (a total of 6 backups each week), then:

• backups/client = (6 backups/week) * (10 weeks) = 60
  
• total backups = 60 backups/client * 10 clients = 600
  

The resultant space calculation includes a generous factor for expansion and for history records, but since the CATALOG file is fairly small, we suggest you add your own factor to ensure sufficient space (e.g., 2000 instead of 600 in the example). See The CATALOG (USTCATLG) File for more detailed information on the contents of the CATALOG file and estimating space requirements.

See Choosing the Repository File Format for help in deciding whether to use IAM or VSAM for the repository file format.

When satisfied with the values, press PF3/END to return to the main DEFINE menu.

Define the “FILEINFO” Repository Data Set#

The FILEINFO repository data set contains one record for every UPSTREAM Client file backed up by UPSTREAM. This includes information such as the Client file/path name, file/path attributes, and the physical location of the actual backup.

Selecting option 3 (“FILEINFO”) from the define menu takes you to the panel shown below, where you define the parameters for the allocation of the FILEINFO repository data set.

Figure 3.10: UPSTREAM - Define the File-Information Cluster

You can ask UPSTREAM to estimate the required size of the FILEINFO data set by entering the number of different Clients for which backups are taken, the average number of files on each Client and the number of incremental backups and full backups per Client. Alternatively, you may specify a data set size in cylinders. If you change one or more of the first four values, UPSTREAM displays its calculated value for the size in cylinders. See Section 6.4 “The FILEINFO (USTFILEI) File” for more detailed information on the contents of the FILEINFO file and estimating space requirements.

When satisfied with the values, press PF3/END to return to the main DEFINE menu.

3.14 UPSTREAM - Generate the JCL

If you opt to define one or more of the UPSTREAM system data sets, the define menu displays the text “* JCL GENERATED” next to each data set to be defined. From that define menu, press PF3/END to display the following menu:

Figure 3.11: Define System Data Sets

USTCAMS

PGM=USTCAMS is used for the definition of the two repository data sets.

USTCAMS is an UPSTREAM front-end to the IBM IDCAMS utility and accepts all of the control statements of IDCAMS. However, USTCAMS allows the UPSTREAM repository data sets to be defined as either VSAM KSDS clusters or as IAM (Innovation Access Method) files.

If any of the cluster names in the two DEFINE statements have an index level of “$UST” (for example, UPSTREAM.CATALOG.$UST.CLUSTER) it is defined in IAM format, otherwise it is defined as a VSAM KSDS.

For optimum performance, we recommend that the CATALOG and FILEINFO data sets be defined as IAM files (i.e., with “$UST” in the cluster name). These are the defaults, as presented by the above panel.

If you have defined any of the repository data sets as IAM, you must use USTCAMS instead of IDCAMS for all operations on those data sets, including REPRO and LISTCAT operations. See The UPSTREAM Repository for more information on the repository data sets, including details of IAM and the USTCAMS program.

If you receive an informational message “IDC2908I FILEINFO NOT FOUND IN SYSTEM” for the CATALOG file, the message can be safely ignored.

Define Optional VTAM System Resources

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

To define to VTAM the application IDs that are used by UPSTREAM, tailor the “USTAPPL” member from the Installation Control Library (ICL) and copy it into your SYS1.VTAMLST data set.

The member name in VTAMLST may be USTAPPL or any name of your choice. You can activate it with the console command “V NET,ACT,ID=membername”. You probably want to add the member name to the “ATCCONxx” member of VTAMLST in order that the UPSTREAM application names are automatically activated when VTAM is started.

• The first application, UPSTREAM, is used by the UPSTREAM started task. If you change the application name, you must also change the name on the APPLID parameter in your UPSTREAM configuration (see APPLID).
  
• The other applications, UPSTR*, are used by USTBATCH (See Chapter 17 “z/OS Initiation with USTBATCH”). If you change the prefix, you also need to specify that prefix on the APPLPREF= statement input to USTBATCH.
  

On the APPL statements, DLOGMOD= defines the default log mode table entry name that is used when UPSTREAM establishes a session to a Client, or when USTBATCH establishes a session to UPSTREAM. #INTER is a mode table entry provided by IBM (in ACF/VTAM V3.4 and above, in the default mode table ISTINCLM) and can be used with UPSTREAM that overrides the parameters in #INTER to allow 4K RU sizes and pacing values of 24.

Sample VTAM Definition

Define an OMVS Segment for the UPSTREAM Started Task Userid

The “z/OS eNetwork Communications Server” (the IBM TCP/IP component) uses z/OS UNIX Systems Services (USS) for the TCP/IP API interface. This requires that the security userid associated with the UPSTREAM started task (UPSTREAM PROC) have an OE OMVS segment defined to your security system before you can start the UPSTREAM started task. See the IBM eNetwork documentation for details.

You may need the assistance of your security personnel to create the OMVS Segment for the UPSTREAM userid.

If this OE OMVS security segment is not defined, starting the UPSTREAM started task results in error messages:

In order for the UPSTREAM Client to communicate with UPSTREAM z/OS Storage Server, two pieces of information are required:

• The network address of the z/OS Storage Server, usually expressed as 4 decimal numbers separated by periods (e.g., 152.12.93.1). During UPSTREAM startup. the default TCP/IP UPSTREAM z/OS Storage Server address is displayed, but this address may not be correct for every Client if you have multiple TCP/IP interfaces to the mainframe. When configuring UPSTREAM for TCP/IP on an Client, verify this address with the system programmer or network administrator responsible for TCP/IP on your system.
  
• A “well-known port” number, within your TCP/IP z/OS Storage Server system, on which UPSTREAM listens for requests from the Client. By default, UPSTREAM uses port 1972, but this can be changed in the UPSTREAM configuration (UPSTREAM ISPF option 4).
  

The address and port number need to be supplied when the Client software is configured using TCP/IP (but the port number there also defaults to 1972).

UPSTREAM uses the well-known port number you assign (or the default of 1972) as long as that port is not already in use by some other application. During UPSTREAM testing, that port will probably be available, so no TCP/IP changes are required, but when UPSTREAM is in production, you probably want to reserve that port number to ensure it is always available when UPSTREAM is started.

For IBM's TCP/IP, you need to edit the TCP/IP profile data set. Check with your TCP/IP systems programmer for the name of this data set (probably “TCPIP.PROFILE.TCPIP”). Find the PORT statement in that profile, and add a line as shown below, where 1972 is the port number, TCP is the protocol, and “UPSTREAM” is the name of the UPSTREAM started task (usually the name of the cataloged procedure used to start UPSTREAM). The text after the # is comments:

   1972 TCP UPSTREAM    * well-known port for UPSTREAMIf the port number is in use by another task when z/OS Storage Server is started, or (for IBM TCP/IP) if the task name in the reserved port list does not match the actual UPSTREAM task name, you will receive a message (from UPSTREAM) indicating that the port is in use. In that case, TCP/IP access is not available until the situation is corrected and UPSTREAM z/OS Storage Server is restarted.

Configure the MAIN Options

You now need to configure the MAIN options used by UPSTREAM z/OS. These options define system-wide processing used by UPSTREAM. From the UPSTREAM main menu below, which we first saw in Start the UPSTREAM ISPF Interface, select option 4 (“Configure”):

UPSTREAM - Main ISPF Panel

UPSTREAM - Configure Main Options - Configuration Data Set

The subsequent screen displays all of the UPSTREAM MAIN configuration options. The configuration can be saved by entering SAVE on the top line and pressing ENTER. Each option is described below. See Chapter 20 “UPSTREAM Configurator” for more detailed information on UPSTREAM configuration.

UPSTREAM - Configure Main Options

UPSTREAM MAIN Configuration Options

The following describes each parameter and its possible values.

APPLID¹

cccccccc / NONE

Beginning with UPSTREAM z/OS 3.9.1, the UPSTREAM started task and USTBATCH may now use TCP/IP to initiate requests. If using TCP/IP, specify NONE.

Alternatively, if using APPC for USTBATCH to started task communications, this specifies the name of the VTAM application ID used by z/OS Storage Server, usually “UPSTREAM”. This is the name on the first APPL statement in the USTAPPL member of VTAMLST (see Define Optional VTAM System Resources), or, if specified, the ACBNAME= value on that APPL statement. This operand is required.

Default: NONE.

DASDBLK

nnnnn

Specifies the default blocksize (1024 to 32760) that UPSTREAM uses when allocating a sequential disk backup. This value can be overridden on any or all individual backup profiles.

Default: 27998.

MAXHIST

nnnnn

Specifies the number of days (0 to 32760) that UPSTREAM retains history records in the CATALOG repository. Records older than the number of days specified are purged when USTMAINT (see Section 16.10 “UPSTREAM Configuration Maintenance”) is run. If MAXHIST=0 is specified, no history records are created.

Default: 365.

MAXTAPEB

nnn

Specifies the maximum number of tape drives (0 to 255) that UPSTREAM uses for backups at any one time. This includes the output tapes required for the online utilities such as USTMIGRT, USTMERGE, and USTVAULT. If the limit is exceeded, any new tasks requiring tape drives wait until the number of backup tapes in use declines. If MAXTAPEBACKUP=0 is specified, no tape limit is enforced.

Default: 0.

MAXTAPER

nnn

Specifies the maximum number of tape drives (0 to 255) that UPSTREAM uses for restores at any one time. If this limit is exceeded, any new restore tasks requiring tape drives waits until the number tape drives in use drops below MAXTAPERESTORE. If MAXTAPERESTORE=0 is specified, no tape limit is enforced.

Default: 0.

MAXTASS

nnn

Specifies the maximum number of sub-tasks (1 to 255) that UPSTREAM can have active at any one time. This includes all backups, restores, inquiries, and utility functions. If this limit is exceeded, UPSTREAM rejects the initiation of any new tasks until the number of active tasks drops below MAXTASKS.

Default: 100.

RACFUPD²

Valid only if SECLVL=2 or 3 has been specified and if a userid has been granted UPDATE or READ access to a Client profile name. RACFUPD then specifies what operation the user is authorized to perform:

BACKUP

Allows users with UPDATE authority to do backups or restores, while users with only READ access can do only restores.

RESTORE

Allows users with UPDATE authority to do backups or restores, while users with only READ access can do only backups.

Default: RESTORE.

SECLVL³

Controls UPSTREAM security (see The SECLVL Parameter).

0

(the default) specifies that UPSTREAM is to do no security checking on the userid and password entered by the end user at the Client. Specify this if you have no security system or prefer not to enforce userid security.

1

specifies that UPSTREAM is to issue a security call to verify the userid and password entered by the end user at the Client. No further security checking is done.

2

specifies that, in addition to verifying the userid and password (SECLVL=1), UPSTREAM issues additional security calls to verify that the userid is permitted to access the Client profile name entered by the end user. It also verifies that the userid is permitted to request restores from tape.

3

same as SECLVL=2, except that if the profile name and userid specified at the Client are the same, the user is automatically considered to be authorized to that profile name.

SUBSYS

cccccccc

Specifies the subsystem and control point name (default “UPSTREAM”) that will be used on security system calls if SECLVL=1, 2, or 3 is specified. Contact BMC Support if you need assistance in altering this value.

TAPEBLK

ccc

Specifies the maximum tape DCB BLKSIZE parameter that will be used when allocating a new tape data set; the default is “MAX”.

UPSTREAM backups can utilize up to a maximum 256KB DCB BLKSIZE, or the optimum that the target tape device manufacturer will allow.

TCPNAME⁴

cccccccc

Identifies the z/OS TCP/IP started task instance name with which the UPSTREAM started task will communicate.

This is generally the name of your TCP/IP started task on your z/OS system. However, if you started the TCP/IP started task with the command similar to the following, the proper value for this parameter would be “SYS2”

S TCPIP.SYS2

If the specified TCP/IP system is not active when z/OS Storage Server is started, a warning message is issued and TCP/IP access is disabled. You must restart the z/OS Storage Server started task to re-establish TCP/IP communications.

TCPPORT

nnnn

Specifies the TCP/IP port number that z/OS Storage Server uses as a “well-known” port number to listen for Client connections.

Default: 1972, which is generally fine.

WTOCOMP

Specifies whether UPSTREAM should issue WTOs to the z/OS system console for all messages relating to backups starting and completing, in addition to writing them to the UPSTREAM log (USTLOG).

YES

UPSTREAM issues WTOs to the z/OS system console for all messages relating to backups starting and completing, in addition to writing them to the UPSTREAM log.

NO

UPSTREAM only writes the messages to the UPSTREAM log.

This operand is optional. If omitted, these messages are written only to USTLOG. This feature may be useful for installations with mainframe automation and tracking facilities that monitor console messages.

Default: NO.

ATBCOUNT

nnnn

This parameter is for internal use only and should only be changed if requested by BMC Support.

Default: 10.

3.19 Make the UPSTREAM ISPF Dialogs Easily Available

The UPSTREAM TSO/ISPF dialog can be invoked at any time, from any TSO userid that is authorized to read the UPSTREAM dialog libraries. This can be done by going to ISPF option 6 (TSO COMMAND) and entering the following command, as previously shown in “Start the UPSTREAM ISPF Interface” in Section3.8:

EXEC 'upstream.clist.library(USTALLOC)'Two shortcuts to this process are also available:

Shortcut 1: Adding an “UPSTREAM” Option to Your Main Menu

You may add “UPSTREAM” as an option on your ISPF main menu (ISR@PRIM), or any other ISPF menu of your choice. In the UPSTREAM ISPF panel data set there are two example panels showing how to add an option for UPSTREAM to the ISPF main menu:

• ISR@V3X - for ISPF V3.x
• ISR@V4X - for ISPF V4.x

Shortcut 2: Adding UPSTREAM as an ISPF Command

You can add the UPSTREAM command to an ISPF command table so that the UPSTREAM dialog can be entered from almost any ISPF panel by entering “UPSTREAM” or just “UPS” on the command line.

This is achieved by entering the command “USTCMDS” on the UPSTREAM main menu.

The modified command table is stored in the first library in the ISPTLIB concatenation for this TSO userid. If the user has a private table library, it normally is the first one in that concatenation, so the updated command table is available only to this user.

If the user does not have a private library, but has update authority to the first public library in ISPTLIB, that library will be updated, and it is available to any userid using it.

However, you are given an option to specify a different table library before it is actually stored. If you choose a different table library, that library will have to be in the ISPTLIB concatenation in front of any other library containing a table by the same name.

The ISPF command table name consists of a prefix followed by the constant CMDS (default ISPCMDS).

For ISPF version 4.2 or higher, we recommend that you update the public command table.

3.20 Define the UPSTREAM Started Task PROC

The ICL member “USTPROC” is a sample PROC to start the UPSTREAM started task. It will need to be tailored to meet your installation specifications and copied into an appropriate system PROCLIB as member “UPSTREAM” (or another name of your choice).

The JCL parameters included in this PROC are described below.

EXEC Statement

Specifies the UPSTREAM started task program USTMAIN. REGION=0M is recommended to allow UPSTREAM to acquire whatever virtual storage is required to perform the requested operations. Certain startup parameters can be specified via the PARM= operand on the EXEC statement, or via a PARM= override on the console START command used to start UPSTREAM. If multiple values need to be specified, separate them by commas. Some supported values on the PARM= operand are shown below. See Startup Options for a full list:

SCHEDULE

This automatically starts USTSCHED, the UPSTREAM scheduler (see UPSTREAM Scheduler). If specified, the USTSCHED DD statement must be included.

NOMAINT

This bypasses the automatic execution of the USTMAINT utility (see UPSTREAM Configuration Maintenance). However, since USTMAINT should be run periodically in order to cleanup any obsolete entries in the UPSTREAM repository, we do not recommend that you run this way normally.

RBSZ=

Overrides the default setting of the TCP/IP receive buffer size (TCPRCVBUFRSIZE) that controls the number of bytes received by the z/OS TCP/IP stack before acknowledging this to the remote system.

Default: 131,072 (effective for most shops.)

SBSZ=

Overrides of the TCP/IP default settings of the TCP/IP send buffer size (TCPSENDBUFSIZE.)

Default: 65,535 (effective for most shops.)

URBSZ=

Overrides the default setting of the TCP/IP receive buffer size (TCPRCVBUFRSIZE) for z/OS UNIX Systems Services based Client communication. This controls the number of bytes received by the z/OS TCP/IP stack before acknowledging this to the remote USS system.

Default: 32,768.

USBSZ=

Overrides the TCP/IP default setting of the TCP/IP send buffer size (TCPSENDBUFSIZE) for z/OS UNIX Systems Services based Client communication.

Default: 131,072.

TIMEOUT=#

nnn

This specifies the maximum number of minutes that UPSTREAM waits for most communication requests to complete. The value can be specified from 1 to 8191 minutes.

Default: 10.

STEPLIB DD Statement

This is the UPSTREAM z/OS Storage Server load library that was APF Authorized earlier in APF Authorize the UPSTREAM Load Libraryand unloaded in Installation ISPF Dialog. As noted, it must be an APF-authorized library.

USTLOG and USTLOG2 DD Statements

These data sets contain all the messages from UPSTREAM z/OS Storage Server. USTLOG is the primary log and USTLOG2 is the (optional) alternate log. Their format is DSORG=PS, RECFM=VB, LRECL=134. The blocksize defaults to 6233 if the data sets are on disk, but you can specify a larger value (smaller values are ignored). BLKSIZE=138 is forced if they are going to SYSOUT. You can switch between USTLOG and USTLOG2 as the active log data set with the following console command:

F UPSTREAM,SWITCHLOGLog Handling for full details on flushing and switching UPSTREAM logs.

USTSUMM and USTSUMM2 DD Statements

These optional data sets contain a one-line summary of each operation performed by UPSTREAM. USTSUMM is the primary log and USTSUMM2 is the (optional) alternate log. Their format is DSORG=PS, RECFM=FB, LRECL=133. The blocksize defaults to 1330 if the data sets are on disk, but you can specify any value that is a multiple of 133. BLKSIZE=133 is forced if they are going to SYSOUT data set. You can switch between USTSUMM and USTSUMM2 (requires the presence of USTLOG2) with the following console command:

USTINFO DD Statement

If one or more of the UPSTREAM repository data sets have been defined as IAM (i.e., they have “$UST” as an index level in the name), this file contains messages about their usage.

USTSNAP DD Statement

Under certain error circumstances, UPSTREAM takes a z/OS “SNAP” dump for problem diagnosis. This data set contains the “SNAP” dump if one is taken. The format of the USTSNAP data set should be: DSORG=PS, LRECL=125, BLKSIZE=1632, RECFM=VBA.

SYSUDUMP DD Statement

In the event of a catastrophic error, this data set contains a system dump taken by z/OS. This dump may prove invaluable in resolving the problem.

INTRDR DD Statement

Used for submission of jobs by the UPSTREAM scheduler USTSCHED (see UPSTREAM Scheduler). It should point to a JES internal reader. If omitted, USTSCHED will dynamically allocate an internal reader, so it can safely be omitted.

USTCONFG DD Statement

This is the UPSTREAM configuration data set that you created in Define the “CONFIG” Configuration Fileand then configured with initial settings. If the configuration data set is a PDS, the member name of the current configuration must be specified. This configuration is used during the startup of UPSTREAM, but the configuration can be changed while UPSTREAM is running, (See Adjusting UPSTREAM Main Configuration Options). The characteristics of this data set must be RECFM=FB and LRECL=120 (any blocksize that is a multiple of 120 is acceptable).

USTSCHED DD Statement

This optional DD statement must be included if you are using the UPSTREAM scheduler USTSCHED (see UPSTREAM Scheduler). It points to the data set where the schedule definitions are stored. This is usually the same configuration data set pointed to by USTCONFG, but it can be a separate data set if it has the proper DCB characteristics of RECFM=FB and LRECL=120 (any blocksize that is a multiple of 120 is acceptable). The member name specified contains the schedule definition that will be used by default, but the member name can be overridden when USTSCHED is started.

USTCATLG DD Statement

This data set is the UPSTREAM repository CATALOG data set (see Define the “CATALOG” Repository Data Set).

USTFILEI DD Statement

This data set is the UPSTREAM repository FILEINFO data set (see Define the “FILEINFO” Repository Data Set).

USTTAPEM DD Statement

This optional DD statement invokes the USTTAPEM facility. USTTAPEM performs tape allocations in a separate, z/OS address space. See Define the USTTAPEM Started Task Proc (Optional).

USTCRYPT DD Statement

This optional DD statement must be included if you are using the UPSTREAM encryption feature (UPSTREAM Data Encryption). This data set contains the USTCRYPT control statements and must be allocated as RECFM=FB, LRECL=80, and a BLKSIZE as a multiple of LRECL.

3.21 Define the USTTAPEM Started Task Proc (Optional)#

Device allocation in z/OS continues to be single-threaded using an exclusive enqueue on the SYSZTIOT resource. To lessen the possibility of a deadlock in allocation and/or deallocation, specific mount requests (non-scratch/private requests) can now be processed by an optional external address space, USTTAPEM. To process a mount request, the UPSTREAM address space will pass the mount request to the USTTAPEM address space to process the request and pass the ready device back to the Upstream address space.

Each specific mount request starts a new USTTAPEM started task. This started task processes the request and ends. This process repeats for each specific mount request. An active system processing hundreds of tape mounts will have started task output for each one. Care should be taken to avoid exceeding the maximum number of jobs allowed in your JES system. We suggest the USTTAPEM started task proc be defined in the Master JCL library and specify a SYSOUT class on the Job card that does not retain job or started task output. See the sample procedure further below and also in the installation ICL library in member USTTAPEM.

Tape mounts will be handled in an external address space, consequently, tape mount activity will no longer be posted in the JESMSGLG DD of the UPSTREAM started task. Instead, that log activity can be found in the individual USTTAPEM started task output. Or if, as suggested, the USTTAPEM output is not retained, see the JES SYSLOG for mount activity.

There are two steps required to enable tape mounts via USTTAPEM.

1. Add the USTTAPEM DD card to the UPSTREAM started task JCL (please refer to Define the UPSTREAM Started Task PROCand the installation ICL library, member USTPROC):
   //USTTAPEM DD DUMMY
   You may override the name of the USTTAPEM procedure in the Upstream started task JCL by specifying the DATACLAS parameter as follows:
   //USTTAPEM DD DUMMY,DATACLAS=<new-proc-name>

2. Create the USTTAPEM started task (please refer to the installation ICL library, member USTTAPEM):
   

   //USTTAPEM JOB MSGCLASS=Z
   //USTTAPEM PROC OUT=X
   //*
   //* MOUNT TAPE FOR UPSTREAM IN AN EXTERNAL ADDRESS SPACE
   //*
   //* THE USTTAPEM PROCEDURE IS INVOKED FOR SELECTED TAPE
   //* MOUNTS ON BEHALF OF THE UPSTREAM ADDRESS SPACE. IT
   //* SHOULD BE ASSIGNED TO A JES MESSAGE CLASS THAT IS
   //* AUTOMATICALLY PURGED, AS NOT TO FILL UP THE JES SPOOL.
   //* *CHANGE* MSGCLASS=Z IN THE JOB STATEMENT TO A MSGCLASS=
   //* THAT WILL AUTOMATICALLY PURGE THE JOB FROM JES SPOOL.
   //*
   //* THE USTTAPEM PROCEDURE CONTAINS A JOB CARD, SO IT
   //* *MUST* BE PLACED IN A LIBRARY POINTED BY EITHER THE
   //* IEFJOBS DD OR THE IEFPDSI DD IN THE MSTJCLXX MEMBER
   //* IN SYS1.PARMLIB.
   //*
   //* *CHANGE* OUT=X TO A SYSOUT HELD CLASS SO ANY ABENDS
   //* WRITTEN TO THE SYSUDUMP DD WILL BE HELD IN SPOOL.
   //*
   //USTTAPEM EXEC PGM=USTTAPEM
   //STEPLIB  DD DISP=SHR,DSN=your.upstream.loadlib
   //SYSUDUMP DD SYSOUT=&OUT
   //*USTTAPEM DD DUMMY         *** FOR WTO MESSAGE ***
   //         PEND
   //         EXEC USTTAPEM

EXEC STATEMENT

Specifies the UPSTREAM started task program USTTAPEM

STEPLIB DD STATEMENT

This is the UPSTREAM z/OS Storage Server load library created earlier in APF Authorize the UPSTREAM Load LibraryIt must be an APF-authorized library, as described inAPF Authorize the UPSTREAM Load Library

SYSUDUMP DD STATEMENT

In the event of a catastrophic error, this data set contains a system dump taken by z/OS. This dump may prove invaluable in resolving the problem.

USTTAPEM DD STATEMENT

Optional. Issues a UST990 WTO to the SYSLOG as follows:

Before you can start to run backups and restores with UPSTREAM, you will need to do the following:

• Install and configure the UPSTREAM Client software.
  See the UPSTREAM Client Guide for full details.
• Review UPSTREAM Security Options.
  Review Security, which describes the SECLVL main configuration parameter. Make sure that you understand the implications of the value you have set for SECLVL (see The SECLVL Parameter).
• Construct a Backup Profile.
  Review UPSTREAM Profiles for a full description of UPSTREAM backup profiles.

• Run your first backup and restore.

  Having created a backup profile, you can then run your first backup and restore. This can be done either from the UPSTREAM z/OS Storage Server (see Performing a Backup and Performing a Restore), or through the UPSTREAM Director or GUI interfaces (please see the UPSTREAM Client Guide).