OS/2 Shareware BBS: 11 Util/11-Util.zip/que09.zip/que.doc

Text File | 1994-04-06 | 15KB | 361 lines

                            QUE version 0.9
               Job Scheduler & Queue System for OS/2 2.x

        Copyright (c)1994 by Lai Zit Seng. All Rights Reserved.


QUE is a job scheduler and queue system for OS/2 2.x. QUE lets you
schedule jobs for sequential processing in a queue. You can schedule
jobs to be processed repeatedly. QUE has an easy to use command line
interface and provides flexible scheduling options.

QUE lets you run jobs (programs, batch files, etc) like the OS/2 START
command. However QUE lets you delay processing until a later time and
repeatedly process the job at a given interval. Jobs are queued
sequentially (by default); If two or more jobs are scheduled to be
processed together, QUE will only process them one after the other.
OS/2's multitasking is great, but starting too many jobs simultaneously
may slow down your system unnecessarily.

I use QUE on my BBS to process mail, generate reports and filelists,
make out-going mail calls, etc.


COPYRIGHT, DISTRIBUTION AND DISCLAIMER NOTICE
─────────────────────────────────────────────

QUE is Copyright (c)1994 by Lai Zit Seng. All rights are reserved.

This software may be used free of charge. Non-profit distribution is
permitted provided the QUE distribution archive/package remains intact.
Modification and/or tampering with QUE or its associated files is
expressly prohibited.

QUE is provided as is and comes with no warranty of any kind, express or
implied, including but not limited to that of quality, performance,
merchantability and fitness for any particular purpose. In no event will
the author be liable for any damages resulting from the direct or
indirect use, or the inability to use, this software. The user bears all
risk with regards to the use or inability to use this software.


CONTENTS OF THIS PACKAGE
────────────────────────

The distribution archive you receive for this software contains the
following files:

    QUE.EXE         The actual executable program
    QUE.DOC         This documentation
    FILE_ID.DIZ     Blurb for BBS file listing
    STARTQUE.CMD    Starts the queue server in a minimized session
    SAVEQUE.CMD     Saves the state of the queue for later retrieval


USING QUE - STARTING THE SERVER
───────────────────────────────

There are two parts to QUE - the server mode that monitors your job
schedules and processes them, and the client mode that sends jobs and
acts as a general interface to the server.

You must start the server mode before using any other QUE commands. To
do so, type:

    QUE /SERVER

You can optionally specify a queue number for this particular server
mode to operate on. This lets you run multiple queues on your system. To
do so, include the /QUEUE parameter:

    QUE /SERVER /QUEUE n

where n is the queue number. To end the queue server, run another copy
of it with:

    QUE /STOP


USING QUE - SUBMITTING JOBS
───────────────────────────

There are many ways to queue jobs for execution. The general formats
are:

    QUE <command>                       <=  starts job now
    QUE AT hh:mm <command>              <=  starts job at the given time
                                            today (hh:mm)
    QUE ON dd-mm-yy <command>           <=  starts job on the given day
                                            (dd-mm-yy) at the current
                                            time
    QUE AT hh:mm ON dd-mm-yy <command>  <=  starts job on the given day
                                            and at the given time
    QUE IN n MINUTES <command>          <=  starts job in n minutes
    QUE IN n HOURS <command>            <=  starts job in n hours
    QUE NEXTHOUR <command>              <=  starts job in 1 hour
    QUE NEXTDAY <command>               <=  starts job in 1 day's time
    QUE NEXTWEEK <command>              <=  starts job in 7 days' time

In all examples above, <command> represents the actual command line
including parameters needed to start your job. QUE saves your current
directory when you submit your job; The server chances to this directory
before processing your job.

The hh:mm time value is in 24 hour format (00:00 to 23:59).

QUE's keywords can be mixed in any other, as long as <command> remains
right at the end. For example, you can type:

    QUE ON dd-mm-yy AT hh:mm <command>
    QUE NEXTHOUR NEXTDAY IN 6 MINUTES <command>

The first is self explanatory. The second example simply means to start
the job one day and 1 hour 6 minutes from now.

The year component of the date value can be in 4 digit format. This
means that the following commands are identical:

    QUE ON 4-4-94 <command>
    QUE ON 4-4-1994 <command>

