OS/2 Professional/OS2PRO194.ISO/os2/wps/progs/ats/ats.hlp

OS/2 Help File | 1993-08-22 | 45KB | 1,658 lines

ΓòÉΓòÉΓòÉ 1. ATS for OS/2 Menus ΓòÉΓòÉΓòÉ

File Menu:

o Log Comment
o Exit

Edit Menu:

o Define Holidays
o Define Events
o Define Schedule
o System Configuration

Reports Menu:

o Defined Holidays Report
o Defined Events Report
o Defined Tasks Report

Signal Event Menu:

o Signal Event

Windows Menu:

o Log
o Status
o Running Tasks
o Tiling Display Windows


ΓòÉΓòÉΓòÉ 2. Extended Help for ATS for OS/2 ΓòÉΓòÉΓòÉ

With the constant increase of processing power on personal computers many
companies are migrating software systems off of minicomputers and mainframes.
As more and more systems are migrated, it is becoming increasingly obvious that
the availability of PC versions of system utilities that have been in use on
the larger computers for many years is now crucial.

One such utility is a full function job scheduler. Years ago, jobs were
scheduled in the order that the card decks were placed in the readers. As time
went by, sophisticated programs were written to manage the scheduling of jobs
on mainframes and then on minicomputers. With the migration of mission critical
systems to the PC environment, it is evident that a full function job scheduler
is required.

Many companies have developed their own in house scheduler to handle the most
common of their requirements while choosing to ignore the more obscure, but yet
important, other cases. ATS for OS/2 has been designed to allow you to build
complete job streams giving complete control of how and when to run each
program.

Here are a few of the features of ATS for OS/2:

o Build complete job streams.

o Define any day to be a holiday.

o Define if a job should run on a holiday, not run on a holiday or run either
  way.

o Define what day of the week a job can run.

o Define what day of the month a job can run.

o Define what months a job can run.

o Define what hours of the day a job can run.

o Define a date range that a job can run within.

o Define if a job should run on the last day of the month, last business day of
  the month, first business day of the month, last business day before the
  15th, or first business day after the 15th.

o Define if the job should run in a window, full screen or as a Presentation
  Manager application.

o Define a job to be dependent upon the completion of one or more scheduled
  jobs.

o Define a job to be dependent upon one or more files being created or
  modified.

o Define a job to be dependent upon the receipt of one or more external
  signals.

o Logs all activity to a file and an on-line window.

o Displays a list of all running jobs in an on-line window.

ATS can be notified that an external event has occurred in one of three ways.
These methods are: an API that can be incorporated into an independently
developed application program, a supplied executable that can be executed at an
OS/2 command line or from within a REXX or OS/2 Command procedure, or through a
menu option on the ATS main window.

ATS allows you to clear the flag that indicates that an event has occurred two
different ways. They are: an API that can be incorporated into an independently
developed application program or a supplied executable that can be executed at
an OS/2 command line or from within a REXX or OS/2 Command procedure.

ATS allows you to define an unlimited number of tasks, dependencies, and
holidays. ATS logs all activity to disk. In addition, there are three display
windows that can be turned on or off at the users discretion, Log, Status, and
Running Tasks. The log window captures all log entries for real time on-line
viewing. The status window displays the current state of ATS. The Running Tasks
window displays a list of all programs that have been initiated by ATS and are
currently running.

ATS for OS/2 requires IBM OS/2 2.0 or later.

ATS for OS/2 is owned by MHR Software And Consulting. We can be reached by mail
at 2227 U.S. Highway #1,Suite 146, North Brunswick, NJ 08902 or by telephone at
[phone].


ΓòÉΓòÉΓòÉ 3. Exit ΓòÉΓòÉΓòÉ

Selecting the Exit option on the File menu will terminate ATS.


ΓòÉΓòÉΓòÉ 4. ATS for OS/2 Syntax ΓòÉΓòÉΓòÉ

To run ATS, simply type ATS at an OS/2 command Prompt.


ΓòÉΓòÉΓòÉ 5. Installing ATS for OS/2 ΓòÉΓòÉΓòÉ

Included Files

o ATS.EXE

o ATS.HLP

o ATSSGNL.EXE

o ATSRESET.EXE

o ATSRSETD.DLL

o ATSRSETD.LIB

o ATSRSET.H

o ATSSGNL.DLL

o ATSSGNL.LIB

o ATSSGNL.H

Installing ATS

There are no special installation instructions for ATS. Copy all of the files
on the supplied diskette to a directory on your PC.

If you will not be using the programming interface to ATS, then you do not need
any of the header (*.H) LIB (*.LIB) files.

If you will not be using ASTRSET or ATSSGNL then you do not need ATSSGNL.EXE or
ATSRSET.EXE.

If you will not be using the programming interface or the supplied executables,
then you do not need any of the DLL (*.DLL) files.

If you do not want on-line help, then you do no need ATS.HLP.


ΓòÉΓòÉΓòÉ 6. Terms used in ATS for OS/2 ΓòÉΓòÉΓòÉ

Dependencies

A dependency is a link between an event and a task. An event can be a
dependency for one or more tasks. A task can be dependent upon one or more
events. Actually, an event can be defined and not be a dependency of any task
and a task can be defined without having being dependent upon any event.

Event

An event is something that happens. This can be either a file being modified
(File Modification), the completion of a task that was scheduled through and
initiated by ATS (Task Completion), or notification that something has occurred
(Signal Event). Signal Event notification can come from either a provided API
that has been embedded in an application program, running the supplied program
ATSSGNL.EXE, or from selecting SIGNAL EVENT on the main menu of ATS. ATS allows
you to clear the flag that indicates that an event has occurred. There are two
different ways to do this. They are: an API that can be incorporated into an
independently developed application program or a supplied program, ATSRESET.EXE
that can be executed at an OS/2 command line or from within a REXX or OS/2
Command procedure.

Holiday

Any day of the year can be defined as a holiday. By defining certain days as
holidays, you are then able to schedule a task to execute on a particular day
if it is a holiday or if it is not a holiday.

Task

A task is a program that you wish to run. The program can be an OS/2 full
screen application, an OS/2 windowed application, or an OS/2 PM application. A
task can be scheduled to run at a certain time of day, on certain days of the
week, on certain days of the month, on holidays, or not on holidays. In
addition, a task can optionally have an unlimited, number of dependencies.


