%SYS.BackgroundTask

abstract persistent class %SYS.BackgroundTask extends %Library.Persistent

SQL Table Name: %SYS.BackgroundTask

This class implements a framework for providing administrators with status and control of long-running tasks/utilities/operations that set to run in the background. These are typically (but not necessarily) tasks that are started interactively, but run in the background because they may run for a long time (e.g. some database management utilities). Note that this framework is separate from the "Task Manager" frameword which can be used to schedule activity.

There are subclasses for each type of operation that uses this infrastructure and objects of those subclasses represent instances that are running or have run since the system started up.

To use this framework for progress and control of a background task, you simply open or query objects the objects through this class or the relevant subclass. The properties represent a snapshot of the state and progress of the task. You can periodically check for changes by rerunning the query or reloading the object via standard object interfaces %OpenId() and %Reload().

RunningState contains information about whether the task is running or not (as of the time the object was last loaded or queried). Progress information may be available via ProgressCurrent, ProgressTotal and ProgressUnits. When complete, the %Status is available in FinalStatus. Subclasses may expose other properties that are germain to that particular type of operation.

Pause(), Resume(), and Cancel() are enabled for some subclasses

Users should not modify properties or save these objects.

To start a job running the task in the background, you can use class method Start() in the desired subclass. The arguments are unique to each subclass. Start() returns an oref to use for monitor and control.

Property Inventory

• CancelIsAvailable
• Class
• DisplayType
• FinalStatus
• HasEnded
• Namespace
• PID
• PauseIsAvailable
• ProgressCurrent
• ProgressTotal
• ProgressUnits
• Request
• ResumeIsAvailable
• RunningState
• StartTime

Method Inventory

• Cancel()
• Pause()
• Resume()
• Start()

Parameters

parameter CANCELDISPOSITION = 0;

Disposition for cancel requests.

0 - not allowed
1 - polls for cancel requests
-1 - directly terminate the process

parameter DOMAIN = %Utility;

parameter PAUSEDISPOSITION = 0;

Disposition for pause requests.

0 - not allowed
1 - polls for pause requests
-1 - directly pause the process

Properties

property CancelIsAvailable as %Integer [ Calculated ];

True if cancel is allowed for this task and the state (as of load time) is such that it can be paused. Used by user interface code to determine whether to enable a "cancel" control.

Property methods: CancelIsAvailableCompute(), CancelIsAvailableDisplayToLogical(), CancelIsAvailableGet(), CancelIsAvailableIsValid(), CancelIsAvailableLogicalToDisplay(), CancelIsAvailableNormalize(), CancelIsAvailableSQLCompute()

property Class as %String [ Calculated ];

The subclass name of the task; accessible via SQL where oref.%ClassName(1) is not be available.

Property methods: ClassCompute(), ClassDisplayToLogical(), ClassGet(), ClassIsValid(), ClassLogicalToDisplay(), ClassLogicalToOdbc(), ClassNormalize(), ClassSQLCompute()

property DisplayType as %String [ Calculated ];

A text string to display as the type of background task as defined by its subclass.

Property methods: DisplayTypeCompute(), DisplayTypeDisplayToLogical(), DisplayTypeGet(), DisplayTypeIsValid(), DisplayTypeLogicalToDisplay(), DisplayTypeLogicalToOdbc(), DisplayTypeNormalize(), DisplayTypeSQLCompute()

property FinalStatus as %Status [ ReadOnly ];

Status code when finished

Property methods: FinalStatusGet(), FinalStatusGetStored(), FinalStatusIsValid(), FinalStatusLogicalToOdbc()

property HasEnded as %Boolean [ Calculated ];

True if the RunningState is one that will not progress any further. Used by monitoring interfaces to determine whether monitoring should continue.

Property methods: HasEndedCompute(), HasEndedDisplayToLogical(), HasEndedGet(), HasEndedIsValid(), HasEndedLogicalToDisplay(), HasEndedNormalize(), HasEndedSQLCompute()

property Namespace as %String [ ReadOnly ];

Namespace in which the task is run.