To schedule repeating jobs, use the EVERY... keywords:

    QUE EVERYQUATER                     <= job repeats every quater-hour
    QUE EVERYHALF                       <= job repeats every half-hour
    QUE EVERYHOUR                       <= job repeats every hour
    QUE EVERYDAY                        <= job repeats every day
    QUE EVERYWEEK                       <= job repeats every week
    QUE EVERYMONTH                      <= job repeats every month
    QUE EVERYYEAR                       <= job repeats every year
    QUE EVERY n MINUTES                 <= job repeats every n minutes
    QUE EVERY n HOURS                   <= job repeats every n hours

These frequency specifying keywords can be mixed with start-time
specifying keywords described earlier to give, as an example:

    QUE AT hh:mm ON dd-mm-yy EVERY n HOURS <command>

The following lists more of QUE options:

    /DIR <directory>                    <=  change to the specified
                                            directory before starting
                                            job
    /INSTANCES n                        <=  maximum of n instances of
                                            this command (including the
                                            one now being submitted)
    /QUEUE n                            <=  use queue n (default is 1)
    /DETACH                             <=  job will be detached to a
                                            background process

The /INSTANCES keyword let you specify the maximum number of the job you
are submitting that is allowed in the queue. This includes the one that
you are going to submit. Jobs are considered identical so long as their
<command> strings are identical (whitespace is ignored). If there are
already 2 instances of TEST.CMD in the queue, the following will fail:

    QUE /INSTANCES 2 TEST.CMD

But the following succeeds:

    QUE /INSTANCES 3 TEST.CMD