ΓòÉΓòÉΓòÉ 7. Watchdog ΓòÉΓòÉΓòÉ

Watchdog is a separate product that allows another program to register with it
and if the registered product ends without canceling its registration, Watchdog
will automatically restart that program.

Since ATS has been designed to be used in mission critical and lights out
applications, it has been developed to interface with Watchdog. When ATS is
started, it attempts to register with Watchdog. When ATS is shut down by a
user, it cancels its registration. If Watchdog is not active when ATS is
invoked, ATS will issue a warning to the user that says "Watchdog is not
active". It will also log this fact.

Watchdog is owned by MHR Software And Consulting. Further information can be
obtained by mail at 2227 U.S. Highway #1, Suite 146, North Brunswick, NJ 08902
or by telephone at [phone].


ΓòÉΓòÉΓòÉ 8. ATS Shortcut Keys ΓòÉΓòÉΓòÉ

Key     Function

Alt+A   Display the About screen.

Alt+C   Display the Add Log Comment screen.

Alt+E   Create the Defined Events report.

Alt+F   Display the Log File screen.

Alt+H   Create the Defined Holidays report.

Alt+K   Create the Defined Tasks report.

Alt+L   Add the Log display window to the ATS main window.

Alt+R   Add the Running Tasks display window to the ATS main window.

Alt+S   Add the Status display window to the ATS main window.

Alt+T   Tile the visible display windows.

Ctrl+E  Display the Define Events screen.

Ctrl+G  Display the Signal Event screen.

Ctrl+H  Display the Define Holidays screen.

Ctrl+P  Display the Preferences screen.

Ctrl+S  Display the Define Tasks screen.

Ctrl+T  Display the Timers screen.

F3      Shut down ATS.

ESC     Cancel the currently active screen.

Lower and Upper case letters work alike.


ΓòÉΓòÉΓòÉ 9. ATS Reports ΓòÉΓòÉΓòÉ

ATS for OS/2 provides the ability to produce hard copy documentation of all
holidays, events, and tasks that are defined to the system. The reports are
generated in the background and can be directed to any file.

The generated files are ASCII text that are 80 columns wide and have 58 lines
per page. These files can be printed by using the OS/2 PRINT command.

Related Topics:

o Defined Holidays Report
o Defined Events Report
o Defined Tasks Report


ΓòÉΓòÉΓòÉ 10. Defined Holidays Report ΓòÉΓòÉΓòÉ

The Defined Holidays report provides a list of all of the holidays that have
been defined to ATS. The report looks very similar to the holiday list on the
Define Holidays screen.

To create the Defined Holidays Report:

o Select Reports from the main ATS menu.

o Select Defined Holidays from the Reports menu.

o Select the file that you want the report written to.

o Click on the OK button.

The keyboard short cut key is: Alt+H.

Related Topics:

o ATS Reports
o Defined Events Report
o Defined Tasks Report


ΓòÉΓòÉΓòÉ 11. Defined Events Report ΓòÉΓòÉΓòÉ

The Defined Events report provides a list of all of the events that have been
defined to ATS. The report provides all of the detail that can be specified for
each type of event.

For all events, the report provides the event name, the event type, and a list
of all of the tasks that are dependent upon it.

For Job Termination events, the report adds the name of the task that the event
is dependent upon and the minimum and maximum allowed return codes defined for
the event.

For File Modification events, the report adds the name of the file that the
event is dependent upon.

To create the Defined Events Report:

o Select Reports from the main ATS menu.

o Select Defined Events from the Reports menu.

o Select the file that you want the report written to.

o Click on the OK button.

The keyboard short cut key is: Alt+E.

Related Topics:

o ATS Reports
o Defined Holidays Report
o Defined Tasks Report


ΓòÉΓòÉΓòÉ 12. Defined Tasks Report ΓòÉΓòÉΓòÉ

The Defined Tasks report provides a list of all of the tasks that have been
defined to ATS. The report provides all of the detail that can be specified for
each task.

For all defined tasks, the report provides the task name, the type of OS/2
session that the program runs in, the eligible date and time ranges, the
maximum number of concurrent occurrences that can be started by ATS, the full
path to and program name of the task, the input parameters for the task, the
working directory, for each day of the week and each day of the month, whether
the program should not be run, run only if it falls on a holiday, run if it
does not fall on a holiday or run regardless of if it is a holiday, and, for
special days of the month, whether the program should be run or not be run.

D Don't Run

R Run (regardless of holiday status)

H Run only if it falls on a holiday

N Run if it does not fall on a holiday

To create the Defined Tasks Report:

o Select Reports from the main ATS menu.

o Select Defined Tasks from the Reports menu.

o Select the file that you want the report written to.

o Click on the OK button.

The keyboard short cut key is: Alt+K.

Related Topics:

o ATS Reports
o Defined Holidays Report
o Defined Events Report


ΓòÉΓòÉΓòÉ 13. Display Windows ΓòÉΓòÉΓòÉ

The display windows give the user information about the current state of ATS,
what ATS has done in the current invocation, and what ATS invoked tasks are
currently executing.

Related Topics:

o View Log
o Status
o Running Tasks
o Tiling Display Windows


ΓòÉΓòÉΓòÉ 13.1. Tiling Display Windows ΓòÉΓòÉΓòÉ

When you select the Tiling option on the Windows menu, ATS will divide the
space in the ATS screen evenly and stack each of the visible windows one on top
of the other.

The order of stacking is constant. The ATS Log window, if visible, is always on
the top. The ATS Running Tasks window, if visible, is always on the bottom. The
ATS Status window, if visible, is on the top if the ATS Log window is not
visible, on the bottom if the ATS Running Tasks window is not visible, and in
the middle if all three windows are visible.

When the ATS main window is re-sized, the display windows will be automatically
re-tiled.

To tile the display windows:

o Select Windows from the main ATS menu.

o Select Tile from the Windows menu

The keyboard short cut key is: Alt+T

Related Topics:

o View Log
o Status
o Running Tasks


ΓòÉΓòÉΓòÉ 13.2. Log Display Window ΓòÉΓòÉΓòÉ

Selecting the Log option on the Windows menu will cause the log window to be
opened if it is not already. If it is, choosing this option will close it. The
log window contains a record for each notable event that takes place within the
ATS system.

