IMS Catalog Record Purge utility (DFS3PU10)

If ACBMGMT=CATALOG is specified in the DFSDFxxx member of the PROCLIB data set, IMS also automatically removes from the IMS directory the DBDs and PSBs that are removed from the IMS catalog. If ACBMGMT=CATALOG is not specified in the DFSDFxxx member, use the MANAGEDACBS statement to enable the utility to remove from the IMS directory the DBDs and PSBs that are removed from the IMS catalog. When ACBs are removed from the IMS directory, the ACBs are also removed from the IMS directory staging data set.

The utility performs three basic functions, analysis, purge, and update, which can be run independently or sequentially in a single execution of the utility. Use the MODE control statement to select the analysis function, the purge function, or both. Use the UPDATE control statement to set or modify the retention criteria of DBD and PSB records in the IMS catalog.

The analysis function of the utility evaluates the records in the IMS catalog by reading the user-defined retention criteria to identify DBD and PSB instances that are eligible for deletion. When the DELDBVER statement is specified, the utility identifies all instances of the specified DBD version as eligible for deletion. The utility creates a report and DELETE statements for each DBD or PSB instance that can be deleted.

The purge function of the utility deletes the DBD and PSB instances by processing the DELETE statements without checking the retention criteria. You can add to or edit the DELETE statements to remove DBD and PSB instances that would not otherwise be eligible for deletion. You can code DELDBVER statements to remove all instances of a specified DBD version.

The update function of the utility sets or modifies the retention criteria in the header segment of individual DBD and PSB records. The retention criteria in a header segment overrides any default retention criteria that is specified the DFSDFxxx member of the IMS PROCLIB data set. If the update and analysis functions are requested at the same time, the utility performs the updates before performing the analysis.

The DFS3PU10 utility issues a CHKP (checkpoint) call to commit updates to the IMS catalog after every 200 updates, and message DFS4518I is issued in the utility output.

The DFS3PU10 utility can run in a DL/I or DBB region or a BMP region.

Restrictions

No restrictions are documented for this utility.

Prerequisites

No prerequisites are documented for this utility.

Requirements

The DFS3PU10 utility requires access to the IMS.PROCLIB data set that contains the DFSDFxxx member that enables the IMS catalog and defines the default retention criteria for the records in the IMS catalog.

If you run the DFS3PU10 utility in a DLI region and the IMS catalog is shared, you must specify IRLM support in the EXEC parameters of the utility JCL.

Recommendations

First, run the utility to obtain the list of DBD and PSB instances that can be deleted based on the retention criteria in effect for each DBD and PSB record. Then, examine the list to ensure that no DBD or PSB instances are included that are still needed by your IMS applications. Finally, run the utility to purge the unneeded DBD or PSB instances.

Input and output

The DFS3PU10 utility accepts the following input:

• The analysis and update functions read control statements from the SYSIN DD statement.
• The purge function reads control statements from the SYSUT1 data set.
• The analysis function reads the records in the IMS catalog.
• Both functions read from the CATALOG section of the DFSDFxxx member of the IMS.PROCLIB data set.

JCL specifications

EXEC statement

The DFSDF= parameter specifies the three-character suffix of your DFSDFxxx member in the IMS.PROCLIB data set.

//BATCH EXEC PGM=DFSRRC00,
// PARM=(DLI,DFS3PU10,DFSCP001,,,,,,,,,,,Y,N,,,,,,,,,,,,'DFSDF=xxx')

PARM=(DLI,DFS3PU10,DFSCP001,,,,,,,,,,,Y,Y,irlmid,,,,,,,,,,,'DFSDF=xxx')

PARM=(BMP,DFS3PU10,DFSCP001,,,,,,,,,,,imsid,,,,,,)

DD statements

STEPLIB DD

Points to IMS.SDFSRESL, which contains the IMS nucleus and required IMS modules. If STEPLIB is unauthorized by having unauthorized libraries that are concatenated to IMS.SDFSRESL, you must include a DFSRESLB DD statement.

DFSRESLB DD

