ims_catalog_purge – Purge records from the IMS Catalog¶

Synopsis ¶

The IMS Catalog Purge utility DFS3PU10 removes the segments that represent a DBD or PSB instance, all instances of a DBD version, or an entire DBD or PSB record from the IMS catalog. You can also analyze the catalog and generate delete statements for ACBs eligible for deletion, as well as update the ACB retention criteria.

Determines which mode the utility runs in. ANALYSIS mode generates delete statements based on the retention criteria and places them in the SYSUT1 data set. PURGE mode executes delete statements in the SYSUT1 data set. BOTH mode performs ANALYSIS and PURGE mode consecutively.

required: True
type: str
choices: PURGE, BOTH, ANALYSIS

online_batch

Indicates if this utility is to be run in a BMP region.

required: False

type: bool

ims_id

The identifier of the IMS system on which the job is to be run.

Required if online_batch is true.

required: False

type: str

dbrc

Indicates if the IMS Database Recovery Control facility is enabled.

required: False

type: bool

irlm_id

The IRLM ID if IRLM is enabled. Cannot be specified when online_batch is true.

required: False

type: str

reslib

Points to an authorized library that contains the IMS SVC modules.

required: False
type: list
elements: str

buffer_pool_param_dataset

Defines the buffer pool parameters data set. This option is required if you are running the utility as a DLI.

required: False

type: str

dfsdf_member

The DFSDFxxx member in the IMS.PROCLIB data set where the CATALOG section is defined. For example, dfsdf_member is “CAT” specifies the DFSDFCAT member of the PROCLIB data set.

required: False

type: str

primary_log_dataset

Defines the primary IMS log data set. This option is required if you are running the utility as a DLI.

required: True

type: dict

dataset_name: Describes the name of the data set.

required: True

type: str
disposition: The status of the data set.

required: False

type: str

choices: NEW, OLD, SHR, EXCL
record_format: The record format.

required: False

type: str

choices: FB, VB, FBA, VBA, U
record_length: The logical record length in bytes.

required: False

type: int
block_size: The block size.

required: False

type: int
primary: The amount of primary space to allocate for the data set.

required: False

type: int
primary_unit: The unit of size to use when specifying primary space.

required: False

type: str
secondary: The amount of secondary space to allocate for the data set.

required: False

type: int
secondary_unit: The unit of size to use when specifying secondary space.

required: False

type: str
normal_disposition: Data set action after normal termination.

required: False

type: str

choices: DELETE, KEEP, CATLG, UNCATLG
abnormal_disposition: Data set action after abnormal termination.

required: False

type: str

choices: DELETE, KEEP, CATLG, UNCATLG
type: The type of data set.

required: False

type: str

choices: SEQ, BASIC, LARGE, PDS, PDSE, LIBRARY, LDS, RRDS, ESDS, KSDS
volumes: A list of volume serials. When providing multiple volumes, processing will begin with the first volume in the provided list. Offline volumes are not considered.

required: False

type: list

elements: str
storage_class: The storage class for an SMS-managed data set. Not valid for data sets that are not SMS-managed.

required: False

type: str
management_class: The management class for an SMS-managed data set. Not valid for data sets that are not SMS-managed.

required: False

type: str
data_class: The data class for an SMS-managed data set. Not valid for data sets that are not SMS-managed.

required: False

type: str

psb_lib

Defines the IMS.PSBLIB data set.

required: True
type: list
elements: str

dbd_lib

Defines the IMS.DBDLIB data sets.

required: True
type: list
elements: str

proclib

Defines the IMS.PROCLIB data set that contains the DFSDFxxx member. The DFSDFxxx member defines various attributes of the IMS catalog that are required by the utility.

required: True
type: list
elements: str

steplib

Points to IMS.SDFSRESL, which contains the IMS nucleus and required IMS modules.

The steplib parameter can also be specified in the target inventory’s environment_vars.

The steplib input parameter to the module will take precedence over the value specified in the environment_vars.

