sweep

The sweep utility deletes jobs that are no longer active from the Control-M/EM and Control-M/Server databases. These jobs are referred to as obsolete jobs and are defined in Obsolete criteria (see below).The sweep utility is available in Control-M/EM installations only.

For reports that are generated by the sweep utility, see Utility Reports.

For return codes, see Return Codes.

To see the criteria used by the sweep utility to determine whether a job or folder is obsolete, see Obsolete Criteria.

Running the Sweep Utility

This procedure describes the sweep utility, which deletes jobs that are no longer active from the Control-M/EM and Control-M/Server databases.

Begin

1. Do one of the following:

   • UNIX: Log in to a Control-M/EM account.

   • Windows: Open a command prompt window where Control-M/EM is installed. You do not need to be in the Control-M/EM database directory.

2. Type the following command:

   • UNIX:

     em sweep [-U <userName> -P <password> | -PF <passwordFile>] -S <serverName> [-Local] [-Date <YYYYMMDD>] [-Test | -Sync] [-Timeout <maxSeconds>] [-Cyclic <maxFiles>] [-H | -Help] [-Force] [-Interval <milliseconds>]

     The parameters are described in the following table. The flags are not case sensitive.

   • Windows:

     sweep [-U <userName> -P <password> | -PF <passwordFile>]
     

     -S <serverName> [-Local] [-Date <YYYYMMDD>]
     

     [-Test | -Sync] [-Timeout <maxSeconds>]
     

     [-Cyclic <maxFiles>] [-H | -Help] [-Force]
     

     [-Interval <milliseconds>]

3. Press Enter.

   The parameters are processed and several reports are generated.

   Avoid updating of the job or folder definitions when the sweep utility is running.

sweep Utility Parameters

The following table describes the sweep parameters:

Parameter	Description
-U userName	Defines the Control-M/EM owner database user name Log in is achieved by providing either a user name and password combination or a password file name.
-P password	Defines the Control-M/EM owner database user password
-PF passwordFile	Defines a flat file that contains an unencrypted user name and password on separate lines in the following format: user=user_name password=password
-S serverName	Defines a logical name for the Control-M/EM GUI server.
-Local	Deletes all obsolete jobs and folders from the Control-M/EM database only. You cannot use the -Sync and -Test flags when using -Local. You can use -Local and -Force to delete obsolete jobs and folders from modified or locked folders in the Control-M/EM database. Log sweep_sync.txt is not updated when the utility is activated with -Local. If -Local is not used, the sweep utility deletes jobs from both the Control-M/EM and Control-M/Server databases.
-Date YYYYMMDD date	Determines a date in YYYYMMDD format which sets the selection criteria for obsolete jobs. Default: two days before the current date 20210915
-Timeout maxSeconds	Determines the maximum time in seconds to wait for pending callbacks to return with responses to UPLOAD and remote DELETE requests. Default: 900 seconds (15 minutes).
-Test	Causes the sweep utility to scan all job definitions and generate the sweep_obsolete.txt file, which consists of a report of the current obsolete jobs and folders, without actually deleting the jobs.
-Sync	Synchronizes all non-synchronized folders, listed in the sweep_sync.txt file, by rerunning the commands that previously failed, in order to synchronize the Control-M and EM databases.
-Cyclic maxFiles	Determines the maximum number of cyclic files for sweep execution log (up to 500 messages each). Default: The execution log is written to one sequential log file without a timestamp.
-H | -Help	Displays the usage.
-Force	Causes the sweep utility to scan all folders, including those that are modified or locked, for obsolete jobs. Use -Force only when you are certain there are no definitions in the Control-M/Server database that were not previously downloaded into the Control-M/EM database.
-Interval milliseconds	Sets the time to wait between executing the DELETE and UPLOAD commands (in milliseconds). It may be required to avoid time-out problems in Gateway or Control-M. By default, there is no interval.

Utility Reports

The reports that are generated by the sweep utility are described in the following table:

File Name	Location	Description
sweep_obsolete.txt	$HOME/sweep	Reports all jobs and folders that are candidates for deletion according to the date criteria.
sweep_sync.txt	$HOME/sweep	Reports all folders that could not be uploaded to or deleted from the Control-M/Server (either because of a failure or a time-out) and therefore are not currently synchronized.
sweep_log.txt	$HOME/log	Lists the Execution log which is cyclic and configurable.

In the sweep_obsolete.txt file, the report for obsolete jobs has the following format:

delete job folder_id job_id ctm_name folder_name job_name mem_name

