TIMEXEC (TIMed EXECution)

IBM License Agreement for TIMEXE IF YOU DOWNLOAD OR USE THIS PROGRAM YOU AGREE TO THESE TERMS. International Business Machines corporation grants you a license to use the Program only in the country where you acquired it. The Program is copyrighted and licensed (not sold). We do not transfer title to the Program to you. You obtain no rights other that those granted you under this license. Under this license, you may: 1. use the Program on one or more machines at a time; 2. make copies of the Program for use or backup purposes within your Enterprise; and 3. modify the Program and merge it into another program. You must reproduce the copyright notice and any other legend of ownership on each copy or partial copy, of the Program. Except as expressly provided in the DAPTOOLS LIBRARY Licence Agreement (LIBRARY.LIC) you may NOT: 1. distribute the program in any manner, including through electronic bulletin board systems or other means; 2. sublicense, rent, lease, or assign the Program; and 3. reverse assemble, reverse compile, or otherwise translate the object code of the Program. We do not warrant that the Program is free from claims by a third party of copyright, patent, trademark, trade secret, or any other intellectual property infringement. Under no circumstances are we liable for any of the following: 1. third-party claims against you for losses or damages; 2. loss of, or damage to, your records or data; or 3. economic consequential damages (including lost profits or savings) or incidental damages, even if we are informed of their possibility. Some jurisdictions do no allow these limitations or exclusions, so they may not apply to you. We do not warrant uninterrupted or error free operation of the Program. We have no obligation to provide service, defect correction, or any maintenance for the Program. We have no obligation to supply any Program updates or enhancements to you even in such are or later become available. IF YOU DOWNLOAD OR USE THIS PROGRAM YOU AGREE TO THESE TERMS. THIS PROGRAM IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion may not apply to you. You may terminate this license at any time. We may terminate this license if you fail to comply with any of its terms. In either event, you must destroy all your copies of the Program. You are responsible for the payment of any taxes resulting from this license. You may not sell, transfer, assign, or subcontract any of your rights or obligations under this license. Any attempt to do so is void. Neither of us may bring a legal action more than two years after the cause of action arose. If you acquired the Program in the United States, this license is governed by the laws of the State of New York. If you acquired the Program in Canada, this license is governed by the laws of the Province of Ontario. Otherwise, this license is governed by the laws of the country in which you acquired the Program. ----------------------------------------------------------------- TIMEXEC - A FACILITY TO ALLOW FOR TIMED EXECUTION OF PROGRAMS April 25, 1989. Ralph E. Yozzo IBM Research T. J. Watson Research Center Yorktown Heights, NY 10598 Document formatted at 8:22 a.m. on Tuesday April 25, 1989. IBM DAPTOOLS Use Only IBM DAPTOOLS USE ONLY ii TIMEXEC - a facility to allow for TIMed EXECution of programs IBM DAPTOOLS USE ONLY ABSTRACT ________ This program allows one to schedule the periodic execution of programs. The format of the control file allows one to schedule events in a large variety of ways. For example, programs can be executed weekly, daily, monthly, on only certain days or hours. The format is described in detail in the TIMEXEC documentation. Such a program is useful in many applications. A few sample applications follow: o backing up of a disk periodically o sending messages periodically o running diagnostics on the disk o logging statistics on usage of a resource such as - Local Area Networks - Host data bases In addition, there is a PM front end available called SCHEDULE.EXE. This program creates TIMEXEC control files for the users. SCHEDULE.EXE is part of the PMCAL PACKAGE. Abstract iii IBM DAPTOOLS USE ONLY iv TIMEXEC - a facility to allow for TIMed EXECution of programs IBM DAPTOOLS USE ONLY CONTENTS ________ GENESIS 1 PROGRAM INSTALLATION 3 Placement of TIMEXEC 3 Program invocation 3 Killing the TIMEXEC process. 3 File name convention 4 Data file format 4 An example TIMEXEC.ADM file 6 Execution of TIMEXEC programs 7 How TIMEXEC executes programs 8 TIMEXEC questions and answers 8 Question 8 Answer 8 TIMEXEC change history 8 Contents v IBM DAPTOOLS USE ONLY vi TIMEXEC - a facility to allow for TIMed EXECution of programs IBM DAPTOOLS USE ONLY GENESIS _______ This program is born from the idea that one needs to perform certain actions periodically. These actions involve the execution of programs. A computer should be capable of carrying on these recurrent events without manual inter- vention. From this idea, springs forth the TIMEXEC program. Genesis 1 IBM DAPTOOLS USE ONLY 2 TIMEXEC - a facility to allow for TIMed EXECution of programs IBM DAPTOOLS USE ONLY PROGRAM INSTALLATION ____________________ PLACEMENT OF TIMEXEC ____________________ Place the TIMEXEC program files in a subdirectory that is referenced by the PATH environment variable. PROGRAM INVOCATION __________________ To start TIMEXEC issue the following command at an os/2 command prompt: TIMEXEC In order to end the execution of TIMEXEC press Ctrl-Break in the session in which it was started. If the program was detached, then kill its process id. KILLING THE TIMEXEC PROCESS. ____________________________ Use the following command to kill a running instance of TIMEXEC. timexec -k To find the process id of the detached TIMEXEC process issue the following command timexec -q This command will display the detached TIMEXEC process id information (i.e., provided the TIMEXEC process is running) To kill the TIMEXEC process, use a utility such as KILL in the PROTUTIL PACKAGE and kill the displayed process id. An sample scenario follows: First, we shall find the TIMEXEC process id. For purpose of illustration, let us assume the TIMEXEC process id is 89. The command that we issue is: timexec -q This command displays the following information: Process id is 89. Then we issue the following command to kill TIMEXEC. Program Installation 3 IBM DAPTOOLS USE ONLY kill 89 FILE NAME CONVENTION ____________________ We look for a file called TIMEXEC.ADM. This file contains the information that is used to schedule the recurring events. If TIMEXEC.ADM is not found in the current directory, then we search the directory path that is associated with the DPATH environment variable. The file called TIMEXEC.RMD. is used to support the PMCAL program which is available via PCTOOLS. TIMEXEC.RMD is a file that PMCAL creates. It is used as a communication vehicle between PMCAL and TIMEXEC. PMCAL will create the TIMEXEC.RMD whenever a person has appointments sched- uled for the current day. The entries start the REMINDER program with the appropriate text information. Therefore, the user should not have to worry about the TIMEXEC.RMD file. The TIMEXEC.RMD file is recreated every day from the PMCAL database and also it is recreated every time an entry is added to the database for the current day. DATA FILE FORMAT ________________ The format of the file is as shown on page 4. ENTRY EXPLANATION HOUR (0-23) MINUTE (0-59) WEEKDAY OF THE MONTH (1-5 with 1 = First ). This entry specifies the week in which the entry should be considered valid. We also allow the keywords o first o second o third o fourth o fifth 4 TIMEXEC - a facility to allow for TIMed EXECution of programs IBM DAPTOOLS USE ONLY DAY OF THE WEEK (1-7 with 1 = Monday) This entry specifies the day of the week in which the entry should be considered valid. We also allow the keywords o monday o tueday o wednesday o thursday o friday o saturday o sunday MONTH OF THE YEAR (1-12) This entry specifies the month of the year in which the entry should be considered valid. We also allow the keywords o january o february o march o april o may o june o july o august o september o october o november o december DAY OF THE MONTH (1-31) This entry specifies the day of the month in which the entry should be considered valid. YEAR (1970-) This entry specifies the year in which the entry should be considered valid. Each of these patterns may contain: Program Installation 5 IBM DAPTOOLS USE ONLY o a number in the range above o two numbers separated by a minus meaning a range inclusive o a list of numbers separated by commas meaning any of the numbers o an asterisk meaning all legal values AN EXAMPLE TIMEXEC.ADM FILE ; hour minute nth_week week_day month month_day year command * * * Sunday,Saturday * * 1989 d:\src\shelldll\beep * * * * * * 1989 d:\src\shelldll\beep 100 x * 1,2 * * * * 1989 d:\src\shelldll\beep 200 x * * first friday,saturday * * 1989 d:\src\shelldll\beep 300 x * * * * mar,apr,may * 1989 d:\src\shelldll\beep 400 x 7 30 first monday october * 1989 d:\src\shelldll\beep 500 x 2 0 fourth sunday october * 1989 timer Fall Backward 2 0 first sunday april * 1989 timer Spring Forward We shall explain each entry. * * * Sunday,Saturday * * 1989 d:\src\shelldll\beep This entry tells us to execute the d:\src\shelldll\beep every minute during every Sunday and Saturday in 1989. * * * * * * 1989 d:\src\shelldll\beep 100 x This entry tells us to execute the d:\src\shelldll\beep and pass the param- eter "100 x", every minute in 1989. * 1,2 * * * * 1989 d:\src\shelldll\beep 200 x This entry tells us to execute the d:\src\shelldll\beep and pass the param- eter "200 x", every hour at 1 minute after the hour and 2 minutes after the hour in 1989. 6 TIMEXEC - a facility to allow for TIMed EXECution of programs IBM DAPTOOLS USE ONLY * * first friday,saturday * * 1989 d:\src\shelldll\beep 300 x This entry tells us to execute the d:\src\shelldll\beep and pass the param- eter "300 x", every minute on every first friday and saturday in 1989. * * * * mar,apr,may * 1989 d:\src\shelldll\beep 400 x This entry tells us to execute the d:\src\shelldll\beep and pass the param- eter "400 x", every minute in march and april and may in 1989. 7 30 first monday october * 1989 d:\src\shelldll\beep 500 x This entry tells us to execute the d:\src\shelldll\beep and pass the param- eter "500 x", on the first monday in october in 1989 at 7:30am. 2 0 fourth sunday october * * timer Fall Backward This entry tells us to set our timer back one hour on the fourth sunday in october at 2:00am. 2 0 first sunday april * 1989 timer Spring Forward This entry tells us to set our timer forward one hour on the first sunday in april at 2:00am. EXECUTION OF TIMEXEC PROGRAMS _____________________________ Program Installation 7 IBM DAPTOOLS USE ONLY HOW TIMEXEC EXECUTES PROGRAMS TIMEXEC should be executed in a detached session. detach timexec If TIMEXEC is detached then any program that TIMEXEC executes which sends output to the standard output device shall be lost unless the output is redi- rected to a file. dir >log If timexec is executed in a foreground session then programs that are exe- cuted will display information in the session where TIMEXEC is running. TIMEXEC QUESTIONS AND ANSWERS _____________________________ QUESTION The documentation specifies the use of two files, TIMEXEC.ADM and TIMEXEC.RMD. Only timexec.adm was included with the package. What is the difference between the two? Do they have the same format ? PMCAL is also mentioned, is this an example? or do we need it to run the package ? ANSWER The TIMEXEC.ADM file is the file that a user would edit. The TIMEXEC.RMD file is created by PMCAL. (It is not needed.) PMCAL assumes that the TIMEXEC.RMD can be deleted and recreated at any point. This is the reason that a person should not add entries to the TIMEXEC.RMD file. The format is the same for both the TIMEXEC.ADM and the TIMEXEC.RMD PMCAL is not needed to use TIMEXEC. However, PMCAL's "Timer Control Center" Menu is a nice front-end to TIMEXEC. TIMEXEC CHANGE HISTORY ______________________ o 11/08/91- TIMEXEC updated to display the name of the command and the parameters as it executes it. o (Sysop's note: the file TIMEXEC.NEW contains the updated change history) 8 TIMEXEC - a facility to allow for TIMed EXECution of programs // Name TIMEXEC NEWS // // Author Ralph Yozzo (YOZZO at WATSON, yozzo@ibm.com) // // Function This file contains the late breaking news about the // TIMEXEC PACKAGE * 23 Jan 1992 13:17:17 (EST) - Help information has been added to TIMEXEC. The help can be displayed by passing the '?' parameter to TIMEXEC. For example, TIMEXEC ? - A very important file handle problem has been solved. This problem occurred whenever a TIMEXEC spawned application tried to read from the STDIN device. The problem was usually seen when using REXX CMD files from TIMEXEC. The solution is to not play around with STDIN in TIMEXEC. * 17 Jan 1991 12:09:37 (EST) - Timexec has been modified to issue less informational messages. These informational message (although displayed with the best of intentions ) seem to confuse some users. The informational messages can be enabled with the -v option (e.g., timexec -v ) * 20 Jun 1989 23:17:01 (EST) - The TIMEXEC program now executes programs using the DosExecPgm asynchronous option. Formerly, TIMEXEC used the detached option. * 6 Sep 1989 22:46:10 (EST) KILLING THE TIMEXEC PROCESS. ____________________________ To find the process id of the detached TIMEXEC process issue the following command timexec -q This command will display the detached TIMEXEC process id information (i.e., provided the TIMEXEC process is running) To kill the TIMEXEC process, use a utility such as KILL in the PROTUTIL PACKAGE and kill the displayed process id. An sample scenario follows: First, we shall find the TIMEXEC process id. For purpose of illustration, let us assume the TIMEXEC process id is 89. The command that we issue is: timexec -q This command displays the following information: Process id is 89. Then we issue the following command to kill TIMEXEC. kill 89