UPSTREAM Configurator

USTCONFG Introduction

UPSTREAM is configured through options set in a control file known as the “Configuration File” (see Define the “CONFIG” Configuration File“). This file is first created during the installation process and is subsequently read by the UPSTREAM started task during initialization. It is named on the USTCONFG DD statement in the UPSTREAM startup PROC (see Define the UPSTREAM Started Task PROC).

Configuration File Contents

The configuration file contains numerous options, which can be divided into two distinct categories:

• Main Options - These control the behavior of UPSTREAM itself, such as security settings and the retention of history records. Initial values for these general options are set during the installation of UPSTREAM, as described in UPSTREAM MAIN Configuration Options (see Define the UPSTREAM Started Task PROC).
  
• Profile Options - These options control the behavior of most UPSTREAM functions, grouped into individual “profiles”. This includes the primary functions of backup and restore, as well as ancillary functions like file transfer. Profiles in the configuration are also used to control utility operations like USTVAULT, USTMERGE, and USTMIGRT. UPSTREAM Profiles provides a full description of all UPSTREAM profiles.
  

Although the main options are likely to remain fairly static after the initial installation and configuration of UPSTREAM, the profile options continue to be added to and modified as the use of UPSTREAM increases.

Maintaining the Configuration File

The primary tools that can be used to maintain the UPSTREAM configuration file are:

• The UPSTREAM TSO/ISPF dialog.
  
• The UPSTREAM Profile options (not Main options) can be viewed, modified, added, or deleted by using the Director. UPSTREAM security parameters (Security) may be used to control which Client users can modify which profiles. See the UPSTREAM Client guide for full details.
  

The remainder of this chapter describes the USTCONFG program. It also lists, in tabular form, all of the operands that can be used by USTCONFG, which can be set via the TSO/ISPF dialog and Client panels.

The USTCONFG Program

The UPSTREAM configuration file can be created and/or updated using the configuration utility program USTCONFG, which can be invoked via batch JCL.

The configuration can be modified at any time by executing USTCONFG in one of two modes:

• A complete new configuration can be built by providing input that completely describes the new configuration.
  
• An existing configuration can be modified by adding new profile definitions, or by modifying existing profile definitions with new options. This modified configuration can then be written back over the original, or it can be written as a new configuration.
  

You can have multiple configuration files, stored either as individual sequential (PS) data sets, or as multiple members in a partitioned (PO) data set.

Activating the New/Modified Configuration

Any changes made to the configuration by USTCONFG do not take effect until the new or modified configuration has been activated. This is done with the REFRESH console command, issued to the UPSTREAM started task, as described in UPSTREAM Operation.

USTCONFG JCL Statements

These JCL statements are required to execute USTCONFG as a batch job. Some sample JCL is provided at the end of this chapter.

EXEC Statement

Must specify PGM=USTCONFG, the name of the UPSTREAM configuration program.

STEPLIB DD Statement

Must specify the name of the UPSTREAM load library.

SYSUDUMP DD Statement

In the event of a catastrophic error, z/OS will take a diagnostic dump to this data set, which may prove invaluable in resolving the problem.

USTCFGIN DD Statement

If updating or printing an existing configuration, this specifies the data set (PS) or member (PO) containing that configuration. The configuration file specified must have DCB characteristics RECFM=FB and LRECL=120. If a completely new configuration is being defined, USTCFGIN can be omitted or specified as DUMMY.

USTCONFG DD Statement

Specifies the output configuration data set or member and must have the DCB characteristics RECFM=FB and LRECL=120. If you are updating an existing configuration, this can specify a data set or member different from the one specified on the USTCFGIN DD. In that case, the modified configuration is written to the new location. Alternatively, it can specify the same data set or member, in which case the modified configuration will replace the original.

Recommendation: A new data set or member name be specified when modifying a configuration, so that you can easily fall back to the original configuration if problems occur with the new one.

USTLOG DD Statement

This is the output message data set for USTCONFG, usually a SYSOUT data set. It has DCB characteristics RECFM=FB and LRECL=80. The BLKSIZE can be any multiple of 80.

USTSRCE DD Statement

This is the control statement input data set for USTCONFG. It can be an input stream (DD *) data set or can point to a data set (sequential or PDS member) as long as the DCB characteristics of the data set are RECFM=FB and LRECL=80.

