OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / progs / ats / userguid.txt < prev

Wrap

Text File | 1993-09-28 | 62.3 KB | 1,521 lines

ATS FOR OS/2 Version 2 Users Guide MHR Software And Consulting can be reached by phone at (908) 821-0359 or by mail at 2227 U.S. Highway # 1 Suite 146 North Brunswick, New Jersey 08902 ATS for OS/2 is a valuable trade secret of MHR Software And Consulting and is not to be used or disseminated in any manner, or by any means whatsoever, without the express written consent of MHR Software And Consulting. OS/2 is a registered trademark of the International Business Machines Corporation Copyright * 1993, MHR Software And Consulting. All Rights Reserved. Table Of Contents 1. Introduction 1 2. System Configuration 5 2.1. Preferences 5 2.2. Timers 7 3. Holidays 11 3.1. Adding a New Holiday 11 3.2. Deleting an Existing Holiday 12 3.3. Editing an Existing Holiday 12 4. Events 15 4.1. Types of Events 15 4.2. Event Characteristics 17 4.3. Adding a New Event 18 4.4. Deleting an Existing Event 18 4.5. Editing an Existing Event 19 5. Tasks 21 5.1. Task Selection 21 5.2. Task Characteristics 23 6. Dependencies 31 6.1. Adding a New Dependency 31 6.2. Remove an Existing Dependency 32 6.3. Define Event 32 7. Signal Event 33 7.1. Signaling an Event 33 8. Invoking Tasks 35 8.1. Overview 35 8.2. Dates and Times 35 8.3. Short Running Tasks with No Dependencies 36 9. Logging 39 9.1. Log File 39 9.2. Log Comment 40 10. Display Windows 43 10.1. ATS Log 43 10.2. ATS Status 43 10.3. ATS Running Tasks 44 10.4. Tiling 45 11. Signaling Events from Outside of ATS 47 11.1. ATSSGNL.EXE 47 11.2. ATSRSET.EXE 47 11.3. ATSSGNLD.DLL 48 11.4. ATSRSETD.DLL 48 12. Reports 51 12.1. Defined Holidays 51 12.2. Defined Events 51 12.3. Defined Tasks 52 Appendices 53 A. Glossary 55 B. Shutting Down ATS from Outside of ATS 57 C. Shortcut Keys 59 D. Installing and Running ATS 61 E. Supplied Files 63 F. Watchdog 65 G. Problem Reporting 67 1. Introduction 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: * Build complete job streams. * Define any day to be a holiday. * Define if a job should run on a holiday, not run on a holiday or run either way. * Define what day of the week a job can run. * Define what day of the month a job can run. * Define what months a job can run. * Define what hours of the day a job can run. * Define a date range that a job can run within. * 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. * Define if the job should run in a window, full screen or as a Presentation Manager application. * Define a job to be dependent upon the completion of one or more scheduled jobs. * Define a job to be dependent upon one or more files being created or modified. * Define a job to be dependent upon the receipt of one or more external signals. * Logs all activity to a file and an on-line window. * 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 * a menu option on the ATS main window. ATS offers two different ways to clear the flag that indicates that an event has occurred. They 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. 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 (908) 821-0359. 2. System Configuration ATS allows you to customize how ATS interfaces with you as well as how often ATS should check to see if any dependent files have been modified or if any tasks should be started. Selecting Preferences from the System Configuration menu displays a dialog box that lets you customize the on-line interface. Selecting Timers from the System Configuration menu displays a dialog box that lets you customize how often ATS should check to see if any dependent files have been modified or if any tasks should be started. 2.1. Preferences There are six user configurable settings on the Preferences screen. These settings control how ATS interacts with the user. To display the Preferences screen: * Select Edit from the main ATS menu. * Select System Configuration from the Edit menu. * Select Preferences from the System Configuration menu. The keyboard short cut key is: Ctrl+P. 2.1.1. Adjusting Preferences Clicking on the box to the left of the Preference choice will turn on or off that option. If a small check mark appears in the box, the option is selected (i.e. on) if there is no check mark, the option is not selected (i.e. off). 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. 2.1.2. 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. 2.1.3. 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. 2.1.4. 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. 2.1.5. 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 each time ATS is started. 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. 2.1.6. Save Screen 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 not , when ATS is started, it will be in the default size and location and no display windows will be opened. The default value is off. 2.1.7. 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. Adjusting The Size Of The On-Line Log There are two ways that you can adjust the size of the on-line log. The first method is to click with the right mouse button on one of the two small arrows to the right of the ruler. This will cause the button that is on the ruler to move. The second method is to click on the button that is on the ruler and slide it to the left or the right. As the button moves, the size of the on-line log will be updated and displayed in the text window above the ruler. 2.2. Timers There are two user configurable timers that control how often ATS checks whether or not to run a job and whether or not any of the dependent files have been modified. They are, respectively, the Clock Check Interval Timer and the File Check Interval Timer. When the Clock Check Interval Timer elapses, ATS examines each of the scheduled tasks to determine if it should invoke them at the current time. If all of the criteria for starting that task are satisfied, ATS will start the task. Refer to Section 5.2 Task Characteristics and Section 8 Invoking Tasks for more detailed information about task starting criteria. When the File Check Interval Timer elapses, ATS examines the OS/2 file systems statistics of each of the files that is defined in a File Modification Event. If the file previously did not exist or if the statistics of the file have changed and ATS is able to open the file for both reading and writing, the File Modification Event that is associated with the examined file is flagged as having occurred. Refer to Section 4 Events for more detailed information about File Modification Events. To display the Timers screen: * Select Edit from the main ATS menu. * Select System Configuration from the Edit menu. * Select Timers from the System Configuration menu. The keyboard short cut key is: Ctrl+T. 2.2.1. Adjusting Timers There are two ways that you can adjust the Clock Check Interval Timer and the File Check Interval Timer. The first method is to click with the right mouse button on one of the two small arrows to the right of the ruler. This will cause the button that is on the ruler to move. The second method is to click on the button that is on the ruler and slide it to the left or the right. As the button moves, the time interval that is associated with the particular timer will be updated and displayed in the text window above the appropriate ruler. 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. 2.2.2. 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. 2.2.3. 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. 3. Holidays ATS uses Holidays to determine when to run a scheduled task. A task can be scheduled to run on any combination of days of the week and days of the month. In addition, a task can be scheduled to run on a particular day (of the week or month) if that day falls on a defined holiday, if it does not fall on a defined holiday or regardless of if it falls on a defined holiday. Refer to Section 5.2 Task Characteristics for a more detailed explanation of how to schedule a task. A Holiday definition consists of a date, a name, and a day of the week. Any day of the year can be defined as a Holiday. You can define an unlimited number of Holidays. To display the Define Holidays screen: * Select Edit from the main ATS menu. * Select Holidays from the Edit menu. The keyboard short cut key is: Ctrl+H. 3.1. Adding a New Holiday * 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"). * Enter a valid date in the Date field. Note: ATS will validate the date when you click on the OK button. * Enter text in the Holiday field that describes the holiday. You can enter a maximum of 32 characters. * 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 window will be set, the holiday will be added to the ATS calendar, and the entry will appear in the list box. 3.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"). * Select the entry in the list box that you wish to delete. * 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. 3.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"). * Select the entry in the list that you wish to edit. * Enter a valid date in the Date field. * Enter text in the Holiday field that describes the holiday. You can enter a maximum of 32 characters. * 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. 4. Events An event, in ATS, is something that happens that a scheduled task can be dependent upon. This can be a file being modified (File Modification Event), the completion of a task that was scheduled through and initiated by ATS (Task Completion Event), or notification that something has occurred (Signal Event). ATS uses events as one of the criteria to base its initiation of scheduled tasks. To display the Define Events screen: * Select Edit from the main ATS menu. * Select Events from the Edit menu. The keyboard short cut key is: Ctrl+E. 4.1. Types of Events 4.1.1. Job Termination Event 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 job ends with a return code that 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. Refer to Section 5.2 Independent Session for more information about the differences between child processes and independent sessions. 4.1.2. File Modification Event 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 Interval timer. If the associated file does not exist when ATS is started, then when it is created and is available for reading and writing ATS will, the next time the File Check Interval elapses, flag the event as having occurred. ATS uses the files last update date and time and file size statistics to determine if a file has been updated. 4.1.3. Signal Event A Signal Event is an event that will be flagged as having occurred when a signal is received from one of the following sources: * a supplied API that has been incorporated into an independently developed application program * a supplied executable, ATSSGNL.EXE, that has been executed at an OS/2 command line or from within a REXX or OS/2 Command procedure * user interaction with the Signal Event menu option on the ATS main window ATS allows you to clear the flag that indicates that an event has occurred. ATS will clear the flag when a signal is received from one of the following sources: * a supplied API that can be incorporated into an independently developed application program * a supplied executable, ATSRESET.EXE that can be executed at an OS/2 command line or from within a REXX or OS/2 Command procedure. Refer to Section 11 Signaling Events From Outside Of ATS for further information about using the supplied executables or API's. 4.2. Event Characteristics 4.2.1. Common Event Name The name given to a particular event by the user. This name must be unique among all events defined to ATS. 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. This field is required for all event definitions. 4.2.2. Job Termination Event Specific 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 Job Termination Event can not be defined to be a dependency of the task of which it is dependent upon. This field is only required for Job Termination events. 4.2.3. File Modification Event Specific 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. 4.2.4. Signal Event Specific There are no additional required fields for Signal Events. 4.3. 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"). * Fill in the required fields as described in Section 4.2 Event Characteristics. * Click on the Add button. * If the name that you entered is already defined or a required field, as defined in Section 4.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. 4.4. 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"). * Select the entry in the Events list box that you wish to delete. * 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. 4.5. 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"). * Select the entry in the Events list box that you wish to edit. * Enter the changes that you want, insuring that you fill in all of the required fields as described above in Section 4.2 Event Characteristics. * 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 4.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. 5. Tasks A Task is a program that you wish to schedule to be automatically started by ATS. 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 based upon any combination of the following: * time of day * day of the week * month * day of the month * holidays or non-holidays * dependencies 5.1. Task Selection To display the Task Selection screen: * Select Edit from the main ATS menu. * Select Tasks from the Edit menu. The keyboard short cut key is: Ctrl+S. 5.1.1. Adding a New Task To add 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. Note: If no tasks are currently defined, selecting the Schedule Tasks option on the Edit menu of the main ATS window will cause this screen to be by passed and the Define Task screen will be brought up directly. 5.1.2. Deleting an Existing Task * Select a task by clicking on it in the Task Selection list box. * 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. 5.1.3. Editing an Existing Task * Select a task by clicking on it in the Task Selection list box. * 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. 5.2. Task Characteristics Task Name The name given to a particular task by the user. This name must be unique among all tasks defined to ATS. The Task Name can be up to 12 characters long. This field is required for all task definitions. Day of Week Defines 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. You can change the setting for a particular day of the week two ways. The first method is to click with the right mouse button on one of the two small arrows below the ruler. This will cause the button that is on the ruler to move. The second method is to click on the button that is on the ruler and slide it up or down. If you have set the slider to "Don't Run", then this task is not eligible to run on the associated day of the week. If you have set the slider to "Run", then this task is eligible to run on the associated day of the week. If you have set the slider to "Holiday", then if the associated day of the week falls on a defined holiday, the task is eligible to run. If you have set the slider to "Non-Holiday", then if the associated day of the week falls on a day that is not defined as a holiday, the task is eligible to run. 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. The following chart summarizes when a task is eligible to run based upon the setting of the slider. +====================================================================+ | SliderSetting Current day of the Current day of the | | week is a holiday week is not a holiday | | ------------- ------------------ --------------------- | | Non-Holiday Can't Run Can Run | | Holiday Can Run Can't Run | | Run Can Run Can Run | | Don't Run Can't Run Can't Run | +====================================================================+ Valid Months Defines the months that you want the task to be allowed to run. 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, the task is not eligible to run in that month. Click on the button to the left of the month's abbreviation to select or deselect the month. If you fail to select any month, a warning message will be displayed informing you that the task will never run. Dates and Times Defines the hours during the day that you want the task to be allowed to run as well as the dates that you want the task to be allowed to run. 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 time. If it is not, then the time range will be assumed to span midnight. 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. To change the start or end date, click on the day, month, or year and then click on the up or the down arrow to the left of the year field. To change the start or end time, click on the hour or minute and then click on the up or the down arrow to the left of the minute field. Refer to Section 8 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 Defines the months 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. You can change the setting for a particular day of the month two ways. The first method is to click with the right mouse button on one of the two small arrows below the ruler. This will cause the button that is on the ruler to move. The second method is to click on the button that is on the ruler and slide it up or down. If you have set the slider to "Don't Run", then this task is not eligible to run on the associated day of the month. If you have set the slider to "Run", then this task is eligible to run on the associated day of the month. If you have set the slider to "Holiday", then if the associated day of the month falls on a defined holiday, the task is eligible to run. If you have set the slider to "Non-Holiday", then if the associated day of the month falls on a day that is not defined as a holiday, the task is eligible to run. Refer to the chart under Day of Week above for a summarization of when a task is eligible to run based upon the setting of the slider. There are five 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. For these five special days, 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. The parameter string may contain imbedded ATS variables which will be replaced by ATS at run time. These variables allow you to pass the following information to the scheduled task: current (execution) date, current time, day of week, holiday indicator, and task name. Each of these variables can be passed in various formats. The chart below defines the syntax and output of each option. This field is optional. Variable Syntax Output Date !DI 1991-10-27 !Di 91-10-27 !DU 10/27/1991 !Du 10/27/91 !DE 27.10.1991 !De 27.10.91 !DJ 1991-10-27 !Dj 91-10-27 Time !TI 13.30.05 !Ti 13.30 !TU 01:30 PM !Tu 01:30 !TE 13.30.05 !Te 13.30 !TJ 13:30:05 !Tj 13:30 Day Of Week !XA SUN !Xa Sun !XF SUNDAY !Xf Sunday !XN 0 (Sun = 0, Sat = 6) !X1 1 (Sun = 1, Sat = 7) Holiday !HN 1 if holiday, 0 if not !Hn 1 if holiday, 0 if not !HA H if holiday, N if not !Ha h if holiday, n if not Task Name !N TASK NAME !n Task Name Exclamation Mark !! ! 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 Defines how the task should be run. The options are Full Screen, OS/2 Window, or PM. If the program to be run is a OS/2 Command Procedure or a REXX program, then the CMD File option should be selected. 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 Defines 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, a warning message will be displayed. Events This is an information only box on the ATS Task Edit screen that 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. 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 6 Dependencies. Concurrent Occurrences Defines the limit of how many concurrent active occurrences of a scheduled 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. 6. 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. You use this screen to link events to tasks. To display the Define Task Dependencies screen: * Select Edit from the main ATS menu. * Select Tasks from the Edit menu. The keyboard short cut key for the above steps is: Ctrl+S. * Select the task that you want to add/edit/delete dependencies for. * Click on the Dependencies button. 6.1. Adding a New Dependency * Select the event, from the Defined Events list box, that you want to be a dependency of the current task. * Click on the Add>> button. * If the task is already listed in the Dependencies list box, ATS will beep. * If you did not select a task from the Defined Events list box, ATS will 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. 6.2. Remove an Existing Dependency * Select the event that you want to remove from the Dependencies list box. * Click on the Remove>> button. * If you did not select a task from the Dependencies list box, ATS will beep. * ATS will remove the event as a dependency of the current task and remove it from Dependencies list box. 6.3. Define 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 that it had been associated with. 7. Signal Event 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. 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. Refer to Section 11 Signaling Events from Outside of ATS for more information about the other methods. To display the Signal Event screen: * Select Signal Event from the main ATS menu. The keyboard short cut key is: Ctrl+G. 7.1. Signaling an Event * Select the event from the Events list box. * Click on the Signal button. * 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. 8. Invoking Tasks 8.1. Overview ATS uses the user configurable timers to determine when to check to see if any scheduled tasks need to be initiated. When the Clock Check Interval Timer elapses, ATS scans all of the scheduled tasks to see if any should be started and then waits for the timer to elapse again. When the File Check Interval Timer elapses, ATS first checks the statistics of all of the files that are associated with File Modification Events and updates the status of those events appropriately. ATS then scans all of the scheduled tasks to see if any should be started and then waits for the timer to elapse again. In order for ATS to determine if a task should be invoked, it will check if: * another occurrence of the task can be invoked * the current date is within the specified date range * the current time is within the specified time range * all dependencies are satisfied * the task can be run on the current day of the week * the task can be run on the current day of the month * the task can be run in the current month After invoking a task, ATS will reset all dependent events for the started task. If an event is a dependency of more than one task, the event is reset only for the invoked task. The flag indicating that an event has occurred is maintained at a task level. 8.2. Dates and Times 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. 8.3. 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 start that task if the current clock reading is 13:00. This is not totally true and it does not mean that ATS will only run the task only once. 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. Also, since the user configurable timers can be set to elapse as far apart as every ten minutes, it is likely that the timers will not elapse on the exact minute that a job is scheduled to run on. In order to handle these conditions, 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 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 Timer to 30 seconds. The task that is being initiated will only run for 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 at least one dependent event. One way to schedule a short running task and insure that it only runs once a day at a certain time is as follows: Schedule your task as you normally would specifying all of the criteria required. The start time and end time of the task do not have to be the same but they probably should be. Create a new Signal Event. This event will be used become a dependency of your task. Schedule another task to run with all of the same criteria as before but set the start time and end time to the same value. This time must be earlier than the start time of the other task by the larger of the Clock Check Interval and the File Check Interval plus 1 minute. If you set the start time of this task to be eleven minutes earlier than the start time of the other task you will always be safe. The program that this new task will run is ATSSGNL.EXE and its input parameter will be the name of the Signal Event that you created above. Make the first task, the one that you want to insure only runs once, to be dependent upon the Signal Event that you created above. The task that runs ATSSGNL.EXE will run twice. But, since setting a Signal Event more than once has no effect, this is no problem. MHR Software and Consulting understands 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 task may be started. ATS will allow you to specify the given period of time in minutes, hours, calendar days, weeks, months and years. Until then please be careful when scheduling short running tasks. 9. Logging 9.1. Log File To display the Log File screen: * Select File from the main ATS menu. * Select Log File from the File menu. The keyboard short cut key is: Alt+F. 9.1.1. 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 one. 9.1.2. 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 one that was just closed. 9.2. Log Comment 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: * Select File from the main ATS menu. * Select Log Comment from the File menu. The keyboard short cut key is: Alt+F. 9.2.1. Inserting Comments Into the Log File * Enter any text that you wish into the entry field. You can enter a maximum of 116 characters per log entry. * If you wish to add more than one comment, click on the Add button. * If you wish to add the current comment and dismiss the dialog box click on the Add/Quit button. * If you do not wish to add the current comment and want to dismiss the dialog box click on the Cancel button. 9.2.2. Inserting Comments Into the Log File from Outside of ATS ATS for OS/2 includes an executable named ATSTOLOG.EXE. Invoking this from an OS/2 prompt or from within a REXX or Command file will insert a record into the ATS log. This is useful if you want some or all of your scheduled jobs to write to a common log. The syntax is as follows: ATSTOLOG text where text is any text that you want included in the log. If there are any imbedded spaces in the text, enclose the entire text string in double quotes. 10. Display Windows 10.1. ATS Log The ATS Log window displays 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. Note: This does not effect the physical log file that is written to disk. To toggle the Log display window on or off: * Select Windows from the main ATS menu. * Select Log from the Windows menu The keyboard short cut key is: Alt+L 10.2. ATS Status The ATS Status window displays the current state of ATS. It provides you with all of the current ATS statistics. The status window displays the: * date and time the current ATS session was started * date and time of the latest clock check * date and time of the latest file check * current clock check interval setting * current file check interval setting * current on-line log size setting * name of the current log file * number of defined holidays * date, name and day of week of each defined holiday * number of defined events * name of each defined event and optionally the task name or file name associated with it * number of defined tasks * name and program name of each task * number of dependencies for each task * name of each dependency for each task and whether it has occurred (TRUE) or not (FALSE) To toggle the Running Tasks display window on or off: * Select Windows from the main ATS menu. * Select Status from the Windows menu The keyboard short cut key is: Alt+S 10.3. ATS Running Tasks 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: * Task Name * Start Date and Time * Session ID (000 for Independent Sessions) * 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 toggle the Running Tasks display window on or off: * Select Windows from the main ATS menu. * Select Running Tasks from the Windows menu The keyboard short cut key is: Alt+R 10.4. Tiling When you select the Tiling option on the Windows menu, ATS will divide the vertical space in the ATS screen evenly and stack each of the visible windows one on top of the other with each window being the full width of the ATS window. 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: * Select Windows from the main ATS menu. * Select Tile from the Windows menu. The keyboard short cut key is: Alt+T 11. Signaling Events from Outside of ATS 11.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 define an event name in upper, lower, or mixed case, you must supply the text in the eventname parameter in the same case to the ATSSGNL command. 11.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 and 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 define a task name in upper, lower, or mixed case, you must supply the text in the taskname parameter in the same case to the ATSSGNL command. Note: ATS is case sensitive. If you define an event name in upper, lower, or mixed case, you must supply the text in the eventname parameter in the same case to the ATSSGNL command. 11.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 define an event name in upper, lower, or mixed case, you must supply the text in the eventname parameter in the same case to the ATSSGNL command. 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. 11.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 define an event name in upper, lower, or mixed case, you must supply the text in the taskname parameter in the same case to the ATSSGNL command. Note: ATS is case sensitive. If you define an event name in upper, lower, or mixed case, you must supply the text in the eventname parameter in the same case to the ATSSGNL command. 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. 12. 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. 12.1. Defined Holidays 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 produce the Defined Holidays report: * Select Reports from the main ATS menu. * Select Defined Holidays from the Reports menu. * Select the filethat you want the report written to. * Click on the OK button. The keyboard short cut key is: Alt+H. 12.2. Defined Events 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 produce the Defined Events report: * Select Reports from the main ATS menu. * Select Defined Events from the Reports menu. * Select the filethat you want the report written to. * Click on the OK button. The keyboard short cut key is: Alt+E. 12.3. Defined Tasks 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 date and time ranges during which the task is eligible to be initiated, 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 produce the Defined Tasks screen: * Select Reports from the main ATS menu. * Select Defined Tasks from the Reports menu. * Select the filethat you want the report written to. * Click on the OK button. The keyboard short cut key is: Alt+K. Appendices A. Glossary Dependency 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. For further information, refer to Section 6 Dependencies. 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. For further information, refer to Section 4 Events. 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. For further information, refer to Section 3 Holidays. 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. For further information, refer to Section 5 Tasks. B. Shutting Down ATS from Outside of ATS ATSSTOP.EXE is an executable that will cause ATS to gracefully terminate. This executable is provided to give you the ability to stop ATS from a rexx program, command file or OS/2 prompt. It is strongly advised by MHR Software And Consulting that this feature be used with extreme caution. When ATS for OS/2 is stopped, any program that was started by ATS for OS/2, except those defined to be run in an independent session, will also be stopped. C. Shortcut Keys Alt+A Display the About screen Alt+C Display the Add Log Comment screen Alt+E Create the Events Report Alt+F Display the Log File screen Alt+H Create the Holidays Report Alt+K Create the Tasks Report Alt+L Toggle the Log display on or off Alt+R Toggle the Running Tasks display window on or off Alt+S Toggle the Status display window on or off 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. D. Installing and Running 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. To run ATS, simply type ATS at the OS/2 command Prompt. Note: When you start ATS, if you are not running Watchdog by MHR Software And Consulting a warning message will be displayed indicating that Watchdog is not active. Click on the OK button. This has no effect on the performance or functionality of ATS. This is just to remind you that if for some reason ATS terminates abnormally, it will not be automatically restarted. E. Supplied Files ATS.EXE ATS.DLL ATS.HLP ATSSTOP.EXE ATSTOLOG.EXE ATSSGNL.EXE ATSRSET.EXE ATSDLL.LIB ATSDLL.H F. 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 registers 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 (908) 821-0359. G. Problem Reporting If you encounter a problem within ATS that you feel is a bug or ATS is not functioning as described in this manual, perform the following steps to report it. 1 Write down any error messages that ATS provides. 2 Make a backup copy of the file ATS.INI. This file is located in the directory that ATS is started from. 3 Make a backup copy of the file ATS.DAT. This file is located in the directory that ATS is started from. 4 Make a backup copy of the current ATS log file. The default log file is ATS.LOG and is located in the directory that ATS is started from. 5 Print out each of the reports that ATS provides, Defined Holidays, Defined Events, and Defined Tasks. 6 Review each of the reports along with the log to insure that the problem is not an error in scheduling. 7 If the situation occurred while creating a holiday, event or task, write down the exact steps that you took leading up to the problem. 8 Try to recreate the problem. 9 Contact MHR Software And Consulting either by phone at (908) 821-0359, or on CompuServe at 70312,627. Note: If you report a problem, please be prepared to provide all of the information and results gathered in the above steps.