Reporting with USTRPORT

Introduction

The ability to produce a range of reports, both detailed and in summary format, is an essential feature of any storage management system. UPSTREAM provides a wide range of reporting capabilities, including:

• USTRPORT (described in this chapter)

• USTBKPRT (see Reporting with USTBKPRT.)

• UPSTREAM Client GUI interface (see the UPSTREAM Client Guide.)

• UPSTREAM Director interface (see the UPSTREAM Client Guide.)

USTRPORT Overview

USTRPORT allows you to report on a wide range of UPSTREAM system activity, including backups, restores, unsuccessful backups and USTVAULT operations.

UPSTREAM history records, retained by the MAXHIST configuration parameter, can also be queried and reported with USTRPORT.

Additional reports are also available in support of key UPSTREAM features, such as registered names and configuration. Administrators responsible for the support and maintenance of the UPSTREAM system can use USTRPORT to view some/all of the contents of the UPSTREAM configuration file.

USTRPORT reports can be in either a “fixed” format (where the layout of the report is fixed, but the contents are controlled by the user. (These can be output either in a standard print and/or a CSV file for import into a spreadsheet. Or, they can be generated from scratch, with full control over both the print layout and the contents of the report.

Running USTRPORT

Reports can be generated with USTRPORT in one of two ways:

• Via an z/OS batch job (see Initiation via an z/OS Batch Job)

• Via the ISPF Reporting Interface (see Initiation via the TSO/ISPF Dialog)

USTRPORT Report Types

The following types of report can be produced by USTRPORT, as controlled by the RPTYPE operand of the PRINT control statement (see PRINT Statement).

BACKUP

For each backup that you perform, UPSTREAM stores a record in the CATALOG repository data set. The USTRPORT “BACKUP” report can display information from some/all of those backup records. Additionally, available as a z/OS batch job, output can also be made to a CSV file.

EXCEPTION

By reading records from the CATALOG and FILEINFO repository data sets, the USTRPORT “EXCEPTION” report can be used to identify profiles that have not had a successful backup within the exception period.

SQBACKUP

The USTRPORT “SQBACKUP” report can be used to list the contents of a UPSTREAM sequential disk/tape backup, taking information from the CATALOG and FILEINFO repository data sets.

VAULT

For each vault operation performed by USTVAULT (Copying Backups with USTVAULT), UPSTREAM stores a record in the CATALOG repository data set. The USTRPORT “VAULT” report can display information from some/all of those vaulting records.

HISTORY

In addition to the preceding records, a “history” record is also created on the completion of each UPSTREAM function (backup, restore, or vault). These records, which are also stored in the CATALOG repository data set, contain information such as the function requested, the elapsed time, execution time, and the number of files processed. They allow you to report on overall UPSTREAM activity, or on the activity of specific servers or functions. The USTRPORT “HISTORY” report can display information from some/all of those history records.

CONFIG

The USTRPORT “CONFIG” report can be used to report on one or more backup profiles currently defined in your UPSTREAM configuration, including all of their associated parameters and settings.

CUSTOM

While the previous reports are all “fixed format”, a USTRPORT “CUSTOM” report allows you to have more control over the content and layout of the report, allowing you to specify which fields will appear in the report, and the order in which those fields will appear.

REGISTRY

This report displays information about the registered name facility (see Registered Name Service).

USTRPORT Control Statements

Each report can be controlled by one or more control statements, which are used to specify the format of the report and what data is to be included.

The control statements are briefly described below, and full details then follow. A PRINT statement must be entered for a report to be generated. All other statements are optional.

TITLE

The TITLE statement allows you to provide a user-defined title for the report. All reports should contain a title to describe and summarize the contents of the report. See TITLE Statement.

HEADING

The HEADING statement allows you to alter the default column headings for the fields that are selected to appear in the report. See HEADING Statement.

DEFAULT

The DEFAULT statement is used to change the operating defaults of USTRPORT when generating a report. See DEFAULT Statement.

SELECT and EXCLUDE

The SELECT statement specifies selection criteria for the data values that are to be included in the report. See SELECT and EXCLUDE Statements.

The EXCLUDE statement specifies criteria for excluding certain data values from the report. See SELECT and EXCLUDE Statements.

REPORT

The REPORT statement is used customize the report, specifying the fields that are to appear in the report. See REPORT Statement.

PRINT

The PRINT statement follows all previous control statements and generates the requested report. See PRINT Statement.

CANCEL

The CANCEL statement is used to negate the effects of all or some prior statements, except DEFAULT. See CANCEL Statement.

TITLE Statement

The TITLE statement is used to define a user-specified title line to be displayed between the default header identification and the column headings. This title line is used as the main identifier for the contents of the report. A maximum of one line may be specified.

Regardless of the use of the TITLE statement, a two line header is automatically generated to identify the fields being reported (i.e., column headings).

TITLE Statement Syntax

TITLE Statement Syntax

TITLE Statement Operands

LINE=#

text

Specifies the text to be printed or displayed in the title. The text must be enclosed in quotes. The number of characters specified must not exceed the page width.

If the title cannot be contained on one control statement (Column 1 to 71), you can continue the text by specifying a “+” or a “-” after the last character on this line.

If “+” is specified, USTRPORT scans for the first non-blank character on the next statement.

If “-” is specified USTRPORT starts with column 1 of the next statement.

Example:

TITLE LINE='BACKUP +
 REPORT'

SKIP=#

n

Specifies the number of lines to be left blank between the title line and the data heading line. A value of 1 to 3 lines may be specified.

Default: 1.

HEADING Statement

USTRPORT provides default column headings for each field in the report. (See REPORT Statementfor a full list).

The HEADING statement allows you to specify up to 3 lines of replacement text. It is your responsibility to line up the text with the actual columns generated by USTRPORT.

HEADING Statement Syntax

HEADING Statement Syntax

HEADING Statement Operands

LINE(n)=

Specifies the replacement text for up to 3 heading lines (n=1, 2, or 3). Only LINE(1)= is required, the others are optional.

If the heading text cannot be contained in one control statement (columns 1 to 71), it may be continued using the same conventions described for the TITLE statement.

DEFAULT Statement

The purpose of the DEFAULT statement is to change USTRPORT's default values for various options used when generating a report. Most of the operands on the DEFAULT statement are also operands on the PRINT statement and can be specified there.

The DEFAULT statement can be used when more than one report (i.e., more than one PRINT statement) is to be generated in one execution of USTRPORT. The DEFAULT statement avoids having to specify more than once any options used in multiple reports.

The alias SET can be used in place of DEFAULT.

DEFAULT Statement Syntax

DEFAULT Statement Syntax

DEFAULT Statement Operands

BYTEFORMAT=#

Specifies the format of the print fields that report a number of bytes.

BYTE

Values are always reported in bytes; if the value exceeds 8 digits, asterisks are displayed.

KILOBYTE

Values are always reported in kilobytes (bytes/1024). Commas are usually inserted to improve readability, but may be omitted if the value exceeds 6 digits.

MEGABYTE

Values are always reported in megabytes and tenths (e.g., 120.5).

Default: The default is that byte fields are displayed in bytes, but if the value is too large it automatically converts the display to kilobytes or megabytes, as required, with a “K” or “M” to the right to indicate the conversion.

CLOCK12

CLOCK24

Specifies how the time of day should be printed in a report including BKFILES (information about workstation/server files included in a backup). The time is the “last update” time recorded for the file.

CLOCK12

Displays it in AM/PM format.

CLOCK24

Displays in 24-hour clock format.

Default: CLOCK12.

EXNOBKDSN

SLNOBKDSN

For RPTYPE=BACKUP, or a custom report that includes the BKDSN or BKVOLS fields:

EXNOBKDSN

Specifies that report lines for history records whose backup data set is no longer recorded in the CATALOG repository (probably because they have expired) is not reported.

SLNOBKDSN

Indicates that they are reported (with “DSN not available” in the BKDSN field).

Default: EXNOBKDSN

EXNOCATLG

SLNOCATLG

For RPTYPE=BACKUP, or a custom report that includes the BKDSN field.

EXNOCATLG

Specifies that report lines for backup data sets that are no longer cataloged in the z/OS catalog are not generated.

SLNOCATLG

Indicates that they are generated (with “not catlg” in the BKVOLS field).

Default: EXNOCATLG.

FORMAT=#

Specifies formatting options for the records selected.

DUMP

Indicates that the record is printed in hexadecimal dump format only.

NORMAL

Indicates records are formatted as normal.

VERIFY

Indicates that the record is printed in hexadecimal dump format immediately following the formatted record.

Default: NORMAL

FULLNAME

SHORTNAME

FULLNAME

Specifies that in a report including BKFILES (information about Client files included in a backup) all file names should be printed with the full path name.

SHORTNAME

Is that the full path name is included only with the first file under a given directory; additional files under that directory have blanks up to the last backslash “\” in the name.

Default: SHORTNAME.

LINECNT=#

nn

Specifies the maximum number of lines each report page can contain. The number can be any value from 10 to 99, inclusive.

Default: 58.

MAXCC=#

nnnn

Overrides the maximum completion code from all USTRPORT statements that preceded this DEFAULT (or SET) statement. This is the completion code returned to z/OS at the end of this USTRPORT step, unless a subsequent statement causes a higher code. This might be used to set the maximum code to zero (SET MAXCC=0) when the successful completion of preceding operations has no bearing on this particular report.

NOABEND

Directs USTRPORT to exit with an error return code instead of a user abend for the rare and unusual conditions that would normally cause a user abend to be taken.

NOCLOCK

USTRPORT generates a title line with the time, date, and page number as the first line of every page. The NOCLOCK option directs USTRPORT to only obtain (from z/OS) the time and date at the beginning of the report and always repeat that value on each page. Normally, without this option, USTRPORT refreshes the time and date at the beginning of each new page.

PAGEWIDTH=#

nnn

When creating custom reports with the REPORT statement, USTRPORT calculates the width of the report using the length of all requested fields, plus spaces between the fields. An error occurs if the report width exceeds the current page width. PAGEWIDTH= has a minimum of 132 and maximum of the LRECL of SYSPRINT minus 1 (which is also the default).

PROFSTACK

NOPROFSTACK

When creating custom reports with the REPORT statement, USTRPORT normally builds the report in the same manner that it builds the report for RPTYPE=HISTORY or RPTYPE=BACKUP - by printing the backup profile name first and then reporting all records for that backup profile, indented by one space. This is the PROFSTACK option.

If the FIELD operand on the REPORT statement includes PROFILENAME, this is not done. This is the NOPROFSTACK option.

The PROFSTACK and NOPROFSTACK operands on the DEFAULT statement can be used to override the default operation previously described.

NOPROFSTACK does not list the backup profile name, even if PROFILENAME is not included on the FIELD operand of the REPORT statement. PROFSTACK lists the backup profile name and indents the following records, even if the profile name is also printed on each line.

SELTERR=#

Specifies if USTRPORT should end with a condition code if no records were selected for reporting by a PRINT statement.

YES

Indicates that you want to be notified that no records were selected (probably due to an error in your SELECT/EXCLUDE statements).

NO

Causes a zero condition code if the only error was that no records were selected.

Default: YES.

SHOWATTR

NOSHOWATTR

Specifies whether a report including BKFILES (information about Client files included in a backup) should include the attribute flags associated with each file.

Default: NOSHOWATTR - do not display attributes.

SUMDIR=#

For RPTYPE=BACKUP or RPTYPE=VAULT, and with the BKFILES field specified on the SELECT statement, SUMDIR controls the printing of summaries of the number of files and data bytes in each directory.

As shown in the syntax summary, SUMDIR has three sets of parameters. You can specify one from each set, enclosing the values in parenthesis, or you can specify only one parameter without parenthesis. Examples:

SUMDIR=(ONLY,FULLNAME) or SUMDIR=INCLSUB

Valid values for SUMDIR are:

YES

Requests that the summary-by-directory be printed at the end of the report.

NO

Suppresses the summary (all other SUMDIR options are ignored).

ONLY

Requests that only the summary be printed, suppressing the detail report.

FULLNAME

Prints the full path name for each directory summarized.

SHORTNAME

Uses an indenting scheme to show the structure of subdirectories.

INCLSUB

The summary for each directory includes all files in that directory, plus all subdirectories beneath that directory. This also means that the directory at the very top of the summary summarizes all files in all directories listed.

EXCLSUB

The summary for each directory includes only those files that actually exist in that directory, not including those in subdirectories beneath that directory.

Default: YES, NOFULLNAME, EXCLSUB.

UPPERCASE

LOWERCASE

UPPERCASE

Forces all output to be generated in only uppercase characters.

LOWERCASE

Allows USTRPORT to use both upper and lower case characters in reports.

Default: LOWERCASE.

SELECT and EXCLUDE Statements

The SELECT and EXCLUDE statements act as a filter for the data sets to be processed by USTRPORT, comparing the values you specify against the values in the repository records to be processed.

The operands on SELECT and EXCLUDE may be followed by one of a number of comparison operators. Since one form of those operators involves special characters, such as the not “¬” and the less than “<“, alternate forms of each operator without special characters are provided.

The operators are:

= or .EQ. - equal

¬= or .NE. - not equal

< or .LT. - less than

> or .GT. - greater than

<= or .LE. - less than or equal to

>= or .GE. - greater than or equal to

Some operands only accept an equal test, some equal and not equal, and some accept all six comparisons, as shown in the syntax summary below.

USTRPORT tests each SELECT and EXCLUDE against the values in each input record. The test implied by each operand is true if the indicated comparison of the FIELD value and the value you provide is true. For example, COMPCODE.NE.0 selects all records for operations that did not complete successfully.

Some operands allow you to specify multiple values in parenthesis for equal and not-equal (as shown in the table below) or single values without parenthesis. If multiple values are specified, USTRPORT compares the input record to each of those values. For equal, the test is true if ANY of the comparisons are equal. For not-equal, the test is true if ALL of the comparisons are not-equal. For example, COMPCODE=(0,SUSPEND) selects those entries whose completion code was either zero or whose operation was suspended. A given field name may be specified more than once with several different operators.

If there are no SELECT or EXCLUDE statements present then all records relevant to the report type (RPTYPE=) are reported. If only EXCLUDE statements are present, then all records not excluded are reported; likewise if only SELECT statements are present, only selected records are reported. If both types are used, EXCLUDE statements should precede SELECT statements to EXCLUDE a subset of the records selected; other than that, the order of the SELECT and EXCLUDE statements is not significant.

SELECT / EXCLUDE Examples

SELECT PROFILE=PROD*,FILES>100,DAYS<5SELECT OPERNAME=(BACKUP,'BACKUP M'),BYTES>100000,BYTES<500000EXCLUDE TRACKS.LE.1000EXCLUDE FILES.GT.100

SELECT / EXCLUDE Statement Syntax

Figure 21.4: SELECT / EXCLUDE Statement Syntax

SELECT and EXCLUDE Statement Operands

PROFILE

Specifies one or more backup profile names. A profile prefix can be specified by using a “*” as the last character of the operand. For example to list all of the entries for all profiles that begin with “SYS” and “OPER” specify PROFILE=(SYS*,OPER*). If necessary, the field can be continued by using a trailing comma onto multiple lines.

BKFILES

Only valid with RPTYPE=BACKUP and VAULT to print output. The operand may be up to 60 characters in length and is not case sensitive. If the value contains embedded blanks, the value must be enclosed in single quotes. If present, the report displays details of Client files that were included in each UPSTREAM backup file reported. The length of the filename printed is limited by the page width currently in effect (see PAGEWIDTH=); the usual page width can display the first 88 characters of file names (including the complete path name). BKFILES=* displays all files contained in the backup, or you may specify a prefix to limit the display. The prefix must match on the beginning characters of the complete path name of the file, for example:

BKFILES=/opt/*
'BKFILES=/opt/name of file'

Individual client files up to 9.99 TB are reported and tallied.

BKTYPE

For backups, indicates the type of backup. Valid values are as follows:

DASD

Backups to disk.

TAPE

Backups to tape.

DEFR

Deferred merge backups that have not yet completed

BLOCKS

Specifies the number of blocks transmitted to/from the Client.

BYTES

Specifies the number of bytes transmitted to/from the Client.

CONDCODE

Specifies the completion codes status of the operation. One or more values can be specified. The following are the valid options:

ABEND

The operation received a System or User abend.

SUSPEND

The operation was suspended.

CANCEL

The operation was canceled.

SYSTEM

The operation received a SYSTEM abend.

USER

The operation received a USER abend.

0 or ZERO

The operation completed successfully.

4

The operation completed with warning messages.

8

The operation was terminated with error messages.

12

The operation was terminated with severe errors.

16

The operation was terminated by the operator.

CPUTIME

Specifies the CPU time required, in thousands of a second or milliseconds, for the operation to complete. For example, to report all of the events that took less than one second of CPU time you would specify CPUTIME.LE.1000 or CPU<=1000.

DAYS

Calculates a date “n” days (0 to 9999) previous to the current date; that date is compared to the starting date recorded in each history record. For example to select records for the last ten days, specify DAYS.LE.10 or DAYS<=10. To select records over 30 days old specify DAYS>30.

DATE

Specifies a date, in the format “yy/mm/dd”, that is compared to the starting date recorded in each history record. For backups, this is the date part of the “version-date”.

ELAPSEDTIME

Specifies the elapsed time, in tenths of minutes, recorded for the operation to complete. For example, to select records for operations that took over 2.5 minutes you would specify ELAPS.GE.25 or ELAPS>=25.

FILES

Specifies the number of files transmitted to/from the Client.

HOURS

Calculates a time “n” hours (0 to 999) previous to the current time; that time is compared to the starting date and time recorded in each history record. For example to select records for the last ten hours, specify HOURS.LE.10 or HOURS<=10.

LUNAME

Specifies one or more Client workstation/server IDs (up to 8 characters) or ID prefixes (up to 7 characters followed by an asterisk). For TCP/IP Clients, this is the network address coded as an 8-digit hexadecimal value (each pair of digits corresponds to one of the 4 values in the address, converted to hex). For SNA APPC Clients, this is the VTAM LUNAME.

MERGEBLOCKS

Specifies the number of blocks that were merged forward from previous backups during a full merge backup. Not valid for other operations.

MERGEBYTES

Specifies the number of bytes that were merged forward from previous backups during a full merge backup. Not valid for other operations.

MERGEFILES

Specifies the number of files that were merged forward from previous backups during a full merge backup. Not valid for other operations.

MIGRATEFILES

Specifies the number of migrated files that were merged forward from previous backups during a full merge backup. Not valid for other operations.

OPERNAME

Specifies one or more UPSTREAM operations. Valid values are:

For UPSTREAM operations:

BACKUP

'BACKUP M'

‘BACKUP D’

RESTORE

RESTARTB

INQUREV

INQUIREF

'REMOVE F'

'REMOVE B'

'COMM z/OS'

'COMM PC'

'VSAM TST'

'NON I/O'

LOGIN

For utility operations:

DELETE

MAINT

MAINTF

REGEN

REORG

For UPSTREAM Termination:

SHUTDOWN

For mainframe-initiated operations

HOSTINIT

Values shown with quotes must be entered that way as they contain blanks; others can be entered with or without quotes.

OPERTYPE

Specifies one or more UPSTREAM operation types. Operation types are used with certain operation names to qualify the type of operation. Valid operation types are:

For BACKUP:

INCR - Incremental backup

FULL - First-time full backup

MERG - Merge backup

For EXCEPTION:

INCR - Incremental backup

FULL - First-time full backup

MERG - Merge backup

NONM - Non-merge backup

For RESTORE

TAPE - Backups to tape

DASD - Backups to disk

For HOSTINIT

z/OS - Functions remotely initiated from the z/OS Storage Server

PC - Functions remotely initiated from the Client

TAPES

Specifies the number of tape volumes that were used for a sequential tape backup. Not valid for other operations.

TIME

Specifies a time, in the format “hh:mm:ss”, that is compared to the starting time recorded in each history record. For backups, this is the time part of the “version-date”.

TRACKS

Specifies the number of DASD tracks that were used for a sequential DASD backup. Not valid for other operations.

USERID

Specifies one or more userids (up to 8 characters) or userid prefixes (up to 7 characters followed by an asterisk). Userids are recorded in history records if the userid was specified at the Client.

If the SECLVL=0 configuration option is specified (see “The SECLVL Parameter” in Section), userids are optional.

21.10 REPORT Statement

The REPORT statement is used to customize reports by specifying the fields to be printed, and the order in which to print them. The REPORT statement is honored if RPTYPE=CUSTOM is specified, or if RPTYPE= is omitted.

The report generated uses the same input data as RPTYPE=HISTORY or BACKUP. If the fields do not include any fields related to backup data sets, the report reports on history records only. If any backup fields are included in the report, it reports on history and backup data, including backup data that has no matching history records.

SELECT and EXCLUDE statements, if present, filter the data to be reported.

REPORT Statement Syntax

REPORT Statement Syntax

REPORT Statement Operands

FIELD=#

Specifies the names of one or more FIELDs to be printed in the custom report. The available field names are shown in the table below.

The fields are printed in the order specified. There is one space between fields, unless the SPn field names are used (where “n” is 0 to 9) to cause the specified number of spaces to appear between the preceding and following fields.

The example below uses SP3 to insert 3 spaces between VERSION and BKDSN, but only one space between BKDSN and BKVOL:

REPORT FIELD=(VERSION,SP3,BKDSN,BKVOL)

Field Name Table

The following table lists the field names that are available for inclusion in the FIELD operand of the REPORT statement. Many of these field names can also be used on SELECT and EXCLUDE statements and have already been described in that section. For each field, the table shows:

NAME

The field name as used in the FIELD= operand

ABBREV

Any valid abbreviations for the field name.

ALAIS

Any valid alias for the field name

ATTR

How the field is displayed:

CHAR

character

NUM

• 
  
  • ======

numeric

HEX

hexadecimal (binary)

LEN

The number of print positions it occupys in the report

DESCRIPTION

A brief description of the field.

The PRINT statement instructs USTRPORT to generate the report, using the characteristics specified by the preceding control statements (SELECT, EXCLUDE, DEFAULT, TITLE, HEADING, or REPORT) that are currently in effect. These statements remain in effect until canceled by a CANCEL statement, or superseded by new TITLE/HEADING statements.

A PRINT statement must be entered, or no report is generated. Multiple PRINT statements may be given to produce various reports in one execution of USTRPORT.

PRINT Statement Syntax

PRINT Statement Syntax

PRINT Statement Operands

Most of the operands on the PRINT statement are also operands on the DEFAULT statement, and are documented DEFAULT Statement. Operands specific to the PRINT statement are as follows.

MEMBER=#

Used with RPTYPE=CONFIG only, specifies the PDS member name of the UPSTREAM configuration file against which this report is to run. It can be omitted if the member name is specified on the USTCONFG DD Statement in the UPSTREAM startup PROC. It must be omitted if the configuration data set is a sequential file.

RPTYPE=#

Specifies the format of the report to be generated, as well as implying the data source for the report. See USTRPORT Report Typesfor the allowable values for RPTYPE.

Default: HISTORY, except that if a REPORT statement is in effect, when the default is CUSTOM.

CANCEL Statement

The CANCEL statement is used to negate the effects of some or all prior statements, except DEFAULT.

By default, the options specified on all preceding statements (except PRINT) remain in effect until you cancel them (or, in the case of TITLE, HEADING, and REPORT, until you override them). Additional SELECT and EXCLUDE statements are added to those already in effect.

CANCEL can be used between PRINT statements to cancel options in effect so that they can be re-specified (or the defaults used).

If no operands are specified, CANCEL cancels the effect of all of the prior commands except DEFAULT.

CANCEL Statement Syntax

CANCEL Statement Syntax

CANCEL Statement Operands

EXCLUDE

Cancels the current exclusion criteria table as created by preceding EXCLUDE statements.

HEADING

Cancels the current HEADING line(s), reinstating the defaults.

REPORT

Cancels the current REPORT field specifications.

SELECT

Cancels the current selection criteria table as created by preceding SELECT statements.

TITLE

Cancels the current TITLE line(s), reinstating the defaults.

USTRPORT Initiation

USTRPORT reports can be initiated in one of two ways:

• Via a z/OS Batch job. (USTRPORT Batch Examples)

• Via the TSO/ISPF Dialog. (Initiation via the TSO/ISPF Dialog)

Initiation via an z/OS Batch Job

The following job control statements are required to execute USTRPORT as an z/OS batch job. Example jobstreams are provided in USTRPORT Batch Examples.

EXEC Statement

Must specify USTRPORT.

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

It may optionally contain a PARM= operand to pass options to the USTRPORT program. Any PARM= data passed to the USTRPORT 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

Specifies the library in which USTRPORT resides (usually the UPSTREAM load library). This must be an APF authorized library.

SYSPRINT DD Statement

Specifies the primary output message data set. This is a required DD statement and is usually a SYSOUT data set. The LRECL may be specified from a minimum of 133 to a maximum of 241 (133 is the default if not specified).

If BLKSIZE is not specified, the system determined blocksize (SDB) is used on systems that support it. LRECL multiplied by 64 is used on other systems.

SYSUDUMP DD Statement

Recommended in all USTRPORT jobs in order to diagnose more easily error conditions that make USTRPORT abend. Usually a SYSOUT data set.

USTCATLG DD Statement

Specifies the CATALOG repository file. For example,

//USTCATLG DD DSN=UPSTREAM.CATALOG.$UST.CLUSTER,DISP=SHRThis DD statement is required for all report types except RPTYPE=CONFIG.

USTCONFG DD Statement

Specifies the data set name (and member name, if a PDS) of the UPSTREAM configuration file. For example:

//USTCONFG DD DSN=UPSTREAM.CONFIG.FILE(CONFIG02),DISP=SHRThis DD statement is required only when you are doing RPTYPE=CONFIG. It may also be used with RPTYPE=EXCEPTION. If the configuration data set is a PDS, member name can be omitted if the MEMBER= operand is specified on the PRINT statement.

USTFILEI DD Statement

Specifies the FILEINFO repository file. For example,

//USTFILEI DD DSN=UPSTREAM.FILEINFO.$UST.CLUSTER,DISP=SHRThis DD statement is required only when you are doing RPTYPE=BACKUP, VAULT, or CUSTOM (if backup fields are included in the REPORT fields).

USTCSV DD and USTPUNCH DD Statements

Either DD statement may be used to specify the data set name of the optional CSV output file for RPTYPE=BACKUP reporting. For example:

SYSIN DD Statement

Specifies the control statement data set. Usually a “DD *” data set or control card PDS member.

USTRPORT Batch Examples

This section shows several example reports that could be created with USTRPORT. Example output is also shown.

“Recent Activity” Report

This report, using RPTYPE=HISTORY, shows all UPSTREAM activity in the past 7 days.

//USTRPORT EXEC PGM=USTRPORT,REGION=0M
//STEPLIB DD DISP=SHR,DSN=upstream.loadlib
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//USTCATLG DD DISP=SHR,DSN=upstream.ustcatlg.file
//SYSIN DD *
 TITLE LINE='XYZ CORPORATION - RECENT FDR/UPSTREAM ACTIVITY'
 SELECT DAYS<7
 PRINT RPTYPE=HISTORY
/*"Recent Activity” Report

“Heavy Afternoon Activity” Report

This report, also using RPTYPE=HISTORY, shows all UPSTREAM backups of more than 5MB that have taken place in the afternoon. This may be done, for example, with a view to shifting those larger backups to an “off-peak” schedule.

“Heavy Afternoon Activity” Report

 “Incomplete Backups” Report

The example shows a customized report using RPTYPE=CUSTOM. It shows any backups that did not complete normally and it has been customized with the REPORT statement to show only selected fields.

“Incomplete Backups” Report

This general backup report, using RPTYPE=BACKUP has been customized to report on only backup profiles starting with “FIN”. The report contains most of the information from the RPTYPE=HISTORY report, but it only selects backup operations (not restores, file inquiries, etc) and it also includes the data set name and disk/tape volume serial(s) where the corresponding backup file currently resides. The optional USTPUNCH DD statement is included for generation of a CSV format file.

“Backup Report”

“Backup and Files” Report

This next report is an expanded example of the preceding report. The BKFILES=* has been added to the SELECT statement to request the display of all the individual Client files contained in each backup. The DEFAULT FULLNAME statement has also been added to request the display of the full path for each file.

//USTRPORT EXEC PGM=USTRPORT,REGION=0M
//STEPLIB DD DISP=SHR,DSN=upstream.loadlib
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//USTCATLG DD DISP=SHR,DSN=upstream.ustcatlg.file
//USTFILEI DD DISP=SHR,DSN=upstream.ustfilei.file
//SYSIN DD *
 TITLE LINE='XYZ CORPORATION - FINANCE DEPARTMENT BACKUPS'
 DEFAULT FULLNAME
 SELECT PROFILE=FIN*,BKFILES=*
 PRINT RPTYPE=BACKUP
/*“Backup and Files” Report

“Exception” Report

The Exception Report is useful for identifying the most recent unsuccessful backup (condition code greater than 4) for a profile, within the exception period, as defined by the Days select operand. A successful backup within the exception period, would result in the profile's exclusion from the Exception report. Additionally, if the USTCONFG DD statement is provided, profiles that have never had a backup or profiles that no longer exist are also excluded from the Exception report. The date and the number of days of the most recent successful backup, (within the specification for MAXHIST) and the date of the most recent unsuccessful backup attempt (if any) within the exception period are listed.

//USTRPORT EXEC PGM=USTRPORT,REGION=0M
//STEPLIB DD DISP=SHR,DSN=your.upstream.loadlib
//SYSPRINT DD SYSOUT=*
//USTCATLG DD DISP=SHR,DSN=your.upstream.ustcatlg.file
//USTFILEI DD DISP=SHR,DSN=your.upstream.ustfilei.file
//USTCONFG DD DISP=SHR,DSN=your.upstream.config.file
//SYSIN DD *
 EXCLUDE PROFILE=SUSELINX
 SELECT OPERNAME=BACKUP,DAYS<=9999
 PRINT RPTYPE=EXCEPTION
/*“Exception” Report

“Configuration” Report

As well as reporting on UPSTREAM activity, such as backups and restores, you can also use USTRPORT to display information about the UPSTREAM configuration data set. In this next report, we are displaying the contents of the CONFIG02 configuration member, but we have asked to see only the details of backup profiles beginning with “FIN”.

//USTRPORT EXEC PGM=USTRPORT,REGION=0M
//STEPLIB DD DISP=SHR,DSN=your.upstream.loadlib
//SYSPRINT DD SYSOUT=*
//USTCONFG DD DISP=SHR,DSN=your.upstream.configuration.file
//SYSIN DD *
 TITLE LINE='XYZ CORPORATION - FINANCE DEPARTMENT PROFILES'
 SELECT PROFILE=FIN*
 PRINT RPTYPE=CONFIG,MEMBER=CONFIG02
/*“Configuration” Report

Initiation via the TSO/ISPF Dialog

As an alternative to running USTRPORT batch jobs, you can also report on UPSTREAM activity through the TSO/ISPF dialog. Select option 7 (“Report”) and press ENTER.

UPSTREAM TSO/ISPF Dialog

You need to enter the name of the UPSTREAM configuration data set and member name, as well as the catalog (USTCATLG) and fileinfo (USTFILEI) repository data sets, all of which are specified in the UPSTREAM startup PROC. Once entered, these values are retained each time you return to this screen. Note the use of the quotes to avoid name resolution interference with your TSO/E profile prefix setting. In our example below, by entering an “*” on the profile name field and “backup” in the report type field, we have requested a display of all backups for all profiles.

UPSTREAM Report