The ATS Log window displays the all of the messages that have been written to
the ATS log during the current ATS session. When the on-line log fills up, the
log is refreshed by clearing out all of the entries and starting over.

To display the Log display window:

o Select Windows from the main ATS menu.

o Select Log from the Windows menu.

The keyboard short cut key is: Alt+L

Related Topics:

o Status
o Running Tasks
o Log Comment
o Tiling Display Windows
o On Line Log Size


ΓòÉΓòÉΓòÉ 13.3. Status Display Window ΓòÉΓòÉΓòÉ

Selecting the Status option on the Windows menu will cause the status window to
be opened if it is not already. If it is, choosing this option will close it.

The ATS Status window displays the current state of ATS. It provides you with
all of the current ATS statistics.

The following information is displayed:

o The date and time the current ATS session was started.

o The date and time of the latest clock check.

o The date and time of the latest file check.

o The current clock check interval setting.

o The current file check interval setting.

o The current on-line log size setting.

o The name of the current log file.

o The number of defined holidays.

o The date, name and day of week of each defined holiday.

o The number of defined events.

o The name of each defined event and optionally the task name or file name
  associated with it.

o The number of defined tasks.

o The name and program name of each task.

o The number of dependencies for each task.

o The name of each dependency for each task and whether it has occurred (TRUE)
  or not (FALSE).

To display the Status display window:

o Select Windows from the main ATS menu.

o Select Status from the Windows menu.

The Keyboard short cut key is: Alt+S

Related Topics:

o Log
o Running Tasks
o Tiling Display Windows


ΓòÉΓòÉΓòÉ 13.4. Running Tasks Display Window ΓòÉΓòÉΓòÉ

Selecting the Running Tasks option on the Windows menu will cause the Running
Tasks window to be opened if it is not already. If it is, choosing this option
will close it.

The ATS Running Tasks window displays a list of all of the currently executing
child tasks and all of the independent sessions that were started by ATS during
the current ATS session.

The following information is displayed for each invoked task:

o Task Name.

o Start Date and Time.

o Session ID (000 for Independent Sessions).

o Process ID (0000 for Independent Sessions).

Tasks invoked as child sessions will be automatically removed from the Running
Tasks display window when they terminate. Tasks invoked as independent sessions
will remain in the display until ATS is shut down.

To display the Running Tasks display window:

o Select Windows from the main ATS menu.

o Select Running Tasks from the Windows menu.

The keyboard short cut key is: Alt+R

Related Topics:

o Status
o Running Tasks
o Tiling Display Windows


ΓòÉΓòÉΓòÉ 14. Logging ΓòÉΓòÉΓòÉ

ATS logs all activity that takes place during the ATS sessions. This includes,
but is not limited to, creating, editing and deleting tasks, events, and
holidays, initiation and termination of tasks, modification of options, and
errors.

Related Topics:

o Log Comment
o Specifying The Log File


ΓòÉΓòÉΓòÉ 15. Log Comment ΓòÉΓòÉΓòÉ

Selecting the Log Comment option on the File menu will cause a dialog box to be
displayed in which the user can enter text that will be written into the ATS
for OS/2 log.

You can insert a comment into the log at any point. Log comments go into the
log with the standard log entry prefix of date and time.

To display the Add Log Comment screen:

o Select File from the main ATS menu.

o Select Log Comment from the File menu.

The keyboard short cut key is: Alt+F.

To insert Comments Into the Log File:

o Enter any text that you wish into the entry field. You can enter a maximum of
  116 characters per log entry.

o Click on the Add button if you wish to add more than one comment.

o Click on the Add/Quit button if you wish to add the current comment and
  dismiss the dialog box.

o Click on the Cancel button if you do not wish to add the current comment and
  want to dismiss the dialog box.

Related Topics:

o View Log
o Specifying The Log File


ΓòÉΓòÉΓòÉ 16. Specifying The Log File ΓòÉΓòÉΓòÉ

To display the Log File screen:

o Select File from the main ATS menu.

o Select Log File from the File menu.

The keyboard short cut key is: Alt+F.

Specifying a New Log File

To open a new ATS log file, enter the new log file name in the Open filename
field or use the Drive, Directory, and File list boxes to select on.

Log File Initialization

If the selected log file already exists, ATS will prompt you to specify if it
should truncate the data in the new file or append new data to it.

ATS will write one entry to the old log file indicating that it is being closed
and another indicating the name of the new log file.

When ATS opens the new log file, it will write one entry to the new log file
indicating that it has just been opened and another one indicating the name of
the previous one.

Related Topics:

o Log Comment
o View Log


ΓòÉΓòÉΓòÉ 17. Holidays ΓòÉΓòÉΓòÉ

You can define an unlimited number of holidays. Any day of the year can be
defined as a holiday. A holiday definition consists of a date, a name, and a
day of week. By defining certain days as holidays, you are then able to
schedule a task to execute on a particular day if it is a holiday or if it is
not a holiday.

To display the Define Holidays screen:

o Select Edit from the main ATS menu.

o Select Holidays from the Edit menu.

The keyboard short cut key is: Ctrl+H.

Related Topics:

o Adding A New Holiday
o Editing An Existing Holiday
o Deleting An Existing Holiday


ΓòÉΓòÉΓòÉ 17.1. Adding A New H.oliday ΓòÉΓòÉΓòÉ

Insure that you are in Add Mode. The mode is indicated in the title bar of the
dialog box. If you are in Add Mode, the title will be "ATS for OS/2 - Define
Holidays (Add)" and the Mode Change button (located in the lower right corner
of the dialog box will be labeled "Edit Mode". If you are not in Add Mode,
click on the Mode Change button (it will be labeled "Add Mode").

Steps:

o Enter a valid date in the Date field.

o Enter text in the Holiday field that describes the holiday. You can enter a
  maximum of 32 characters.

o Click on the Add button.

If the date that you entered is invalid or is already defined as a holiday, an
error message will be displayed.

If the date is valid and is not already defined as a holiday, the day of week
field will be updated, the holiday will be added to the ATS calendar, and the
entry will appear in the list box.

Related Topics:

o Holidays
o Editing An Existing Holiday
o Deleting An Existing Holiday


ΓòÉΓòÉΓòÉ 17.2. Deleting An Existing Holiday ΓòÉΓòÉΓòÉ

