Expanded Retention Option

Review this topic to learn about Expanded Retention Option (ERO) table statements, assigning SYSOUT IDs based on embedded text, tape consolidation of reports (SARPAC), SARPAC reports, and running SARPAC.
Review this topic to learn about Expanded Retention Option (ERO) table statements, assigning SYSOUT IDs based on embedded text, tape consolidation of reports (SARPAC), SARPAC reports, and running SARPAC.
The initialization parameters NGEND and NGENT specify how many generations of each SYSOUT remain on disk and tape.
The ERO allows you to specify particular SYSOUTs as having expanded retention. These SYSOUTs can be given separate retention criteria.
When a SYSOUT has expanded retention, you can specify how long to keep the SYSOUT in the database (the retention period) by the number of generations to be kept, the number of copies to be kept, or the number of days the SYSOUT is to remain on the database. By appropriately setting your NGEND and NGENT parameters, then assigning selected SYSOUT to have expanded retention, you can set up a minimum archival retention period for all SYSOUT, and then selectively archive desired SYSOUT for longer periods.
The ERO gives you the added flexibility of assigning, at archival time, SYSOUT IDs based on text strings found within the SYSOUT (PTEXT
The SARPAC utility is part of the ERO. SARPAC consolidates backup tapes, copying only current reports to new tapes.
Define and Use ERO
A report user can use the Expanded Retention Option (ERO) to provide additional retention capabilities for specific reports or groups of reports. Implementing ERO involves the configuration of the ERO initialization parameters and the creation of an ERO table.
ERO provides the flexibility to specify report retention options at the individual report level. This lets you match report retention to your business needs and Records Management policies.
The base
product allows retention based on database generations. A report may be retained in the database for a specified number of generations and on a backup tape for specified number of generations. The Expanded Retention Option allows for more flexibility in assigning retentions to individual reports.
Follow these steps:
Define Expanded Retention Option (ERO)
You can define the retention options using the ERO table and the following SARINIT initialization parameters.
Follow these steps:
Set the following SARINIT parameters.
    Specifies whether the ERO option is being used.
    • NEW
      Indicates to
      that only newly archived reports must be evaluated for Expanded Retention. Reports from older generations which are controlled by standard retention are not considered.
    • YES
      Indicates that all reports controlled by standard retention, either new or old, must be evaluated for Expanded Retention. If the name of the report matches an entry in the ERO table, the retention is switched to ERO control. The parameter is not reset to NEW at the end of the backup cycle.
    • ALL
      Indicates that all reports controlled by standard retention, either new or old, must be evaluated for Expanded Retention. If the name of the report matches an entry in the ERO table, the retention is switched to ERO control. This is reset to NEW at the end of the backup cycle.
    We recommend that EROPRO be set to YES and left that way unless a large percentage of the database is under standard retention.
The EROPRO parameter settings do not control when a report is removed from ERO control. Once a report has been defined to ERO, it remains under ERO control until its total ERO retention has expired. If you change a report's retention in the ERO table, the next standard backup cycle applies that retention to all past versions of that report - not just the new versions. If you remove a report entry from the ERO table, the system searches for a more generic match and uses the retention specified in that entry. If a more generic match cannot be found, the system defaults to using PCOPIES. The important thing to remember is that once a report is switched to ERO control it stays under ERO control until its ERO retention has expired.
Controls what happens to a report after its total ERO retention has expired. It controls whether a report must switch back to standard retention or be deleted.
  • INIT
    INIT indicates that the report is to switch back to standard retention unless the ERO table entry for this report contains the DELETE parameter. When the DELETE parameter is not specified, the report is kept until it exceeds the NGENT/NGEND specification, then it is deleted.
    Indicates that the report is to be deleted.
We recommend setting PRETAIN=TABLE
Use the ERO table
You can use the ERO table to perform the following three functions:
  • Override the standard report retention specified in NGENT and NGEND.
  • Assign reports to a STORGRP so they are backed up with other reports in the same STORGRP.
  • Specify when reports are to be migrated to secondary storage (OPTICAL or CENTERA) and assign a retention for the report copies residing on those devices.
SYSOUTs are given expanded retention status with entries in what is referred to as the 
expanded retention table
, or ERO table.
Follow these steps:
  1. Define expanded retention table entries to
    using the SARPATAB DD statement in the
    started task JCL, and in the SARDSK2B batch job for optical migration.
  2. Use wildcards in the expanded retention table statements. You can specify wildcards at any location in the SYSOUT ID. ABC* and AB*C*D are valid SYSOUT ID entries in the table.
    All SYSOUT IDs that contain a particular character string are identified.
The terms expanded retention and permanent status are synonymous.
The Expanded Retention Option (ERO) of
uses a table to provide additional retention capabilities for specific reports or groups of reports. The base
product only allows retention based on database generations. A report can be retained in the database for x generations (NGEND initialization parameter) and on a backup tape for y generations (NGENT initialization parameter). Without ERO, all reports have the same retention.
Specify Retention Parameters
ERO provides additional retention options based on generations, days, and copies.
Specify the following ERO retention parameters:
    Displays the date the report was archived.
    Refers to the number of versions that you wish to keep.
  • GENS
    Displays the generation number when the report was created. This is the number that
    assigns to all reports archived between standard backup cycles. If you specify GENS=2 and you archived the report in GEN 100, it will be scratched after GEN 101 has completed its standard backup.
     If no ERO retention parameter is specified (RETPD, COPIES, or GENS), the INIT PARM PCOPIES is used as the default.
Control statements specify the retention parameters in a sequential file that is accessible by the backup task through the SARPATAB DD statement. The control statements specify the reports that receive these retention options. The report name can be all 32 significant characters, or from 0 to 31 characters followed by the wildcard character, the asterisk (*).
If the payroll register must be kept on the database for 30 days and on tape for 3 years, add a control statement to the ERO table as follows:
If you have to keep all other payroll reports for only one year, add the following control statement to the ERO table:
The backup cycle searches the ERO table from the top to the bottom using the report name as a search argument. The first entry that matches the most significant characters (and the wildcard character if present) is used to obtain the report's retention options.
Special considerations apply if this table is sorted, the '/PAY*' statement would appear in the file ahead of the '/PAYREG' statement, and the payroll register report would obtain the same retention options as the other payroll reports.
If a '/* ALL …' default report retention statement was in the sorted file, it sorts as the first statement in the ERO table, and all reports would then obtain retention options from the first entry in the table.
To prevent this type of sequence error from occurring,
validates the order of the ERO table before every backup cycle. When you change the ERO table, we recommend you run the SARVERO utility to validate the ERO table and prevent problems during the next
backup cycle.
Define ERO Table Statements
ERO table statements are made up of SYSOUT IDs (including wildcards), parameters, and the values you set for those parameters.
Expanded retention table entries are input to the
started task using the SARPATAB DD statement.
The following example shows the keywords that can be specified in the ERO table statements:
  {ALL|MARK|LAST}             RETPD=nnnnn  GENS=nnnnn  COPIES=nnnnn              DRETPD=nnnnn DGENS=nnnnn DCOPIES=nnnnn             IRETPD=nnnnn LRETPD=nnnnn             STORGRP=storage-group-name             DSK2DAYS=nnnnn             DSK2NOTP             D2RETPD=nnnnn             REGDAYS=nnnnn             VIEWTAPE={YES|NO}             XCOND={YES|NO}             EXCLUDE             DELETE
Follow these steps:
  1. Specify a selection parameter of ALL, LAST, or MARK, in each statement.
    If the ALL, LAST, or MARK parameter is not specified, the initialization parameter POPT is used as a default. We recommend that you specify MARK, ALL, or LAST in each statement, to understand and verify the effects of the statements in your expanded retention table.
    • ALL
      Specifies that all reports for the SYSOUT ID from the current generation are evaluated for ERO processing.
    • LAST
      Specifies that the last (most recent) report from the current generation is evaluated for ERO processing.
    • MARK
      Specifies that all reports for the SYSOUT ID for the current generation are evaluated for ERO processing, only if marked manually.
     If you use one parameter, do not use the other two parameters. For example, if ALL is specified, MARK and LAST must not be specified.
  2. Specify ERO tape or disk retention (COPIES, RETPD, or GENS).
    If no parameter is specified, then the initialization parameter PCOPIES is used as the default.
  3. Specify the amount of retention in days with the DRETPD parameter for disk and RETPD parameter for tape. 
    The report is retained for 
    days. Specifying the DRETPD parameter is the most efficient processing method, because
    can use a simple arithmetic calculation on the archival date.
    We recommend that you use only one tape retention parameter per entry; however, if you use more than one parameter, each parameter must be satisfied before a SYSOUT no longer has expanded retention (PERM) status.
  4. Optionally code any of the following parameters to further define your ERO table content:
    • IRETPD=nnnnn
      Specifies the number of days (0 to 32767) that any page indexes defined for the reports are retained on disk.
      Specifies the tape storage group for SYSOUT. These group names can be unique for your location; they are linked to STORGRP1 through STORGRP9.
    • DSK2DAYS
      Specifies the number of days (1 to 998) a report remains on the primary disk before it is migrated to the secondary disk is specified.
    • DSK2NOTP
      Specifies that the report resides on optical disk and the tape backup is deleted.
    • D2RETPD=nnnnn
      Specifies the number of days that a report is retained on optical or secondary disk (valid values are 0 to 32767).
      D2RETPD is intended to be specified with DRETPD to provide separate retention for optical or secondary disk and primary disk.
      If D2RETPD is not specified, DCOPIES, DGENS, and DRETPD governs the optical or secondary disk retention and the report is deleted from primary disk after it is migrated.
    • REGDAYS=nnnnn
      Controls the number of days that a report cannot be deleted in
      . When the parameter is used in the ERO table, matching reports are flagged as non-deletable until a calculated REGDAYS date has been reached. (Valid values are 0 to 32767).
      The REGDAYS date is calculated by adding REGDAYS to the report ARCHIVE date.After a REGDAYS date is assigned to a report, it can only be extended and never shortened through changes in the ERO table.
      The SARBCH /CHANGE ARCHDATE function fails with a message if the target report is under REGDAYS control.
      Specifies that the SYSOUT can be viewed through the Expanded Access Server (SAREAS) if it only resides on tape.
    • XCOND
      Specifies whether
      is to consider SYSOUTs that had exceptional conditions, for example, JCL errors, ABENDS, and so on, for ERO evaluation is specified.
      Specifies that ERO does not retain the reports. These reports are retained in the database, based on the NGEND and NGENT initialization parameters.
    • DELETE
      Specifies that when the ERO retention TOTAL criteria expire, the report is deleted (and does not revert to the control of the
      initialization parameters NGENT).
    • The data set referred to in the SARPATAB DD statement in the SARSTC JCL contains the ERO table. This data set can be either a sequential file or a member of a partitioned data set. The data set attributes must be Fixed or Fixed Blocked with a Logical Record Length from 80 to 256 characters in length. Code the slash in column 1 followed immediately by the SYSOUT ID.
    • One or more blanks must follow the SYSOUT ID and separate it from the ERO table parameters.
    • Parameters are separated by one or more blanks and/or commas, and can be specified in any order.
    • A statement that exceeds the Logical Record Length minus 8 characters must be continued on additional statements. The last eight columns of each logical record are reserved for statement numbering. When continuing a statement, interrupt the statement between complete parameters only, and omit the slash on the continuation statement.
    • An asterisk in column 1 indicates a comment line.
ERO Table Examples
The following examples show initialization parameters and ERO table entries and the effects on reports within the
Example 1
This example shows you how to keep:
  • Two generations of all
    reports on disk, and three on tape.
    If a value for the NGENI parameter is not specified NGENT also governs master index backups.
  • Reports beginning with the characters ABC on tape for 90 days; however, you are limited to 30 days on disk.
Set the following initialization parameters:
Specify the following ERO table:
Example 2
This example shows you how to keep:
  • All reports beginning with ABCD on disk for 7 days and on tape for one year.
  • Reports beginning with ABC on disk for 7 days and on tape for 90 days.
Set the following initialization parameters:
ERO uses the first match that it finds. If these entries were in reverse order, an error message (SARPAR08) is generated at the start of the backup.
Assign SYSOUT IDs Based on Embedded Text
You can have ERO assign SYSOUT IDs based on text within a report. For example, you can give compilation listings of a production program a SYSOUT ID that is the name of the program.
Follow these steps:
  1. Specify a text string to be found in the report.
    When the string is found, the preceding or following characters are extracted by ERO and assigned to the report as the SYSOUT ID. The text comprising that string must all be on one line of the report.
  2. Define up to five separate text strings, which you specify as initialization parameters PTEXT1 through PTEXT5.
  3. Prefix the PTEXT text string with a plus or minus sign to indicate if the SYSOUT ID is to be the characters to the right of the PTEXT (specified with +) or to the left (specified with - ). The default is plus.
  4. Specify a series of text strings separated by periods, referred to as segmented text strings. If segmented text is specified:
    • Enclose each text segment in single quotation marks.
    • Each PTEXT specification can be 40 characters, including the periods that separate the segmented text strings.
    • Quotation marks that enclose the text string are not included in the 40 characters.
  5. Use double quotation marks as the delimiter, to search for a period or a single quotation mark.
reports have a fixed report ID. You cannot use PTEXTn to change the SYSOUT ID for a
Consolidate Reports in Tapes (SARPAC)
The SARPAC tape consolidation utility is provided with ERO to consolidate backup tapes. SARPAC copies current reports (retained by
) and bypasses expired reports. The first
backup cycle (standard or interim) following a SARPAC consolidation uncatalogs the input tapes that are no longer needed.
SARPAC produces three reports:
  • The first report lists the status of all tapes in the database, and can help you determine which tapes need to be consolidated.
  • The second report lists the copied SYSOUT groups when SARPAC actually performs the consolidation.
  • The third report is created only if the SARDRLST DD statement is in the SARPAC JCL.
You can use storage groups to put reports with the same retention on the same tape, thereby minimizing the need for consolidation.
Follow these steps:
  1. Specify the ERO initialization parameters PTHRESH, PMXTAPES, and PMXYEARS to control which tapes are consolidated by SARPAC.
  2. Use the SYSIN statements to specify which tapes to use for input. Additionally, you can modify the SARPACUX user exit to select input tapes based on user-defined criteria.
    SARPAC mounts its input tapes directly. SARPAC does not use the expanded access server for tape and robotics to mount input tapes.
  3. (Optional) Code the keyword REPORT.
    The tape status report is only produced and no actual tape consolidation is performed.
You can execute SARPAC by setting initialization parameters, consolidating the tape storage group, and consolidating one tape for a tape storage group.
It is not necessary to stop the SARSTC archival task to run the SARPAC utility. Consolidation can occur concurrently with report archival and the
backup cycle.
Follow these steps:
  1. Execute SARPAC. Locate the sample execution JCL in member HAEXPAC in your CVDEJCL data set.
    The job control statements, JOB, EXEC, STEPLIB DD, SARDRLST DD, SYSPRINT DD, SYSIN DD, SORTLIB DD, SYSOUT DD, and SORTWKnn DD are required to execute SARPAC.
  2. Consolidate Tape Storage Groups.
    If you use tape storage groups, we recommend that you consolidate one tape storage group at a time. Include the following SYSIN control statement to decrease the number of tape mounts:
  3. Stop SARPAC.
    If you must terminate SARPAC before it has completed processing, you can use an MVS STOP command to cause SARPAC to terminate normally. SARPAC acknowledges the STOP command with the following message:
    SARPAC99 Operator issued STOP command - PROCESSING TERMINATED
  4. Cancel SARPAC.
    If you have a tape management system and you cancel SARPAC, it is possible for your tape management system to override the
    tape retention criteria. We recommend that you always let SARPAC run to completion.
    If you must cancel SARPAC, any output tapes it created must be excluded from a scratch and clean run because
    still controls those tapes. This exclusion applies to primary, duplex, and DR tapes. You can run the SARTCHK utility to determine if any tapes were un-cataloged that are required by
You must run a standard or interim backup cycle to assign reports to tape storage groups. Storage groups are only for reports residing on the
database since the last backup cycle.