Points to an authorized library that contains the IMS SVC modules. For IMS batch, SDFSRESL and any data set that is concatenated to it on the DFSRESLB DD statement must be authorized through the Authorized Program Facility (APF). This DD statement provides an authorized library for the IMS SVC modules, which must be in an authorized library. The JOBLIB or STEPLIB statement does not need to be authorized for IMS batch.

PROCLIB DD

Defines the IMS.PROCLIB data set that contains the DFSDFxxx member that defines the default retention criteria for the records in the IMS catalog.

IMS DD

Defines the IMS.PSBLIB and IMS.DBDLIB data sets.

IEFRDER DD

Defines the primary IMS log data set.

DFSVSAMP

Defines the buffer pool parameters data set.

SYSPRINT

If the utility is run with MODE ANALYSIS specified, the SYSPRINT data set contains a list of the names and timestamps of the DBD and PSB and PSB instances that are eligible for deletion based on the retention criteria that is currently in effect. If the utility is run with MODE PURGE or MODE BOTH specified, the SYSPRINT data set contains a list of the DBD and PSB instances that were deleted. The DCB parameters for the SYSPRINT data set are RECFM=FBA and LRECL=121, but you do not have to specify these parameters.

SYSIN

A physical sequential data set that contains the utility control statements that are read by the analysis, purge, and update functions of the DFS3PU10 utility. The DCB parameters for the SYSIN data set are RECFM=FB and LRECL=80, but you do not have to specify these parameters.

SYSUT1

A physical sequential data set that contains the DELETE control statements, DELDBVER control statements, or both that are read by the purge function of the utility. The analysis function of the utility writes DELETE statements to the SYSUT1 data set.

Except when MODE BOTH is specified, you can edit the contents of the SYSUT1 data set to modify the generated DELETE statements or to add DELETE statements and DELDBVER statements.

The DCB parameters for the SYSUT1 data set are RECFM=FB and LRECL=80, but you do not have to specify these parameters.

SYSIN control statements

MODE statement

Specifies whether the utility executes the analysis function, the purge function, or both. The MODE statement can be specified only once.

ANALYSIS

Based on the retention criteria that is in effect for each record and any DELDBVER statements that are included as input, the utility generates DELETE statements for the DBD and PSB instances that are eligible for deletion. Nothing is deleted from the IMS catalog.

The retention criteria that are set in the HEADER segment of each catalog record is used to determine eligibility for deletion. If the HEADER segment of a record does not contain any retention criteria, the utility uses the retention criteria from the CATALOG section of the DFSDFxxx member of the IMS.PROCLIB data set.

The DELETE statements are written to the SYSUT1 data set, overwriting any existing contents. After the analysis is complete, you can review and, if necessary, edit the DELETE statements.

You can submit UPDATE statements with this mode. The UPDATE statements are processed before the utility examines the catalog HEADER information.

PURGE

The utility reads the DELETE statements in the SYSUT1 data set and purges the matching DBD and PSB instances from the database.

UPDATE statements are not allowed with this mode.

BOTH

The utility runs in ANALYSIS mode, determines which record instances are no longer needed according to the current retention criteria, and then runs in PURGE mode to remove the identified record instances.

You can submit UPDATE statements with this mode. The UPDATE statements are processed before the utility takes any other action.

DELDBVER statement

Deletes all instances of the specified version of a DBD. When DELDBVER is specified, MODE ANALYSIS or MODE BOTH must also be specified.

When MODE ANALYSIS is specified, the DELDBVER statement generates DELETE statements in the SYSUT1 data set for all of the DBD instances of the specified version number of a DBD, regardless of the retention criteria. The DBD instances that are proposed for deletion are also listed in the SYSPRINT data set.

When MODE BOTH is specified, the DELDBVER statement deletes all instances of the specified DBD version. The deleted DBD instances are listed in the SYSPRINT data set.

When MODE PURGE is specified, the DELDBVER statement cannot be specified in the SYSIN data set.

The DELDBVER statement can also be specified in the SYSUT1 data set. For more information, see SYSUT1 control statements.

The following diagram shows the syntax of the DELDBVER statement.

You can specify the following parameters on the DELDBVER statement:

member-name