Property methods: NamespaceDisplayToLogical(), NamespaceGet(), NamespaceGetStored(), NamespaceIsValid(), NamespaceLogicalToDisplay(), NamespaceLogicalToOdbc(), NamespaceNormalize()

property PID as %String [ ReadOnly ];

PID of job performing the work, available once the "Running" state has been entered.

Property methods: PIDDisplayToLogical(), PIDGet(), PIDGetStored(), PIDIsValid(), PIDLogicalToDisplay(), PIDLogicalToOdbc(), PIDNormalize()

property PauseIsAvailable as %Integer [ Calculated ];

True if pause is allowed for this task and the state (as of load time) is such that it can be paused. Used by user interface code to determine whether to enable a "pause" control.

Property methods: PauseIsAvailableCompute(), PauseIsAvailableDisplayToLogical(), PauseIsAvailableGet(), PauseIsAvailableIsValid(), PauseIsAvailableLogicalToDisplay(), PauseIsAvailableNormalize(), PauseIsAvailableSQLCompute()

property ProgressCurrent as %Numeric [ Calculated ];

The current amount of progress made. To be interpreted, along with ProgressTotal and ProgressUnits as follows:

non-zero total and non-null units: current and total values are to be displayed with the unit string.

non-zero total and null units: current / total is to be displayed as a percentage.

zero total, non-zero current, and non-null units: current is displayed with the unit string (without reference to the total).

otherwise numeric progress not available.

Property methods: ProgressCurrentCompute(), ProgressCurrentDisplayToLogical(), ProgressCurrentGet(), ProgressCurrentIsValid(), ProgressCurrentLogicalToDisplay(), ProgressCurrentNormalize(), ProgressCurrentSQLCompute()

property ProgressTotal as %Numeric [ Calculated ];

The total amount of progress that must be made to complete. This value may change while running as more accurate estimates become available. See ProgressCurrent for more detail.

Property methods: ProgressTotalCompute(), ProgressTotalDisplayToLogical(), ProgressTotalGet(), ProgressTotalIsValid(), ProgressTotalLogicalToDisplay(), ProgressTotalNormalize(), ProgressTotalSQLCompute()

property ProgressUnits as %String [ Calculated ];

The units in which progress is measured. Used to display progress to the user. Null is allowed, treating progress as dimensionless. See ProgressCurrent for more details.

Property methods: ProgressUnitsCompute(), ProgressUnitsDisplayToLogical(), ProgressUnitsGet(), ProgressUnitsIsValid(), ProgressUnitsLogicalToDisplay(), ProgressUnitsLogicalToOdbc(), ProgressUnitsNormalize(), ProgressUnitsSQLCompute()

property Request as %Integer [ Calculated ];

Request to the running task. 1 is request to pause. 2 is request to cancel.

Property methods: Request(), RequestCompute(), RequestDisplayToLogical(), RequestGet(), RequestIsValid(), RequestLogicalToDisplay(), RequestNormalize(), RequestSQLCompute()

property ResumeIsAvailable as %Integer [ Calculated ];

True if pause is allowed and the utility is paused. Used by user interface code to determine whether to enable a "resume" control.

Property methods: ResumeIsAvailableCompute(), ResumeIsAvailableDisplayToLogical(), ResumeIsAvailableGet(), ResumeIsAvailableIsValid(), ResumeIsAvailableLogicalToDisplay(), ResumeIsAvailableNormalize(), ResumeIsAvailableSQLCompute()

property RunningState as %String [ Calculated ];

Information about whether the task is running or not. Values are constants, defined for convenience in %syBackgroundTask.inc

"Starting" ($$$BGTaskStarting) - Object has been created but has not started working yet.

"Running" ($$$BGTaskRunning) - Task is running

"Done" ($$$BGTaskDone) - Task has completed successfully

"Error" ($$$BGTaskError) - Task has returned an error - see FinalStatus

"Paused" ($$$BGTaskPaused) - Task has been pasued

"Cancelled" ($$$BGTaskCancelled) - Task has been cancelled

"Exited" ($$$BGTaskExited) - Task exited unexpectedly and did not complete normally

