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

A Graphical User Interface for managing one-shot and periodic task initiation.
Excellent for periodic report initiation, or to trigger data collection.
Can play .MP3 or .WAV files and function as a Musical Alarm Clock. Use your notebook computer when traveling instead of a clock radio.
Features a configurable clock view that is fun to display.

Size and color are configurable.
12 or 24 hour format
Date, or Seconds are optional
The Local or UTC timezones may be displayed.
The digits and text are optionally tilted.

Startup appearance is customizable using .Xdefaults or $HOME/.dmhrc resource options.
Dialog prompts and messages are read from msgcat files, and can be Localized for International use.
Displays updating list of scheduled tasks in pending execution order.
Periodic tasks can be scheduled for weekly, hourly, daily, <N> seconds, <N> minutes, <N> hours, <N> days, or <N> weeks, up to a year interval.
Possible scheduled task actions:

Execute Tcl programming statements.
Execute an external application.
Play an MP3 or WAV file.

Installation

Installation of the Scheduling Component (SC) requires the following software be installed as well:

The Hume Datahub SDK
The [incr Tcl], [incr Tk], and Iwidgets packages
The Hume Component Libraries which includes the Humelib and Dmhwidgets packages

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:

Install the SC files in a directory under your Tcl runtime directories, such as /usr/local/lib/sc.
In your application execute:

package require HumeSC
HumeSC::sc_main

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:

The next time due can be specified for your own timezone or for the UTC timezone.
The buttons with the downward arrows activate selection lists.
One of the choices for "Period:" is one-shot. This choice is used for aperiodic tasks.
For some of the "Period:" choices such as <N> hours you must also enter a positive integer value for <N>.
For the task pathname or application arguments, you should use Unix style slashes in pathname specifications. If multiple application arguments are provided, you need to conform to the syntax of Tcl lists.
Applications are executed in background using the Tcl exec command with & specified.
You can execute new Tcl procedures in your tasks, by adding files to the SC directory, rebuilding the tclIndex file, and restarting the SC.
You can test execute your tasks from the main window, by selecting the task and choosing the appropriate right-mouse click action, or pull-down menu item.

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: 2008/03/18 17:38:51 $

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.