Commands related to the Windows task scheduler
This module provides commands for scheduling and running jobs through the Windows task scheduler.
The Windows task scheduler allows programs to be automatically started at certain times or when certain conditions are met. Tasks may be scheduled on either local or remote computers.
The simplest way to create and delete tasks is through the mstask_create and mstask_delete commands. These take care of acquiring and releasing the low lever interface handles and deal with the common case where a single task trigger is associated with a task.
More flexible and complete task scheduler functionality is available through commands that expose the interface handles to the different types of task scheduler objects. Working with the task scheduler involves three types of objects:
An interface to the local or a remote task scheduler is obtained through the itaskscheduler_new command. The returned interface handle can be used to manage tasks on that computer. The commands itaskscheduler_get_target_system and itaskscheduler_set_target_system allow retrieving and changing the system associated with the task scheduler handle at any time.
Once a task scheduler interface handle is obtained, it can be used to access task definitions for that scheduler. The commands itaskscheduler_new_itask and itaskscheduler_get_itask will return interfaces to new and existing tasks which can be manipulated as described below. Tasks can also be deleted through the itaskscheduler_delete_task command and enumerated using itaskscheduler_get_tasks. Existence of a task definition can be verified using the itaskscheduler_task_exists command. (Note: as a general rule, commands related to tasks that require a task interface handle use itask in the command name while commands that require a task name use task.)
Once an interface handle to a task is obtained, its settings can be accessed and modified through the itask_get_info and itask_configure commands. Any changes made must be saved by then calling the itask_save command. Alternately, itask_edit_dialog may be used to display a dialog that allows the user to configure a task.
In addition to scheduling through the task scheduler, task execution can also be directly controlled. itask_run will immediately run a task while itask_end will terminate a task that is currently executing. Future times when a task will be run can be obtained using the itask_get_runtimes_within_interval call.
Each task is associated with zero or more task triggers that determine when and under what conditions the task is executed. The commands itask_new_itasktrigger and itask_get_itasktrigger return interface handles to new or existing task triggers. When not required triggers can be deleted through itask_delete_itasktrigger. The number of triggers associated with a task can be obtained through the itask_get_itasktrigger_count command. itask_get_itasktrigger_string returns a string describing the trigger.
Once a handle to a trigger is obtained, its settings can be retrieved and modified through the itasktrigger_get_info and itasktrigger_configure commands respectively.
-account USERNAME | Sets USERNAME as the account under which the task will be run. If USERNAME is specified as the empty string, the task will be run under the system account. If any user other than the system account is specified, the -password option must also be specified. |
-application PATH | Sets the application to be executed to PATH. |
-comment COMMENT | Sets the comment for the task. |
-creator NAME | Sets the task's creator name. |
-data BINDATA | Stores BINDATA as the application-defined data for the task. BINDATA is treated as binary data. |
-deletewhendone BOOLEAN | If specified as true, the task will be automatically deleted from the task scheduler when it has no more scheduled run times. Default is false. |
-disabled BOOLEAN | If specified as true, the task is disabled and will not be run at its scheduled times. Default is false. |
-dontstartonbatteries BOOLEAN | If specified as true, the task is not started at the scheduled time if the system is running on batteries. Default is false. |
-hidden BOOLEAN | If specified as true, the task is hidden. Default is false. |
-idlewait MINUTES | Sets the number of minutes that the system must be idle before the task runs. |
-idlewaitdeadline MINUTES | Sets the maximum number of minutes that the task scheduler will wait for the system to become idle. |
-killifonbatteries BOOLEAN | If specified as true, the task is not terminated if if the system is switches to batteries while the task is running. Default is false. |
-killonidleend BOOLEAN | If specified as true, the task is terminated, if running, when the computer switches to a non-idle state (i.e. receives user input). Default is false. |
-maxruntime MILLISECONDS | Sets the maximum time (in milliseconds) the application can run before it is terminated. If MILLISECONDS is specified as -1, there is no limit on the run time. |
-params PARAMSTRING | Sets PARAMSTRING as the parameters to be passed to the application when the task is run. |
-password PASSWORD | Specifies PASSWORD as the password associated with the user account specified with the -account option. |
-priority PRIORITY | Sets the priority for the process executing the task. PRIORITY must be one of normal, abovenormal, belownormal, high, realtime, or idle. |
-resumesystem BOOLEAN | If specified as true, the system will be awakened from a suspended state, if necessary, at the task's scheduled time. Default is false. |
-restartonidleresume BOOLEAN | If specified as true, the task is restarted when the system goes into an idle state and the task had been previously terminated when the system went into a non-idle state. Default is false. |
-runonlyifloggedon BOOLEAN | If specified as true, the task is only run if the user specified through the -account option is logged on. Default is false. |
-startonlyifidle BOOLEAN | If specified as true, the task is only run if the system is idle at the task's scheduled run time. Default is false. |
-workingdir PATH | Sets PATH as the working directory when the task is executed. |
-all | Returns all settings. |
-lastruntime | Returns the last time that the task was run in the format Year-Month-Day Hour:Minutes:Seconds. (Note the month must be specified numerically.) An empty string is returned if the task has not been run yet. |
-nextruntime | Returns the next time that the task is scheduled to run in the format Year-Month-Day Hour:Minutes:Seconds. (Note the month must be specified numerically.) The return value may also be one of disabled if the task is disabled, notriggers if no triggers are defined for it, or oneventonly if the task is configured to run on events as opposed to time. |
-status | Returns the status of the task which is one of ready, running, disabled, partiallydefined, or unknown. |
-count COUNT | The maximum number of time elements to return. COUNT must be less than 1440. The actual number returned may of course be less than COUNT depending on how many times the task is scheduled to run in the specified interval. |
-end DATETIMESPEC | The ending time of the interval specified as Year-Month-Day Hour:Minutes:Seconds. By default, this is January 1, 2038. Note the month must be specified numerically. |
-start DATETIMESPEC | The starting time of the interval specified as Year-Month-Day Hour:Minutes:Seconds. By default, this is the current time. Note the month must be specified numerically. |
-statusvar VARNAME | If specified, VARNAME in the caller's context is set to the status of the call. This is success to indicate successful retrieval of the scheduled times. Otherwise, it may also be be one of disabled if the task is disabled, notriggers if no triggers are defined for it, or oneventonly if the task is configured to run on events as opposed to time. In all these three cases, the return value of the command is an empty list. |
-begindate DATESPEC | Specifies the date on which the trigger is activated. DATESPEC must be in the format YEAR-MONTH-DAY. Defaults to the current date. |
-daysofmonth MONTHDAYMASK | Specifies the days of the month that the task is scheduled to run. MONTHDAYMASK is a bitmask with the low order bit corresponding to the first day of the month. This option only has effect if the value of the -type option is monthlydate. |
-disabled BOOLEAN | If specified as true, disables the trigger so it has no effect. Default is false. |
-duration MINUTES | Specifies the number of minutes after the task starts that the trigger is active. The task will be continuously restarted during this period with the interval between starts given by the option -interval. |
-enddate DATESPEC | Specifies the date on which the trigger becomes inactive. DATESPEC must be in the format YEAR-MONTH-DAY. If DATESPEC is the empty string, there is no end date and the trigger never becomes inactive. This is also the default. |
-interval MINUTES | See description of -duration. |
-killatdurationend BOOLEAN | If specified as true, the task is terminated if it is still running at the end of the trigger duration. Default is false. |
-months MONTHMASK | Specifies the months in which the trigger is active. MONTHMASK is a bitmask with the low order bit corresponding to January. The trigger is active in those months for which the corresponding bit is set. By default, the trigger is active for all months. This option is only used if the -type option specifies the trigger type to be either monthlydate or monthlydow. |
-period PERIOD | If -type is daily, PERIOD is the number of days between invocations of the task. Similarly, if -type is weekly, PERIOD is the number of weeks between invocations of the task. This option is not used for other trigger types. If unspecified, this option defaults to 1. |
-starttime TIMESPEC | Specifies the time at which the task is to be run. TIMESPEC is of the form HOUR:MINUTES. |
-type TRIGGERTYPE | Specifies the type of the trigger. If TRIGGERTYPE is once, the task
will only be run once. A value of daily or weekly will cause the task to be scheduled daily or weekly respectively. In both cases, the interval between runs being governed by the -period option. Furthermore, in the weekly case, the option -weekdays will control which days of the week the task is run. If TRIGGERTYPE is monthlydate, the task will be scheduled for the days defined by the -months and -daysofmonth options. A value of monthlydow allows the task to be scheduled during a specific week of a month. The -weekofmonth option specifies which week of the month, the -weekdays option specifies which days in that week, and -months option specifies which months are included. In addition, there are three trigger types that are event based - if TRIGGERTYPE is onidle, the trigger is activated when the system becomes idle, atsystemstart causes the task to run every time the system starts and atlogon causes it to run everytime the user logs on. |
-weekdays WEEKMASK | Specifies the days of a week that the trigger should be activated. WEEKMASK is a bitmask corresponding to days of the week with the low order bit corresponding to Sunday. This option is only used if -type is specified as weekly or monthlydow. |
-weekofmonth WEEKNUMBER | Specifies the week of the month that a task should be active. WEEKNUMBER must be an integer in the range 1-5 where 1-4 correspond to the first four weeks while a value of 5 corresponds to the last week of the month. |
Copyright © 2004-2007 Ashok P. Nadkarni