Property methods: RunningStateCompute(), RunningStateDisplayToLogical(), RunningStateGet(), RunningStateIsValid(), RunningStateLogicalToDisplay(), RunningStateLogicalToOdbc(), RunningStateNormalize(), RunningStateSQLCompute()

property StartTime as %TimeStamp [ ReadOnly ];

Start time of run

Property methods: StartTimeDisplayToLogical(), StartTimeGet(), StartTimeGetStored(), StartTimeIsValid(), StartTimeLogicalToDisplay(), StartTimeNormalize(), StartTimeOdbcToLogical()

Methods

final method Cancel() as %Status

Request cancellation.

final method Pause() as %Status

Request pause.

final method Resume() as %Status

Request to resume from pause.

final classmethod Start(args...) as %ObjectHandle

Starts this task in the background and returns on oref for monitoring and control. Returns null on error, with error status available in %objlasterror. The meaning of the arguments are specific to each subclass.

Queries

query DatabaseList()

SQL Query:
SELECT ID,StartTime,DisplayType,Database,RunningState,HasEnded,ProgressTotal,ProgressCurrent FROM SYS_Database.BackgroundFileCompact UNION SELECT ID,StartTime,DisplayType,Database,RunningState,HasEnded,ProgressTotal,ProgressCurrent FROM SYS_Database.BackgroundDefragment ORDER BY ID

All database-oriented tasks. This currently includes SYS.Database.BackgroundFileCompact and SYS.Database.BackgroundFileCompact

query ListAll()

SQL Query:
SELECT %ID,StartTime,Class,DisplayType,Namespace,RunningState,HasEnded,FinalStatus, ProgressCurrent,ProgressTotal,ProgressUnits FROM %SYS.BackgroundTask

Query background tasks of all types

Indexes

index (IDKEY on ) [IdKey, Type = key];

Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods

• %%CLASSNAMELogicalToStorage()
• %%CLASSNAMEStorageToLogical()
• %AddToSaveSet()
• %AddToSyncSet()
• %BMEBuilt()
• %BuildIndicesAsync()
• %BuildIndicesAsyncResponse()
• %CheckConstraints()
• %CheckConstraintsForExtent()
• %ClassIsLatestVersion()
• %ClassName()
• %ComposeOid()
• %ConstructClone()
• %Delete()
• %DeleteExtent()
• %DeleteId()
• %DispatchClassMethod()
• %DispatchGetModified()
• %DispatchGetProperty()
• %DispatchMethod()
• %DispatchSetModified()
• %DispatchSetMultidimProperty()
• %DispatchSetProperty()
• %Exists()
• %ExistsId()
• %Extends()
• %GUID()
• %GUIDSet()
• %GetLock()
• %GetParameter()
• %GetSwizzleObject()
• %Id()
• %InsertBatch()
• %IsA()
• %IsModified()
• %IsNull()
• %KillExtent()
• %KillExtentData()
• %LoadFromMemory()
• %LockExtent()
• %LockId()
• %New()
• %NormalizeObject()
• %ObjectIsNull()
• %ObjectModified()
• %Oid()
• %OnBeforeAddToSync()
• %OnDeleteFinally()
• %OnDetermineClass()
• %OnOpenFinally()
• %OnSaveFinally()
• %Open()
• %OpenId()
• %OriginalNamespace()
• %PackageName()
• %PhysicalAddress()
• %PurgeIndices()
• %Reload()
• %RemoveFromSaveSet()
• %ResolveConcurrencyConflict()
• %RollBack()
• %Save()
• %SaveDirect()
• %SaveIndices()
• %SerializeObject()
• %SetModified()
• %SortBegin()
• %SortEnd()
• %SyncObjectIn()
• %SyncTransport()
• %UnlockExtent()
• %UnlockId()
• %ValidateIndices()
• %ValidateObject()
• %ValidateTable()

Storage

Storage Model: Storage (%SYS.BackgroundTask)

^%SYS.BackgroundTaskD(ID)

=

%%CLASSNAME StartTime Namespace FinalStatus PID MemIdx Version JobNum JobID ExternalStateStored

Subclasses

• SYS.Database.BackgroundDefragment
• SYS.Database.BackgroundFileCompact