OS/2 Shareware BBS: SysTools

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

/ OS/2 Shareware BBS: SysTools / SysTools.zip / chrdmo.zip / CHRONMAN.TXT < prev next >

Wrap

Text File | 1994-01-17 | 68KB | 1,320 lines

Chron v4.0 An Event Dispatching Program Legalities Information in this document is subject to change without notice and does not represent a commitment on the part of Hilbert Computing. The software described in this document is furnished under a license agreement. The purchaser may make one copy of the software for backup purposes. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical including photocopying and recording for any purposes other than the purchaser's personal use, without written permission from Hilbert Computing The software and accompanying written materials are provided "as is" without warranty of any kind including implied warranties of fitness for a particular purpose. Hilbert Computing specifically is not liable for any direct, indirect, consequential, or incidental damages arising from the execution of the Chron software on your computer. Hilbert Computing 1022 N. Cooper Olathe, KS 66061 IBM(R), OS/2(R), Presentation Manager(R) and PROFS(R), DDCS/2(R) and DB2(R) are registered trademarks of International Business Machines Corporation. CUATM, Common User AccessTM , REXXTM, Workplace ShellTM and OfficeVisionTM are trademarks of International Business Machines Corporation. UnixTM is a registered trademark of Unix Systems Laboratories. VisProREXXTM is a trademark of Hockware, Inc. 3MTM and Post-ItTM are trademarks of the 3M Corporation. Contents Preface...................................................1 Quick Start...............................................2 Diskette Contents.........................................2 Installation..............................................3 Start-up..................................................3 Entering Events...........................................4 Hints for Using Chron.....................................4 Full Installation Instructions............................6 Initial Start-up..........................................7 Basic Event Manipulation..................................8 Creating Events...........................................8 Changing Existing Events.................................10 Duplicating Existing Events..............................10 Hiding and Surfacing Open Events.........................10 Viewing Posted Events....................................10 Exiting Chron............................................11 Product Information......................................11 Customizing Chron Settings...............................12 File Settings Page.......................................12 Confirm Settings Page....................................12 Past Due Settings Page...................................12 General Settings Page....................................13 Event Settings Page......................................13 The Posted Bag...........................................15 General Function.........................................15 The Event Window.........................................17 Event Window Controls....................................17 Event Window PopUp Menu..................................18 Setting the Time.........................................18 Event Settings...........................................19 Scheduling the Event.....................................19 Cancelling the Event.....................................19 Using the Clipboard......................................20 Time/Date Dialog.........................................21 Selecting Time...........................................21 Selecting the Date.......................................21 Past Due Events..........................................22 Macros...................................................23 Command Line Interface...................................25 Removing Chron...........................................27 Support for Chron........................................28 Preface Thank you for purchasing Chron. Chron can be used as a starting point for time-based automation tasks. It was designed to accommodate two particular groups of needs as follows: Chron can handle the automatic start-up of a number of programs at a desired fre- quency. This has been successfully used by a number of LAN administrators to schedule the backup of files on the server. Others have used Chron to schedule data- base reorganizations and other tasks that must be scheduled at off hours to minimize the impact to their clients. Customers have also used Chron to schedule the automated backup of important files to a LAN server using Chron with the OS/2 XCOPY com- mand or to start other backup programs. Still others have used Chron to schedule data acquisition and analysis tasks. Workstation users have used Chron as a way of setting reminders and scheduling follow-ups. Users of the IBM mainframe products PROFS and OfficeVision have used the cut and paste facilities of Chron to remind them of meetings. Since data from a 3270 screen can be cut into the clipboard and since Chron can read the contents of the clipboard, you can easily transfer host information to Chron to be notified of events, even when you are not logged in on the host. Chron is not intended to be a full fea- tured personal information manager, but it can supplement follow-up activities and other personal information manager products. Individual workstation users will find Chron useful as a way to schedule routine housekeeping chores. Small REXX pro- grams can be written to make backup copies of important files such as CONFIG.SYS and PROTOCOL.INI. Chron can schedule these execs to ensure a current backup copy is made. If you are unhappy with the operation of Chron or find that it does not meet your needs, you may return all original materials within 30 days of purchase for a refund. Quick Start Most people don't like to read user manuals. Keeping that in mind, here is a very brief overview for installation and start-up of Chron. It is still recommended that you take some time in the near future to read this manual to become familiar with the more subtle features of Chron. Diskette Contents All of the files neccessary to install and run Chron v4.0 are in the root directory of the installation diskette. The disk also contains the latest (and last) 16-bit version of Chron for those customers running OS/2 v1.x. The 16-bit code is based on Chron v3.0 and is in a subdirectory of the installation diskette called 16-BIT. The installation program is a 32-bit VisProREXX application, so customers using the 16-bit Chron v3.0 will have to install the product manually. The files inventory is: B2HILB.DLL This is the data link library (DLL) required for Chron to execute. This file must be in a directory in the LIBPATH statement in your CONFIG.SYS for Chron to operate. B2HILB.MSG This is one of the two message files that Chron uses for error and informational messages. Chron will function without this file, but error messages may not be meaningful. This file should be in the list of directories in the DPATH environment variable. CHRON.EXE This is the main executable for the Chron application. CHRON.HLP This contains the help text for Chron. This file is not required for Chron to function, but help will not be available if it is missing. This file should be in the list of directories in the HELP environment vari- able. CHRON.MSG This is second of two message files that Chron uses for error and informational messages. Chron will function without this file, but error messages may not be meaningful. This file should be in the list of directories in the DPATH environment variable. CHRONAT.CMD This is a REXX program used for adding events to Chron via the command line. The REXX code will handle the command line pars- ing and input validation for the command line interface. Once the input parameters are validated, this code will call CHRONCLI for the actual scheduling of the event. CHRONCLI.EXE This is called by the CHRONAT REXX exec. This should not be invoked directly, since there is no input validation in this code. CHRONCVT.EXE This is called to convert Chron event files from older formats to the Chron v4.0 format. This code will support conversion from Chron v2.3 (shareware), Chron v3.0 and Chron v3.0.1. It is automatically called by the installation program. INSTALL.EXE This is the installation program. It is not copied from the installation directory to the hard drive. *.CHM These files are sample REXX macros that can be used to create more complex scheduling options. These files are not an officially supported part of Chron, but are intended to be used to give you ideas of how REXX macros can enhance scheduling. If there are any questions on developing REXX scheduling macros, contact Hilbert Computing and will can assist you. Installation It is recommended that you use the installation program - INSTALL - to install Chron. This will copy neccessary files to the directory you specify for Chron and validate the installation. The CONFIG.SYS file will be checked to ensure that the current direc- tory (i.e. a period) or the installation directory is in the LIBPATH statement. It will also check to ensure the installation directory is in the list of directories in the SET HELP statement and will add it if it is not there. A backup copy of the CONFIG.SYS file is made to the CONFIG.CHR file before updates are made. If an older version of Chron is installed on system, the installation procedure will optionally remove obsolete entries from the OS2.INI file. To run the installation program, change your current drive to the drive containing the installation program and type: INSTALL. Start-up Start Chron from the program object or type START CHRON from a command line session. Chron stores settings information in the CHRON.INI file. The INI file is expected to be in the current directory and will be created in the current directory if one doesn't already exist. Therefore, it is important that you start Chron from the same directory each time. The installation program will specify a default name of CHRON.DAT in the INI file for the file in which the events are stored. If Chron cannot find the INI file in the current directory, you will be asked for the name of the file into which the scheduled events will be placed. There is no restriction on the file name. If you don't specify a path, the current path information will be used. It is recommended that you fully qualify the name of the file, so you can be assured of creating this file in the directory where you want it. If you used the installation program and see the dialog box asking for the name of the events file, it is a good bet that Chron is not being started from the installation directory for Chron. Entering Events Now that Chron has started, you can schedule your first event. Chron v4.0 was designed to behave as much like the OS/2 Workplace Shell as much as possible. When in doubt, press the right mouse button. In most cases a popup menu will display giving you a list of actions that can be performed on the object. So to schedule your first event, press the right mouse button on the Chron window and select Create another from the menu. A new desktop window will be created that will contain the informa- tion needed for an event. Enter the information as appropriate. Additional information, such as the program name to execute can be found in the settings pages for the event. To fill in the settings information, press the right mouse button and select the Settings... menu option. When the settings information is entered, close the settings window via Alt-F4 or by closing from the system menu button in the upper left corner. The time and date at which the event is to be scheduled can be changed using the Time... menu option. To schedule the event, close the event window via Alt-F4 or using the system menu. For more detailed information, see other topics in this manual or refer to the online help information. Hints for Using Chron Again, we recommend that you read the manual to gain a full understanding of all that can be done with Chron. However, we realize that you may be anxious to get started, so here are a few hints that will make Chron v4.0 a little easier to use. The number one hint is "When in doubt, press the right mouse button to get a menu". Chron v4.0 was designed to work as much as possible like the OS/2 Workplace Shell and to conform to Common User Access '91 (CUA '91) rules. Since there are few CUA '91-compliant applications on the market, this may seems a little foreign at first. The biggest change is the lack of "Save" buttons on the windows and dialogs. To save the object -- be it an event or settings -- close the window. To cancel changes, press the Undo button and close the window. The time/date dialog for an event can be displayed by double-clicking on the static text fields on the event window. As mentioned, the events window's menu can be displayed using the right mouse button. However, due to the nature of some of the Presentation Man- ager controls, there are some "dead spots". The right mouse button will not display a menu when pressed over the Type: or Freq: combo boxes or spin buttons. If the menu doesn't popup, move the mouse pointer to another area on the window. I usually press the mouse button over the Message: multiple-line entry field control. We are working to remove these "dead spots" in future service levels of Chron. Chron was designed to run from the same working directory each time. The settings information for the Chron application is saved in the CHRON.INI file in the current working directory. The easiest way to ensure that Chron is started from the same directory is to create a Workplace Shell program object and alway start Chron from there. The installation program will automatically create the program object for Chron. Full Installation Instructions For those less familiar with OS/2, this section provides a more detailed explanation of the procedures needed to install Chron on your system. From the command line, start the installation program on the supplied diskette. The installation program is called INSTALL, so for most customers, the command would be: start a:\install An OS/2 Presentation Manager installation program will prompt for the directory from which Chron is being installed and the directory to which Chron will be installed. Chron can be installed from a hard drive. This is most useful for customers with site or enterprise licenses. In that case, copy the files from the root drive of the diskette to a shared directory on a local area network. The network directory should then be specified for the "From" directory. If the destination directory doesn't exist, Chron will create it. It will not create intermediate directories. For example, if you want to install Chron in D:\UTILITES\CHRON, then the D:\UTILITES directory must already exist. Select Actions/Install from the menu bar and the files will be copied to the destination directory. When the files have been copied, Chron will create a program object (an icon) on the desktop. You can move that program object to any suitable folder if you wish. Since Chron should be started from the same directory (so it can find its INI file), it is recommended that Chron always be started from the program object since this will ensure the proper working directory. After the installation is complete, Chron will check for the presence of an older version of Chron. Specifically, it looks for an entry in the OS2USER.INI file for Chron. If found, it will display a dialog that will migrate the old events file format to the new format. By default, the dialog has two options checked. One option will allow you to migrate the files, the other will allow you ro remove the obsolete entries from the OS2USER.INI file. Selecting the option to remove the entries from the INI file will not erase the old Chron code or events files. That must still be done manually. Initial Start-up If you have installed Chron into a program object or on a group window, you may start Chron by double-clicking on the icon. You may also start Chron by issuing the START CHRON command from the OS/2 command line prompt. There are no optional command line parameters from Chron and any entered will be ignored. Chron was designed to run from the same default directory every time. The settings for Chron are stored in the file CHRON.INI in the current directory. Once Chron is started, you will see the window in the lower left corner of the screen. This main Chron window contains the current date and time and the number of events that are currently scheduled. If there have been no previous version of Chron installed, the text will display No Pending Events. All event manipulation starts with the popup menu on the main Chron window. There is a second, initially hidden, window in Chron. That is the window referred to as the "posted bag". When the time comes to schedule an event, a copy is placed in the posted bag window. Initially this window will be empty, but after events are scheduled you will be able to manipulate those events from the posted bag as well. The posted bag is most useful as a "To-Do" list for message-type events. You can show the posted bag window on the screen by selecting the Surface Posted Bag menu item. The posted bag will be covered in more detail later in this manual. Basic Event Manipulation This section will discuss the basic manipulation of events within Chron. After reading this, you should be able understand what an event is and how to create, modify and delete them from Chron. Creating Events What is an event? Simply stated, an event is the entity that Chron schedules, but that doesn't really tell you much! Chron currently supports four types of events: messages, programs, resume, and pause. Message events contain all of the scheduling informa- tion such as its time to be displayed and how often you want it to be redisplayed (the frequency). They also contain the message text to be displayed. The message text is required for message-type events. Program events contain all of the information that a message event does, except that the message text is optional. Program events also must contain additional properties, such as the name of the program to start, the default directory and any command line parameters to the program being scheduled. Resume and pause events are used to stop the scheduling of other events. Resume and pause- type events can be used to keep programs from running and to keep messages from being displayed while you are on vacation or during a company holiday for example. To schedule a new event, press the right mouse button on the main Chron window and select the Create another menu selection. You will be presented with a sizeable window that is used to fill in information about the event. You must fill in a title for the event. It can be any text that briefly describes the event. You can then choose the frequency with the combo box. Initially, this is set to schedule a One Time event, meaning the event will be scheduled for execution once. The spin button can be used to further specify the frequency. For example, you can schedule an event to run every 17 minutes or every 3 weeks. Specifically, you can schedule an event to run from 1 to 255 minutes, hours, weekdays, days, months, or years. You also need to choose the type of event as a message, program, pause or resume using the other combo box. It is recommended that you not schedule pause or resume events until you are more familiar with the operation of Chron. You then can enter the time at which you want the event to be scheduled. The default time for a new event is the current date and time. This is done using the Time menu item on the popup menu from the event window, the accelerator key for that menu item, Ctrl-T, or you can double click on the static text with the date and time on the events window. Note that the popup menu for an event is displayed using the right mouse button on the event window, not the main Chron window. When you select the time in one of these ways, you will be presented with the date time dialog. You can select the time of day at which to schedule the event in a combination of ways. The slider control will allow you to position the time of day at the appropriate spot. You can also select a time using the spin buttons on the dialog. The month and year are selected using the spin controls. The day of the month is changed by pressing the but- ton that corresponds to the day you want. Once you have entered the desired date and time, you can press the OK button. You will be returned to the event window with the date and time text updated to reflect your selection. You can then enter the message text in the multi-line edit box at the bottom of the event screen. You are limited to 32 kilobytes of text. Chron requires you to enter text for a message-type event (otherwise, what's the point?), but it is optional for program-type events. The message text for a program event is useful for displaying operator instructions or for notification of when a program has been started by Chron. If you don't specify mesage text for program events, then Chron will not display the infor- mation window (also called the read-only event view) when the event is scheduled. Scheduling several program-type events with message text can clutter the desktop with the read-only event view windows, so I usually leave the message text blank for pro- gram events. Program events require that additional information be entered before the event can be scheduled. At the very least, the name of the program to execute must be entered. This is filled in using the Settings... menu selection from the event window. Fill in the name of the program, the default directory and any command line parameters that are required for its operation. If you are scheduling a batch file or REXX command file, the event needs to execute under the OS/2 command shell. This is handled by checking the checkbox entitled Run under OS/2 shell. In most cases, this box will automatically be checked for you when you tab out of the Path & File Name entry field. In some unique cases, you may need to run the OS/2 command shell to get the desired result. To run the OS/2 shell, enter C:\OS2\CMD.EXE for the program name and /C commandline for the command line parameters, where commandline is the name of the command as you would enter it from the command line. See the OS/2 online command reference for CMD.EXE for more information. Examples of where this may be necessary are when internal shell commands, such as COPY or ERASE are scheduled. If you are using alternative shells, such as ports of Korn, Bourne or C Unix shells, or a popular shareware shell, the automatic "run under OS/2 shell" may not work as expected. Chron attempts to use the default shell by looking in the COMSPEC environment variable in CONFIG.SYS, but the command may not be con- structed properly if the alternative shell doesn't use a syntax close to that of OS/2's default CMD.EXE shell. Once the desired entries have been filled in, you can close the settings and return to the event window. You now have all of the information needed to schedule an event. Either select the Schedule menu item from the popup menu, or close the event window using Alt-F4 or by selecting close from the system menu button in the upper left corner of the event window. The event window will be removed and the main Chron window will be updated to reflect that another event has been scheduled. This sounds a bit complex at first, but the consistent and very visual nature of Presen- tation Manager applications should make this process fairly straightforward after a couple of times. If you forget to enter a required piece of information, Chron will display a dialog box that explains what is missing. Chron was designed to conform to IBM's 1991 rules for Common User Access (CUA '91). Since there are relatively few CUA '91 applications on the market, most users want to see Save and Cancel buttons for the settings and event windows instead of the Undo and Cancel buttons. It is "uncomfortable" to save an event or settings changes by closing the window. How- ever, this behavior is consistent with the operation of the Workplace Shell and should become more comfortable after working with Chron for a while. Changing Existing Events After you have scheduled one or more events, you can change them in any way you like. To display the list of currently scheduled events, select the List events... menu item from the main Chron window. You will be presented with a dialog that contains the titles of all of the events scheduled sorted in execution time order. To the right of the currently highlighted event, you will see summary information about the event. As you select the events from the listbox, the summary information changes to match the selection. This feature allows you to quickly scan the pending events merely by drag- ging the mouse pointer down the items in the listbox. If you would like to bring up an event window to modify or further inspect the event, either press the Update button or double click the entry in the listbox. At this point, the event editing is the same as creating a new event. Note that this event window is non-modal. This means that you are not required to complete the edit of the event before doing something else with Chron. You can have multiple events out for edit, you can create new events, delete existing events -- even minimize the event and come back to it later. Duplicating Existing Events When you duplicate an event, Chron creates an exact copy of the selected event. There is no connection to the original event. There are two distinct events that can be inde- pendently manipulated and will be independantly scheduled. You can duplicate an event by highlighting it on the list events dialog and pressing the Duplicate button. The now-familiar event window will be displayed to allow you to alter some of the fields if desired. When you have completed editing the event, you schedule it as you would a newly created event. Hiding and Surfacing Open Events Events that contain message text are displayed on the desktop when the event executed. If there are several event windows that have displayed, or if you are in the midst of updating events, the desktop can become cluttered with windows. To hide all open windows, both update event windows and read-only event windows, select the Hide open events menu option from the main Chron window. To regain access to those windows, select the Surface open events menu item from the popup menu from the Chron main window. Viewing Posted Events When a program event is executed or a message event is displayed (or "posted" to use Chron's lingo), a copy of the information about the event is placed into a special win- dow called the "posted bag". The posted bag is a container with objects that represent posted events. These event objects can be manipulated in the same way as events that are created, updated or deleted from the main Chron window or the events list dialog. To see the posted bag, select the Surface Posted Bag menu item from the main Chron menu. The posted bag is designed to work very similar to a Workplace Shell folder. To manipulate a single event, place the mouse pointer over the event and press the right mouse button to get a popup menu for that event. You can update, view (which dis- plays the read-only event window), delete or duplicate an event by selecting the appropriate menu option. As with Workplace Shell folders, you can select several objects and manipulate those with a single menu selection. Pressing the right mouse button on the background for the posted bag will display a menu of items that dom't pertain to any event. Namely, you can create another event, hide or surface open events, hide the posted bag or close the Chron application. Exiting Chron When you would like to shut Chron down, you may do so in a variety of ways. You can select the Close item from the system menu of the main window or the posted bag or select the Event/Exit option from the main Chron window. Regardless of the method used to close Chron, it will avoid loss of data my making sure there is no unsaved information. First, Chron will confirm via a dialog that you really intend to exit. If you answer yes, Chron will ask every outstanding event window if it is OK to close. If there have been unsaved changes to that event window, it will ask if it is OK to discard the changes. All outstanding event windows must agree to close before the Chron application will close. This is similar operationally to shutting down the OS/2 operating system in that all windows must reach a consensus before allowing the shut- down to complete. Product Information The Product Information... menu option displays information regarding the release and fix level of Chron. It also displays the copyright information. When reporting problems with Chron on the Hilbert Computing bulletin board, please include both the release and service level information found on the Product information dialog, so that we can better meet your needs. Customizing Chron Settings Chron allows considerable flexibility in its operation to better meet your needs. These options are all changed using the Settings... menu on the main Chron window. File Settings Page This dialog prompts for the name of the file on disk that is used to store the events list. It is unlikely that you will need to change this value. If you decide you would like to move the events file to a different location, there are a couple of ways you can do this. If you change the name of the events file, then that file will be used the next time Chron needs to save the event list. However, Chron will not write out the events file until it has changed. Therefore one technique would be to: ° Change the name of the file in which to store events. ° Close Chron. ° Move the Chron events file to the new location that you specified. ° Restart Chron Confirm Settings Page Chron v4.0 has greatly expanded the ability to customize which warning dialogs are displayed during the operation of Chron. The default settings generate a very high amount of interaction with the user to ensure that the action selected is what the user intended. Chron was designed to give the user a "second chance" for almost all destructive actions. After becoming familar with Chron, some of these confirmation dialogs may be annoying. The confirmation can be turned off by removing the check mark next to the confirmation on the Confirm settings page. Past Due Settings Page When Chron is started, it checks the list of events for those that are past due. The default is for Chron to prompt the user with a dialog box that contains the list of past due events. The user then has the option to reschedule those events that are not sup- posed to run immediately. Chron will not schedule any events until this rescheduling dialog is dismissed. In some unattended environments, the prompting dialog may not be appropriate. The past due settings page allows you to specify that Chron automatically reschedule past due events to be run at the next appropriate time in the future. You can also specify that Chron continue initialization with past due events. In this case, those past due events would be run at the top of the next minute. General Settings Page This will allow you to change configuration options that apply to the operation of Chron and all events in general. At the top of the dialog there are a series of seven check boxes bounded in a group that are labelled with the days of the week. This gives you the option of what you consider to be weekdays. If your work week runs from Tuesday through Saturday, then you may choose to configure valid weekdays to be those days. This option effects only those events that are scheduled for execution on weekdays. You must select at least one valid weekday. The default for the valid weekdays are Monday through Friday. The valid weekdays are used when rescheduling an event. If you change the list of valid weekdays, then those events scheduled for weekday execution will not be auto- matically changed. However, the next time they are posted, the computation of when to schedule that event next will honor the weekdays set. Note that Chron will also let you schedule a weekday event initially on a day that is not a valid weekday. Valid weekdays are used only when Chron reschedules the event after it is posted. This settings page also contains a check box to auto-open window when event is posted. When an event is posted, a new window is created (or refreshed) on the OS/2 desktop. If this option is selected, the read-only event view of the event will be displayed if there is message text associated with the event. The "read-only event view" is simply a window that contains the message text in a read-only multiple line entry field. This serves to notify you when an event has been posted. This is most likely the desired action for message events, but may not be the desired action for program events. This is the reason that in most cases you will not want to enter message text for program- type events. If you don't want any events to automatically open a read-only view, turn this option off. The default for this option is on. The next checkbox on the general page is the option to sound the alarm when an event is posted to the bag. If you are using Chron to schedule reminder messages, it is most likely that you will want this option selected to serve as additional emphasis that an event has been posted. Some customers find the alarm annoying, so the option is pro- vided here of turning it off. The default when Chron is installed is to sound the alarm when an event is posted. The final checkbox on this page determines whether the posted bag is displayed when Chron is first started. Older version of Chron automatically displayed both the main Chron window (the one with the date and time) as well as the posted bag. Many cus- tomers found the posted bag to be confusing and distracting. This option defaults to not displaying the posted bag when Chron is started, but you can change this to behave the way older versions did by selecting the checkbox. Event Settings Page Chron allows you to fill in default values for new events. This page will allow you to fill in values for the event frequency, the event type and the session type (e.g. OS/2 Fullscreen, OS/2 Windowed, etc.) for program type events. As the new event is being edited, you are free to make any changes to any of these defaults. This is merely added as a convenience to fill in the values you will use most. Chron defaults this value to one-time program events, but if you schedule mostly weekly program events, you can change this to speed the creation of new events. The Posted Bag As mentioned above, the posted bag is a desktop window that contains the events that have been posted. However, the posted bag is more than a container for posted mes- sage windows. You can also handle most of the functions of Chron and most event manipulation from the posted bag window. The posted bag allows you to effectively use Chron as a follow-up list manager. All of the events that have been posted are tasks that may require your attention, especially in the case of message-type events. You can either defer taking action and reschedule the event for a later time, or you can keep them in the posted bag as a "to do" list. This section will document the function of the posted bag, so that you may choose to use it in a way that best meets your needs. General Function The function of the posted bag is consistent with the operation of a Workplace Shell folder. Any event in the posted bag can be manipulated via its popup menu. Press the right mouse button with the mouse pointer over the object of interest. A popup menu will display, giving you the options to update, view, duplicate, remove or delete the event. If Update is selected, Chron will open the same event window that is displayed when a new event is created except that it is prefilled, as you would expect, with the values for that particular event. The View option will open a read only event view. This is the same window that is display when an event is posted. While no updating can take place from this window, it has it's own popup menu from which you can open the event for update. The view option is the same as if the icon were double-clicked. The Duplicate option will create a "clone" of the event and open the new event using an update window. This will create a completely separate event. There are no ties back to the event from which it was created. This option is handy if you need to keep the original event, but create a new one that is very similar to that original event. The Remove option will take the event out of the posted bag. This doesn't delete the event and if the scheduling frequency is anything other than one time, the event will be posted again when its time comes due. I use the remove option primarily when creat- ing reminder message events. The posted bag can serve as a to-do list. When I have completed the task, I remove it from the bag, but I don't delete it if it is a recurring task. For example, I have a weekly reminder for a staff meeting. When it displays. I select the remove menu option, grab my notebook and head out for the staff meeting. I don't want to delete the event, because I want to be reminded next week's meeting. By now, it should be clear what the Delete menu option does. If delete is selected, the event is gone for good. Unless you change the settings, you will receive a confirma- tion dialog to ensure that you really want the event deleted. The remaining menu options don't apply to the selected event and are also available if the popup menu is requested when the mouse pointer is over the background of the posted bag. The Create Another menu option will open an event window for the creation of a new event, the same as if the menu option were selected from the main Chron window. The Hide open events and Surface open events will display or hide those events are currently have an open read-only event view or an update window for them. If the event is open, you will see the cross-hatching on the event's icon in the posted bag, similar to the operation of Workplace Shell folders. As events are posted, a read-only event window is opened if there was message text associated with the event. If there are lot of these events, the screen can become cluttered. The option to hide all of these with a single option clears the clutter effortlessly. Currently, Chron will automatically arrange the icons in the posted events bag, so the Arrange option has no effect. The Hide bag option will keep the bag from displaying on the desktop, and finally the Close Chron option will terminate the Chron applica- tion. The Event Window Most of the interaction with Chron will be done through the event windows. These are the sizeable, non-modal windows that contain the information that makes up an event. Most of the main functions of the event window were discussed in the section on Cre- ating Events. Since this same window is used for editing existing events, duplicated events as well as new events, it was felt that a more focused discussion of the event window was needed in its own section. The event window can be sized during editing. When the size of the frame window is changed, all of the controls in the window adjust their size to fill the area. The mes- sage text will automatically word wrap to adjust to the new size. If there are hard carriage return characters, then the text may not wrap as intended. This occurs most often in the case where the text for the message box was pasted from another applica- tion such as a 3270 screen from the IBM OfficeVision product. Sizing the window to make the message box wider can make the contents more readable. The event windows are non-modal. A modal window in Presentation Manager forces you to complete the activity within the current window before proceeding to other activities within the application. Dialog boxes are the most common source for modal windows. While modal windows make sense in many areas of an application, they tend to be inflexible. The better alternative, when it makes sense, is to use non-modal windows to enable the customer to complete tasks in their choice of order. Multiple events windows can be open and "under construction" at any time. If you are in the middle of creating or changing an event, you can switch over to the posted bag, for example, to copy some text into the clipboard and copy it back into your message window. While it was not in the original design intent of Chron, many customers have used open event windows as a computer version of the 3M Post-ItTM notes into which they can type information. Event Window Controls The event window contains a set of Presentation Manager control windows into which you can type or select information. The first single-line entry field contains the title of the event. This should be a brief description of the contents of this event. This title is used in two places. It is the text that appears in the list dialog when the List events menu item is selected from the main menu. It also appears in the icon text of the posted event icons contained within the posted bag. If the event is a program event, this title is also used as the title for the executing program in the Window List when you press Ctrl-Esc. This title does not have to be unique, but to avoid confusion, it is recommended that each event have a unique title. The type of event is selected using the combo box to the right of the Type: label. This specifies whether this is a program, message, pause or resume event. As with all Pre- sentation Manager combo boxes, you can either press the drop down button and select the type with the mouse, or you may tab to the combo box and press the first letter of the choice. In this case, you may press P for Program and Pause events, M for mes- sage events or R for Resume events. The following combo box and spin button, labelled Freq.: collectively determine the frequency with which the event will be posted. This choice can be selected from the drop down or using the first letter of the option as with all Presentation Manager combo boxes. The choices are One Time, Hour(s), Weekday(s), Day(s), Week(s), Month(s) or Year(s). The spin button determines how many of those used are used when rescheduling the event. One Time events are scheduled to be posted once, after which they are removed from the list of pending events. Weekday events are sched- uled to be run at the same time of day on the next n weekdays. A weekday is defined to be any one of the days listed in the Settings notebook. They default to Monday through Friday, but can be changed to reflect your work week. Rescheduling a monthly event presented an interesting problem. Generally you would expect a monthly event to be rescheduled to run at the same time and day of the month on the next month. However, when you schedule an event on one of the last few days of the month, an interesting thing happens. If you schedule a monthly event to run on, for example, the 31st of March then the event can't be rescheduled for the 31st of April since there are only 30 days in that month. If Chron schedules for the 30th of April, then it will be scheduled after that posting to run on the 30th of May. Well, there are 31 days in May, and Chron has no way of knowing whether you wanted execution to be scheduled on the 30th or 31st. This monthly scheduling problem is handled in the following way. If you schedule an event within the last five days of the month, Chron assumes that you are scheduling that event relative to the end of the month. In other words, if you schedule the event above on the 31st of March, Chron interprets that as running on the last day of the month. Chron would continue to post that event on the 30th of April and the 31st of May. Similarly, if the monthly event was scheduled on the 28th of March, Chron would logically treat that event as being scheduled on the fourth to the last day of the month for all months. If this implementation of scheduling monthly events is not what you need, contact us here at Hilbert Computing and request a design change for future releases. At this point, this implementation has met the needs of Chron customers. The remaining event frequencies should be self-explanatory. Event Window PopUp Menu The event window menu items let you further refine the contents of the event. This menu is displayed when the right mouse button is pressed (almost) anywhere on the update events window. The "almost" comes in because there are some "dead spots" where the right mouse button doesn't work due to the way that subclassing of Presen- tation Manager controls works. Currently, the right mouse button doesn't display the menu when pressed over the static date/time text, or when the mouse pointer is over either the combo box controls or the spin button controls. Hilbert Computing will try to remove this restriction in subsequent service levels of the product if it is possible to do so. Setting the Time The time at which the event is scheduled to run is set by the Time menu item. Alter- nately, you can press the Alt-T accelerator key or double click on the static text containing the time and date. When any of these three methods are chosen, the user is presented with a dialog that is used to set the date and time at which the event will be scheduled. The details of entering dates and times are explained in the section entitled Time Dialog below. Event Settings Certain events types have additional information specific to that event type. In par- ticular, program events require additional information before they can be scheduled. Program events require that at least the program name be entered. This is entered in the notebook that is presented when the Settings menu item is chosen. This notebook also allows you to enter optional values for parameters to the program, the default working directory, and the session type for the program. The settings dialog also contains a page for selecting the macro to be associated with this event. Macros provide a way to extend the basic scheduling options in Chron by writing REXX code that will determine if the event should be scheduled. For more information on REXX macros, see the section later in this manual. The changes to the settings for the event are saved when the notebook is closed. If the changes aren't meant to be saved, the Undo button will restore the options to the way they were before the notebook was opened. The Default button will restore the set- tings to the Chron defaults. Scheduling the Event Once you have entered all of the information about the event, you can place the event into the list of pending events by selecting the Schedule menu item. Other methods of scheduling the event include pressing the accelerator key, Ctrl-S, or by closing the event window using Alt-F4 or by closing the window from the system menu button in the upper left corner of the window. All methods accomplish the same result. At first, there may be reluctance to save the event by closing it. This is notably different from the CUA '89 behavior that most applications exhibit, but it is consistent with CUA '91 guidelines and is consistent with the way that the Workplace Shell operates. If you have selected a time to schedule the event that is the same as, or previous to the current date and time, Chron will pop a dialog stating that the event is past due. If you press the OK key, the event will be scheduled to execute at the top of the next minute. If you press the Cancel button, you will be returned to the event window to further refine the time and date. This confirmation dialog can be turned off using the settings notebook for the main Chron window. Cancelling the Event If you decide that you do not want to schedule the event, you can remove the event window by pressing the Cancel button. If you have made changes to the event win- dow, Chron will present a dialog asking you if you are sure that you want to close the window. Using the Clipboard The event window has menu items that allow you to use the clipboard to cut, copy and paste information to and from the message text window. The Edit menu item lists the three operations. Regardless of which control on the event window contains the cur- sor, these menu selections always operate on the message text window. You may also use the CUA-compliant accelerator keys: Shift-Del to cut to the clip- board, Ctrl-Ins to copy selected text to the clipboard, and Shift-Ins to paste from the clipboard. If the message text multi-line edit control on the event window has input focus (that is, if your cursor is in the message text window), then the accelerator keys work the same as the menu items for Cut, Copy and Paste. Otherwise, the accelerator keys will work on the window that currently contains the input cursor. This enables you to use the keyboard to move data to and from the entry field for the title, but allows the mouse selection of the menu items to operate on the more likely choice of the message text window. Time/Date Dialog The time dialog is a complex dialog that allows you to enter both the date and the time at which you want an event to be scheduled. This dialog contains several controls that are explained below. Once the date and time have been entered, press the OK button to dismiss the time dialog. You will be returned to the event window and the date and time text will be updated to reflect your selection. Selecting Time There are three ways to select the time on this dialog. The simplest and most direct is to move the slider control to the desired position. As the slider is moved, the time is dynamically updated in the spin controls to reflect the time at which the event is to be scheduled. You can increase or decrease the scheduled time by one hour by pressing on the bar of the hours slider control. The second way by which you can select the time of day is to directly enter the time in the spin controls. The third way is to press up and down buttons on the spin control to select the time at which you want to schedule the event. Using either of the last two methods require that you also indicate, with the radio buttons, whether the time is AM or PM. Military (24-hour) time cannot be entered directly in the hours spin control. Note that regardless of the technique or combination of techniques that are used to select the time, the slider control, spin buttons and the AM/PM radio buttons are all tightly synchronized. Changing one will immediately change the others. Selecting the Date The month and year on which to schedule the event are selected using the controls above the month calendar. The month and year are selected using the spin buttons. The day of the month is selected by pressing the desired day on the calendar with the mouse. At this release, there is no way to enter the day of the month using the key- board only. If there is a need to enter a day without a pointing device, contact Hilbert Computing by bulletin board or by voice and request a design change and we will accommodate your request in the next release of the product. Past Due Events If Chron has not been started in a while, it is possible for scheduled events to be past due when Chron is finally started. After all of the events are read from the event file, if there are any events with a scheduled time that is later than the current time, you will be presented with a dialog listing those past due events. If you would like to resched- ule that event for the next appropriate time, highlight the event and press the Reschedule »button. Rescheduling works as follows: The event frequency is checked and the event is repeatedly rescheduled without being posted until the date is later than the present time. There is one exception. Past due events that are scheduled to be posted one time are rescheduled to be posted five minutes into the future. This delay in posting gives you ample time to reschedule the event for an appropriate time, or to delete the event if that is more appropriate. If you change your mind, and wish to not reschedule an event after you have resched- uled it in the dialog, highlight that event in the rescheduled listbox and press the «gnore button. When you have rescheduled the events that you want, press the OK button. Those past due events that were not rescheduled will be posted at the top of the next minute. If you always want to ignore all past due events or always reschedule past due events at startup, you can change the Chron settings to not display this dialog and automatically reschedule or ignore. This is common in sites that run machines in an unattended or lightly attended environment. This setting is changed by selecting the Settings... option from the popup menu on the main Chron window and turning to the Past Due page. Macros Support for macros is one of the main new features for this version of Chron. Many customers expressed a wish for enhanced scheduling options. Some of those requests, like the addition of a number for scheduling every x days, weeks, or months was incorporated directly into the product. Other scheduling options were more complex and some were downright exotic. Instead of trying to accomodate all the scheduling requests, Hilbert Computing chose to extend the product with a macro facility to allow customers to create more advanced scheduling algorithms in REXX and attach those macros to events. Hilbert Computing has supplied sample macros on the diskette. These are intended to be used for ideas on enhancing Chron scheduling options. If you have questions as to how to implement some scheduling options, send us a note on CompuServe or the Hilbert Computing BBS and we can point you in the right direction. Regardless of the complexity of the REXX code, it all boils down to one thing. If the macro returns a return code of '1', then event is scheduled. If it returns a return code of '0' the event is not run, but is rescheduled for the next potential time. Events will receive the event title and the message text as arguments to the macro. The following sample macro will schedule an event only if it is between the hours of 8 am and 4:59 pm: /** *** This will schedule the event if it is between 8am and 4:59 pm. **/ parse arg EventTitle, MessageText CurrentHour = time("Hours") if CurrentHour < 8 then return 0 if CurrentHour > 16 then /* 5pm */ return 0 return 1 /* Schedule the event */ This macro could be added to an event that is scheduled to execute every 15 minutes. The scheduling of the event plus the macro would cause the event to run every 15 minutes between 8 and 5. The power of REXX allows for some very exotic and com- plex scheduling opportunities. For example, you could check for the existence of a file before scheduling the event. You could even to something as complex as an SQL query to a mainframe DB2 database using a DDCS/2 gateway if you had those software facilities in place. The possibilities are limited only by the imagination and the mastery of the very powerful REXX language. In this first release for macro support, there are no debugging capabilities from within Chron for the macros. It is therefore recommended that you first create and debug your REXX macros as standalone CMD files. From the command line, you can use all of the trace facilities within the REXX language. There are no special function calls to the Chron application an no Chron-specific commands that can be executed within the macro, so there should be no problem debugging from the command line. When the REXX code is sufficiently tested, simply rename the macro to have the recommended .CHM extension and attach it to an event. To add a macro to a Chron event for the first time is a three-step process. First, create and debug the macro as suggested above. Next, register the macro to Chron using the settings notebook from the main Chron window. The Macros page will display the list of registered macros and will allow you to add, update and delete the macro regis- tration. If you press the Create another... button, you will be presented with a dialog that prompts for the title for the macro and the program name. Enter a descriptive title (this will appear in the macros selection list for the settings for each event) and the name of the file containing the REXX macro and press the OK button. To add the macro to an event, display the settings notebook for the event using the Settings... menu option for the event. The list of the titles for the registered macros will appear. To attach the macro to the event, select the macro from the list with a single mouse click. To undo the selection, press the Undo button. To remove any macro from the being associated with the event, press the Default button, since the default for any event is to not run any macros at all. To delete a macro from being registered to Chron, select the Macros page from the settings on the main Chron menu and delete the entry. Note that there is no "referen- tial integrity" regarding macros, events and the actual file containing the macro. In other words, if you delete a macro entry from Chron, those events that wanted to execute the event will not automatically revert to the default of no macro. You will have to remove the macro from each event that wanted to use it. Similarly, removing the registration of a macro from Chron doesn't delete the file containing the macro. Certainly, deleting the physical file doesn't remove the registration of the macro from Chron. It is the intent to make the macro facilities more robust in future service levels or releases of Chron. Hilbert Computing welcomes customer feedback on what your expectations would be in this area and what would be considered appropriate behavior for Chron. Command Line Interface Chron v4.0 has a command line interface that will enable the scheduling of events without using the Presentation Manager front-end. Some customers have a need to schedule events on unattended servers. The command line interface enables the addi- tion of new events using facitilies such as TCP/IP telnet sessions, remote execution using REXEC, AREXEC or LAN-based remote execution facitilities. At this release, the command line interface can be used only to schedule new events. Application developers can also use the command line interface to schedule new events from their application. The command line interface communicates dynamically with Chron, so Chron must be running for the scheduling to work. There is a considerable amount of information that must be specified on the command line for a new event. The results in a rather long, cryptic command. To get a brief listing of the options enter the command: ChronAt -? and the following screen will be displayed: Syntax - CHRONAT [mm-dd-yy|= [hh:ss]|=] [-fo|h|k|d|w|m|y[<n>]] [-p<pgmname>] [-a<cmdlineparms>][-d<workingdir>][-m<message>][-n<name>][-s] where: -f -- Scheduling frequency as follows (default is O - One time): o - One Time h - Hours k - Weekdays d - Days w - Weeks m - Months y - Years -p -- Executable program name -a -- Command like parameters to the program -d -- Working directory for the program -m -- Message text -n -- Name of the event -s -- Run under command shell. Req'd for command files Any parameter containing a blank must be surrounded by double quotes. A date or time of "=" defaults to the current date or time. Example: CHRONAT 11/22/93 4:53 -fk3 -m"This is a test message" will schedule a message event for every 3 weekdays. Enter the parameters as shown on the help screen. Note that any parameters with blanks must be surrounded by double quotes. The date and time are required fields. If a program name is specified using the -p option, then the event is assumed to be a program event. Otherwise, it is assumed to be a message event and the message text (-m) is a required option. While the event is checked for syntactic and semantic cor- rectness, much of the input validation that occurs with the GUI interface is missing from the command line interface. For example, checks for the existence of the pro- gram or working directory, checks for past due scheduling, and the automatic scheduling of command files under the shell is not available using the command line. The command line interface was developed for a fairly small part of the customer base. If you use this, we would be interested in hearing what features you would like to see added. Removing Chron Assuming that the installation program was used, Chron v4.0 will be installed in its entirety in the destination directory. There are no INI entries in the system profiles nor any files that get copied to other directories. Therefore to remove Chron, simply remove the files in the destination directory and remove the directory. The installation process for Chron will also add the installation directory to the end of the SET HELP= entry in the CONFIG.SYS file. The installation also checks to see if the current directory (indicated by a period) is in the LIBPATH statement. If not, the installation will add a period to the beginning of the list. You can manually remove these changes by editing the CONFIG.SYS. Support for Chron Support for Chron is available in multiple ways. The preferred way is to login to the Hilbert Computing bulletin board at 8N1, 14,400bps or lower. The phone number is (913) 829-2450. You can leave a message indicating your needs, questions or code defect report. Hilbert Computing is also supporting Chron via the OS2AVEND forum on CompuServe. Leave a message to 73457,365 with the word Chron in the title and we will answer your questions promptly. You may also send a fax to (913) 829-2450 with your questions, comments or defect reports. You may also call the voice number for assistance at (913) 780-5051. Periodically, Hilbert computing will place new service levels of Chron that fix reported code defects and provide minor enhancements. These are placed in the CUSTOMER file area on the bulletin board and are available for download without charge. This area is available only to registered customers. The Sysop for the Hilbert BBS will have to authorize you as a customer after the first time you logon. When you receive your Chron package, it is recommended that you logon to the BBS and leave a message stat- ing that you are a registered customer. If you aren't the same person that originally ordered the product, please indicate the company and/or the person who ordered the product so you can be identified as a registered customer. There will be no explicit notification via mail of service level updates. You may want to check the board every few months to see if there have been any code changes or fixes. You can use Chron to schedule a monthly reminder to check the Hilbert Computing bulletin board if you like. Support for Chron v4.0 will continue until three months after release of the next release level (v4.1) or version (v5.0). Free upgrades to the next release of Chron will be available to all customers who purchase Chron v4.0 within three (3) months of the next release of version level. Upgrade policies for those customers purchasing Chron prior to three months before the next release have not been determined. Customers will be notified of that policy and pricing when it is put into effect.