Insure that you are in Edit Mode. The mode is indicated in the title bar of the
dialog box. If you are in Edit Mode, the title will be "ATS for OS/2 - Define
Holidays (Edit)" and the Mode Change button (located in the lower right corner
of the dialog box will be labeled "Add Mode". If you are not in Edit Mode,
click on the Mode Change button (it will be labeled "Edit Mode").

Steps:

o Select the entry in the list box that you wish to delete.

o Click on the Delete button.

If the "Warn on Delete" option on the Preferences screen was selected, a
message box will appear asking you to confirm the deletion.

If "Warn on Delete" is off or if you answered yes to the deletion confirmation,
the holiday will be removed from the ATS calendar, and the entry will be
removed from the list box.

Related Topics:

o Holidays
o Adding A New Holiday
o Editing An Existing Holiday


ΓòÉΓòÉΓòÉ 17.3. Editing An Existing Holiday ΓòÉΓòÉΓòÉ

Insure that you are in Edit Mode. The mode is indicated in the title bar of the
dialog box. If you are in Edit Mode, the title will be "ATS for OS/2 - Define
Holidays (Edit)" and the Mode Change button (located in the lower right corner
of the dialog box will be labeled "Add Mode". If you are not in Edit Mode,
click on the Mode Change button (it will be labeled "Edit Mode").

Steps:

o Select the entry in the list that you wish to edit.

o Enter a valid date in the Date field.

o Enter text in the Holiday field that describes the holiday. You can enter a
  maximum of 32 characters.

o Click on the OK button.

If the "Warn on Edit" option on the Preferences screen was selected, a message
box will appear asking you to confirm the changes.

If the date that you entered is invalid or is already defined as a holiday, an
error message will be displayed.

If the date is valid and is not already defined as a holiday, the day of week
field will be updated, the holiday will be edited in the ATS calendar, and the
entry will be refreshed in the list box.

Related Topics:

o Holidays
o Adding A New Holiday
o Deleting An Existing Holiday


ΓòÉΓòÉΓòÉ 18. Signal Event ΓòÉΓòÉΓòÉ

Selecting the Signal Event option on the ATS main menu will cause the Signal
Event screen to be displayed.

This is one of three ways that a Signal Event can be flagged as having
occurred. The other two are the ATSSGNL.EXE program provided, or embedding the
provided API into your own application.

When an event is flagged as having occurred, it is flagged for all tasks that
currently have that event defined as a dependency of it.

To display the Signal Event screen:

o Select Signal Event from the main ATS menu.

The keyboard short cut key is: Ctrl+G.

Signaling an Event

o Select the event from the Events list box.

o Click on the Signal button.

o Click on Cancel to dismiss the screen or repeat the above steps to signal
  another event.

Double clicking on an entry in the Events list box is the same as doing the
first two steps above.


ΓòÉΓòÉΓòÉ 19. Define Events ΓòÉΓòÉΓòÉ

You use the Define Events screen to create, modify and remove events that will
be used as dependencies for scheduled tasks.

An event is something that happens. This can be either a file being modified
(File Modification), the completion of a task that was scheduled through and
initiated by ATS (Task Completion), or notification that something has occurred
(Signal Event). Signal Event notification can come from either a provided API
that has been embedded in an application program, running the supplied program
ATSSGNL.EXE, or from selecting SIGNAL EVENT on the main menu of ATS. ATS allows
you to clear the flag that indicates that an event has occurred. There are two
different ways to do this. They are: an API that can be incorporated into an
independently developed application program or a supplied program that can be
executed at an OS/2 command line or from within a REXX or OS/2 Command
procedure.

To display the Define Events screen:

o Select Edit from the main ATS menu.

o Select Events from the Edit menu.

The keyboard short cut key is: Ctrl+E.

Types of Events

o Job Termination

o File Modification

o Signal Event

Screen Elements

o Common Elements

o Job Termination Elements

o File Modification Elements

Defining Events

o Adding A New Event

o Editing An Existing Event

o Deleting An Existing Event

Related Topics:

o Define Schedule
o Define Dependencies


ΓòÉΓòÉΓòÉ 19.1. Job Termination Events ΓòÉΓòÉΓòÉ

A Job Termination event is an event that will be flagged as having occurred
when the associated job (a task that is scheduled and executed through ATS)
completes and the associated jobs return code falls within the defined return
code range. In order for a task to be used as a Job Termination event, it must
run as a child process of ATS. Any task that is scheduled through ATS and does
not have the Independent Session option selected on the Task Edit screen will
run as a child process of ATS.


ΓòÉΓòÉΓòÉ 19.2. File Modification Events ΓòÉΓòÉΓòÉ

A File Modification event is an event that will be flagged as having occurred
when the associated file is updated and is available for reading and writing.
The file is checked periodically to see if its statistics have changed and if
it is available. The interval between file checks is determined by the setting
of the File Check timer.


ΓòÉΓòÉΓòÉ 19.3. Signal Events ΓòÉΓòÉΓòÉ

A Signal Event event is an event that will be flagged as having occurred when a
signal is received from either an API that has been incorporated into an
independently developed application program, a supplied executable,
ATSSGNL.EXE, that can be executed at an OS/2 command line or from within a REXX
or OS/2 Command procedure, or through a menu option on the ATS main window.


ΓòÉΓòÉΓòÉ 19.4. Common Event Elements ΓòÉΓòÉΓòÉ

Event Name
The name given to a particular event by the user. This name must be unique
among all events. The Event Name can be up to 12 characters long. This field is
required for all event definitions.

Event Type
Defines the characteristics of the event and how it is flagged as having
occurred. The three possibilities are: Job Termination, File Modification, and
Signal Event. This field is required for all event definitions.


ΓòÉΓòÉΓòÉ 19.5. Job Termination Event Elements ΓòÉΓòÉΓòÉ

Minimum Return Code
The lowest possible value returned by the dependent task that will cause this
event to be flagged as having occurred. This value can be up to 5 digits or 4
digits and a leading sign. This value must be less than the Maximum Return
Code. This field is only required for Job Termination events.

Maximum Return Code
The highest possible value returned by the dependent task that will cause this
event to be flagged as having occurred. This value can be up to 5 digits or 4
digits and a leading sign. This value must be greater than the Minimum Return
Code. This field is only required for Job Termination events.

