═══ 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 (908) 821-0359. ═══ 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 (908) 821-0359. ═══ 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