Canceling background tasks from a CLI

Background tasks that are in a Status of RUNNING can be canceled using a Command Line Interface (CLI). This is typically done during ZDT ("Zero Down-Time") deployments to ensure that no tasks are running before database updates are performed.

When canceling background tasks using a CLI, you can cancel tasks for specific configuration or for specific tenants in the Multi-Tenant Cloud (MTC).

Canceling tasks for a specific configuration

When canceling RUNNING background tasks for a specific configuration, use this syntax: 

ConfigManager.exe -U:CONFIG -mode:utensil -utensil:CancelBgTasks -name:configName

where configName is the name of the configuration that is being updated.

Canceling tasks for a specific tenant

When canceling RUNNING background tasks for a specific MTC tenant, use this syntax: 

ConfigManager.exe -U:CONFIG -mode:batchutensil -application_dbsource:dbServerName 
-application_dbname:tenantDbName -utensil:CancelBgTasks

where:

  • dbServerName is the name of the server that hosts the tenant database.
  • tenantDbName is the name of the tenant database.
Example 1
This example updates the version of a configuration to MAINT and cancels all RUNNING background tasks for a configuration named MyConfig: 
ConfigManager.exe -U:CONFIG -mode:edit -name:MyConfig -version:MAINT -cancelbgtasks
Example 2
This updates a the version of a configuration to MAINT and also cancels all RUNNING background tasks for a tenant database named MyTenantDB hosted on a server named MyDBServer: 
ConfigManager.exe -U:CONFIG -mode:batchedit -application_dbsource:MyDBServer 
-application_dbname:MyTenantDB -version:MAINT -cancelbgtasks

Viewing the count of background task types for a configuration

After using a command to cancel RUNNING background tasks, it is a good idea to verify that those tasks have actually canceled and stopped running before proceeding with any other action. This can be done by getting a report of the count of each type of task currently on the target configuration or tenant. The BGTaskReport utility generates this report. Before proceeding with another action, you would want to verify that the count of RUNNING tasks is 0 (zero).

To view a count of each type of task for a specific configuration, use this syntax: 

ConfigManager.exe -U:CONFIG -mode:report -name:BGTaskReport -config:configName

where configName is the name of the configuration to check.

This is an example of the output from this report: 

Parent process: cmd, Current process: ConfigManager, Need Console: True
Attached Console for process id: 29908, name: cmd
CreateNoWindow = False
Running in console mode ......
Output Redirection ......False
Using StreamWriter
Utility : CONFIG
Generating BGTask Count Report:
ConfigName: Mongoose2209
WAITING    2
PROCESS    1
READY      1
RUNNING    0
CANCEL     0
End using StreamWriter
Enter Key Pressed from Output not redirected!

You can also view the count of task types in JSON format, using this syntax: 

ConfigManager.exe -U:CONFIG -mode:report -name:BGTaskReport -config:configName -json

This is an example of the output in JSON format: 

{"Results":[{"ConfigName":"configName","TaskStatusCode":"WAITING","Count":2},
{"ConfigName":"configName","TaskStatusCode":"PROCESS","Count":1},
{"ConfigName":"configName","TaskStatusCode":"READY","Count":1},
{"ConfigName":"configName","TaskStatusCode":"RUNNING","Count":0},
{"ConfigName":"configName","TaskStatusCode":"CANCEL","Count":0}]}
Related topics