Task
The name of the task which this event is dependent upon. The task is specified
by selecting one task from the Tasks list box. A scheduled task can not be
dependent upon its own completion. Therefore, a Signal Event event can not be
defined as a dependency of the task of which it is dependent upon. This field
is only required for Job Termination events.


ΓòÉΓòÉΓòÉ 19.6. File Modification Event Elements ΓòÉΓòÉΓòÉ

Full File Name
The drive, path, and name of the file that is being monitored for this event.
The drive, path and name can contain a maximum of 255 characters. This field is
only required for File Modification events.


ΓòÉΓòÉΓòÉ 19.7. Adding A New Event ΓòÉΓòÉΓòÉ

Insure that you are in Add Mode. The mode is indicated in the title bar of the
dialog box. If you are in Add Mode, the title will be "ATS for OS/2 - Define
Events (Add)". and the Mode Change button (located in the lower right corner of
the dialog box will be labeled "Edit Mode". If you are not in Add Mode, click
on the mode change button (it will be labeled "Add Mode").

Steps:

o Fill in the required fields.

o Click on the Add button.

If the name that you entered is already defined or a required field is missing
or out of range, an error message will be displayed.

If all required fields are filled in and within range, the event will be added
to the ATS event list, and the event name will appear in the Events list box.


ΓòÉΓòÉΓòÉ 19.8. Deleting An Existing Event ΓòÉΓòÉΓòÉ

Insure that you are in Edit Mode. The mode is indicated in the title bar of the
dialog box. If you are in Edit Mode, the title will be "ATS for OS/2 - Define
Events (Edit)". and the Mode Change button (located in the lower right corner
of the dialog box will be labeled "Add Mode". If you are not in Edit Mode,
click on the mode change button (it will be labeled "Edit Mode").

Steps:

o Select the entry in the Events list box that you wish to delete.

o Click on the Delete button.

If the "Warn on Delete" option on the Preferences screen was selected, a
message box will appear asking you to confirm the deletion.

If "Warn on Delete" is off or if you answered yes to the deletion confirmation,
the event will be removed from the ATS event list, and the entry will be
removed from the Events list box.


ΓòÉΓòÉΓòÉ 19.9. Editing An Existing Event ΓòÉΓòÉΓòÉ

Insure that you are in Edit Mode. The mode is indicated in the title bar of the
dialog box. If you are in Edit Mode, the title will be "ATS for OS/2 - Define
Events (Edit)". and the Mode Change button (located in the lower right corner
of the dialog box will be labeled "Add Mode". If you are not in Edit Mode,
click on the mode change button (it will be labeled "Edit Mode").

steps

 1. Select the entry in the Events list box that you wish to edit.

 2. Enter the changes that you want, insuring that you fill in all of the
    required fields.

 3. Click on the OK button.

If the "Warn on Edit" option on the Preferences screen was selected, a message
box will appear asking you to confirm the changes.

If the name that you entered is already defined or a required field, as defined
above in Section 5.2. Event Characteristics is missing or out of range, an
error message will be displayed.

If all required fields are filled in and within range, the event will be added
to the ATS event list, and the event name will appear in the Events list box.


ΓòÉΓòÉΓòÉ 20. Define Dependencies ΓòÉΓòÉΓòÉ

You use this screen to link events to tasks. An event can be a dependent of
zero, one or more tasks. A task can have zero, one or more dependencies.

A dependency is a link between an event and a task. An event can be a
dependency for one or more tasks. A task can be dependent upon one or more
events. Actually, an event can be defined and not be a dependency of any task
and a task can be defined without having being dependent upon any event.

To display the Define Task Dependencies screen:

o Select Edit from the main ATS menu.

o Select Tasks from the Edit menu.

  The keyboard short cut key is: Ctrl+S.

o Select the task that you want to add/edit/delete dependencies for.

o Click on the Dependencies button.

Defining Dependencies

o Adding A Dependency

o Removing A Dependency

o Defining An Event

Related Topics:

o Define Schedule
o Define Events


ΓòÉΓòÉΓòÉ 20.1. Adding A Dependency ΓòÉΓòÉΓòÉ

Steps:

o Select the event, from the Defined Events list box, that you want to be a
  dependency of the current task.

o Click on the Add>> button.

If the task is already listed in the Dependencies list box, ATS will just beep.

If you did not select a task from the Defined Events list box, ATS will just
beep.

If the selected event is not already in the Dependencies list box, ATS will add
the event as a dependency of the current task and add it to the Dependencies
list box.


ΓòÉΓòÉΓòÉ 20.2. Removing A Dependency ΓòÉΓòÉΓòÉ

Steps:

o Select the event, from the Dependencies list box, that you want to remove.

o Click on the Remove<< button.

If you did not select a task from the Dependencies list box, ATS will just
beep.

ATS will remove the event as a dependency of the current task and remove it
from Dependencies list box.


ΓòÉΓòÉΓòÉ 20.3. Defining An Event ΓòÉΓòÉΓòÉ

Clicking on the Define Event button on the Define Task Dependencies screen will
bring up the Define Events screen. You can add new events, delete existing
events, or edit existing events. When you return to the Define Task
Dependencies screen, the Defined Events list box and the Dependencies list box
will be refreshed.

If an event is deleted, it is removed as a dependency from all tasks.


ΓòÉΓòÉΓòÉ 21. Define Tasks ΓòÉΓòÉΓòÉ

To display the Task Selection screen:

o Select Edit from the main ATS menu.

o Select Tasks from the Edit menu.

The keyboard short cut key is: Ctrl+S.

Defining Tasks

o Adding A New Task

o Editing An Existing Task

o Deleting An Existing Task

o Task Definition Elements

Related Topics:

o Define Events
o Define Dependencies


ΓòÉΓòÉΓòÉ 21.1. Adding A New Task ΓòÉΓòÉΓòÉ

Click on the New Task button on the Task Selection screen. When you select this
option, the Define Task screen will be brought up. If no tasks are defined when
you select the Schedule Tasks option on the Edit menu of the main ATS window,
this screen will be bypassed and the Define Task screen will be brought up
directly.


ΓòÉΓòÉΓòÉ 21.2. Deleting An Existing Task ΓòÉΓòÉΓòÉ

