collect_garbage

Collects unreferenced workspace objects and places them in a WASTE BASKET folder in the Home folder of the user. Datasets, envelopes, folders, items, and forms objects can be collected. Released objects are not collected A special case operation is the orphan option that collects item revisions that do not have valid parent items. These items revisions may be referenced in other folders, in which case you are warned while collection is taking place. Orphan operations should not be combined with other operations. The collect_garbage utility should be run in two phases. The first phase is run without the -delete option, which allows objects to be collected in the WASTE BASKET folder. This allows you to examine the contents of the waste basket. Once you are satisfied with the contents, the collect_garbage can be rerun with the -delete option to empty the WASTE BASKET folder. When working with large databases, use the -query argument to create a report of all unreferenced objects. You can restrict the report to specific object types with various arguments. When working with a large report, you can split the report into separate files that can be executed in batches. Use the -rf and -if arguments to define the file to which you want to write the report. The batch jobs can then be executed simultaneously on multiple workstations. Use the -delete argument to delete the unreferenced objects from the specified folder. Syntax collect_garbage [-u=user-id {-p=password | -pf=password-file} -g=group] -rf=report-file-name -if=input-file-name [-dataset] [-item] [-occurrence] [-absoccdataqualifier] [-form] [-folder] [-envelope] [-all] [-orphan] [-delete] [-report] [-query] [-dataset] [-child_references] [-ignore_relation] [-gsidentity] [-plmappuid=ReportOnly | ReportAndDelete] [-start=number] [-end=number] [-h] Caution You must run Teamcenter Workspace with system administration privileges to access the WASTE BASKET folder. Arguments -u Specifies the user ID. This is a user with Teamcenter administration privileges. Note If Security Services single sign-on (SSO) is enabled for your server, the -u and -p arguments are authenticated externally through SSO rather than being authenticated against the Teamcenter database. If you do not supply these arguments, the utility attempts to join an existing SSO session. If no session is found, you are prompted to enter a user ID and password. -p Specifies the password. This argument is mutually exclusive with the -pf argument. -pf Specifies the password file. For more information about managing password files, see Manage password files. This argument is mutually exclusive with the -p argument. -g Specifies the group associated with the user. If used without a value, the user's default group is assumed. -dataset Specifies that datasets be collected or deleted. -item Specifies that items be collected or deleted. Note This argument also collects all item revisions associated with the item. -occurrence Specifies that occurrences (appearance path nodes, absolute occurrences, and occurrence threads) are collected. -absoccdataqualifier Collects or deletes locally owned unreferenced, and locally owned referenced, absolute occurrence data qualifier (AbsOccDataQualifier) objects associated with replica BOM view revisions (BVRs). -form Specifies that forms be collected or deleted. -folder Specifies that object folders be collected or deleted. -envelope Specifies that envelopes be collected or deleted. -all Collects or deletes datasets, items, forms, object folders, and envelopes. This argument does not include orphans. Siemens Digital Industries Software does not recommend using this argument when processing a large database. -orphan Collects or deletes all item revisions that do not have a valid parent item. These item revisions may be referenced in other folders, in which case you are warned while collection is taking place. Use the -orphan argument alone to collect orphan item revisions in the WASTE BASKET folder. Use the -delete argument in conjunction with the -orphan argument to delete orphans from the WASTE BASKET folder. Orphan operations should not be combined with other operations. See restriction #2. Note Because orphan operations collect or delete item revisions that do not have valid parent items, it is normal for the collect_garbage application log file to include some errors. In most cases, you can disregard them. -delete Deletes all objects of a specified type. One or more of the -dataset, -item, -form, -folder, or -envelope arguments or the -all or -orphan arguments must be supplied. You can also include the -gsidentity option with the -delete argument. -query Queries the database for the instances of the specified object type when used in combination with a defined object type. Note This argument works only in combination with an object type argument (-item, -dataset, -form, -envelope, -folder, -all) and the -rf argument. -report Creates a report of the objects moved to the WASTE BASKET folder of the user. Note The -report argument generates output in a different format than the -orphan operations because orphan objects are not valid workspace objects. -gsidentity Locates and removes all invalid GSIdentity records for objects that do not exist. -plmappuid Deletes unreferenced entries from the plmappuid table. When objects are imported into Teamcenter using PLM XML, an Application Ref tag can be used to define individual IDs for the imported objects. The IDs are stored in the plmappuid table. If these objects are later deleted in Teamcenter, the entries are not deleted from the table. Over time the table size increases, decreasing performance. Use the ReportOnly value to generate a count of all the unreferenced entries in the plmappuid table. Use the ReportAndDelete value to generate a count of all the unreferenced entries in the table and delete them. -rf= report-file-name Creates a report file listing instances of a specified type. This argument may be used in combination with object type arguments (-item, -dataset, -form, -envelope, -folder, -orphan) and the -query argument. When used in combination with object type arguments, the -rfargument retrieves a list of all instances of a specified class and writes the list to a specified file. Note This argument works only in combination with an object type argument (-item, -dataset, -form, -envelope, -folder, -all) and the -if argument. A file name is required when using this argument. If a file name is not provided, the list is written to a default file named argument-name_report.txt, where argument name is equal to item, dataset, form, folder, envelope, or orphan. If the default file already exists in the directory where this utility is executed, instances are overwritten to the default file. When the report is large, Siemens Digital Industries Software recommends that it be split into multiple reports. The suggested naming convention is argument-name_report_aa.txt, argument-name_report_ab.txt, and so on. -if= input-file-name Uses the report file name as input to identify the unreferenced objects of a given object type. Unreferenced objects are placed in a specified subfolder within the Waste Basket folder. Note This argument works only in combination with an object type argument (-item, -dataset, -form, -envelope, -folder, -all) and the -if argument. If no value is specified for this argument, the utility exits with a message. -start Specifies the starting number of objects to process. The default value is 1. Use this option in conjunction with the -end option. The -start and -end arguments are recommended when the utility runs out of memory when loading too many objects of the given class for processing. -end Specifies the ending number of objects to process. Use this option in conjunction with the -start option. -dataset Specifies that datasets qualify as garbage for collection. -child_references Specifies that datasets qualify as garbage if they are unreferenced in the system but have secondary objects. Use with the -dataset option. -ignore_relation Specifies that datasets are excluded from garbage collection if they have at least one secondary object attached with any of the relations in the list. The valid value for this argument is a comma-separated list containing internal relation names. Use with the -dataset option. -h Displays help for this utility. Environment As specified in Setting up a Teamcenter command-line environment. Files As specified in Log files produced by Teamcenter. Restrictions The collect_garbage utility must be run by a user with Teamcenter administration privileges. This automatically enables the bypass feature and collects and deletes all garbage objects regardless of owning user and group. Do not use the -orphan argument with an object type argument -dataset, -item, -form, -folder, -envelope or -all. Examples The following examples illustrate how to use the -query argument with this utility: The following example displays a message and exits the program because no file name was provided for the -rf argument: Copy collect_garbage -u=Tc-admin-user -p=password -g=group -item -rf -query The following example collects a list of unreferenced objects of the type item and writes the report to the list_items.txt file: Copy collect_garbage -u=Tc-admin-user -p=password -g=group -item -rf=list_items.txt -query The following example collects a list of unreferenced objects of type item and writes the report to the item_report.txt file: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -query To collect unreferenced folders, enter the following command on a single line: Copy collect_garbage -folder To collect unreferenced folders and items, enter the following command on a single line: Copy collect_garbage -folder -item To collect unreferenced folders and items and get a report to stdout, enter the following command on a single line: Copy collect_garbage -folder -item -report To collect all unreferenced objects except orphans, enter the following command on a single line: Copy collect_garbage -all To delete folders collected in the WASTE BASKET folder, enter the following command on a single line: Copy collect_garbage -folder -delete To delete all objects collected in the WASTE BASKET folder except orphans, enter the following command on a single line: Copy collect_garbage -all -delete To collect all item revisions with no parent item, enter the following command on a single line: Copy collect_garbage -orphan To delete orphan item revisions in the WASTE BASKET, enter the following command on a single line: Copy collect_garbage -orphan -delete To collect unreferenced items into the item_rep file, enter the following command on a single line: Copy collect_garbage -item -query -rf=item_rep To process these items and insert into folder, enter the following command on a single line: Copy collect_garbage -item -report -if=item_rep To delete items in the SUB WASTE BASKET folder, enter the following command on a single line: Copy collect_garbage -item -delete -sub_folder=WBITEM_item_rep To collect unreferenced forms when there are too many forms in the database to load in memory, enter the following command on a single line: Copy collect_garbage -form -end=1000 collect_garbage -form -delete collect_garbage -form -end=1000 collect_garbage -form -delete Or Copy collect_garbage -form -start=1 -end=1000 collect_garbage -form -start=1001 -end=2000 collect_garbage -form -delete To delete unreferenced occurrence threads, appearance path nodes, and absolute occurrences, enter the following command on a single line: Copy collect_garbage -occurrence -delete To collect all locally owned referenced, and locally owned unreferenced AabsOccDataQualfier objects and place them in the respective BadAbsOccFolder and BadAbsOccFolder_unrefdirectory folders: Copy collect_garbage -absoccdataqualifier -query -sub_folder= Copy BadAbsOccFolder To delete all locally owned unreferenced AbsOccDataQualifier objects: Copy collect_garbage -absoccdataqualifier -delete To delete all locally owned referenced AbsOccDataQualifier objects: Copy collect_garbage -absoccdataqualifier -delete -sub_folder= Copy BadAbsOccFolder When working with a large database, or with a large number of instances in a report file, Siemens Digital Industries Software recommends that you split the query report into multiple files. The following examples illustrate how to split a report into specified files: The following example splits 50,000 instances reported from a query into files of 5,000 lines each: Copy split -l 5000 item_rep.txt ITEM_rep_ The following example processes each instance from the report and identifies unreferenced objects. These objects are placed in a subfolder of the WASTE BASKET folder: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -if=list_items.txt The following example processes each instance from the report and identifies unreferenced objects. These objects are placed in a subfolder of the WASTE BASKET folder. It also displays the object information, such as object name, ID, object type and owner's name. Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -if=list_items.txt -report The following example retrieves all unreferenced objects of type item and places them in the WASTE BASKET folder: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item The following example retrieves all unreferenced objects of type item and places them in the WASTE BASKET folder. It also displays object information, such as object name, ID, object type, and owner's name. Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -report The following examples illustrate how to use the -delete argument to delete unreferenced objects: The following example deletes all objects in the WBITEM_item_rep.txt subfolder within the WASTE BASKET folder. Copy collect_garbage -item -delete -sub_folder=WBITEM_item_rep.txt The following example deletes all unreferenced instances of type item in the WASTE BASKET folder, as well as all instances from any subfolders with names beginning with WBITEM_: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -delete The following example displays a message and exits the program because no subfolder value is specified: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -sub_folder= The following example deletes all objects of type folder, but does not delete the contents of the folder object. (The same concept is true for other object types, such as item, dataset, form, and envelope.) Copy collect_garbage -u=admin-user -p=admin-password -g=dba -folder -delete The following example deletes all GSIdentity records from the database: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -gsidentity -delete -rf=report-file-name The following examples illustrate how to use the-rf argument: The following example displays a message and exits the program because no file name is provided for the -rf argument: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -rf -query The following example collects a list of unreleased objects of type item and writes them to the list_items.txt file: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -rf=list_items.txt -query The following example collects a list of unreleased objects of type item and writes them to the item_report.txt file: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -query The following example generates a list of objects for the following types: item, dataset, form, envelope, and folder. The list is placed in the following files, respectively: item_report.txt, dataset_report.txt, form_report.txt, envelope_report.txt, and folder_report.txt. Copy collect_garbage -all -query The following examples illustrate how to use the -if argument: The following example displays a message and exits the program because no value was provided for the -if argument: Copy collect_garbage -item -if= The following example checks each entry in the item_report_aa file. A folder named WBITEM_item_report_aa is created within the WASTE BASKET folder and all unreferenced objects are placed within this folder. Copy collect_garbage -item -if=item_report_aa The following example checks each entry in the given list and identifies unreferenced objects. A subfolder is created within the WASTE BASKET folder and all unreferenced objects are placed within this subfolder. It also displays object information, such as object name, ID, object type and owner's name. Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -if=list_items.txt -report The following examples illustrate how to use the -sub_folder argument: The following example deletes the objects of type dataset within the WBDSET_dataset_report1 folder within the WASTE BASKET folder. Copy collect_garbage -dataset -sub_folder=WBDSET_dataset_report1 -delete The following example deletes all instances of type dataset within the WASTE BASKET folder and all instances in the subfolder named WBDSET_file-name: Copy collect_garbage -dataset -delete This section illustrates how to use the -query argument. The following example compiles a list of objects of type item that are not released and writes the list to the list_items.txt file: Copy collect_garbage -u=admin-user -p=admin-password -g=dba -item -rf=list_items.txt -query The following example shows how to use the -dataset, -child_references, and -ignore_relation arguments. In the example, all unreferenced datasets that have secondary objects are collected as garbage, except those that have any of the secondary object attached with the IMAN_Rendering or IMAN_specification relationship. Copy collect_garbage -u=admin-user -p= -g=dba -dataset -query -rf=report.txt -child_references -ignore_relation=IMAN_Rendering,IMAN_specification Important Notes The -report option for orphan operations outputs in a different format than for other object types, because orphans are not valid workspace objects. The -item option collects the associated item revisions along with the item. Errors are reported in the logfile when running in orphan collection mode. The error reported indicates that an error attempting to load an indirected object. These errors can be disregarded. Related Topics Introduction to administering volumes