In the sweep_obsolete.txt file, the report for obsolete folders has the following format:

delete folder folder_id ctm_name folder_name folder_lib

The MaxObsoleteJobs system parameter controls the size of the GUI Server memory by limiting the number of obsolete jobs stored in the GUI Server. The default value is 100000.This parameter should only be changed after consulting with BMC Customer Support.

In the sweep_sync.txt file, the report for non-synchronized folders has the following format:

upload folder folder_id ctm_name folder_name folder_lib

Only the last versions of the sweep_obsolete.txt and sweep_sync.txt reports are saved.

sweep Utility Work Flow Example

The following example describes typical work flow for the sweep utility:

• Activate the sweep utility with the –Test parameter to generate the sweep_obsolete.txt file, which is essentially a report listing the obsolete jobs and folders.

• Check the sweep_obsolete.txt file and decide if you want to delete the jobs and folders displayed in the report.

• Activate the sweep utility without the –Test parameter to delete the obsolete jobs and folders from the Control-M/EM and Control-M/Server databases.

• Check the sweep_sync.txt file to find failures that occurred while the sweep utility was attempting to upload or delete folders.

• Check the sweep_log.txt file to understand the reason for the failures and perform the necessary corrections.

• Activate the sweep utility with the –Sync parameter to upload or delete the folders that were not successfully uploaded or deleted in the previous run.

• Check the sweep_sync.txt file to check that there are no more failures.

Prepare a Report of Obsolete Jobs Example

The following command specifies that the sweep_obsolete.txt file, containing a list of obsolete jobs, is generated according to the obsolete date of September 15, 2021:

sweep.exe -U emuser -P empass -S TLVW2K366 -Test -Date 20210915

Delete Obsolete Jobs from the Database Example

The following command specifies that any job from two days ago is considered obsolete and is being deleted from the database:

sweep.exe -U emuser -P empass -S TLVW2K366

Return Codes

The following table describes Sweep utility return codes:

Return Code	Description
0	Success (all of the obsolete jobs were deleted, however there may be commands in the sync file that must be run later). If necessary, run the sweep utility again.
1	Failure. Run the sweep utility again.
2	Partial success (some obsolete jobs were not deleted). Run the sweep utility again to delete the remaining jobs or folders.

Obsolete Criteria

The following describes the criteria used by the sweep utility to determine whether a job or folder is obsolete.

If the ACTIVE_TILL parameter is specified the following elements are considered as obsolete:

• A regular job, which is not part of a SMART folder, is considered as obsolete if the following is true:

  ACTIVE_FROM < ACTIVE_TILL and ACTIVE_TILL < obsolete date.

• A RBC is considered as obsolete if:

  ACTIVE_FROM < ACTIVE_TILL and ACTIVE_TILL < obsolete date.

• A SMART folder is considered as obsolete if:

  All of its RBCs are obsolete (the relationship between the RBCs is always OR).

• A regular folder is considered obsolete if:

  All the jobs in the folder are obsolete.

• A job that is part of a SMART folder is defined as obsolete if one of the following conditions is true:

  • the SMART folder is obsolete

  • it satisfies the obsolete criteria according to its own ACTIVE_TILL/ACTIVE_FROM and has no RBCs

  • it has RBCs and is considered as obsolete according to the following table:

  Relationship	Job (ACTIVE_TILL/ ACTIVE_FROM)	RBC (ACTIVE_TILL/ ACTIVE_FROM)	Result
  AND	Obsolete	Obsolete	Delete job
  AND	Obsolete	Active	Delete job
  AND	Active	Obsolete	Delete job
  AND	Active	Active	Job is active
  OR	Obsolete	Obsolete	Delete job
  OR	Obsolete	Active	Job is active
  OR	Active	Obsolete	Job is active
  OR	Active	Active	Job is active
  AND	Not defined	Obsolete	Delete job
  AND	Not defined	Active	Job is active
  OR	Not defined	Obsolete	Job is active
  OR	Not defined	Active	Job is active

Obsolete Criteria Examples

This following are examples of how the sweep utility applies the obsolete criteria to determine whether various jobs are obsolete.

The following values apply to all examples in this section:

• SMART folder G has the following two RBCs:

  • RBC A: ACTIVE_FROM Not defined; ACTIVE_TILL September 12, 2021

  • RBC B: ACTIVE_FROM September 11, 2018; ACTIVE_TILL October 28, 2021

• The obsolete day of the user is September 20, 2021.

  For the obsolete day of the user, RBC A is obsolete and RBC B is active, according to the above.