required: False
type: list
elements: str

delete_dbd_by_version

Delete DBD instances based on the specified name and version. If ANALYSIS mode is specified, it will generate DELETE DBD statements in the SYSUT1 data set along with any other delete statements based off the retention criteria. If PURGE or BOTH mode is specified, it will write the delete statements to the SYSUT1 data set and then execute them.

required: False
type: list
elements: dict

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

required: True

type: str
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.

required: True

type: int

update_retention_criteria

Use this statement to set the retention criteria for DBD or PSB records in the catalog database. You can submit any number of update statements. You cannot specify this option if PURGE mode is selected. If used with any other mode options, it will update the retention criteria first.

required: False
type: list
elements: dict

resource: Specifies whether a DBD or PSB should be updated.

required: True

type: str

choices: DBD, PSB
member_name: The 8 character IMS name of the DBD or PSB resource. Wildcards are supported.

required: True

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

required: True

type: int
days: The number of days that an instance of a DBD or PSB must be retained before it can be purged.

required: False

type: int

delete

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

This option must be used with PURGE mode and overrides any retention criteria, hence you can remove any DBD or PSB that would not otherwise be eligible for deletion.

required: False
type: list
elements: dict

resource: Specify whether you want to delete a DBD or PSB.

required: True

type: str

choices: DBD, PSB
member_name: The 8 character IMS name of the DBD or PSB resource. Wildcards are supported.

required: True

type: str
time_stamp: The ACB timestamp that identifies the specific DBD or PSB instance to purge.

required: True

type: int

managed_acbs

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. If ‘analysis_mode’ is true, the DBD and PSB instances will not be deleted from the IMS directory.

required: False

type: bool

resource_chkp_freq

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

required: False

type: int

sysut1

The data set where delete statements are written to. Written either by the purge utility when specifying ANALYSIS or BOTH mode, or by the user when specifying PURGE mode.

required: False

type: dict

dataset_name: Describes the name of the data set.

required: True

type: str
disposition: The status of the data set.

required: False

type: str

choices: NEW, OLD, SHR, EXCL
block_size: The block size.

required: False

type: int
primary: The amount of primary space to allocate for the data set.

required: False

type: int
primary_unit: The unit of size to use when specifying primary space.

required: False

type: str
secondary: The amount of secondary space to allocate for the data set.

required: False

type: int
secondary_unit: The unit of size to use when specifying secondary space.

required: False

type: str
normal_disposition: Data set action after normal termination.

required: False

type: str

choices: DELETE, KEEP, CATLG, UNCATLG
abnormal_disposition: Data set action after abnormal termination.

required: False

type: str

choices: DELETE, KEEP, CATLG, UNCATLG
type: The type of the data set.

required: False

type: str

choices: SEQ, BASIC, LARGE, PDS, PDSE, LIBRARY, LDS, RRDS, ESDS, KSDS
volumes: A list of volume serials. When providing multiple volumes, processing will begin with the first volume in the provided list. Offline volumes are not considered.

required: False

type: list

elements: str
storage_class: The storage class for an SMS-managed data set. Not valid for data sets that are not SMS-managed.

required: False

type: str
management_class: The management class for an SMS-managed data set. Not valid for data sets that are not SMS-managed.

required: False

type: str
data_class: The data class for an SMS-managed data set. Not valid for data sets that are not SMS-managed.

required: False

type: str

Examples ¶

- name: Purge the IMS Catalog of DBDs beginning with 'DB'
  ims_catalog_purge:
    reslib:
      - SOME.IMS.SDFSRESL
    steplib:
      - SOME.IMS.SDFSRESL
    proclib:
      - SOME.IMS.PROCLIB
    dbd_lib:
      - SOME.IMS.DBDLIB
    psb_lib:
      - SOME.IMS.PSBLIB
    buffer_pool_param_dataset: "SOME.IMS1.PROCLIB(DFSVSMHP)"
    dfsdf_member: "CAT"
    primary_log_dataset:
      dataset_name: SOME.IMS.LOG1
    mode: PURGE
    delete:
      - resource: DBD
        member_name: 'AUTODB'
        time_stamp: 500

