Class %SYS.BackgroundTask

abstract persistent class %SYS.BackgroundTask extends %Persistent

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.

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
3	22	22	3

Summary

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

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	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 Class as %String [ Calculated ];

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

• property DisplayType as %String [ Calculated ];

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

• property FinalStatus as %Status [ ReadOnly ];

Status code when finished

• 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 Namespace as %String [ ReadOnly ];

Namespace in which the task is run.

• property PID as %String [ ReadOnly ];

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

• 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 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 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 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 Request as %Integer [ Calculated ];

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

• 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 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 StartTime as %TimeStamp [ ReadOnly ];

Start time of run

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

Class Reference IRIS for UNIX 2024.1.2
Documentation Search