The /DETACH keyword specifies that the job will be "spawned off" and
executed in the background. Detached jobs cannot be viewed on the screen
and cannot accept keyboard/mouse input. If several jobs are scheduled
for the same time, detached jobs are always processed first. If you want
to run a job "in the background" (not occupying QUE's time) but want to
see its screen output and provide keyboard/mouse input, use:

    QUE START <command>

START is an OS/2 command that starts a new session. QUE merely passes
"START <command>" to the OS/2 command processor.


USING QUE - MANAGEMENT TOOLS
────────────────────────────

The following keywords are provided to manage your queue:

    QUE /STOP                           <=  Stops the queue server (the
                                            current job is always
                                            completed first before
                                            shutting down)
    QUE /LIST                           <=  Tabular list of all jobs
                                            scheduled
    QUE /VERBOSE n                      <=  Detailed information of the
                                            schedule for job ID n
    QUE /KILL n                         <=  Remove the schedule for job
                                            ID n
    QUE /SAVE                           <=  output a command file that
                                            can restore the queue to the
                                            current state

/STOP ends the queue server. The current job is always completed first
before the serve mode shuts down.

/LIST generates output of the form:

    1004 05-04-1994 22:55 W    test4
    1001 05-04-1994 23:00 W    test1
    1007 06-04-1994 02:36 W hr test5
    1002 06-04-1994 22:35 W    test2
    1003 12-04-1994 22:35 W    test3
    1008 12-04-1994 22:45 W ?m test6
    ^    ^          ^       ^  ^
    |    |          |       |  +------- command
    |    |          |       +---------- frequency for repeated jobs: qt,
    |    |          |                   hf, hr, dy, wk, mn, yr, ?m, ?h
    |    |          |                   for quarter-hourly, half-hourly,
    |    |          |                   hourly, daily, weekly, monthly,
    |    |          |                   yearly, in "some" interval of
    |    |          |                   minutes and in "some" interval
    |    |          |                   of hours
    |    |          +------------------ the start time of this job
    |    +----------------------------- the start date of this job
    +---------------------------------- Job ID

/SAVE generates an output that makes up all the QUE commands required to
restore your queue to its current state. This is a convenient meants to
restore your queue after a system reboot. The output for the above
schedules look like:

    que at 22:55 on 05-04-1994 /dir F:\work\queue test4
    que at 23:00 on 05-04-1994 /dir F:\work\queue test
    que at 02:36 on 06-04-1994 everyhour /dir F:\work\queue test5
    que at 22:35 on 06-04-1994 /dir F:\work\queue test2
    que at 22:35 on 12-04-1994 /dir F:\work\queue test3
    que at 22:45 on 12-04-1994 every 50 minutes /dir F:\work\queue test6

If you run "QUE /SAVE > RESTORE.CMD", then after your system reboots,
running "RESTORE.CMD" restores the queue to what it previously was.

The /LIST and /VERBOSE commands sorts according to the order that the
queue will be processed. This means that the earliest job is listed
first. For all jobs scheduled for the same time, detached jobs are listed
first. The last sort criteria is by job ID - this means that if two
job (both detached or both not detached) are scheduled at the same time,
the job submitted earlier is listed first (job IDs are assigned in
ascending order).

The /VERBOSE gives detailed information about the specified job ID. With
the above example of jobs, running "QUE /VERBOSE 1008" produces:

    Job ID: 1008  Frequency: Every 50 minutes  Executed: 0 times
    Date: 12-04-1994  Time: 22:45  Run Mode: Wait
    Directory: F:\work\queue
    Command:   test6

The "Processed: n times" field is useful only for repeating jobs. This
tells you how many times this job has already been processed. The Date
and Time fields of repeating jobs reflect the date/time of the next run,
not that of the original run.


TIPS FOR USING QUE
──────────────────

The STARTQUE.CMD file provided starts QUE in a windowed, minimized
session directly without going through the command processor. When the
QUE server is stopped, this window is closed automatically. STARTQUE.CMD
contains this line:

    start /n /win /min que /server

You can include this line in STARTUP.CMD in the root directory of your
OS/2 boot drive to automatically start the QUE server at boot time.

If you like to have QUE save its current schedule to a file
automatically at some fixed interval, schedule the following job:

    que every 20 minutes saveque.cmd

SAVEQUE.CMD is included in this distribution archive. It contains the
following line:

    que /save > queagain.cmd

When you reboot your system, run "queagain.cmd" to restore your schedule
to what it was when your system when down. This command is very useful
in restoring your queue in the event of a system crash or other
unexpected shutdown. In fact, you might want to include this "autosave
feature" in STARTUP.CMD after starting the QUE server.


OTHER NOTES
───────────

If you want to run a command that is the same as one of QUE's keywords,
prefix your command with a minus sign. For example, if you want to run a
command called AT, the following results in an error:

    QUE IN 5 MINUTES AT

You should use the following instead:

    QUE IN 5 MINUTES -AT

If the command you want to run actually starts with a minus sign, you
also prefix it with another minus sign. To run a command called -HI,
type:

    QUE IN 5 MINUTES --HI

Typing "QUE" alone gives you a one page help. Some options can be
abbreviated by dropping the lowercase component. For example, the one
page help lists "/Server", which can be abbreviated to "/S".

A job scheduled to run at 17:50 does not necessary start exactly at 17:50.
This may be due to other jobs (non-detached ones) also scheduled to run
at the same time that started first. This can also happen when jobs
(non-detached ones) that started before 17:50 have not completed at
17:50. You need to take this into consideration when you want a
particular job to start exactly at the scheduled time. (If necessary,
you may want to start a 2nd queue.)


KEYWORD SYNONYMS
────────────────

The following lists QUE keywords in the right-hand column that are
identical to that in the left-hand column. The keywords in the left-hand
column are used in this documentation. Most of the synonym keywords are
merely abbreviations accepted by QUE.

    In this text:       Identical to:
    -------------------------------------------------------------
    NEXTDAY             TOMORROW
    HOURS               HR HRS HOUR
    MINUTES             MIN MINS MINUTE
    /SERVER             /S
    /DETACH             /D
    /INSTANCES          /I /INSTANCE
    /LIST               /L
    /VERBOSE            /V
    /QUEUE              /Q


CONTACTING THE AUTHOR
─────────────────────

If you like to contact me, here's how:

    FidoNet:    Lai Zit Seng @ 6:600/200
    Internet:   [e-mail]
                [e-mail]
    BBS:        Open Connection
                65-4811345, v.32ter/v.42bis
    Snailmail:  Lai Zit Seng
                149 Tamarind Road
                Singapore 2880
                Republic of Singapore

If you have found QUE useful, I'd appreciate a note! Enjoy ;-)


Lai Zit Seng

<end>