Running CATSYNC for specified data sets

The catalog synchronization (CATSYNC) option, DATASETS, allows users to run catalog synchronization for only the data sets with names that match a specified pattern. This prevents catalog synchronization from making updates to Output Manager tables when a catalog is offline or an alias has been deleted. The DATASETS option can also be used to force the update or deletion of Output Manager metadata, even when no data sets matching a pattern are found in the catalog.

The DATASETS keyword is a safeguard against catalogs being offline. Include a DATASETS keyword for each alias or multi-level alias that is used for Output Manager data sets. Output Manager will write suggested DATASETS commands to the sysout CHANGES DDNAME. After running Output Manager, check this DD and add these commands to the SYSIN DD in the Cat Sync JCL.

The DATASETS option uses the following syntax:

DATASETS (match pattern) [FORCE]

Where:

(match pattern) is the pattern against which to match the data set names. When an archive data set name matches the specified pattern, CATSYNC is performed on it. The pattern must end in **, and must have no other wildcards. For example:
DATASETS **
Would match all data sets and is the equivalent of omitting all of the DATASETS parameters. If the pattern is "**", it is equivalent to specifying a DATASETS HLQ.** for each HLQ mentioned in the database. This statement is useful when your system has only single level aliases. However, if you have a multilevel catalog alias environment, this statement will not prevent updates to Output Manager tables in the case of an offline catalog or deleted alias. To determine the alias level of your environment, you can issue the following MVS™ command:
```
F CATALOG,REPORT
```
DATASETS BJT.**

Would match all data sets with the high-level qualifier "BJT", and CATSYNC would be performed for all data sets beginning with BJT. This statement is useful when "BJT" is an alias.

DATASETS BJT.ABC.**

Would match all data sets with the high-level qualifier "BJT" and the second level qualifier of "ABC". CATSYNC would be performed for only the data sets beginning with "BJT.ABC". This statement is useful when "BJT.ABC" is an alias.
FORCE is an optional parameter that indicates whether to force updates to the Output Manager database, when no data sets matching the pattern are found.
- When FORCE is omitted: If no data sets matching the pattern are found in the catalog, no changes are made to the database for that matched pattern. The archive rows are preserved.
  If the most-specific DATASETS pattern does not match any data sets in the catalog, but does match some database archive and related table rows, the matching database archive and related table rows are not deleted. If these rows are not deleted, a return code 8 warning message is written to the SYSPRINT. This message includes information on what happened and how to re-run to delete those database rows.
- When FORCE is specified: Depending on whether or not the archive data sets exist in a user catalog, FORCE determines what is done to the database rows.
  - If there are no archive data sets in the user catalog, the database rows are updated.
  - If there are archive data sets in the user catalog, the job ends with a return code 4. Warning messages are written to the SYSPRINT and a SYSOUT DDNAME CHANGES is dynamically allocated. CHANGES includes information on what should be added to the SYSIN DD.
  Note: FORCE is optional, and because it intentionally avoids an important check, it is not recommended. The use of FORCE is only recommended for users who are very familiar with their archive attribute mask patterns, and who have backed up their production system database.
  If you do not expect any data sets to exist in the catalog for a DATASETS archive attribute mask, and you want to update the Output Manager tables accordingly (by deleting rows relating to the mask), then FORCE is the appropriate action. It is highly recommended to follow the steps listed in Catalog synchronization best practices before using the FORCE parameter.

The DATASETS option can be omitted, specified once, or specified multiple times. Omitting the DATASETS option is the equivalent of specifying DATASETS ** and CATSYNC will match all data sets.

When ALLOW_DELETE or ALLOW_UPDATE = YES is specified and CATSYNC is performed, the Output Manager database rows that relate to the archive data sets that matched the matched DATASETS pattern when "dsn" is not found in the catalog are deleted or updated to 'G' (Gone).

Important: It is highly recommended to make the changes suggested in the CHANGES DD output. If the archive data sets that exist in the Output Manager tables are tied to a multi-level alias catalog environment, and a CATSYNC job that had previously completed with an RC=0 now results in an RC=4, you must make the recommended changes to the SYSIN DD in the JCL to prevent data loss in the event that a catalog was offline or a catalog alias had been accidentally deleted.

If an Output Manager database row refers to a data set name ("dsn") that is not matched by any of the DATASETS match patterns, a warning message containing a suggested DATASETS pattern is printed, and a return code 4 is returned.