The 8-character name of the DBD that you are deleting a version from.

version-number

The version number of the DBD that you are deleting. The value must match the version number that is specified on the DBVER keyword in the DBD generation statement of the version that you are deleting.

UPDATE statements

Use this statement to set the retention criteria for records in the catalog database. This information is stored in the HEADER segment of the relevant catalog record.

You can submit any number of UPDATE statements. If a MODE statement is specified with one or more UPDATE statements, the UPDATE statements are processed first.

If one or more UPDATE statements are specified without a MODE statement, the utility does not write DELETE statements to the SYSUT1 data set or delete any DBD or PSB instances.

When MODE PURGE is specified, the UPDATE statement cannot be specified in the SYSIN data set.

UPDATE DBD|PSB

Specify DBD or PSB. You can specify multiple UPDATE statements in the utility input.

member-name

The IMS resource name. These names are 8 characters, and wildcards are supported in the following formats:

• You can update the retention criteria for all DBD or PSB resources by specifying only the wildcard operator (*)
• You can update the retention criteria for DBD or PSB records that match a prefix value by specifying the prefix and then the wildcard operator (ABC*)

Updates are processed in alphanumeric order. Later updates override earlier ones. For example, if the following UPDATE statements are submitted:

UPDATE DBD DB* 1 365
UPDATE DBD * 1 20
UPDATE DBD DBOHIDK5 10 813

And your IMS catalog database contains records for the following resources:

DBD CUSTDB
DBD DB1XYZ
DBD DB2XYZ
DBD DB3XYZ
DBD DBOHIDK5
DBD DBVHDJ05
DBD EMHDB1

The utility processes the universal wildcard update first, assigning all DBD records the retention values of VERSIONS=1 and DAYS=20. Then it processes the statement for DB*, assigning all records with the DB prefix the retention values of VERSIONS=1 and DAYS=365. Finally, it processes the statement for DBOHIDK5, assigning that specific resource the retention values of VERSIONS=10 and DAYS=813. The later updates override the earlier updates.

instances

The number of instances of a DBD or PSB that must be retained in the DBD or PSB record.

For DBD instances, if database versioning is used, this value is the number of instances of the DBD that must be retained for each version of the DBD.

If this parameter is set to 1, any DBD or PSB instance other than the most recent instance is eligible for deletion.

If the number of instances in the record or the DBD version is less than this value, no instances are eligible for deletion.

If the number of instances in the record or the DBD version exceeds this value, the oldest instances are eligible for deletion, but only if they are older than the days value, if it is set.

This value is stored in the RETNINST field of the HEADER segment in DBD and PSB records.

days

The number of days that an instance of a DBD or PSB must be retained before it can be purged from the DBD or PSB record. Only DBD and PSB instances older than this number of days are eligible for deletion.

If this parameter is omitted or set to 0 for a DBD or PSB record, the age of the DBD or PSB instances is not used as a retention criterion. This value is stored in the RETNDAYS field of the HEADER record segment.

Note: When a value greater than 0 is specified on the days parameter, a DBD or PSB instance is eligible for deletion only if all of the following criteria are met:

• The age of the instance is greater than the days value
• The number of instances in the record or the DBD version is greater than the instances value
• The timestamp of the instance is older than the timestamps of the instances that are retained to satisfy the instances value

For example, if the number of DBD or PSB instances in a record is less than the instances value, no instances are eligible for deletion, even if the age of one or more of the instances is greater than the days value. Similarly, if the number of instances in a record is greater than the instances value, but the age of each instance in the record is less than the days value, no instances are eligible for deletion.

MANAGEDACBS

Specifies whether deleting DBD and PSB instances from the IMS catalog causes the corresponding DBD and PSB instances in the IMS directory to be deleted.

The MANAGEDACBS statement can be specified according to the following syntax diagram:

UPDATE

Deletes from the IMS directory the DBD and PSB instances that are deleted from the IMS catalog. The MANAGEDACBS UPDATE statement is automatically generated if the IMS directory is active, that is, if ACBMGMT=CATALOG is specified in the <CATALOG> section of the effective DFSDFxxx PROCLIB member. If both the MANAGEDACBS UPDATE and MODE ANALYSIS statements are specified, DBD and PSB instances are not deleted from the IMS directory.