If you are creating a new configuration, USTSRCE must contain a complete configuration definition, including a MAIN statement and one or more DEFINE statements. If updating an existing configuration, it need only contain the statements required to specify the modifications (i.e., an optional MAIN statement, and one or more MODIFY, DEFINE, DELETE, or PRINT statements).

20.7 USTCONFG Control Statements

The input control statements to USTCONFG must be 80-byte fixed-length records. The control statements may be in the input stream (USTSRCE DD *) or may come from a data set, such as control statement PDS library).

On any control statement, the control statement name (e.g., MAIN) may be preceded and followed by any number of blank columns. At least one blank column must follow the control statement name.

The operands on each control statement are separated by commas with no intervening blanks. The operands may appear in any order.

If the operands are too long to fit on one 80-byte input record, they may be continued onto another record by putting a blank after any comma, and then continuing the operands on the next record, starting in any column, with any number of preceding blanks.

Totally blank records and records with an asterisk “*” in column 1 are treated as comments.

Statement Types

USTCONFG accepts the following control statements:

MAIN

Defines the main UPSTREAM options (MAIN Statement).

DEFINE

Defines or replaces a WSNAME/WSPREF profile definition (DEFINE Statement).

MODIFY

Changes options on an existing WSNAME/WSPREF profile definition (MODIFY Statement).

COPY

Copies an existing WSNAME/WSPREF profile definition to create a new one (COPY Statement).

DELETE

Removes a WSNAME/WSPREF definition from an existing configuration (DELETE Statement).

PRINT

Prints all (or part) of the configuration definition (PRINT Statement).

A sample of a complete USTCONFG input stream is shown at the end of this section.

20.8 MAIN Statement

The MAIN statement, if present, must be the first control statement specified.

• For a new configuration (i.e., the USTCFGIN DD statement is omitted), the MAIN statement is required.
  
• When updating an existing configuration (i.e., the USTCFGIN DD statement points to an existing configuration data set or member), the MAIN statement can be omitted, unless you need to change the general UPSTREAM options specified on the MAIN statement.
  

If a MAIN statement is specified when updating an existing configuration, all operands not using the default value must be re-specified. A value for any operand not specified is replaced with the default value. Please re-specify all non-defaulted operands.

MAIN Statement Syntax

Figure 20.1: MAIN Statement Syntax

MAIN Statement Operands

These are the operands of the MAIN statement.

APPLID=#

applname

Specifies either NONE or the 1 - 8 character name of the VTAM application ID to be used by UPSTREAM.

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.

Alliteratively, 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.

Default: NONE.

DASDBLK=#

nnnnn

Specifies the default block size (1024 - 32760) that UPSTREAM uses when allocating a sequential disk backup.

It is no longer used as the actual block size of the backup data set, so you generally do not need to change the default value. It can be overridden on any or all profiles by the equivalent DASDBLK= operand on a DEFINE or MODIFY statement.

Default: 27998.

MAXHIST=#

nnnn

Specifies the number of days (0 - 32760) that UPSTREAM retains history records in the CATALOG repository.

Records older than the number of days specified are purged when USTMAINT (UPSTREAM Operation) is run.

If MAXHIST=0 is specified, no history records will be created.

Default: 365.

MAXTAPEBACKUP=#

nnn