Steps:

o Select a task by clicking on it in the Task Selection list box.

o Click on the Delete Task button.

If the "Warn on Delete" option on the Preferences screen was selected, a
message box will appear asking you to confirm the deletion.

If "Warn on Delete" is off or if you answered yes to the deletion confirmation,
the event will be removed from the ATS task list and the entry will be removed
from the Task Selection list box.


ΓòÉΓòÉΓòÉ 21.3. Editing An Existing Task ΓòÉΓòÉΓòÉ

Steps:

o Select a task by clicking on it in the Task Selection list box.

o Click on the OK button.

Double clicking on the entry in the Task Selection list box is the same as
doing both of the above steps.


ΓòÉΓòÉΓòÉ 21.4. Task Definition Elements ΓòÉΓòÉΓòÉ

Task Name

Task Name is the name given to a particular task by the user. This name must be
unique among all tasks. The Task Name can be up to 12 characters long. This
field is required for all task definitions.

Day of Week

You can select the days of the week that you want the task to be allowed to
run. You can further define if the task should run if the particular day of the
week is a holiday, if it is not a holiday, or regardless of its holiday status.
If you have set the slider to "Don't Run", then even if all of the dependencies
for this task are satisfied, the task will not be initiated. If you have set
the slider to "Run", then if all of the dependencies for this task are
satisfied, the task will be initiated. If you have set the slider to "Holiday",
then if all of the dependencies for this task are satisfied and the day of the
week falls on a defined holiday, the task will be initiated. If you have set
the slider to "Non-Holiday", then if all of the dependencies for this task are
satisfied and the day of the week does not fall on a defined holiday, the task
will be initiated.

If you set all of the days of the week to "Don't Run", a warning message will
be displayed informing you that the task will never run.

Valid Months

You can select which months a particular task is allowed to run in. If the
radio button to the left of the months abbreviation is selected, the task is
eligible to run in that month. If the month is not selected, if all of the
other criteria for running the job are satisfied, the job will not be invoked.

If you fail to select any month, a warning message will be displayed informing
you that the task will never run.

Dates and Times

You can specify the hours during the day that a particular task can be
initiated. If all of the other criteria are satisfied but the current time is
not within the start/end time range, the task will not be started. The start
and end times can be from 00:00 to 23:59. The start time does not have to be
earlier than the end date. If it is not, then the time range will be assumed to
span midnight.

You can specify the dates that a particular task can be initiated. If all of
the other criteria are satisfied but the current date is not within the
start/end date range, the task will not be started. The start and end dates can
be from 01/01/1993 to 12/31/2025. The start date must be before the end date or
a warning message will be displayed.

The allowed date and time ranges are independent of each other.

Refer to Section 10. Invoking Tasks for more information on how the date and
time fields are used to determine when a task will be started.

Day of Month

You can select the days of the month that you want the task to be allowed to
run. You can further define if the task should run if the particular day of the
month is a holiday, if it is not a holiday, or regardless of its holiday
status. If you have set the slider to "Don't Run", then even if all of the
dependencies for this task are satisfied, the task will not be initiated. If
you have set the slider to "Run", then if all of the dependencies for this task
are satisfied, the task will be initiated. If you have set the slider to
"Holiday", then if all of the dependencies for this task are satisfied and the
day of the month falls on a defined holiday, the task will be initiated. If you
have set the slider to "Non-Holiday", then if all of the dependencies for this
task are satisfied and the day of the month does not fall on a defined holiday,
the task will be initiated.

There are 5 special days of the month. They are 1) "L" the last day of the
month, 2) "LB" the last business day of the month, 3) "FB" the first business
day of the month, 4) "B15" the last business day of the month before the 15th,
and 5) "A15" the first business day of the month after the 15th. Saturdays,
Sundays, and holidays are considered to be non-business days.

If you set all of the days of the month to "Don't Run", a warning message will
be displayed informing you that the task will never run.

Program Details

Program Name is the drive, path, and name of the executable associated with
this task that is to be run when all of the dependencies for the task are
satisfied. The drive, path and name can contain a maximum of 255 characters.
This field is required for all tasks.

Parameters is a string that is passed to the executable when it is invoked by
ATS. The Parameters field can contain a maximum of 255 characters. This field
is optional.

Working Directory is the drive and path where the executable will be invoked
from. The drive and path can contain a maximum of 255 characters. This field is
optional.

Session Type

You must select how the task should be run. The options are Full Screen, OS/2
Window, PM, or CMD File. Additionally, you can specify that the program be run
in the background. If you do not select the background option, ATS will attempt
to make the executed task the active session. Sometimes this is not possible.

Independent Session

You must also decide if the task should run as a child process of ATS or as an
independent session. If the task runs as a child of ATS, then when the program
ends, the system will notify ATS and provide the return code from the scheduled
task. ATS will use this information to signal any dependent tasks, remove the
item from the Running Tasks window, and place an entry in the ATS log
indicating that the task has ended.

Independent tasks are recorded in the ATS log and in the Running Tasks window.
However, because the system does not notify ATS when the task ends, they are
not removed from the Running Tasks window and no termination entry is placed in
the ATS log. Because ATS can not determine when an independent session has
ended, it is recommended that all scheduled tasks be run as child processes
unless it is absolutely necessary to run it as an independent session.

If ATS is terminated, whether normally or abnormally, any task that is a child
of ATS will be terminated by the system. If there are active child tasks
running and a user attempts to shut down ATS, ATS will display a warning
message.

Dependencies

The Dependencies box on the ATS Task Edit screen displays the number of
dependencies, by type, that the current task has. The information in this box
is for display only and can not be changed by the user.

Edit Dependencies

Clicking on the Dependencies button will bring up the ATS Define Task
Dependencies dialog box. This screen is used to link events with the current
task. For further information, refer to Section 7. Dependencies.

Concurrent Occurrences

The Concurrent Occurrences field is used to limit how many concurrent
occurrences of this task ATS can invoke. i.e. If this number is set to 1 and
the task is active, even if all of the dependencies and other criteria are
satisfied, ATS will not invoke the transaction. This does not apply to
independent sessions since ATS does not know if the task is truly active.

If you set this value to 0 (zero), then ATS will never invoke this task. This
can be used as a way of archiving a task for a period of time without having to
remove it from ATS and then rebuild it at a later date. This does apply to
independent tasks.


