Updating the Repository

USTREGEN Overview

The USTREGEN utility can be used to insert or update information in the UPSTREAM repository. The source of the new/updated information can be:

• An original UPSTREAM backup

  If, for any reason, information for a backup is inadvertently removed from the repository (deleted, expired etc), this information can be re-written to the repository, as long as you still have the original backup tape available and cataloged to z/OS. Every UPSTREAM backup contains a copy of the repository records that describe it, allowing USTREGEN to read that information and re-write it back into the repository.

• A foreign UPSTREAM or UPSTREAM Reservoir backup

  USTREGEN can read any backup created by any UPSTREAM system, including the UPSTREAM Reservoir (assuming the tape hardware is compatible and the defaulted “UPSTREAM-z/OS Compatible” option was set in the profile definition that was used to create the backup). USTREGEN can, therefore, be used to read a “foreign” backup created by a different UPSTREAM or UPSTREAM Reservoir system, importing the appropriate control records into the new host UPSTREAM system's repository.

• A vaulted copy of an UPSTREAM backup (USTVAULT)

  UPSTREAM repository records normally point to the original (copy 1) backup, so that all restores use that primary copy. When additional copies are created by USTVAULT (Copying Backups with USTVAULT) control records updated to point to the secondary copy are written to a separate data set at the end of the vaulted tape. If you need to access the vaulted backup at any time (e.g., at a disaster recovery site), USTREGEN can read those control records from the separate data set and update the repository to point to the copied backup, enabling all future restore requests to use that copy.

  If you are using the UPSTREAM data encryption feature (UPSTREAM Data Encryption) and if you have chosen to encrypt the vault control data set as well as the actual copies of the backups themselves (via the ENCRYPTV option in the USTVLTxx profile), you need to ensure that the UPSTREAM encryption key file is accessible to USTREGEN.

Executing USTREGEN

USTREGEN can be executed in various ways:

• USTREGEN via UPSTREAM Operator Command
  
• USTREGEN via z/OS Operator Command
  
• USTREGEN via USTBATCH
  
• USTREGEN as a Batch Job
  

See USTVAULT (Copying Backups with USTVAULT) for additional information on running USTREGEN.

USTREGEN via UPSTREAM Operator Command

USTREGEN can be initiated through an UPSTREAM operator command with the UPSTREAM started task active.

Select option 6 (“Operator Commands”) from the UPSTREAM TSO/ISPF dialog main menu and press ENTER.

USTREGEN via z/OS Operator Command

You can initiate a USTREGEN process using an z/OS operator command to the UPSTREAM started task.

• First, enter the z/OS console interface that you would normally utilize to access the z/OS system console. In the example below we are using the IOF product.
  
• Then, on the command line, enter a REGEN command in the format shown below and press ENTER.
   F [started task name],REGEN [P=xxxxxxxx][,DSN=xxxxxx]

• In our example below, we are running a REGEN process against a vaulted copy of a backup:
  

The combined length of the P= and DSN= operands can not exceed 43 characters.

USTREGEN via USTBATCH

USTREGEN can` also be executed via USTBATCH (z/OS Initiation with USTBATCH) when the UPSTREAM started task is active. The sample USTBATCH job below shows a REGEN against the backup called “backup.dataset.name” This JCL would require some customizing for your own site's requirements, such as the JOB card and STEPLIB specifications. Please also review the parameter descriptions that follow.

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

  //jobname  JOB (accounting,information),'job id data',
  //         NOTIFY=userid,MSGLEVEL=(1,1),CLASS=A,MSGCLASS=X
  //*
  //*
  //MAINT    EXEC PGM=USTBATCH
  //STEPLIB  DD DISP=SHR,DSN=your.upstream.loadlib
  //SYSUDUMP DD SYSOUT=*
  //USTLOG   DD SYSOUT=*
  //USTPARM  DD *
  HOSTDNS=YOUR.LPAR.DNS.NAME
  HOSTPORT=1972 *default
  *
  CONV=WAIT * WAIT for Backup to complete before ending
  COMMAND=REGEN DSN=backup.dataset.name
  *
  ENDPARM
  /*

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

  //jobname  JOB (accounting,information),'UPSTREAM REGEN',
  //        MSGLEVEL=(1,1),CLASS=A,MSGCLASS=X
  //*  **********************************************************
  //*  ***         REGEN A BACKUP                             ***
  //*  **********************************************************
  //REGEN    EXEC PGM=USTBATCH
  //STEPLIB  DD DISP=SHR,DSN=your.upstream.loadlib
  //SYSUDUMP DD SYSOUT=*
  //USTLOG   DD SYSOUT=*
  //USTPARM  DD *
  APPLPREF=UPSTR
  USAPPL=UPSTREAM
  LOGMODE=#INTER
  CONV=WAIT
  COMMAND=REGEN DSN=backup.dataset.name
  ENDPARM
  /*

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

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

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

HOSTDNS

The DNS name of the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTIP parameter.

HOSTIP

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

HOSTPORT

The IP port number of the UPSTREAM started task. If omitted, the default is 1972. This parameter may be used with either the HOSTDNS or HOSTIP parameters.

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

APPLPREF=

The 5-character prefix of the VTAM APPLID to be used by USTBATCH for its communications with the UPSTREAM started task.

USAPPL=

The VTAM APPLID of the UPSTREAM started task.

LOGMODE=

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

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

CONV=

This controls whether or not the USTBATCH job should wait for the completion of the request submitted to the started task, or end immediately after the request is accepted.

COMMAND=

This controls the started task command that is to be issued, in this case a REGEN.

ENDPARM

Indicates the end of the USTBATCH input parameters.

USTREGEN as a Batch Job

As we have shown, USTREGEN can be executed in various ways. If the UPSTREAM started task is not active, USTREGEN can be executed rather than USTBATCH.

In this example of running USTREGEN as a batch job, the USTARCH DD statement points directly to the backup itself, rather than to the vault control data set (but USTREGEN can read the required information from either source).