RESOURCE_CHKP_FREQ n

Specifies the number of resource instances to be deleted or updated between checkpoints. n can be a 1- to 8-digit numeric value ranging from 1 to 99999999. The default value is 200.

SYSUT1 control statements

The control statements in the SYSUT1 data set are used by the DFS3PU10 utility to delete DBD and PSB segment instances, DBD versions, or whole DBD or PSB records from an IMS catalog.

The analysis function of the DFS3PU10 utility generates control statements in the SYSUT1 data set, which can then be used as input to the purge function.

If you specify MODE ANALYSIS, you can add to or edit the generated control statements in SYSUT1 before executing the purge function. However, if you specify MODE BOTH, you cannot review or edit the control statements before the purge function processes the SYSUT1 data set and deletes the segments and records.

For processing when MODE PURGE is specified, you can code your own SYSUT1 data set or use the SYSUT1 data set that was produced by the analysis function in a previous execution of the utility.

The following control statements can be specified in the SYSUT1 data set.

DELDBVER statement

Deletes all DBD instances of the specified version of a DBD.

The following diagram shows the syntax of the DELDBVER statement.

You can specify the following parameters on the DELDBVER statement:

member-name

The eight-character name of the DBD from which you are deleting a version.

version-number

The version number of the DBD that you are deleting. The number that is specified here must match the version number that is specified on the DBVER keyword in the DBD generation statement of the version that you are deleting.

DELETE statements

Specifies a DBD or PSB instance or an entire DBD or PSB record to delete from the IMS catalog database.

Important: In a managed ACBs environment, active or pending directory members cannot be deleted when IMS is online if the utility is run as a BMP job.

The individual instances within each DBD or PSB record are differentiated by their DBD or PSB name and their ACB generation timestamps.

The analysis function of the utility automatically generates the DELETE statements based on the retention criteria that is currently in effect for each record and any DELDBVER statements in the SYSIN data set.

When MODE ANALYSIS is specified, you can review and edit the contents of the SYSUT1 data set before anything is deleted.

The eligibility of an instance for deletion is determined by the retention criteria that the utility reads from either the HEADER segment of a record or from the CATALOG section of the DFSDFxxx member of the IMS.PROCLIB data set.

During the purge mode, the utility does not check the retention criteria. If you manually code or edit the DELETE statements, you can remove DBD and PSB instances that would not otherwise be eligible for deletion.

The following syntax diagram shows the format of the DELETE statement:

DELETE DBD|PSB

You can delete either DBD or PSB resource record instances.

member-name

The IMS name of the DBD or PSB resource. These names are 8 characters, and wildcards are supported in the following formats:

• You can include all DBD or PSB resources by specifying only the wildcard operator (*).
• You can include DBD or PSB resources that match a prefix value by specifying the prefix and then the wildcard operator (ABC*).

timestamp

The ACB timestamp that identifies the specific DBD or PSB instance to purge.

The timestamp is in the following format: yydddhhmmssth.

Tip: You can specify a wildcard operator (*) to delete an entire DBD or PSB record, including the root segment and the header segments, from the IMS catalog.

Other usage information

If no retention criteria are stored in the RETNINST and RETNDAYS fields of the HEADER segment of a DBD or PSB record, the utility uses the DFSDFxxx member of the IMS.PROCLIB data set to determine the retention criteria.

If the RETNINST and RETNDAYS fields in the HEADER segment of the record both contain non-zero values, the utility does not use the values in the DFSDFxxx member to determine which DBD and PSB instances to purge. Instead, it uses the values from the RETNINST field (for the minimum number of instances) and the RETNDAYS field (for the minimum number of days) of the HEADER segment.

You might want to configure the DAYS parameter in the DFSDFxxx member to set a minimum number of days to retain catalog record instances, but selectively disable time-based retention for specific records. In that case, use this utility to explicitly specify a value of at least 1 for the number of instances and 0 for the number of days for those records.