ΓòÉΓòÉΓòÉ 22. Invoking Tasks ΓòÉΓòÉΓòÉ

ATS will attempt to invoke tasks either when the clock timer or file timer
elapse. ATS will perform the following steps to determine if a task should be
invoked:

o Determine if another occurrence of the task can be invoked.
o Determine if the current date is within the specified date range.
o Determine if the current time is within the specified time range.
o Determine if all dependencies are satisfied.
o Determine if the task can be run on the current day of the week.
o Determine if the task can be run on the current day of the month.
o Determine if the task can be run in the current month.

After invoking a task, ATS will unflag all dependent events for the started
task. If an event is a dependency of more than one task, only the event for the
invoked task is unflagged. The flag indicating that an event has occurred is
maintained at a task level.

Considerations

The date range and time range are independent of each other. They define the
days and time of day that ATS is allowed to run the task.

For example, if you set the start date to 11/14/1993 and the end date to
12/21/1993 then even if all of the other criteria for initiating the task are
satisfied, ATS will not start the task if the current system date is not within
the specified date range. Likewise, if you set the start time to 10:00 and the
end time to 11:00, then ATS will only start the task if the current system time
is between 10:00 and 11:00.

Short Running Tasks with No Dependencies

Because of the robustness of ATS, short running tasks present a problem. The
problem is that the task might be initiated multiple times even if that is not
what you had wanted.

For a particular task, assume that you set the start time to 13:00 and the end
time to 13:00. You would assume that ATS will only star that task if the
current clock reading is 13:00. However, this is not totally true. Since the
computer that ATS runs on allows anyone with keyboard access to adjust the
system clock, ATS had to be designed to ensure that every job that is supposed
to run does even if the system clock is changed. In order to handle this, each
time ATS checks the system clock, it will initiate any task that has a start
time that falls between the current system clock time and the system clock time
from the previous check. This also allows you to set the check interval to 10
minutes and not worry that a particular task will not get started because its
start time did not exactly match a system clock reading.

The problem for short running tasks with no dependencies is as follows. Assume,
once again, that the start time for the task is 13:00 and the end time is 13:00
and you have set the clock check interval on the Options/Timers screen to 30
seconds. The task that is being initiated runs for only 5 seconds. At 13:00:04
ATS checks your task and decides that all of the criteria to run the task are
satisfied (i.e. day, month, date...) so it starts it. At 13:00:09, the task
ends. At 13:00:34, ATS once again checks your task and since it is still 13:00,
decides that all of its criteria to run are still satisfied and initiates it
again. At 13:01:04, ATS again checks your task. Now, remember that ATS will
start any task whose valid start time range falls between the previously
checked system clock time and the current system clock time. Since 13:00 is
definitely between 13:00:34 and 13:01:04, ATS will start your task again.

Therefore, it is recommended that any job that may run for less than one minute
have some dependency.

MHR Software and Consulting understand that this is not the optimal solution
and will be adding to the next release the ability to specify how often within
a given period of time a particular may be started. The given period of time
may be specified in minutes, hours, calendar days, weeks, months and years.
Until then please be careful when scheduling short running tasks.


ΓòÉΓòÉΓòÉ 23. System Configuration ΓòÉΓòÉΓòÉ

The System Configuration screens allow the user to customize ATS to suit their
particular needs.

Related Topics:

o Preferences
o Timers


ΓòÉΓòÉΓòÉ 23.1. Preferences ΓòÉΓòÉΓòÉ

There are six user configurable options on the Preferences screen. These
options control how ATS interacts with the user.

To display the Preferences screen:

o Select Edit from the main ATS menu.

o Select System Configuration from the Edit menu.

o Select Preferences from the Options menu.

The keyboard short cut key is: Ctrl+P.

Adjusting Preferences

Clicking on the OK button will save the changes that you made and dismiss the
Preferences dialog box. If the "Warn on Edit" option on the Preferences screen
was previously selected, a message box will appear asking you to confirm the
changes.

Clicking on the Cancel button will dismiss the Preferences dialog box. If any
changes were made, a message box will appear asking you if you really want to
exit without saving your changes.

Clicking on the Default button will reset all of the options to their default
value. Refer to the following sections for the default values.

Preferences:

o Warn On Edit
o Warn On Delete
o Sound
o Truncate Log On Startup
o Save Screen Positions Upon Exit
o On Line Log Size

Related Topics:

o Timers


ΓòÉΓòÉΓòÉ 23.1.1. Warn On Edit ΓòÉΓòÉΓòÉ

Turning this on will cause a warning box to appear each time you try to save an
event, task, or holiday that has been modified before the changes are committed
to the ATS data file.

The default value is on.


ΓòÉΓòÉΓòÉ 23.1.2. Warn On Delete ΓòÉΓòÉΓòÉ

Turning this on will cause a warning box to appear each time you try to delete
an event, task or holiday before the object is actually deleted from the ATS
data file.

The default value is on.


ΓòÉΓòÉΓòÉ 23.1.3. Sound ΓòÉΓòÉΓòÉ

ATS will beep when certain things happen. These include task initiation, task
termination, file modification, etc. If this option is not selected, ATS will
not beep in these cases.

The default value is on.

Note:  ATS will always beep when a error or warning message box is displayed on
       the screen.


ΓòÉΓòÉΓòÉ 23.1.4. Truncate Log On Startup ΓòÉΓòÉΓòÉ

Each time ATS is started, the currently selected log file is opened up. If this
option is selected, all of the entries in the log file will be deleted before
any new entries are added. If this option is not selected, the new log entries
are appended to the end of the current log file.

The default value is off.


ΓòÉΓòÉΓòÉ 23.1.5. Save Positions Upon Exit ΓòÉΓòÉΓòÉ

If this option is selected, when ATS is shut down, the physical size and
location of the ATS main window are saved as are the states of the three
display windows, refer to Section 10. Display Windows for further information.
If this option is selected, when ATS is started, it will be restored to the
same state it was in when it was last shutdown. If this option is not selected,
when ATS is started, it will be in the size and location as provided and no
display windows will be opened.

The default value is off.


ΓòÉΓòÉΓòÉ 23.1.6. On Line Log Size ΓòÉΓòÉΓòÉ

