The Scheduling Component

Licensed and Supported Software
(C) Copyright 2002, Hume Integration Software
All Rights Reserved


Introduction

The Scheduling Component is useable as a standalone application or as a process in a distributed system for the purpose of managing and initiating tasks in the future.  The Scheduling Component can also be used as a Tcl package extension in a custom application.

Feature Summary

Installation

Installation of the Scheduling Component (SC) requires the following software be installed as well: These software selections are available using the setup program that installs the SC.

Startup

The SC can be used as a standalone application or as a process in a distributed system.  To start the SC as a separate process, use the sc_run (or sc_run.bat) script file, or invoke the Windows Start menu program item.  The SC reads and writes to the file sc_tasks.tab when running, so the SC needs to be executing with the working directory being writeable by the person who starts the application.

The user should have the environment variable LANG set to his current Locale.  If the value of LANG is not set, the SC sets it to en_US so that English messages are presented to the user.  The SC is configured for other locales by defining message catalog files.  See the msgcat package document, and review the provided en.msg English message catalog file.

The SC can run in background or as a service.  The GUI does not need to be instantiated or used to have scheduled tasks execute.  Additional arguments on the sc_run command line are interpreted as Tcl commands and executed at startup.  One use of this capability is to have the SC join a DMH message system group, so that it can send and receive DMH messages while it runs.  For example, if a DMH server is already running, the SC can connect to it:

datahub "set group=demo" eof &
sc_run "mbx init demo" "mbx whenmsg SC_SQL mbx_SQL" &
hubclient SC_SQL@demo &
hubclient DATAHUB@demo &
Even if the GUI is not viewable, examining the sc_tasks table data remotely using a DMH connection can give the confidence that the SC is executing properly, and that tasks are being invoked and rescheduled.

The SC can also be installed and used as a Tcl package extension in your application.  The SC package name is HumeSC.  To use the SC as a package, follow these steps:

Resources

On all platforms, at startup, the SC sources the file $env(HOME)/.dmhrc if it exists.  This feature gives you the ability to custom configure the initial appearance of the SC clock.  Here are model statements:
option add *Lcdclock.Foreground turquoise userDefault
option add *Lcdclock.Background grey32 userDefault
option add *Lcdclock.Height 250 userDefault
option add *Lcdclock.Date 1
option add *Lcdclock.Hours 12
option add *Lcdclock.Seconds 0
option add *Lcdclock.Tilt 0
option add *Lcdclock.Utc 0
In this same file, you can also add custom startup code.

The resource customization can also be done on POSIX platforms using the .Xdefaults file and a different syntax for X-Windows resources.  See the X-Windows documentation.

Usage

A freshly installed SC instance has some tasks defined, and  .WAV files included so that it can function as a chime sounding alarm clock.  One of key ideas is that scheduled tasks can be enabled or disabled.  When a task is disabled, all of the usual re-scheduling takes place, but the task is not executed.  For example, if you are using the SC for a musical alarm clock, you can disable the wake-up music for a particular day but keep the makeup task scheduled, and enable it in the future.

The dialog used to configure tasks has the following appearance:

Hopefully, most of the expected usage is self-evident.  Some notes:





Internal API

The more important procedures used internally by the SC are presented in this section.  These procedures could be used in new applications to address custom requirements.  These procedures are all coded in the namespace HumeSC.


sc_gui - create the main user interface window for the SC

Tcl Command Syntax

sc_gui {w .sc_gui}
Return Value
None
Description
This command creates the main Graphical User Interface window of the SC application.  The window name used can be optionally specified.


sc_load_data - load the task data from the file system and commence scheduling

Tcl Command Syntax

sc_load_data
Return Value
None
Description
This command attempts to read the SQL table image file sc_tasks.tab and then restart timers for the tasks found in the file.  As the SC runs, it updates the sc_tasks.tab file image.  The file is plain text SQL statements and may be manually edited before starting the SC.  Past due one-shot tasks are deleted from the table without execution.  Periodic tasks are moved to the next future time due.


sc_main - Begin running the SC

Tcl Command Syntax

sc_main {want_gui 1}
Return Value
None
Description
This command is the main entry to running the SC.  It requests the additional Tcl packages needed by the software including Humelib and msgcat, and then executes, sc_schema, sc_load_data, and optionally sc_gui.  The scheduling logic starts running with the execution of sc_load_data so sc_gui does not need to be called to have scheduled tasks execute.


sc_schema - Create the SC SQL tables

Tcl Command Syntax

sc_schema
Return Value
None
Description
This command creates the two in-memory tables described in the next section.



Table Schema

These tables are created as in-memory tables in the SC Tcl/Tk process.


sc_task_type Table - Possible Task Types for GUI Selection
 
 
Column 
Name
Key Type Description
task_type PK varchar(20) A keyword to indicate the task type. { play_soundfile | exec | eval }
description   varchar(40) Description text shown to the user as a prompt, such as 'Play an MP3 or WAV audio file'
argprompt   varchar(20) The prompt to be displayed for the file system Browse.. button such as 'Pathname:'



sc_tasks Table - Configuration of Scheduled Tasks
 
 
Column 
Name
Key Type Description
utctime_due PCK varchar(19) A timestamp for the task due time in the UTC timezone. (localtime 10)
timer_id PCK varchar(20) A unique name for an ep_timer instance used to schedule the task.
localtime_due   varchar(19) A timestamp for the task due time in the local timezone. (localtime 9)
period   varchar(20) The period interval for periodic tasks.  Blank or one-shot for aperiodic tasks.  Should be equal to a year or less duration.  { N [second[s]] | N day[s] | N week[s] | weekly | hourly | daily | N hour[s] | N minute[s] }
is_enabled   integer Used as a boolean to determine whether the task is executed when the current time becomes the time due.
is_utc_schedule   integer Used as a boolean to determine whether the task is scheduled in the local timezone or in the UTC timezone.  The task configuration GUI will present the task data and pre-select the timezone checkbox accordingly.  Also, for periodic tasks that are scheduled in the local timezone where the period is an integer number of days, the scheduling logic will adjust the task time across Daylight Saving Time clock shifts so that the task occurs at the same local hour of day, if possible.  Periodic tasks that are scheduled in the UTC timezone are not adjusted for Daylight Saving Time clock shifts.
description   varchar(40) A description for the scheduled task provided by the user.
task   varchar(2000) A two element list of the task type and its arguments.  The arguments to the task depend on the task type. 




Document Version

Date of last revision: $Date: 2004/03/02 17:04:39 $

This document covers the Hume Integration Software developed Scheduling Component which is available for the Tcl 8.3/Tk 8.3 environment on the Windows 2000/NT and UNIX/POSIX platforms.