home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / WAIT.ZIP / WAIT.DOC < prev    next >
Text File  |  1991-02-06  |  15KB  |  374 lines
  1.                                    WAIT 1.10
  2.                               OS/2 "WAIT" UTILITY
  3.  
  4.         WAIT is a general purpose OS/2 "wait" or "wait until" utility.
  5.         Using WAIT, you can wait for a specified period of time, until a
  6.         specified time, or until a specified process has ended.  When
  7.         the waiting period has ended, WAIT can execute any OS/2 command,
  8.         program or batch file (including starting a new session or
  9.         detaching a process); or, it can simply terminate.  WAIT uses
  10.         very little of your system's resources while it is waiting, so
  11.         other processes can run quite efficiently.
  12.  
  13.  
  14.         Usage summary
  15.         -------------
  16.         There are several ways to use WAIT:
  17.  
  18.             WAIT [/D] elapsed-time [command {arguments}]
  19.             WAIT [/D] UNTIL [date|TOMORROW] time [command {arguments}]
  20.             WAIT [/D] FOR name [command {arguments}]
  21.             WAIT [/D] FOR PID # [command {arguments}]
  22.             WAIT [/D] FOR SESSION # [command {arguments}]
  23.             WAIT /V
  24.             WAIT /HELP
  25.  
  26.         The arguments must be entered in the order specified but are not
  27.         case-sensitive.  You may use either '/' or '-' to introduce
  28.         option switches.
  29.  
  30.  
  31.         Waiting for a specified period of time
  32.         --------------------------------------
  33.         The first format is used to wait for a specified period of time:
  34.  
  35.             WAIT [/D] elapsed-time [command {arguments}]
  36.  
  37.         The period of time can be specified as any of:
  38.  
  39.             hh:mm:ss
  40.             hh:mm
  41.             hh:
  42.             :mm:ss
  43.             :mm
  44.  
  45.         Missing elements are assumed to be 0; thus, "12:15" is assumed
  46.         to mean "12:15:00", or twelve hours and fifteen minutes.
  47.  
  48.         Without the /D option, WAIT executes the child process using the
  49.         current command shell (usually CMD.EXE); the child process cna
  50.         thus be any valid OS/2 internal command, batch file, or program
  51.         name.  If no command is specified, WAIT simply terminates when
  52.         the time has elapsed.
  53.  
  54.         If command arguments require special characters (like
  55.         redirection characters), you can pass them intact to WAIT by
  56.         enclosing them in quotes.  You can either quote the special
  57.         characters themselves or the entire argument string; just don't
  58.         quote the command itself:
  59.  
  60.             wait :10 dir "> prn"    (OK)
  61.             wait :10 dir ">" prn    (OK)
  62.             wait :10 "dir prn"      (WRONG - don't quote the command)
  63.             wait :10 dir > prn      (WRONG - output from WAIT, not
  64.                                      DIR, is redirected)
  65.  
  66.         If you need to pass along a real quotation mark, use double
  67.         apostrophes:
  68.  
  69.             start ''session name'' my prog
  70.  
  71.         Examples:
  72.  
  73.             wait 1:0:0
  74.                 Wait one hour, then terminate.
  75.  
  76.             wait :10 dir
  77.                 Wait ten minutes, then execute a DIR command.
  78.  
  79.             wait 196: dir "> prn"
  80.                 Wait 196 hours, then execute a DIR command, redirecting
  81.                 output to the printer.  Quotes are required, otherwise
  82.                 WAIT's output will be routed to the printer.
  83.  
  84.             wait :0:15 start "''New Session'' /fs c:\cm\rxt2.exe > nul"
  85.                 Wait fifteen seconds, then start a new session as
  86.                 shown.  Note that ''New Session'' is translated to
  87.                 "New Session" as required by the START command.
  88.  
  89.         With the /D option, WAIT executes the program directly, without
  90.         using the command shell (this is equivalent START's /D option).
  91.         This is faster but more limited; the command to be executed must
  92.         be an external program (not an internal command or batch file),
  93.         and you cannot use redirection.  The other advantage to using /D
  94.         is that you will receive the exit code of the specified program,
  95.         rather than the exit code from the command shell.
  96.  
  97.         Examples:
  98.  
  99.             wait /d :10 rxt2 arg1 arg2
  100.                 Wait ten minutes, then execute RXT2.EXE with arguments
  101.                 as specified.  RXT2.EXE may be in the current directory
  102.                 or anywhere in the current PATH.
  103.  
  104.             wait /d :10 dir
  105.                 Invalid: internal commands not legal with /D.
  106.  
  107.             wait /d :10 foo "> prn"
  108.                 Invalid: cannot use redirection.
  109.  
  110.  
  111.         Waiting until a specific date/time
  112.         ----------------------------------
  113.         The second format is used to wait until a specified time:
  114.  
  115.             WAIT [/D] UNTIL [date|TOMORROW] time [command {arguments}]
  116.  
  117.         The optional date may be specified as either of:
  118.  
  119.             mm/dd/yy
  120.             mm/dd           (assumed current year)
  121.  
  122.         If a date is specified, the keyword UNTIL is assumed (and
  123.         is therefore optional).  If no date is specified, the current
  124.         date is assumed, and the keyword UNTIL is required.
  125.  
  126.         The time may be specified as any of:
  127.  
  128.             hh:mm:ss
  129.             hh:mm           (ss assumed 0)
  130.             hh:             (mm, ss assumed 0)
  131.             :mm:ss          (hh assumed current hour)
  132.             :mm             (hh assumed current hour, ss assumed 0)
  133.  
  134.         Hours are assumed to be in 24-hour format:
  135.  
  136.             11:15           (11:15 am)
  137.             23:15           (11:15 pm)
  138.  
  139.         The remaining arguments are used exactly as described in the
  140.         last section.  Examples:
  141.  
  142.             wait until 11:15
  143.                 Wait until 11:15 am, then terminate.
  144.  
  145.             wait until 1/12 11:15
  146.                 Wait until 11:15 am on January 12, then terminate.  Note
  147.                 that the UNTIL keyword is optional here.
  148.  
  149.             wait until 11:15 detach "dir > prn"
  150.                 Wait until 11:15, then send a directory listing to the
  151.                 printer, detaching this as a separate process.
  152.  
  153.             wait /d 2/14 11:15 rxt2 "arg1 arg2"
  154.                 Wait until 11:15 on 2/14, then run RXT2.EXE directly.
  155.  
  156.         If the specified time has already passed when WAIT begins, then
  157.         WAIT will either terminate or run the specified command
  158.         immediately (as appropriate).  There is, however, one exception
  159.         to this.  If:
  160.  
  161.             -- no date is specified, and
  162.             -- the current time is 10pm (22:00) or LATER, and
  163.             -- the specified time is 10am (10:00) or EARLIER,
  164.  
  165.         then WAIT assumes that you mean "tomorrow morning" rather than
  166.         "this morning".  This allows you to start overnight processing
  167.         before midnight without having to specify a date.  For example,
  168.         if it is now 11:00pm and you type
  169.  
  170.             wait until 03:00 command
  171.  
  172.         then WAIT assumes you mean 3am tomorrow, rather than 3am today
  173.         (which has already passed).
  174.  
  175.         You can also use the keyword TOMORROW to indicate that you mean
  176.         tomorrow's date rather than today.  This is useful if you want
  177.         to start an overnight process before 10pm:
  178.  
  179.             wait until tomorrow 03:00 command
  180.  
  181.  
  182.         Waiting for a process or session to end
  183.         ---------------------------------------
  184.         These three formats allow you to wait for a specific process or
  185.         session to end:
  186.  
  187.             WAIT [/D] FOR PID # [command {arguments}]
  188.             WAIT [/D] FOR name [command {arguments}]
  189.             WAIT [/D] FOR SESSION # [command {arguments}]
  190.  
  191.         The keyword FOR is required; this is what signals WAIT that you
  192.         want to wait for a process or session (rather than a time).
  193.  
  194.         A process can be specified either by a process ID number or by
  195.         name.  Process ID numbers can be in decimal (default) or in
  196.         hexadecimal (preceded by 'x').  Use the keyword PID to indicate
  197.         that you're specifying a process ID number.  For example:
  198.  
  199.             wait for pid 90 "dir > prn"
  200.                 Wait for process 90 to terminate, then run DIR
  201.  
  202.  
  203.             wait /d for pid 0x5A "dir"
  204.                 Wait for process x5A (decimal 90)
  205.  
  206.         To specify a name, just omit the PID keyword and use the name:
  207.  
  208.             wait /d for RXT2 "prexx msgscan"
  209.                 Wait for "RXT2" to end, then run "prexx msgscan".
  210.  
  211.         To specify a session, use the session number in either hex or
  212.         decimal:
  213.  
  214.             wait for session 12 "prexx msgscan"
  215.             wait for session x0c "prexx msgscan"
  216.  
  217.         "Waiting for a session" means waiting for all processes with the
  218.         specified session ID to terminate.
  219.  
  220.         Notes:
  221.  
  222.             1. You can see a list of process names and numbers with the
  223.             OS/2 programs PS or PSTAT, with the supplied program PLIST,
  224.             or with the public domain programs STATUS or RUNNING.
  225.             PSTAT, STATUS, and RUNNING all display more information than
  226.             PLIST.  However, PLIST's display shows only data that is of
  227.             interest to WAIT; hence, it is more concise.  PLIST shows
  228.             for each process:  the process ID (PID), the parent's
  229.             process ID (PPID), the session number, and the name.  All
  230.             numbers are hexadecimal.
  231.  
  232.             2. This feature uses an undocumented OS/2 API call; it has
  233.             been tested with OS/2 SE 1.1 and 1.2, but may not work with
  234.             other or future versions.
  235.  
  236.             3. WAIT only checks the status of the specified process
  237.             every five seconds or so; thus, up to about five seconds may
  238.             elapse between the termination of a process/session and
  239.             WAIT's noticing that this has occurred.
  240.  
  241.             4. WAIT exits with an error if you specify a process by name
  242.             and more than one such process exists (PIDs are unique, but
  243.             names may not be).
  244.  
  245.         (Thanks hereby expressed to those who investigated and
  246.         published the information about this useful API function!
  247.         Unlike WAIT, PLIST is uncopyrighted and is donated to the public
  248.         domain for use without restrictions.)
  249.  
  250.  
  251.         Cancelling the wait
  252.         -------------------
  253.         When WAIT goes to sleep, it displays the elapsed time before it
  254.         is going to wake up, then blocks its thread for the period
  255.         specified.  (While it is sleeping, you can of course switch to
  256.         other sessions.)  You can cancel the wait at any time by
  257.         pressing either Ctrl+C or Ctrl+Break.
  258.  
  259.         If interrupted, WAIT wakes up and displays an option list; you
  260.         can select one of these three actions:
  261.  
  262.             -- go back to sleep
  263.             -- terminate immediately
  264.             -- execute the command (if specified) immediately
  265.  
  266.  
  267.         Exit codes
  268.         ----------
  269.         If WAIT is unsuccesful, it returns one of these exit codes
  270.         (errorlevels):
  271.  
  272.             30000 - problem getting process information
  273.             30001 - problem setting up ^C/^Break signal handler
  274.             30002 - more than one instance of named process found
  275.             30003 - unable to execute specified command
  276.             30004 - cancelled by user (Ctrl+C, Ctrl+Break)
  277.             30005 - invalid date or time
  278.             30006 - improper syntax
  279.  
  280.         If WAIT is successful, it returns the exit code of the child
  281.         process.  With /D, this will be the exit code of the specific
  282.         program that was executed; without /D, it will be the exit code
  283.         returned by the command shell.
  284.  
  285.  
  286.         Version number
  287.         --------------
  288.         To display WAIT's version number and logo, use:
  289.  
  290.             wait /V
  291.  
  292.         Please be sure to know your version number before contacting
  293.         Cove Software about WAIT.  All other arguments are ignored if /V
  294.         is specified.
  295.  
  296.  
  297.         Getting help
  298.         ------------
  299.         To display a usage summary for WAIT, use either of:
  300.  
  301.             wait /help
  302.             wait /?
  303.  
  304.         All other arguments are ignored if these options are used.
  305.  
  306.  
  307.         Version history
  308.         ---------------
  309.         1.10 02/06/91 (a quick update)
  310.             Added wait for process/session
  311.             Added TOMORROW keyword
  312.             Corrected /N option to /D (as documented)
  313.             Simplified quotation rules
  314.             Changed error exit codes to reduce chances of collision
  315.               with exit codes from commands
  316.             Eliminated diagnostics that slipped into the release
  317.             Added PLIST program
  318.  
  319.         1.00 02/05/91
  320.             Initial release
  321.  
  322.  
  323.         Copyright/License/Warranty
  324.         --------------------------
  325.         This document and the program file WAIT.EXE ("the software") are
  326.         copyrighted by the author.  If you are an individual, you are
  327.         licensed to:  use the software; make as many copies of the
  328.         program and documentation as you wish; give such copies to
  329.         anyone; and distribute the software and documentation via
  330.         electronic means.  There is no charge for any of the above.
  331.  
  332.         However, you are specifically prohibited from charging, or
  333.         requesting donations, for any such copies, however made; and
  334.         from distributing the software and/or documentation with
  335.         commercial products without prior permission.  An exception is
  336.         granted to not-for-profit user's groups, which are authorized to
  337.         charge a small fee (not to exceed $7) for materials, handling,
  338.         postage, and general overhead.  NO FOR-PROFIT ORGANIZATION IS
  339.         AUTHORIZED TO CHARGE ANY AMOUNT FOR DISTRIBUTION OF COPIES OF
  340.         THE SOFTWARE OR DOCUMENTATION, OR TO INCLUDE COPIES OF THE
  341.         SOFTWARE OR DOCUMENTATION WITH SALES OF THEIR OWN PRODUCTS.
  342.  
  343.         THIS INCLUDES A SPECIFIC PROHIBITION AGAINST FOR-PROFIT
  344.         ORGANIZATIONS DISTRIBUTING THE SOFTWARE, EITHER ALONE OR WITH
  345.         OTHER SOFTWARE, AND CHARGING A "HANDLING" OR "MATERIALS" FEE OR
  346.         ANY OTHER SUCH FEE FOR THE DISTRIBUTION.  NO FOR-PROFIT
  347.         ORGANIZATION IS AUTHORIZED TO INCLUDE THE SOFTWARE ON ANY MEDIA
  348.         FOR WHICH MONEY IS CHARGED.  PERIOD.
  349.  
  350.         Businesses, institutions, and governmental entities are
  351.         prohibited from installing or using the software on their
  352.         systems without specific permission from The Cove Software
  353.         Group.
  354.  
  355.         No copy of the software may be distributed or given away without
  356.         this document; and this notice must not be removed.
  357.  
  358.         There is no warranty of any kind, and the copyright owner is not
  359.         liable for damages of any kind.  By using this free software,
  360.         you agree to this.
  361.  
  362.         The software and documentation are:
  363.  
  364.                              Copyright (C) 1991 by
  365.                             The Cove Software Group
  366.                              Christopher J. Dunford
  367.                                  P.O. Box 1072
  368.                             Columbia, Maryland 21044
  369.  
  370.                                 (301) 992-9371
  371.                         CompuServe 76703,2002 [IBMNET]
  372.  
  373.                 Software and documentation author: Chris Dunford
  374.