All of the entries that are written out to the ATS log file are also stored in
memory and optionally displayed in the ATS Log display window. This parameter
allows you to select how much RAM is used to store the log file. When the
on-line log file is full, ATS will clear it and start fresh.

The default value is 3K.


ΓòÉΓòÉΓòÉ 23.2. Timers ΓòÉΓòÉΓòÉ

There are two timers that are user configurable that control how often ATS
checks whether or not to run a job.

To display the Timers screen:

o Select Edit from the main ATS menu.

o Select System Configuration from the Edit menu.

o Select Timers from the Options menu.

The keyboard short cut key is: Ctrl+T.

Adjusting Timers

Clicking on the OK button will save the changes that you made and dismiss the
Timers dialog box. If the "Warn on Edit" option on the Preferences screen was
selected, a message box will appear asking you to confirm the changes.

Clicking on the Cancel button will dismiss the Timers dialog box. If any
changes were made, a message box will appear asking you if you really want to
exit without saving your changes.

Clicking on the Default button will reset all of the options to their default
value. Refer to the following sections for the default values.

Timers:

o File Check Interval
o Clock Check Interval

Related Topics:

o Preferences


ΓòÉΓòÉΓòÉ 23.2.1. File Check Interval ΓòÉΓòÉΓòÉ

The File Check Interval is used by ATS to determine how often to check to see
if a file has been modified. This value can range from 30 seconds to 10 minutes
in thirty second intervals.

The default value is 1 minute.


ΓòÉΓòÉΓòÉ 23.2.2. Clock Check Interval ΓòÉΓòÉΓòÉ

The Clock Check Interval is used by ATS to determine how often to check to see
if any task should be started. This value can range from 30 seconds to 10
minutes in thirty second intervals.

The default value is 1 minute.


ΓòÉΓòÉΓòÉ 24. Interfaces to ATS ΓòÉΓòÉΓòÉ

ATS comes with two programs that interface with it to set and reset Signal
Events. ATS also comes with all of the necessary files to allow you to write
your own programs to interface with ATS.

o ATSSGNL.EXE sets Signal Events.

o ATSRSET.EXE resets Signal Events.

o ATSSGNLD.DLL contains routines that can be called from your program to set
  Signal Events.

o ATSRSETD.DLL contains routines that can be called from your program to reset
  Signal Events.

Related Topics:

o ATSSGNL.EXE
o ATSRSET.EXE
o ATSSGNLD.DLL
o ATSRSETD.DLL


ΓòÉΓòÉΓòÉ 24.1. ATSSGNL.EXE ΓòÉΓòÉΓòÉ

ATSSGNL is a supplied executable that will flag a Signal Event as having
occurred.  The syntax for ATSSGNL is as follows:

ATSSGNL eventname

where eventname is the name of the event that you want to signal to ATS as
having occurred.

Note:  ATS is case sensitive.  If you create an event in upper, lower, or mixed
       case, you must supply the event name in the same case to the ATSSGNL command.

Related Topics:

o ATSRSET.EXE
o ATSSGNLD.DLL
o ATSRSETD.DLL


ΓòÉΓòÉΓòÉ 24.2. ATSRSET.EXE ΓòÉΓòÉΓòÉ

ATSRSET is a supplied executable that will reset all Signal Event dependencies
for a given task, reset a specific Signal Event for all tasks that are
dependent upon it, or reset a specific Signal Event for a particular task.  The
syntax for ATSRSET is as follows:

ATSRSET T taskname

ATSRSET E eventname

ATSRSET B taskname eventname

where taskname is the name of the task that you want affected eventname is the
name of the event that you want affected.

ATSRSET works as follows.  If you specify ATSRSET T taskname, all Signal Events
for the named task will be reset as if they have not occurred.  If you specify
ATSRSET E eventname, the named Signal Event will be reset for all tasks that
are dependent upon it as if it had not occurred.  If you specify ATSRSET B
taskname eventname, the named Signal Event will be reset for the named task as
if it had never occurred.

Note:  ATS is case sensitive.  If you create an event and/or task in upper,
       lower, or mixed case, you must supply the event name and/or task name in
       the same case to the ATSRSET command.

Related Topics:

o ATSSGNL.EXE
o ATSSGNLD.DLL
o ATSRSETD.DLL


ΓòÉΓòÉΓòÉ 24.3. ATSSGNLD.DLL ΓòÉΓòÉΓòÉ

ATSSGNL is a dynamic link library that contains one API. The format of the API
is as follows:

ATSSignalEvent(char[]);

ATSSignalEvent returns a ULONG.  and expects a null terminated string as input.
The null terminated string is the name of the Signal Event that is to be
flagged as having occurred.

Note:  ATS is case sensitive.  If you create an event in upper, lower, or mixed
       case, you must supply the event name in the same case to the
       ATSSignalEvent API.

The possible return codes that ATSSignalEvent returns are listed in ATSSGNL.H.

ATSSignalEvent provides the same functionality as ATSSGNL but has the
flexibility of being inserted into a custom program.

Related Topics:

o ATSSGNL.EXE
o ATSRSET.EXE
o ATSRSETD.DLL


ΓòÉΓòÉΓòÉ 24.4. ATSRSETD.DLL ΓòÉΓòÉΓòÉ

ATSRSET is a dynamic link library that contains one API.  The format of the API
is as follows:

ATSReset(short, char[]. char[]);

ATSReset returns a ULONG.  and expects a short and two null terminated string
as input.  The short is the action code.  The first null terminated string is
the name of the Signal Event if the action code is ATS_RESET_EVENT or the name
of the task if the action code is either ATS_RESET_TASK or ATS_RESET_LINK
(ATS_RESET_LINK will rest a specific Signal Event for a particular task).The
second null terminated string is the name of the Signal Event if the action
code is ATS_RESET_LINK or a null string if the action code is either
ATS_RESET_TASK or ATS_RESET_EVENT.

Note:  ATS is case sensitive.  If you create an event and/or task in upper,
       lower, or mixed case, you must supply the event name and/or task name in
       the same case to the ATSReset API.

The possible return codes that ATSReset returns are listed in ATSRSET.H.

ATSReset provides the same functionality as ATSRSET but has the flexibility of
being inserted into a custom program.

Related Topics:

o ATSSGNL.EXE
o ATSRSET.EXE
o ATSSGNLD.DLL