- name: Purge the IMS Catalog and the IMS Directory of DBDs beginning with 'DB'
  ims_catalog_purge:
    reslib:
      - SOME.IMS.SDFSRESL
    steplib:
      - SOME.IMS.SDFSRESL
    proclib:
      - SOME.IMS.PROCLIB
    dbd_lib:
      - SOME.IMS.DBDLIB
    psb_lib:
      - SOME.IMS.PSBLIB
    buffer_pool_param_dataset: "SOME.IMS1.PROCLIB(DFSVSMHP)"
    dfsdf_member: "CAT"
    primary_log_dataset:
      dataset_name: SOME.IMS.LOG1
    mode: PURGE
    delete:
      - resource: DBD
        member_name: AUTODB
        time_stamp: 500
    managed_acbs: true

- name: Analyze the IMS Catalog and generate delete statements for resources eligible for deletion
  ims_catalog_purge:
    reslib:
      - SOME.IMS.SDFSRESL
    steplib:
      - SOME.IMS.SDFSRESL
    proclib:
      - SOME.IMS.PROCLIB
    dbd_lib:
      - SOME.IMS.DBDLIB
    psb_lib:
      - SOME.IMS.PSBLIB
    buffer_pool_param_dataset: "SOME.IMS1.PROCLIB(DFSVSMHP)"
    dfsdf_member: "CAT"
    primary_log_dataset:
      dataset_name: SOME.IMS.LOG1
    mode: ANALYSIS

- name: Update resource retention criteria for resources in the IMS Catalog while running as BMP
  ims_catalog_purge:
    online_batch: True
    ims_id: IMS1
    reslib:
      - SOME.IMS.SDFSRESL
    steplib:
      - SOME.IMS.SDFSRESL
    proclib:
      - SOME.IMS.PROCLIB
    dbd_lib:
      - SOME.IMS.DBDLIB
    psb_lib:
      - SOME.IMS.PSBLIB
    buffer_pool_param_dataset: "SOME.IMS1.PROCLIB(DFSVSMHP)"
    dfsdf_member: "CAT"
    primary_log_dataset:
      dataset_name: SOME.IMS.LOG1
    mode: ANALYSIS
    update_retention_criteria:
      - resource: DBD
        member_name: AUTODB
        instances: 0
        days: 0
      - resource: PSB
        member_name: DBF000
        instances: 0
        days: 0

Notes ¶

Note

The steplib parameter can also be specified in the target inventory’s environment_vars.

The steplib input parameter to the module will take precedence over the value specified in the environment_vars.

If only the steplib parameter is specified, then only the steplib concatenation will be used to resolve the IMS RESLIB data set.

Specifying only reslib without steplib is not supported.

Return Values ¶

content: The standard output returned running the IMS Catalog Purge utility.

returned: always

type: str

sample: DFS4810I ALL OF THE MEMBER INSTANCES THAT ARE REFERENCED IN THE SYSUT1 DATA SET WERE DELETED FROM THE IMS CATALOG.
rc: The return code from the IMS Catalog Purge utility.

returned: sometimes

type: str

sample: 0
stderr: The standard error output returned from running the IMS Catalog Purge utility.

returned: sometimes

type: str

sample: 12.27.08 STC00143 +DFS671I OMVSADM8.STEP1. - FOR THIS EXECUTION, DBRC IS SET TO NO IMS1
msg: Messages returned from the IMS Catalog Purge module.

returned: sometimes

type: str

sample: You must specify a buffer pool parameter data set when running as DLI.

ims_catalog_purge – Purge records from the IMS Catalog¶

Synopsis¶

Parameters¶

Examples¶

Notes¶

Return Values¶

Synopsis ¶

Parameters ¶

Examples ¶

Notes ¶

Return Values ¶