persistent class %SYS.TaskSuper
extends %Persistent, %XML.Adaptor
This class defines an API to schedule tasks to run in the background.
• parameter DOMAIN = "%Utility";
• parameter Version = 2.9;
• property DailyEndTime
as %Time(XMLTIMEZONE="IGNORE") [ InitialExpression = 0 ];
See DailyFrequency property for legal values
• property DailyFrequency
as %Integer(DISPLAYLIST=",Once,Several",VALUELIST=",0,1") [ InitialExpression = 0 ];
How often each day to run the task.
This property governs how the properties DailyFrequencyTime,
DailyIncrement, DailyStartTime, and DailyEndTime are interpreted.
Valid parameters for DailyFrequency are:
0 - ONCE - Run once on the day scheduled
DailyFrequencyTime - "", ignored
DailyIncrement - "", ignored
DailyStartTime - Time for task to run in $H format($p($h,",",2))
DailyEndTime - "",ignored
1 - SEVERAL - Run Several times in a day
DailyFrequencyTime - 0 - Run every x minutes
DailyFrequencyTime - 1 - Run every x hours
DailyIncrement - # of minutes between runs or # of hours between runs
DailyStartTime - Time for tasks to start running in $H format($p($h,",",2))
DailyEndTime - Time for task to stop running in $H format($p($h,",",2))
Examples:
Run once at 5:00 pm
DailyFrequency=0,DailyFrequencyTime="",DailyIncrement="",DailyStartTime=61200,DailyEndTime=""
Run every 60 minutes between 5:00 pm and 9:00 pm
DailyFrequency=1,DailyFrequencyTime=0,DailyIncrement=60,DailyStartTime=61200,DailyEndTime=75600
Run every hour between 5:00 pm and 9:00 pm
DailyFrequency=1,DailyFrequencyTime=1,DailyIncrement=1,DailyStartTime=61200,DailyEndTime=75600
Run every two hours between 5:00 pm 9:00 pm
DailyFrequency=1,DailyFrequencyTime=1,DailyIncrement=2,DailyStartTime=61200,DailyEndTime=75600
By default, if the Daily parameters are not set when a task is created, it
will run once on the day scheduled at 12:00 am.
• property DailyFrequencyTime
as %Integer(DISPLAYLIST=",Minutes,Hourly",VALUELIST=",0,1");
See DailyFrequency property for legal values
• property DailyIncrement
as %String;
See DailyFrequency property for legal values
• property DailyStartTime
as %Time(XMLTIMEZONE="IGNORE") [ InitialExpression = 0 ];
See DailyFrequency property for legal values
• property DayNextScheduled
as %Date(XMLPROJECTION="NONE") [ ReadOnly ];
$h Value of when the task is next scheduled to run
• property Description
as %String(MAXLEN=100,TRUNCATE=1);
Description of task
• property DisplayDayNextScheduled
as %String(MAXLEN=255) [ Transient ];
• property DisplayEndDate
as %String(MAXLEN=255) [ Transient ];
• property DisplayErrorDate
as %Date [ Transient ];
• property DisplayErrorNumber
as %String(MAXLEN=255) [ Transient ];
• property DisplayFinished
as %String(MAXLEN=255) [ Transient ];
• property DisplayInterval
as %String(MAXLEN=255) [ Transient ];
• property DisplayNextScheduled
as %String(MAXLEN=255) [ Transient ];
• property DisplayNextScheduledBrief
as %String(MAXLEN=255) [ Transient ];
• property DisplayRun
as %String(MAXLEN=255) [ Transient ];
• property DisplayRunAfter
as %String(MAXLEN=255) [ Transient ];
• property DisplayStartDate
as %String(MAXLEN=255) [ Transient ];
• property DisplayStarted
as %String(MAXLEN=255) [ Transient ];
• property DisplayStatus
as %String(MAXLEN=1024) [ Transient ];
• property ER
as %String;
$lb(date,index) in %ER global on error
• property EmailOnCompletion
as list of %String(MAXLEN=255);
A comma separated list of email addresses to send a completion
notification to.
• property EmailOnError
as list of %String(MAXLEN=255);
A comma separated list of email addresses to send an error notification to.
• property EmailOnExpiration
as list of %String(MAXLEN=255);
A comma separated list of email addresses to send notification if the task expires.
• property EmailOutput
as %Library.Boolean [ InitialExpression = 0 ];
If an output directory and output file are chosen, and EmailOutput is
set to 1 the output from the entry will be emailed to the email
addresses in the EmailOnCompletion property.
• property EndDate
as %Date;
$p($h,",",1) value when to stop scheduling the task
Default is to never stop scheduling
• property Error
as %String(MAXLEN=1024,TRUNCATE=1);
Untrapped error from User task, or "Success"
• property Expires
as %Boolean [ InitialExpression = 1 ];
Whether this entry expires. Expiration is only checked if this flag is set to 1.
Expiration is determined by whichever is first:
1) The current time passed the next submit time.
2) Expiration Offsets (Days, Hours, Minutes).
• property ExpiresDays
as %Integer;
• property ExpiresHours
as %Integer;
• property ExpiresMinutes
as %Integer;
• property IsBatch
as %Boolean [ InitialExpression = 0 ];
Batch mode restricts the job to a small section of the buffer pool.
0 - Don't run in batch mode (default)
1 - Run in batch mode
• property JobGUID
as %String;
Unique Identifier assigned to each job
• property LastFinished
as %String [ InitialExpression = 0 ];
$h Value of when the task was last finished
0 - did not finish
• property LastSchedule
as %String [ InitialExpression = 0 ];
$h Value of when the task was last scheduled to run
0 - Never run
• property LastStarted
as %String [ InitialExpression = 0 ];
$h Value of when the task was last started
0 - Never started
• property MirrorStatus
as %Integer(DISPLAYLIST=",Primary,Backup,Either",VALUELIST=",1,2,3") [ InitialExpression = 1 ];
Used to control the execution of tasks when the system is part of a Mirror.
Tasks should be scheduled to run on both the Primary and Backup system, but will
only be executed if the current status matches what is indicated by this property.
This property is ignored by the Task Manager if the system is not a Mirror member.
Status = 1 - run on Primary Mirror member only (default)
Status = 2 - run on Backup Mirror member only
Status = 3 - run on Either Primary or Backup
• property Name
as %String(TRUNCATE=1);
Name of the task. Must be 16 characters or less, first character
must be a letter.
• property NameSpace
as %String(MAXLEN=64) [ InitialExpression = "%SYS" ];
Namespace to run the task in (default="%SYS")
• property OpenOutputFile
as %Library.Boolean [ InitialExpression = 0 ];
If the output from the executed code is to be directed to an output
file, open the output file. If the executed code handles the open and
close this value should be 0.
• property OutputDirectory
as %String(MAXLEN=1024);
If an output directory and output file are chosen, the output from
the entry will be directed there.
• property OutputFileIsBinary
as %Boolean [ InitialExpression = 1 ];
When emailing the output file this flag
will indicate if the file should be sent as binary
• property OutputFilename
as %String(MAXLEN=255);
If an output directory and output file are chosen, the output from
the entry will be directed there.
• property Priority
as %Integer(DISPLAYLIST=",Normal,Low,High",VALUELIST=",0,1,2") [ InitialExpression = 0 ];
Background Job priority
0 - Normal (Default)
1 - Low
2 - High
• property RescheduleOnStart
as %Boolean [ InitialExpression = 0 ];
If true, when the CheckSchedule class method is called with SystemStart=1
any jobs pending in the task queue will be removed, and rescheduled
for their next time. For example, the journal switch is
scheduled for midnight. If the system goes down at 11 pm, and then
restarts at 1 am, the journal switch would normally run. But since
we just started, we don't really want it to switch, so we reschedule it
for the next time.
Default=0
• property RunAfterGUID
as %String;
Execute this job when specified job completes
• property RunAsUser
as %String;
Username of user to run as
User must have %Admin_Secure role to define task to run as another user
• property RunningJobNumber
as %String;
$J value of the job when running
• property StartDate
as %Date [ InitialExpression = $H+1 ];
$p($h,",",1) value when to schedule the task first
Default is to start tomorrow
• property Status
as %String(MAXLEN=1024,TRUNCATE=1) [ InitialExpression = 1 ];
Return value of the method %OnTask
If not defined by the task default success will be 1
If the job is currently running (JobRunning) Status will be -1
If there was an untrapped error (JobUntrappedError) Status will be -2
If there was an error before execution (JobSetupError) Status will be -3
If the task timed out trying to job (JobTimeout) Status will be -4
If there was an error after execution JobPostProcessError) Status will be -5
The text of the status code will be in the property Error
• property Suspended
as %Integer(DISPLAYLIST=",,Suspend Leave,Suspend Reschedule",VALUELIST=",0,1,2") [ InitialExpression = 0 ];
0 - Not suspended (default)
1 - Suspend the task, but leave it in task queue
2 - Suspend the task, remove from task queue, and reschedule for next time
• property TaskClass
as %String(MAXLEN=255);
A class in the specified 'NameSpace' which inherits from %SYS.Task.Definition
• property TimeNextScheduled
as %Time(XMLPROJECTION="NONE") [ ReadOnly ];
$h Value of the times the task is next scheduled to next run,
each time separated by a "~"
• property TimePeriod
as %Integer(DISPLAYLIST=",Daily,Weekly,Monthly,Monthly Special,Run After,On Demand",VALUELIST=",0,1,2,3,4,5") [ InitialExpression = 0 ];
Time period to run the task.
This property governs how the properties TimePeriodEvery and
TimePeriodDay are interpreted
Valid parameters For TimePeriod are
0 - DAILY
TimePeriodEvery - Run every x Days, where Days are 1-7
TimePeriodDay - Set to "", ignored
1 - WEEKLY
TimePeriodEvery - Run every x Weeks, where weeks are 1-5
TimePeriodDay - Run on days xxxx, where Sunday=Day 1,Saturday=Day 7
(where 23456 would be Monday thru Friday)
2 - MONTHLY
TimePeriodEvery - Run every x Months, where months are 1-12
TimePeriodDay - Run on day x, where day=1-31, where 31=last day of month
3 - MONTHLYSPECIAL
TimePeriodEvery - Run every x Months, where months are 1-12
TimePeriodDay - week^day,where weeks is 1-5, 5 being last, day is 1-7, sunday is day 1
4 - RUNAFTER - Run this task after another task completes
TimePeriodEvery - Task Name to Run after
TimePeriodDay - 0
5 - ONDEMAND - The task is set up. It can be run On Demand by calling the RunOnce method
TimePeriodEvery - "",ignored
TimePeriodDay - "", ignored
The user calls the RunOnce Class method to schedule the task after it is set up
If the Time period fields are not set when a task is created, The task is set by default to be
run every day.
Examples:
Run every day
TimePeriod=0,TimePeriodEvery=1,TimePeriodDay=""
Run every other day
TimePeriod=0,TimePeriodEvery=2,TimePeriodDay=""
Run Every Sunday
TimePeriod=1,TimePeriodEvery=1,TimePeriodDay=1
Run Every Monday through Friday
TimePeriod=1,TimePeriodEvery=1,TimePeriodDay=23456
Run Every other Saturday
TimePeriod=1,TimePeriodEvery=2,TimePeriodDay=7
Run The first day of every month
TimePeriod=2,TimePeriodEvery=1,TimePeriodDay=1
Run the last day of every month
TimePeriod=2,TimePeriodEvery=1,TimePeriodDay=31
Run the last day of every other month
TimePeriod=2,TimePeriodEvery=2,TimePeriodDay=31
Run the second Saturday of every month
TimePeriod=3,TimePeriodEvery=1,TimePeriodDay=2^7
Run the first Sunday of every month
TimePeriod=3,TimePeriodEvery=1,TimePeriodDay=1^1
Run after task BACKUP completes
TimePeriod=4,RunAfterGUID=BackupJobGUID,TimePeriodDay=0
Task is not scheduled to run. Task is scheduled to run by calling the RunOnce method
TimePeriod=5,TimePeriodEvery="",TimePeriodDay=""
• property TimePeriodDay
as %String;
See TimePeriod property for legal values
• property TimePeriodEvery
as %String [ InitialExpression = 1 ];
See TimePeriod property for legal values
• classmethod %OnDelete(OID As %Library.ObjectIdentity)
as %Status
Log the Deletion of a Task
• method AssignSettings(pTask As %SYS.Task.Definition = "")
as %Status
Used to properly move the settings from the Task Definition class into the settings property
• classmethod DisplayErrorCalc(ER As %String, Position)
as %String
• classmethod DisplayGUID(JobGUID As %String, Brief As %Boolean)
as %String
Displays Name, NameSpace, ID for a Guid
• classmethod DisplayIntervalCalc(TimePeriod, RunAfterGUID, DailyFrequency, DailyFrequencyTime, DailyStartTime, DailyEndTime, DailyIncrement)
• classmethod DisplayRunCalc(TimePeriod, TimePeriodEvery, TimePeriodDay, RunAfterGUID)
as %String
• method Expired(ByRef TaskFinished)
as %Boolean
When a task is marked as Expires=1 the task will expire if
- there are no values for ExpiresDays,ExpiresHours,ExpiresMinutes
and the time has passed the next scheduled date/time
- the scheduled time + ExpiresDays+ExpiresHours+ExpiresMinutes is
passed the current times
• classmethod ExportTasks(ListOfIDS As %String = "", FileName As %String = "", qspec As %String = "d")
as %Status
List of task IDs to export $lb(1,2,3)
• classmethod FindId(Name As %Library.String)
as %Integer
backward compatible - returns ID for a %SYS.Task object
• classmethod GUIDToID(TaskGUID)
as %Integer
• classmethod GetRunAfterGUID(ID)
as %String
get job guid given an ID
• classmethod GetRunAfterID(GUID)
as %String
• method GetSettings(ByRef Settings As %List)
as %Status
Return the settings defined for the TaskClass
• classmethod ImportTasks(FileName As %String = "", qspec As %String = "d")
as %Status
• classmethod OpenId(Name As %Library.String)
as %SYS.Task
somewhat backward compatibility
• classmethod Resume(ID As %Integer = "")
as %Status
Resume a Task previously suspended using Suspend or Suspended due to Error.
• classmethod RunNow(ID As %Integer)
as %Status
Schedule a task to run immediately (or within a short period of time).
ID of the task
• classmethod RunOnce(ID As %Integer, Date As %Integer, Time As %Integer)
as %Status
Schedule a task to run at a specific time.
ID of the task
Date - Date in $h format
Time - Time in $h format
• classmethod SettingsDisplayToLogical(Settings As %Binary)
as %Binary
• classmethod SettingsLogicalToDisplay(Settings As %Binary)
as %Binary
• method StartDateSet(Arg As %String)
as %Status
on reset of StartDate also reset the LastSchedule and the NextSchedule
so that a (proper) new schedule is created
• classmethod StatusAsText(Status As %Status)
as %String
• classmethod Suspend(ID As %Integer = "", Flag As %Integer = 1)
as %Status
Suspend a Task.
Flag=1 - Suspend the task, but leave it in task queue (default)
=2 - Suspend the task, remove from task queue, and reschedule for next time
• classmethod SuspendGet()
as %Boolean
Return the value of the Task suspension flag.
0 - Currently running
1 - Currently suspended
• classmethod SuspendSet(Flag As %Boolean)
as %Status
Suspend/Resume the Task Manager.
Flag =
0 - Resume Task Manager
1 - Suspend Task Manager
• classmethod TASKMGRStatus()
as %Integer
Task Status
0 - Not running
1 - Running
2 - Suspended
• classmethod VersionGet()
as %String
Return the version of the Task Class.
• classmethod WakeTASKMGR(Message As %String = "")
Wake up the Task Manager.
• query JobGUIDTaskList()
Selects
JobGUID As %String, Task Name As %String
SQL Query
:
SELECT JobGUID,Name FROM %SYS.Task
Returns a list of the task names with JobGUIDs.
• query OnDemandTasks()
Selects
ID As %Integer, Task Name As %String, Description As %String
SQL Query
:
SELECT %ID,Name,Description FROM %SYS.Task Where TimePeriod=5
• query QuickTaskList()
Selects
ID As %Integer, Task Name As %String
SQL Query
:
SELECT %ID,Name FROM %SYS.Task
Returns a list of the task names.
• query RunAfterQuery(RunAfterGUID As %Integer = 0)
SQL Query
:
SELECT %ID FROM %SYS.Task
Where RunAfterGUID=:RunAfterGUID and Suspended=0
Find all tasks scheduled to run after completing task
• query SuspendedTasks()
Selects
Task Name As %String, Last Status As %String, Last Result As %String, Suspended As %String, ID As %Integer
SQL Query
:
select Name,displaystatus,Error,Suspended,%ID from %SYS.Task
Where Suspended=1 or Suspended=2
Show all Suspended tasks
• query TASKMGRInfo()
Selects
Version As %String, Status As %String, HistoryPurge As %String
Return information about TASKMGR parameters
• query TaskDetail(ID As %Integer = "")
Selects
Task Name As %String, Description As %String, Task Type As %String, Namespace As %String, TaskClass, Batch Mode As %String, Priority As %String, Suspended As %String, Reschedule on Start As %String, Run Task As %String, Run Interval As %String, Next Scheduled Date As %Date, Next Scheduled Time, Start Date As %String, End Date As %String, Last Started As %String, Last Finished As %String, Last Status As %String, Last Result As %String, %ER Date As %Date, %ER Error # As %String, ID As %Integer
SQL Query
:
SELECT Name,Description,Type,NameSpace,TaskClass,IsBatch,Priority,Suspended,RescheduleOnStart,
DisplayRun,DisplayInterval,DisplayDayNextScheduled,TimeNextScheduled,DisplayStartDate,DisplayEndDate,DisplayStarted,DisplayFinished,DisplayStatus,Error,DisplayErrorDate,DisplayErrorNumber,%ID
FROM %SYS.Task
WHERE ID=:ID
Returns details about a Task.
• query TaskList()
Selects
Task Name As %String, Task Type As %String, Namespace As %String, Description As %String, ID As %Integer, Suspended As %String, Last Finished As %String, Next Scheduled As %String
SQL Query
:
SELECT Name,Type,Namespace,Description,%ID,Suspended,DisplayFinished,DisplayNextScheduledBrief FROM %SYS.Task
Returns a list of the task names.
• query TaskListDetail()
Selects
Task Name As %String, Description As %String, Task Type As %String, Namespace As %String, TaskClass As %String, Batch Mode As %String, Priority As %String, Suspended As %String, Reschedule on Start As %String, Run Task As %String, Run Interval As %String, MirrorStatus As %String, Next Scheduled Date As %Date, Next Scheduled Time, Start Date As %String, End Date As %String, Last Started As %String, Last Finished As %String, Last Status As %String, Last Result As %String, %ER Date As %Date, %ER Error # As %String, ID As %Integer
SQL Query
:
SELECT Name,Description,Type,NameSpace,TaskClass,IsBatch,Priority,Suspended,RescheduleOnStart,
DisplayRun,DisplayInterval,MirrorStatus,DisplayDayNextScheduled,TimeNextScheduled,DisplayStartDate,DisplayEndDate,DisplayStarted,DisplayFinished,DisplayStatus,Error,DisplayErrorDate,DisplayErrorNumber,%ID
FROM %SYS.Task
Returns details about all Tasks.
• query TaskSchedule()
Selects
Next Scheduled As %String, Task Name As %String, Last Start As %String, Last Status As %String, Last Result As %String, Suspended As %String, ID As %Integer
SQL Query
:
select displaynextscheduled,name,displaystarted,displaystatus,Error,Suspended,%ID
from %SYS.Task
order by daynextscheduled,timenextscheduled
Show Task Schedule for all tasks
• query TasksInTrouble()
SQL Query
:
SELECT %ID,Name,NameSpace,Error,DisplayStatus FROM %SYS.Task
WHERE (Status NOT= 1)
• query ToRunQuery(DateNow As %String = +$H, TimeNow As %String = $p($h, ",", 2))
SQL Query
:
SELECT %ID FROM %SYS.Task
Where RunningJobNumber is null and (DayNextScheduled<:DateNow or (DayNextScheduled=:DateNow and TimeNextScheduled<=:TimeNow))
ORDER BY DayNextScheduled, TimeNextScheduled
Pick up jobs which are scheduled now or in the past
exclude Suspended and Leave or Jobs marked as Running
• query UpcomingTasks(HoursOffset As %String = "24", ToDate As %Date = "", ToTime As %Time = "", MAXROWS=1000)
Selects
ID As %String, Name As %String, Namespace As %String, Date As %Date, Time As %Time, Suspended As %Integer
• index (JobGUIDIndex on JobGUID) [Unique];
• index (RunAfterIndex on RunAfterGUID);
• index (ScheduleIndex on DayNextScheduled,TimeNextScheduled,Suspended);