For example, if the DFSDFxxx member contains the following retention information, no instances are eligible for deletion unless there are more than five instances in a record, and at least one of those instances is at least five days old.

RETENTION(INSTANCES=5,DAYS=5)

However, you can disable the time-based retention period for a subset of records in the IMS catalog by using the UPDATE statement of the DFS3PU10 utility to set the DAYS value to 0 directly in the HEADER segment of each record, as shown in the following example:

UPDATE DBD JK* 5 0

For each DBD record with the prefix JK, the preceding example sets RETNINST=5 and RETNDAYS=0. For these records, the IMS Catalog Record Purge utility does not consider age when determining eligibility for deletion. The utility generates DELETE statements for JK* DBD instances only if more than five instances are stored for in each JK* DBD record. The oldest record instances are removed first.

If no RETENTION values are specified in the CATALOG section of the DFSDFxxx member, the defaults are INSTANCES=2 and DAYS=0.

Example JCL

The following example of the utility JCL both updates the retention criteria and generates delete statements for all of the eligible DBD and PSB instances.

In the UPDATE phase of utility execution, the example JCL updates the retention settings for all PSB records and for the DBD records matching the prefix JK*.

In the ANALYSIS phase, the example JCL generates DELETE statements for all DBD and PSB instances that are eligible for deletion. The DELDBVER statement generates DELETE statements for all of the DBD instances of version 2 of the DBD JKDBA020. The utility writes the DELETE statements to the data set referenced by the SYSUT1 data set. You can then edit this data set or use it directly as SYSUT1 input to a separate run with MODE PURGE.

//BATCH EXEC PGM=DFSRRC00,
// PARM=(DLI,DFS3PU10,DFSCP001,,,,,,,,,,,Y,N,,,,,,,,,,,,'DFSDF=001')
//STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
//DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
//PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
//IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
//         DD  DSN=IMS.DBDLIB,DISP=SHR
//SYSUT1   DD  ...            DELETE statements
//IEFRDER  DD  ...            Log data set
//DFSVSAMP DD  ...            Buffer pool parameters
//SYSPRINT DD  SYSOUT=*       Analysis or purge report
//SYSIN DD *                  Control statements
MODE ANALYSIS 
UPDATE PSB * 5 365 
UPDATE DBD JK* 5 365 
DELDBVER JKDBA020 2 
RESOURCE_CHKP_FREQ 300

The following JCL shows how you can code DELETE and DELDBVER statements of your own to use as SYSUT1 input to a run with MODE PURGE.

//BATCH EXEC PGM=DFSRRC00,
// PARM=(DLI,DFS3PU10,DFSCP001,,,,,,,,,,,Y,N,,,,,,,,,,,,'DFSDF=001')
//STEPLIB  DD  DSN=IMS.SDFSRESL,DISP=SHR
//DFSRESLB DD  DSN=IMS.SDFSRESL,DISP=SHR
//PROCLIB  DD  DSN=IMS.PROCLIB,DISP=SHR
//IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
//         DD  DSN=IMS.DBDLIB,DISP=SHR
//IEFRDER  DD  ...            Log data set
//DFSVSAMP DD  ...            Buffer pool parameters
//SYSPRINT DD  SYSOUT=*       Analysis or purge report
//SYSIN DD *                  SYSIN control statements
 MODE PURGE
RESOURCE_CHKP_FREQ 300
/*
//SYSUT1   DD  *              SYSUT1 control statements
 DELETE DBD JKDBA600  1306514025679
 DELETE DBD  *       1300112161055
 DELETE PSB   *      1300112161055
 DELETE PSB  PSBJKE05    * 
 DELDBVER JKDBA020 2
/*

Return codes

The IMS Catalog Record Purge utility completes execution with one of the following return codes:

0

No errors or exceptional conditions.

4

Warnings only.

8

Errors in control statements.

12

Invalid combinations of control statements, as indicated by messages DFS4424E or DFS4433E.

20

An error occurred that generated one of the following messages

• DFS4420E
• DFS4421E
• DFS4422E
• DFS4423E
• DFS4427E
• DFS4485E

24

The SYSPRINT DD statement was missing or invalid.