Specifies the maximum number of tape drives (0 - 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.

MAXTAPERESTORE=

nnn

Specifies the maximum number of tape drives (0 - 255) that UPSTREAM uses for restores at any one time.

If this limit is exceeded, any new restore tasks requiring tape drives wait until the number tape drives in use drops below MAXTAPERESTORE.

If MAXTAPERESTORE=0 is specified, no tape limit is enforced.

Default: 0.

MAXTASKS=#

nnn

Specifies the maximum number of sub-tasks (1 - 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 Security for full details).

0

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.

Default: 0.

SUBSYS=#

cccccccc

Specifies the 1 - 8 character subsystem and control point name that is used on security system calls if SECLVL=1, 2, or 3 is specified.

Specification of this value is optional. Contact BMC Support if you need assistance in altering this value.

Default: UPSTREAM.

TAPEBLK=#

nnn

Specifies the maximum tape DCB BLKSIZE parameter that is used when allocating a new tape data set.

MAX

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

Utility functions such as USTVAULT, USTMIGRT, and USTMERGE support a maximum of 64KB, or the optimum that the target tape device manufacturer allows.

The term “optimum” refers to the manufacturer defined “optimum” BLKSIZE for their device.

Default: MAX.

TCPNAME=#

cccccccc

Identifies the z/OS TCP/IP Started Task instance name with which the UPSTREAM started task communicates.

NONE

This is generally the 1 - 8 character 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: S TCPIP.SYS2 the proper value for this parameter would be “SYS2”.

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

TCPPORT=#

nnnnn

Specifies the TCP/IP port number that UPSTREAM will use as a “well-known” port number to listen for Client connections. The value can range from 1 to 65535.

Default: 1972, which is generally fine for most sites.

WTOCOMP=

Specifies that 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 (USTLOG).

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.

DEFINE, MODIFY, and COPY Statements#

UPSTREAM profiles (UPSTREAM Profiles) can be created or modified using the DEFINE, MODIFY, and COPY statements, as follows.

DEFINE Statement

The DEFINE statement is used to create or replace a profile, named by either a WSNAME or WSPREF operand.

When creating a new configuration, a DEFINE WSNAME or DEFINE WSPREF statement must be present for every profile to be defined. When updating an existing configuration, DEFINE statements are used to add new profiles or completely replace existing profiles. Operands that are not specified on the DEFINE statement take their default values.

MODIFY Statement

When updating a configuration, the MODIFY statement is used to change options on an existing profile, named by either a WSNAME or WSPREF operand.

Operands that are not specified on the MODIFY statement retain their previous values in the profile. If a MODIFY statement names a profile that does not already exist in the configuration, it is treated as a DEFINE, but a warning message is issued and, since defaults may have been taken for many operands, may not result in an appropriate profile.

COPY Statement

The COPY statement can be used when updating a configuration, to create a new profile or replace an existing one.

This is done by copying the attributes associated with an existing profile. The WSNAME or WSPREF operand specifies the input profile, while the NEWNAME/NEWPREF operands specify the profile to be created or replaced. You can also specify any of the other operands shown below to modify the profile as it is being copied.

DEFINE, MODIFY, and COPY Statement Syntax

DEFINE, MODIFY, and COPY Statement Syntax

DEFINE, MODIFY, and COPY Statement Operands

These are the operands of the DEFINE, MODIFY, and COPY statements. Defaults for optional operands apply only to the DEFINE statement. For a MODIFY or COPY of an existing profile, the defaults are the values previously specified for that profile.

COPYINCR

• 
  
  • =====

NOCOPYINCR

• 
  
  • =====

COPYINCR

Specifies that, when doing a full merge backup, any incremental backups that are stored in separate locations is copied to the full backup data set. Incremental backups that are already on the same tape as the full backup are not copied, but incremental backups that are on different tapes or on DASD are copied. Once the incremental backups are successfully copied, they are scratched (if on DASD) and uncataloged, and the UPSTREAM repository record detailing their location is updated to point to the new full backup.

This option is particularly useful if incremental backups are taken to disk but the full backup is written to tape. This option is ignored when MERGE=DEFER is specified.

Default: NOCOPYINCR.

DASD

Specifies that this profile is permitted to perform backups directly to z/OS sequential disk.

If specified, the DASDPREF=and DUNIT=, and VOL=or STORCLAS=options must also be enabled.

Default: NO.

DASDBLK=#

nnnnn

The blocksize (1024 through 32760) to use when allocating to DASD.

This option is no longer used as the actual blocksize of the backup data set, so you generally do not need to override the default.

An exception to this is the special profile for USTVAULT where DASDBLK is used as the blocksize of the vault control file (Copying Backups with USTVAULT).

On a DEFINE, the default is the value of DASDBLK specified on the MAIN statement.

Default: 27998.

DASDGDG

NODASDGDG#

DASDGDG

Specifies that backups are to be allocated as new generations of a GDG. This is recommended, since GDG processing will automatically delete old generations.

GDG bases must be predefined in the appropriate system catalog before they can be used by UPSTREAM. Be sure you define sufficient generations in the GDG base to retain all required backups.

If DASDGDG is used in a “prefix” profile defined with WSPREF, and the last index level of DASDPREF matches the profile prefix name, then UPSTREAM substitutes the actual profile name used by the Client.

Example:

WSPREF=ABC,DASDGDG,DASDPREF=BACKUP.ABC

If the Client uses profile name ABC123, the actual GDG name will be BACKUP.ABC123.

This allows unique data set names to be generated based on the actual profile name. The GDG bases for these modified names must be predefined, and the total length of the name (with a maximum 8-character profile name) cannot exceed 35 characters.

If the last index does not match, the unmodified GDG name is used for all actual profile names (in this case, GDG is not recommended).

DASDMAXSIZE=

nnnnnn

Specifies a maximum size (0 - 999999) in kilobytes (units of 1024 bytes) for sequential disk backups.

For incremental merge backups to DASD only, if the estimated size of the backup exceeds this value, the backup is redirected to sequential tape.

Full merge backups are never redirected to tape.

If DASDMAXSIZE is specified, the profile must be enabled for sequential tape backups (TAPE) as well as sequential disk backups (DASD). However, the DASDPREF value (not TAPEPREF) is used to name the backup.

DASDMAXSIZE=0 indicates never to redirect DASD backups to tape.

Default: 0.

DASDPREF=#

prefix

DASDPREF provides a 1 to 35 character data set name prefix that is used to dynamically allocate the disk data set for the backup. 

The prefix may include periods “.” to separate index levels and must meet z/OS data set naming standards (no more than 8 characters in an index level and the first character of an index must be an alpha/national character).

With DASDGDG=NO, UPSTREAM allocates the backup file as a non-GDG. The length of the value of DASDPREF must not exceed 19 characters, and UPSTREAM adds three additional index levels at the end of the name to create a unique data set name containing the profile name, the date (Dyymmdd), and the time (Thhmmss). Since UPSTREAM adds the profile name to the prefix, the same prefix may be specified in multiple profiles.

For DASDGDG=YES, UPSTREAM allocates the file as a new generation of a GDG. DASDPREF must specify the GDG base name, and may be up to 35 characters long. The GDG name used in each profile should be unique. The suggestion is that it include the profile name. The “%PROFILE” profile name substitution parameter may be used for any qualifier in the data set name. Using this parameter substitutes the name of the backup profile (or, if a DB backup, the backup profile prefix) in the backup data set. The GDG base must be predefined in the appropriate z/OS catalog along with the number of generations to keep. The DELETE option should be specified when defining the GDG base so that old generations are scratched from disk. Ensure that GDG data set names are unique across all profiles, for all UPSTREAM regions, on all LPARS sharing the same z/OS user catalog. i.e., a GDG data set name is used by only one profile. (See also IBM publication z/OS DFSMS Using Data Sets, GDS Reclaim Processing)

Special Characters:

DASDPREF may optionally contain a single exclamation character “!” (X'5A') anywhere in the name. If present, it is replaced at the time the backup is created with:

F - Full merge backup or first-time full merge

I - Incremental merge backup

N - Non-merge backup

This is especially useful if a profile with DASDGDG and where merge backups are being created. You can setup one GDG with the “F” character to specify the number of full backups to be kept, and a second with the “I” character for the number of incremental backups to be retained. You must define GDG bases with each of the possible characters substituted. You must also specify NEWTAPE=FULL.

DASDPREF may also contain a single question mark character “?” anywhere in the name except as the first character of an index level. If present, that character will be replaced with a “1” when the backup is created. If the profile is enabled for vaulting (USTVAULT), the profile must contain the “?”. When USTVAULT is run to create additional copies of the backup, each copy will have another copy number (from 2 to 9) in place of the “?”. If DASDGDG is specified, you must define the GDG base with the “1” substituted, and additional GDG bases with whatever copy numbers you intend to use for vaulting within this profile.

DATACLAS=

NODATACLAS

dataclas

Specifies a data class name (1 - 8 characters) that will be passed to SMS during the dynamic allocation of the backup data set. This value is used by SMS if the data set becomes SMS-managed (see also STORCLAS=and MGMTCLAS=).

Consult your storage administrator or z/OS system programmer for valid data class names.

Default: NODATACLAS.

DREPTD=

nnnn

See RETPD=.

Default: 0.

DUNIT=#

diskunit

Specifies an z/OS disk unit name (i.e., any value that will allocate a disk device when specified in a UNIT= parameter in JCL).

This unit name is used when dynamically allocating the backup data set. The DASD volumes mounted on the devices included in that unit name must include one or more volumes with a mount attribute of STORAGE.

If necessary, UPSTREAM allocates the backup data set on as many as 5 volumes (if that many STORAGE volumes are available).

ENCRYPTV=

If you have the UPSTREAM data encryption feature licensed and enabled, this option specifies the encryption algorithm that will be used by USTVAULT when creating encrypted copies of backups belonging to this backup profile. See UPSTREAM Data Encryption for a full description of the UPSTREAM encryption feature.

AESFAST

AES192

AES256

EXPDT=#

yyddd

See RETPD=.

GROUPID=#

NOGROUPID

id

Used to group profiles for processing by the online utility programs USTMIGRT, USTMERGE, and USTVAULT (see UPSTREAM Profiles for full details). The “id” value is specified as a 2-alpha-numeric character value.

The use of GROUPID is recommended since it automates the selection of backup profiles for utility processing, instead of depending on the operator to specify profile names.

Default: NOGROUPID.

MERGE=#

Controls the utilization of the merge backup facility.

YES

Specifies that this profile is enabled for merge backup processing. The profile must also be enabled for DASD (sequential disk) or TAPE (sequential tape) backups.

NO

Indicates that this profile cannot be used for merge processing.

DEFER

Enables the profile for merge backups, but in addition requests that those backups be performed with “deferred merge” processing option (Completing Deferred Merge Backups).

Default: YES.

MGMTCLAS=#

NOMGMTCLAS#

mgmtclas

Specifies a management class name (1 - 8 characters) that will be passed to SMS during the dynamic allocation of the backup data set. This value will be used by SMS if the data set becomes SMS-managed (see also DATACLAS=and STORCLAS=).

Consult your storage administrator or z/OS system programmer for valid management class names.

Default: NOMGMTCLAS.

MIGTHRESH=

nn

Specifies a threshold for the migration of disk-based backups to tape with USTMIGRT (Migrating Backups from Disk to Tape).

When the USTMIGRT utility is run, it looks for sequential disk backups recorded under each profile name. If the number of such backups equals or exceeds the MIGTHRESH=nn value, USTMIGRT migrates the least recent backups to tape until the remaining number is nn-1.

MIGTHRESH=0 disables USTMIGRT migration for this profile.

MIGTHRESH=255 does not migrate incremental backups made after the most recent full backup.

Default: 0.

NEWNAME=#

cccccccc

Specifies the new profile name (1 - 8 characters) to be assigned to the copied profile. (See WSNAME=and WSPREF=for an explanation of profile names).

WSNAME must also be specified with NEWNAME to identify the existing profile to be copied. The newly copied profile will then be modified by any other operands on the COPY statement and saved under the new name. If a profile with that name already exists it will be replaced by the new one.

NEWNAME and NEWPREF are mutually exclusive.

NEWPREF=

ccccccc

Specifies the new “prefix” profile name (1 - 7 characters) to be assigned to the copied profile. (See WSNAME= and WSPREF=for an explanation of profile names).

WSPREF must also be specified with NEWPREF to identify the existing profile to be copied. The newly copied profile is then modified by any other operands on the COPY statement and saved under the new name. If a profile with that name already exists it is replaced by the new one.

NEWNAME and NEWPREF are mutually exclusive.

NEWTAPEF

NONEWTAPEF

Specifies if a new z/OS data set should be created on a new tape volume when processing first time full or full merge backups.

Default: NONEWTAPEF.

NEWTAPEI

• 
  
  • =====

NONEWTAPEI

Specifies if a new z/OS data set should be created on a new tape volume when processing incremental merge backups.

Default: NONEWTAPEI.

RETPD=#

nnnn

The RETPD, DRETPD, and EXPDT operands apply only to profiles where DASD (sequential disk) or TAPE (sequential tape) backups are enabled, and they specify the retention period in days (0 to 9999), or the expiration date “yyddd” of the dynamically allocated backup data set.

RETPD/DRETPD are identical to the JCL parameter RETPD=.

EXPDT is identical to the JCL parameter EXPDT=. However, it only accepts a 2-digit year number (years less than 70 are assumed to be in the 21st century - 20xx).

Only one of the operands RETPD= or EXPDT= can be specified.

If the profile is enabled for both DASD and TAPE, you can optionally specify a retention period to be used only for disk with DREPTD=.

If DREPTD=is specified (even as DRETPD=0), then the RETPD/EXPDT value will be used only for tape. If it is omitted, the RETPD value applies to both disk and tape, but EXPDT applies only to tape and no expiration is used for disk.

All three operands are optional. By default, no retention or expiration is specified when the data set is allocated. However, your DASD or TAPE management system may apply a default retention.

UPSTREAM does not explicitly enforce these dates, but if you have a DASD or TAPE management system which does, UPSTREAM recognizes that the data set has been scratched or uncataloged during USTMAINT execution.

Special expirations, such as EXPDT=99000 for catalog control, can be specified if they are meaningful to your tape management system. Catalog control is especially meaningful for tape GDGs, since older backups expire as they roll out of the GDG (exceed the maximum generations defined in the GDG base).

Default: 0.

STORCLAS=#

NOSTORCLAS#

storclas

Specifies a valid storage class name (1 to 8 characters) that is passed to SMS during the dynamic allocation of the backup data set and requests that the data set be SMS-managed (see also DATACLAS=and MGMTCLAS=).

Consult your storage administrator or z/OS system programmer for valid storage class names.

Default: NOSTORCLAS.

TAPE

Specifies that this profile is permitted to perform backups directly to z/OS sequential tape data sets.

If TAPE=YES is specified, TAPEPREF and TUNIT or TAPESTORCLAS must also be enabled.

Default: NO.

TAPECOMP

• 
  
  • =====

NOTAPECOMP

• 
  
  • =====

TAPECOMP

Causes UPSTREAM to specify the TRTCH=COMP parameter when dynamically allocating the tape backup to request hardware (IDRC) compaction of the tape data set.

Default: NOTAPECOMP.

TAPEGDG

• 
  
  • =====

NOTAPEGDG

• 
  
  • =====

TAPEGDG

Specifies that any backup data sets are to be allocated as new generations of a GDG. This is recommended since GDG processing automatically deletes old generations.

GDG bases must be predefined in the appropriate system catalog before they can be used by UPSTREAM. Be sure you define sufficient generations in the GDG base to retain all required backups.

Default: NOTAPEGDG.

TAPEPREF=

prefix

Specifies the prefix of the data set name (1 - 44 characters) to be used for sequential tape backups.

See the DASDPREF=description for details of the data set name that is created by UPSTREAM for these backups.

TAPESTORCLAS=

storclas

Specifies an SMS storage class name (1 to 8 characters) that allocates an appropriate SMS-managed scratch tape. This storage class is used when dynamically allocating the backup data set.

TIMEOUT=

nnn

This specifies the maximum number of minutes that UPSTREAM waits for most communication requests to complete. The value can be specified from 0 to 8191 minutes and only affects this backup profile. A value of 0 will not change the timeout value set by either the timeout startup parameter (if set) or a modify command changing the timeout value (if performed).

Default: 0.

TRANSFER=#

Controls the file transfer facility (File Transfer).

YES - Identifies this profile as one controlling a file transfer operation.

NO -

Default: NO.

TUNIT=#

tapeunit

Specifies a z/OS tape unit name. This unit name is used when dynamically allocating the tape backup data set.

UNITCNT=

n - Specifies how many tape drives are allocated when doing tape backups under this profile. Two tape drives may be requested to avoid the delays that occur while rewinding the tape and mounting a new output volume as each tape volume is filled.

Default: 1.

VAULT

• 
  
  • =====

NOVAULT

Specifies if this profile is enabled for the USTVAULT facility (Copying Backups with USTVAULT).

With VAULT=YES, special data set naming takes effect. See the TAPEPREF=and DASDPREF=fields for additional information.

Default: NOVAULT.

VOL=#

volser

Specifies an z/OS disk volume serial (1 to 6 characters) where the backup data set is allocated. If VOL is specified, a unit name of SYSALLDA is used for all dynamic allocations to the volume.

The DUNIT, VOL, and STORCLAS parameters are mutually exclusive.

WSNAME=

cccccccc

Specifies the profile name to be defined. WSNAME is 1 to 8 alpha, numeric, or national characters in length and must start with an alphabetic or national character, but the remainder may be any alphanumeric or national character.

UPSTREAM profiles are fully described in UPSTREAM Profiles.

WSPREF=#

ccccccc

Specifies that the backup profile name is a “prefix”, rather than a fully qualified name. When this option is in effect, the parameters specified for this backup profile are used when the exact profile name specified in the backup request does not exist in the configuration, but it does match all the characters specified.

For example, a “prefix” backup profile called “TES” can used to control UPSTREAM backup requests that use profiles of TEST, TEST21, TESTER etc. This effectively allows you to manage numerous unique backup profile names with just one overall controlling backup profile in the configuration.

This feature is useful if a large number of profiles have similar prefix naming and utilize similar profile attributes.

This option may also be used for Oracle and DB2 multi-channel database backups. If the backup profile is defined as a prefix, the channel number of that portion of the multi-channel backup is appended to the profile prefix name in the backup data set name. This feature, in addition to the backup date and time, creates a unique backup data set name. If the data set is a GDG, either the profile prefix name must be specified as the last qualifier of the GDG base data set name or the “%PROFILE” profile name substitution parameter must be used as a qualifier in the GDG base data set name. When creating the GDG base, define a base name for each profile_prefix_channel_number combination for all channels that may be used when the backup is run. For example, using the example above, data set names might be:

HLQ.DB2.DATA.TES1.G0123V00

and

HLQ.DB2.DATA.TES2.G0123V00

where “TES” is the profile prefix name and channels 1 and 2 were used in the backup.

WSPREF is 1 - 7 characters in length and must start with an alphabetic or national character, but the remainder may be any alphanumeric or national character.

UPSTREAM profiles are fully described in UPSTREAM Profiles.

DELETE Statement

The DELETE statement is used to delete a profile from an existing configuration. As such, it can only be used when updating a configuration (i.e., if USTCFGIN DD statement is present).

DELETE STATEMENT Syntax

ELETE Statement Syntax

DELETE STATEMENT Operands

WSNAME=#

profilename

Specifies the name of the profile to be deleted.

WSPREF=#

prefixname

Specifies the name of the “prefix” profile to be deleted.

PRINT Statement

The PRINT statement is used to print information about the configuration. It can print definitions of:

• Individual profiles
  
• The UPSTREAM general options
  
• The entire configuration
  

PRINT Statement Syntax

PRINT Statement Syntax

ALL

Specifies that information about the entire configuration is printed, including UPSTREAM options from the MAIN statement and all profile definitions.

WSNAME=#

profname

Specifies that only the definition of the specified profile is printed. Multiple profiles can be printed by entering multiple PRINT statements. If neither ALL, WSNAME, nor WSPREF is specified, then only the options from the MAIN statement and the definition of the GLOBAL profile (if defined) is printed.

WSPREF=#

prefixname

Specifies that only the definition of the specified “prefix” profile is printed. Multiple profiles can be printed by entering multiple PRINT statements. If neither ALL, WSNAME, nor WSPREF is specified, then only the options from the MAIN statement and the definition of the GLOBAL profile (if defined) is printed.

LIST=#

LONG

Lists the profiles in a format similar to the DEFINE statement.

PUNCH

Lists the profiles in a format that duplicates the MAIN and DEFINE statements necessary to reproduce the configuration. With minor editing, the output can then be turned into a data set that can be read back in by USTCONFG.

This operand is optional.

Default: LONG.

Sample USTCONFG JCL

Example #1: Creating a New Configuration

This sample JCL is provided as member USTCONFG in the UPSTREAM Installation Control Library (ICL).

It creates a brand new configuration by reading USTCONFG control statements stored in a member of a control statement library pointed to by the USTSRCE DD. The new configuration is stored in the member pointed to by the USTCONFG DD statement.

Example #2: Updating an Existing Configuration

This sample JCL updates an existing configuration.

The old configuration is read from DD USTCFGIN and updated by control statements stored in the file pointed to by the USTSRCE DD. The updated configuration is then written to the member indicated on the USTCONFG DD statement.

Sample USTCONFG Configuration

The following sample configuration is included in the UPSTREAM Installation Control Library (ICL) as member USTCFG01 and serves as a sample of a fairly basic UPSTREAM configuration.