ONCE 1.2g - Execute programs once in 'n' days on workstations
-------------------------------------------------------------
(C) Pratap Pereira, 1994


Introduction:
------------

ONCE can be used to execute a program on a given workstation once every
'n' days. The default being once a day. It is written to be executed from the
login script. There are many applications for such a program, typically at my
installations we run the virus scanner F-PROT on the workstations every day. I
run MSD to log the system configuration of the workstations every 7 days. Other
applications are only limited by your imagination.

ONCE keeps track of which workstations have executed the program by recording
the date last executed and the unique ethernet number in the CONTROL file that
is specified. The nature of execution from the login script makes it sensible
to have the CONTROL file on the File Server. It is my personal preference to be
able to see the control file at one specific location rather than on a local
drive. This is recommended. In the same way the behaviour of ONCE is
different from cron or other time based schedulers. Since ONCE is executed from
the login script it is impossible to execute the program every 'n' days if the
machine is not used on a daily basis. Thus ONCE will execute the program if
more than 'n' days have passed since the last time it was done.

For a program that is executed from the login script for it is useful to log
the output to a file. This logging does typically pose a problem as to what
the log file should be named. The hack that is commonly used is to use the
last 8 characters of the ethernet address and hope that it is unique enough
for the installation :-). ONCE has implemented a better approach of converting
the 48 bit ethernet address to a base 21 number which allows the range of the
48 bit ethernet address to be expressed in 11 characters. This allows a unique
filename to be generated in the 8.3 characters DOS allows. This is the unique
filename that is referred to in this document.

All the dates are obtained by looking at the server date. The program works
only with the novell drivers installed (surprise !!). The program being
executed is actually spawned to overlay ONCE, thus if the program fails to
execute it returns an error but ONCE would have updated the data file. This
overlay approach was chosen so that all memory is available to the executing
program. If updating the data file when the operation failed poses a problem
I might be convinced to change this behaviour. I have not found the need to
do so.



Options:
-------

ONCE is executed with a command line that is as follows

        ONCE [-d(days)] <filename> <program + arguments>

-d(days)   : Specify every (days) the program must be run. Default (1).
Example of this option is -d7 for 7 days. Note that there is no space between
the option and the number.

<filename> : Is the CONTROL File to be used for the program.
<prgm+arg> : Actual Program with arguments to be executed.

ONCE looks for the days setting (-d) as the first option. The actual program to
be executed is specified with its arguments after the control filename. The
examples will make the operation clear. Typically this is the way ONCE will be
used in the login script. Specify the full path to the file with a mapped drive
letter in the login script. This is the way I use it <g>. The control file will
be created with a .ONC extension if an extension is not specified.

The unique filename can be used in the arguments to the program being executed
by ONCE by embedding a ~f anywhere. This escape code is replaced (blindly) by
the unique filename.

The program can also be used interactively with the following options.

        -h      : Display the Help Screen
        -c      : Convert Ethernet Number <-> Unique Filename.
        -u      : Enhanced UserList with Unique Filename Listed.
        -l      : List the CONTROL File contents

The -c option allows interconversion between the ethernet number and the unique
filename.

The -u option is an enhanced version of the userlist that shows the currently
logged on users along with the ethernet address and the unique filename. These
options are useful to find out which machine a unique filename belongs to. In
my installation I have the unique filename recorded with my BOOTP table and
assists me in finding out the machine in question. However with it inevitably
being outdated :-) the -u option is quite helpful.

The -l option displays the contents of a CONTROL file that is specified. The
output shows the Ethernet Number, Date Last Done and the unique filename
associated with the Ethernet Number.

Examples:
--------

1)

Command:
        ONCE -d7 test.onc msd /p ~f
Output:

ONCE 1.2f - Execute programs once in 'n' days on workstations
Days: 7
Using datafile: test.onc
Program: msd /p 1GF9E3KI.    
Last Done: 08/24/94 , Not yet 7 days.

Explanation:
        run msd every 7 days saving the report to unique filename. Here ONCE
        does not execute the program since the number of days have not passed.
        Otherwise the last done date will be reported and the program run.

2)

Command:
        ONCE -u
Output:

ONCE 1.2f - Execute programs once in 'n' days on workstations
ConnNum	UserName       	LoginTime	EthAddr               	Filename
  1	LEEEW          	07:58:06 08/25	00:00:C0:79:8D:5C	'1GDE32FC.   '
  2	DOLLYMH        	06:14:39 08/25	00:00:C0:7A:8D:5C	'1GDEA477.   '
  3	ANNER          	07:00:59 08/25	00:00:C0:85:8D:5C	'1GDI410F.   '
  4	VIJAYMB        	07:46:16 08/24	00:00:C0:29:75:4D	'1GC83737.   '
  5	VICKILL        	07:02:43 08/25	00:00:C0:83:8D:5C	'1GDHAIH4.   '
  6	TANYART        	07:03:38 08/25	00:00:C0:89:8D:5C	'1GDJB79G.   '
  7	TIMAB          	08:33:54 08/25	00:00:C0:26:1E:43	'1GC70EH0.   '
  8	CONSTLG        	07:10:53 08/25	00:00:C0:ED:24:47	'1GFB224K.   '
  9	QSERVER        	07:10:32 08/25	00:00:C0:F3:24:47	'1GFD2BIB.   '
 10	SALLYAE        	07:18:32 08/25	00:00:C0:8A:6A:4B	'1GDJH9F1.   '
 11	ANGIELL        	07:20:00 08/25	00:00:C0:67:37:52	'1GD7K7I0.   '
 12	EASE2          	12:08:59 08/23	00:00:C0:FC:19:81	'1GFG2K21.   '
 13	EASE1          	12:09:05 08/23	00:00:C0:D0:17:81	'1GF16B43.   '
 14	QSERVER        	07:20:32 08/25	00:00:C0:5E:0C:45	'1GD4IA87.   '
 15	JETDIRECT_4SI  	07:21:07 08/25	08:00:09:47:16:A5	'B1BHI94B.9E '
 16	LISAMH         	08:06:19 08/25	00:00:C0:A1:6A:4B	'1GE6C4EC.   '

License, Warranty:
-----------------

        ONCE has been tested and been used for about 4 months as of (8/94)
        however :

        ONCE is provided "AS IS" without warranty of any kind,
        either expressed or implied, including, but not limited to the
        implied warranties of merchantability and fitness for any purpose.
        The entire risk as to the quality and performance of this program
        is with the user and should the program prove defective, the user
        and not the author will assume all responsibility.
        The author does not warrant that this program will function as desired
        or that the operation of the program will be error free.

        This software is copyrighted and SHAREWARE and on registration a
        limited license is granted to the user and entitles the user to 2 free
        updates. The user is free to try the program for a period not to exceed
        30 days. Please register and support development of similar products.
        The program is fully functional and does not 'nag' you.
        If you do not register it will be only in your conscience or whatever.

        Comments, suggestions, gripes, or error reports are welcome.

        You are free to upload this program in its original distribution to
        ftp sites, bulletin boards or other distribution media. You are not
        allowed to distribute modified forms.

Registration:
------------

        The retail price is US $19 per server.

        Payment Procedure:

        Money Order and Check are the only payment methods accepted.
        Outside the US please send only US Postal Money Orders.

        Mail to:
                Pratap Pereira
                1560 Hunter Ave
                Columbus, OH 43201
                USA

        email:
                pereira.1@osu.edu

