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.

Job 1 belongs to SMART folder G and has RBC A. ACTIVE_FROM is not defined for Job 1.

ACTIVE_TILL is defined for Job 1 for October 1, 2016. The relationship between Job 1 and its RBCs is AND.

Result: Job 1 is obsolete.

Job 2 belongs to SMART folder G and has RBC B.

ACTIVE_FROM and ACTIVE_TILL are not defined.

The relationship between Job 2 and its RBCs is OR.

Result: Job 2 is active.

Job 3 belongs to SMART folder G and has RBCs A, B, and C.

RBC C was deleted from SMART folder G, but Job 4 still has it.

ACTIVE_FROM and ACTIVE_TILL are not defined.

The relationship between Job 3 and its RBCs is AND.

Result: Job 3 is active, while RBC C is ignored.

The following may be applicable to the features described in this section:

  • The sweep utility searches for obsolete jobs and folders on the Control-M/EM side only. It does this by scanning the Control-M/EM database. Any obsolete jobs or folders that are found are deleted from both the Control-M/EM and the Control-M/Server databases. It is therefore recommended that the folders are synchronized in the Control-M/EM and Control-M/Server databases before activating the sweep utility.

  • To delete obsolete folders or jobs a user requires FULL permissions for the specific folder.