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


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)] [-s(YY/MM/DD)] [-v] <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.
-s(YY/MM/DD)  : Specify the starting date after which the program will be run.
-v            : By default the program now does not print any status messages
                to make its use in login scripts unobtrusive. Using -v for
                verbose turns on status messages. Error messages however are
                always printed.

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

ONCE looks for the options in the beginning of the command line. 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.
Interactive mode is always verbose !.

        -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.


Error Level Returned:
--------------------

The program returns an error level of 255 for all errors in execution of
ONCE itself. If ONCE executed without errors the error level returned is
the error level returned by the executed program or 0 if the program was not
executed.

An error in execution of the specified program will return a 255. This feature
is to allow greater control in login scripts or batch files. If the program to
be executed by ONCE uses 255 as a return code this will not be quite as useful.
Most programs however seem to use the error levels starting at the lowest
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.   '

3)

Command:
        ONCE -s95/01/01 -d7 remind.onc command.com /c remind.bat

Explanation:
        Run the batch file remind.bat once every 7 days after January 1, 1995.

4)

Just a reminder that the login script conditional commands can be used to
execute a once command on a specific DAY_OF_WEEK, for MEMBER of a specific
group etc.

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

